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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user