Atlas: Pydantic Logfire (US) for the LLM lane

Branch issue-1291-atlas-logfire · Story: pramaan-io/pramaan-spec#1291 · Provenance: pramaan-docs ADR-118 (Logfire = LLM lane), builds on ADR-117 (Pydantic AI), ADR-116 (provider-switch), ADR-110 §6 (thin brain), ADR-104 (ONE general-tracing system)

🛰️ 1 · Satellite — why this exists

Atlas now runs on Pydantic AI (Story-1288 / ADR-117). The general telemetry lane — CloudWatch + X-Ray via the single ADOT layer (ADR-104) — sees Lambda/AgentCore runtime metrics, but it is blind to the inside of an LLM call: the exact prompt, the model + provider chosen, the token counts, the latency, the structured output. When Atlas fabricates a clause or stalls, that lane gives us a flat span and no answer.

The naïve fix — bolt prompt/response logging into the runtime by hand — detonates on two doctrines: it would re-implement an observability path the platform already standardises (ADR-104 says ONE general-tracing system), and it risks dumping privileged prompt text into the wrong place. The decision (ADR-118): a dedicated LLM lane — Pydantic Logfire — that natively instruments Pydantic AI and ships prompt/model/token/latency spans to a Logfire project, leaving the general lane untouched.

This Story is the agents-side wiring only: one env-gated init hook. No behaviour change, no new truth, no runtime-shape change.

✈️ 2 · Airplane — the shape of the change

cold start (main.py)
      │  configure_observability()          ← the one hook, called once
      ▼
LOGFIRE_TOKEN set?  ──no──►  NO-OP  (no configure, no instrument, no egress)
      │ yes                              local dev + CI are byte-identical here
      ▼
logfire.configure(token, service_name="atlas",
                  advanced=AdvancedOptions(base_url="https://logfire-us.pydantic.dev"),
                  send_to_logfire="if-token-present", console=False)
logfire.instrument_pydantic_ai()           ← instruments ALL five Atlas agents
      ▼
every agent.run / run_stream  →  prompt · model · provider · tokens · latency span
      ▼
OTLP egress → Logfire US datacenter project

One new module (observability.py), one call site (main.py cold start), one dep (logfire). The brain's request/response contracts, events, and truth boundary are frozen.

🔬 3 · Microscope — what was added, and WHY each piece

🔬 4 · The one subtle bit — gate before import

The import logfire lives inside the token branch, not at module top. So with no token the SDK is never even imported — the no-op path costs nothing and a Logfire-free environment never trips over a missing/heavy dependency at cold start. The test injects a fake logfire into sys.modules and asserts it is never touched on the no-token path.

token = os.getenv("LOGFIRE_TOKEN")
if not token:
    _log.debug("Logfire disabled: …")
    return False
# logfire is never imported here

import logfire
logfire.configure(
  token=token, service_name="atlas",
  advanced=logfire.AdvancedOptions(
    base_url="https://logfire-us.pydantic.dev"),
  send_to_logfire="if-token-present",
  console=False)
logfire.instrument_pydantic_ai()

✅ 5 · Behaviour preserved — the evidence

The point: token absent ⇒ nothing changes; token present ⇒ spans only. A new test module pins every constraint, and the existing Atlas suite stays green.