7.9 KiB
Consuming The Complete D&D Pipeline
This guide applies the subprocess workflow to the maintained complete D&D configuration. CLI Reference owns invocation and the native report; Configuration owns composition; Published JSON Output owns logical paths. Migration guidance covers older orchestrators.
Prepare The Deployment
Start from 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:
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. 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:
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. 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. 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 |
npc-registry |
Canonical registry of named NPCs. | NPC registry |
location-registry |
Canonical registry of named locations. | Location registry |
scene-descriptions |
Classification, title, and summary for each scene. | Scene descriptions |
item-occurrences |
Source-grounded item discovery, acquisition, use, transfer, and loss events. | Item occurrences |
spells |
Source-grounded spell casts and casters. | Spell casts |
combat-turns |
Source-grounded combat turn participation. | Combat turns |
npc-occurrences |
Source-grounded NPC interaction occurrences. | NPC occurrences |
location-occurrences |
Source-grounded location occurrences. | Location occurrences |
enemy-events |
Source-grounded enemy combat events. | Enemy events |
The complete configuration also selects two pipeline-wide files:
chunk-map.json, the materialized plan/chunks.evidence-context.json, 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. 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.