base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Document identified resource formats and interpretation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-02 12:57:20 +00:00
parent 0eee3ec962
commit 2ccbee3758
5 changed files with 75 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
docs/formats.md
View File

@@ -6,31 +6,28 @@ 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://gitea.maximumdirect.net/eric/ConfigKit)
owns outbound wire behavior. [ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.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 keyed top-level `backends`, `profiles`,
and `prompts` mappings, plus a `collections` mapping of namespaced resource
groups. Resource keys are literal IDs, not filename-derived identities. Each
prompt ID maps directly to one definition; an optional `version` string is
descriptive metadata, not a selection key. Keys and references must be nonblank
and remain exact: Promptkit does not trim or re-key them. Old embedded `id` and
`base_profile` fields are invalid. Unknown fields are errors. Promptkit installs
no provider or profile catalog; callers select the definitions they need.
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 no provider or
profile catalog; callers select the definitions they need.
```yaml
backends:
local:
- id: local
endpoint: http://localhost:8000/v1
concurrency_limit: 2
profiles:
local-summary:
- id: local-summary
backend: local
model: example-model
prompts:
meeting.summary:
version: "1.0.0"
- id: meeting.summary
default_profile: local-summary
messages:
- role: user
@@ -42,17 +39,17 @@ collections:
support:
release_version: "1.4.0"
backends:
offline:
- id: offline
endpoint: https://example.invalid/v1
profiles:
base:
- id: base
backend: support/offline
model: offline-model
fast:
extends: base
- id: fast
extends: {id: base}
timeout_seconds: 30
prompts:
answer:
- id: answer
default_profile: support/fast
messages:
- role: user
@@ -66,31 +63,33 @@ collections:
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
`"1"` or strict decimal integer `1`; null and other values are invalid. This
header is distinct from a prompt's nested `version` label and a collection's
`release_version`. ConfigKit checks and consumes accepted headers on non-main
`"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.
The root resource mappings contain unqualified IDs. Each `collections` entry
The root resource lists contain unqualified IDs. Each `collections` entry
has a namespace key and may contain `release_version` plus the same three
resource mappings. Collection resource keys are local keys; their runtime IDs
resource lists. Collection resource IDs are local keys; their runtime IDs
are `<namespace>/<local-key>`. Root and collection keys may be the same. A
namespace and local key must be nonblank and slash-free, and references must
name their intended exact ID; mounting a source does not rewrite references.
For example, the `support/fast` profile above stores `support/offline` as its
backend ID. In `collections.support.profiles.fast`, ConfigKit `extends: base`
refers to a sibling profile in that same mapping. It is not a qualified or
cross-collection reference.
backend ID. `extends: {id: base}` refers to a sibling in the same resource
list. It is not a qualified or cross-collection reference.
`release_version` and prompt `version` are optional opaque labels. Absent or
null means no label; an explicitly empty string is retained as a declared
label. Neither label selects a resource or changes execution. Runtime lookups
`release_version` is an optional opaque collection label. Absent or null means
no label; an explicitly empty string is retained. It does not select a resource
or change execution. Runtime lookups
use the captured effective resource indexes. `InspectConfiguration` is an
explicit operator view of effective settings and provenance; source history is
not a second runtime resolver, and the retained effective shape is not flattened
or rewritten into those indexes.
explicit operator view of composed settings and provenance. Normalization and
defaults appear in Promptkit's interpreted execution views, not as changes to
that composed tree. Source history is not a second runtime resolver, and the
retained effective shape is not flattened or rewritten into those indexes.
For examples of explicitly selecting native collection inputs and inspecting
inventories, see the [consumer guide](consumers/pkg-promptkit.md) and its
@@ -116,12 +115,11 @@ see the consumer guide's [resource and collection listing](consumers/pkg-promptk
## Prompt Definitions
The `prompts` mapping selects a literal prompt ID whose value is the definition:
The `prompts` list contains definitions selected by their literal IDs:
```yaml
prompts:
meeting.summary:
version: "1.0.0"
- id: meeting.summary
default_profile: local-summary
description: Summarize a synthetic meeting note.
session_id: '{{.session}}'
@@ -237,7 +235,8 @@ It may contain `default_profile`, `reachability`, and `authentication`:
```yaml
backends:
openrouter:
- id: openrouter
endpoint: https://openrouter.ai/api/v1
smoke_tests:
default_profile: application-profile
reachability:
@@ -266,21 +265,22 @@ These values are configuration only: engine construction does not contact a
backend.
These fields are resolved through the ordinary ConfigKit source layers before
Promptkit validates the final effective values. A higher-priority mapping can
override individual nested fields; an explicit null can clear the whole
`smoke_tests` block or one of its nested objects. An endpoint set to null uses
Promptkit validates the final effective values. Sibling inheritance can overlay
individual nested fields; a later same-ID resource replaces the whole record.
An explicit null can clear the whole `smoke_tests` block or one of its nested
objects. An endpoint set to null uses
its documented fallback, while an explicit blank endpoint is invalid. The
metadata does not change ordinary generation credential requirements or
provider settings.
## Profile Definitions
Profiles are keyed by literal ID and may inherit a named parent with
Profiles have literal IDs and may inherit a sibling parent with
`extends`:
```yaml
profiles:
local-summary:
- id: local-summary
backend: local
model: example-model
temperature: 0.2
@@ -288,8 +288,8 @@ profiles:
timeout_seconds: 90
extra_params:
provider_option: enabled
local-summary-fast:
extends: local-summary
- id: local-summary-fast
extends: {id: local-summary}
timeout_seconds: 30
reasoning_effort: low
```
@@ -343,25 +343,27 @@ nothing. Imports are disabled by these helpers unless the caller enables them
on an input. Single files can use ConfigKit inputs directly.
Root backends, profiles, and prompts, as well as collection declarations and
their resource mappings, follow these same source rules. `CollectionInput`
their resource lists, follow these same source rules. `CollectionInput`
mounts one explicitly selected source at a collection destination and enables
ConfigKit imports for that input; it does not discover or select sources.
A later profile or backend can change individual fields of a lower definition.
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
neither is selected, preparation fails. Exact profile inspection selects one
explicit ID and does not consult a prompt default.
### Profile Inheritance
### Resource Inheritance
ConfigKit resolves `extends` on effective profile definitions. One profile
may inherit a sibling profile by local key in the same root or collection
mapping; collection inheritance cannot cross namespaces. Presence, explicit
ConfigKit resolves `extends: {id: parent}` for backends, profiles, and prompts.
Each child inherits a surviving sibling in the same root or collection list;
collection inheritance cannot cross namespaces. Parents are ordinary validated
resources, and profiles may remain partial until request completion. Presence, explicit
null, and recursively merged maps determine the final fields. Other resource
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://gitea.maximumdirect.net/eric/ConfigKit).
[ConfigKit](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md).
## Schemas