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

143 lines
7.9 KiB
Markdown
Raw Normal View History

2026-08-09 20:57:28 +00:00
# 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
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
Preflight without credentials or inference:
2026-08-09 20:57:28 +00:00
~~~sh
notarius config validate --config /absolute/path/to/notarius.yml
notarius pipeline validate dnd-session --config /absolute/path/to/notarius.yml
~~~
2026-08-09 20:57:28 +00:00
## Supply The Transcript And References
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
Run with explicit input/output and pipeline-level references:
2026-08-09 20:57:28 +00:00
~~~sh
2026-08-09 20:57:28 +00:00
notarius run dnd-session \
--config /absolute/path/to/notarius.yml \
--input-file /absolute/path/to/transcripts/final.trimmed.json \
2026-08-09 20:57:28 +00:00
--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
~~~
2026-08-09 20:57:28 +00:00
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
2026-08-09 20:57:28 +00:00
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
2026-08-09 20:57:28 +00:00
| 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:
2026-08-09 20:57:28 +00:00
- [`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.
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
## Decide Consumer Acceptance
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
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.
2026-08-09 20:57:28 +00:00
## 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.