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

3
docs/internal/observation.md
View File

@@ -25,8 +25,7 @@ other content. Events are values with no mutable containers. Callback panics
propagate to the caller.
Resolved prompt and profile IDs are the exact runtime identities selected for
the invocation, including namespace qualification when supplied by an engine
view. A prompt's optional version label is descriptive metadata, not a
selection key.
view.
Per-operation callbacks are ordered and synchronous; different operations may
invoke the same callback concurrently. The recorder marks each measured phase's
end before delivery, so callback work does not inflate provider duration.

3
docs/internal/runner.md
View File

@@ -36,8 +36,7 @@ The internal engine applies each namespace view to slashless caller selections
before they reach the runner. The runner therefore selects captured prompts and
profiles by the resulting exact runtime IDs. Already-qualified selections pass
through, while configured defaults and stored references are used as authored
and are not requalified. Prompt version labels are returned as optional
descriptive metadata; they are not prompt selectors.
and are not requalified.
Ordinary preparation selects the full prompt definition and construction-time
hash. It retains its early request-ID check before direct-session

26
docs/internal/sources.md
View File

@@ -12,8 +12,8 @@ source semantics. Internal packages are not consumer APIs.
`internal/configuration` is the single adapter from ConfigKit's final
effective configuration to execution-owned definitions. It performs one
layered load, captures effective presence (including explicit null), records
normalization and defaults through resolution, and validates all effective
layered load, captures effective presence (including explicit null), builds
detached normalized interpretations during validation, 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
@@ -27,22 +27,22 @@ 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 result for explicit operator inspection.
contexts, and retains ConfigKit's composed result for explicit operator inspection.
Accepted non-main source headers are consumed during composition; the main
source declaration remains available in that inspection view. Prompt and
collection release labels are descriptive metadata, not selection inputs. The
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 v0.8.0 and returns its public difference records. Comparison
once to ConfigKit v1.0.0 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 [v0.8.0 comparison contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/docs/config.md#effective-configuration-diffs).
and ConfigKit's [v1.0.0 comparison contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md#effective-configuration-diffs).
After resource materialization and effective-profile snapshot construction, the
adapter captures lexically ordered identity inventories for backends, profiles,
@@ -85,10 +85,12 @@ returning and retains no source capability for public inspection.
Prompt materialization shares a lazy metadata snapshot across root and collection
resources during construction, avoiding a full metadata copy per collection.
Role and cache-control normalization is applied to execution-owned message
copies. ConfigKit v0.8.0 retains effective input message metadata and its
resource origins; recording a sequence-wide normalization in the retained
configuration would replace origins of unchanged content-file fields.
Normalization and defaults are applied to execution-owned interpretations,
including message roles and cache controls. ConfigKit retains the composed
values and origins, rather than synthetic Promptkit normalization events. List
indexes identify fields for presence, validation, sensitivity, and resource
context; full IDs select captured runtime indexes. Recording a sequence-wide
normalization would replace origins of unchanged content-file fields.
The runner selects full definitions from this index for preparation and uses
captured prompt metadata for `InspectPrompt` and `InspectRequirements`; the
@@ -142,7 +144,7 @@ change rendering behavior.
## Profiles
ConfigKit resolves profile inheritance before the handoff. Within a collection,
`extends` names a sibling local key; it is not a cross-collection reference.
`extends: {id: parent}` names a sibling local ID; it is not a cross-collection reference.
The configuration adapter validates final effective resource references and
field values, then builds target
snapshots with backend defaults and presence/suppression state. A profile can

7
docs/roadmap/implementation.md
View File

@@ -833,6 +833,13 @@ documents whose descriptions changed.
Validation: compare every current format example with the actual implemented
schema and owning tests. Exact Go declarations remain the API contract owner.
Completion: the format reference now describes identified lists, header 2,
sibling inheritance, whole-record replacement, and collection labels. Internal
source, runner, and observation documentation now describe captured interpreted
values and unchanged ConfigKit provenance without prompt labels. Examples were
reviewed against the schema and passing loader/example tests; `git diff --check`
passed.
## Stage 21: Document One Coherent Consumer Migration
Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README,