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

Add reusable PromptKit request flags

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-07 04:16:09 +00:00
parent 6378ceb3c5
commit c3d5f551c3
17 changed files with 450 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/cli.md
View File

@@ -563,8 +563,8 @@ native selection and discovery rules:
```text
example promptkit requirements show briefing --campaign spring
example promptkit requirements show briefing --profile editorial --var mode=full
example promptkit requirements show briefing --session-id session-42 --var note= --format yaml
example promptkit requirements show briefing --llm-profile editorial --llm-var mode=full
example promptkit requirements show briefing --llm-session-id session-42 --llm-var note= --format yaml
```
The command accepts:
@@ -574,9 +574,9 @@ The command accepts:
| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
| `--profile` | string | empty | Pass the profile ID to PromptKit; empty uses its native selection rule. |
| `--session-id` | string | empty | Pass session context to PromptKit. |
| `--var` | repeatable `KEY=VALUE` | none | Supply caller-variable context for native discovery. |
| `--llm-profile` | string | empty | Pass the profile ID to PromptKit; empty uses its native selection rule. |
| `--llm-session-id` | string | empty | Pass session context to PromptKit. |
| `--llm-var` | repeatable `KEY=VALUE` | none | Supply caller-variable context for native discovery. |
| `--format` | `text`, `yaml`, `json` | automatic | Select the requirements report format; automatic and text use YAML for this structured report. |
The `promptkit` namespace identifies the operation, so there is no built-in
@@ -585,10 +585,10 @@ native empty-string meaning. Requirements inspection does not require a profile
to be execution-ready. See the
[PromptKit v0.18.0 consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad30509e538fc73ea16710df3a3ec084502/docs/consumers/pkg-promptkit.md)
for native configuration, selection, and requirements behavior. The built-in
flags other than `--var` are singleton bindings; when repeated, the last value
flags other than `--llm-var` are singleton bindings; when repeated, the last value
is used. Suite selectors retain their declared binding behavior.
Each `--var` occurrence must contain `=`. CommandKit splits at the first
Each `--llm-var` occurrence must contain `=`. CommandKit splits at the first
separator and preserves the exact key and remaining value. Empty keys and
values, whitespace, commas, and additional `=` characters are retained. All
occurrences are parsed; duplicate keys use the last value, while any malformed
@@ -644,8 +644,8 @@ prompt ID and passes a concrete request to PromptKit's native
`Engine.ValidateRequest` preparation path:
```text
example promptkit requirements validate briefing --campaign spring --input topic=topic.txt
example promptkit requirements validate briefing --profile editorial --session-id session-42 --var mode=full --input notes=notes.txt
example promptkit requirements validate briefing --campaign spring --llm-input-file topic=topic.txt
example promptkit requirements validate briefing --llm-profile editorial --llm-session-id session-42 --llm-var mode=full --llm-input-file notes=notes.txt
```
The command accepts:
@@ -655,24 +655,28 @@ The command accepts:
| `--config` | path string | omitted | Select the configuration input; explicit presence is retained. |
| `--overlay` | path string | omitted | Select one overlay; explicit presence is retained. Repeated occurrences use the last value. |
| Suite selectors | application-defined | per selector | The flags captured from `Suite.Selectors`. |
| `--profile` | string | empty | Pass the profile ID to PromptKit. |
| `--session-id` | string | empty | Pass session context to PromptKit. |
| `--var` | repeatable `KEY=VALUE` | none | Supply caller variables for the concrete request. |
| `--input` | repeatable `NAME=PATH` | none | Bind a file-backed PromptKit artifact. |
| `--llm-profile` | string | empty | Pass the profile ID to PromptKit. |
| `--llm-session-id` | string | empty | Pass session context to PromptKit. |
| `--llm-var` | repeatable `KEY=VALUE` | none | Supply caller variables for the concrete request. |
| `--llm-input-text` | repeatable `NAME=TEXT` | none | Bind a literal PromptKit artifact. |
| `--llm-input-file` | repeatable `NAME=PATH` | none | Bind a file-backed PromptKit artifact. |
| `--format` | `text`, `yaml`, `json` | automatic | Select the success confirmation format; automatic and text use YAML for this structured report. |
The built-in flags other than repeatable `--var` and `--input` are singleton
bindings; when repeated, the last value is used. Explicit empty `--config` or
Validation also accepts the execution controls from `--llm-endpoint` through
`--llm-extra-params` listed under [smoke testing](#promptkit-smoke-testing).
The built-in flags other than
`--llm-var`, `--llm-input-text`, and `--llm-input-file` are singleton bindings;
when repeated, the last value is used. Explicit empty `--config` or
`--overlay` values keep their supplied-presence information. The profile and
session fields use native empty-string semantics. PromptKit owns their
interpretation and selection errors.
Each `--var` and `--input` occurrence must contain `=`. CommandKit splits at the
first separator and preserves the exact key/name and remaining value/path.
Empty variable keys and values and empty input names and paths are passed to
native validation. File paths become `promptkit.File(PATH)` references without
being read, normalized, expanded, or rebased during argument binding. Duplicate
keys or names use the last value, but every occurrence is parsed.
Each `--llm-var`, `--llm-input-text`, and `--llm-input-file` occurrence must
contain `=`. CommandKit splits at the first separator and preserves the exact
key/name and remaining value. Empty names and values are passed to native
validation. Text becomes a `promptkit.Inline` reference; file paths become
`promptkit.File` references without being read, normalized, expanded, or
rebased during argument binding. Every occurrence is parsed.
On success, the confirmation contains only the requested prompt ID and
`valid: true`:
@@ -765,33 +769,39 @@ each aggregate call changes the seed kind before invoking it. The command
accepts:
```text
example promptkit test text_inference --campaign spring --prompt briefing --profile spring
example promptkit test all --campaign spring --prompt briefing --profile spring
example promptkit test authentication --backend local
example promptkit test text_inference --campaign spring --llm-prompt briefing --llm-profile spring
example promptkit test all --campaign spring --llm-prompt briefing --llm-profile spring
example promptkit test authentication --llm-backend local
```
| Flag | Values | Default | Meaning |
| --- | --- | --- | --- |
| `--config`, `--overlay` | path strings | omitted | Select PromptKit configuration; supplied presence is retained. |
| Suite selectors | application-defined | per selector | Captured flags from `Suite.Selectors`. |
| `--backend` | string | empty | Native backend ID. |
| `--prompt` | string | empty | Native prompt ID. |
| `--profile` | string | empty | Native profile ID. |
| `--endpoint` | string | omitted | Override the execution endpoint. |
| `--model` | string | omitted | Override the execution model. |
| `--temperature` | float | omitted | Override execution temperature. |
| `--max-tokens` | integer | omitted | Override execution maximum tokens. |
| `--top-p` | float | omitted | Override execution top-p. |
| `--timeout-seconds` | integer | omitted | Override the execution timeout. |
| `--service-tier` | string | omitted | Override the execution service tier. |
| `--reasoning-effort` | string | omitted | Override execution reasoning effort. |
| `--api-key-env` | string | omitted | Supply an API-key environment-variable name to native configuration. |
| `--transient-retries` | integer | omitted | Set the native inference transient retry count. |
| `--llm-backend` | string | empty | Native backend ID. |
| `--llm-prompt` | string | empty | Native prompt ID. |
| `--llm-profile` | string | empty | Native profile ID. |
| `--llm-endpoint` | string | omitted | Override the execution endpoint. |
| `--llm-model` | string | omitted | Override the execution model. |
| `--llm-temperature` | float | omitted | Override execution temperature. |
| `--llm-max-tokens` | integer | omitted | Override execution maximum tokens. |
| `--llm-top-p` | float | omitted | Override execution top-p. |
| `--llm-timeout-seconds` | integer | omitted | Override the execution timeout. |
| `--llm-service-tier` | string | omitted | Override the execution service tier. |
| `--llm-reasoning-effort` | string | omitted | Override execution reasoning effort. |
| `--llm-api-key-env` | string | omitted | Supply an API-key environment-variable name to native configuration. |
| `--llm-transient-retries` | integer | omitted | Set the native inference transient retry count. |
| `--llm-extra-params` | JSON object | omitted | Supply provider parameters as a whole map. |
| `--format` | `text`, `yaml`, `json` | automatic | Select the report format; automatic and text use YAML for these structured reports. |
The execution flags populate PromptKit's native execution override. The
`--api-key-env` value is a variable name, not a credential value. Application
selectors, loader policy, credentials, and client wiring remain application
`--llm-api-key-env` value is a variable name, not a credential value. The
extra-parameters flag accepts one JSON object, including an empty object;
PromptKit owns its native replacement semantics and validation. Integer JSON
numbers use signed or unsigned 64-bit integers where representable; decimal
and exponent numbers use floating point.
Application selectors, loader policy, credentials, and client wiring remain application
owned. The `WithSmokeTesting` helper accepts an optional typed builder. A nil
builder forwards the seed; a supplied builder's complete native request is
authoritative. The helper retains a native report when PromptKit returns both a

6
docs/consumers/guide.md
View File

@@ -326,6 +326,12 @@ and state. `FromEngine` uses PromptKit's public listing and inspection methods,
including `Engine.InspectRequirements`; validation must be opted into separately
and uses `Engine.ValidateRequest`.
Application-owned commands can use `ckprompt.NewExecutionFlags`,
`ckprompt.NewResourceFlags`, and `ckprompt.NewPromptInputFlags` to bind the
same canonical request flags into their own input types. Each collection exposes
individual handles and an `All` method, so a command can choose its applicable
subset. The application decides how to apply the resulting values to its request.
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

7
docs/roadmap/implementation.md
View File

@@ -1,6 +1,6 @@
# Shared reporting and PromptKit v0.20.0 implementation plan
Status: implementation in progress; Stages 1–9 complete.
Status: implementation in progress; Stages 1–10 complete.
## Scope, authority, and execution
@@ -350,6 +350,11 @@ for the converted commands.
## Stage 10: Reusable execution and resource flag collections
**Complete.** Reusable request flag collections feed requirements discovery,
validation, and smoke requests; the next stage supplies ordered text/file
precedence and prepared-request preview. The root, ckconfig, and ckprompt
workspace suites passed with Go 1.27.0, including collection and builder tests.
Implement CLI-specific collections in ckprompt using ordinary public core flags.
Use typed flag-set structs exposing named original `Flag[I]` handles and an
`All() []Flag[I]` convenience method; callers select subsets with ordinary slices.