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

4.0 KiB

Upgrade PromptKit Sources And Definitions

This guide covers the CLI and framework configuration cutover to PromptKit v0.23.3 and ConfigKit v1.2.1. See the framework format reference for the full upstream contract.

Removing version selectors and changing framework definition shapes are intentional incompatible changes under the release policy.

Application configuration

Existing application fields that already select the desired sources retain their meaning. For example, this application configuration works both before and after the cutover:

promptkit_sources:
  - directory: ./examples/prompts
  - directory: ./examples/profiles
  - file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas

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.

Rewrite framework definitions

Replace version-keyed prompts and keyed profile/backend mappings with lists of records containing id. For example, before:

prompts:
  report:
    "1":
      default_profile: fast
      messages:
        - role: user
          content: Summarize this note.
      output:
        format: text
        validation_mode: none
profiles:
  fast:
    endpoint: https://example.invalid/v1
    model: synthetic-model

After:

prompts:
  - id: report
    default_profile: fast
    messages:
      - role: user
        content: Summarize this note.
    output:
      format: text
      validation_mode: none
profiles:
  - id: fast
    endpoint: https://example.invalid/v1
    model: synthetic-model

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}.

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.

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. Its entry files declare their own namespaces; checkout names do not become IDs. The CLI reference demonstrates qualified rendering and the operations guide describes when updates take effect.