Document shared configuration and repair defaults

This commit is contained in:
2026-11-21 14:48:19 +00:00
parent 56795bb49a
commit 08d3d0ea3b
15 changed files with 259 additions and 166 deletions

View File

@@ -1,8 +1,7 @@
# Configuration And API Migration
This breaking pre-v1 minor migration adopts Promptkit's vanity module path,
changes the v0.16-era keyed resources to identified lists, adopts ConfigKit v1,
and removes prompt-version labels.
This guide covers the current configuration and repair-input migration, as well
as earlier module-path and keyed-resource migrations.
Promptkit installs a default-on bundled OpenRouter catalog; applications 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
@@ -10,6 +9,35 @@ 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.
## Move Settings Under Promptkit
Place complete-document resources under `promptkit`, including `schema_root`,
`backends`, `profiles`, `prompts`, and `collections`. Old root-level resource
keys are application data and are not loaded as Promptkit resources; selecting
an unmigrated resource can therefore fail with a not-found error. IDs and
references do not acquire a `promptkit` prefix. `SettingsInput` mounts a
wrapperless fragment at `/promptkit`, and `CollectionInput` mounts one at
`/promptkit/collections/<namespace>`. Discovery helpers still return root-mounted
inputs; set destinations explicitly for discovered fragments. Standalone
id-first files use native sequence-item placement. The [format reference](../formats.md)
describes extensions and strict nested objects.
Applications can instead embed `promptkit.Settings`, call `Configure` on their
ConfigKit definition, load once, and pass the whole result to `NewFromConfig`.
The [preparation example](../../examples/go-library/prepare/main.go) shows the
workflow. Select `BundledOpenRouterUnderlay` before an application-owned load;
the default bundle option applies only to `NewEngine`. The application owns
version policy; Promptkit no longer validates resource-version fields.
Replace `RunRequest.Validation` values of type `*OutputContract` with
`*OutputContractInput` and use a pointer for `RepairAttempts`. Nil or null
selects zero for `none` and one for `basic`, `json`, and `json_schema`;
explicit zero disables correction. Runtime replacements resolve independently
of configured budgets. Inspection reports resolved integer budgets, including
zero. A failed validation can cause an additional generation and associated
latency and usage; a correction is not guaranteed. See the
[output contract](../formats.md#output-contract).
## Update Go Imports
Promptkit's module and public package import path is now
@@ -37,8 +65,8 @@ The configuration and API adaptations below are also part of this migration.
## 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
application intends to use. `NewEngine` selects the bundled OpenRouter underlay
by default; callers explicitly select other sources. An application may select an explicit
collection input with `CollectionInput`:
```go
@@ -64,11 +92,10 @@ Promptkit does not rewrite references when a source is mounted. `extends`
selects a sibling ID in the same list, not a cross-collection reference.
Review collisions and all references when moving resources into collections.
The optional source-root `version` header now accepts `2` or `"2"`; headerless
sources remain valid. A collection's `release_version` remains an optional
label. Prompt-version labels have been removed: choose one definition per ID
and store any application-specific release label outside Promptkit. In a
standalone imported prompt item, root `version` is a source header, not a label.
A collection's `release_version` remains an optional label. Prompt-version
selection has been removed: choose one definition per ID. Application-specific
version data may be retained at supported extension points, but is not used by
Promptkit for resource selection.
For example, change a version-keyed definition:
@@ -84,7 +111,7 @@ prompts:
validation_mode: none
```
to one identified definition:
to one identified wrapperless fragment, mounted with `SettingsInput`:
```yaml
prompts:
@@ -98,7 +125,8 @@ prompts:
```
The same conversion applies to backends and profiles. Sibling inheritance uses
identity references, and a later same-ID record replaces the whole lower record:
identity references, and a later same-ID record replaces the whole lower record.
This is another wrapperless fragment to mount with `SettingsInput`:
```yaml
profiles:
@@ -113,11 +141,11 @@ profiles:
To customize a lower resource's fields, add a distinct inherited variant as
above; when replacing the same ID, supply the complete intended record. Generic
append, replace, imports, and inheritance are described by the
[ConfigKit v1 configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md).
[ConfigKit v1 configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md).
Source-root controls are now `config:`, not `configkit:`. Imports are optional
unless the selected import declares `required: true`.
Update ConfigKit imports to `go.maximumdirect.net/configkit` at v1.0.0: its Go
Update ConfigKit imports to `go.maximumdirect.net/configkit` at v1.4.0: its Go
types are incompatible with the old module path. Promptkit now requires Go
1.27.0 or newer. Source builders take ordered slices with explicit IDs:
@@ -133,7 +161,7 @@ source := promptkit.ProfileSource("application", []promptkit.ProfileConfig{
Replace former maps passed to `BackendSource` in the same way, setting each
`BackendConfig.ID`. Duplicates are retained for loading to reject. Resource
inspection paths now address list indexes, for example
`configkit.Keys("profiles").Index(0).Key("model")`. Configuration inspection
`configkit.Keys("promptkit", "profiles").Index(0).Key("model")`. Configuration inspection
and diffs expose resolved values, recorded normalization and provenance.
`InspectProfile` reports the selected resolved profile without backend completion.
Use `Prepare` or `PreparedExecution.Details` for completed request settings,
@@ -165,7 +193,8 @@ These are conversion examples, not aliases or bundled resources. Mounting old
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
For example, the following wrapperless fragments can be mounted with
`SettingsInput`. An optional caller-owned standard profile may extend a selected
Gemini profile in the same `openrouter` collection:
```yaml