# LangGraph as the cyclic-graph substrate

We will build the QA pipeline (see ADR-0001) as an explicit LangGraph graph
rather than hand-rolling the loop in the existing `audiobook_creator`
orchestration. LangGraph is the industry-standard substrate for cyclic, stateful
agent graphs in Python, and it makes the back-edges first-class, legible objects
in the code (`add_conditional_edges` pointing backward), which is the point: the
DAG→cyclic shift becomes inspectable rather than an emergent property of
control flow.

## Status

accepted

## Considered options

- **Hand-rolled `while` loops** in the current orchestrator. No new dependency,
  but the cyclic graph lives implicitly in control flow — harder to reason
  about as cycles multiply, and the topology stops being inspectable.
- **LangGraph (chosen).** A dependency and some lock-in, in exchange for the
  graph topology being a first-class, inspectable artifact and for using the
  substrate the wider ecosystem has standardised on for cyclic agent graphs.

## Consequences

- Adds a LangGraph dependency to a project that is currently plain Python + API
  clients.
- Pipeline state (per-chapter retry budgets, best-so-far WER, flags for the
  report) becomes an explicit shared state object — the thing the graph carries
  between nodes and across back-edges.

## Skeleton scope (deferred behaviours)

The skeleton expresses the legacy linear orchestration as an acyclic graph and
deliberately defers anything cyclic. Two legacy behaviours map onto the
Quality Checks defined in `CONTEXT.md` at the repo root and are therefore
deferred to the cyclic-detector PRs, not reimplemented inside the skeleton:

- **Per-chapter duration check** (`check_chapter_during_synthesis`,
  `verification_integration.py`): maps to the **Fidelity check** plus the
  short-LLM-output signal of the **Script-validity check**. The skeleton would
  reimplement it; the cyclic detectors replace it.
- **Post-M4B audiobook verification** (`verify_complete_audiobook`,
  `verify.py`): is the seed of the **Coverage check** (CONTEXT.md says so
  explicitly). Same reasoning.

Three legacy behaviours are *not* Quality Checks and are wired into the
skeleton as ordinary infrastructure rather than deferred:

- **TTS preflight** (`_verify_tts_provider_available`) — runs in `run_graph`
  before invoking the compiled graph, conditioned on `creator.mode != "process"`.
- **TOC preview + confirm prompt** — encapsulated in `confirm_node`, which sits
  between `read` and `script_gen` in the `full` and `process` graphs. An abort
  returns `{"chapters": []}`, and downstream nodes naturally no-op on empty
  state (no conditional edges needed).
- **Process / synthesize modes** — `build_graph(mode)` dispatches to three
  topologies: `full`, `process` (`read → confirm → script_gen → report`), and
  `synthesize` (`load_scripts → synthesize → assemble → report`). The
  `--graph` flag therefore honours `--process-only` and `--synthesize-only`
  identically to the legacy orchestrator.