172 lines
7.8 KiB
Markdown
172 lines
7.8 KiB
Markdown
# ConfigKit and PromptKit example
|
|
|
|
This example combines application and PromptKit configuration, resource
|
|
inspection, request checks, and smoke tests. It uses local fixtures and an
|
|
in-memory model client. **No model service or credentials are required.**
|
|
|
|
Use Go 1.27.0 on `PATH`. An aligned workspace containing all three local modules
|
|
exercises their current sources; follow the [workspace setup](../../../../docs/development.md#documentation-validation)
|
|
from the repository root. The example also builds independently with
|
|
`GOWORK=off` against its module's released dependencies.
|
|
The [consumer guide](../../../../docs/consumers/guide.md#module-selection) owns
|
|
version and compatibility details.
|
|
|
|
From the repository root:
|
|
|
|
```sh
|
|
cd integrations/ckprompt/examples/composed
|
|
export GOWORK=auto GOTOOLCHAIN=local
|
|
go run . config scopes
|
|
go run . promptkit list prompts --campaign spring
|
|
go run . promptkit show prompt briefing --campaign spring --format yaml
|
|
```
|
|
|
|
The first command lists `app` and `promptkit` configurations and their available
|
|
operations. The next commands find and inspect the `briefing` prompt.
|
|
`--campaign` is a selector supplied by this example, not a standard PromptKit flag.
|
|
|
|
## Validate and compare configuration
|
|
|
|
```sh
|
|
go run . config validate --scope all --campaign spring --limit=0
|
|
go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml
|
|
go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring --against-campaign spring
|
|
```
|
|
|
|
The application scope requires `--limit=0` when `--campaign` is supplied.
|
|
The app comparison reports a changed default campaign and `campaigns.spring.model`.
|
|
The PromptKit comparison selects spring on both sides and reports the changed
|
|
profiles list as one value.
|
|
|
|
The two sides have independent selectors and overrides:
|
|
|
|
```sh
|
|
go run . config diff --scope app --campaign spring --limit=0 --against-campaign autumn --against-limit=0 --set '/campaigns/spring/model="left"' --against-set '/campaigns/spring/model="right"' --details
|
|
```
|
|
|
|
Only the application scope supports `--set` here. The released PromptKit loader
|
|
has no override handoff, so its configuration scope does not enable the feature.
|
|
An aggregate operation that includes that scope rejects overrides.
|
|
|
|
## List resources and select namespaces
|
|
|
|
```sh
|
|
go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml
|
|
go run . promptkit list backends --campaign spring
|
|
go run . promptkit list namespaces --campaign spring
|
|
go run . promptkit list collections --campaign spring
|
|
go run . promptkit list prompts --namespace field-notes --campaign spring
|
|
go run . promptkit show prompt briefing --campaign spring --prompt-namespace field-notes
|
|
go run . promptkit show profile spring --campaign spring
|
|
```
|
|
|
|
The profile list includes the selected `autumn` profile. PromptKit's default
|
|
bundle contributes additional resources. The example also supplies a
|
|
`field-notes` collection containing a backend, profile, and prompt. Listing
|
|
filters and resource namespace flags let you inspect that collection.
|
|
|
|
## Discover inputs, then check a request
|
|
|
|
```sh
|
|
go run . promptkit requirements show briefing --campaign spring
|
|
go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml
|
|
```
|
|
|
|
The first report is incomplete: the `notes` input is conditional and `mode` is
|
|
missing. Supplying `mode=full` selects that branch and makes `notes` required.
|
|
Both commands succeed; discovery alone does not establish that a request can run.
|
|
|
|
```sh
|
|
go run . promptkit requirements validate briefing --campaign spring --llm-input-file topic=fixtures/topic.txt
|
|
go run . promptkit requirements validate briefing --campaign spring --llm-input-file topic=fixtures/topic.txt --llm-var mode=full --llm-input-file notes=fixtures/notes.txt --format yaml
|
|
```
|
|
|
|
Both commands check request preparation and report `prompt_id` and `valid: true`.
|
|
The builder provides campaign-specific variable defaults; the operator supplies
|
|
the input files. For comparison, this command intentionally fails because the
|
|
required `topic` input is missing:
|
|
|
|
```sh
|
|
# Intentional failure: missing topic input.
|
|
go run . promptkit requirements validate briefing --campaign spring
|
|
```
|
|
|
|
Preview a request with literal input instead of a file:
|
|
|
|
```sh
|
|
go run . promptkit show prepared briefing --campaign spring --input topic=sprint --profile spring --extra-params '{"campaign":"preview"}'
|
|
```
|
|
|
|
The preview includes rendered messages and effective provider settings.
|
|
Validation and preview do not call the model or guarantee later execution.
|
|
|
|
## Run smoke tests
|
|
|
|
```sh
|
|
go run . promptkit test text_inference --campaign spring --prompt briefing --profile spring
|
|
# Some diagnostics can fail or be unsupported; inspect the retained report.
|
|
go run . promptkit test all --campaign spring --llm-prompt briefing --llm-profile spring
|
|
```
|
|
|
|
Inference uses the example's in-memory client. HTTP checks may be unsupported
|
|
or not applicable because the local backend has no network probe. The aggregate
|
|
can return a failure while still showing results. Read the facts in the report;
|
|
a successful command status does not mean every observation is positive.
|
|
|
|
For any command that returns nonzero, `go run` prints `exit status N` and itself
|
|
exits with status 1. A built executable returns the application's status directly.
|
|
The [CLI reference](../../../../docs/cli.md#promptkit-smoke-testing) explains the
|
|
standard test kinds, results, and statuses.
|
|
|
|
## Try aliases and application commands
|
|
|
|
```sh
|
|
go run . list collections --campaign spring
|
|
go run . pk list bundles --campaign spring
|
|
go run . pk show prompt briefing --campaign spring --fmt yaml
|
|
go run . smoke text_inference --campaign spring --llm-prompt briefing --llm-profile spring
|
|
go run . pk --hlep
|
|
go run . session restore session-42 --campaign spring
|
|
go run . request inspect --llm-prompt briefing --llm-profile= --llm-model example --llm-input-text topic=sprint --format json
|
|
```
|
|
|
|
The first two commands reach `promptkit list collections`. `pk` shortens the
|
|
PromptKit group; `--fmt` is an alias on prompt inspection and `--hlep` is a global
|
|
help alias. `smoke` shortens `promptkit test` while leaving the test kind as an
|
|
argument. The session command uses an in-memory store. `request inspect` shows
|
|
how an application command can reuse canonical `--llm-*` flag collections without
|
|
installing PromptKit's short aliases.
|
|
|
|
## Try shell completion
|
|
|
|
```sh
|
|
go build -o composed-example .
|
|
./composed-example completion bash
|
|
```
|
|
|
|
Initialize `bash-completion` if using Bash, then load the generated script using
|
|
the [CLI reference](../../../../docs/cli.md#shell-completion). Try completing
|
|
`composed-example pk show prompt briefing --fmt=` or
|
|
`composed-example config show --config=fixtures/`. The already-entered `pk` alias
|
|
selects the command context without loading an engine.
|
|
|
|
## How it is wired
|
|
|
|
The example installs `ckconfig.Command(suite)` and
|
|
`ckprompt.Declarations(definitions)` with application-owned aliases in a
|
|
`[]commandkit.Declaration`. `NewInput` initializes scope inputs; `NewState`
|
|
creates a cache shared within an invocation. The loaders cache successful
|
|
configuration results by the complete configuration/overlay selection,
|
|
overrides, and supplied campaign, including whether each value was supplied.
|
|
These are example choices, not a CommandKit cache policy.
|
|
|
|
Smoke testing uses `WithSmokeTesting` with a nil builder, forwarding the request
|
|
selected by flags. Applications can supply a builder to customize that request.
|
|
See the [consumer guide](../../../../docs/consumers/guide.md#promptkit-configuration-definitions-and-requirements)
|
|
for suite composition, builders, and ownership, and the [source](main.go) for
|
|
the complete application.
|
|
|
|
Run `GOWORK=auto GOTOOLCHAIN=local go test ./...` from this example directory
|
|
for an aligned workspace check. Use
|
|
`GOWORK=off GOTOOLCHAIN=local go test ./...` to check the declared releases.
|