promptkit/docs/consumers/configuration-migration.md

Configuration And API Migration

Promptkit no longer installs a provider catalog or selects prompt definitions by descriptive version labels. Applications now choose configuration inputs explicitly, and execution selects one prompt by its exact ID. This guide explains the shape changes and decisions an application must make; it is not an automatic migration tool. The framework format reference owns the current configuration contract, and the root package GoDoc owns exact API signatures and errors.

Select And Compose The Configuration You Need

Supply each backend, profile, prompt, schema, and collection source that the application intends to use. Promptkit does not discover directories or install provider definitions implicitly. An application may select an explicit collection input with CollectionInput:

input, err := promptkit.CollectionInput(
	"openrouter",
	configkit.File("config/openrouter.yaml"),
)
if err != nil {
	return err
}
engine, err := promptkit.NewEngine(promptkit.Config{
	Sources: promptkit.ConfigurationSources{
		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{input}}},
	},
})

Collection resource keys are local keys, while their runtime identities are qualified. For example, collections.openrouter.profiles.gemini-flash-latest is selected as openrouter/gemini-flash-latest. Stored backend, prompt-default, and other resource references must use their exact intended IDs; Promptkit does not rewrite references when a source is mounted. Profile extends remains a sibling local key in the same collection, not a cross-collection reference. Review collisions and all references when moving resources into collections.

The root version is an optional ConfigKit source header. A collection's release_version and a prompt's version are optional descriptive labels; neither selects a resource or changes execution. Preserve a label only when it is useful to your application. A formerly version-keyed prompt mapping must be reduced to one deliberately chosen definition per prompt ID, with its old label retained as prompt metadata if desired. Promptkit cannot choose a winner from a consumer's version history.

For example, change a version-keyed definition:

prompts:
  report:
    "2.0":
      messages:
        - role: user
          content: Review this report.
      output:
        format: text
        validation_mode: none

to one direct definition. Its optional version is only a label:

prompts:
  report:
    version: "2.0"
    messages:
      - role: user
        content: Review this report.
    output:
      format: text
      validation_mode: none

Identity Mapping

The reviewed catalog identities have slash-free profile keys. Their documented mapping is:

Previous identity	Namespaced identity or action
Backend openrouter	openrouter/default
Backend rakestrawhome	rakestrawhome/default
Each OpenRouter catalog profile p	openrouter/p, retaining the exact local key p
Profile rakestrawhome-gemma-4-31b	rakestrawhome/rakestrawhome-gemma-4-31b
Built-in promptkit-openrouter-standard	No automatic replacement; optionally define caller profile openrouter/standard
Built-in promptkit-openrouter-auto	No automatic replacement; optionally define caller profile openrouter/auto

These are conversion examples, not aliases or bundled resources. Mounting old /v3 assets does not update backend references, profile inheritance, prompt defaults, or diagnostic defaults inside them. Edit those values to the exact qualified IDs you chose.

For example, an optional caller-owned standard profile may extend a selected Gemini profile in the same openrouter collection:

collections:
  openrouter:
    profiles:
      standard:
        extends: gemini-flash-latest

An optional auto profile may instead select the exact backend and model values:

collections:
  openrouter:
    profiles:
      auto:
        backend: openrouter/default
        model: openrouter/auto

Neither optional profile name is a Promptkit contract. Keep provider model strings and settings as selected by the application, including any meaningful prefixes. If a backend declares diagnostic defaults, update them to exact qualified IDs; an unselected diagnostic default is not automatically made resolvable by migration.

Prompt Selection API

Prompt selection is ID-only. Remove version selectors from calls to Run, Prepare, PrepareExecution, ValidateRequest, InspectRequirements, and SmokeTest. Remove the PromptVersion field from RunRequest, RequirementInspectionRequest, and SmokeTestRequest; InspectPrompt now has the form InspectPrompt(ctx, promptID). For example, select the prompt explicitly in the request rather than setting a version selector:

request := promptkit.RunRequest{
	PromptID:  "support/report",
	ProfileID: "support/standard",
}
_, err = engine.Run(ctx, request)
if err != nil {
	return err
}

If the former format contained multiple versions under one ID, choose the one definition the application should install, and optionally keep its label in the prompt's version field. That label remains descriptive metadata and is reported by inspection or results where applicable; it never chooses the definition.

The public inventory APIs can help an operator inspect a captured effective configuration: ListProfiles, ListPrompts, and ListBackends return exact identities, while ListNamespaces and ListCollections expose resource-bearing namespaces and effective collection declarations. Inventory does not select which configuration version the application should deploy.

Deployment Selection Remains With The Application

Applications decide which checked-in, embedded, operator-supplied, or programmatic inputs to compose for each deployment. They also decide when to construct a replacement engine after changing those sources. Promptkit does not fetch catalog updates, select provider availability, validate upstream catalog release status, or automatically migrate arbitrary consumer files. The maintained offline collection example shows explicit source selection, local imports, layering, a scoped view, and operator inventory without a provider call.