Document PromptKit source migration
This commit is contained in:
175
docs/consumers/upgrading-promptkit.md
Normal file
175
docs/consumers/upgrading-promptkit.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user