Document PromptKit source migration
This commit is contained in:
123
docs/cli.md
123
docs/cli.md
@@ -25,19 +25,23 @@ go run ./cmd/scriptorium render \
|
||||
- `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 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.
|
||||
- `scriptorium config sources`: show the ordered configuration sources.
|
||||
- `scriptorium config explain`: explain one effective or historical configuration path.
|
||||
|
||||
All commands accept `--config <path>` and `--config-overlay <name>` and reject
|
||||
positional arguments. `--config-overlay` selects one application configuration
|
||||
overlay; it is separate from `--profile`, which selects a Promptkit execution
|
||||
profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
|
||||
for name, root, and no-base behavior. `run`,
|
||||
`render`, `serve`, and `inspect prompt` require an effective `prompt_dir`;
|
||||
`inspect profile` does not. Supply the directory through the configuration
|
||||
contract or a supported `--prompt-dir` flag. Explicit application flags,
|
||||
All command families accept `--config <path>` and `--config-overlay <name>`;
|
||||
positional arguments are rejected. `--config-overlay` selects one application
|
||||
configuration overlay; it is separate from `--profile`, which selects a
|
||||
Promptkit execution profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
|
||||
for name, root, and no-base behavior. `run`, `render`, `serve`, `inspect prompt`,
|
||||
`inspect profile`, and `inspect configuration` accept repeated
|
||||
`--promptkit-source <path>` flags and `--schema-dir <dir>` where applicable.
|
||||
They replace the configured source sequence in flag order. `--prompt-dir` and
|
||||
`--profile-dir` are no longer supported; use `promptkit_sources` in application
|
||||
configuration or the repeated source flags. Application `config` commands
|
||||
remain independent of framework source loading. Explicit application flags,
|
||||
including empty values, override file settings. Configuration load diagnostics
|
||||
go to stderr and exit with status 1; successful load warnings are printed once
|
||||
before command work.
|
||||
@@ -60,8 +64,7 @@ Optional flags:
|
||||
| --- | --- |
|
||||
| `--config <path>` | Application configuration file. |
|
||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||
| `--prompt-dir <dir>` | Prompt-definition directory override. |
|
||||
| `--profile-dir <dir>` | Custom profile-directory override. |
|
||||
| `--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. |
|
||||
@@ -90,7 +93,7 @@ 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.11.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||
[Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/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
|
||||
@@ -157,7 +160,7 @@ scriptorium render [flags]
|
||||
```
|
||||
|
||||
`--prompt <id>` is required. The following optional flags are supported:
|
||||
`--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, `--schema-dir`, `--prompt-version`, `--profile`,
|
||||
`--config`, `--config-overlay`, repeatable `--promptkit-source`, `--schema-dir`, `--prompt-version`, `--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
|
||||
@@ -185,8 +188,7 @@ Optional flags:
|
||||
| `--config <path>` | Application configuration file. |
|
||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||
| `--addr <listen-address>` | HTTP listen-address override. |
|
||||
| `--prompt-dir <dir>` | Prompt-definition directory override. |
|
||||
| `--profile-dir <dir>` | Custom profile-directory override. |
|
||||
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
||||
| `--artifact-root <dir>` | Root for HTTP `file` input references. |
|
||||
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
||||
@@ -200,26 +202,26 @@ schemas, and error codes are defined in the [HTTP API reference](api.md).
|
||||
|
||||
```text
|
||||
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
||||
[--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out PATH]
|
||||
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
|
||||
`--prompt` is required. Inspection uses normal configuration discovery and a
|
||||
`--prompt-dir` override, defaults to text regardless of `defaults.render_format`,
|
||||
and writes to stdout unless `--out` is supplied. It loads and normalizes the
|
||||
selected definition but does not resolve a profile, load a schema, render a
|
||||
template, reserve backend capacity, or call a model.
|
||||
`--prompt` is required. Inspection uses normal configuration discovery and the
|
||||
selected Promptkit sources, defaults to text regardless of
|
||||
`defaults.render_format`, and writes to stdout unless `--out` is supplied. It
|
||||
loads and normalizes the selected definition but does not resolve a profile,
|
||||
load a schema, render a template, reserve backend capacity, or call a model.
|
||||
|
||||
## `scriptorium inspect profile`
|
||||
|
||||
```text
|
||||
scriptorium inspect profile --profile ID
|
||||
[--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out PATH]
|
||||
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||
```
|
||||
|
||||
`--profile` is required; built-in profiles need no prompt directory. Inspection
|
||||
resolves profile inheritance and backend defaults, but never reads a credential
|
||||
value, loads a prompt, reserves capacity, or calls a model. Unset provider
|
||||
controls are shown as zero values when Promptkit leaves them unspecified.
|
||||
`--profile` is required. Inspection resolves profile inheritance and backend
|
||||
defaults from the selected sources, but never reads a credential value, loads
|
||||
a prompt, reserves capacity, or calls a model. Unset provider controls are
|
||||
shown as zero values when Promptkit leaves them unspecified.
|
||||
|
||||
## Application configuration inspection
|
||||
|
||||
@@ -230,17 +232,17 @@ scriptorium config sources [flags]
|
||||
scriptorium config explain --path JSON_POINTER [flags]
|
||||
```
|
||||
|
||||
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`,
|
||||
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`,
|
||||
Each accepts `--config`, `--config-overlay`, `--schema-dir`, `--addr`,
|
||||
`--artifact-root`, `--max-request-bytes`,
|
||||
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
|
||||
configuration selectors and overrides; request, credential, backend-editing,
|
||||
output-format, and output-file flags are not accepted. Positional arguments
|
||||
are rejected.
|
||||
|
||||
`validate` writes no success output; status 0 means the application configuration
|
||||
loaded and passed its own validation. It does not establish that a prompt
|
||||
directory exists, credentials are present, or Promptkit can construct an
|
||||
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources`
|
||||
loaded and passed its own validation. It does not establish that selected
|
||||
Promptkit sources can construct an engine, credentials are present, or a
|
||||
provider is available. `show` writes ConfigKit's resolved YAML snapshot. `sources`
|
||||
writes one newline-terminated JSON array of source records in load order. Each
|
||||
record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI
|
||||
overrides appear as synthetic sources. Defaults-only input without overrides
|
||||
@@ -251,19 +253,64 @@ The empty string selects the root; `/server/addr` selects a field; `~1` and
|
||||
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
|
||||
according to the containing mapping or sequence. Dotted paths, file paths,
|
||||
and URL fragments are not accepted. ConfigKit writes a human-readable account
|
||||
of the effective value and its chronological default, base, overlay, CLI,
|
||||
normalization, and structural-inheritance history, including consumed
|
||||
`extends` directives and removed values. This is not a JSON schema or a
|
||||
of the effective value and its chronological default, file/import, overlay,
|
||||
CLI, normalization, and removed-value history. This is not a JSON schema or a
|
||||
byte-for-byte stable prose format. Unknown and malformed paths exit 1 without
|
||||
successful explanation output.
|
||||
|
||||
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
|
||||
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
|
||||
leave partial data on failure. The inspection output can contain paths,
|
||||
identifiers, `api_key_env` reference names, and ordinary `extra_params` values,
|
||||
including displaced historical values in explanations;
|
||||
protect it accordingly. Raw API-key values are not read or emitted by these
|
||||
commands.
|
||||
leave partial data on failure. Application inspection can contain paths and
|
||||
configured values; protect its output accordingly. Raw API-key values are not
|
||||
accepted by the application configuration schema.
|
||||
|
||||
## Framework configuration inspection
|
||||
|
||||
```text
|
||||
scriptorium inspect configuration validate [flags]
|
||||
scriptorium inspect configuration show [flags]
|
||||
scriptorium inspect configuration sources [flags]
|
||||
scriptorium inspect configuration explain --path JSON_POINTER [flags]
|
||||
```
|
||||
|
||||
Each operation accepts `--config`, `--config-overlay`, repeatable
|
||||
`--promptkit-source`, and `--schema-dir`. These flags select the application
|
||||
settings and framework sources; positional arguments, `--format`, and `--out`
|
||||
are not accepted. Unlike `config validate`, framework `validate` constructs
|
||||
the Promptkit engine and validates all effective definitions, including
|
||||
unused ones. It writes nothing on success and does not prepare a request,
|
||||
resolve a credential, or contact a provider.
|
||||
|
||||
`show` writes Promptkit's native effective YAML, an inspection snapshot rather
|
||||
than a promised reloadable file. `sources` writes a
|
||||
newline-terminated JSON array in captured source order. Each source record has
|
||||
`id`, `label`, `layer`, `kind`, and `underlay_index`, plus `path` when available
|
||||
and `imported_from` for imported sources. That nested object has `source_id`,
|
||||
`line`, and `column`. Values and output structure are a projection of the
|
||||
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
|
||||
remain literal. Malformed and unknown pointers exit 1 without a successful
|
||||
report. Explanation prose is native and is not a stable machine-readable
|
||||
format.
|
||||
|
||||
Framework `show` and `explain` use Promptkit's native redaction for its
|
||||
classified credential-shaped provider fields, including historical values.
|
||||
Environment-variable reference names and ordinary provider parameters remain
|
||||
visible. Arbitrary prompt or provider content is not classified as secret by
|
||||
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).
|
||||
|
||||
Warnings and errors go to stderr. Successful `validate` writes nothing to
|
||||
stdout; successful `show`, `sources`, and `explain` write their reports there.
|
||||
Parse, load, path, and output failures exit 1. A native writer error may leave
|
||||
partial output.
|
||||
|
||||
## Input And Variable Syntax
|
||||
|
||||
|
||||
Reference in New Issue
Block a user