Document PromptKit source migration
This commit is contained in:
167
docs/config.md
167
docs/config.md
@@ -1,11 +1,12 @@
|
||||
# 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.2 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
||||
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).
|
||||
outcomes, see the [HTTP API reference](api.md). For migration examples, see
|
||||
[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md).
|
||||
|
||||
## Discovery And Precedence
|
||||
|
||||
@@ -21,20 +22,19 @@ If neither exists, it uses built-in defaults. An explicit `--config` path must
|
||||
exist and decode successfully.
|
||||
|
||||
The maintained [minimal configuration](../examples/config.yml),
|
||||
[complete configuration](../examples/config.full.yml), and
|
||||
[complete configuration](../examples/config.full.yml),
|
||||
[composed configuration](../examples/config.composed.yml), and
|
||||
[backend inheritance configuration](../examples/config.inheritance.yml) are
|
||||
[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.
|
||||
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.
|
||||
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
|
||||
@@ -42,6 +42,36 @@ 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
|
||||
```
|
||||
|
||||
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](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. A selected application overlay that defines
|
||||
`promptkit_sources` replaces the prior sequence as a whole.
|
||||
|
||||
### Explicit imports and selected overlays
|
||||
|
||||
A file-backed configuration may declare `configkit.imports` with relative
|
||||
@@ -74,15 +104,15 @@ go run ./cmd/scriptorium render \
|
||||
--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.
|
||||
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 |
|
||||
| --- | --- | --- |
|
||||
| `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. |
|
||||
| `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. |
|
||||
@@ -90,7 +120,6 @@ These source constraints are separate from HTTP artifact containment.
|
||||
| `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](api.md) defines how
|
||||
@@ -98,91 +127,29 @@ 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. `api_key_env` is an environment-variable *name* and remains
|
||||
visible in inspection; its environment value is never read by ConfigKit.
|
||||
Ordinary backend `extra_params` values also remain visible, so keep secrets out
|
||||
of those fields and protect inspection output as potentially sensitive.
|
||||
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. Neither renderer looks up credential bytes, and neither
|
||||
claims to identify arbitrary secrets in unclassified parameter values.
|
||||
|
||||
### Application mapping inheritance
|
||||
|
||||
Any application input mapping may use ConfigKit's `extends: sibling-name`
|
||||
directive to inherit from a mapping among its immediate siblings. Names are
|
||||
exact, and lookup does not search ancestor or unrelated mappings. ConfigKit
|
||||
resolves inheritance after imports, a selected overlay, and explicit CLI
|
||||
overrides have been assembled, and before typed decoding. It resolves every
|
||||
effective relationship, even for a backend the selected profile does not use;
|
||||
an invalid relationship in such a mapping still fails the load.
|
||||
|
||||
The child retains its own mapping name. Explicit child values replace inherited
|
||||
values, including zero, false, empty strings, sequences, and null where the
|
||||
application field permits null; omitted values inherit. `extends: null`
|
||||
cancels inheritance and keeps the child's own settings. The parent remains an
|
||||
ordinary configured entry: a parent backend is registered and validated by
|
||||
Promptkit along with other configured backends, not treated as an abstract
|
||||
template. Inheritance copies settings but does not create a shared capacity
|
||||
pool across distinct backend IDs. The maintained [backend inheritance
|
||||
example](../examples/config.inheritance.yml) shows a complete parent and child.
|
||||
|
||||
ConfigKit retains inherited origins and displaced values for inspection:
|
||||
`show` presents the resolved result and `explain` describes derivation and
|
||||
history. Inherited application paths retain their working-directory-relative
|
||||
meaning. An inherited `api_key_env` remains a visible environment-variable
|
||||
name passed to Promptkit; ConfigKit does not read its value. Promptkit prompt,
|
||||
profile, and schema formats and HTTP request payloads are independently parsed
|
||||
and do not acquire this directive. See the pinned [ConfigKit v0.5.0 inheritance
|
||||
contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance)
|
||||
for exact semantics.
|
||||
|
||||
`extends` is reserved across application input mappings, not only under
|
||||
`backends`; quoting the key does not make it ordinary data. This can affect a
|
||||
mapping name (such as a backend ID) or a literal provider parameter with that
|
||||
name. Rename an application-owned name where appropriate. A provider-required
|
||||
literal key cannot generally be renamed without provider support, and this
|
||||
ConfigKit version has no escape or opt-out; a concrete need must be addressed
|
||||
upstream.
|
||||
|
||||
## Custom Backends
|
||||
|
||||
Use `backends` when a profile selects an application-defined backend ID:
|
||||
|
||||
```yaml
|
||||
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.
|
||||
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 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.
|
||||
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.
|
||||
@@ -192,7 +159,7 @@ parse those framework file formats.
|
||||
contracts.
|
||||
|
||||
See the
|
||||
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
|
||||
[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
|
||||
@@ -201,7 +168,7 @@ 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
|
||||
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.
|
||||
@@ -235,7 +202,7 @@ 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.11.2/docs/integrations/openai-compatible-chat.md)
|
||||
[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.
|
||||
|
||||
@@ -244,4 +211,4 @@ and timeout layering.
|
||||
- [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.11.2/docs/formats.md)
|
||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
|
||||
|
||||
Reference in New Issue
Block a user