# 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 a version field; future work will embed cryptographic attestations

- 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 -> IR parser (minimal)
    - cli.py: CLI entry point
  - tests/
    - test_core.py: basic unit test for DSL parsing
  - test.sh: test runner that executes unit tests and builds the package

- Testing philosophy
  - One basic test ensures the DSL is parsed into a structured IR.
  - Tests should be deterministic and fast, enabling CI checks early.

- 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.