Update documentation for PromptKit adoption
This commit is contained in:
54
docs/cli.md
54
docs/cli.md
@@ -24,7 +24,7 @@ go run ./cmd/scriptorium render \
|
||||
- `scriptorium render`: prepare a prompt and write prepared-run output.
|
||||
- `scriptorium serve`: start the HTTP server.
|
||||
- `scriptorium inspect prompt`: inspect one prompt definition without model execution.
|
||||
- `scriptorium inspect profile`: inspect one effective profile without model execution.
|
||||
- `scriptorium inspect profile`: inspect one resolved profile without model execution.
|
||||
- `scriptorium inspect configuration`: validate or inspect Promptkit's captured framework configuration.
|
||||
- `scriptorium config validate`: validate application configuration without building an engine.
|
||||
- `scriptorium config show`: show the resolved application configuration.
|
||||
@@ -66,7 +66,6 @@ Optional flags:
|
||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
||||
| `--prompt-version <version>` | Optional prompt-definition version selector. |
|
||||
| `--profile <id>` | Execution-profile override. |
|
||||
| `--session-id <id>` | Optional direct session identifier. |
|
||||
| `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. |
|
||||
@@ -93,16 +92,17 @@ only; the caller context and configured transport cap remain active. CLI
|
||||
durations are converted to whole seconds by truncation toward zero, so any
|
||||
duration whose absolute value is below one second becomes an explicit
|
||||
zero-second override. The timeout layers are defined in the
|
||||
[Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||
[Promptkit outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||
With the built-in client, each transient retry gets a fresh generation timeout;
|
||||
this flag does not limit the complete run.
|
||||
`--run-timeout` keeps subsecond precision and starts immediately before engine
|
||||
execution. It bounds preparation, capacity waits, retry waits, generation, and
|
||||
repairs where they honor context. Parsing, engine construction, and output
|
||||
writes are outside that interval. A failed run whose execution context reaches
|
||||
this deadline exits 1 with a safe deadline diagnostic; a completed invalid
|
||||
output still exits 2. It does not promise immediate interruption of synchronous
|
||||
work.
|
||||
writes are outside that interval. A failed run identified by PromptKit as an
|
||||
operation timeout exits 1 with a safe deadline diagnostic; a completed invalid
|
||||
output still exits 2. Synchronous work may not stop immediately. The selected
|
||||
PromptKit release can report an in-flight built-in HTTP operation timeout as a
|
||||
transport failure rather than a typed deadline; see the [API reference](api.md#error-responses).
|
||||
Omitting `--transient-retries` inherits the application setting or Promptkit's
|
||||
current default of two additional attempts. The flag overrides only this
|
||||
request; it does not alter the configured engine. Structural repair generations
|
||||
@@ -110,10 +110,10 @@ have separate transient retry budgets.
|
||||
|
||||
There is no raw API-key flag. Use `--api-key-env`.
|
||||
|
||||
`--prompt-version` is passed directly to Promptkit. When it is omitted, the
|
||||
selected prompt ID must have exactly one available version. `--input` is
|
||||
optional at the CLI boundary: Promptkit decides whether the selected definition
|
||||
requires declared inputs or template-referenced values.
|
||||
Prompt and profile IDs are passed unchanged, including collection-qualified
|
||||
IDs. The removed `--prompt-version` flag is rejected. `--input` is optional
|
||||
at the CLI boundary: PromptKit decides whether the selected definition requires
|
||||
declared inputs or template-referenced values.
|
||||
|
||||
`--session-id` supplies a direct, non-secret session identifier. A nonblank
|
||||
value replaces a definition-rendered session ID; an omitted or blank value lets
|
||||
@@ -160,7 +160,7 @@ scriptorium render [flags]
|
||||
```
|
||||
|
||||
`--prompt <id>` is required. The following optional flags are supported:
|
||||
`--config`, `--config-overlay`, repeatable `--promptkit-source`, `--schema-dir`, `--prompt-version`, `--profile`,
|
||||
`--config`, `--config-overlay`, repeatable `--promptkit-source`, `--schema-dir`, `--profile`,
|
||||
`--input`, `--var`, `--out`, `--llm-base-url`,
|
||||
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`,
|
||||
`--reasoning-effort`, `--session-id`, `--timeout`, `--transient-retries`, and `--format text|json`. Their meanings match the corresponding
|
||||
@@ -175,6 +175,17 @@ include a retry field in prepared output.
|
||||
`render` resolves profiles and schemas as part of preparation but
|
||||
does not call an LLM.
|
||||
|
||||
To render from independently maintained collection checkouts:
|
||||
|
||||
```bash
|
||||
go run ./cmd/scriptorium render --config ./examples/config.discovery.yml \
|
||||
--prompt support/answer --profile support/fast \
|
||||
--input transcript=./examples/fixtures/transcript.md
|
||||
```
|
||||
|
||||
The [discovery example](../examples/discovery/framework.yml) also provides
|
||||
`review/answer`; see [configuration discovery](config.md#collection-checkout-discovery).
|
||||
|
||||
## `scriptorium serve`
|
||||
|
||||
```text
|
||||
@@ -201,7 +212,7 @@ schemas, and error codes are defined in the [HTTP API reference](api.md).
|
||||
## `scriptorium inspect prompt`
|
||||
|
||||
```text
|
||||
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
||||
scriptorium inspect prompt --prompt ID
|
||||
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
|
||||
@@ -220,6 +231,9 @@ Inspection does not prepare an execution request, load request-time schemas or
|
||||
artifacts, resolve credential values, reserve backend capacity, or call a model.
|
||||
Prompt inspection does not select an execution profile or render request-specific
|
||||
templates.
|
||||
Prompt output includes ID, hash, optional default profile and input metadata,
|
||||
and the output contract. Absent optional values are omitted; explicitly empty
|
||||
or zero values are retained. Captured message text is not projected.
|
||||
|
||||
## `scriptorium inspect profile`
|
||||
|
||||
@@ -229,9 +243,11 @@ scriptorium inspect profile --profile ID
|
||||
```
|
||||
|
||||
`--profile` is required. After the [full-source engine construction described
|
||||
above](#scriptorium-inspect-prompt), inspection selects one effective profile
|
||||
with resolved inheritance and backend defaults. Unset provider controls are
|
||||
shown as zero values when Promptkit leaves them unspecified.
|
||||
above](#scriptorium-inspect-prompt), inspection selects one resolved profile
|
||||
with inheritance. `profile_model_params` contains only fields present on that
|
||||
profile; it does not fill backend defaults. `api_key_required` is a separate
|
||||
optional field. Explicit zero and empty values remain visible. Use `render`
|
||||
for request-completed model settings.
|
||||
|
||||
## Application configuration inspection
|
||||
|
||||
@@ -302,8 +318,8 @@ captured Promptkit view, not Scriptorium's application-source records.
|
||||
|
||||
`explain` requires an explicitly supplied `--path` in ConfigKit JSON Pointer
|
||||
syntax; `--path ''` selects the root. For example,
|
||||
`/profiles/team~1summary/model` addresses the `model` field of the literal
|
||||
profile ID `team/summary`. Escape `/` as `~1` and `~` as `~0`; dots in a key
|
||||
`/collections/support/profiles/0/model` addresses the first support profile's
|
||||
model in the captured list. Escape `/` as `~1` and `~` as `~0`; dots in a key
|
||||
remain literal. Malformed and unknown pointers exit 1 without a successful
|
||||
report. Explanation prose is native and is not a stable machine-readable
|
||||
format.
|
||||
@@ -316,7 +332,7 @@ name inspection, so treat these reports as sensitive. This redaction policy is
|
||||
limited to framework configuration reports; it does not add redaction to
|
||||
`inspect profile` or prepared-run output. Credentials are not resolved by any
|
||||
of these inspection operations. Promptkit owns detailed field and source
|
||||
semantics; see its tagged [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
|
||||
semantics; see its tagged [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md).
|
||||
|
||||
Warnings and errors go to stderr. Successful `validate` writes nothing to
|
||||
stdout; successful `show`, `sources`, and `explain` write their reports there.
|
||||
|
||||
Reference in New Issue
Block a user