LEARNING.md

Learning path

Read the codebase in this order. Each file answers an interview question that actually gets asked about agent systems — the question is stated first, so you know what you are reading for.

Budget: about three focused hours for the six stops, plus an hour reading traces.

---

1. app/graph/state.py — state design and reducers

"Two agents run in parallel and both write to shared state. What stops one from clobbering the other?"

Read for: why every field written by more than one node carries an Annotated[..., reducer], and why the reducers are all commutative merges rather than read-modify-write.

The answer, in one sentence: nothing in this system ever reads state, mutates it, and writes it back — nodes return partial updates and the runtime merges them with a declared reducer, so ordering between the two workers cannot matter.

Check yourself:

• Which fields are written by both agents? (errors, tool_calls, attempts, token_spend, agents_completed)
• What happens if you remove the reducer from one of them? (LangGraph raises InvalidUpdateError on concurrent writes — try it.)
• Why is iterations operator.add rather than last-write-wins?
• Why are append_records and append_errors bounded?

Then read tests/test_reducers.py — the second test drives a real superstep with await points that force interleaving.

---

2. app/graph/supervisor.py — routing, caps and termination

"How do you stop an agent loop from running forever or burning your budget?"

Read for: the two independent brakes, and how the fan-out is expressed.

The answer: a hard iteration cap and a token/USD budget guard that can trip from inside any node. They are independent on purpose — a cheap infinite loop is caught by the first, an expensive short one by the second.

Check yourself:

• Why does route_from_supervisor return a list of node names? (That is what puts both workers in one superstep.)
• Where is "retry a failed ticker exactly once" actually implemented? (attempts_for(...) < MAX_ATTEMPTS_PER_TICKER in the pending-ticker helpers.)
• The supervisor calls Haiku, but the dispatch set is computed from state. Why does that matter? (A model hiccup can slow the run; it cannot route it somewhere unsafe.)

Then read app/core/budget.py — note ensure_headroom, the pre-flight check, and why an unknown model prices at the most expensive tier.

---

3. app/mcp_server/ — tool schemas, and why MCP

"Why MCP? Couldn't you just call a Python function?"

Read for: registry.py (the tool contracts and docstrings), providers.py (caching, rate limiting, failure-as-data) and client.py (transport, whitelist, telemetry).

The answer: three things a function call does not give you — a standard other agent frameworks and clients can consume, runtime discoverability of schemas and documentation, and a hard security boundary around a closed tool surface.

Check yourself:

• Why does every tool return an error field instead of raising? (It is what makes per-ticker graceful degradation possible at all.)
• Where is the whitelist enforced? (Both ends — server and client.)
• What is the difference between the MCP tools and the "output tools" in prompts.py? (Data versus structured response. Only the first are executed.)
• Run make mcp and speak to the server yourself.

---

4. app/graph/verify.py + recompute.py — determinism

"How do you know the model didn't make a number up?"

Read for: the three-layer guarantee, and why recompute.py refuses to import the tool's maths.

The answer: the model cannot type a number at all. app/models/brief.py rejects any narrative string containing a bare numeral, so figures exist only as {{cN}} references into a claim table minted from tool output — and every claim is then recomputed from the raw price bars by a different implementation.

Check yourself:

• Name the three implementation differences between metrics.py and recompute.py. (Welford vs two-pass variance; accumulate vs a running-peak loop; bisect vs a forward scan.)
• Why is unverifiable treated as a failure rather than a pass?
• What are the tolerances, and why is USD 0.005?
• What happens to a quoted headline the model paraphrased?

Then read tests/test_verifier.py::TestDualPathAgreement — the proof the two paths agree on live data, which is what makes the dual check real.

---

5. app/graph/gate.py — interrupts and checkpointers

"How does a graph pause for a human and resume hours later?"

Read for: interrupt(), and the comment explaining why the node performs no side effects before it.

The answer: interrupt() suspends the graph and checkpoints state. The process can exit entirely. ainvoke(Command(resume=decision), config) continues from the checkpoint — which is why approval is a separate authenticated HTTP request and not a callback held in memory.

Check yourself:

• Why must the node avoid side effects before interrupt()? (It re-executes from the top on resume.)
• Where is the "awaiting approval" telemetry emitted instead, and why?
• A reviewer edits the headline to "stock jumped 42 percent". What happens? (Rejected — narrative validation still applies to human edits.)
• Which checkpointer is used locally, which in production, and why does the serializer have an allowlist?

Then read app/services/runner.py — the two ainvoke calls that bracket the pause.

---

6. app/graph/context.py — the LangGraph lesson that cost time

"How do you get a live handle — an open MCP session — into a graph node?"

The answer: not through config["configurable"]. LangGraph filters unknown configurable keys once a checkpointer is attached, because that dictionary is checkpoint state. Live handles belong in the runtime context channel (StateGraph(..., context_schema=RunContext) + ainvoke(..., context=ctx)), which is deliberately not persisted.

Also worth knowing: a node parameter annotated RunnableConfig | None under from __future__ import annotations is a string at inspection time, so LangGraph silently ignores it. The parameter looks right and does nothing.

Both were found by running the thing and reading warnings with -W error, not by reading documentation. That is the story to tell.

---

7. Twenty traces, end to end

Set LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY, run make eval, then read the traces rather than the summary.

Look for:

• Span shape — is the supervisor being called more often than the number of dispatches justifies?
• Token spend per role — is Haiku actually taking the routing load?
• Tool latency — which provider call dominates? (get_price_history, ~1s cold, ~0ms cached.)
• The regeneration path — run demo_mismatch and follow writer → verify → writer → verify → gate.
• A degraded run — run demo_fault and watch the retry-once logic drop a dead ticker at attempt two.

"I debug agents by reading traces, not by guessing" is only credible if you can describe something you actually found this way.

---

Questions you should be able to answer cold

1. Why LangGraph over CrewAI or AutoGen — and what you give up.
2. What a reducer is, and what breaks without one.
3. Why the tool layer is MCP rather than plain functions.
4. How a hallucinated number is prevented — all three layers, in order.
5. Why the verifier does not import the tool's maths.
6. What happens on a mismatch, exactly, and how many times.
7. How the graph survives the process dying between assembly and approval.
8. Where the run stops if the budget is exhausted mid-flight, and what status it reports.
9. How a prompt-injected headline is prevented from redirecting the run.
10. What it costs per brief, and which knob moves that number.

---

Portfolio context

LedgerLens → Lexora → AlphaBrief: extraction, retrieval, agents. One design language, three live demos, zero dollars spent.