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)

```bash
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 \
  --out ./out.md
```

This relies on `model_defaults.endpoint` and `model_defaults.model` in the selected profile.  
You can override either at runtime with `--llm-base-url` and/or `--model`.

For schema-validated JSON output:

```bash
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

```bash
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`

```bash
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`

`metadata` includes stable audit fields such as run/profile IDs, profile hash, effective model params, prompt/input hashes, timing, usage, and validation summary.

## 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. Ensure endpoint/model are available from either:
   - profile defaults (`model_defaults.endpoint`, `model_defaults.model`), or
   - request overrides (`--llm-base-url`, `--model`, or HTTP `model.endpoint`/`model.model`).
3. Use template helpers such as `{{input "transcript"}}` and template vars like `{{.session_date}}`.
4. For structured JSON output, set:
   - `output_format: json`
   - `validation.validation_mode: json_schema`
   - `validation.schema_path: <schema file>`
5. Place schema files in `schemas/` and pass `--schema-dir ./schemas` for CLI/serve.
6. `validation.repair_attempts` is bounded and applies only to structured modes (`json`, `json_schema`).

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