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

Document resource inspection and source migrations

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-06 15:31:16 +00:00
parent ea31e71280
commit 19a0604874
8 changed files with 148 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -94,7 +94,7 @@ engine, err := promptkit.NewEngine(promptkit.Config{
For a single highest-priority document, set `Sources.Main` to a
`*configkit.Input`; omit it for ordinary layered construction. A single file
can use `configkit.File` directly. `ProfileSource`, `BackendSource`, and raw
can use `configkit.File` directly. `PromptSource`, `ProfileSource`, `BackendSource`, and raw
`configkit.Mapping` supply programmatic definitions. Schema and runtime
collaborator options remain available. Construction validates the final
effective configuration and captures referenced prompt content; construct a
@@ -177,8 +177,12 @@ input := configkit.Input{Source: document}
// Add input to a later underlay, or set Sources.Main = &input.
```
`ProfileSource` and `BackendSource` are smaller typed conveniences when null
is not needed. Their provider maps use ConfigKit Mapping input forms: built-in
`PromptSource`, `ProfileSource`, and `BackendSource` are typed conveniences when
null is not needed. Prompt and backend helpers, like profiles, support sibling
inheritance via `Extends`; partial records can be completed by other layers.
For relative prompt `content_file` references, supply the ordinary ConfigKit
`Input.Filesystem` context for that source. The helpers do not read files or
validate final definitions. Profile and backend provider maps use ConfigKit Mapping input forms: built-in
scalars, `[]any`, and `map[string]any` recursively. Convert `json.Number` or
typed containers explicitly to an appropriate supported value, choosing numeric
precision for your application. Mapping captures supported values immediately;
@@ -264,9 +268,10 @@ is not necessarily safe to share. Inspection uses the engine's captured result
and does not reopen sources or resolve credentials. It retains effective values,
including recorded field normalization and queue defaulting, alongside source
provenance.
`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.
`InspectPrompt`, `InspectProfile`, and `InspectBackend` instead show individual
resolved resources without backend-to-profile execution completion or provenance.
`Prepare` or `PreparedExecution.Details` shows completed request-specific settings,
rendered messages, inputs, and validation resources. None substitutes for the others.
To review changes between two independently captured configurations, compare
their inspection views:
@@ -380,8 +385,10 @@ if err != nil {
return err
}
for _, input := range inspection.Inputs {
// Compare the declared input with application configuration.
if inspection.Inputs != nil {
for _, input := range *inspection.Inputs {
// Compare the declared input with application configuration.
}
}
```
@@ -707,10 +714,9 @@ composition rules.
### Inspect A Profile Before Prompt Work
Use [`Engine.InspectProfile`](../../engine.go) to validate one configured
profile without constructing a synthetic prompt or placeholder inputs. It
resolves the profile's effective target but does not prepare or execute a
prompt:
Use [`Engine.InspectProfile`](../../engine.go) to inspect a resolved profile
without constructing a synthetic prompt or placeholder inputs. It reports the
profile's own fields, not a backend-completed target:
```go
inspection, err := engine.InspectProfile(ctx, profileID)
@@ -718,24 +724,48 @@ if err != nil {
return err
}
target := inspection.EffectiveModelParams
if inspection.APIKeyRequired {
if inspection.APIKeyRequired != nil && *inspection.APIKeyRequired {
// Arrange a usable direct or configured environment credential.
}
if target.APIKeyEnv != "" {
if inspection.APIKeyEnv != nil {
// This is the configured environment lookup source, not its value.
}
```
Use this configuration-time boundary when only the profile and its target need
checking. Use `Prepare` when the application also needs prompt, input, schema,
or rendering work; use prepared execution when that work must remain tied to a
later execution. A reported `APIKeyEnv` identifies a configured source, while
`APIKeyRequired` is the explicit requirement; both may be present. The
Use [`InspectBackend`](../../engine.go) to inspect the referenced backend
separately. Its diagnostics are configured metadata, not live checks or derived
destinations; `ErrBackendNotFound` identifies an absent backend. References in
all three resource reports remain as authored. Use `Prepare` for completed
request settings and rendering, or prepared execution when that work must remain
tied to later execution. A reported `APIKeyEnv` identifies a configured source,
not its value; `APIKeyRequired` can also be present. The
[credential format reference](../formats.md#credentials) and the method's
[GoDoc](../../engine.go) own the exact precedence, timing, result, and error
contracts.
Resource inspection pointers represent optional fields: nil is absent, while a
non-nil pointer preserves zero, false, or an empty string. Pointer-to-collection
fields distinguish omission from an empty map or list. Results and nested mutable
values belong to the caller. Ordinary generic encoders need no per-field adapter:
```go
jsonBytes, err := json.Marshal(inspection)
if err != nil { return err }
yamlBytes, err := yaml.Marshal(inspection) // go.yaml.in/yaml/v4
if err != nil { return err }
_, _ = jsonBytes, yamlBytes
```
For migration, replace `ProfileInspection.EffectiveModelParams` accesses with
the optional resource fields, and use `Prepare` or `PreparedExecution.Details`
where backend completion and request overrides are needed. Prompt inspection's
`DefaultProfileID`, `Inputs`, nested input metadata, and output fields now use
optional pointers where presence matters; check for nil before dereferencing.
Consumers such as CommandKit can render the results directly instead of copying
each field into a parallel report. See the result types' [GoDoc](../../resource_inspection.go)
for keys and ownership; resource inspection does not replace `InspectConfiguration`
provenance, `InspectRequirements`, or concrete-request `ValidateRequest`.
### Set A Per-Run Session And Reasoning
Supply a direct session ID when one prompt should be correlated with a