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

5.6 KiB

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 and release notes.

Move source selectors into an ordered sequence

Replace the old application directory settings:

prompt_dir: ./examples/prompts
profile_dir: ./examples/profiles

with an ordered promptkit_sources sequence:

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:

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 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:

backends:
  local-gpu:
    endpoint: http://localhost:11434/v1
    api_key_env: LOCAL_GPU_API_KEY

to framework/backends.yml:

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:

id: meeting.summary
version: "1.0.0"
messages:
  - role: user
    content: Summarize this synthetic note.
output:
  format: text
  validation_mode: none

to keyed definitions:

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:

id: fast
base_profile: common
timeout_seconds: 30

under its keyed mapping and rename the inheritance field:

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:

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 and operations contracts for path ownership and runtime boundaries.