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

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

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:

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

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:

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, messages, temperature, max_tokens, top_p, service_tier, 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, 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:

examples/prompts/dnd/recap.yaml
examples/profiles/local/local-quality.yaml
examples/schemas/dnd/structured_events.schema.json

Integration References

• Inbound HTTP contract
• Outbound OpenAI-compatible contract