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

@@ -26,8 +26,8 @@ source-relative prompt content, supplies an inline input, and prepares through
a scoped view. The example also demonstrates collection inventories and
namespace-filtered discovery, without contacting a provider or requiring
credentials.
The example disables the bundled OpenRouter configuration to keep its
inventories limited to its own offline fixtures.
The example loads application-owned settings once and selects no bundled
underlay, keeping inventories limited to its own offline fixtures.
The [consumer guide](docs/consumers/pkg-promptkit.md) also shows a local backend,
ordered file/embedded sources, programmatic mappings, and how to replace an
engine when source files change. Applications adapting the prior keyed

View File

@@ -9,8 +9,10 @@ import (
)
// ConfigurationInspection is a read-only view of one Engine's captured
// effective configuration and source history. It does not expose typed
// configuration values, filesystem contexts, or runtime credentials.
// effective configuration and source history focused on /promptkit. Metadata,
// sources, and explicit path queries retain native whole-load evidence; the
// focus is not an isolation boundary. It does not expose typed configuration
// values, filesystem contexts, or runtime credentials.
// Report content may include application prompt and provider data, so callers
// choose where and to whom to disclose it.
type ConfigurationInspection struct {
@@ -30,7 +32,9 @@ func (e *Engine) InspectConfiguration() (ConfigurationInspection, error) {
// Diff compares this view's captured effective configuration with other. This
// view is the earlier (left) value and other is the later (right) value. The
// comparison delegates to ConfigKit's frozen effective-value semantics, so
// source or resolution history alone does not create differences. It does not
// source or resolution history alone does not create differences. Native
// ancestor differences are retained, while sibling-only records are excluded.
// It does not
// reread external sources or compare referenced file contents, resolved
// credential contents, later execution preparation, or request-specific
// overrides. Either zero view returns ErrInvalidConfig and no records; other
@@ -86,7 +90,8 @@ func (v ConfigurationInspection) Explain(path configkit.Path) (configkit.Explana
return v.source.Explain(path)
}
// WriteEffective writes ConfigKit's redacted effective YAML. Writer errors
// WriteEffective writes the focused ConfigKit-redacted effective YAML. An absent
// effective focus fails without output; explicit null renders normally. Writer errors
// remain available through errors.Is and errors.As. The zero view returns
// ErrInvalidConfig.
func (v ConfigurationInspection) WriteEffective(w io.Writer) error {

8
doc.go
View File

@@ -1,8 +1,8 @@
// Package promptkit provides an embeddable engine for preparing and executing
// prompt-defined LLM workflows.
//
// Applications construct an [Engine] with [NewEngine], select ConfigKit
// sources for prompts, profiles, and backends, and
// Applications construct an [Engine] with [NewEngine] or register [Configure]
// during their own ConfigKit load and pass its result to [NewFromConfig], then
// call [Engine.InspectConfiguration], [Engine.InspectPrompt],
// [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.InspectBackend],
// [Engine.ListProfiles], [Engine.ListPrompts], [Engine.Prepare],
@@ -23,8 +23,8 @@
// independently. An injected [LLMClient] or [ArtifactReader] can therefore
// still receive concurrent calls and must be safe for that use.
//
// ConfigKit captures the selected configuration when NewEngine constructs an
// Engine. Prepare, PrepareExecution, and Run copy request maps, slices, pointer
// An Engine captures selected configuration resources during construction.
// Prepare, PrepareExecution, and Run copy request maps, slices, pointer
// values, and JSON-compatible extra parameters before using them. InspectPrompt,
// InspectRequirements, InspectProfile, and InspectBackend return copied
// inspection values.

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.

View File

@@ -6,71 +6,58 @@ This is the canonical reference for Promptkit's backend, profile, prompt, and
schema definitions. The [Go consumer guide](consumers/pkg-promptkit.md) shows
how to select sources and use an engine; the
[OpenAI-compatible integration contract](integrations/openai-compatible-chat.md)
owns outbound wire behavior. [ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md)
owns outbound wire behavior. [ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md)
owns the generic YAML grammar, imports, layering, inheritance, and diagnostics.
This reference describes what Promptkit does with the final effective values.
A configuration document may contain top-level `backends`, `profiles`, and
`prompts` lists, plus a `collections` mapping of namespaced resource groups.
Each resource has an explicit literal `id`, not a filename-derived identity.
IDs and references must be nonblank and remain exact: Promptkit does not trim or
re-key them. Unknown fields are errors. Promptkit installs a default-on bundled
OpenRouter underlay; callers still explicitly select a profile.
A complete configuration document places Promptkit settings beneath `promptkit`.
The `backends`, `profiles`, and `prompts` lists contain explicit literal
`id` values; `collections` groups namespaced resources. IDs remain exact and
do not include the `promptkit` path. Standalone resource fragments may omit
the wrapper when explicitly mounted as described below.
```yaml
backends:
- id: local
endpoint: http://localhost:8000/v1
concurrency_limit: 2
profiles:
- id: local-summary
backend: local
model: example-model
prompts:
- id: meeting.summary
default_profile: local-summary
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
collections:
support:
release_version: "1.4.0"
backends:
- id: offline
endpoint: https://example.invalid/v1
profiles:
- id: base
backend: support/offline
model: offline-model
- id: fast
extends: {id: base}
timeout_seconds: 30
prompts:
- id: answer
default_profile: support/fast
messages:
- role: user
content: Answer the selected caller input.
output:
format: text
validation_mode: none
promptkit:
profiles:
- id: local-summary
endpoint: http://localhost:8000/v1
model: example-model
prompts:
- id: meeting.summary
default_profile: local-summary
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
collections:
support:
release_version: "1.4.0"
backends:
- id: offline
endpoint: https://example.invalid/v1
profiles:
- id: fast
backend: support/offline
model: offline-model
```
## Source Headers, Collections, And Resource IDs
An input may omit a source header. When present, the source-root `version` is
reserved for ConfigKit's specification header and accepts only the exact string
`"2"` or strict decimal integer `2`; null and other values are invalid. This
header is distinct from a collection's `release_version` and ConfigKit's own
software version. ConfigKit checks and consumes accepted headers on non-main
inputs; a declaration on the main input remains visible in explicit
configuration inspection. Headerless inputs still undergo ordinary final-value
validation. ConfigKit owns generic import and source-history behavior.
For a standalone prompt item, a root `version` is only a source header, not
prompt metadata.
Applications own ConfigKit's version policy and source controls. Promptkit adds
no resource-version rule, including for collection, prompt, or profile records.
An application's root `version` is distinct from a collection's descriptive
`release_version`. Old root-level `prompts` or `profiles` keys are application
data, not Promptkit resources, and are neither consumed nor specially rejected.
The `promptkit` section, each collection, backend, profile, and prompt retain
unrecognized fields as application data. Such fields compose normally and are
visible to application validation and configuration inspection, but do not
become provider parameters or appear in resource reports. Grouping them under
an application-specific key reduces collisions; a misspelled optional Promptkit
field can also be accepted there. Nested Promptkit-owned objects, including
message, input, output, and smoke-test objects, remain strict.
The root resource lists contain unqualified IDs. Each `collections` entry
has a namespace key and may contain `release_version` plus the same three
@@ -98,8 +85,9 @@ inventories, see the [consumer guide](consumers/pkg-promptkit.md) and its
breaking identity and prompt-selection changes, see the
[configuration migration guide](consumers/configuration-migration.md).
Every effective backend, profile, and prompt definition is validated when
`NewEngine` constructs the engine, even if it is never selected. A profile may
Every effective backend, profile, and prompt definition is validated during
the registered configuration load and engine capture, even if never selected.
A profile may
be partial: an endpoint and model need only be complete after request overrides
are applied. A prompt's default profile similarly need not be runnable without
an overriding request. Missing request data, artifacts, schemas, credentials,
@@ -116,7 +104,9 @@ see the consumer guide's [resource and collection listing](consumers/pkg-promptk
## Prompt Definitions
The `prompts` list contains definitions selected by their literal IDs:
The `prompts` list contains definitions selected by their literal IDs. The
following examples in this reference are wrapperless `promptkit` fragments
unless explicitly shown as complete documents; mount them with `SettingsInput`.
```yaml
prompts:
@@ -147,8 +137,9 @@ prompts:
`default_profile`, `description`, `session_id`, `inputs`, and cache-control
fields may be absent or cleared with null where appropriate. A null whole
definition, required role, output format, or validation mode is invalid.
`required` and `repair_attempts` default to false and zero, respectively, and
are not nullable. `InspectPrompt` selects the same captured definition without
`required` defaults to false and is not nullable. An omitted or null
`repair_attempts` resolves according to `validation_mode`; see the output
contract below. `InspectPrompt` selects the same captured definition without
rendering or resolving a profile.
### Inputs
@@ -204,7 +195,7 @@ messages; the integration contract defines its wire representation.
| `schema` | one selection for `json_schema` | Inline JSON Schema value |
| `schema_file` | one selection for `json_schema` | File relative to the contributing field's source context |
| `schema_path` | one selection for `json_schema` | Path within the applicable explicit schema root |
| `repair_attempts` | no | Integer 0–3; default 0. Positive values need `basic`, `json`, or `json_schema` |
| `repair_attempts` | no | Integer 0–3; omitted or null defaults to 0 for `none`, otherwise 1. Positive values need `basic`, `json`, or `json_schema` |
`none` skips content validation; `basic` requires nonempty content; `json`
accepts any valid JSON value; `json_schema` checks the selected schema.
@@ -219,8 +210,12 @@ structured-output metadata to compatible clients. Plain `json` does not
request a provider-native JSON-object constraint. A positive repair budget
counts additional generations after failed validation; exhaustion returns the
last candidate and its failed validation result. Operational errors remain
errors. A request-level `OutputContract` replaces the whole configured one,
not individual fields; an empty request format defaults to `text`.
errors. A request-level `OutputContractInput` replaces the whole configured
contract, not individual fields; an empty request format defaults to `text`.
Its omitted budget resolves from its own validation mode, not the prompt's
budget. Explicit zero disables repair. A failed validation can incur one extra
generation by default, with corresponding latency and usage; correction is not
guaranteed.
## Backend Definitions
@@ -237,7 +232,8 @@ negative value is invalid. For positive concurrency, omitted/null queue
capacity defaults to 1024. An explicit queue capacity, including zero,
requires positive concurrency and must be nonnegative. Unlimited concurrency
has no queue. Provider maps contain JSON-compatible values; null entries are
ordinary JSON null. Unknown fields, including a raw `api_key`, fail.
ordinary JSON null. A raw `api_key` is not a Promptkit credential field: an
unrecognized backend field is application data and must not contain secrets.
`smoke_tests` is optional backend metadata for explicit diagnostic operations.
It may contain `default_profile`, `reachability`, and `authentication`:
@@ -310,7 +306,8 @@ Nonblank endpoints follow the backend URL rules; temperature is 0–2, top_p
is 0–1, max_tokens and timeout_seconds are nonnegative. Provider maps accept
JSON-compatible values with nonempty keys and cannot collide with the built-in
client's [standard request fields](integrations/openai-compatible-chat.md#request-body).
Credential values do not belong in profiles: raw `api_key` is invalid.
Credential values do not belong in profiles. A raw `api_key` is not a
Promptkit credential setting; an unrecognized field is application data.
### Defaults And Overrides
@@ -363,7 +360,8 @@ The default bundle installs root backend `openrouter`, endpoint
`OPENROUTER_API_KEY`, and smoke metadata selecting `gpt-luna-latest` with the
`openrouter_key` authentication adapter. Existing diagnostic endpoint fallback
applies. No prompt, implicit profile selection, or tuning defaults are installed.
Disable the entire bundle with `WithBundledOpenRouter(false)`.
Disable the bundle for `NewEngine` with `WithBundledOpenRouter(false)`; an
application-owned load selects `BundledOpenRouterUnderlay` explicitly.
The root profile IDs and their models are:
@@ -418,8 +416,12 @@ on an input. Single files can use ConfigKit inputs directly.
Root backends, profiles, and prompts, as well as collection declarations and
their resource lists, follow these same source rules. `CollectionInput`
mounts one explicitly selected source at a collection destination and enables
mounts one explicitly selected source at `/promptkit/collections/<namespace>` and enables
ConfigKit imports for that input; it does not discover or select sources.
`SettingsInput` mounts wrapperless settings fragments at `/promptkit`; an
id-first resource file uses ConfigKit sequence-item placement at the matching
resource list. Directory discovery retains root destinations, so callers mount
discovered wrapperless fragments explicitly. No document shape is inferred.
A later same-ID record replaces the lower definition in full. Use a distinct
inherited sibling when a variant should retain its parent's fields.
A request `ProfileID` takes precedence over a prompt `default_profile`; if
@@ -437,12 +439,12 @@ references are exact IDs and use their qualified form when they select a
collection resource. There is no Promptkit-specific depth limit or second
base-chain resolver. Missing references and cycles fail at construction. For
generic inheritance and layer mechanics, consult
[ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md).
[ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md).
## Schemas
Schemas can be inline, source-relative files, or files under an explicit root.
An optional `schema_root` may be set at the application root and in each
An optional `schema_root` may be set at the `promptkit` root and in each
collection. A collection's nonnull root takes precedence over the application
root for its prompts; an absent or null collection root falls back to the
application root. A nonnull blank root is invalid. There is no implicit

View File

@@ -16,10 +16,11 @@ contributor workflow and validation.
| `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, programmatic profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) |
| `examples/go-library/observe` | Demonstrates offline retry, observation, prepared notification, and separately budgeted coordinated proposal and assessment runs using two profiles on one finite backend. It is not a public library package. | [Example program](../../examples/go-library/observe/main.go) |
| `internal/backend` | Holds a defensive, immutable lookup of final backend definitions, including diagnostic metadata, plus capacity policies validated by the configuration adapter. | [Backend registry](../../internal/backend/registry.go) |
| `internal/configuration` | Loads root and namespaced resources through ConfigKit; validates final values, captures indexed resource views and source-relative prompt content, compiled templates, requirement metadata, identity inventories, backend and presence-aware execution profiles, and the read-only provenance inspection view. | [Typed loader](../../internal/configuration/load.go), [identity listing](../../internal/configuration/listing.go), [internal sources](sources.md#typed-configuration-loading) |
| `internal/configuration` | Supplies component rules and captures final shared settings and native inspection evidence into owned indexed resources, compiled templates, requirement metadata, identities, and execution profiles. | [Configuration capture](../../internal/configuration/load.go), [identity listing](../../internal/configuration/listing.go), [internal sources](sources.md#typed-configuration-loading) |
| `internal/settings` | Declares the shared public configuration data model exposed through root aliases under ADR 0002; contains no loading or execution logic. | [Settings declarations](../../internal/settings/settings.go), [ADR 0002](../adr/0002-shared-configuration-data-model.md) |
| `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) |
| `internal/domain` | Defines internal framework values for requests, immutable conversation exchanges, artifacts, prompt definitions, requirement inspection, profiles, execution targets, rendering, generation, validation, and source-neutral smoke diagnostics, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, output contracts, and resource-identity syntax and qualification. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [exchange storage](../../internal/domain/exchange.go), [requirement values](../../internal/domain/requirements.go), [endpoint invariant](../../internal/domain/endpoint.go) |
| `internal/engine` | Assembles caller-selected configuration into one snapshot, then constructs shared capacity, rendering, validation, generation, repair, the ordinary runner, and the smoke tester for each engine. Immutable namespace views share those collaborators and qualify caller-supplied execution, inspection, and diagnostic selections without rewriting captured references. Built-in engines provide the diagnostic HTTP collaborator; injected-client engines do not. It delegates resource inspection and identity listing directly to the captured configuration rather than the runner. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#typed-configuration-loading), [internal runner](runner.md) |
| `internal/engine` | Assembles an already captured configuration into shared capacity, rendering, validation, generation, repair, runner, and smoke-test collaborators. Immutable namespace views share those collaborators and qualify selections without rewriting captured references. Built-in engines provide the diagnostic HTTP collaborator; injected-client engines do not. It delegates resource inspection and listing to the capture. | [Engine assembly](../../internal/engine/engine.go), [internal sources](sources.md#typed-configuration-loading), [internal runner](runner.md) |
| `internal/generation` | Coordinates frozen built-in HTTP attempts and one-shot injected calls through active backend permits, including bounded status retries, cancellable backoff, ordinary attempt observations, and invocation-local evidence for diagnostics. | [Internal generation coordination](generation.md) |
| `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) |
| `internal/filecatalog` | Provides deterministic YAML discovery and path helpers for operating-system filesystems and `fs.FS` sources. | [File catalog](../../internal/filecatalog/catalog.go) |

View File

@@ -30,6 +30,11 @@ internal callers and tests.
Each invocation carries its state in request, prepared-run, and result values.
The runner has no durable run or session store.
Request output-contract replacements carry an optional repair budget. The
runner resolves that budget from the replacement's validation mode before
building the concrete validation plan; prepared execution retains the resolved
integer. Configured budgets are already resolved by the configuration adapter.
Captured exchanges are immutable parent-linked domain values. Each holds only
its new rendered suffix, final assistant message, and run identities; flattening
iteratively fills a single detached message buffer for preparation or projects

View File

@@ -10,38 +10,24 @@ source semantics. Internal packages are not consumer APIs.
## Typed Configuration Loading
`internal/configuration` is the single adapter from ConfigKit's final
effective configuration to execution-owned definitions and resource views. It performs one
layered load, captures the needed effective presence, records
field-level normalization and derived defaults during resolution, and validates all effective
root and collection backend, profile, and prompt values. Replaced lower-layer
domain values are not separately validated. It indexes root resources under
their unqualified IDs and collection resources under their full
`namespace/local-key` IDs while retaining ConfigKit's resolved tree. It builds an immutable backend index and presence-aware profile
targets, applying final backend defaults only after profile inheritance. Runtime
lookups use those final indexes and exact stored references; they do not rewrite
or resolve resources from ConfigKit source history. The runtime/domain packages
do not depend on ConfigKit.
The root facade composes Promptkit rules into a ConfigKit definition. An
application-owned load or the standalone constructor produces final settings
at `/promptkit`; `internal/configuration` captures execution-owned resources
from those settings and a native inspection view without another load.
`internal/settings` supplies the shared data declarations exposed through
root aliases. The adapter records normalization and validates effective values,
then uses one metadata snapshot for presence and source origins. Runtime/domain
packages do not depend on ConfigKit.
ConfigKit owns source headers, imports, composition, and source evidence.
Promptkit does not preparse contributions: it validates the final effective
values once, captures the indexed identities and their original resource
contexts, and retains ConfigKit's resolved result for explicit operator inspection.
Accepted non-main source headers are consumed during composition; the main
source declaration remains available in that inspection view. Collection
release labels are descriptive metadata, not selection inputs. The
[format reference](../formats.md#source-headers-collections-and-resource-ids)
owns the exact source-header and collection contracts.
The `ConfigurationInspection.Diff` facade method compares two retained results
through a private wrapper and a narrow `internal/configuration.Diff` bridge.
The wrapper keeps `Result[document]` inside the adapter; the bridge delegates
once to ConfigKit and returns its public difference records. Comparison
uses only frozen effective values and does not reopen sources, resolve runtime
credentials, or enter the execution path. ConfigKit applies sensitivity from
both results; reports may still contain ordinary application data. See the
[consumer comparison guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration)
and ConfigKit's [comparison contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md#effective-configuration-diffs).
Capture detaches known settings, builds indexed definitions and profile targets,
and binds source-relative resources from the effective field's source context.
It retains a frozen native focused view and copied diagnostics, not the mutable
application result. Configuration inspection delegates reporting, redaction,
history and comparison to ConfigKit; explicit queries and metadata retain
whole-application paths and evidence. Runtime never derives values from history.
The [format reference](../formats.md#source-headers-collections-and-resource-ids)
owns the configuration contract and the [consumer guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration)
describes reporting scope.
After resource materialization and effective-profile snapshot construction, the
adapter captures lexically ordered identity inventories for backends, profiles,
@@ -52,15 +38,15 @@ captured values without consulting ConfigKit or copying resource definitions.
The root `DirectoryInputs` and `FilesystemInputs` helpers discover sorted YAML
files under an explicit root, provide resource context, and leave imports
disabled. Each returned slice belongs to one strict-composition group; file
order does not confer priority. Engine assembly prepends a dedicated embedded
OpenRouter underlay unless disabled, without modifying caller-owned slices.
order does not confer priority. The standalone facade prepends a dedicated
embedded OpenRouter underlay unless disabled, without modifying caller-owned slices.
Caller underlays are composed in their given
order, followed by the optional main input. The
[configuration tests](../../internal/configuration/load_test.go) exercise the
real loader and final-value handoff.
The public `CollectionInput` helper mounts one caller-selected source at
`collections/<namespace>` and enables ConfigKit imports for that input. The
`/promptkit/collections/<namespace>` and enables ConfigKit imports for that input. The
helper does not read the source; ConfigKit retains responsibility for loading,
composition, imports, and source-local resource context. Imported or inherited
`content_file` values continue resolving relative to the source that contributed
@@ -83,7 +69,7 @@ declaration; absent and null fields remain distinguishable from explicit
strings, including empty strings. It closes content-file handles before
returning and retains no source capability for public inspection.
Prompt materialization shares a lazy metadata snapshot across root and collection
Prompt materialization shares one metadata snapshot across root and collection
resources during construction, avoiding a full metadata copy per collection.
Input metadata, message content and templates, and output contracts are captured
separately before the definition, inspection, and hash are assembled. Schema

View File

@@ -51,9 +51,10 @@ The [internal component overview](../internal/overview.md) owns the inventory
of implemented packages and their concrete responsibilities. This policy owns
the boundaries and dependency rules those components must preserve.
The internal engine composes caller-selected ConfigKit inputs once, then
assembles the captured definitions, capacity manager, renderer, validator,
outbound client, and use-case runner. The configuration adapter interprets and
The facade either registers Promptkit rules in the application's ConfigKit load
or performs one standalone load, then passes captured configuration to the
internal engine. The internal engine assembles the captured definitions,
capacity manager, renderer, validator, outbound client, and use-case runner. The configuration adapter interprets and
validates only the final effective values, including presence, null, and
resource context. It retains source history for explicit operator inspection,
not for validation or a second resolution pass. The root facade translates

View File

@@ -642,6 +642,10 @@ consumer examples with no paid or live inference calls.
## Stage 16 — Update Canonical Contracts And Migration Guidance
Status: complete. Canonical guides, GoDoc, architecture, and internal component
descriptions cover the new configuration and repair contracts; local links and
focused tests passed.
Focus: GoDoc, `README.md`, `docs/formats.md`,
`docs/consumers/pkg-promptkit.md`, `docs/consumers/configuration-migration.md`,
and `docs/internal/{overview,sources,runner}.md`.

View File

@@ -165,7 +165,8 @@ type engineOptions struct {
}
// WithBundledOpenRouter enables or disables the built-in OpenRouter underlay.
// It is enabled by default; when repeated, the last option wins.
// It is enabled by default for NewEngine; when repeated, the last option wins.
// It has no effect on an already resolved NewFromConfig handoff.
func WithBundledOpenRouter(enabled bool) Option {
return optionFunc(func(options *engineOptions) error {
options.disableBundledOpenRouter = !enabled
@@ -263,13 +264,20 @@ type Configuration interface {
// RuntimeConfig selects runtime-only client and retry settings for NewFromConfig.
// Its fields have the same semantics as the corresponding Config fields.
type RuntimeConfig struct {
Timeout time.Duration
HTTPClient *http.Client
// Timeout is the built-in client's transport timeout fallback.
Timeout time.Duration
// HTTPClient is cloned for the built-in client and ignored by injected clients.
HTTPClient *http.Client
// TransientRetries selects additional built-in attempts; nil defaults to two.
TransientRetries *int
}
// NewFromConfig captures resources from an application-owned completed load.
// The application must register PromptKit rules during that load. Callers must
// The application must register PromptKit rules during that load, using Configure
// or equivalent explicit composition. Missing or nil selected settings contribute
// no resources; Settings and *Settings are accepted, while other nonnil types,
// nil results, and unavailable inspection views fail with ErrInvalidConfig.
// Callers must
// not mutate its selected settings between loading and this handoff. After
// construction, later settings mutations do not alter the engine. This method
// does not load sources, rerun callbacks, or select bundled underlays.

View File

@@ -40,6 +40,7 @@ type PromptCacheControlConfig struct{ Type, TTL *string }
// PromptOutputConfig supplies optional output contract source fields. Schema
// supplies a nonnull inline value, and SchemaFile and SchemaPath are reference
// selections. Raw ConfigKit mappings can express explicit null to clear one.
// A nil RepairAttempts omits the budget; a pointer to zero disables repair.
type PromptOutputConfig struct {
Format, ValidationMode, SchemaPath, SchemaFile *string
Schema any

View File

@@ -77,6 +77,7 @@ type PromptCacheControlInspection struct {
// PromptOutputInspection describes a prompt's configured output contract.
// SchemaFile and SchemaPath are references and are not loaded by inspection.
// RepairAttempts is the resolved budget and is emitted even when zero.
type PromptOutputInspection struct {
Format OutputFormat `json:"format" yaml:"format"`
ValidationMode ValidationMode `json:"validation_mode" yaml:"validation_mode"`

View File

@@ -492,8 +492,8 @@ type ExecutionTargetPresence struct {
// OutputContract describes resolved output and validation requirements.
//
// A non-nil RunRequest.Validation replaces the complete prompt contract. It
// does not merge fields. The public Engine performs bounded correction after a
// A non-nil RunRequest.Validation input replaces the complete prompt contract.
// The public Engine performs bounded correction after a
// failed eligible validation when RepairAttempts is positive. A JSON Schema
// request replacement requires exactly one of Schema and SchemaPath; other
// modes ignore them. A replacement uses the prompt's configured root for
@@ -519,15 +519,24 @@ type OutputContract struct {
RepairAttempts int `json:"repair_attempts"`
}
// OutputContractInput replaces a prompt's complete output contract. An omitted
// repair budget defaults to one for active validation and zero for none;
// an explicit zero disables repair. Schema selection follows OutputContract.
// OutputContractInput replaces a prompt's complete output contract without
// merging fields. A nil repair budget defaults to one for basic, json, and
// json_schema validation, or zero for none; an explicit zero disables repair.
// The budget is resolved independently of the prompt's configured budget.
// Each repair can add a generation call, latency, and usage and may still fail.
// Schema selection follows OutputContract. Empty Format defaults to text;
// ValidationMode must be set. Valid budgets range from zero to three.
type OutputContractInput struct {
Format OutputFormat `json:"format"`
// Format selects artifact metadata; empty defaults to text.
Format OutputFormat `json:"format"`
// ValidationMode selects the content check and is required.
ValidationMode ValidationMode `json:"validation_mode"`
Schema any `json:"schema,omitempty"`
SchemaPath string `json:"schema_path"`
RepairAttempts *int `json:"repair_attempts,omitempty"`
// Schema is an inline JSON Schema selected for json_schema mode.
Schema any `json:"schema,omitempty"`
// SchemaPath selects a schema under the prompt's configured root.
SchemaPath string `json:"schema_path"`
// RepairAttempts is an optional additional generation-call budget.
RepairAttempts *int `json:"repair_attempts,omitempty"`
}
// ValidationResult represents a completed output check and has a stable JSON