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:

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:

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: "processed_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:

• uses processed transcript input (transcripts/processed.json)
• 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:

go test ./...

Plan a run:

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

Run full pipeline:

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

Run analyze only:

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