121 lines
4.0 KiB
Markdown
121 lines
4.0 KiB
Markdown
# Checkpoint 6: D&D Spells Extractor
|
|
|
|
## Status
|
|
|
|
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
|
|
|
|
Implement the first useful extract-stage 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/modules/extract/dnd/spells`;
|
|
- module metadata/capability requirements for pipeline validation;
|
|
- source-reference and schema validators in the extractor chain;
|
|
- fake LLM tests;
|
|
- runner-level integration tests with fake infrastructure.
|
|
|
|
Out of scope:
|
|
|
|
- D&D item extraction;
|
|
- NPC extraction;
|
|
- combat extraction;
|
|
- cross-slice deduplication beyond simple deterministic merging;
|
|
- broad D&D rules validation;
|
|
- a `notarius run` command.
|
|
|
|
## Target End State
|
|
|
|
The repository should contain a real D&D spells extract-stage module at
|
|
`internal/modules/extract/dnd/spells`.
|
|
|
|
The spells module should be registered under the stable extractor key
|
|
`dnd/spells`. It should be selectable as a named artifact lane in pipeline
|
|
configuration, for example a lane named `spells` whose extractor module is
|
|
`dnd/spells`.
|
|
|
|
The module should translate generic source chunks into spell-cast artifact
|
|
candidates with this spell payload:
|
|
|
|
- `caster`;
|
|
- `spell`;
|
|
- `effect`;
|
|
- `narrative_description`.
|
|
|
|
The LLM structured response should also include source references for each
|
|
spell cast. The extractor should copy those references into the generic
|
|
artifact envelope rather than duplicating source references inside the durable
|
|
spell payload.
|
|
|
|
The caster is the in-world character or creature casting the spell, not the
|
|
table speaker. Speaker metadata from transcript source units may be used as
|
|
optional prompt context when present, but it should not be a required or durable
|
|
field in the spell payload.
|
|
|
|
Prompts should:
|
|
|
|
- describe the generic source-unit input format;
|
|
- explain that source references must use source-unit IDs exactly;
|
|
- avoid relying on transcript-specific fields except as optional metadata;
|
|
- request only D&D spell-cast artifacts.
|
|
|
|
The extractor should attach deterministic validators by default. Validation
|
|
should cover:
|
|
|
|
- spell payload shape;
|
|
- non-empty required spell fields;
|
|
- at least one source reference per spell cast;
|
|
- source references that validate against the source document.
|
|
|
|
The module should declare flat capabilities for pipeline validation. Initial
|
|
capabilities should require chunked transcript source material and provide a
|
|
D&D spell-cast artifact capability.
|
|
|
|
Implementation staging belongs in
|
|
[`implementation.md`](implementation.md).
|
|
|
|
## Fixtures And Tests
|
|
|
|
The checkpoint should add synthetic fixtures and focused tests for:
|
|
|
|
- successful spell extraction with a fake structured LLM client;
|
|
- empty spell-cast results;
|
|
- malformed structured output handling;
|
|
- invalid source-reference rejection;
|
|
- stable output ordering;
|
|
- pipeline-profile selection of a `spells` artifact lane;
|
|
- runner integration from Seriatim input through the spells extractor using
|
|
fake chunk and output modules.
|
|
|
|
## 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 extract module/artifact packages and docs.
|
|
- The spells module can be selected as a named artifact lane in pipeline
|
|
configuration.
|
|
- The first meaningful vertical slice is available through tests.
|
|
- No CLI `run` behavior is documented or implemented until the CLI path exists.
|
|
|
|
## Review Questions
|
|
|
|
- Is the spell extract module 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?
|