104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# 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 \
|
|
--llm-base-url http://localhost:8000/v1 \
|
|
--model gpt-4o-mini \
|
|
--out ./out.md
|
|
```
|
|
|
|
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`
|
|
|
|
## 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.
|