153 lines
3.9 KiB
Markdown
153 lines
3.9 KiB
Markdown
# D&D Spell-Cast Artifacts
|
|
|
|
This document is the durable artifact contract for approved
|
|
`dnd.spell_cast` artifacts produced by the implemented `dnd/spells` extractor.
|
|
|
|
## Artifact Identity
|
|
|
|
- Extractor 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 extractor requires source chunks and transcript source capability. It
|
|
returns generic artifact candidates that are serialized by the JSON output
|
|
module.
|
|
|
|
## Artifact Envelope
|
|
|
|
Approved artifacts use the generic artifact envelope documented in
|
|
[JSON Output](json-output.md#artifact-files):
|
|
|
|
```json
|
|
{
|
|
"extractor_key": "dnd/spells",
|
|
"artifact_type": "dnd.spell_cast",
|
|
"schema_version": "v1",
|
|
"payload": {
|
|
"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": "seg-001",
|
|
"end_unit_id": "seg-001"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Payload Fields
|
|
|
|
The `payload` object 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.
|
|
|
|
All payload fields are strings and must be non-empty after trimming.
|
|
|
|
`caster` is the in-world caster, not the transcript speaker.
|
|
|
|
## Source References
|
|
|
|
Source references live on the artifact envelope as `source_refs`; they are not
|
|
duplicated inside the `payload`.
|
|
|
|
Each source reference uses the generic source-reference shape:
|
|
|
|
- `source_id`
|
|
- `start_unit_id`
|
|
- `end_unit_id`
|
|
|
|
Validation requires:
|
|
|
|
- at least one source reference;
|
|
- non-empty source ID and unit IDs;
|
|
- source ID matching the source document ID;
|
|
- start and end unit IDs existing in the source document;
|
|
- start unit appearing before or at the same position as end unit.
|
|
|
|
## Structured LLM Response Shape
|
|
|
|
The extractor asks the LLM for this top-level response 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": "seg-001",
|
|
"end_unit_id": "seg-001"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`spell_casts` must be present. It may be empty when no spell casts are found.
|
|
|
|
The response schema asset is embedded at
|
|
`internal/modules/extract/dnd/spells/assets/schemas/dnd_spells.v1.json`.
|
|
|
|
## Validators
|
|
|
|
The extractor supplies two deterministic validators by default:
|
|
|
|
- `dnd/spells/shape`
|
|
- `dnd/spells/source_refs`
|
|
|
|
Rejection reason codes:
|
|
|
|
- `invalid_payload`: payload JSON cannot be decoded as a spell-cast payload.
|
|
- `missing_required_field`: `caster`, `spell`, `effect`, or
|
|
`narrative_description` is blank.
|
|
- `missing_source_ref`: candidate has no source references.
|
|
- `invalid_source_ref`: at least one source reference fails generic source
|
|
reference validation.
|
|
|
|
Rejected candidates are written to `rejected.json` by the JSON output module.
|
|
|
|
## 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.
|
|
|
|
## Compatibility Limit
|
|
|
|
This contract covers only `dnd.spell_cast` artifacts produced by the
|
|
implemented spell-cast extractor.
|