Files
scriptorium/docs/consumers/upgrading-promptkit.md

176 lines
5.6 KiB
Markdown

# 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).
## Move source selectors into an ordered sequence
Replace the old application directory settings:
```yaml
prompt_dir: ./examples/prompts
profile_dir: ./examples/profiles
```
with an ordered `promptkit_sources` sequence:
```yaml
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:
```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:
```yaml
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:
```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
```
## 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:
```yaml
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](../config.md) and
[operations](../operations.md) contracts for path ownership and runtime
boundaries.