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:

{
  "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:

{
  "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:

{
  "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.

3.9 KiB Raw Blame History