137 lines
3.8 KiB
Markdown
137 lines
3.8 KiB
Markdown
# Checkpoint 6: D&D Spells Extractor
|
|
|
|
## Status
|
|
|
|
This document describes planned work, not implemented behavior.
|
|
|
|
## 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;
|
|
- 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:
|
|
|
|
```go
|
|
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 extract module 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: Process Module Implementation
|
|
|
|
Implement `internal/modules/extract/dnd/spells`.
|
|
|
|
The extractor should:
|
|
|
|
- satisfy the framework `Extractor` contract;
|
|
- declare module metadata for pipeline-profile validation;
|
|
- build LLM messages from a source document or source chunk;
|
|
- 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:
|
|
|
|
```sh
|
|
notarius run dnd-session --input ./transcript.json --only spells
|
|
```
|
|
|
|
The test should use fake LLM wiring, fixture input, and a named pipeline profile
|
|
with a `spells` artifact lane.
|
|
|
|
## 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, and through
|
|
CLI if the CLI path is ready.
|
|
|
|
## 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?
|