117 lines
3.1 KiB
Markdown
117 lines
3.1 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
artifacts:
|
|
spells:
|
|
extract: dnd/spells
|
|
merge: appendorder
|
|
normalize: noop
|
|
```
|
|
|
|
## Limits
|
|
|
|
This checkpoint implements only D&D spell-cast extraction. It does not
|
|
implement:
|
|
|
|
- item extraction;
|
|
- NPC extraction;
|
|
- combat extraction;
|
|
- encounter extraction;
|
|
- broad D&D rules validation;
|
|
- a CLI `run` workflow.
|