notarius/docs/integrations/dnd-spells.md

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:

artifacts:
  spells:
    extract: dnd/spells
    merge: appendorder
    normalize: noop

Limits

The current implementation covers only D&D spell-cast extraction. It does not yet implement:

• item extraction;
• NPC extraction;
• combat extraction;
• encounter extraction;
• broad D&D rules validation;
• a CLI run workflow.