176 lines
5.6 KiB
Markdown
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.
|