149 lines
6.1 KiB
Markdown
149 lines
6.1 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.
|
|
During extraction, every range must be wholly contained in the current accepted
|
|
chunk. This prevents a candidate from citing valid units that were not presented
|
|
to that extraction call.
|
|
Unknown fields are rejected.
|
|
|
|
## Interaction Categories
|
|
|
|
`kind` is exactly one of:
|
|
|
|
| Kind | Meaning |
|
|
| --- | --- |
|
|
| `mentioned` | The NPC is referred to, but is not established as present or communicating in the evidenced passage. |
|
|
| `noncombat_presence` | The NPC is present and relevant to the passage but does not meaningfully participate in dialogue or combat. |
|
|
| `dialogue` | The NPC speaks, responds, or is directly engaged in a meaningful non-combat exchange. |
|
|
| `combat_ally` | The NPC actively participates in combat on the party's side. |
|
|
| `combat_opponent` | The NPC actively participates in combat against the party. |
|
|
| `other` | The transcript clearly establishes a direct NPC occurrence that fits none of the preceding kinds. |
|
|
|
|
`other` is a residual category for positively evidenced activity, not a fallback
|
|
for uncertain classification. When activities overlap, active combat
|
|
participation outranks dialogue, presence, and mention; dialogue outranks
|
|
non-combat presence and mention; and non-combat presence outranks mention.
|
|
Combat alignment is not resolved by precedence: a meaningful change between
|
|
ally and opponent creates separate occurrences.
|
|
|
|
These categories do not encode summaries, relationships, state, motives, or
|
|
unobserved events.
|
|
|
|
## Occurrence Boundaries And Ordering
|
|
|
|
One occurrence represents one NPC, one kind, and one locally coherent passage
|
|
within one accepted chunk. Repeated evidence belongs to the same occurrence
|
|
only while it supports the same uninterrupted activity. A kind change, combat
|
|
alignment change, intervening scene or meaningful absence, or transition from
|
|
mention to presence starts a new occurrence. Occurrences never span chunks, and
|
|
merge or normalization never semantically combines nearby, overlapping, or
|
|
cross-chunk records.
|
|
|
|
Normalization orders records by:
|
|
|
|
1. earliest valid source-document position;
|
|
2. the NPC identity comparison key;
|
|
3. the exact canonical NPC display name;
|
|
4. interaction kind in lexical order; and
|
|
5. the complete canonical source-reference sequence, ordered by source ID and
|
|
the source-document positions of each range's start and end.
|
|
|
|
Only records with identical canonical names, kinds, and complete valid evidence
|
|
sequences are duplicates. Different categories, ranges, or separately grounded
|
|
occurrences remain separate.
|
|
|
|
## 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 canonicalizes source references
|
|
and applies the ordering and exact-duplicate rules above.
|
|
|
|
## 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 runs normalized invariants after
|
|
registry validation and before source-reference and schema validation, followed
|
|
by relatedness. Normalizer and relatedness warnings are bounded and end with an
|
|
omission summary when necessary. 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
|
|
[complete D&D example](../../examples/dnd-complete.config.yml).
|