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