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

Document PromptKit request validation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-12 22:25:43 +00:00
parent be8bd9c1ea
commit 88d4059e8d
10 changed files with 219 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/consumers/guide.md
View File

@@ -11,7 +11,7 @@ through `commandkit.New` or `App.Register`.
| --- | --- |
| `gitea.maximumdirect.net/eric/CommandKit` | The application needs typed command declarations and common CLI behavior. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | The application wants ConfigKit-backed configuration scopes and reports. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, or requirements discovery. |
| `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | The application wants PromptKit engine configuration/comparison, prompt/profile catalogs, named inspection, requirements discovery, or concrete request validation. |
The two integrations are independent optional imports. `ckprompt` uses the
public scope and error contracts from `ckconfig`; importing it does not add the
@@ -119,22 +119,54 @@ source inventory, path explanation, and ConfigKit-backed comparison for the
capabilities declared by its scopes. The [CLI reference](../cli.md#configuration-scopes)
owns operator syntax and report details.
## PromptKit configuration and definitions
## PromptKit configuration, definitions, and requirements
`ckprompt.ConfigScope(loadEngine)` returns a `ckconfig.Scope` for the PromptKit
engine's captured configuration. Add that scope to a `ckconfig.Suite` to expose
it under `config` with validate/show/sources/explain and native diff operations;
it does not install PromptKit catalog, definition, or requirements commands.
`ckprompt.FromEngine(loadEngine)` supplies the prompt/profile catalog callbacks,
named inspection callbacks, and native requirements callback. Set its
`NewInput`, `NewState`, selectors, or validation when the application needs
them, then pass `ckprompt.Command(suite)` to core. All five callbacks are
independently optional; `Command` creates each operation group only when its
callbacks are present. Applications can use the requirements callback alone,
clear it while retaining other operations, wrap it, or replace it with their
own provider. For catalogs without named or requirements inspection, narrow the
suite before command capture:
`ckprompt.FromEngine(loadEngine)` supplies five callbacks: prompt and profile
catalogs, named prompt and profile inspection, and native requirements
discovery. Concrete request validation is a sixth, independently optional
capability and is added explicitly with `ckprompt.WithRequestValidation`.
`ckprompt.Command(suite)` creates only operations whose callbacks are present;
discovery and validation share `promptkit requirements` but can be installed
independently. A composed suite can keep the standard five and add validation:
```go
suite := ckprompt.FromEngine(loadEngine)
suite = ckprompt.WithRequestValidation(suite, loadEngine, buildRequest)
suite.NewInput = newInput
suite.NewState = newState
suite.Selectors = selectors
definitionCommand := ckprompt.Command(suite)
```
A validation-only suite can start empty. With application types named `Input`
and `State`, a nil builder forwards the request fields populated by standard
flags directly to PromptKit:
```go
suite := ckprompt.WithRequestValidation(
ckprompt.Suite[Input, State]{}, loadEngine, nil,
)
validationCommand := ckprompt.Command(suite)
```
If the loader is nil, the returned suite retains a wiring issue for installation
to report, even if capabilities are narrowed later. A builder runs before the
engine loader and receives the seed request, selection, typed input, shared
state, and invocation context. It returns the
concrete request; the adapter does not merge seed fields back afterward. The
loader receives the original selection. Builders should start from the seed,
preserve operator values and bindings, and apply defaults only when a map key is
absent, so explicitly supplied empty values stay meaningful. Applications that
validate and then execute a request are encouraged to share their request
construction logic between those paths.
All six suite capabilities are independently optional. For catalogs without
named or requirements inspection, narrow the suite before command capture:
```go
definitions := ckprompt.FromEngine(loadEngine)
@@ -144,20 +176,28 @@ definitions.InspectRequirements = nil
definitionCommand := ckprompt.Command(definitions)
```
Each selected inspection, requirements, or catalog operation prepares one input,
applies its captured selectors, checks that input, and initializes one state
value when those steps are reached. See
Each selected inspection, requirements, validation, or catalog operation
prepares one input, applies its captured selectors, checks that input, and
initializes one state value when those steps are reached. The bundled validation
adapter delegates concrete request preparation to PromptKit and carries its
native errors plus engine-loading diagnostics through the acquisition. It does
not call the model or retain a prepared execution snapshot. See
[ckprompt.Suite's GoDoc](../../integrations/ckprompt/adapters.go) for factory
timing, omitted-factory zero values, and caller-owned objects and effects.
The loader receives invocation context, explicitly supplied selection, input,
and state. The adapter uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`, and preserves acquisition diagnostics
and supported error identity.
and state. `FromEngine` uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`; validation must be opted into separately
and uses `Engine.ValidateRequest`.
CommandKit-owned listing and inspection code does not execute prompts, contact model
providers, or resolve credential values; application loaders and direct callbacks
retain their own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
owns the command and report contracts.
Catalog, named definition inspection, and requirements discovery do not render
messages or load request artifacts. Concrete request validation follows native
PromptKit preparation, which can resolve prompt/profile resources, load
artifacts and schemas, render messages, and perform applicable configuration
and credential checks. It does not make a model call or certify that a later
execution will succeed. Application loaders and direct callbacks retain their
own effects. The [CLI reference](../cli.md#promptkit-definition-inspection)
and [requirements contract](../cli.md#promptkit-requirements) own operator
syntax and reports.
The [composed example](../../integrations/ckprompt/examples/composed/README.md)
combines app and PromptKit config scopes, comparison and catalogs, named and