129 lines
3.2 KiB
Markdown
129 lines
3.2 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 the structured LLM response as raw JSON. 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 supplied by the model.
|
|
|
|
`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 extractor prompt and schema use integer `start_unit_id` and `end_unit_id`
|
|
values matching source-unit IDs.
|
|
|
|
## 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.
|