Document shared configuration and repair defaults
This commit is contained in:
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
|
||||
|
||||
Reference in New Issue
Block a user