Document shared configuration and repair defaults
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user