diff --git a/docs/integrations/dnd-spells.md b/docs/integrations/dnd-spells.md new file mode 100644 index 0000000..cd67169 --- /dev/null +++ b/docs/integrations/dnd-spells.md @@ -0,0 +1,116 @@ +# D&D Spell Cast Extraction + +This document describes the D&D spell-cast extractor currently implemented in +Notarius. + +## Module + +- Module key: `dnd/spells` +- Artifact type: `dnd.spell_cast` +- Schema version: `v1` +- Prompt ID: `dnd.spells` +- Response schema key: `dnd_spells` +- Response schema ID: `notarius.dnd.spells` +- Response schema name: `notarius_dnd_spells_v1` + +The module is an extract module. It reads a generic source chunk, renders the +`dnd.spells` prompt, calls the configured structured LLM client, and returns +spell-cast artifact candidates. + +## Source Expectations + +The extractor expects a generic `SourceDocument` and active source chunk. It +does not depend on concrete Seriatim package types. + +Pipeline resolution must provide these capabilities before the extractor runs: + +- `chunks` +- `source.transcript` + +Source units may include transcript metadata such as speaker and timestamps. +That metadata is optional prompt context. It is not part of the durable spell +payload. + +## Artifact Payload + +Each approved artifact payload is a JSON object with these fields: + +- `caster`: in-world character or creature casting the spell; +- `spell`: spell name; +- `effect`: concise spell effect in the scene; +- `narrative_description`: short description of the spell cast in context. + +`caster` is not the table speaker. NPCs, monsters, and other DM-voiced +characters can be casters. + +## Source References + +The structured LLM response must include `source_refs` for each spell cast. +Each source reference uses the generic source-reference shape: + +- `source_id` +- `start_unit_id` +- `end_unit_id` + +The extractor copies those references into the generic artifact envelope +`source_refs` field. The durable `dnd.spell_cast` payload does not duplicate +source references. + +Source-reference IDs must match the source document and source-unit IDs +exactly. The validator chain rejects unknown source IDs, unknown unit IDs, and +reversed unit ranges. + +## Validators + +The extractor provides these deterministic validators by default, in order: + +- `dnd/spells/shape` +- `dnd/spells/source_refs` + +`dnd/spells/shape` rejects: + +- malformed JSON payloads with reason code `invalid_payload`; +- blank `caster`, `spell`, `effect`, or `narrative_description` fields with + reason code `missing_required_field`. + +`dnd/spells/source_refs` rejects: + +- candidates with no source references using reason code `missing_source_ref`; +- invalid source references using reason code `invalid_source_ref`. + +The source-reference validator uses the core `source.ValidateRef` behavior, so +its rejection message includes the underlying source-reference validation +error. + +## Capabilities + +The module declares these required capabilities: + +- `chunks` +- `source.transcript` + +The module declares this provided capability: + +- `dnd.spell_casts` + +A pipeline artifact lane can reference the extractor with: + +```yaml +artifacts: + spells: + extract: dnd/spells + merge: appendorder + normalize: noop +``` + +## Limits + +This checkpoint implements only D&D spell-cast extraction. It does not +implement: + +- item extraction; +- NPC extraction; +- combat extraction; +- encounter extraction; +- broad D&D rules validation; +- a CLI `run` workflow. diff --git a/docs/roadmap/6-dnd-spells-extractor.md b/docs/roadmap/6-dnd-spells-extractor.md index 3c4e756..17dc60c 100644 --- a/docs/roadmap/6-dnd-spells-extractor.md +++ b/docs/roadmap/6-dnd-spells-extractor.md @@ -2,7 +2,9 @@ ## Status -This document describes planned work, not implemented behavior. +This document records the target scope for checkpoint 6. The implemented +integration contract is documented in +[`docs/integrations/dnd-spells.md`](../integrations/dnd-spells.md). ## Goal