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

Document the consumer migration to identified resources

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-02 12:58:39 +00:00
parent 2ccbee3758
commit b0bfe857fe
5 changed files with 118 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/consumers/pkg-promptkit.md
View File

@@ -15,6 +15,9 @@ Import the package as:
import "gitea.maximumdirect.net/eric/promptkit"
```
Configuration APIs use `go.maximumdirect.net/configkit` v1.0.0. Its types are
not interchangeable with the old ConfigKit module path.
The maintained [offline preparation example](../../examples/go-library/prepare/main.go)
demonstrates explicit collection composition and inventory. Applications
adapting older provider or versioned-prompt configuration can use the
@@ -28,7 +31,8 @@ programs.
## Go Compatibility
The `go` directive in the selected release's [module metadata](../../go.mod)
declares its minimum supported consumer Go version. Maintainers build and
declares its minimum supported consumer Go version, currently Go 1.27.0.
Maintainers build and
validate releases with the locally selected Go patch release; the minimum
does not simply track that patch version.
@@ -108,8 +112,8 @@ defaults, err := promptkit.FilesystemInputs("embedded defaults", applicationFS,
if err != nil { return err }
operator, err := promptkit.DirectoryInputs(operatorDirectory)
if err != nil { return err }
profile := promptkit.ProfileSource("application choices", map[string]promptkit.ProfileConfig{
"summary": {Model: &selectedModel},
profile := promptkit.ProfileSource("application choices", []promptkit.ProfileConfig{
{ID: "summary", Endpoint: &selectedEndpoint, Model: &selectedModel},
})
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{
Underlays: []configkit.Underlay{
@@ -120,7 +124,9 @@ engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.Configura
}})
```
Only add the operator group when the application selects that directory; an
Each later same-ID resource replaces the complete earlier record; use a distinct
inherited sibling for field-level customization. Only add the operator group
when the application selects that directory; an
explicitly selected missing or unreadable root is an error. Each helper finds
`.yaml` and `.yml` files recursively and disables imports by default. The
caller may enable imports on individual inputs. A nil `Sources.Main` is an
@@ -131,8 +137,8 @@ labeled mapping as an input. A mapping owns a snapshot of supported values:
```go
document := configkit.Mapping("application configuration", map[string]any{
"profiles": map[string]any{
"local-summary": map[string]any{
"profiles": []any{
map[string]any{"id": "local-summary",
"backend": "local", "model": "example-model",
"temperature": nil, // Suppress an inherited provider control.
},
@@ -202,15 +208,15 @@ sensitive application data.
## Inspect The Captured Configuration
Use [`Engine.InspectConfiguration`](../../configuration_inspection.go) for an
operator-selected report of effective configuration, source descriptions,
diagnostics, and path history. Configuration inspection uses the collection's
nested configuration path rather than its qualified runtime ID. For profile
`team/summary`, construct the semantic path with `configkit.Keys`:
operator-selected report of composed configuration, source descriptions,
diagnostics, and path history. Configuration inspection uses list indexes in
the collection's nested path rather than qualified runtime IDs. For a profile
at index `i` in collection `team`, construct the path with `configkit.Keys`:
```go
view, err := engine.InspectConfiguration()
if err != nil { return err }
path := configkit.Keys("collections", "team", "profiles", "summary", "model")
path := configkit.Keys("collections", "team", "profiles").Index(i).Key("model")
explanation, found := view.Explain(path)
if found && explanation.Effective.Redacted {
// Apply the application's disclosure policy before sharing the report.
@@ -221,8 +227,9 @@ if found && explanation.Effective.Redacted {
the application decides whether those reports may be disclosed. Credential-
shaped provider keys are redacted, but arbitrary prompt and provider content
is not necessarily safe to share. Inspection uses the engine's captured result
and does not reopen sources or resolve credentials. `InspectProfile` instead
shows backend-completed execution settings for one profile, and `Prepare` or
and does not reopen sources or resolve credentials. It retains composed values
and provenance rather than Promptkit's normalized/defaulted interpretation.
`InspectProfile` instead shows backend-completed execution settings for one profile, and `Prepare` or
`PreparedExecution.Details` shows request-specific rendered messages, inputs,
and validation resources. None of those views is a substitute for the others.
@@ -253,7 +260,7 @@ for _, difference := range differences {
```
See the [`ConfigurationInspection.Diff` GoDoc](../../configuration_inspection.go)
and ConfigKit's [v0.8.0 effective-configuration diff guidance](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/docs/config.md#effective-configuration-diffs)
and ConfigKit's [v1.0.0 effective-configuration diff guidance](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/config.md#effective-configuration-diffs)
for the exact comparison contract. The operation compares only frozen effective
configuration values: it does not reread external files or compare their
contents, resolved credential contents, later execution preparation, or
@@ -621,7 +628,7 @@ copy, and credential behavior. The
interact with prompt definitions, layered profiles, built-ins, schemas, and
framework defaults.
For programmatic profiles, use [`ProfileSource`](../../profiles.go) with keyed
For programmatic profiles, use [`ProfileSource`](../../profiles.go) with identified
`ProfileConfig` values. Nil fields are omitted; pointers preserve explicit
zero, false, and blank values. Raw `configkit.Mapping` expresses explicit null.
@@ -634,13 +641,13 @@ and `WithBackend` options have no compatibility wrappers. Use
`DirectoryInputs` or `FilesystemInputs` for a strict-composition file group,
ConfigKit file inputs for individual files, and `ProfileSource`,
`BackendSource`, or `configkit.Mapping` for programmatic values. Backend IDs
are keys in configuration, not registrations. Choose caller underlays in
are fields in configuration, not registrations. Choose caller underlays in
fallback-to-operator-to-programmatic order; use `Sources.Main` for one final
highest-priority input.
Move embedded IDs into keyed `profiles` and `prompts` maps; each prompt ID now
contains one installed definition, with any descriptive `version` label inside
that definition. Convert `base_profile` to ConfigKit `extends`. For the current
Move resource IDs into identified `backends`, `profiles`, and `prompts` lists;
each prompt ID identifies one installed definition without a version label.
Convert `base_profile` to ConfigKit `extends: {id: parent}`. For the current
collection identity mapping, ID-only prompt selection, and required
caller-owned choices, see the
[configuration migration guide](configuration-migration.md). Exact current
@@ -656,7 +663,7 @@ application selects. PromptKit does not install provider catalogs or built-in
profile inventories; conventional backend ID constants are names only. Define
the model, endpoint, credentials lookup, and settings that your application
intends to support. A profile may inherit a sibling profile by its local key in
the same root or collection mapping; its backend reference uses the exact
the same root or collection list; its backend reference uses the exact
configured identity. Caller-selected source layers determine the final values. The
[format reference](../formats.md) describes the definition fields and
composition rules.
@@ -729,8 +736,8 @@ it and shared backend identity or capacity policy is unnecessary:
```go
endpoint, model := "http://localhost:8000/v1", "example-model"
profile := promptkit.ProfileSource("local profile", map[string]promptkit.ProfileConfig{
"local-summary": {Endpoint: &endpoint, Model: &model},
profile := promptkit.ProfileSource("local profile", []promptkit.ProfileConfig{
{ID: "local-summary", Endpoint: &endpoint, Model: &model},
})
// Add configkit.Input{Source: profile} to a caller underlay.
```
@@ -745,11 +752,13 @@ identity, endpoint, and concurrency limit:
```go
backendID, model := promptkit.BackendLocal, "example-model"
backend := promptkit.BackendSource("local backend", map[string]promptkit.BackendConfig{
backendID: promptkit.LocalBackend("http://localhost:8000/v1", 2),
localBackend := promptkit.LocalBackend("http://localhost:8000/v1", 2)
localBackend.ID = backendID
backend := promptkit.BackendSource("local backend", []promptkit.BackendConfig{
localBackend,
})
profile := promptkit.ProfileSource("local profile", map[string]promptkit.ProfileConfig{
"local-summary": {Backend: &backendID, Model: &model},
profile := promptkit.ProfileSource("local profile", []promptkit.ProfileConfig{
{ID: "local-summary", Backend: &backendID, Model: &model},
})
// Add both sources as inputs in a caller underlay.
```
@@ -760,13 +769,14 @@ capacity of 1024.
#### Configure A Complete Backend
Use a keyed `BackendConfig` value for authentication, extra request parameters, an
Use an identified `BackendConfig` value for authentication, extra request parameters, an
explicit queue capacity, a custom ID, or multiple local endpoints:
```go
endpoint, keyName, limit, noWaiting := "http://gpu-host:8000/v1", "LOCAL_GPU_API_KEY", 2, 0
backend := promptkit.BackendSource("GPU backend", map[string]promptkit.BackendConfig{
"local-gpu": {
backend := promptkit.BackendSource("GPU backend", []promptkit.BackendConfig{
{
ID: "local-gpu",
Endpoint: &endpoint, APIKeyEnv: &keyName,
ConcurrencyLimit: &limit, QueueCapacity: &noWaiting,
ExtraParams: map[string]any{"provider_option": "enabled"},
@@ -775,7 +785,7 @@ backend := promptkit.BackendSource("GPU backend", map[string]promptkit.BackendCo
```
Place `backend` in a caller underlay and select `"local-gpu"` from a
`ProfileConfig.Backend` pointer or a keyed file profile. All backend
`ProfileConfig.Backend` pointer or an identified file profile. All backend
contributions use the same ConfigKit layering rules, including overlays of
maintained definitions. The [`BackendConfig` and `LocalBackend` GoDoc](../../backends.go)
defines exact omission and construction behavior.
@@ -805,7 +815,7 @@ backend := promptkit.BackendConfig{
}
```
The pointer distinguishes an explicit zero from omission. Use keyed
The pointer distinguishes an explicit zero from omission. Use identified
`BackendConfig` literals inside `BackendSource` for programmatic definitions.
Capacity belongs to one engine and the selected backend ID; endpoint-only
profiles and custom backends without a configured limit remain unrestricted.