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: ./prompts
profile_dir: ./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 in prompt_dir.

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

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/