132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```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 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:
|
|
|
|
```sh
|
|
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?
|