Add integration and artifact contract documentation

2026-07-04 03:11:29 +00:00
parent 6ceabf40bb
commit 30e98a4d99
7 changed files with 517 additions and 147 deletions
--- a/docs/integrations/dnd-spell-artifacts.md
+++ b/docs/integrations/dnd-spell-artifacts.md
@@ -0,0 +1,152 @@
+# 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.