idea115-taxalpha-studio-declarative/AGENTS.md

Architecture and contributor guidance for idea115-taxalpha-studio-declarative

Overview

• Phase-0 skeleton for TaxAlpha Studio: canonical IR, a tiny DSL parser, a deterministic greedy optimizer (warm-start), and two simple adapters (custodian mock and CSV reader).

Tech stack

• Python 3.8+
• Packaging: setuptools (pyproject.toml)
• Testing: pytest

Repository layout

• idea115_taxalpha_studio_declarative/: package source
  • ir.py: canonical dataclasses (TaxLot, Account, HarvestAction, PlanDelta, AuditLog)
  • dsl.py: very small line-oriented DSL parser
  • solver.py: deterministic greedy warm-start optimizer (Phase-0)
  • adapters/: simple adapters (custodian mock, CSV reader)
• tests/: pytest tests
• pyproject.toml: package metadata and build-system
• README.md: project description
• AGENTS.md: this file

Developer rules

• Make minimal, well-scoped changes. Prefer small, correct edits.
• Use apply_patch for modifications.
• Add tests for new behavior and ensure pytest passes.
• test.sh must run pytest and python3 -m build successfully.

How to run tests

1. Install requirements if needed (Phase-0 uses stdlib only)
2. Run: bash test.sh