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.

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

4.4 KiB Raw Blame History