Configure once, apply everywhere: governed output standards

Every extracted field has to answer two questions the same way, no matter which agent produced it: how is this value shaped (is a date 2025-01-05 or Jan 5, 2025, is money 100000 or $100,000), and how sure are we (was it read verbatim, implied, inferred, or genuinely uncertain). If each agent answers those questions in its own YAML, you don’t have a standard — you have twenty-three near-copies that drift apart the moment someone edits one and forgets the rest.

InsightXtract treats output shape as a platform concern, not an agent concern. There is one canonical Output Contract for formatting and one canonical confidence taxonomy. Every agent inherits both automatically. An agent may override a specific rule, and a single field may set its own option, but the default is inheritance — so the standard is the path of least resistance, and drift has to be a deliberate act, not an accident.

The governing principle: agents declare what, the platform decides how

The whole model rests on one idea. An agent declares what a field is — its type — and the platform decides how that type renders. A field marked currency renders as a bare number with no symbol and no separators, because that is what the contract says currency means, everywhere. A field marked date renders as YYYY-MM-DD. The agent author never re-states the format; they just pick the right type, and the resolved contract does the rest at extraction time.

This is why formatting doesn’t need to live in each agent’s configuration. The schema already carries the type. Per-agent configuration then shrinks to the things that genuinely differ between agents: business rules like glossary standardization, cross-field derivations, and validations.

The layered model: most specific wins

Rules resolve through four layers. Each layer can inherit from the one above, override a specific rule, or add extra rules. Later, more specific layers win — field by field.

Precedence: platform < org < agent < document-class. The resolver merges these top-to-bottom, field by field, and the most specific setting wins — producing one resolved contract the engine applies at extraction time.

Layer	Scope	What it controls
Platform Output Contract	Global	The canonical format rules keyed by field type, plus the confidence taxonomy and its numeric bands. Inherited by every agent automatically.
Org defaults	Tenant	Optional org-wide overrides layered above the platform defaults — e.g. a house convention for a whole tenant.
Agent master_config	Per agent	Where agent-specific business rules live — and where an agent may override one format rule if justified.
Document-class config	Per class	The most specific layer. Can inherit, override, or add extras for a single document class within an agent.

The key word is field-by-field. Overriding the currency rule on one field of one agent changes exactly that field. Every other field, and every other agent, still inherits the platform default. There is no way for a local edit to quietly reshape the global standard.

Two kinds of rules, two very different defaults

Not all rules behave the same way, and treating them the same is what causes drift. InsightXtract separates them.

Format rules — date, currency, number, percent, boolean, and the null policy — are global-first. They are driven by the field’s type, so the platform can decide them once and they almost never need an override. Business rules — glossary standardization, derivations, and validations — are the opposite: a few common ones can be shared, but they are mostly agent-specific by nature, and adding them per agent is their primary use.

Rule kind	Global by default?	Overridable?	Added per agent?	Driven by
Format rules date · currency · percent · boolean · null	Yes — the Contract	Yes	Rarely (type already decides)	Field type
Business rules standardize · derive · validate	A few common ones	Yes	Yes — primary use	Explicit configuration

The practical effect: the boring, universal decisions (how money looks) are made once and never repeated, while the interesting, account-specific decisions (how to standardize a coverage code, how to derive a loss ratio, what makes a submission invalid) stay exactly where they belong — with the agent that needs them.

The canonical Output Contract

Applied to every field automatically, keyed off the field’s declared type. This is the format table an administrator sees on the Output Contract page.

Declared type	Canonical output	Example in → out
date / datetime	YYYY-MM-DD	Jan 5 2025 → 2025-01-05
currency / money	bare number	$100,000 → 100000 — no symbol, no commas
number / integer	bare number	1,200 → 1200
percentage	ratio	15% → 0.15, 12.5% → 0.125
boolean	Yes / No	true / Y → Yes
email / phone / address / text	trimmed string	whitespace and placeholders normalized
any type, not found	null	—

Two conventions are worth calling out because they remove ambiguity downstream. Percentages are stored as a ratio — a fraction — keeping up to four decimal places, so 12.50% is preserved as 0.125 rather than truncated; a field that already arrives in points declares percent_basis: points and the contract divides by 100. Booleans are stored as the strings Yes / No by requirement, so a boolean field is a string in the JSON — intentional and consistent everywhere.

