5.6 KiB
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 and release notes.
Move source selectors into an ordered sequence
Replace the old application directory settings:
prompt_dir: ./examples/prompts
profile_dir: ./examples/profiles
with an ordered promptkit_sources sequence:
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./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 former --prompt-dir and --profile-dir flags are removed. Replace them
with repeated source flags, for example:
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 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:
backends:
local-gpu:
endpoint: http://localhost:11434/v1
api_key_env: LOCAL_GPU_API_KEY
to framework/backends.yml:
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:
id: meeting.summary
version: "1.0.0"
messages:
- role: user
content: Summarize this synthetic note.
output:
format: text
validation_mode: none
to keyed definitions:
prompts:
meeting.summary:
"1.0.0":
messages:
- role: user
content: Summarize this synthetic 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:
id: fast
base_profile: common
timeout_seconds: 30
under its keyed mapping and rename the inheritance field:
profiles:
fast:
extends: common
timeout_seconds: 30
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:
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
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.
Validate without a provider call
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 and
operations contracts for path ownership and runtime
boundaries.