Update documentation for PromptKit adoption
This commit is contained in:
@@ -1,175 +1,101 @@
|
||||
# Upgrade Promptkit Sources And Definitions
|
||||
# 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).
|
||||
This guide covers the CLI and framework configuration cutover to
|
||||
[PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/configuration-migration.md)
|
||||
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
|
||||
for the full upstream contract.
|
||||
|
||||
## Move source selectors into an ordered sequence
|
||||
Removing version selectors and changing framework definition shapes are
|
||||
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
|
||||
|
||||
Replace the old application directory settings:
|
||||
## Application configuration
|
||||
|
||||
```yaml
|
||||
prompt_dir: ./examples/prompts
|
||||
profile_dir: ./examples/profiles
|
||||
```
|
||||
|
||||
with an ordered `promptkit_sources` sequence:
|
||||
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: ./framework/backends.yml
|
||||
- file: ./examples/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 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).
|
||||
|
||||
The former `--prompt-dir` and `--profile-dir` flags are removed. Replace them
|
||||
with repeated source flags, for example:
|
||||
## Rewrite framework definitions
|
||||
|
||||
```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:
|
||||
Replace version-keyed prompts and keyed profile/backend mappings with lists
|
||||
of records containing `id`. For example, before:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
meeting.summary:
|
||||
"1.0.0":
|
||||
report:
|
||||
"1":
|
||||
default_profile: fast
|
||||
messages:
|
||||
- role: user
|
||||
content: Summarize this synthetic note.
|
||||
content: Summarize this 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
|
||||
endpoint: https://example.invalid/v1
|
||||
model: synthetic-model
|
||||
```
|
||||
|
||||
## 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:
|
||||
After:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: report
|
||||
default_profile: fast
|
||||
messages:
|
||||
- role: user
|
||||
content: Summarize this note.
|
||||
output:
|
||||
format: text
|
||||
validation_mode: none
|
||||
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
|
||||
- id: fast
|
||||
endpoint: https://example.invalid/v1
|
||||
model: synthetic-model
|
||||
```
|
||||
|
||||
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.
|
||||
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.
|
||||
Keep relative message files beside their owning definitions. 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}`.
|
||||
|
||||
## Validate without a provider call
|
||||
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.
|
||||
|
||||
`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.
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user