The null policy is equally firm: a not-found value becomes JSON null inside the {value, page, bbox} wrapper, empty tables become rows: [], and placeholder tokens like N/A, -, or none are normalized to null. Fields are never omitted, never "N/A", never an empty string. A consumer can trust that “absent” always looks the same.

Inherit vs. override: one money field, two agents

Here is the model at its most concrete. The platform contract renders currency as an integer — zero decimals. Agent A leaves it alone. Agent B works with a downstream system that requires cents, so it overrides the decimal places on that one field. Same source value, same field type, two governed outputs — and the difference is visible and deliberate.

	Agent A — inherits	Agent B — overrides
Field type	currency	currency
Contract setting used	platform default (0 decimals)	agent override (decimal_places: 2)
Raw value in document	$100,000.00	$100,000.00
Governed output	100000	100000.00
Who authored it	nobody — inherited	Agent B, one line, justified

Agent A didn’t write a formatting rule at all; it got the correct answer for free. Agent B’s deviation is a single explicit line that any reviewer can see and question. That is the whole point: inheritance is silent and universal; overrides are loud and local.

A shared confidence taxonomy

Confidence gets the same treatment as formatting: one standard, applied everywhere. Instead of an opaque number that means something slightly different for each agent, every field carries a category from a fixed enum, mapped to a numeric band. The bands are tunable by an administrator, but the categories are constant.

Category	Meaning	Representative band
exact	Value read verbatim from the document.	1.0
implied	Stated indirectly or drawn from adjacent context.	~0.85
inferred	Derived or computed from other values.	~0.6
uncertain	Ambiguous, conflicting, or from a low-quality source.	~0.3

Formatting and confidence are enforced from opposite ends. Formatting has a deterministic post-processor as its source of truth: the prompt asks the model for near-canonical values, but code coerces them regardless of model drift. Confidence is the reverse — the model is the source of truth for the category, because only it knows how it obtained a value, and code may only validate and downgrade. A date that fails to parse, or a required field that comes back null, is capped at uncertain no matter what label the model attached. Both the category and its numeric score are persisted per field, and the document-level score aggregates from them.

The admin surface: one page, visible to all, editable by admins

The canonical format rules and the confidence bands live on a single Output Contract page. It is read-only for everyone and editable by administrators. That distinction matters more than it sounds: the standard is no longer buried in code or scattered across YAML files where only an engineer can find it. Anyone — a reviewer, an auditor, a new team member — can open one page and see exactly how the platform formats a date, renders money, stores a percentage, and grades confidence.

Because the contract is stored as configuration rather than hard-coded, non-default changes take effect without a redeploy. The engine reads the resolved contract through a cached loader and falls back to the built-in defaults if nothing has been customized. An administrator can adjust a confidence band or set an org-level convention, and the next extraction picks it up — no release, no downtime.

Why it matters

Governed output standards are not a cosmetic nicety. They change what the platform can promise:

• Consistency across dozens of agents. Every agent renders a date, a dollar amount, and a percentage identically, because they all resolve the same contract. A downstream system integrating with the platform writes one parser, not one per agent.
• Auditable standards. The rules exist in one place, visible to everyone. “How does this platform handle money?” has a single, inspectable answer — not an archaeology project across configuration files.
• No copy-paste drift. Because inheritance is the default, adding a new agent means it’s already compliant. Nobody duplicates formatting rules, so nobody forgets to update a duplicate.
• Deliberate, local exceptions. When a real business reason demands cents, or points instead of a ratio, the override is a single explicit line scoped to one field — easy to review and easy to justify.
• Blocking validation when it counts. Turning on strict mode makes validation enforcement blocking: if an error-severity rule fails, the run is marked failed rather than emitting a quietly non-compliant record. For regulated or high-stakes intake, a bad record never leaves the pipeline.

The result is a platform where the output standard is a first-class, governed object — authored once, inherited everywhere, overridden only on purpose, and visible to everyone who has to trust the numbers. Adding the twenty-fourth agent doesn’t add a twenty-fourth formatting convention. It inherits the one that already exists.