Master Instructions

As the same field is extracted from many documents, AI synthesizes a master instruction — a reusable directive that captures the best way to extract that field. Master instructions improve accuracy over time and are automatically used when running jobs. They encode domain-specific knowledge about where a field typically appears in a document, what format it takes, and how to disambiguate it from similar fields.

Master instructions are synthesized by analyzing the extraction patterns across all documents where a field appears. The AI examines how the field was successfully extracted — including the source text, confidence scores, and document context — and distills a concise directive that captures the best extraction approach. For example, a master instruction for "invoice_date" might specify: "Look for the date near the invoice number, typically in the header area. Prefer the issue date over due date. Format as ISO 8601."

Master instructions fire automatically during Phase 2 of job runs, when the Planner extracts values for fields that could not be resolved via lookup. The instruction is injected into the AI prompt alongside the document content, giving the model specific guidance for that field. This is why master instructions improve accuracy: they encode domain-specific knowledge that the base model would otherwise lack.

You can view and edit master instructions from the field detail page in the registry. Editing an instruction overrides the AI-synthesized version, which is useful when you have domain expertise the AI hasn't captured. The "Synthesize All" button in the Field Registry triggers the full pipeline — embedding, resolution, and synthesis — for all qualifying fields in a single operation.

Instruction Lifecycle

1. A field is discovered and added to the registry as Candidate with no instruction.
2. As more documents are processed, the field accumulates occurrences and extraction examples.
3. When the field is promoted to Proven, the platform synthesizes a master instruction by analyzing all extraction patterns for that field.
4. The instruction is injected into AI prompts during future job runs, improving extraction accuracy.
5. You can manually edit the instruction at any time from the field detail page to incorporate domain expertise.

Auditing Instructions via API

Instruction synthesis is triggered from the app (the Improve All Rules action on the Extraction Rules page, /instructions), but instruction coverage is fully auditable over the REST API. Every field returned by GET /v1/fields carries its master_instruction (or null when no instruction has been synthesized yet), so you can script a coverage report by listing fields per maturity level and counting non-null instructions. This is useful for automated checks that instruction coverage stays above your quality threshold after each batch ingestion.

curl "https://api.talonic.com/v1/fields?maturity=proven" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Each field in "data" includes a "master_instruction" property.
# Fields with "master_instruction": null have no instruction yet.

The quality of master instructions directly correlates with extraction accuracy. Fields with well-crafted instructions consistently produce higher confidence scores during job runs because the AI model receives specific guidance about where to find the value, what format to expect, and how to disambiguate similar fields. Teams that invest in reviewing and refining master instructions — either manually or through the synthesis pipeline — typically see a 10-15% improvement in extraction confidence for Proven fields compared to extraction without instructions.

A well-written master instruction typically includes three components: where to find the field in the document (e.g., "Look in the header area near the document date"), what format to expect (e.g., "Format as ISO 8601 date: YYYY-MM-DD"), and how to disambiguate from similar fields (e.g., "Prefer the issue date over the due date or payment date"). The AI synthesis process automatically generates instructions following this pattern by analyzing successful extractions, but you can always refine them manually when your domain expertise suggests a better approach.