Files
scriptorium/docs/config.md

259 lines
14 KiB
Markdown
Raw Normal View History

# Configuration Reference
This is the canonical reference for Scriptorium application settings. Prompt,
2026-10-04 13:04:02 +00:00
profile, backend, schema, execution-setting, built-in profile, and framework
credential semantics are defined by the
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and
2026-10-04 13:04:02 +00:00
outcomes, see the [HTTP API reference](api.md). For migration examples, see
[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md).
## 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](../examples/config.yml),
2026-10-04 13:04:02 +00:00
[complete configuration](../examples/config.full.yml),
[composed configuration](../examples/config.composed.yml),
[collection configuration](../examples/config.collections.yml), and
2026-10-04 13:04:02 +00:00
[framework inheritance configuration](../examples/config.inheritance.yml) 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.
2026-10-04 13:04:02 +00:00
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.
2026-09-26 18:08:36 +00:00
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
2026-09-26 18:08:36 +00:00
directory. Load diagnostics are printed safely on stderr; invalid application
configuration exits with status 1.
2026-10-04 13:04:02 +00:00
### Promptkit source selectors
`promptkit_sources` is an ordered sequence of explicit Promptkit source
selectors. Each item must set exactly one of `file` or `directory`:
```yaml
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas
```
An empty or null final resolved `promptkit_sources` list selects no
2026-10-04 13:04:02 +00:00
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](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
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.
2026-10-04 13:04:02 +00:00
### 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](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).
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](../examples/config.collections.yml)
declares `file` identity with `upsert`, combines imported file selectors, and
lets an overlay add another. CLI list overrides still replace the whole list.
At application precedence boundaries, omission preserves lower-precedence
selectors. Under ordinary list replacement, `[]` clears the selection and
`null` resolves to no selectors. Under authored `append` or `upsert`, `[]`
contributes no records and `null` is invalid. To clear a collection with an
inherited policy, declare `mode: replace` at
`destination: [promptkit_sources]` in the higher-precedence source and supply
`promptkit_sources: []`. See
[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#yaml-declarations-and-policy-lifetime)
for policy lifetime and combination rules.
These application root `config` controls do not change the separate
Promptkit v0.12.0 framework format: its selected framework files use the
[Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
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; sequence contributions and nulls at collection
destinations follow the effective collection policy described above. Other
explicit nulls replace lower values subject to the application schema.
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](../examples/config.composed.yml) imports the application
[source-selection fragment](../examples/config-fragments/sources.yml) and has
a selectable [local overlay](../examples/overlays/local.yml). That fragment
selects the [framework backend file](../examples/framework/backends.yml) through
`promptkit_sources`; backend definitions are not imported into the application
document. From the repository root:
```bash
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:
```bash
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
```
2026-10-04 13:04:02 +00:00
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 |
| --- | --- | --- |
2026-10-04 13:04:02 +00:00
| `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](api.md) defines how
each limit is enforced and reported. `server.artifact_root` configures an HTTP
deployment boundary; see [operations](operations.md) for deployment handling.
2026-09-26 18:17:57 +00:00
The `config validate`, `config show`, `config sources`, and `config explain`
2026-10-04 13:04:02 +00:00
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](cli.md#framework-configuration-inspection).
2026-09-26 18:17:57 +00:00
`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
2026-10-04 13:04:02 +00:00
resolved snapshot. The application schema rejects raw credential fields, but
do not treat inspection as a general-purpose filter for sensitive strings.
2026-08-29 14:18:29 +00:00
## Framework Source Mapping
2026-10-04 13:04:02 +00:00
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
2026-10-04 13:04:02 +00:00
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
for all of those definitions. The files under
[`examples/prompts`](../examples/prompts/),
[`examples/profiles`](../examples/profiles/), and
[`examples/schemas`](../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
2026-10-04 13:04:02 +00:00
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
2026-10-04 13:04:02 +00:00
[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md)
defines outbound authentication, provider request mapping, transport limits,
and timeout layering.
## Related References
- [CLI reference](cli.md)
- [HTTP API reference](api.md)
- [Operations guide](operations.md)
2026-10-04 13:04:02 +00:00
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)