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

4.4 KiB

Upgrade PromptKit Sources And Definitions

This guide covers the earlier framework configuration cutover to PromptKit v0.23.3 and ConfigKit v1.2.1. See the framework format reference for the full upstream contract. The subsequent native CLI migration owns command, reporting, application-discovery, and source-setting changes.

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

Application configuration

Framework definition migration and application acquisition are separate changes. Rewrite older framework files as below, then select their entry file using the current application configuration. The old source-selector list and top-level schema root are not current aliases; follow the CLI migration guide. Scriptorium does not provide a legacy definition reader or embedded-definition extraction/reload path.

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. PromptKit resolves content_file relative to the source that supplied the field, including imported or inherited definitions. The framework format reference describes which paths are allowed within the source root.

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

The single external framework entry uses native ConfigKit import composition; there is no application-managed source-list precedence. Native record replacement and inheritance remain upstream-owned. Checkouts imported by the same discovery file are peers: conflicting definitions of the same ID fail instead of overriding one another.

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 defines qualified selection and prepared preview; the operations guide describes when updates take effect.