259 lines
14 KiB
Markdown
259 lines
14 KiB
Markdown
# 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](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
|
|
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),
|
|
[complete configuration](../examples/config.full.yml),
|
|
[composed configuration](../examples/config.composed.yml),
|
|
[collection configuration](../examples/config.collections.yml), and
|
|
[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.
|
|
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`:
|
|
|
|
```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
|
|
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.
|
|
|
|
### 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
|
|
```
|
|
|
|
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](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.
|
|
|
|
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](cli.md#framework-configuration-inspection).
|
|
`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](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
|
|
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](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)
|
|
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
|