# Coda: Agentic Workflows

**Coda** (`ows-coda`) is a standalone AI agent for the Abacus royalties platform that is
becoming the **engine for agentic workflows over our internal APIs**. A caller 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 project doc covers the **workflow engine** and its **first workflow, contract creation**.
Other Coda capabilities (the chatbot, search, adjustments tooling, MCP exposure) are out of
scope here and tracked separately.

- **Owner:** Jonathan Raysor
- **Project key:** COD
- **Status:** Contract-creation workflow shipped (`ows-coda` PR #255 + follow-ups). Flag-gated,
  dry-run by default, real execution QA-only.
- **Last updated:** 2026-06-16

## Documents

| Document | Description |
|----------|-------------|
| [TRD](TRD.md) | Technical design of the workflow engine and the contract-creation workflow: the LangGraph state machine, the pure-pipeline / single-LLM-step split, the checkpointer, the preview-equals-execution guarantee, the safety gates, and the audit trail. |
| [Runbook](../../runbooks/coda/contract-creation.md) | Operating contract creation: flags, dev console, API, dry-run vs QA execution, monitoring, failures. |
| [Learn](../../learn/coda/contract-creation.md) | What the workflow does, conceptually. |

## Quick Links

| Resource | URL |
|----------|-----|
| Jira board: COD | [COD board](https://theorchard.atlassian.net/jira/software/c/projects/COD/boards/1318) |
| Repo: ows-coda | [github.com/theorchard/ows-coda](https://github.com/theorchard/ows-coda) |
| Shipping PR | `ows-coda` #255: Contract-creation agentic workflow (LangGraph) with evals and Coda UI panel |

## Repos

| Repo | What it contains (this project's scope) |
|------|------------------|
| `ows-coda` | The whole workflow engine. Graph + nodes in `apps/server/src/ai/workflows/contract-creation/`; checkpointer and audit in `apps/server/src/ai/workflows/`; HTTP API in `apps/server/src/routes/workflows.ts`; extraction eval in `apps/server/evals/contract-extraction/`; React hook + dev console for the UI. |
| `graphql-abacus` | The GraphQL gateway whose `abacusCreate*` / `abacusUpdate*` contract mutations Coda's write handler calls. Enforces the confirming user's permissions. |
| `ows-royalties` | The contract/term backend behind those mutations (the source of the "one label per term" and "at least one attachment" rules Coda mirrors in validation). |

## Glossary

| Term | Definition |
|------|-----------|
| **Workflow / thread** | One run of a workflow, identified by a `wf_<uuid>` thread ID. State is checkpointed per thread. |
| **Draft** | The structured extraction target: the contract-creation tool's fields, all optional. The single object the whole pipeline reads from. |
| **Extract** | The one LLM-backed node. Reads a document/text into a draft (Bedrock Claude, temperature 0, structured output). Skipped when only structured `params` are supplied. |
| **Validate** | Pure node that owns required-ness and mirrors the write handler's business rules (rates total 100, one label per term, at least one attachment, ISO dates). |
| **Prepare** | Pure node that builds the execution plan (exact tool input + ordered mutations with defaults) and the human preview from the same draft. |
| **Review** | The node that pauses the graph (LangGraph `interrupt()`) and waits for a confirm / amend / cancel. |
| **Execute** | Node that runs the confirmed plan through the hardened `create_distribution_contract` write handler. Idempotent: at most one execution per thread. |
| **Audit** | Node that records who/what/outcome to `coda:wf:audit:*` and the structured log. |
| **Dry-run** | Mode where confirm returns the would-be mutation payloads and writes nothing (`CODA_WORKFLOWS_DRY_RUN`). |
| **QA gate** | The write handler refuses contract mutations outside `ENVIRONMENT=qa`. |
| **Checkpointer** | `CacheStoreCheckpointSaver`. Persists LangGraph checkpoints to the cache (Redis or in-memory) under `coda:wf:ckpt:*` so a paused run survives across HTTP requests. |

## Team

| Role | Contact |
|------|---------|
| Owner / lead | Jonathan Raysor |
| Team | Coda (see the COD board) |