Files
notarius/docs/consumers/dnd-pipeline.md

143 lines
7.9 KiB
Markdown

# Consuming The Complete D&D Pipeline
This guide applies the [subprocess workflow](subprocess.md) to the maintained
complete D&D configuration. [CLI Reference](../cli.md) owns invocation and the
native report; [Configuration](../config.md) owns composition;
[Published JSON Output](../integrations/json-output.md) owns logical paths.
[Migration guidance](native-migration.md) covers older orchestrators.
## Prepare The Deployment
Start from [examples/dnd-complete/config.yml](../../examples/dnd-complete/config.yml).
Preserve its imported pipeline fragments, native companion, and reference files,
or update the paths deliberately. It uses every implemented D&D family, ordered
generated handoffs, and selected chunk-map/evidence output.
Native embedded defaults and the maintained companion already provide profile/
backend definitions. A deployment can supply variants rather than being required
to recreate them. YAML paths retain the contributing declaration's origin;
CLI reference paths use the process working directory. Absolute caller paths
are useful for services. Keep credentials in the intended environment, not
files, arguments, sessions, or logs.
Preflight without credentials or inference:
~~~sh
notarius config validate --config /absolute/path/to/notarius.yml
notarius pipeline validate dnd-session --config /absolute/path/to/notarius.yml
~~~
## Supply The Transcript And References
Use the [Seriatim JSON contract](../integrations/seriatim.md). Preserve segment
IDs because artifact citations use those source-unit ranges. If the caller
maintains a final trimmed transcript tier, select that same session content
consistently for later consumers.
Run with explicit input/output and pipeline-level references:
~~~sh
notarius run dnd-session \
--config /absolute/path/to/notarius.yml \
--input-file /absolute/path/to/transcripts/final.trimmed.json \
--output-dir /absolute/path/to/notarius-output \
--reference party=/absolute/path/to/references/party.txt \
--reference players=/absolute/path/to/references/players.txt \
--reference glossary=/absolute/path/to/references/glossary.txt \
--reference spell_catalog=/absolute/path/to/references/spells.json \
--format json
~~~
Only supply optional references the deployment maintains. Unqualified selectors
reach every selected target declaring the slot; narrower overrides follow the
[selector contract](../cli.md#reference-selectors). Generated registry, scene,
combat, and NPC-occurrence handoffs stay in pipeline configuration, not CLI file
bindings.
The ordinary input-based session is suitable without an override. Use
`--llm-session-id` only to intentionally change its native selection.
Sessions correlate provider routing; they are not credential or output identities.
Capture stdout/stderr separately, propagate cancellation, impose an appropriate
caller deadline, and wait for completion. Parse a successful report only after
status zero; failed writes can leave partial stdout. Nonzero status after
publication can still leave valid artifacts for deliberate recovery.
## Locate And Read Artifacts
Use the report's absolute `output_directory`, not a newest-directory scan.
The report's exact fields and fallback qualification belong in
[CLI Reference](../cli.md#completion-report). There is no receipt schema,
index/manifest traversal, or descriptor inventory to load.
The complete configuration uses safe literal lane IDs: each table entry below
is at `lanes/<lane-id>.json` beneath that run directory. Decode the configured
domain contract directly. All ten lane artifacts plus the two enabled/available
auxiliaries give twelve deliverables; a count is not a substitute for checking
the files required by the caller.
## Complete Artifact Inventory
| Lane ID | Purpose | Canonical contract |
| --- | --- | --- |
| `item-registry` | Canonical registry of encountered items and currency. | [Item registry](../integrations/dnd-item-registry-artifacts.md) |
| `npc-registry` | Canonical registry of named NPCs. | [NPC registry](../integrations/dnd-npc-registry-artifacts.md) |
| `location-registry` | Canonical registry of named locations. | [Location registry](../integrations/dnd-location-registry-artifacts.md) |
| `scene-descriptions` | Classification, title, and summary for each scene. | [Scene descriptions](../integrations/dnd-scene-description-artifacts.md) |
| `item-occurrences` | Source-grounded item discovery, acquisition, use, transfer, and loss events. | [Item occurrences](../integrations/dnd-item-occurrence-artifacts.md) |
| `spells` | Source-grounded spell casts and casters. | [Spell casts](../integrations/dnd-spell-artifacts.md) |
| `combat-turns` | Source-grounded combat turn participation. | [Combat turns](../integrations/dnd-combat-turn-artifacts.md) |
| `npc-occurrences` | Source-grounded NPC interaction occurrences. | [NPC occurrences](../integrations/dnd-npc-occurrence-artifacts.md) |
| `location-occurrences` | Source-grounded location occurrences. | [Location occurrences](../integrations/dnd-location-occurrence-artifacts.md) |
| `enemy-events` | Source-grounded enemy combat events. | [Enemy events](../integrations/dnd-enemy-event-artifacts.md) |
The complete configuration also selects two pipeline-wide files:
- [`chunk-map.json`](../integrations/chunk-map.md), the materialized plan/chunks.
- [`evidence-context.json`](../integrations/evidence-context.md), the union of
selected cited units and their configured surrounding window.
They are not lanes and need no discovery descriptor. Their intrinsic payload
schemas are unchanged. Evidence is reading context, not authoritative lane
attribution; surrounding units do not widen citations in lane artifacts.
No index, manifest, rejection/warning/diagnostic sidecars are required.
## Decide Consumer Acceptance
Process completion does not establish the caller's required artifact set,
semantic quality, or fresh validation under changed policy. A complete-workflow
caller should check all ten required lane files against their contracts. A
subset consumer can choose a narrower set deliberately. Empty valid domain
collections remain distinguishable from missing/incompatible files.
Explicit permissive execution can complete with qualified fallback. Decide
whether to accept that and inspect positive `fallback_count` when relevant.
The count identifies emitting operations, not individual affected lanes.
Fallbacks satisfy intrinsic/downstream invariants but not ordinary semantic
approval; valid downstream results affected by them also avoid cache reuse.
Default cache reuse does not repeat semantic assessment. For a deliberate model/
policy experiment requiring fresh inference, select bypass/refresh under
[configuration controls](../config.md#producer-controls). Do not look for retired
validation ledgers or treat optional debug serialization as an API.
Retain useful domain files and caller-owned invocation/report evidence. Capture
failure after publication does not invalidate completed artifact writes, but
requires deliberate caller recovery rather than parsing partial success output.
A failed publication can leave an incomplete directory. Transcript-derived
artifacts, evidence, cache, debug, and streams can contain private campaign data;
apply the caller's sharing and retention choices.
## Consumer Checklist
- Validate application configuration and the selected pipeline offline.
- Preserve Seriatim source-unit IDs.
- Pass source, output root, and optional campaign references as first-class inputs.
- Keep generated handoffs configured; avoid external/generated collisions.
- Separate streams, propagate cancellation, and check status before parsing.
- Use the native report directory and configured domain/auxiliary paths.
- Decode supported payload contracts and check the caller's explicit required set.
- Decide whether qualified fallback and cached acceptance meet caller needs.
- Retain only the artifact/report/evidence records useful to the caller.
- Treat source-derived data as sensitive; do not rely on a sanitized debug bundle.