scriptorium/docs/config.md

# Configuration Reference

## Config Discovery And Precedence

Application settings are loaded in this order:

1. Built-in defaults
2. `config.yml` values
3. CLI overrides

When `--config` is not provided, Scriptorium searches for config files in this order:

1. `/usr/local/etc/scriptorium/config.yml`
2. `/etc/scriptorium/config.yml`

If neither file exists, Scriptorium continues with built-in defaults.

When `--config <path>` is provided, that file is required.

## Minimal App Config

```yaml
prompt_dir: ./prompts
profile_dir: ./profiles
```

This is enough to use `run` and `render` when prompt/profile files are valid.

## Production-Oriented App Config

```yaml
prompt_dir: /opt/scriptorium/prompts
profile_dir: /opt/scriptorium/profiles
schema_dir: /opt/scriptorium/schemas

server:
  addr: 127.0.0.1:8080

defaults:
  render_format: text
```

## App Config File (`config.yml`)

Top-level fields:

- `prompt_dir` (optional): default prompt definition directory.
- `profile_dir` (optional): default profile definition directory.
- `schema_dir` (optional): base directory for schema files used by `json_schema` validation.
- `server.addr` (optional): default listen address for `serve`.
- `defaults.render_format` (optional): default `render` output format (`text` or `json`).

Built-in defaults:

- `schema_dir`: `.`
- `server.addr`: `:8080`
- `defaults.render_format`: `text`

Validation behavior:

- Config decoding is strict; unknown YAML fields are rejected.
- Raw API key fields are not supported in `config.yml`.

## Prompt Definition Files

Prompt definitions are YAML files in `prompt_dir`.

Example:

```yaml
id: generic.structured_events
version: "1.0.0"
default_profile: local-quality
description: Produce structured event JSON from a transcript.

inputs:
  - name: transcript
    required: true
    content_type: text/markdown
    description: Source transcript content
  - name: glossary
    required: false
    content_type: text/yaml
    description: Optional glossary context

messages:
  - role: system
    content_file: ./generic.structured_events.system.md
  - role: user
    content_file: ./generic.structured_events.user.md

output:
  format: json
  validation_mode: json_schema
  schema_path: structured_events.schema.json
  repair_attempts: 0
```

Field reference:

- `id` (required): prompt identifier.
- `version` (required): prompt version.
- `default_profile` (optional): profile ID used when request does not provide `profile_id`.
- `description` (optional): prompt description.
- `inputs` (optional list): expected named inputs.
- `messages` (required list): prompt message templates.
- `output` (required object): output contract.

`inputs[]` fields:

- `name` (required)
- `required` (optional, boolean)
- `content_type` (optional metadata)
- `description` (optional)

`messages[]` fields:

- `role` (required)
- `content` or `content_file` (exactly one is required)

Message rules:

- Repeated roles are allowed.
- `content_file` is resolved relative to the prompt YAML file location.
- Prompt decoding is strict; unknown YAML fields are rejected.

`output` fields:

- `format` (required): `text`, `markdown`, or `json`.
- `validation_mode` (required): `none`, `basic`, `json`, or `json_schema`.
- `schema_path` (required when `validation_mode: json_schema`).
- `repair_attempts` (required): integer `>= 0`.

Repair behavior boundary:

- `repair_attempts` is part of the prompt contract.
- CLI and HTTP currently construct the runner without a repairer, so normal `run`/`serve` execution does not perform output repair attempts.

## Profile Definition Files

Execution profiles are YAML files in `profile_dir`.

Example:

```yaml
id: local-fast
endpoint: http://localhost:8000/v1
model: gpt-4o-mini
temperature: 0.2
max_tokens: 500
top_p: 1.0
timeout_seconds: 90
api_key_env: SCRIPTORIUM_API_KEY
```

Field reference:

- `id` (required)
- `endpoint` (required)
- `model` (required)
- `temperature` (optional): range `0..2`
- `max_tokens` (optional): `>= 0`
- `top_p` (optional): range `0..1`
- `timeout_seconds` (optional): `>= 0`
- `reasoning_effort` (optional)
- `api_key_env` (optional)
- `extra_params` (optional map of strings)

Profile rules:

- Profile decoding is strict; unknown YAML fields are rejected.
- Raw `api_key` is rejected; use `api_key_env`.
- If `api_key_env` is set, that environment variable must be set when preparing/running.

Current outbound request behavior:

- The OpenAI-compatible client currently serializes: `model`, `messages`, `temperature`, `max_tokens`, `top_p`, and optional `response_format` for `json_schema` prompts.
- `reasoning_effort` and `extra_params` are parsed and carried in effective settings, but are not currently serialized into outbound chat-completions requests.

## Schema Behavior

Schemas are JSON files, typically in `schema_dir`.

Rules:

- `output.validation_mode: json_schema` requires `output.schema_path`.
- Relative `schema_path` values resolve from `schema_dir`.
- Absolute `schema_path` values are used directly.
- Missing or invalid schema documents cause runtime validation errors.
- Invalid generated JSON causes validation status `failed` (not a runtime error).

Supported artifact reference types for request inputs are `file` and `inline`.

## Secrets Handling

- Keep secret values in environment variables.
- Store only environment-variable names in profile `api_key_env`.
- Do not put raw API keys in config, prompts, profiles, CLI flags, or HTTP request bodies.

## Maintained Examples

- App config: `examples/config.yml`
- Prompt examples: `prompts/`
- Profile examples: `profiles/`
- Schema examples: `schemas/`
- Input fixtures: `examples/fixtures/`
- Render example script: `examples/render-markdown-summary.sh`
- HTTP request example: `examples/http-run.json`

## Integration References

- Inbound HTTP contract: `docs/integrations/http-api.md`
- Outbound OpenAI-compatible contract: `docs/integrations/openai-compatible-chat.md`