99 lines
4.7 KiB
Markdown
99 lines
4.7 KiB
Markdown
# 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.
|