# Learn: Coda (agentic workflows)

**Coda** (`ows-coda`) is a standalone AI agent for the Abacus royalties platform. It started
as a chatbot over royalties data, and it is becoming the **engine that runs agentic workflows
over our internal APIs**. A user (or another service) describes an outcome, Coda drafts the
exact mutations, a human confirms, and Coda executes them through the same hardened API surface
the Abacus UI uses.

This section explains those workflows conceptually. For how to operate them see the
[Coda runbooks](../../runbooks/coda/README.md); for the design see the
[Coda technical project](../../technical-projects/coda/README.md).

## Why a workflow engine (and not just a chatbot)

A chat tool answers questions. A workflow does work, and "work" here means **writes**:
creating a contract, submitting an adjustment, transferring earnings. Writes need three things
a free-form chat loop does not give you cheaply:

1. **A reviewable plan.** The user must see exactly what will be written *before* it happens.
2. **A confirm gate.** Nothing mutates until a human says "yes", and what they approve is
   byte-for-byte what runs.
3. **An audit trail.** Every execution is recorded: who, what they confirmed, what ran, the
   outcome.

Coda models each workflow as a small **LangGraph** state machine with exactly one stochastic
(LLM) step, extraction, and an otherwise **pure** pipeline. That split is the whole point. The
model only ever *reads* a document into structured fields; planning, preview and execution are
deterministic functions of those fields, so the preview the user confirms is identical to the
payload that executes.

## Topics

- [Contract creation](./contract-creation.md): the first workflow. It turns a deal memo (PDF,
  text, or structured params) into a distribution contract, with a preview-and-confirm gate
  before anything is written. **This is the only workflow shipped so far.**
- [Evals](./evals.md): how the one stochastic step (extraction) is measured against fixtures,
  and how that scoring is what makes an LLM safe to put in front of real contract writes.

## The shape every Coda workflow shares

```mermaid
flowchart LR
    IN["Input<br/>(document / text / params)"] --> EX["extract<br/>(LLM, the only stochastic step)"]
    EX --> VA["validate<br/>(pure)"]
    VA --> PR["prepare<br/>(plan + preview, pure)"]
    PR --> RV{{"review<br/>(pauses, waits for a human)"}}
    RV -->|amend| VA
    RV -->|cancel| STOP["end"]
    RV -->|confirm| EXE["execute<br/>(wraps the real write API)"]
    EXE --> AU["audit<br/>(record who/what/outcome)"]
```

- **Human in the loop is mandatory.** `review` literally pauses the graph (a LangGraph
  `interrupt()`). The workflow sits and waits, possibly across many minutes and several HTTP
  requests, until someone confirms, amends, or cancels.
- **Preview equals execution.** Both are built from the same checkpointed draft, so there is no
  gap between "what you were shown" and "what ran."
- **Two safety gates wrap every real write.** A **dry-run** mode returns the would-be mutation
  payloads without sending them, and real execution is **QA-only** today.
- **State is durable.** Each workflow run ("thread") is checkpointed to the cache (Redis in
  deployed environments), so a paused workflow survives the request that created it.

The rest of this section walks the contract-creation workflow concretely.