Document shared configuration and repair defaults
This commit is contained in:
@@ -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