notarius/docs/roadmap/5-dnd-spells-extractor.md

Checkpoint 5: D&D Spells Extractor

Status

This document describes planned work, not implemented behavior.

Goal

Implement the first useful extraction module: D&D spell casts from a Seriatim transcript source document.

This checkpoint should produce the first meaningful vertical slice from real source input to validated artifact output.

Scope

In scope:

• D&D spell artifact schema and Go structs;
• structured response schema asset;
• prompt assets;
• internal/extractors/dnd/spells;
• source-reference and schema validators in the extractor chain;
• fake LLM tests;
• CLI-level integration test if the CLI path is ready.

Out of scope:

• D&D item extraction;
• NPC extraction;
• combat extraction;
• cross-slice deduplication beyond simple deterministic merging;
• broad D&D rules validation.

Proposed Stages

Stage 1: Spell Artifact Schema

Define the D&D spell artifact model.

Initial shape:

type SpellCast struct {
    Player               string      `json:"player"`
    Spell                string      `json:"spell"`
    Effect               string      `json:"effect"`
    NarrativeDescription string      `json:"narrative_description"`
    SourceRefs           []SourceRef `json:"source_refs"`
}

Keep this schema inside the D&D spells extractor or a D&D artifact package, not inside core framework packages.

Stage 2: Structured Response Schema

Add a structured response schema asset for spell extraction.

The schema should require:

• spell-cast array;
• non-empty player, spell, effect, and narrative description fields;
• at least one source reference per spell cast.

Stage 3: Prompt Assets

Add embedded prompt assets for D&D spell extraction.

Prompts should:

• describe the generic source-unit input format;
• explain that source references must use source-unit IDs;
• avoid relying on transcript-specific fields except as optional metadata;
• request only spell-cast artifacts.

Stage 4: Extractor Implementation

Implement internal/extractors/dnd/spells.

The extractor should:

• satisfy the framework Extractor contract;
• build LLM messages from a source document or source slice;
• call the structured LLM client;
• return artifact candidates with source references;
• attach its validator chain.

Stage 5: Validators And Tests

Wire deterministic validators:

• schema/shape validation;
• source-reference validation;
• required-field validation if not covered by schema handling.

Add tests using a fake structured LLM client:

• successful spell extraction;
• empty result;
• invalid source reference rejection;
• malformed structured output handling;
• stable output ordering.

Stage 6: CLI Integration

If the CLI path is ready, add an end-to-end test using:

notarius extract ./transcript.json --input seriatim --extractors dnd.spells --output ./artifacts.json

The test should use fake LLM wiring and fixture input.

Done Criteria

• go test ./... passes.
• Seriatim input can flow through the runner into the D&D spells extractor.
• Spell artifacts include valid source references.
• D&D concepts are contained in extractor/artifact packages and docs.
• The first meaningful vertical slice is available through tests, and through CLI if the CLI path is ready.

Review Questions

• Is the spell extractor domain-specific without making the framework D&D-specific?
• Are source references valid and useful for downstream validation?
• Is prompt/schema ownership clear?
• Does this vertical slice reveal contract changes needed before adding items, NPCs, or combat?