commandkit/integrations/ckprompt/examples/composed/README.md

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 from the repository root. The example also builds independently with GOWORK=off against its module's released dependencies. The consumer guide owns version and compatibility details.

From the repository root:

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

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:

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

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

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.

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:

# Intentional failure: missing topic input.
go run . promptkit requirements validate briefing --campaign spring

Preview a request with literal input instead of a file:

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

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 explains the standard test kinds, results, and statuses.

Try aliases and application commands

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

go build -o composed-example .
./composed-example completion bash

Initialize bash-completion if using Bash, then load the generated script using the CLI reference. 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 for suite composition, builders, and ownership, and the source 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.