# AGENTS.md

Architecture overview for the EquiCompiler MVP

- Purpose
  A compact, production-ready starting point for an algebraic, verifiable portfolio DSL compiler targeting low-latency backends. This MVP focuses on a minimal, well-tested core that can be extended by additional agents in this SWARM.

- Tech Stack (initial)
  - Language: Python (back-end DSL parsing, IR generation, and reference backtester)
  - Packaging: setuptools via pyproject.toml (Python package: equicompiler_algebraic_portfolio_dsl_to_)
  - Tests: unittest (built into Python) with a small pytest-friendly path for future expansion
  - CLI: python -m equicompiler_algebraic_portfolio_dsl_to_.cli
  - Documentation: README.md and AGENTS.md in root

- Core Concepts (MVP subset)
  - LocalProblem: a portfolio-level optimization task expressed in the DSL
  - SharedVariables: signals and inter-node communication primitives (simplified in MVP)
  - PlanDelta: incremental plan changes with versioning (simplified in MVP)
  - Auditability: IR includes versioning, deterministic attestations, lineage digests, and a Graph-of-Contracts skeleton

- Repository structure (initial)
  - AGENTS.md: this document
  - README.md: project overview, quickstart
  - pyproject.toml: packaging metadata
  - equicompiler_algebraic_portfolio_dsl_to_/
    - __init__.py
    - core.py: DSL -> EquiIR compiler, lineage, attestations, and execution-plan synthesis
    - cli.py: CLI entry point with optional reference backtest
    - delta_sync.py: deterministic IR diffing and plan delta summaries
    - registry.py: in-process Graph-of-Contracts contract registry
    - goc_registry.py: GoC skeleton generation helpers
    - backends/python_backtester.py: deterministic Python reference backtester
    - adapters/: starter feed and broker adapters
  - tests/
    - test_core.py: DSL parsing and core IR assertions
    - test_execution_policy.py: execution policy parsing
    - test_goC.py: GoC structure assertions
    - test_version_override.py: DSL version override coverage
    - test_compiler_pipeline.py: richer compiler, backtest, and delta-sync coverage
  - test.sh: test runner that executes unit tests and builds the package

- Testing philosophy
  - Tests should be deterministic and fast, enabling CI checks early.
  - Cover parser normalization, deterministic backtesting, and delta-sync behavior.

- Roadmap (high level)
  - Expand the DSL grammar and IR representation
  - Add formal verification hooks (placeholder)
  - Implement delta-sync protocol and simple offline backtester
  - Introduce more adapters and a Graph-of-Contracts registry surface

Notes
- This document is intentionally concise to enable rapid iteration. It can be expanded as the project evolves.

Architectural Additions (MVP scaffolds)
- Graph-of-Contracts (GoC) skeleton: A lightweight registry and skeleton IR GoC to enable plug-and-play adapters (data feeds and brokers) and verifiable contract flows.
- Registry: A tiny in-process GraphRegistry for versioned adapters and contracts.
- Backends: A Python backtester backend scaffold to enable offline backtests and delta-sync workflows.
- Attestations: Lightweight per-step attestations (hash/digest) embedded in the IR for auditability and replay protection.
- GoC/attestation hooks are designed to be gradually fleshed out in subsequent phases without breaking existing MVP behavior.