14 KiB
Configuration Reference
This is the canonical reference for Scriptorium application settings. Prompt, profile, backend, schema, execution-setting, built-in profile, and framework credential semantics are defined by the Promptkit v0.12.0 format reference. For command syntax, see the CLI reference; for HTTP request shapes and outcomes, see the HTTP API reference. For migration examples, see Upgrading Promptkit sources and definitions.
Discovery And Precedence
ConfigKit assembles the selected main source, imports, and overlay, resolves inheritance, and decodes the result with Scriptorium's typed defaults. It then applies explicitly supplied application CLI values, records application normalization, and validates the result. Source, composition, inheritance, and decoding failures happen before CLI assignment and cannot be repaired by it; an override can correct a decoded value before application validation.
When --config is omitted, Scriptorium searches
/usr/local/etc/scriptorium/config.yml and then /etc/scriptorium/config.yml.
ConfigKit performs this ordered search for each load. If neither exists, it
uses built-in defaults; an error in a selected candidate does not cause a
fallback. An explicit --config path must exist and decode successfully,
including when an empty path is explicitly supplied.
The maintained minimal configuration, complete configuration, composed configuration, collection configuration, and framework inheritance configuration are copyable examples.
Application Configuration File
Application configuration is decoded by ConfigKit v1.2.0 as strict YAML.
Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors
are rejected.
An explicit empty string is a value and may clear a file-provided optional
string. A scalar null is not an empty string and is rejected for non-nullable
fields; nullable fields such as transient_retries retain their documented
meaning. Raw API-key fields and unknown application fields are rejected.
Only explicitly supplied application CLI flags override decoded settings. 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.
Promptkit source selectors
promptkit_sources is an ordered sequence of explicit Promptkit source
selectors. Each item must set exactly one of file or directory:
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas
Omitting the field or setting it to [] (or null) selects no
application-supplied framework sources; Promptkit's selected catalog and
maintained definitions still apply. A later sequence item overlays an earlier
one. Files within a selected directory are composed together, so conflicting
definitions in that group fail instead of using filename order as precedence.
An explicit file may use ConfigKit imports. The complete framework format and
source rules belong to the Promptkit v0.12.0 format reference.
Selector paths are relative to the process working directory, not to the
application configuration file. Application validation checks the selector
shape but does not open or validate Promptkit sources. config validate
therefore does not prove that selected sources can build an engine; use
inspect configuration validate for that separate check. Repeated
--promptkit-source flags replace the entire configured selector sequence
and preserve flag order. Without an authored collection policy, a selected
overlay replaces promptkit_sources as a whole; a declared sequence policy
may instead combine the lists.
Explicit imports and selected overlays
Application files declare imports under root config.imports. Native path,
dir, and glob selectors, filters, recursion, destinations, and item
placement are available as described in the pinned ConfigKit contract.
Imports are optional by default; set required: true when absence must fail.
The old optional field is not supported. Directory selection has no default
filename filter; author a pattern when only YAML files are intended. ConfigKit
composes peer sources strictly, rather than using filename order to resolve
conflicts. Imports are resolved relative to their declaring file within the
native source root. Scriptorium does not widen that root.
Root config.sequences can declare an identity key and merge mode for a
collection. Scriptorium does not register or infer an identity for
promptkit_sources: absent an authored policy, unkeyed lists replace across
precedence boundaries. The collection example
declares file identity with upsert, combines imported file selectors, and
lets an overlay add another. CLI list overrides still replace the whole list.
These application root config controls do not change the separate
Promptkit v0.12.0 framework format: its selected framework files use the
Promptkit contract
and its older ConfigKit controls.
--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. Mappings merge and explicit nulls replace; sequence behavior
depends on any authored collection policy. Defaults-only loading can enable
imports, but an absent main has no import declarations. This CLI supplies no
independent overlay root, so an active overlay cannot be located without a
selected main context. That is not a general ConfigKit restriction.
The composed example imports the application
source-selection fragment and has
a selectable local overlay. That fragment
selects the framework backend file through
promptkit_sources; backend definitions are not imported into the application
document. 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
Inspect the collection overlay and render without contacting a provider:
go run ./cmd/scriptorium config show --config ./examples/config.collections.yml --config-overlay collection
go run ./cmd/scriptorium render --config ./examples/config.collections.yml --config-overlay collection \
--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 promptkit_sources, schema_dir, and server.artifact_root
remain relative to the process working directory even when authored in a
fragment or overlay. These source constraints are separate from Promptkit
message-resource paths and HTTP artifact containment.
| Field | Default | Meaning |
|---|---|---|
promptkit_sources |
empty sequence | Ordered file/directory sources for Promptkit backends, profiles, and prompts. |
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. |
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.
The config validate, config show, config sources, and config explain
commands inspect this application configuration without creating a Promptkit
engine. show is a resolved inspection snapshot, not necessarily a reloadable
file. Application validation does not check framework sources, backend
connectivity, or credential availability. Use inspect configuration for
Promptkit's separately captured framework configuration; its four operations
are documented in the CLI reference.
config explain --path /server/addr uses JSON Pointer syntax to show the
selected field's current value and history from defaults, files, overlays,
explicit CLI overrides, and normalization. --path '' selects the root.
History includes replaced and removed values; show presents the final
resolved snapshot. The application schema rejects raw credential fields, but
do not treat inspection as a general-purpose filter for sensitive strings.
Framework Source Mapping
Scriptorium assembles selected Promptkit source files and directories in the
order described above, then constructs the Promptkit engine. Framework
definitions and custom backends belong in those selected source files, not in
the Scriptorium application configuration. Message content_file paths use
the defining source's resource context and are captured when the engine is
constructed; schema and request-artifact loading remain preparation-time
operations. Scriptorium does not redefine or independently parse 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 selected application 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.