Document native application configuration adoption
This commit is contained in:
@@ -10,35 +10,39 @@ outcomes, see the [HTTP API reference](api.md). For migration examples, see
|
||||
|
||||
## Discovery And Precedence
|
||||
|
||||
Application settings are resolved in this order:
|
||||
|
||||
1. built-in Scriptorium defaults;
|
||||
2. a configuration file; then
|
||||
3. CLI overrides.
|
||||
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`.
|
||||
If neither exists, it uses built-in defaults. An explicit `--config` path must
|
||||
exist and decode successfully.
|
||||
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), and
|
||||
[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
|
||||
|
||||
Configuration is decoded by ConfigKit v0.5.0 as strict YAML. Unknown fields,
|
||||
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
@@ -69,28 +73,43 @@ 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. A selected application overlay that defines
|
||||
`promptkit_sources` replaces the prior sequence as a whole.
|
||||
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
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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. 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.
|
||||
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](../examples/config.composed.yml) imports the application
|
||||
[source-selection fragment](../examples/config-fragments/sources.yml) and has
|
||||
@@ -107,6 +126,16 @@ go run ./cmd/scriptorium render \
|
||||
--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
|
||||
|
||||
Reference in New Issue
Block a user