143 lines
7.9 KiB
Markdown
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.
|