166 lines
6.2 KiB
Markdown
166 lines
6.2 KiB
Markdown
# 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](../formats.md) 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`:
|
|
|
|
```go
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
collections:
|
|
openrouter:
|
|
profiles:
|
|
standard:
|
|
extends: gemini-flash-latest
|
|
```
|
|
|
|
An optional auto profile may instead select the exact backend and model values:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```go
|
|
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](../../examples/go-library/prepare/main.go)
|
|
shows explicit source selection, local imports, layering, a scoped view, and
|
|
operator inventory without a provider call.
|