116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# D&D NPC Interaction Artifact
|
|
|
|
This document defines the durable D&D NPC-interaction-list artifact and its
|
|
two-step production pipeline. It records discrete, source-grounded occurrences
|
|
for NPCs already accepted into a normalized NPC registry; it does not expand
|
|
the registry or summarize events.
|
|
|
|
## Identity And JSON
|
|
|
|
- Artifact kind: `dnd/npc-interaction-list`
|
|
- Durable schema ID: `notarius.dnd.npc_interactions`
|
|
- Durable schema name: `notarius_dnd_npc_interactions_v1`
|
|
- Durable schema version: `v1`
|
|
- Media type: `application/json`
|
|
|
|
The payload is one strict JSON object with only an `interactions` array. The
|
|
array may be empty. Each item has exactly `name`, `kind`, and `source_refs`:
|
|
|
|
```json
|
|
{
|
|
"interactions": [
|
|
{
|
|
"name": "Mira Thorn",
|
|
"kind": "dialogue",
|
|
"source_refs": [
|
|
{"source_id": "session-7", "start_unit_id": 12, "end_unit_id": 13}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`name` is the canonical display name from the required NPC registry.
|
|
`source_refs` contains one or more current-source ranges with required
|
|
`source_id`, `start_unit_id`, and `end_unit_id`; unit IDs are positive integers.
|
|
Unknown fields are rejected.
|
|
|
|
## Interaction Categories
|
|
|
|
`kind` is exactly one of:
|
|
|
|
- `mentioned`: the named NPC is referenced without stronger participation.
|
|
- `noncombat_presence`: the NPC is present in the current scene without a
|
|
dialogue or combat classification.
|
|
- `dialogue`: the NPC participates in spoken interaction.
|
|
- `combat_ally`: the NPC participates in combat aligned with the party.
|
|
- `combat_opponent`: the NPC participates in combat against the party.
|
|
- `other`: a transcript-supported interaction outside the bounded categories.
|
|
|
|
These categories do not encode summaries, relationships, state, motives, or
|
|
unobserved events.
|
|
|
|
## Evidence, Registry, And Normalization
|
|
|
|
The registry proves only the canonical NPC identity. Its source references are
|
|
registry provenance and are never interaction evidence. Every durable
|
|
interaction must cite current transcript units supporting both the name and its
|
|
classification.
|
|
|
|
The extractor receives a names-only registry projection such as
|
|
`{"npcs":[{"name":"Mira Thorn"}]}`. The normalizer uses the full immutable
|
|
registry for exact canonical-name lookup. It orders source references,
|
|
stable-sorts occurrences by their earliest source-document position, and
|
|
collapses only exact duplicates with the same canonical name, kind, and complete
|
|
valid evidence. Different categories, distinct ranges, and separately grounded
|
|
occurrences remain separate; no semantic merge is performed.
|
|
|
|
## Production Pipeline
|
|
|
|
The extractor and normalizer key is `dnd/npc-interactions`. Both require the
|
|
structured `npcs` slot, so an accepted normalized registry must come from an
|
|
earlier step:
|
|
|
|
```yaml
|
|
pipelines:
|
|
dnd-npc-interactions:
|
|
input: seriatim
|
|
steps:
|
|
- id: identify-npcs
|
|
artifacts:
|
|
npcs:
|
|
extract: dnd/npcs
|
|
normalize: dnd/npcs
|
|
- id: extract-interactions
|
|
references:
|
|
npcs:
|
|
artifact:
|
|
step: identify-npcs
|
|
lane: npcs
|
|
artifacts:
|
|
interactions:
|
|
extract: dnd/npc-interactions
|
|
normalize: dnd/npc-interactions
|
|
```
|
|
|
|
The framework passes only the accepted normalized producer. A missing, rejected,
|
|
or incompatible NPC artifact prevents the consumer step from executing. It
|
|
records generated artifact identity and bounded producer provenance without
|
|
copying registry names, source ranges, or payload content into the manifest.
|
|
|
|
## Validation And Metadata
|
|
|
|
The default extract chain is `generic/valid_json`, interaction shape, registry,
|
|
and source-reference validation, `generic/valid_json_schema`, then warning-only
|
|
source relatedness. The normalize chain adds normalized invariants after schema
|
|
validation and before relatedness. The codec metadata contains only
|
|
`interaction_count`. Extractor metadata identifies its prompt and private
|
|
response schema; component-local checkpoint identities include the names-only
|
|
registry projection where relevant. Generated registry identity stays in
|
|
framework provenance and dependency fingerprints.
|
|
|
|
See [Configuration](../config.md#implemented-production-modules) for selectable
|
|
keys and chains, [the NPC artifact contract](dnd-npc-artifacts.md) for the
|
|
registry boundary, and the copyable
|
|
[maintained example](../../examples/dnd-npc-interactions.config.yml).
|