107 lines
4.3 KiB
Markdown
107 lines
4.3 KiB
Markdown
# Upgrade PromptKit Sources And Definitions
|
|
|
|
This guide covers the CLI and framework configuration cutover to
|
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/configuration-migration.md)
|
|
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
|
for the full upstream contract.
|
|
|
|
Removing version selectors and changing framework definition shapes are
|
|
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
|
|
|
|
## 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:
|
|
|
|
```yaml
|
|
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](../config.md).
|
|
|
|
## Rewrite framework definitions
|
|
|
|
Replace version-keyed prompts and keyed profile/backend mappings with lists
|
|
of records containing `id`. For example, before:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md#messages-and-templates)
|
|
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](../../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.
|