265 lines
8.6 KiB
Markdown
265 lines
8.6 KiB
Markdown
# 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: ./examples/prompts
|
|
profile_dir: ./examples/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 anywhere under `prompt_dir`, including nested subdirectories.
|
|
|
|
Subdirectories are organizational only. Callers still select prompts by the YAML `id`, not by file path. For example, `prompts/dnd/recap.yaml` may still declare `id: dnd.recap`, and callers use `--prompt dnd.recap`.
|
|
|
|
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.
|
|
- `session_id` (optional): Go-template string for OpenRouter sticky-routing `session_id`; rendered from request vars.
|
|
- `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)
|
|
- `cache_control` (optional object): provider prompt-cache metadata for this message
|
|
|
|
Message rules:
|
|
|
|
- Repeated roles are allowed.
|
|
- `content_file` is resolved relative to the prompt YAML file location.
|
|
- Nested prompt files keep the same relative `content_file` behavior; `./recap.user.md` next to `dnd/recap.yaml` resolves from `dnd/`.
|
|
- Prompt decoding is strict; unknown YAML fields are rejected.
|
|
- Duplicate prompt IDs are invalid. If multiple files declare the requested prompt ID, Scriptorium fails instead of choosing one.
|
|
|
|
`messages[].cache_control` fields:
|
|
|
|
- `type` (required when `cache_control` is present): currently only `ephemeral`.
|
|
- `ttl` (optional): currently only `1h`; omitted from outbound requests when unset.
|
|
|
|
Example cache-controlled message:
|
|
|
|
```yaml
|
|
messages:
|
|
- role: system
|
|
content_file: ./stable_context.md
|
|
cache_control:
|
|
type: ephemeral
|
|
ttl: 1h
|
|
- role: user
|
|
content: |
|
|
{{input "transcript"}}
|
|
```
|
|
|
|
Use cache control on stable reusable prompt content. Dynamic per-run inputs before the cache-controlled message change the provider cache key.
|
|
|
|
Example prompt-level session ID:
|
|
|
|
```yaml
|
|
session_id: "{{ .session_id }}"
|
|
```
|
|
|
|
When configured, `session_id` is rendered with the same variable context as messages. The rendered value is trimmed, omitted when empty, and rejected if longer than 256 characters. CLI callers pass the value through `--var session_id=<value>`; HTTP callers pass it through `"vars": {"session_id": "<value>"}`.
|
|
|
|
`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 anywhere under `profile_dir`, including nested subdirectories.
|
|
|
|
Subdirectories are organizational only. Callers still select profiles by the YAML `id`, not by file path. For example, `profiles/local/local-quality.yaml` may still declare `id: local-quality`, and callers use `--profile local-quality`.
|
|
|
|
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
|
|
service_tier: priority
|
|
```
|
|
|
|
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`
|
|
- `service_tier` (optional): provider-specific request tier such as OpenRouter `flex` or `priority`
|
|
- `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.
|
|
- Duplicate profile IDs are invalid. If multiple files declare the requested profile ID, Scriptorium fails instead of choosing one.
|
|
|
|
Current outbound request behavior:
|
|
|
|
- The OpenAI-compatible client currently serializes: `model`, optional `session_id`, `messages`, `temperature`, `max_tokens`, `top_p`, `service_tier`, and optional `response_format` for `json_schema` prompts.
|
|
- Messages without `cache_control` serialize with string `content`.
|
|
- Messages with `cache_control` serialize as a single text content-block array containing `cache_control`.
|
|
- `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`, including explicit nested paths such as `dnd/structured_events.schema.json`.
|
|
- Absolute `schema_path` values are used directly.
|
|
- Scriptorium does not recursively search schemas by basename; nested schemas must be referenced by their relative path.
|
|
- 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: `examples/prompts/`
|
|
- Profile examples: `examples/profiles/`
|
|
- Schema examples: `examples/schemas/`
|
|
- Input fixtures: `examples/fixtures/`
|
|
- Render example script: `examples/render-markdown-summary.sh`
|
|
- HTTP request example: `examples/http-run.json`
|
|
|
|
Example organizational layout:
|
|
|
|
```text
|
|
examples/prompts/dnd/recap.yaml
|
|
examples/profiles/local/local-quality.yaml
|
|
examples/schemas/dnd/structured_events.schema.json
|
|
```
|
|
|
|
## Integration References
|
|
|
|
- [Inbound HTTP contract](integrations/http-api.md)
|
|
- [Outbound OpenAI-compatible contract](integrations/openai-compatible-chat.md)
|