Update documentation for PromptKit adoption

This commit is contained in:
2026-11-18 19:25:54 +00:00
parent a2205db152
commit 50c65adac4
16 changed files with 270 additions and 347 deletions

View File

@@ -1,175 +1,101 @@
# Upgrade Promptkit Sources And Definitions
# Upgrade PromptKit Sources And Definitions
This guide moves Scriptorium application configuration and framework files to
the Promptkit v0.12.0 source model. It covers the executable CLI and HTTP
application, not the former Scriptorium Go package. For exact framework
semantics, see the tagged [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
and [release notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/releases/v0.12.0.md).
This guide covers the CLI and framework configuration cutover to
[PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/configuration-migration.md)
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
for the full upstream contract.
## Move source selectors into an ordered sequence
Removing version selectors and changing framework definition shapes are
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
Replace the old application directory settings:
## Application configuration
```yaml
prompt_dir: ./examples/prompts
profile_dir: ./examples/profiles
```
with an ordered `promptkit_sources` sequence:
Existing application fields that already select the desired sources retain
their meaning. For example, this application configuration works both before
and after the cutover:
```yaml
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./framework/backends.yml
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas
```
Each item selects exactly one `file` or `directory`. Later items overlay
earlier items; conflicts within one directory source group are errors. Paths
are relative to the process working directory. An omitted or empty sequence
selects no application-supplied framework sources, while Promptkit's selected
catalog and maintained definitions remain available. A selected application
overlay replaces the whole sequence, and repeated `--promptkit-source` flags
replace it in command-line order rather than appending to it.
The selected framework files must still be rewritten as described below.
Scriptorium uses one native application schema: discovery, imports, selected
overlays, source order, explicit overrides, and working-directory-relative
selector paths remain application configuration behavior. It loads framework
sources separately with PromptKit's schema. No second application schema or
legacy definition reader is provided. See the [configuration reference](../config.md).
The former `--prompt-dir` and `--profile-dir` flags are removed. Replace them
with repeated source flags, for example:
## Rewrite framework definitions
```sh
scriptorium render \
--config ./examples/config.yml \
--promptkit-source ./examples/prompts \
--promptkit-source ./examples/profiles \
--promptkit-source ./examples/framework/backends.yml \
--prompt generic.markdown_summary \
--input transcript=./examples/fixtures/transcript.md \
--input glossary=./examples/fixtures/glossary.yml
```
Use the same source selectors with `run`, `serve`, and the supported
`inspect` commands. The [CLI reference](../cli.md) lists each command's
accepted flags.
## Relocate backend definitions
Custom backends no longer belong in Scriptorium's application configuration.
Move them into a selected Promptkit framework source file. For example, move
this old application section:
```yaml
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
```
to `framework/backends.yml`:
```yaml
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
```
Then select that file in `promptkit_sources`. Keep only the environment
variable name in `api_key_env`; never put the credential value in a file or
command line.
## Convert embedded identities to mapping keys
Prompt, version, profile, and backend IDs are mapping keys. Old embedded
`id`, `version`, and `base_profile` fields are not accepted. Change a standalone
prompt definition such as:
```yaml
id: meeting.summary
version: "1.0.0"
messages:
- role: user
content: Summarize this synthetic note.
output:
format: text
validation_mode: none
```
to keyed definitions:
Replace version-keyed prompts and keyed profile/backend mappings with lists
of records containing `id`. For example, before:
```yaml
prompts:
meeting.summary:
"1.0.0":
report:
"1":
default_profile: fast
messages:
- role: user
content: Summarize this synthetic note.
content: Summarize this note.
output:
format: text
validation_mode: none
```
Retain the other valid definition content from your source. Likewise, replace profile
`base_profile: common` with `extends: common` inside the profile mapping.
`extends` names an exact sibling profile ID. It is resolved while sources are
composed, before Promptkit validates the final definitions.
For example, move an old standalone profile:
```yaml
id: fast
base_profile: common
timeout_seconds: 30
```
under its keyed mapping and rename the inheritance field:
```yaml
profiles:
fast:
extends: common
timeout_seconds: 30
endpoint: https://example.invalid/v1
model: synthetic-model
```
## Review presence, null, and map values
Omitted values inherit or receive defaults; an explicit value can override
them even when it is `0`, `false`, or an empty string. For example,
`max_tokens: 0` is an explicit provider control, not omission. `null` is
field-specific: for example, a null `model` is unspecified, null
`timeout_seconds` restores its 600-second default, and null `extra_params`
clears the configured provider map. Check each field in the format reference
before converting old defaults or sentinel values.
For example, express the intended behavior directly:
After:
```yaml
prompts:
- id: report
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles:
explicit-zero:
temperature: 0
leave-temperature-unset:
model: explicit-model
overlay-provider-options:
extra_params:
provider_option: local
clear-provider-options:
extra_params: null
- id: fast
endpoint: https://example.invalid/v1
model: synthetic-model
```
Maps overlay recursively. An empty map does not erase keys inherited from a
parent or backend; use `extra_params: null` to suppress the configured map.
If changing only a model or backend, review other inherited fields because
they can remain effective. Do not infer inheritance or replacement from the
old loader's behavior.
Select prompts by exact ID; `--prompt-version` is rejected. If multiple former
versions must remain independently selectable, give them distinct IDs and
update callers. Qualified IDs such as `support/answer` are passed unchanged.
Keep relative message files beside their owning definitions. Convert framework
source controls from `configkit:` to `config:` and add `required: true` for
imports that must exist. An optional framework source header, if present, is
`version: 2`. Use sibling inheritance such as `extends: {id: base}`.
## Validate without a provider call
Composition now replaces a whole record when a later source selects the same
ID; supply the complete intended replacement, or create a distinct inherited
record. Null profile endpoint, credential, or provider-map settings can fall
back to the selected backend; review behavior rather than assuming null clears
backend values. Keep JSON schemas self-contained instead of depending on remote
schema references. Application selectors remain separate from these framework
semantics.
`scriptorium config validate --config PATH` validates Scriptorium's application
configuration, including selector shape, but does not open framework sources.
Then run `scriptorium inspect configuration validate --config PATH` to build
the engine and validate all selected Promptkit definitions, including unused
ones. It does not prepare a request, resolve credentials, contact a provider,
or load request-time schemas and artifacts. A running `serve` process captures
its configuration and message content at startup; restart it after changing
those inputs. See the [configuration](../config.md) and
[operations](../operations.md) contracts for path ownership and runtime
boundaries.
## Replace catalog selections
The default-on OpenRouter bundle supplies actual profiles such as `auto` and
`gpt-sol-latest`. Former catalog and `promptkit-openrouter-*` IDs are not
compatibility aliases. Choose an intended current bundled profile explicitly,
or define a complete local profile with the endpoint, model, and settings you
need. Do not assume a new default model. The bundle is an underlay and caller
records can replace it through ordinary composition.
For multiple independently maintained repositories, see the
[collection-discovery example](../../examples/config.discovery.yml). Its
entry files declare their own namespaces; checkout names do not become IDs.
The [CLI reference](../cli.md) demonstrates qualified rendering and the
[operations guide](../operations.md) describes when updates take effect.