AI Extract — Structured Extraction

• Area: Intelligence
• Path: services/ai/extract
• Kind: Schema-driven structured extraction (JSON-out-of-content), NER, KV pairs
• Status: v0.0.1 — schema-driven extraction engine landed (EXTRACT-001, 2026-05-28): JSON Schema 2020-12 validation + validate→retry-with-correction loop + LLMClient (gateway) + Pydantic-shorthand + cache. Live gateway wiring + persistence pending.

Role in the stack

extract consolidates a capability that was duplicated across the stack: every consumer needing JSON-out-of-text (rag, recsys, half-a-dozen product backends parsing forms/invoices) had its own home-grown prompt + retry + repair loop, all subtly different and all subtly broken. This sector centralizes the capability — JSON Schema validation server-side, principled retry-with-correction (LLM sees its own validator error and fixes it), batch processing, cached repeat extractions.

It is the Koder analog of OpenAI Structured Outputs, Instructor (Python), and Marvin. It pairs with vision/ (visual document → text+layout pre-step) and is the canonical ingest path for rag/ and recsys/.

Boundary vs neighbors

• services/ai/vision is the visual pre-step for PDF/image content; extract consumes its layout-aware output.
• services/ai/rag and services/ai/recsys are the highest-volume consumers — both will migrate from bespoke loops.
• services/ai/gateway provides the LLM with structured-output / function-calling.
• services/ai/cache provides repeat-extraction caching.
• services/ai/prompt owns extraction prompt templates.

Features (v1 target)

• Schema-driven extraction (JSON Schema draft 2020-12)
• Bounded retry-with-correction (default 3 attempts, hard cap 5)
• NER with canonical Koder taxonomy (16 types incl. CPFCNPJCEP)
• KV pair extraction (forms, receipts) — layout-aware when input has bounding boxes
• Async batch jobs with concurrency control + progress streaming (SSE)
• Repeat-extraction cache keyed by (schema, content, model, instructions)
• Pydantic-shorthand acceptor (auto-translated to JSON Schema)
• SDK helpers (Go + Dart) for downstream consumers

Primary couplings

RFC and bootstrap

• RFC: extract-RFC-001-foundations.kmd — accepted 2026-05-09
• Bootstrap ticket: services/ai/backlog/done/132-extract-bootstrap.md
• Implementation tickets: 001 schema-driven extraction + retry-with-correction — DONE 2026-05-28 (backend/: JSON Schema 2020-12 via santhosh-tekuri/jsonschema/v6 behind a Validator iface; Engine.Extract normalize→compile→cache→validate→retry-with-correction loop (maxattempts 3cap 5, correction prompt shows the model its error per RFC Q2); LLMClient (HTTPLLMClient→gateway `v1chatcompletions + stub); Pydantic-shorthand→JSON-Schema translator (RFC Q1); sha256 cache; EXTRACT- errors; POST v1extractschema on :9461; -race` tests on dev-linux-workflow VM covering simplenestedoneOfenumformatadditionalPropertiesretry-2ndretry-exhaustedcacheshorthandHTTP). Residual: live gateway wiring, shared cache via servicesai/cache. *002 NER endpoint + canonical entity taxonomy — DONE 2026-05-28 (internal/ner: closed 16-type taxonomy with pt-BR CPFCNPJCEP first-class; deterministic regex+rule pre-pass for high-precision types + CPFCNPJ mod-11 + CEP validators (bad check digit → 0.4 confidence) + normalization (digitsMONEY→{amount,currency}DATE→ISO); LLM context pass reusing the #001 engine; `POST /v1extractentities; -race` tests on the VM). Residual: precisionrecall golden-set metric (needs labeled corpus + real LLM). 003 KV pair extraction — DONE 2026-05-28*(internal/kv: POST /v1/extract/keyvals over the #001 engine — free-form pairs + expectedkeys-constrained fill-or-null; hints + multilingual label-expansion in instructions; koder-vision-doc text parsing (layout heuristic deferred → vision); NER-shared cpfcnpjcep normalization; EXTRACT-KV-* errors; -race tests on the VM). Residual: layout-aware mode (gated on servicesaivision). 004 batch + async jobs — DONE 2026-05-28 (internal/jobs: async manager + worker pool reusing #001, per-tenant + per-job concurrency caps, progress counters, idempotency, cancel, SSE per-itemjob_finished, cost estimate; `POST /v1extractbatch + GET /jobs{id} + stream + cancel; -race tests incl. deterministic concurrency-bound proof on the VM). Residual: kdb-blob JSONL persistence + restart-resumability + 10k stress. Pending: 005` SDK+rag/recsys.

Self-hosted-first analysis (5 gates)