From b913ef0d078069c28d865d5ee6867b5475f31e3d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 4 Oct 2026 13:04:02 +0000 Subject: [PATCH] Document PromptKit source migration --- README.md | 8 +- docs/cli.md | 123 ++++++++++++------ docs/config.md | 167 ++++++++++-------------- docs/consumers/upgrading-promptkit.md | 175 ++++++++++++++++++++++++++ docs/operations.md | 55 ++++---- docs/roadmap/implementation.md | 22 +++- 6 files changed, 384 insertions(+), 166 deletions(-) create mode 100644 docs/consumers/upgrading-promptkit.md diff --git a/README.md b/README.md index 5ba7254..e4c14e1 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ OpenAI-compatible model endpoints, and returns generated output with validation metadata. The application uses -[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/) +[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/) for prompt, profile, schema, preparation, generation, and validation behavior. Scriptorium owns executable configuration, CLI and HTTP mapping, process behavior, output presentation, and HTTP artifact-containment policy. @@ -33,14 +33,16 @@ a model. For complete invocation and output behavior, see the - [CLI reference](docs/cli.md) - [Configuration reference](docs/config.md) - [Application configuration inspection](docs/cli.md#application-configuration-inspection) +- [Framework configuration inspection](docs/cli.md#framework-configuration-inspection) - [HTTP API reference](docs/api.md) - [Operations guide](docs/operations.md) - [Consumer integration overview](docs/consumers/api.md) - [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md) +- [Upgrade Promptkit source selectors and definitions](docs/consumers/upgrading-promptkit.md) - [Subprocess integration](docs/integrations/subprocess.md) - [Architecture policy](docs/policy/architecture.md) -- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) -- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md) +- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) +- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) ## Examples diff --git a/docs/cli.md b/docs/cli.md index ca327aa..516561b 100644 --- a/docs/cli.md +++ b/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 ` and `--config-overlay ` 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 ` and `--config-overlay `; +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 ` flags and `--schema-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 ` | Application configuration file. | | `--config-overlay ` | Selected application configuration overlay. | -| `--prompt-dir ` | Prompt-definition directory override. | -| `--profile-dir ` | Custom profile-directory override. | +| `--promptkit-source ` | PromptKit source file or directory; repeat to select ordered sources. | | `--schema-dir ` | Schema base-directory override. | | `--prompt-version ` | Optional prompt-definition version selector. | | `--profile ` | 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 ` 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 ` | Application configuration file. | | `--config-overlay ` | Selected application configuration overlay. | | `--addr ` | HTTP listen-address override. | -| `--prompt-dir ` | Prompt-definition directory override. | -| `--profile-dir ` | Custom profile-directory override. | +| `--promptkit-source ` | PromptKit source file or directory; repeat to select ordered sources. | | `--schema-dir ` | Schema base-directory override. | | `--artifact-root ` | Root for HTTP `file` input references. | | `--max-request-bytes ` | 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 diff --git a/docs/config.md b/docs/config.md index c437393..06bb808 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,11 +1,12 @@ # Configuration Reference This is the canonical reference for Scriptorium application settings. Prompt, -profile, schema, execution-setting, built-in profile, and framework credential -semantics are defined by the -[Promptkit v0.11.2 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md). +profile, backend, schema, execution-setting, built-in profile, and framework +credential semantics are defined by the +[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and -outcomes, see the [HTTP API reference](api.md). +outcomes, see the [HTTP API reference](api.md). For migration examples, see +[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md). ## Discovery And Precedence @@ -21,20 +22,19 @@ If neither exists, it uses built-in defaults. An explicit `--config` path must exist and decode successfully. The maintained [minimal configuration](../examples/config.yml), -[complete configuration](../examples/config.full.yml), and +[complete configuration](../examples/config.full.yml), [composed configuration](../examples/config.composed.yml), and -[backend inheritance configuration](../examples/config.inheritance.yml) are +[framework inheritance configuration](../examples/config.inheritance.yml) are copyable examples. ## Application Configuration File Configuration is decoded by ConfigKit v0.5.0 as strict YAML. Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors are rejected. -An explicit empty string is a value: it clears a file-provided optional path -or, for required `prompt_dir`, fails the command's prerequisite. A scalar -`null` is not an empty string and is rejected for scalar fields; nullable -fields such as `transient_retries` retain their documented meaning. Raw -API-key fields are not accepted. +An explicit empty string is a value and may clear a file-provided optional +string. A scalar `null` is not an empty string and is rejected for non-nullable +fields; nullable fields such as `transient_retries` retain their documented +meaning. Raw API-key fields and unknown application fields are rejected. ConfigKit applies defaults, the selected file, then only explicitly supplied application CLI flags before validating the result. Paths in the application @@ -42,6 +42,36 @@ document remain relative to the process working directory, not to the file's directory. Load diagnostics are printed safely on stderr; invalid application configuration exits with status 1. +### Promptkit source selectors + +`promptkit_sources` is an ordered sequence of explicit Promptkit source +selectors. Each item must set exactly one of `file` or `directory`: + +```yaml +promptkit_sources: + - directory: ./examples/prompts + - directory: ./examples/profiles + - file: ./examples/framework/backends.yml +schema_dir: ./examples/schemas +``` + +Omitting the field or setting it to `[]` (or `null`) selects no +application-supplied framework sources; Promptkit's selected catalog and +maintained definitions still apply. A later sequence item overlays an earlier +one. Files within a selected directory are composed together, so conflicting +definitions in that group fail instead of using filename order as precedence. +An explicit file may use ConfigKit imports. The complete framework format and +source rules belong to the [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md). + +Selector paths are relative to the process working directory, not to the +application configuration file. Application validation checks the selector +shape but does not open or validate Promptkit sources. `config validate` +therefore does not prove that selected sources can build an engine; use +`inspect configuration validate` for that separate check. Repeated +`--promptkit-source` flags replace the entire configured selector sequence +and preserve flag order. A selected application overlay that defines +`promptkit_sources` replaces the prior sequence as a whole. + ### Explicit imports and selected overlays A file-backed configuration may declare `configkit.imports` with relative @@ -74,15 +104,15 @@ go run ./cmd/scriptorium render \ --input glossary=./examples/fixtures/glossary.yml ``` -Import and overlay file locations are constrained by ConfigKit; -*application path values* such as `prompt_dir` remain relative -to the process working directory even when authored in a fragment or overlay. -These source constraints are separate from HTTP artifact containment. +Import and overlay file locations are constrained by ConfigKit; application +path values such as `promptkit_sources`, `schema_dir`, and `server.artifact_root` +remain relative to the process working directory even when authored in a +fragment or overlay. These source constraints are separate from Promptkit +message-resource paths and HTTP artifact containment. | Field | Default | Meaning | | --- | --- | --- | -| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value. | -| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. | +| `promptkit_sources` | empty sequence | Ordered file/directory sources for Promptkit backends, profiles, and prompts. | | `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. | | `server.addr` | `:8080` | Address used by `serve`. | | `server.artifact_root` | unset | Root that enables HTTP `file` input references. | @@ -90,7 +120,6 @@ These source constraints are separate from HTTP artifact containment. | `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. | | `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. | | `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. | -| `backends` | unset | Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings. | | `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. | The size fields must be zero or greater. The [HTTP API](api.md) defines how @@ -98,91 +127,29 @@ each limit is enforced and reported. `server.artifact_root` configures an HTTP deployment boundary; see [operations](operations.md) for deployment handling. The `config validate`, `config show`, `config sources`, and `config explain` -commands inspect this -application configuration without creating a Promptkit engine. `show` is a -resolved inspection snapshot, not necessarily a reloadable file. Application -validation does not check framework sources, backend connectivity, or credential -availability. `api_key_env` is an environment-variable *name* and remains -visible in inspection; its environment value is never read by ConfigKit. -Ordinary backend `extra_params` values also remain visible, so keep secrets out -of those fields and protect inspection output as potentially sensitive. +commands inspect this application configuration without creating a Promptkit +engine. `show` is a resolved inspection snapshot, not necessarily a reloadable +file. Application validation does not check framework sources, backend +connectivity, or credential availability. Use `inspect configuration` for +Promptkit's separately captured framework configuration; its four operations +are documented in the [CLI reference](cli.md#framework-configuration-inspection). `config explain --path /server/addr` uses JSON Pointer syntax to show the selected field's current value and history from defaults, files, overlays, explicit CLI overrides, and normalization. `--path ''` selects the root. History includes replaced and removed values; `show` presents the final -resolved snapshot. Neither renderer looks up credential bytes, and neither -claims to identify arbitrary secrets in unclassified parameter values. - -### Application mapping inheritance - -Any application input mapping may use ConfigKit's `extends: sibling-name` -directive to inherit from a mapping among its immediate siblings. Names are -exact, and lookup does not search ancestor or unrelated mappings. ConfigKit -resolves inheritance after imports, a selected overlay, and explicit CLI -overrides have been assembled, and before typed decoding. It resolves every -effective relationship, even for a backend the selected profile does not use; -an invalid relationship in such a mapping still fails the load. - -The child retains its own mapping name. Explicit child values replace inherited -values, including zero, false, empty strings, sequences, and null where the -application field permits null; omitted values inherit. `extends: null` -cancels inheritance and keeps the child's own settings. The parent remains an -ordinary configured entry: a parent backend is registered and validated by -Promptkit along with other configured backends, not treated as an abstract -template. Inheritance copies settings but does not create a shared capacity -pool across distinct backend IDs. The maintained [backend inheritance -example](../examples/config.inheritance.yml) shows a complete parent and child. - -ConfigKit retains inherited origins and displaced values for inspection: -`show` presents the resolved result and `explain` describes derivation and -history. Inherited application paths retain their working-directory-relative -meaning. An inherited `api_key_env` remains a visible environment-variable -name passed to Promptkit; ConfigKit does not read its value. Promptkit prompt, -profile, and schema formats and HTTP request payloads are independently parsed -and do not acquire this directive. See the pinned [ConfigKit v0.5.0 inheritance -contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance) -for exact semantics. - -`extends` is reserved across application input mappings, not only under -`backends`; quoting the key does not make it ordinary data. This can affect a -mapping name (such as a backend ID) or a literal provider parameter with that -name. Rename an application-owned name where appropriate. A provider-required -literal key cannot generally be renamed without provider support, and this -ConfigKit version has no escape or opt-out; a concrete need must be addressed -upstream. - -## Custom Backends - -Use `backends` when a profile selects an application-defined backend ID: - -```yaml -backends: - local-gpu: - endpoint: http://localhost:11434/v1 - api_key_env: LOCAL_GPU_API_KEY - extra_params: - provider_option: enabled - concurrency_limit: 2 - queue_capacity: 0 -``` - -Each mapping key is the case-sensitive backend ID. `endpoint` is required; -`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are -optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting -`queue_capacity` lets Promptkit use its default for a limited backend, while -an explicit `queue_capacity: 0` disables queueing. - -Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit -validates backend IDs, endpoints, environment-variable names, extra parameters, -and capacity relationships when Scriptorium constructs its engine. There are no -backend command-line overrides. Store only an environment-variable name in -`api_key_env`; raw API-key fields are not accepted. +resolved snapshot. The application schema rejects raw credential fields, but +do not treat inspection as a general-purpose filter for sensitive strings. ## Framework Source Mapping -Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit -when constructing its engine. Scriptorium does not redefine or independently -parse those framework file formats. +Scriptorium assembles selected Promptkit source files and directories in the +order described above, then constructs the Promptkit engine. Framework +definitions and custom backends belong in those selected source files, not in +the Scriptorium application configuration. Message `content_file` paths use +the defining source's resource context and are captured when the engine is +constructed; schema and request-artifact loading remain preparation-time +operations. Scriptorium does not redefine or independently parse framework +file formats. - Prompt selection, versions, message templates, inputs, output contracts, and session IDs are Promptkit contracts. @@ -192,7 +159,7 @@ parse those framework file formats. contracts. See the -[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) +[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) for all of those definitions. The files under [`examples/prompts`](../examples/prompts/), [`examples/profiles`](../examples/profiles/), and @@ -201,7 +168,7 @@ application inputs using that tagged format. Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and `promptkit-openrouter-auto`. They can be selected as a prompt default or request -profile, and custom profile sources retain precedence. Their effective model +profile, and selected application sources retain precedence. Their effective model settings may change with a catalog upgrade; use a complete application-owned profile when fixed settings are required. See the tagged format reference for the maintained-profile contract. @@ -235,7 +202,7 @@ client retains its own retry behavior. The tagged integration contract owns eligibility and timing. Promptkit's -[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) +[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md) defines outbound authentication, provider request mapping, transport limits, and timeout layering. @@ -244,4 +211,4 @@ and timeout layering. - [CLI reference](cli.md) - [HTTP API reference](api.md) - [Operations guide](operations.md) -- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md) +- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) diff --git a/docs/consumers/upgrading-promptkit.md b/docs/consumers/upgrading-promptkit.md new file mode 100644 index 0000000..02bd97f --- /dev/null +++ b/docs/consumers/upgrading-promptkit.md @@ -0,0 +1,175 @@ +# Upgrade Promptkit Sources And Definitions + +This guide moves Scriptorium application configuration and framework files to +the Promptkit v0.12.0 source model. It covers the executable CLI and HTTP +application, not the former Scriptorium Go package. For exact framework +semantics, see the tagged [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) +and [release notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/releases/v0.12.0.md). + +## Move source selectors into an ordered sequence + +Replace the old application directory settings: + +```yaml +prompt_dir: ./examples/prompts +profile_dir: ./examples/profiles +``` + +with an ordered `promptkit_sources` sequence: + +```yaml +promptkit_sources: + - directory: ./examples/prompts + - directory: ./examples/profiles + - file: ./framework/backends.yml +schema_dir: ./examples/schemas +``` + +Each item selects exactly one `file` or `directory`. Later items overlay +earlier items; conflicts within one directory source group are errors. Paths +are relative to the process working directory. An omitted or empty sequence +selects no application-supplied framework sources, while Promptkit's selected +catalog and maintained definitions remain available. A selected application +overlay replaces the whole sequence, and repeated `--promptkit-source` flags +replace it in command-line order rather than appending to it. + +The former `--prompt-dir` and `--profile-dir` flags are removed. Replace them +with repeated source flags, for example: + +```sh +scriptorium render \ + --config ./examples/config.yml \ + --promptkit-source ./examples/prompts \ + --promptkit-source ./examples/profiles \ + --promptkit-source ./examples/framework/backends.yml \ + --prompt generic.markdown_summary \ + --input transcript=./examples/fixtures/transcript.md \ + --input glossary=./examples/fixtures/glossary.yml +``` + +Use the same source selectors with `run`, `serve`, and the supported +`inspect` commands. The [CLI reference](../cli.md) lists each command's +accepted flags. + +## Relocate backend definitions + +Custom backends no longer belong in Scriptorium's application configuration. +Move them into a selected Promptkit framework source file. For example, move +this old application section: + +```yaml +backends: + local-gpu: + endpoint: http://localhost:11434/v1 + api_key_env: LOCAL_GPU_API_KEY +``` + +to `framework/backends.yml`: + +```yaml +backends: + local-gpu: + endpoint: http://localhost:11434/v1 + api_key_env: LOCAL_GPU_API_KEY +``` + +Then select that file in `promptkit_sources`. Keep only the environment +variable name in `api_key_env`; never put the credential value in a file or +command line. + +## Convert embedded identities to mapping keys + +Prompt, version, profile, and backend IDs are mapping keys. Old embedded +`id`, `version`, and `base_profile` fields are not accepted. Change a standalone +prompt definition such as: + +```yaml +id: meeting.summary +version: "1.0.0" +messages: + - role: user + content: Summarize this synthetic note. +output: + format: text + validation_mode: none +``` + +to keyed definitions: + +```yaml +prompts: + meeting.summary: + "1.0.0": + messages: + - role: user + content: Summarize this synthetic note. + output: + format: text + validation_mode: none +``` + +Retain the other valid definition content from your source. Likewise, replace profile +`base_profile: common` with `extends: common` inside the profile mapping. +`extends` names an exact sibling profile ID. It is resolved while sources are +composed, before Promptkit validates the final definitions. + +For example, move an old standalone profile: + +```yaml +id: fast +base_profile: common +timeout_seconds: 30 +``` + +under its keyed mapping and rename the inheritance field: + +```yaml +profiles: + fast: + extends: common + timeout_seconds: 30 +``` + +## Review presence, null, and map values + +Omitted values inherit or receive defaults; an explicit value can override +them even when it is `0`, `false`, or an empty string. For example, +`max_tokens: 0` is an explicit provider control, not omission. `null` is +field-specific: for example, a null `model` is unspecified, null +`timeout_seconds` restores its 600-second default, and null `extra_params` +clears the configured provider map. Check each field in the format reference +before converting old defaults or sentinel values. + +For example, express the intended behavior directly: + +```yaml +profiles: + explicit-zero: + temperature: 0 + leave-temperature-unset: + model: explicit-model + overlay-provider-options: + extra_params: + provider_option: local + clear-provider-options: + extra_params: null +``` + +Maps overlay recursively. An empty map does not erase keys inherited from a +parent or backend; use `extra_params: null` to suppress the configured map. +If changing only a model or backend, review other inherited fields because +they can remain effective. Do not infer inheritance or replacement from the +old loader's behavior. + +## Validate without a provider call + +`scriptorium config validate --config PATH` validates Scriptorium's application +configuration, including selector shape, but does not open framework sources. +Then run `scriptorium inspect configuration validate --config PATH` to build +the engine and validate all selected Promptkit definitions, including unused +ones. It does not prepare a request, resolve credentials, contact a provider, +or load request-time schemas and artifacts. A running `serve` process captures +its configuration and message content at startup; restart it after changing +those inputs. See the [configuration](../config.md) and +[operations](../operations.md) contracts for path ownership and runtime +boundaries. diff --git a/docs/operations.md b/docs/operations.md index 2649e84..409b200 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -9,7 +9,9 @@ fields, or HTTP wire behavior. - [CLI reference](cli.md): commands, output destinations, and exit codes. - [Configuration reference](config.md): application settings, source locations, defaults, and credential mapping. -- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md): +- [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise + source-selector and definition migration examples. +- [Promptkit v0.12.0 framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md): prompt, profile, schema, execution-setting, and framework credential contracts. - [HTTP API reference](api.md): route, request/response schema, status codes, @@ -39,10 +41,17 @@ without a report. ## Deploy The Filesystem And Process -Provide the process with readable configured Promptkit prompt, profile, and -schema sources that follow the tagged framework formats. For an HTTP deployment -that accepts file artifacts, use a dedicated, narrow artifact directory rather -than a general-purpose or sensitive filesystem tree. +Provide the process with readable selected Promptkit source files/directories +and schema sources that follow the tagged framework formats. At engine +construction, Promptkit v0.12 validates every selected effective definition, +including unused definitions, and captures referenced message-file contents +and static template syntax. `serve` constructs one engine at startup; it does +not reload changed configuration or message content. Restart the process to +validate and capture a new configuration. Schema and request-artifact reads, +credential resolution, and provider work remain request-preparation or runtime +concerns. For an HTTP deployment that accepts file artifacts, use a dedicated, +narrow artifact directory rather than a general-purpose or sensitive filesystem +tree. If application configuration uses explicit imports or a selected overlay, deploy those files beneath the selected configuration file's canonical @@ -87,25 +96,27 @@ and apply the same retention and access rules as for model input and output. Before changing production inputs, profiles, or schemas: -1. use `config validate`, `config show`, or `config sources` to check the - application configuration and its selected sources without constructing an - engine; this does not verify prompt files, provider access, or credentials; -2. confirm the deployed configuration selects the intended sources and model - credentials; -3. use [`render`](cli.md) with the same request inputs and variables to confirm +1. use `config validate`, `config show`, or `config sources` to check + Scriptorium's application configuration; these do not open Promptkit sources + or construct an engine; +2. use `inspect configuration validate` to construct the engine and validate + all selected framework definitions; this does not prepare a request, check + credentials, load request-time schemas/artifacts, or contact a provider; +3. confirm the deployed configuration selects the intended sources and + environment-variable names; +4. use [`render`](cli.md) with the same request inputs and variables to confirm preparation without a model call; -4. use [`run`](cli.md) for generation; and -5. retain or discard validation-failed output according to the caller's +5. use [`run`](cli.md) for generation; and +6. retain or discard validation-failed output according to the caller's policy. -Inspection output can include configuration paths, names, and ordinary backend -parameters. `config explain --path` uses JSON Pointer paths and can show -displaced historical values as well as the final value. Protect both the -selected paths and the output, especially when backend parameters contain -sensitive identifiers; ConfigKit does not infer arbitrary secrets in those -parameters. Apply -access and retention controls; the application stores only API-key environment -reference names, not the resolved credential bytes. +Application configuration inspection can include paths and configured values. +Framework `inspect configuration show` and `explain` use Promptkit's native +redaction for classified credential-shaped provider fields, including +historical values, while leaving environment-reference names and ordinary +provider parameters visible. Neither report identifies arbitrary sensitive +content by value or name. Protect inspection output accordingly; Scriptorium +stores environment-variable names, not the resolved credential bytes. The [maintained render script](../examples/render-markdown-summary.sh) is a copyable preflight example. The CLI reference owns its complete invocation and @@ -150,7 +161,7 @@ setting and then Promptkit's default, while explicit zero disables additional attempts. Existing generation timeouts apply per attempt, while the caller context covers the complete operation. Provider `Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the -[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/integrations/openai-compatible-chat.md) +[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md) for details. CLI `run` can set a [whole-run deadline](cli.md) when total execution time must diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 94c9cc6..e18bead 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -3,8 +3,8 @@ ## Status, Baseline, And Authority Planned on 2026-10-04 against Scriptorium -`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–10 are complete; stages -11–13 are pending. +`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–11 are complete; stages +12–13 are pending. This plan is for a Luna coding agent: implement the stages in sequential order, normally one stage per implementation prompt. The [feature roadmap](promptkit.md) owns the target state, scope, and confirmed @@ -615,7 +615,23 @@ redaction exception limited to it and application/framework scopes distinguishab ## Stage 11: Update User Contracts And Upgrade Guidance -Status: Pending. Depends on Stage 10. +Status: Complete. The configuration reference now owns the ordered +`promptkit_sources` sequence, empty/default behavior, source precedence and +paths, application imports/overlays, and the separation from Promptkit +definition and message-resource semantics; obsolete application backend and +directory settings were removed. The CLI reference documents repeated source +flags, removed flags, command-specific options, all four framework inspection +operations, their JSON source projection, JSON Pointer behavior, output and +exit behavior, and limited native redaction. Operations distinguish +application validation from eager framework construction and describe message +capture, restart, runtime schema/artifact/credential boundaries, and sensitive +report handling. A separate executable migration guide covers selector +replacement, backend relocation, keyed IDs/versions, `base_profile` to +`extends`, and zero/null/map review. README dependency/navigation links were +updated while the historical Go-package migration and licensing footer remain +intact. The README and composed render examples, both maintained render +scripts, application validate/explain examples, and framework validate/explain +examples ran offline; `git diff --check` passes. Files: `docs/config.md`, `docs/cli.md`, `docs/operations.md`, `README.md`, affected executable-consumer guidance and example scripts.