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

@@ -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