base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 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 schema definitions. The [Go consumer guide](consumers/pkg-promptkit.md) shows
how to select sources and use an engine; the how to select sources and use an engine; the
[OpenAI-compatible integration contract](integrations/openai-compatible-chat.md) [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. owns the generic YAML grammar, imports, layering, inheritance, and diagnostics.
This reference describes what Promptkit does with the final effective values. This reference describes what Promptkit does with the final effective values.
A configuration document may contain keyed top-level `backends`, `profiles`, A configuration document may contain top-level `backends`, `profiles`, and
and `prompts` mappings, plus a `collections` mapping of namespaced resource `prompts` lists, plus a `collections` mapping of namespaced resource groups.
groups. Resource keys are literal IDs, not filename-derived identities. Each Each resource has an explicit literal `id`, not a filename-derived identity.
prompt ID maps directly to one definition; an optional `version` string is IDs and references must be nonblank and remain exact: Promptkit does not trim or
descriptive metadata, not a selection key. Keys and references must be nonblank re-key them. Unknown fields are errors. Promptkit installs no provider or
and remain exact: Promptkit does not trim or re-key them. Old embedded `id` and profile catalog; callers select the definitions they need.
`base_profile` fields are invalid. Unknown fields are errors. Promptkit installs
no provider or profile catalog; callers select the definitions they need.
```yaml ```yaml
backends: backends:
local: - id: local
endpoint: http://localhost:8000/v1 endpoint: http://localhost:8000/v1
concurrency_limit: 2 concurrency_limit: 2
profiles: profiles:
local-summary: - id: local-summary
backend: local backend: local
model: example-model model: example-model
prompts: prompts:
meeting.summary: - id: meeting.summary
version: "1.0.0"
default_profile: local-summary default_profile: local-summary
messages: messages:
- role: user - role: user
@@ -42,17 +39,17 @@ collections:
support: support:
release_version: "1.4.0" release_version: "1.4.0"
backends: backends:
offline: - id: offline
endpoint: https://example.invalid/v1 endpoint: https://example.invalid/v1
profiles: profiles:
base: - id: base
backend: support/offline backend: support/offline
model: offline-model model: offline-model
fast: - id: fast
extends: base extends: {id: base}
timeout_seconds: 30 timeout_seconds: 30
prompts: prompts:
answer: - id: answer
default_profile: support/fast default_profile: support/fast
messages: messages:
- role: user - role: user
@@ -66,31 +63,33 @@ collections:
An input may omit a source header. When present, the source-root `version` is 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 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 `"2"` or strict decimal integer `2`; null and other values are invalid. This
header is distinct from a prompt's nested `version` label and a collection's header is distinct from a collection's `release_version` and ConfigKit's own
`release_version`. ConfigKit checks and consumes accepted headers on non-main software version. ConfigKit checks and consumes accepted headers on non-main
inputs; a declaration on the main input remains visible in explicit inputs; a declaration on the main input remains visible in explicit
configuration inspection. Headerless inputs still undergo ordinary final-value configuration inspection. Headerless inputs still undergo ordinary final-value
validation. ConfigKit owns generic import and source-history behavior. 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 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 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 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. name their intended exact ID; mounting a source does not rewrite references.
For example, the `support/fast` profile above stores `support/offline` as its For example, the `support/fast` profile above stores `support/offline` as its
backend ID. In `collections.support.profiles.fast`, ConfigKit `extends: base` backend ID. `extends: {id: base}` refers to a sibling in the same resource
refers to a sibling profile in that same mapping. It is not a qualified or list. It is not a qualified or cross-collection reference.
cross-collection reference.
`release_version` and prompt `version` are optional opaque labels. Absent or `release_version` is an optional opaque collection label. Absent or null means
null means no label; an explicitly empty string is retained as a declared no label; an explicitly empty string is retained. It does not select a resource
label. Neither label selects a resource or changes execution. Runtime lookups or change execution. Runtime lookups
use the captured effective resource indexes. `InspectConfiguration` is an use the captured effective resource indexes. `InspectConfiguration` is an
explicit operator view of effective settings and provenance; source history is explicit operator view of composed settings and provenance. Normalization and
not a second runtime resolver, and the retained effective shape is not flattened defaults appear in Promptkit's interpreted execution views, not as changes to
or rewritten into those indexes. 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 For examples of explicitly selecting native collection inputs and inspecting
inventories, see the [consumer guide](consumers/pkg-promptkit.md) and its 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 ## 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 ```yaml
prompts: prompts:
meeting.summary: - id: meeting.summary
version: "1.0.0"
default_profile: local-summary default_profile: local-summary
description: Summarize a synthetic meeting note. description: Summarize a synthetic meeting note.
session_id: '{{.session}}' session_id: '{{.session}}'
@@ -237,7 +235,8 @@ It may contain `default_profile`, `reachability`, and `authentication`:
```yaml ```yaml
backends: backends:
openrouter: - id: openrouter
endpoint: https://openrouter.ai/api/v1
smoke_tests: smoke_tests:
default_profile: application-profile default_profile: application-profile
reachability: reachability:
@@ -266,21 +265,22 @@ These values are configuration only: engine construction does not contact a
backend. backend.
These fields are resolved through the ordinary ConfigKit source layers before These fields are resolved through the ordinary ConfigKit source layers before
Promptkit validates the final effective values. A higher-priority mapping can Promptkit validates the final effective values. Sibling inheritance can overlay
override individual nested fields; an explicit null can clear the whole individual nested fields; a later same-ID resource replaces the whole record.
`smoke_tests` block or one of its nested objects. An endpoint set to null uses 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 its documented fallback, while an explicit blank endpoint is invalid. The
metadata does not change ordinary generation credential requirements or metadata does not change ordinary generation credential requirements or
provider settings. provider settings.
## Profile Definitions ## 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`: `extends`:
```yaml ```yaml
profiles: profiles:
local-summary: - id: local-summary
backend: local backend: local
model: example-model model: example-model
temperature: 0.2 temperature: 0.2
@@ -288,8 +288,8 @@ profiles:
timeout_seconds: 90 timeout_seconds: 90
extra_params: extra_params:
provider_option: enabled provider_option: enabled
local-summary-fast: - id: local-summary-fast
extends: local-summary extends: {id: local-summary}
timeout_seconds: 30 timeout_seconds: 30
reasoning_effort: low 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. on an input. Single files can use ConfigKit inputs directly.
Root backends, profiles, and prompts, as well as collection declarations and 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 mounts one explicitly selected source at a collection destination and enables
ConfigKit imports for that input; it does not discover or select sources. 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 A request `ProfileID` takes precedence over a prompt `default_profile`; if
neither is selected, preparation fails. Exact profile inspection selects one neither is selected, preparation fails. Exact profile inspection selects one
explicit ID and does not consult a prompt default. explicit ID and does not consult a prompt default.
### Profile Inheritance ### Resource Inheritance
ConfigKit resolves `extends` on effective profile definitions. One profile ConfigKit resolves `extends: {id: parent}` for backends, profiles, and prompts.
may inherit a sibling profile by local key in the same root or collection Each child inherits a surviving sibling in the same root or collection list;
mapping; collection inheritance cannot cross namespaces. Presence, explicit 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 null, and recursively merged maps determine the final fields. Other resource
references are exact IDs and use their qualified form when they select a references are exact IDs and use their qualified form when they select a
collection resource. There is no Promptkit-specific depth limit or second collection resource. There is no Promptkit-specific depth limit or second
base-chain resolver. Missing references and cycles fail at construction. For base-chain resolver. Missing references and cycles fail at construction. For
generic inheritance and layer mechanics, consult 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 ## 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. propagate to the caller.
Resolved prompt and profile IDs are the exact runtime identities selected for Resolved prompt and profile IDs are the exact runtime identities selected for
the invocation, including namespace qualification when supplied by an engine the invocation, including namespace qualification when supplied by an engine
view. A prompt's optional version label is descriptive metadata, not a view.
selection key.
Per-operation callbacks are ordered and synchronous; different operations may Per-operation callbacks are ordered and synchronous; different operations may
invoke the same callback concurrently. The recorder marks each measured phase's invoke the same callback concurrently. The recorder marks each measured phase's
end before delivery, so callback work does not inflate provider duration. 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 before they reach the runner. The runner therefore selects captured prompts and
profiles by the resulting exact runtime IDs. Already-qualified selections pass profiles by the resulting exact runtime IDs. Already-qualified selections pass
through, while configured defaults and stored references are used as authored through, while configured defaults and stored references are used as authored
and are not requalified. Prompt version labels are returned as optional and are not requalified.
descriptive metadata; they are not prompt selectors.
Ordinary preparation selects the full prompt definition and construction-time Ordinary preparation selects the full prompt definition and construction-time
hash. It retains its early request-ID check before direct-session 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 `internal/configuration` is the single adapter from ConfigKit's final
effective configuration to execution-owned definitions. It performs one effective configuration to execution-owned definitions. It performs one
layered load, captures effective presence (including explicit null), records layered load, captures effective presence (including explicit null), builds
normalization and defaults through resolution, and validates all effective detached normalized interpretations during validation, and validates all effective
root and collection backend, profile, and prompt values. Replaced lower-layer root and collection backend, profile, and prompt values. Replaced lower-layer
domain values are not separately validated. It indexes root resources under domain values are not separately validated. It indexes root resources under
their unqualified IDs and collection resources under their full 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. ConfigKit owns source headers, imports, composition, and source evidence.
Promptkit does not preparse contributions: it validates the final effective Promptkit does not preparse contributions: it validates the final effective
values once, captures the indexed identities and their original resource 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 Accepted non-main source headers are consumed during composition; the main
source declaration remains available in that inspection view. Prompt and source declaration remains available in that inspection view. Collection
collection release labels are descriptive metadata, not selection inputs. The release labels are descriptive metadata, not selection inputs. The
[format reference](../formats.md#source-headers-collections-and-resource-ids) [format reference](../formats.md#source-headers-collections-and-resource-ids)
owns the exact source-header and collection contracts. owns the exact source-header and collection contracts.
The `ConfigurationInspection.Diff` facade method compares two retained results The `ConfigurationInspection.Diff` facade method compares two retained results
through a private wrapper and a narrow `internal/configuration.Diff` bridge. through a private wrapper and a narrow `internal/configuration.Diff` bridge.
The wrapper keeps `Result[document]` inside the adapter; the bridge delegates 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 uses only frozen effective values and does not reopen sources, resolve runtime
credentials, or enter the execution path. ConfigKit applies sensitivity from credentials, or enter the execution path. ConfigKit applies sensitivity from
both results; reports may still contain ordinary application data. See the both results; reports may still contain ordinary application data. See the
[consumer comparison guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration) [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 After resource materialization and effective-profile snapshot construction, the
adapter captures lexically ordered identity inventories for backends, profiles, 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 Prompt materialization shares a lazy metadata snapshot across root and collection
resources during construction, avoiding a full metadata copy per collection. resources during construction, avoiding a full metadata copy per collection.
Role and cache-control normalization is applied to execution-owned message Normalization and defaults are applied to execution-owned interpretations,
copies. ConfigKit v0.8.0 retains effective input message metadata and its including message roles and cache controls. ConfigKit retains the composed
resource origins; recording a sequence-wide normalization in the retained values and origins, rather than synthetic Promptkit normalization events. List
configuration would replace origins of unchanged content-file fields. 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 The runner selects full definitions from this index for preparation and uses
captured prompt metadata for `InspectPrompt` and `InspectRequirements`; the captured prompt metadata for `InspectPrompt` and `InspectRequirements`; the
@@ -142,7 +144,7 @@ change rendering behavior.
## Profiles ## Profiles
ConfigKit resolves profile inheritance before the handoff. Within a collection, 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 The configuration adapter validates final effective resource references and
field values, then builds target field values, then builds target
snapshots with backend defaults and presence/suppression state. A profile can 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 Validation: compare every current format example with the actual implemented
schema and owning tests. Exact Go declarations remain the API contract owner. 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 ## Stage 21: Document One Coherent Consumer Migration
Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README, Scope: `docs/consumers/configuration-migration.md`, the Go consumer guide, README,