91 lines
3.2 KiB
Markdown
91 lines
3.2 KiB
Markdown
# D&D Spell Artifact
|
|
|
|
This document is the durable serialized artifact contract for the production
|
|
D&D spell extractor. Selectable extractor keys are cataloged in
|
|
[Configuration](../config.md#implemented-production-modules).
|
|
|
|
## Identity
|
|
|
|
- Artifact kind: `dnd/spell-list`
|
|
- 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 durable JSON Schema is owned by the D&D spell artifact codec. The
|
|
extractor's private LLM response schema is a separate transport contract: its
|
|
source-reference objects omit `source_id`, which the extractor assigns while
|
|
mapping the response to the canonical artifact. The LLM DTO and transport
|
|
schema are not part of this durable contract.
|
|
|
|
The output contains canonical spell casts derived from transcript evidence.
|
|
Source IDs are assigned from the input identity; source-unit ranges identify
|
|
the evidence location.
|
|
|
|
## Output Shape
|
|
|
|
The extractor payload is a JSON object with one required top-level array. Its
|
|
structure is:
|
|
|
|
```text
|
|
{"spell_casts": [<spell-cast object>, ...]}
|
|
```
|
|
|
|
`spell_casts` must be present. It may be empty when no spell casts are found.
|
|
When multiple chunk results are combined, spell casts remain in chunk order.
|
|
When the payload is written as durable output, its logical path is derived from
|
|
the configured artifact lane ID as defined by the
|
|
[JSON output contract](json-output.md#output-payload-files).
|
|
|
|
## Spell-Cast Fields
|
|
|
|
Each spell cast contains exactly these required 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;
|
|
- `source_refs`: transcript source references with extractor-assigned source
|
|
IDs and evidence unit ranges. It must contain at least one entry.
|
|
|
|
All four string fields must be non-empty. `caster` is the in-world caster, not
|
|
the transcript speaker. Unknown fields are rejected.
|
|
|
|
## Source References
|
|
|
|
Each source reference contains exactly three required fields: `source_id`,
|
|
`start_unit_id`, and `end_unit_id`. The source ID must match the input identity.
|
|
The unit IDs must be positive integers present in the input, and the start unit
|
|
must not appear after the end unit. Unknown fields are rejected.
|
|
|
|
Reference slot keys and accepted file types are defined in
|
|
[Configuration](../config.md#implemented-production-modules). References are
|
|
supporting disambiguation material, 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.
|