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.
|
||||
|
||||
|
||||
142
docs/formats.md
142
docs/formats.md
@@ -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
|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user