From e99983be137c111604e95dd075b2ec49f0c0f830 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 11 Sep 2026 02:45:18 +0000 Subject: [PATCH] Document D&D processing profiles and artifacts --- README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c3828db..1b53933 100644 --- a/README.md +++ b/README.md @@ -70,8 +70,120 @@ the prompt library directly at the prompt-library root. By default both follow their `main` branches; callers can select an immutable commit, tag, or another branch through the revision variables. Narratio receives the deployed campaign root, while Scriptorium receives its `prompts/` and `schemas/` children. -Execution profiles, model backends, credentials, and D&D processing policy -remain deferred. + +### D&D processing policy + +The variables below are deliberate D&D suite policy, not a copy of application +defaults. They remain ordinary inventory variables, so callers can replace a +chosen policy value when their deployment requires it. + +| Variable group | Default policy | +| --- | --- | +| `dnd_pipeline_audita_pipeline_modules` | `glossary`, `homophones`, `glossary`, `spoken_word`, `grammar` | +| `dnd_pipeline_audita_output_schema` | `audita-v1` | +| `dnd_pipeline_audita_llm_proposal_*` | `https://inference.ai.rakestrawhome.com/v1`, `google/gemma-4-31b-it`, `AUDITA_LLM_API_KEY`, `900s`, `3` | +| `dnd_pipeline_audita_llm_validation_*` | `https://inference.ai.rakestrawhome.com/v1`, `google/gemma-4-31b-it`, `AUDITA_VALIDATION_LLM_API_KEY`, `900s`, `3` | +| `dnd_pipeline_audita_concurrency_*` | total, proposal, and validation concurrency of `4` | +| `dnd_pipeline_audita_chunking_*` | `8` target sections, `6144` maximum and `2048` minimum section tokens | +| `dnd_pipeline_audita_normalization_*` | `3s` maximum and ellipsis gaps, `240s` maximum duration, `2048` maximum tokens | +| `dnd_pipeline_audita_thresholds_*` | `0.8` for glossary, homophones, spoken word, and grammar | +| `dnd_pipeline_audita_context_description` | D&D-game transcript context, including possible pre- and post-session banter | +| `dnd_pipeline_audita_diagnostics_*` | `/tmp/audita`, retained automatically | + +The API-key values themselves are never managed by this role. The two +environment-variable names above are configuration only. Audita owns its +endpoint, model, tuning, and diagnostics configuration; Narratio receives its +managed Audita configuration path and supplies the run-specific output path. + +| Variable | Default | +| --- | --- | +| `dnd_pipeline_narratio_seriatim_output_schema` | `seriatim-intermediate` | +| `dnd_pipeline_narratio_normalize_output_path` | `transcripts/final.json` | +| `dnd_pipeline_narratio_normalize_output_schema` | `seriatim-intermediate` | +| `dnd_pipeline_narratio_trim_enabled` | `true` | +| `dnd_pipeline_narratio_trim_output_path` | `transcripts/final.trimmed.json` | +| `dnd_pipeline_narratio_trim_bounds_prompt_id` | `dnd.session_bounds` | +| `dnd_pipeline_narratio_trim_bounds_transcript_input_name` | `transcript` | +| `dnd_pipeline_narratio_trim_bounds_output_path` | `artifacts/session_bounds.json` | +| `dnd_pipeline_narratio_render_enabled` | `true` | +| `dnd_pipeline_narratio_render_format` | `markdown` | +| `dnd_pipeline_narratio_testing_scriptorium_profile` | `gemini-flash-latest` | + +`dnd_pipeline_audita_output_schema` is also the Narratio Audita-adapter schema; +it is the shared cross-application boundary. Other Narratio-local controls, +including reports, timeouts, debug rendering, presentation, and bounds prompt +profile selection, remain Narratio defaults. + +### Artifacts and profiles + +The role owns these complete native mapping variables. Replacing one mapping +changes that source's configuration as a whole; it does not change the fixed +file name, import, or source key. Set `enabled: false` to retain an available +source while excluding it from normal analysis. + +| Variable | Fixed source | Default state | Output | +| --- | --- | --- | --- | +| `dnd_pipeline_narratio_session_recap_artifact` | `session_recap` | enabled | `artifacts/session_recap.md` | +| `dnd_pipeline_narratio_hostile_rumors_artifact` | `hostile_rumors` | enabled | `artifacts/hostile_rumors.md` | +| `dnd_pipeline_narratio_deranged_rumors_artifact` | `deranged_rumors` | enabled | `artifacts/deranged_rumors.md` | +| `dnd_pipeline_narratio_scene_map_artifact` | `scene_map` | disabled | `artifacts/scene_map.json` | +| `dnd_pipeline_narratio_character_analysis_family` | `character_meta_analysis` | disabled | `artifacts/character_meta_analysis/{character_id}.md` | + +The character-analysis family expands over campaign `party.characters` and +passes each member's name and class summary to its prompt. Recap and both rumor +sources are enabled; the rumor input derives its recap dependency without a +redundant explicit ordering edge. Production artifacts inherit each prompt's +declared profile. + +Narratio's root file remains owned by the standalone role. It imports the +suite-owned base fragments in this fixed order: + +```text +/usr/local/etc/narratio/ +├── pipeline.yml +├── conf.d/processing.yml +├── artifacts/session-recap.yml +├── artifacts/hostile-rumors.yml +├── artifacts/deranged-rumors.yml +├── artifacts/scene-map.yml +├── artifact-families/character-meta-analysis.yml +└── profiles/testing.yml +``` + +The `testing` profile is an overlay, not a second configuration tree. It only +sets the Scriptorium `profile_id` for the four artifact sources and the one +family. Its default, `gemini-flash-latest`, is an inexpensive development +choice, not a compatibility guarantee. Replace it through inventory when a +different testing profile is appropriate: + +```yaml +dnd_pipeline_narratio_testing_scriptorium_profile: endpoint-profile +``` + +### Inspecting configuration + +The following native Narratio commands resolve configuration without running +transcription or requesting a model provider. Select a deployed campaign for +the party-driven character family: + +```sh +sudo -u narratio narratio config validate \ + --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs +sudo -u narratio narratio config validate \ + --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs --profile testing +sudo -u narratio narratio config artifacts \ + --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs +sudo -u narratio narratio config diff default testing \ + --config /usr/local/etc/narratio/pipeline.yml --campaign centaurs +``` + +The first two commands validate production and testing resolution. Artifact +inspection shows enabled sources, inferred dependencies, and generated family +members; the diff shows the overlay's profile selections without modifying +managed files. + +API keys, Notarius enablement, storage and publishing, operator access, +scheduling, and end-to-end external execution remain deferred. ## Validation