4.7 KiB
ADR-0009: Prefer minimal evidence-grounded extraction artifacts
Status: Accepted Date: 2026-07-22
Context
Notarius is intended to extract structured facts from source material. Several early D&D artifacts grew to include descriptive prose, inferred relationships, immediate outcomes, summaries, and other enrichment alongside the facts that identify an event or entity. Those fields make one model call responsible for both extraction and synthesis.
In practice, the richer contracts have produced overlapping or weakly grounded fields and have made structurally valid, semantically coherent output harder for cost-effective smaller models. They also increase prompt size, validation and normalization policy, durable schema surface, downstream coupling, and the number of claims whose provenance must be evaluated.
The application needs a consistent rule for deciding what belongs in an extractor before redesigning the current D&D spell, NPC, and combat-turn contracts or adding new artifact families.
Decision
An extraction module answers one narrowly stated question and returns the smallest durable structured artifact that usefully answers it.
Every model-produced field in an extraction artifact must:
- be necessary to answer the extractor's stated question or serve a known downstream consumer;
- represent a fact or bounded classification that can be supported directly by cited source ranges;
- remain independently meaningful without model-generated explanatory prose; and
- justify the additional prompt, schema, validation, normalization, and compatibility surface it creates.
Source references are required provenance for extracted records. Auxiliary references may disambiguate identities or canonical names, but they do not establish source facts and are not copied into evidence.
Extraction artifacts do not include narrative summaries, general analysis, speculative enrichment, inferred biography or relationships, or redundant free-text descriptions by default. When such output has a demonstrated use, it belongs in an explicitly named extraction, classification, enrichment, or analysis module with its own contract and evidence policy.
Occurrence-level facts are not forced into entity-level attributes. A fact that can change between encounters, such as an NPC's role in a scene, belongs on an occurrence artifact rather than as one scalar property of a normalized NPC registry entry.
Deterministic mapping and normalization may assign application-owned identifiers, canonicalize known catalog values, order and deduplicate evidence, and collapse records under an explicit identity rule. They must not manufacture removed descriptive fields or synthesize missing claims to satisfy an older contract.
This is a default design rule, not a prohibition on rich artifacts. A richer field is appropriate when its consumer, evidence semantics, and ownership are explicit.
Alternatives considered
- Keep rich schemas and improve prompts or use larger models. This retains potentially convenient prose but does not resolve overlapping field responsibilities, weak provenance, higher cost, or unnecessary downstream coupling.
- Make enrichment fields optional. This reduces rejection pressure but leaves ambiguous artifact semantics and inconsistent records, and many strict structured-output providers still require nullable placeholders.
- Keep minimal private LLM schemas while preserving rich durable artifacts. Deterministic code would have to invent, default, or separately derive the missing fields, hiding synthesis behind the extraction boundary.
- Use one broad session-analysis module. This reduces the number of lanes but couples unrelated facts, schemas, retries, evaluation, and downstream consumers into one model call.
Consequences
Extraction prompts and response schemas become smaller, more focused, and more suitable for lower-cost models. Artifacts carry fewer unsupported claims, and their evidence and validation policies become easier to explain and evaluate. Independent extractors can evolve, retry, and be consumed without requiring unrelated enrichment.
Some descriptive convenience fields will disappear from primary artifacts. Consumers that genuinely need them may require a separate module and explicit pipeline step. Entity registries may no longer resolve aliases or relationships unless a dedicated, evidence-grounded capability supplies them.
Removing durable fields is a schema compatibility change. Each affected artifact requires an explicit version and reference policy; private prompt changes alone are insufficient. Current-behavior integration and internal documentation must change with implementation, while the roadmap owns the proposed contract until then.