134 lines
3.5 KiB
Markdown
134 lines
3.5 KiB
Markdown
# D&D Spell Raw Output
|
|
|
|
This document is the durable raw output contract for the implemented
|
|
`dnd/spells` extractor.
|
|
|
|
## Identity
|
|
|
|
- Extractor key: `dnd/spells`
|
|
- Prompt ID: `dnd.spells`
|
|
- Response schema key: `dnd_spells`
|
|
- Response schema ID: `notarius.dnd.spells`
|
|
- Response schema name: `notarius_dnd_spells_v1`
|
|
- Response schema version: `v1`
|
|
- Media type: `application/json`
|
|
|
|
The extractor requires source chunks and transcript source capability. It
|
|
returns canonical spell-cast JSON derived from the structured LLM response. The
|
|
extractor assigns source IDs deterministically and keeps source-unit ranges as
|
|
model-authored evidence locations. The default `appendorder` merger passes a
|
|
single chunk output through and concatenates multiple
|
|
`spell_casts` arrays in chunk order. The default `noop` normalizer passes the
|
|
merge output through unchanged.
|
|
|
|
## Output Shape
|
|
|
|
For a single chunk, `lanes/spells.json` has this shape:
|
|
|
|
```json
|
|
{
|
|
"spell_casts": [
|
|
{
|
|
"caster": "Aria",
|
|
"spell": "Cure Wounds",
|
|
"effect": "heals an injured ally",
|
|
"narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
|
|
"source_refs": [
|
|
{
|
|
"source_id": "session-alpha",
|
|
"start_unit_id": 1,
|
|
"end_unit_id": 1
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`spell_casts` must be present. It may be empty when no spell casts are found.
|
|
|
|
For multiple chunks with the default merger, the lane output keeps the same
|
|
top-level shape and concatenates `spell_casts` in chunk order:
|
|
|
|
```json
|
|
{
|
|
"spell_casts": [
|
|
{
|
|
"caster": "Aria",
|
|
"spell": "Cure Wounds",
|
|
"effect": "heals an injured ally",
|
|
"narrative_description": "Aria raises her holy symbol and casts Cure Wounds.",
|
|
"source_refs": [
|
|
{
|
|
"source_id": "session-alpha",
|
|
"start_unit_id": 1,
|
|
"end_unit_id": 1
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Spell-Cast Fields
|
|
|
|
Each spell cast contains:
|
|
|
|
- `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;
|
|
- `source_refs`: transcript source references with extractor-assigned source
|
|
IDs and model-supplied unit ranges.
|
|
|
|
`caster` is the in-world caster, not the transcript speaker.
|
|
|
|
## Source References
|
|
|
|
Each source reference uses the generic source-reference shape:
|
|
|
|
- `source_id`
|
|
- `start_unit_id`
|
|
- `end_unit_id`
|
|
|
|
The LLM-facing prompt schema asks only for integer `start_unit_id` and
|
|
`end_unit_id` values matching source-unit IDs. `source_id` is assigned by the
|
|
extractor from the source document ID before validation and output, and is
|
|
required in this durable output contract.
|
|
|
|
## References
|
|
|
|
The extractor accepts optional UTF-8 text references:
|
|
|
|
- `players`
|
|
- `party`
|
|
- `glossary`
|
|
- `roster`, a deprecated compatibility alias for `party`
|
|
|
|
References are supporting disambiguation material only. They are not source
|
|
evidence and are not addressable through `source_refs`.
|
|
|
|
## Manifest Metadata
|
|
|
|
The extractor adds prompt and response-schema provenance under the artifact lane
|
|
manifest metadata:
|
|
|
|
```json
|
|
{
|
|
"metadata": {
|
|
"extractor": {
|
|
"prompt_id": "dnd.spells",
|
|
"prompt_version": "v1",
|
|
"prompt_sha256": "sha256:...",
|
|
"response_schema_key": "dnd_spells",
|
|
"response_schema_id": "notarius.dnd.spells",
|
|
"response_schema_name": "notarius_dnd_spells_v1",
|
|
"response_schema_version": "v1",
|
|
"response_schema_sha256": "sha256:..."
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Raw prompt and schema content are not included in manifest metadata.
|