Document PromptKit source migration

This commit is contained in:
2026-10-04 13:04:02 +00:00
parent 411a67b241
commit b913ef0d07
6 changed files with 384 additions and 166 deletions

View File

@@ -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

View File

@@ -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

View File

@@ -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)

View File

@@ -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.

View File

@@ -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

View File

@@ -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.