# rakestraw.dnd_pipeline

Installs the D&D transcript-processing application suite by composing the
standalone Seriatim, Audita, Notarius, Scriptorium, and Narratio roles. It
supports Ubuntu 26.04 and Ansible Core 2.18 or newer. Downstream roles perform
their own task-level privilege escalation, so a play does not need `become`.
Supported host architectures are `amd64` and `arm64`.

## Installation

Install the role dependencies and their collection before applying this role:

```sh
ansible-galaxy role install -r requirements.yml
ansible-galaxy collection install -r collections/requirements.yml
```

The dependency manifest installs the roles under their canonical names:
`rakestraw.seriatim`, `rakestraw.audita`, `rakestraw.notarius`,
`rakestraw.scriptorium`, and `rakestraw.narratio`. This standalone role is
named `rakestraw.dnd_pipeline`; a later collection release will expose it as
`rakestraw.dnd.pipeline`.

```yaml
---
- name: Install the D&D pipeline foundation
  hosts: pipeline_hosts
  gather_facts: true
  roles:
    - role: rakestraw.dnd_pipeline
      vars:
        dnd_pipeline_whisperx_transcribe_url: https://whisperx.example/transcribe
```

## Variables

`dnd_pipeline_whisperx_transcribe_url` is required and is passed to Narratio.
The compatible application versions are selected through these variables:

| Variable | Default |
| --- | --- |
| `dnd_pipeline_audita_version` | `v0.9.1` |
| `dnd_pipeline_narratio_version` | `v2.0.0` |
| `dnd_pipeline_notarius_version` | `v0.6.0` |
| `dnd_pipeline_seriatim_version` | `v1.5.0` |
| `dnd_pipeline_scriptorium_version` | `v0.13.0` |
| `dnd_pipeline_manage_build_dependencies` | `true` |
| `dnd_pipeline_go_snap_channel` | `1.26/stable` |
| `dnd_pipeline_go_binary` | `/snap/bin/go` |
| `dnd_pipeline_campaigns_repository_url` | `https://gitea.maximumdirect.net/eric/campaigns.git` |
| `dnd_pipeline_campaigns_revision` | `main` |
| `dnd_pipeline_campaigns_root` | `/usr/local/share/narratio/campaigns` |
| `dnd_pipeline_prompt_library_repository_url` | `https://gitea.maximumdirect.net/eric/narratio-prompts.git` |
| `dnd_pipeline_prompt_library_revision` | `main` |
| `dnd_pipeline_prompt_library_root` | `/usr/local/share/narratio/prompt-library` |

The common dependency-management switch controls whether every application
role installs Git and Go. Callers that disable it must provide both Git and Go.
The Go channel and executable are likewise passed to all five roles. Advanced
callers may supply unmapped standalone-role variables directly through normal
Ansible variable precedence.

Narratio receives the standard Seriatim, Audita, Notarius, and Scriptorium
binary and configuration paths managed by the composed roles. Notarius is
installed but remains disabled in Narratio until a later feature supplies a
Notarius pipeline.

The role deploys the campaign repository directly at the campaign root and
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.

### 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

`tests/integration` installs the pinned Git dependencies and collection into
private temporary paths, runs syntax and production-profile lint checks, then
applies the suite with a local syntactically valid WhisperX URL and explicit
immutable `file://` asset inputs. It uses native application
smoke/configuration commands, validates Narratio's assembled configuration and
campaign discovery as the Narratio account, and inspects deployed Scriptorium
prompts and a schema path. It requires a clean repeat, then selects Seriatim
`v1.4.0` through the suite interface and requires a clean repeat of that
selection. Cleanup reapplies the asset-enabled baseline suite and removes only
the driver's private temporary directory.