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

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
  • verification.py: structured constraint parsing and deterministic verification reports
  • 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.
• Verification: Deterministic constraint parsing and proof-digest generation for auditable plan validation.
• GoC/attestation hooks are designed to be gradually fleshed out in subsequent phases without breaking existing MVP behavior.