Configuration Reference

This is the canonical reference for Scriptorium application settings. Prompt, profile, schema, execution-setting, built-in profile, and framework credential semantics are defined by the Promptkit v0.11.0 format reference. For command syntax, see the CLI reference; for HTTP request shapes and outcomes, see the HTTP API reference.

Discovery And Precedence

Application settings are resolved in this order:

built-in Scriptorium defaults;
a configuration file; then
CLI overrides.

When --config is omitted, Scriptorium searches /usr/local/etc/scriptorium/config.yml and then /etc/scriptorium/config.yml. If neither exists, it uses built-in defaults. An explicit --config path must exist and decode successfully.

The maintained minimal configuration, complete configuration, and composed configuration are copyable examples.

Application Configuration File

Configuration is decoded by ConfigKit v0.4.0 as strict YAML. Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors are rejected. An explicit empty string is a value: it clears a file-provided optional path or, for required prompt_dir, fails the command's prerequisite. A scalar null is not an empty string and is rejected for scalar fields; nullable fields such as transient_retries retain their documented meaning. Raw API-key fields are not accepted.

ConfigKit applies defaults, the selected file, then only explicitly supplied application CLI flags before validating the result. Paths in the application document remain relative to the process working directory, not to the file's directory. Load diagnostics are printed safely on stderr; invalid application configuration exits with status 1.

Explicit imports and selected overlays

A file-backed configuration may declare configkit.imports with relative path or glob entries. Each entry is explicit; Scriptorium does not scan for fragments on its own. ConfigKit composes the selected file and imports by conflict, so two fragments cannot define the same field merely to establish precedence. A required missing import fails; an entry may use optional: true to suppress target nonexistence. Imports are resolved from the declaring file's canonical directory and remain within the selected file's canonical directory by default. Scriptorium does not widen that root.

--config-overlay NAME selects one file at overlays/NAME.yml below that root. The name must use letters, digits, _, or -; it is not a path. Empty and exact lowercase default select no overlay. There is no fallback, case folding, inherited stack, or automatic selection; a missing selected overlay fails. ConfigKit merges mapping fields and replaces other values, including sequences and explicit nulls, before applying explicit CLI flags. An active overlay needs a selected base file. No-source defaults-only loads cannot use imports or an active overlay.

The composed example imports two fragments and has a selectable local overlay. From the repository root:

go run ./cmd/scriptorium render \
  --config ./examples/config.composed.yml --config-overlay local \
  --prompt generic.markdown_summary \
  --input transcript=./examples/fixtures/transcript.md \
  --input glossary=./examples/fixtures/glossary.yml

Import and overlay file locations are constrained by ConfigKit; application path values such as prompt_dir remain relative to the process working directory even when authored in a fragment or overlay. These source constraints are separate from HTTP artifact containment.

Field	Default	Meaning
`prompt_dir`	unset	Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value.
`profile_dir`	unset	Optional custom Promptkit profile source directory overlaid on Promptkit built-ins.
`schema_dir`	`.`	Promptkit schema source directory for relative schema paths.
`server.addr`	`:8080`	Address used by `serve`.
`server.artifact_root`	unset	Root that enables HTTP `file` input references.
`server.max_request_bytes`	`16777216`	Maximum encoded HTTP request-body bytes; `0` disables the limit.
`server.max_artifact_bytes`	`16777216`	Maximum HTTP file-input artifact bytes; `0` disables the limit.
`server.max_response_bytes`	`16777216`	Maximum encoded HTTP response bytes; `0` disables the limit.
`defaults.render_format`	`text`	Default prepared-run output format: `text` or `json`.
`backends`	unset	Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings.
`transient_retries`	Promptkit default	Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts.

The size fields must be zero or greater. The HTTP API defines how each limit is enforced and reported. server.artifact_root configures an HTTP deployment boundary; see operations for deployment handling.

Custom Backends

Use backends when a profile selects an application-defined backend ID:

backends:
  local-gpu:
    endpoint: http://localhost:11434/v1
    api_key_env: LOCAL_GPU_API_KEY
    extra_params:
      provider_option: enabled
    concurrency_limit: 2
    queue_capacity: 0

Each mapping key is the case-sensitive backend ID. endpoint is required; api_key_env, extra_params, concurrency_limit, and queue_capacity are optional. concurrency_limit: 0 leaves the backend unlimited. Omitting queue_capacity lets Promptkit use its default for a limited backend, while an explicit queue_capacity: 0 disables queueing.

Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit validates backend IDs, endpoints, environment-variable names, extra parameters, and capacity relationships when Scriptorium constructs its engine. There are no backend command-line overrides. Store only an environment-variable name in api_key_env; raw API-key fields are not accepted.

Framework Source Mapping

Scriptorium passes prompt_dir, profile_dir, and schema_dir to Promptkit when constructing its engine. Scriptorium does not redefine or independently parse those framework file formats.

Prompt selection, versions, message templates, inputs, output contracts, and session IDs are Promptkit contracts.
Profile fields, numeric ranges, execution defaults, overlay precedence, built-in profiles, and credential rules are Promptkit contracts.
Schema path behavior and generated-content validation are Promptkit contracts.

See the tagged Promptkit format reference for all of those definitions. The files under examples/prompts, examples/profiles, and examples/schemas are maintained Scriptorium application inputs using that tagged format.

Promptkit supplies the opt-in profile IDs promptkit-openrouter-standard and promptkit-openrouter-auto. They can be selected as a prompt default or request profile, and custom profile sources retain precedence. Their effective model settings may change with a catalog upgrade; use a complete application-owned profile when fixed settings are required. See the tagged format reference for the maintained-profile contract.

Credentials And Outbound Behavior

Scriptorium maps --api-key-env and HTTP model.api_key_env into Promptkit request overrides. Keep secret values in environment variables and store only their names in configuration or framework source files. Do not place raw keys in configuration, prompts, profiles, CLI arguments, examples, or HTTP payloads.

An optional api_key_env whose environment value is absent or empty can result in an unauthenticated provider request. A profile that declares credentials required still fails as an invalid request when no credential source is selected, and fails with ErrAPIKeyEnvMissing when its selected environment source is absent or empty. Scriptorium never reads or emits the environment value itself.

Unset optional provider controls are omitted from compatible provider requests. A positive Promptkit repair_attempts budget can add provider calls, latency, token use, and cost; see the tagged format reference for its permitted values and validation-mode requirements.

Promptkit's built-in client makes up to two additional attempts for eligible transient HTTP statuses by default. The application transient_retries setting changes that budget for its constructed engine; an explicit run request override takes precedence. This can increase latency, request count, and cost. Each initial or repair generation has its own transient budget; an injected client retains its own retry behavior. The tagged integration contract owns eligibility and timing.

Promptkit's OpenAI-compatible integration contract defines outbound authentication, provider request mapping, transport limits, and timeout layering.

9.5 KiB Raw Blame History