Atlas: BAML → Pydantic AI

Branch issue-1288-baml-to-pydantic-ai · Story: pramaan-io/pramaan-spec#1288 · Provenance: pramaan-docs ADR-117 (accepted 2026-06-14), builds on ADR-116, amends ADR-110

🛰️ 1 · Satellite — why this exists

Atlas's "soul" — his prompts and typed I/O — lived in BAML: a bespoke .baml DSL with its own compiler, plus a baml-cli generate step that produced a large committed baml_client/ package the brain imported. That is a second language and a codegen artifact bolted onto a stack that is otherwise pure Python + Pydantic everywhere (pramaan-functions models, the agent-event contracts, the wizard input).

WHY this friction never paid for itself at our scale: every prompt or type change meant "remember to regenerate, then commit the generated diff" — a recurring drift trap in this repo's history. And BAML re-derives Pydantic models from its DSL anyway, so we were paying a translation layer to arrive at the thing we already speak.

The decision (ADR-117): own the prompts and models directly in Pydantic AI. One language end-to-end, no DSL, no codegen, no committed generated client, no regenerate-or-drift failure mode. This is an implementation swap, not a behaviour change — the contracts above and below the brain are frozen.

✈️ 2 · Airplane — the shape of the swap

BEFORE                                    AFTER (pramaan-docs ADR-117)
─────────────────────────────            ────────────────────────────────────
baml_src/atlas.baml   (DSL: types        models.py   (hand-owned Pydantic models)
  + prompts + tests)                      prompts.py  (system prompts + builders)
        │ baml-cli generate                      │  (no codegen — plain Python)
        ▼                                         ▼
baml_client/  (committed generated)       Pydantic AI Agent(output_type=…)
        │ b.stream.AtlasIntake(…)                 │ agent.run_stream(prompt, model=…)
        ▼                                         ▼
ClientRegistry (runtime model swap)       provider.py  build_model(config)
  bedrock | openrouter                      bedrock → BedrockConverseModel
                                            openrouter → OpenAIChatModel(OpenRouter)

Five BAML functions → five Pydantic AI agents. ~16 BAML classes + 1 enum → hand-owned Pydantic models. The ClientRegistry model-swap → first-class Model objects selected per-run from config. Everything the broker and the browser see is unchanged.

🔬 3 · Microscope — what moved, and WHY each piece

🔬 4 · The one subtle bit — streaming cadence parity

BAML streamed partial AtlasTurns, then yielded one final complete turn via get_final_response() — and only by then was token usage known, so the runtime stamped the real cost on the final turn. Pydantic AI's result.usage is likewise populated only after the stream is consumed. To preserve the exact cadence, stream_atlas_turn streams the partials, captures usage, then re-yields the final turn — so the runtime's per-yield cost stamp lands on the final turn.completed exactly as before.

stream = b.stream.AtlasIntake(…)
async for partial in stream:
    yield partial
yield await stream.get_final_response()

async with _intake_agent.run_stream(p, model=…) as r:
    async for partial in r.stream_output():
        final = partial; yield partial
    collector.usage = r.usage
if final is not None:
    yield final   # restamp cost on final turn

✅ 5 · Behaviour preserved — the evidence

This is the whole point: same events, same truth boundary, same prompt substance, same knobs. The existing Atlas test suite was ported off baml_client imports onto the new Pydantic models and stays green — 45 passed.