scriptorium/README.md

scriptorium

Scriptorium is a generic prompt-profile execution engine written in Go.

It loads a prompt profile, resolves named input artifacts, renders a prompt, calls an OpenAI-compatible LLM endpoint, validates output, and returns an artifact plus metadata.

Relationship to Narratio

In the broader workflow, Narratio handles pipeline orchestration (transcription, cleanup, storage, notifications). Scriptorium handles only prompt-profile execution for a single run.

Repository Example Assets

• Profiles: profiles/
• Schemas: schemas/
• Tiny fixtures: examples/fixtures/

Included profiles:

• generic.markdown_summary
• dnd.session_recap (example content only; no D&D-specific Go logic)
• generic.structured_events (JSON + JSON Schema validation)

Run a Local Profile (CLI)

go run ./cmd/scriptorium run \
  --profile-dir ./profiles \
  --profile-id generic.markdown_summary \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml \
  --llm-base-url http://localhost:8000/v1 \
  --model gpt-4o-mini \
  --out ./out.md

For schema-validated JSON output:

go run ./cmd/scriptorium run \
  --profile-dir ./profiles \
  --profile-id generic.structured_events \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml \
  --llm-base-url http://localhost:8000/v1 \
  --model gpt-4o-mini \
  --schema-dir ./schemas \
  --out ./events.json

Start Local HTTP API

go run ./cmd/scriptorium serve \
  --addr :8080 \
  --profile-dir ./profiles \
  --schema-dir ./schemas \
  --llm-base-url http://localhost:8000/v1 \
  --model gpt-4o-mini

Call POST /v1/runs

curl -sS http://localhost:8080/v1/runs \
  -H 'Content-Type: application/json' \
  -d '{
    "profile_id": "generic.structured_events",
    "inputs": {
      "transcript": {"type": "file", "uri": "./examples/fixtures/transcript.md"},
      "glossary": {"type": "file", "uri": "./examples/fixtures/glossary.yml"}
    },
    "model": {"model": "gpt-4o-mini"}
  }'

Response shape:

• artifact
• validation
• metadata
• raw_model_output

Add a New Prompt Profile

1. Add a YAML file under profiles/ with:
   • id, version, expected_inputs, templates, model_defaults, output_format, validation
   • optional model timeout via model_defaults.timeout_seconds (per-run LLM timeout override)
2. Use template helpers such as {{input "transcript"}}.
3. For structured JSON output, set:
   • output_format: json
   • validation.validation_mode: json_schema
   • validation.schema_path: <schema file>
4. Place schema files in schemas/ and pass --schema-dir ./schemas for CLI/serve.

Validation Behavior

Validation modes currently implemented:

• none
• basic (non-empty output)
• json (must parse as JSON)
• json_schema (must parse JSON and satisfy schema)

Important behavior:

• Validation content failures are returned as structured run results (validation.status = failed) and preserve raw_model_output.
• Validation runtime/configuration failures are treated as run errors.