# AGENTS.md

## Project

`statement-to-tikz` converts olympiad-style **plane geometry statements** into **constraint-solved TikZ diagrams**.

Pipeline:

```text
natural language → GeometryIR (JSON) → SciPy least_squares → TikZ → pdflatex + residual report
                              ↘ schematic layout if underconstrained / unsat
```

## For coding agents

- Prefer editing IR / solver / emitter over asking the LLM to invent freehand TikZ coordinates.
- Correctness = numeric residuals on IR constraints (`mode=exact` when max residual ≤ `--tol`, default `1e-4`).
- Offline formalizer patterns live in `src/statement_to_tikz/formalize.py`; general statements need `OPENAI_API_KEY`.
- Do not commit `.venv/`, `out/`, or API keys.
- Run `pytest -q` after solver/IR changes (no network required).

## Key paths

| Path | Role |
|------|------|
| `src/statement_to_tikz/ir.py` | Pydantic GeometryIR + constraints |
| `src/statement_to_tikz/solve.py` | Residual solver + gauge |
| `src/statement_to_tikz/schematic.py` | Fallback layout |
| `src/statement_to_tikz/emit_tikz.py` | Deterministic TikZ |
| `src/statement_to_tikz/formalize.py` | LLM / offline → IR |
| `src/statement_to_tikz/pipeline.py` | Orchestration |
| `src/statement_to_tikz/cli.py` | `stt` CLI |
| `tests/fixtures/*.json` | Golden IR + expected mode |

## CLI

```bash
stt "In triangle ABC, AB = AC, and D is the midpoint of BC." -o out/fig
stt --ir path.ir.json --emit-only -o out/fig
```

## Constraint vocabulary (v1)

`equal_length`, `length`, `equal_angle`, `angle_measure`, `perpendicular`, `parallel`, `on_line`, `on_circle`, `midpoint`, `collinear`, `intersection`.