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

View File

@@ -18,7 +18,7 @@ import "go.maximumdirect.net/promptkit"
For migration from the former module path, see
[Update Go Imports](configuration-migration.md#update-go-imports).
Configuration APIs use `go.maximumdirect.net/configkit` v1.2.0. Its types are
Configuration APIs use `go.maximumdirect.net/configkit` v1.4.0. Its types are
not interchangeable with the old ConfigKit module path.
The maintained [offline preparation example](../../examples/go-library/prepare/main.go)
@@ -56,13 +56,13 @@ The bundled OpenRouter backend and profiles are installed in a lower underlay
by default. Select a profile explicitly, for example:
```go
input := configkit.Input{Source: configkit.Mapping("application", map[string]any{
input := promptkit.SettingsInput(configkit.Mapping("application", map[string]any{
"prompts": []any{map[string]any{
"id": "my-prompt",
"messages": []any{map[string]any{"role": "user", "content": "Hello"}},
"output": map[string]any{"format": "text", "validation_mode": "none"},
}},
})}
}))
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &input}})
if err != nil { return err }
result, err := engine.Run(ctx, promptkit.RunRequest{PromptID: "my-prompt", ProfileID: "gpt-luna-latest"})
@@ -83,9 +83,13 @@ promptInputs, err := promptkit.DirectoryInputs("prompts")
if err != nil { return err }
profileInputs, err := promptkit.DirectoryInputs("profiles")
if err != nil { return err }
// These selected files are wrapperless Promptkit fragments.
for i := range promptInputs { promptInputs[i].Destination = configkit.Keys("promptkit") }
for i := range profileInputs { profileInputs[i].Destination = configkit.Keys("promptkit") }
filesystem := configkit.NewFilesystem("application schemas", os.DirFS("."))
schemaInput := configkit.Input{
Source: promptkit.SchemaRootSource("application schemas", "schemas"),
Destination: configkit.Keys("promptkit"),
Filesystem: &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."},
}
engine, err := promptkit.NewEngine(promptkit.Config{
@@ -107,6 +111,31 @@ new engine to observe configuration edits. See the [constructor GoDoc](../../eng
for the exact public contract and the [framework format reference](../formats.md)
for definition fields.
### Reuse An Application-Owned Load
An application that already loads ConfigKit configuration can embed
`promptkit.Settings` at `yaml:"promptkit"`, compose its definition with
`promptkit.Configure`, and pass the successful whole result to
`promptkit.NewFromConfig`. The [preparation example](../../examples/go-library/prepare/main.go)
shows a complete single-load workflow. Existing application resolve and
validate callbacks run before Promptkit's, and its defaults, version rule,
sequence registrations, and sensitivity predicate are preserved. Callers can
wrap the returned callbacks for work that must run afterward.
`NewFromConfig` accepts a completed result or a wrapper exposing the three
methods in [`Configuration`](../../engine.go). The selected `/promptkit`
value can be `Settings`, `*Settings`, absent, or nil; an incompatible value,
nil result, or unavailable inspection view returns `ErrInvalidConfig`. It
does not load sources, rerun callbacks, or add a bundle. Select
`BundledOpenRouterUnderlay()` before the application load if desired;
`WithBundledOpenRouter` affects only `NewEngine`. `RuntimeConfig` supplies only
client timeout, HTTP client, and transient-retry settings. Do not mutate the
resolved settings before handoff; subsequent mutation does not change captured
resources. Applications may register equivalent callbacks explicitly instead
of using `Configure`. Construction errors retain their underlying causes;
on the standalone path, a ConfigKit `LoadError` remains available through
`errors.As`.
### Load Companion Prompts Relative To The Main Configuration
A non-file underlay can use the selected main configuration's directory for
@@ -136,7 +165,7 @@ engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.Configura
`Imports: true`. The binding itself does not enable imports, and an explicit
`Input.Filesystem` takes precedence. Imported prompt `content_file` references
keep their source-local context. See ConfigKit's
[layered-loading contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md#layered-loading)
[layered-loading contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#layered-loading)
for eligible inputs, fallback contexts, and behavior when the main has no usable
filesystem context.
@@ -179,6 +208,8 @@ defaults, err := promptkit.FilesystemInputs("embedded defaults", applicationFS,
if err != nil { return err }
operator, err := promptkit.DirectoryInputs(operatorDirectory)
if err != nil { return err }
for i := range defaults { defaults[i].Destination = configkit.Keys("promptkit") }
for i := range operator { operator[i].Destination = configkit.Keys("promptkit") }
profile := promptkit.ProfileSource("application choices", []promptkit.ProfileConfig{
{ID: "summary", Endpoint: &selectedEndpoint, Model: &selectedModel},
})
@@ -186,7 +217,7 @@ engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.Configura
Underlays: []configkit.Underlay{
{Inputs: defaults},
{Inputs: operator},
{Inputs: []configkit.Input{{Source: profile}}},
{Inputs: []configkit.Input{promptkit.SettingsInput(profile)}},
},
}})
```
@@ -211,7 +242,7 @@ document := configkit.Mapping("application configuration", map[string]any{
},
},
})
input := configkit.Input{Source: document}
input := promptkit.SettingsInput(document)
// Add input to a later underlay, or set Sources.Main = &input.
```
@@ -294,7 +325,7 @@ at index `i` in collection `team`, construct the path with `configkit.Keys`:
```go
view, err := engine.InspectConfiguration()
if err != nil { return err }
path := configkit.Keys("collections", "team", "profiles").Index(i).Key("model")
path := configkit.Keys("promptkit", "collections", "team", "profiles").Index(i).Key("model")
explanation, found := view.Explain(path)
if found && explanation.Effective.Redacted {
// Apply the application's disclosure policy before sharing the report.
@@ -307,7 +338,11 @@ shaped provider keys are redacted, but arbitrary prompt and provider content
is not necessarily safe to share. Inspection uses the engine's captured result
and does not reopen sources or resolve credentials. It retains effective values,
including recorded field normalization and queue defaulting, alongside source
provenance.
provenance. The view focuses effective output and `HistoricalPaths` on
`/promptkit`; it is not an isolation boundary. Metadata and source catalogs
remain whole-load evidence, and explicit `Explain` queries may address paths
outside the focus. The empty path explains the whole application. Diagnostics
come from the original load and are returned as detached records.
`InspectPrompt`, `InspectProfile`, and `InspectBackend` instead show individual
resolved resources without backend-to-profile execution completion or provenance.
`Prepare` or `PreparedExecution.Details` shows completed request-specific settings,
@@ -340,9 +375,11 @@ for _, difference := range differences {
```
See the [`ConfigurationInspection.Diff` GoDoc](../../configuration_inspection.go)
and ConfigKit's [effective-configuration diff guidance](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md#effective-configuration-diffs)
and ConfigKit's [effective-configuration diff guidance](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md#effective-configuration-diffs)
for the exact comparison contract. The operation compares only frozen effective
configuration values: it does not reread external files or compare their
configuration values, including native ancestor differences; sibling-only
records are excluded, but an ancestor record may contain sibling changes. It
does not reread external files or compare their
contents, resolved credential contents, later execution preparation, or
request-specific overrides. Inputs normalizing to the same effective value do
not create a value diff; lists are compared atomically. An empty diff is not
@@ -707,22 +744,26 @@ Set a small additional-call budget when a structurally invalid result can be
corrected automatically:
```go
request.Validation = &promptkit.OutputContract{
request.Validation = &promptkit.OutputContractInput{
Format: promptkit.FormatJSON,
ValidationMode: promptkit.ValidationJSONSchema,
Schema: map[string]any{"type": "object"},
RepairAttempts: 1,
RepairAttempts: new(1),
}
```
Each repair attempt is another model generation, so it can increase latency and
Omission or null selects one repair for active validation and zero for `none`;
an explicit zero selects single-pass validation. A replacement resolves its
own budget and does not inherit the configured one. Each repair attempt is
another model generation, so it can increase latency and
usage; `RunResult.Usage` is cumulative and `Validation.RepairAttempts` reports
repair generations rather than transient HTTP attempts. Exhaustion still
returns the final failed validation result. `basic` validation can also repair
an empty candidate, but structural
validity is not evidence of factual or domain correctness. See the
validity is not evidence of factual or domain correctness and a correction is
not guaranteed. See the
[output-contract format reference](../formats.md#output-contract) and
[`OutputContract` GoDoc](../../types.go) for the exact budget and eligibility
[`OutputContractInput` GoDoc](../../types.go) for the exact budget and eligibility
rules.
The built-in client also retries eligible temporary HTTP statuses. By default,
@@ -1015,7 +1056,7 @@ endpoint, model := "http://localhost:8000/v1", "example-model"
profile := promptkit.ProfileSource("local profile", []promptkit.ProfileConfig{
{ID: "local-summary", Endpoint: &endpoint, Model: &model},
})
// Add configkit.Input{Source: profile} to a caller underlay.
// Add promptkit.SettingsInput(profile) to a caller underlay.
```
Endpoint-only profiles have an empty backend ID and remain unrestricted by
@@ -1135,7 +1176,7 @@ shown above, or declare `schema_root` in application or collection mappings.
For a former single-file source, configure `schema_file` relative to its
contributing source, or supply its directory as a root and use its basename in
`schema_path`. To substitute an unrelated file per request, read and decode it
in the caller and supply its value as `OutputContract.Schema`. There is no
in the caller and supply its value as `OutputContractInput.Schema`. There is no
implicit working-directory root. Public structs gained fields; change any
positional struct literals to keyed literals when migrating.