narratio/README.md

# narratio

`narratio` is a Go orchestration application for processing D&D session audio into transcripts and generated artifacts.

## Current Implementation

Implemented now:

- strict config loading/validation (`pipeline.yml` and `session.yml`)
- local workspace/session layout, locking, and manifest persistence
- resumable stage control (`run`, `plan`, `resume`, `run-stage`, `status`)
- real `prepare`, `transcribe`, `merge`, and `polish` stages
- real WhisperX, Seriatim, and Audita adapters
- real Scriptorium subprocess adapter
- real `analyze` stage for `session_recap`
- optional Scriptorium render diagnostics (`render_debug`)

Not implemented yet:

- real `trim` behavior
- real `archive` behavior
- real `notify` behavior
- additional analyze artifacts beyond `session_recap`
- generic DAG orchestration

## Config Files

Narratio expects two YAML files:

- `pipeline.yml`: pipeline/workspace settings
- `session.yml`: per-session settings

YAML decoding is strict (`KnownFields(true)`), so unknown fields fail fast.

## Trim Configuration (Scaffold)

`pipeline.trim` is optional. If omitted, no trim config is loaded. If `trim.enabled` is omitted, it defaults to `false`.

When `trim.enabled: true`:

- `trim.output_path` is required
- `trim.bounds.prompt_id` is required
- `trim.bounds.transcript_input_name` is required
- `trim.bounds.output_path` is required
- `trim.bounds.timeout` must be a valid Go duration when provided
- `trim.bounds.render_debug: true` requires `trim.bounds.render_output_path`
- `trim.bounds.profile_id` may be empty to use the prompt default profile

Trim paths are treated as session-workdir-relative when not absolute.

Example trim scaffold config:

```yaml
trim:
  enabled: true
  output_path: "transcripts/trimmed.json"
  bounds:
    prompt_id: "dnd_session.bounds"
    profile_id: ""
    transcript_input_name: "transcript"
    output_path: "artifacts/session_bounds.json"
    timeout: "10m"
    render_debug: false
    render_output_path: "artifacts/session_bounds.render.json"
  seriatim:
    report: false
```

## Scriptorium Configuration

`pipeline.scriptorium` is optional. When present, Narratio validates and uses it for analyze-stage artifact generation.

Key points:

- `scriptorium.binary` is required when section is present
- `scriptorium.config_path` is optional
- `scriptorium.timeout` defaults to `10m` when omitted
- `scriptorium.render_debug` enables render diagnostics globally
- artifacts are configured under `scriptorium.artifacts` (map shape supports multiple artifacts)
- enabled artifacts require `prompt_id` and `output_path`
- artifact `render_debug` may override global render setting
- `vars` currently support boolean and string values

Example `session_recap` artifact definition:

```yaml
scriptorium:
  binary: "scriptorium"
  config_path: "/etc/scriptorium/config.yml"
  timeout: "10m"
  render_debug: false

  artifacts:
    session_recap:
      enabled: true
      prompt_id: "dnd.session_recap"
      profile_id: "local-quality" # optional
      output_path: "artifacts/session_recap.md"
      timeout: "10m"
      # render_debug: true # optional per-artifact override

      inputs:
        transcript:
          source: "trimmed_transcript"
          required: true

        previous_recap:
          source: "previous_session_artifact"
          artifact: "session_recap"
          path: "" # optional; set when available
          required: false

      vars:
        session_id: true
        session_date: true
        campaign_name: true
        previous_session_id: true
        output_kind: "session_recap"
```

Prompt IDs and profile IDs are configuration values. They are not hardcoded in analyze-stage logic.

Do not put secrets in `pipeline.yml`. If API-key behavior is configured, use env var names only.

## Scriptorium Runtime Behavior

Narratio integrates with Scriptorium through the public CLI subprocess contract:

- generation: `scriptorium run`
- diagnostics/testing: `scriptorium render --format json` when `render_debug` is enabled

For the initial implementation, only `session_recap` generation is supported.

Analyze-stage session recap behavior:

- defaults to trimmed transcript input (`transcripts/trimmed.json`) when configured with `source: trimmed_transcript`
- still supports full polished transcript input (`transcripts/processed.json`) when configured with `source: processed_transcript`
- optionally includes `previous_recap` when configured and resolvable
- omits optional previous recap when unavailable
- fails if required inputs are missing
- validates output file exists and is non-empty

Expected session output paths:

- `artifacts/session_recap.md`
- `logs/scriptorium.session_recap.stdout.log`
- `logs/scriptorium.session_recap.stderr.log`
- `config/scriptorium.session_recap.generated.yml`
- `artifacts/session_recap.render.json` when render diagnostics are enabled

## Examples

Starter files:

- `examples/pipeline.minimal.yml`
- `examples/session.minimal.yml`
- `examples/speakers.yml`

## Commands

Run tests:

```bash
go test ./...
```

Plan a run:

```bash
go run ./cmd/narratio plan --config examples/pipeline.minimal.yml --session examples/session.minimal.yml
```

Run full pipeline:

```bash
go run ./cmd/narratio run --config examples/pipeline.minimal.yml --session examples/session.minimal.yml
```

Run analyze only:

```bash
go run ./cmd/narratio run-stage --config examples/pipeline.minimal.yml --session examples/session.minimal.yml analyze
```

## Roadmap

Near-term roadmap:

- extend analyze to additional configured artifacts
- support workflows where later artifacts consume earlier generated artifacts
- keep orchestration explicit without a generic DAG engine
- implement archive and notify backends