4.3 KiB
Upgrade PromptKit Sources And Definitions
This guide covers the CLI and framework configuration cutover to PromptKit v0.23.3 and ConfigKit v1.2.1. See the framework format reference for the full upstream contract.
Removing version selectors and changing framework definition shapes are intentional incompatible changes under the release policy.
Application configuration
Existing application fields that already select the desired sources retain their meaning. For example, this application configuration works both before and after the cutover:
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas
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.
Rewrite framework definitions
Replace version-keyed prompts and keyed profile/backend mappings with lists
of records containing id. For example, before:
prompts:
report:
"1":
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles:
fast:
endpoint: https://example.invalid/v1
model: synthetic-model
After:
prompts:
- id: report
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles:
- id: fast
endpoint: https://example.invalid/v1
model: synthetic-model
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.
PromptKit resolves content_file relative to the source that supplied the
field, including imported or inherited definitions. The
framework format reference
describes which paths are allowed within the source root.
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}.
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.
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. Its entry files declare their own namespaces; checkout names do not become IDs. The CLI reference demonstrates qualified rendering and the operations guide describes when updates take effect.