equicompiler-algebraic-portfolio-dsl-to-/README.md

# EquiCompiler: Algebraic Portfolio DSL to Verifiable Low-Latency Compiler (MVP)

Overview
- This repository contains a minimal, production-ready MVP for a compiler stack that translates a domain-specific language for market strategies into a portable, verifiable execution graph. The MVP focuses on a small, well-formed core to enable safe extension by additional agents in the swarm.

What you get in this MVP
- A small DSL parser that reads a concise DSL and converts it into a canonical in-memory IR (EquiIR) represented as Python dicts.
- A minimal Python package equicompiler_algebraic_portfolio_dsl_to_ with a core module and a CLI entry point.
- A tiny test suite to validate DSL parsing and IR generation.
- A test runner (test.sh) that executes tests and builds the package to verify packaging metadata.

Usage
- DSL to IR (programmatic):
  from equicompiler_algebraic_portfolio_dsl_to_.core import parse_dsl_to_ir
  dsl = "assets: AAPL, MSFT, GOOG\nobjectives: maximize_return\nconstraints: max_drawdown=0.2, var=0.95"
  ir = parse_dsl_to_ir(dsl)
  print(ir)

- CLI (Python module):
python -m equicompiler_algebraic_portfolio_dsl_to_.cli path/to/dsl_file.txt

Verifiable DSL Overview
- The EquiCompiler MVP translates a mathematically precise portfolio DSL into a portable, verifiable IR (EquiIR).
- Each transformation step embeds lightweight cryptographic attestations (digest-based) to ensure auditability and replayability without leaking sensitive data.
- A Graph-of-Contracts (GoC) skeleton is attached to the IR to enable plug-and-play adapters for data feeds and brokers, while preserving versioned contracts and compatibility.
- The system supports offline-first evaluation with deterministic delta-sync, enabling local backtests and plan replay when connectivity resumes.
- Backends are designed for cross-runtime portability: Python backtester for offline tests, C++ for live trading, and WebAssembly for browser-based evaluation.
- The MVP keeps a minimal, stable surface area while providing clear extension points for future formal verification hooks and delta-sync workflows.

Example workflow
- Parse a DSL to IR (programmatic):
  ``from equicompiler_algebraic_portfolio_dsl_to_.core import parse_dsl_to_ir``
  ``dsl = "assets: AAPL, MSFT, GOOG\nobjectives: maximize_return\nconstraints: max_drawdown=0.2, var=0.95"``
  ``ir = parse_dsl_to_ir(dsl)``
  ``print(ir)``
- Use the CLI to validate and inspect the IR produced from a file:
  ``python -m equicompiler_algebraic_portfolio_dsl_to_.cli path/to/dsl_file.txt``

Roadmap (high level)
- Phase 0: DSL to IR, start backends (Python backtester, minimal C++ live skeleton) and a minimal GoC registry.
- Phase 1: Formal verification hooks and delta-sync for offline/online reconciliation.
- Phase 2: Cross-backend interoperability tests with toy adapters.
- Phase 3: Hardware-in-the-loop (HIL) testing with partitioned portfolios.

Publishing readiness
- This repository is designed for packaging as a Python module named
  ``equicompiler_algebraic_portfolio_dsl_to`` with versioning in ``pyproject.toml``.
- The README now includes a marketing-style overview and usage examples to aid publication.

Project structure
- AGENTS.md: architecture and testing guidelines for future agents
- README.md: this file
- pyproject.toml: packaging metadata
- equicompiler_algebraic_portfolio_dsl_to_/ (package)
  - __init__.py
  - core.py: DSL -> IR parser (minimal)
  - cli.py: CLI entry point
- tests/test_core.py: small unit test for DSL parsing
- test.sh: test runner to validate test suite and packaging

Development notes
- The MVP intentionally keeps dependencies minimal to ensure fast iterations and deterministic tests.
- When adding features, try to keep changes small and focused on a single goal.
- Ensure tests cover the new functionality and avoid sensitive data in tests.

Next steps
- Extend the DSL with richer constraints (VaR, VaR-CVaR, liquidity, latency) and ExecutionPolicy primitives.
- Integrate the GoC registry and build a canonical EquiIR representation with per-message metadata for replay/verification.
- Add a lightweight delta-sync coordinator and starter adapters for data feeds and brokers.
- Expand the test suite to exercise the new backtester and Graph-of-Contracts scaffolds.
- Improve packaging and docs to support publishing to a Python package index.
- Implement a more expressive DSL and a richer IR (EquiIR) representation.
- Add more tests for edge cases and simple integration tests for the CLI.
- Expand packaging metadata and README with a longer developer and user guide.
- Add a first-pass Graph-of-Contracts registry scaffold (GoC) and a minimal adapter registry.
- Documentation: GoC overview and how to plug in new adapters.

Extensibility notes
- The repository now includes a small GoC registry module (equicompiler_algebraic_portfolio_dsl_to_/goc_registry.py) and a registry-aware GoC skeleton integrated into the IR formation flow. This provides a stable extension point for future adapters (data feeds, brokers) and verifiable contract graphs.
- You can register adapters via the GoCRegistry class and view a digest that helps ensure reproducible builds and auditability.

- Extend the DSL with richer constraints (VaR, VaR-CVaR, liquidity, latency) and ExecutionPolicy primitives.
- Integrate the GoC registry and build a canonical EquiIR representation with per-message metadata for replay/verification.
- Add a lightweight delta-sync coordinator and starter adapters for data feeds and brokers.
- Expand the test suite to exercise the new backtester and Graph-of-Contracts scaffolds.
- Improve packaging and docs to support publishing to a Python package index.
- Implement a more expressive DSL and a richer IR (EquiIR) representation.
- Add more tests for edge cases and simple integration tests for the CLI.
- Expand packaging metadata and README with a longer developer and user guide.

This README intentionally stays light; the AGENTS.md contains the deeper architectural notes for the SWARM collaborators.