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

EquiCompiler

EquiCompiler translates a compact portfolio DSL into a canonical EquiIR graph with deterministic attestations, structured constraint verification, registry-backed contracts, delta-sync metadata, and a reference Python backtest path.

What It Does

• Parses portfolio strategy declarations into a normalized IR.
• Captures assets, objective clauses, constraints, execution policy, risk budgets, and regulatory metadata.
• Normalizes constraints into a structured verification surface with deterministic proof digests.
• Builds a deterministic execution plan with backend targets for Python, C++, and WebAssembly.
• Emits digest-based attestations and a Graph-of-Contracts skeleton for auditability.
• Provides a reference Python backtester for offline evaluation and replay.
• Computes deterministic delta-sync summaries between IR revisions.

DSL

Example:

version: 0.3
assets: AAPL@0.6, MSFT@0.4
objectives: maximize_return; minimize_risk
constraints: max_drawdown=0.15, var=0.95, cvar=0.9
risk_budget: max_var=0.1, max_exposure=0.8
execution_policy: offline, delta_sync, rebalance=1d
regulatory: venue=us, suitability=true

Supported sections:

• version
• assets
• objectives
• constraints
• execution_policy
• risk_budget
• market_microstructure
• regulatory

IR Surface

parse_dsl_to_ir() returns a dictionary with:

• canonical assets and optional weights
• objectives and constraints
• execution policy and risk budget
• compiler metadata and lineage digest
• structured constraint specifications and verification status
• execution plan with registry contracts
• attestations and GoC skeleton
• delta-sync metadata

Reference Backtest

The Python backend accepts either provided price series or a deterministic synthesized scenario and returns:

• a portfolio curve
• total return
• volatility
• max drawdown
• VaR / CVaR estimates
• objective satisfaction

CLI

python -m equicompiler_algebraic_portfolio_dsl_to_.cli path/to/strategy.dsl
python -m equicompiler_algebraic_portfolio_dsl_to_.cli path/to/strategy.dsl --backtest

Programmatic Use

from equicompiler_algebraic_portfolio_dsl_to_.core import parse_dsl_to_ir
from equicompiler_algebraic_portfolio_dsl_to_.backends.python_backtester import run_backtest

ir = parse_dsl_to_ir(dsl_text)
result = run_backtest(ir)

Packaging

• Python package name: equicompiler_algebraic_portfolio_dsl_to
• Source package: equicompiler_algebraic_portfolio_dsl_to_
• Build metadata: pyproject.toml
• README used as the long-form package description

Tests

Run the local verification flow with:

bash test.sh

That script installs the package in editable mode, runs the unit tests, and builds a source/wheel distribution.

Architecture Notes

• core.py: DSL parsing, IR normalization, lineage, attestations, and plan synthesis
• verification.py: structured constraint parsing and deterministic verification reports
• delta_sync.py: deterministic IR diffing
• registry.py: in-process GoC contract registry
• goc_registry.py: GoC skeleton builder
• backends/python_backtester.py: deterministic reference backtester
• adapters/: starter adapter interfaces for feeds and brokers

Status

This repository now has a coherent compiler pipeline, but it is still a reference implementation rather than a full market execution platform.