The Spec & One Engine

A Spec is the configuration layer for production structuring. It sits on top of one schema and describes the full path a document travels: which stages run, in what order, with which policies and validation gates attached. Where a quick Job answers "structure these documents against this schema right now", a Spec answers "this is how documents of this kind are always structured", and it can be run again and again as new documents arrive. The Spec is the front door for any workload that is more than a one-off.

Running a Spec compiles its composed rail into a pipeline and executes it on the engine: a single, per-document phase runner, distinct from the multi-strategy 4-phase engine behind quick Jobs. Each document moves through the same ordered phases independently and in parallel, so one slow document never holds up the rest. Every value the engine writes lands in the value plane as a versioned cell with provenance, so the output is auditable from raw extraction through resolution and human review.

The engine runs four kinds of per-document phase in sequence. Transfer fills cells deterministically from the Field Registry, binding known values with no AI call. Extraction runs Claude over the gap fields that transfer could not fill. Resolution applies your Data Policies to normalize and transform values. Validation checks the document against the gates you placed in the rail. After every document is terminal, a pipeline-scoped Assembly step can compose grouped documents into a single record. Phases are strictly sequential per document: phase N+1 starts only once phase N completes.

Resolution and Validation can also run after Assembly, not only per document. When a Data Policy or a validation checkpoint sits after the Assembly node in the rail, it becomes a pipeline-scoped phase that runs once over the composed record. A post-assembly resolution normalizes the assembled row and mirrors the resolved values back onto each anchor document, so the data product ships the resolved value rather than the raw composed one. A post-assembly validation gate then checks the full composed row. The two run in that order — resolution before validation — so a gate placed after Assembly sees resolved composed values. Both are best-effort tail steps and do not appear in the per-document progress phases.

This separation is what makes the platform repeatable. You invest once in composing a Spec for a document kind (a delivery note, a purchase order, a contract), attach the policies and checkpoints that encode your quality bar, and from then on every run is a single call. Because the rail is a faithful description of the run, the compiled pipeline always matches what you configured, and a re-run reproduces the same path. The growing Field Registry means each run also resolves more cells deterministically at zero cost.

Spec and Pipeline via API

A Spec is a schema with a composed rail. Create the schema, set its rail, then run a pipeline against it with a set of document IDs. The public pipeline endpoint compiles the rail and starts processing in one call, so there is no separate start step. Poll the progress endpoint to watch each phase advance.

curl -X POST https://api.talonic.com/v1/pipelines \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "sch_delivery_notes",
    "document_ids": ["doc_7f3a1b2c", "doc_9e4d5f6a"]
  }'

{
  "id": "pl_x8k2m9",
  "status": "active",
  "schema": { "id": "sch_delivery_notes", "name": "Delivery Notes" },
  "document_count": 2,
  "enqueued_documents": 2,
  "message": "Pipeline created and queued for processing.",
  "links": {
    "self": "/v1/pipelines/pl_x8k2m9",
    "progress": "/v1/pipelines/pl_x8k2m9/progress",
    "data_product": "/v1/pipelines/pl_x8k2m9/data-product"
  }
}