Update documentation for PromptKit adoption

This commit is contained in:
2026-11-18 19:25:54 +00:00
parent a2205db152
commit 50c65adac4
16 changed files with 270 additions and 347 deletions

View File

@@ -43,7 +43,6 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
| Field | Required | Meaning |
| --- | --- | --- |
| `prompt_id` | yes | Non-blank prompt ID. |
| `prompt_version` | no | Prompt version filter. |
| `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
| `session_id` | no | Optional direct, non-secret session identifier. |
| `inputs` | no | Optional object mapping input names to references. Promptkit decides whether the selected definition needs them. |
@@ -52,7 +51,7 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
| `include_raw_output` | no | Include `raw_model_output` when true. |
| `include_execution_report` | no | Include a terminal `execution` report when true and Promptkit supplies a terminal observation. Omitted, `null`, or false leaves reporting off. |
| `transient_retries` | no | Nonnegative additional transient attempt count for this run. Omitted or `null` inherits the configured engine value and then Promptkit's default; `0` disables additional attempts. |
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second limit for engine execution. Omitted, `null`, or `0` adds no deadline; positive values shorten the caller context deadline. |
| `run_timeout_seconds` | no | Optional signed 64-bit whole-second engine operation budget. Omitted, `null`, or `0` adds no deadline. |
An input reference has a required `type` of `file` or `inline`. A `file`
reference requires `uri`; an `inline` reference requires `body`.
@@ -68,16 +67,17 @@ The optional `model` object accepts `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges 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).
[PromptKit v0.23.2 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md).
Explicit zero values for the numeric fields are overrides; zero
`timeout_seconds` disables the per-attempt generation deadline only, retaining the
request context and configured transport cap. The timeout layers are defined in
the [Promptkit v0.12.0 outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
the [PromptKit v0.23.2 outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
Each built-in transient retry gets a fresh generation timeout; the caller's
request context remains the outer cancellation boundary.
Raw API-key values are not accepted. `api_key` and any other unknown model
field cause `400 invalid_json`.
Raw API-key values are not accepted. `api_key`, the removed `prompt_version`,
and any other unknown field cause `400 invalid_json`. Prompt and profile IDs
are passed unchanged, including qualified collection IDs.
`model.reasoning_effort` is an optional JSON string with three states: omission
inherits the selected profile, a non-empty string replaces its value, and an
@@ -116,14 +116,14 @@ validation contract. The response contains:
optional `uri`;
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
optional `errors` and `schema_path`;
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity, model, input-hash, usage,
timing, validation, and repair-attempt metadata; and
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity,
model parameters, input hashes, usage, and timing; and
- optional `raw_model_output` when requested.
- optional `execution` when requested and a terminal observation exists.
`metadata.model_params` has `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, and `timeout_seconds`, plus optional
`backend_id`, `service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
`service_tier`, `reasoning_effort`, `api_key_env`, and `extra_params`.
`metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
cache usage is reported as zero.
@@ -132,10 +132,11 @@ When Promptkit resolves a direct or definition-rendered session ID,
`metadata.session_id` contains that effective result value. It is omitted when
no effective session ID exists.
`metadata.selected_backend_id` and `metadata.model_params.backend_id` report
the corresponding Promptkit result fields independently when present. Both are
omitted for an endpoint-only profile; Scriptorium does not infer backend
identity from an endpoint.
`metadata.selected_backend_id` is omitted for an endpoint-only profile;
Scriptorium does not infer backend identity from an endpoint. The redundant
`prompt_version`, `model_name`, `endpoint`, `validation_mode`,
`validation_status`, `repair_attempts_used`, and `model_params.backend_id`
metadata members are not returned: use `model_params` and `validation`.
A validation failure has `validation.status: "failed"`, `is_valid: false`,
and any available diagnostic errors, while still returning the artifact and
@@ -150,7 +151,7 @@ call was dispatched; if there is no terminal event, `execution` is omitted.
| Field | Meaning |
| --- | --- |
| `run_id`, `prompt_id`, `prompt_version`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
| `run_id`, `prompt_id`, `profile_id`, `backend_id`, `model` | Terminal identifiers; absent values are omitted. |
| `outcome` | `success`, `invalid_output`, `error`, or `other` for an unrecognized upstream value. |
| `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
| `status_code` | Provider status, omitted when unavailable. |
@@ -201,7 +202,7 @@ exceed it, the response is the compact `413 response_too_large` error without
| `400` | `prompt_render_failed` | Prompt template rendering failed. |
| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
| `404` | `not_found` | Route does not exist. |
| `404` | `prompt_not_found` | Prompt ID or version does not exist. |
| `404` | `prompt_not_found` | Prompt ID does not exist. |
| `404` | `profile_not_found` | Profile ID does not exist. |
| `405` | `method_not_allowed` | The route does not accept the method. |
| `408` | `request_canceled` | The caller context was canceled during a failed run. |
@@ -212,13 +213,20 @@ exceed it, the response is the compact `413 response_too_large` error without
| `500` | `internal_error` | Unclassified server failure. |
| `502` | `llm_failed` | Outbound model request failed. |
| `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. |
| `504` | `deadline_exceeded` | The execution context's deadline expired during a failed run. |
| `504` | `deadline_exceeded` | PromptKit reports an operation timeout, or the parent deadline expired and the failed run wraps that deadline. |
These context outcomes require the execution context to have ended. A provider
attempt timeout while it remains live retains `502 llm_failed`. A successful
An operation timeout is checked before parent cancellation; a failed run
wrapping cancellation returns `408` when the parent is canceled. A provider
attempt timeout while the parent remains live retains `502 llm_failed`. A successful
run remains successful even if cancellation races with response formatting;
delivery after a client disconnect cannot be guaranteed.
With the selected PromptKit release and Go 1.27.4, an operation budget that
expires during an in-flight built-in HTTP request can currently surface as
`502 llm_failed` instead of the intended `504`: the transport may return the
operation's cancellation cause without the typed timeout. Retry and capacity
waits are attributed correctly. Treat this as a known upstream limitation.
## Retry And Idempotency
Scriptorium provides no idempotency keys, pagination, caching headers, or rate

View File

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

View File

@@ -3,7 +3,7 @@
This is the canonical reference for Scriptorium application settings. Prompt,
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).
[PromptKit v0.23.2 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/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). For migration examples, see
[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md).
@@ -33,7 +33,7 @@ copyable examples.
## Application Configuration File
Application configuration is decoded by ConfigKit v1.2.0 as strict YAML.
Application configuration is decoded by ConfigKit v1.2.1 as strict YAML.
Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors
are rejected.
An explicit empty string is a value and may clear a file-provided optional
@@ -60,12 +60,12 @@ schema_dir: ./examples/schemas
```
An empty or null final resolved `promptkit_sources` list selects no
application-supplied framework sources; Promptkit's selected catalog and
maintained definitions still apply. A later sequence item overlays an earlier
application-supplied framework sources; PromptKit's bundled OpenRouter underlay
still applies. 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).
source rules belong to the [PromptKit v0.23.2 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md).
Selector paths are relative to the process working directory, not to the
application configuration file. Application validation checks the selector
@@ -77,11 +77,32 @@ and preserve flag order. Without an authored collection policy, a selected
overlay replaces `promptkit_sources` as a whole; a declared sequence policy
may instead combine the lists.
### Collection checkout discovery
Select a framework discovery file using the existing file selector, as in
[config.discovery.yml](../examples/config.discovery.yml). Its native imports
select both supported collection-entry spellings:
```yaml
config:
imports:
- glob: collections/*/collection.yml
- glob: collections/*/collection.yaml
```
Both globs are optional, so either spelling may have no matches. Paths are
relative to the framework file; this example's `*` selects one checkout
level and is not a general layout restriction. Each entry declares its own
collection namespace and imports only its intended resource fragments. The
checkout directory name does not determine the namespace. New checkouts are
available on the next invocation without editing this file; a running server
does not reload them. See the [maintained collection examples](../examples/discovery/collections/).
### Explicit imports and selected overlays
Application files declare imports under root `config.imports`. Native `path`,
`dir`, and `glob` selectors, filters, recursion, destinations, and item
placement are available as described in the [pinned ConfigKit contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).
placement are available as described in the [pinned ConfigKit contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md).
Imports are optional by default; set `required: true` when absence must fail.
The old `optional` field is not supported. Directory selection has no default
filename filter; author a pattern when only YAML files are intended. ConfigKit
@@ -103,13 +124,13 @@ contributes no records and `null` is invalid. To clear a collection with an
inherited policy, declare `mode: replace` at
`destination: [promptkit_sources]` in the higher-precedence source and supply
`promptkit_sources: []`. See
[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md#yaml-declarations-and-policy-lifetime)
[ConfigKit's collection policy contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md#yaml-declarations-and-policy-lifetime)
for policy lifetime and combination rules.
These application root `config` controls do not change the separate
Promptkit v0.12.0 framework format: its selected framework files use the
[Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
and its older ConfigKit controls.
PromptKit v0.23.2 framework format: its selected framework files use the
[Promptkit contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
and their own native ConfigKit `config` controls.
`--config-overlay NAME` selects one file at `overlays/NAME.yml` below that
root. The name must use letters, digits, `_`, or `-`; it is not a path. Empty
@@ -195,7 +216,7 @@ 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
- Prompt selection by ID, message templates, inputs, output contracts, and
session IDs are Promptkit contracts.
- Profile fields, numeric ranges, execution defaults, overlay precedence,
built-in profiles, and credential rules are Promptkit contracts.
@@ -203,19 +224,18 @@ file formats.
contracts.
See the
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
[tagged Promptkit format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
for all of those definitions. The files under
[`examples/prompts`](../examples/prompts/),
[`examples/profiles`](../examples/profiles/), and
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium
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 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.
PromptKit supplies a default-on OpenRouter bundle as the lowest-priority
underlay. Choose an actual bundled profile such as `auto`, or a complete
application-owned profile; old catalog IDs are not aliases. Caller definitions
can replace bundled records by normal composition. Bundle availability is not
a readiness check or a promise of a fixed provider model.
## Credentials And Outbound Behavior
@@ -246,7 +266,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.12.0/docs/integrations/openai-compatible-chat.md)
[OpenAI-compatible integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/integrations/openai-compatible-chat.md)
defines outbound authentication, provider request mapping, transport limits,
and timeout layering.
@@ -255,4 +275,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.12.0/docs/formats.md)
- [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)

View File

@@ -13,8 +13,8 @@ and the HTTP service according to the boundary your application needs.
- Application configuration: [configuration reference](../config.md)
Go applications that need an in-process prompt framework should import
Promptkit directly. The tagged
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
`go.maximumdirect.net/promptkit` directly. The tagged
[Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
owns that interface; Scriptorium does not provide a Go library package.
Consumers arriving from the former Scriptorium Go API should follow the
[migration guide](migrating-to-promptkit.md).
@@ -35,4 +35,4 @@ Scriptorium does not persist run state. A retry can produce different output
and can incur another provider request. CLI exits belong to the
[CLI reference](../cli.md), HTTP status behavior belongs to the
[HTTP API reference](../api.md), and framework semantics belong to
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
[PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md).

View File

@@ -1,5 +1,11 @@
# Migrate From Scriptorium To Promptkit
This historical first hop targets Promptkit v0.11.1 and its former module
path. For the current public module `go.maximumdirect.net/promptkit` and the
ID-only configuration cutover, follow the
[current upgrade guide](upgrading-promptkit.md) afterward and consult the
[current Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md).
## Supported Migration Boundary
Scriptorium `v0.11.1` at

View File

@@ -1,175 +1,101 @@
# Upgrade Promptkit Sources And Definitions
# 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).
This guide covers the CLI and framework configuration cutover to
[PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/configuration-migration.md)
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
for the full upstream contract.
## Move source selectors into an ordered sequence
Removing version selectors and changing framework definition shapes are
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
Replace the old application directory settings:
## Application configuration
```yaml
prompt_dir: ./examples/prompts
profile_dir: ./examples/profiles
```
with an ordered `promptkit_sources` sequence:
Existing application fields that already select the desired sources retain
their meaning. For example, this application configuration works both before
and after the cutover:
```yaml
promptkit_sources:
- directory: ./examples/prompts
- directory: ./examples/profiles
- file: ./framework/backends.yml
- file: ./examples/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 selected framework files must still be rewritten as described below.
Scriptorium uses one native application schema: discovery, imports, selected
overlays, source order, explicit overrides, and working-directory-relative
selector paths remain application configuration behavior. It loads framework
sources separately with PromptKit's schema. No second application schema or
legacy definition reader is provided. See the [configuration reference](../config.md).
The former `--prompt-dir` and `--profile-dir` flags are removed. Replace them
with repeated source flags, for example:
## Rewrite framework definitions
```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:
Replace version-keyed prompts and keyed profile/backend mappings with lists
of records containing `id`. For example, before:
```yaml
prompts:
meeting.summary:
"1.0.0":
report:
"1":
default_profile: fast
messages:
- role: user
content: Summarize this synthetic note.
content: Summarize this 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
endpoint: https://example.invalid/v1
model: synthetic-model
```
## 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:
After:
```yaml
prompts:
- id: report
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
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
- id: fast
endpoint: https://example.invalid/v1
model: synthetic-model
```
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.
Select prompts by exact ID; `--prompt-version` is rejected. If multiple former
versions must remain independently selectable, give them distinct IDs and
update callers. Qualified IDs such as `support/answer` are passed unchanged.
Keep relative message files beside their owning definitions. Convert framework
source controls from `configkit:` to `config:` and add `required: true` for
imports that must exist. An optional framework source header, if present, is
`version: 2`. Use sibling inheritance such as `extends: {id: base}`.
## Validate without a provider call
Composition now replaces a whole record when a later source selects the same
ID; supply the complete intended replacement, or create a distinct inherited
record. Null profile endpoint, credential, or provider-map settings can fall
back to the selected backend; review behavior rather than assuming null clears
backend values. Keep JSON schemas self-contained instead of depending on remote
schema references. Application selectors remain separate from these framework
semantics.
`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.
## Replace catalog selections
The default-on OpenRouter bundle supplies actual profiles such as `auto` and
`gpt-sol-latest`. Former catalog and `promptkit-openrouter-*` IDs are not
compatibility aliases. Choose an intended current bundled profile explicitly,
or define a complete local profile with the endpoint, model, and settings you
need. Do not assume a new default model. The bundle is an underlay and caller
records can replace it through ordinary composition.
For multiple independently maintained repositories, see the
[collection-discovery example](../../examples/config.discovery.yml). Its
entry files declare their own namespaces; checkout names do not become IDs.
The [CLI reference](../cli.md) demonstrates qualified rendering and the
[operations guide](../operations.md) describes when updates take effect.

View File

@@ -2,11 +2,11 @@
This is the contributor entry point for Scriptorium. Scriptorium is an
application that consumes the public
[Promptkit v0.12.0 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md);
[PromptKit v0.23.2 package](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md);
framework implementation work belongs in Promptkit. Application configuration
uses ConfigKit v1.2.0; keep Scriptorium's schema and source selection local.
Promptkit uses ConfigKit v0.5.0 to load framework sources under its own
schema and format contract.
uses ConfigKit v1.2.1; keep Scriptorium's schema and source selection local.
PromptKit uses the same ConfigKit release to load framework sources under its
own separate schema and format contract.
## Initial Orientation
@@ -48,13 +48,13 @@ Before recommending, planning, or implementing work:
| Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests |
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` |
| Promptkit source selection or captured framework inspection | [Configuration contract](config.md#promptkit-source-selectors), [framework configuration CLI contract](cli.md#framework-configuration-inspection), and [source internals](internal/sources.md) |
| Prompt, profile, schema, generation, or validation semantics | [Promptkit v0.12.0 framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) |
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit v0.12.0 integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md) |
| Prompt, profile, schema, generation, or validation semantics | [PromptKit v0.23.2 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md) and the [Promptkit consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md) |
| OpenAI-compatible outbound behavior or timeout layering | [PromptKit v0.23.2 integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/integrations/openai-compatible-chat.md) |
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
| Runtime operation or recovery | [Operations](operations.md) |
| Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) |
| Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) |
| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit v0.12.0 format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md), and the related files under `examples/` |
| Examples or copyable assets | The owning Scriptorium contract, the relevant [PromptKit v0.23.2 format contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md), and the related files under `examples/` |
| Architecture decisions or future work | The [documentation policy](policy/documentation.md), relevant accepted ADRs, and relevant roadmap documents |
Cross-project changes land and release in Promptkit before Scriptorium adopts
@@ -64,7 +64,7 @@ Promptkit source, or an import of a Promptkit `internal` package.
## Baseline Validation
The Go consumer minimum is the version declared in `go.mod`, currently 1.27.0,
required by application ConfigKit v1.2.0. Running a published binary does not
required by application ConfigKit v1.2.1. Running a published binary does not
require a Go installation. Release validation and builds use
the separately selected toolchain in the [release procedure](release.md).

View File

@@ -55,8 +55,10 @@ protocol.
For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
engine invocation. It is separate from the per-attempt generation timeout and
does not include child startup or output writing. A deadline failure exits 1;
supervisors still own process termination when they need to stop the child
does not include child startup or output writing. A typed operation deadline
failure exits 1; an in-flight built-in HTTP timeout can currently be reported
as a transport failure as described in the [API reference](../api.md#error-responses).
Supervisors still own process termination when they need to stop the child
outside that engine interval.
For deployment, filesystem permissions, and sensitive-artifact handling, see

View File

@@ -9,7 +9,7 @@ own IO and presentation mechanics, not framework decisions.
External contracts are canonical in the [CLI reference](../cli.md) and
[HTTP API reference](../api.md). Promptkit's public engine contract is
described by its tagged
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md).
[Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md).
## Components And Collaborators
@@ -20,11 +20,11 @@ described by its tagged
exposes application and captured framework configuration inspection, and
owns output files, summaries, and exit codes.
- `internal/config` delegates application YAML decoding, default resolution,
overrides, and validation ordering to ConfigKit v1.2.0. The CLI supplies only
overrides, and validation ordering to ConfigKit v1.2.1. The CLI supplies only
explicitly visited application flags as overrides and renders safe structured
load diagnostics on stderr. Promptkit uses old-path ConfigKit v0.5.0 to load
framework sources under its own definition and format contract. Errors and
warnings are written by the owning generation's native diagnostic writer.
load diagnostics on stderr. PromptKit uses the same ConfigKit release to
load framework sources under its own definition and format contract. Both
domains use ConfigKit's native diagnostic writer.
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
public values, calls its adapter-owned `Runner` interface, and maps results
and errors to HTTP DTOs.
@@ -38,7 +38,7 @@ described by its tagged
### CLI
`run` calls `promptkit.Engine.Run`; `render` calls
`promptkit.Engine.Prepare`. Both share request mapping for prompt ID/version
`promptkit.Engine.Prepare`. Both share request mapping for exact prompt ID
and profile selection, optional file inputs, variables, and presence-aware
execution overrides. Omitted framework settings remain zero values so Promptkit
resolves its own defaults and definition-required inputs.
@@ -47,10 +47,10 @@ run/render flag enters only the mapped request. The server uses the same engine
setting and retains one backend admission state. Render prepares without
generation.
`inspect prompt` maps the selected ID and optional version to
`inspect prompt` maps the selected ID to
`promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection
data. `inspect profile` maps an explicit profile ID to `Engine.InspectProfile`
and formats Scriptorium-owned effective profile data.
and formats Scriptorium-owned resolved profile data without backend completion.
Both paths construct the same full-source engine as execution before inspecting
the chosen definition; selected prompts are not filtered out. They do not
@@ -79,7 +79,7 @@ adapter's consumer-owned `Runner` interface, and starts the server.
The command paths assemble the engine from application-selected framework
source files and directories plus the schema directory and retry setting.
Individual files become import-enabled old-path ConfigKit inputs; directory selections
Individual files become import-enabled ConfigKit inputs; directory selections
are expanded through Promptkit's directory-input helper. Scriptorium supplies
those ordered underlays through Promptkit's public configuration API rather
than parsing or mapping framework definitions itself. The server constructs
@@ -95,6 +95,9 @@ validation, model, usage, and metadata values directly.
The optional HTTP retry count maps to `RunRequest.TransientRetries` without
mutating the shared engine. Negative values are rejected before invocation;
Promptkit controls retries and backend admission for concurrent requests.
CLI and HTTP operation budgets map to PromptKit's `OperationTimeout`; HTTP
passes the caller context through unchanged. The public sentinels determine
timeout classification, subject to the documented transport limitation.
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader

View File

@@ -9,11 +9,11 @@ public behavior belongs in the linked contracts.
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/adapter/cli` | Parses execution, application-configuration, and captured framework-configuration inspection commands; resolves settings; constructs Promptkit engines for execution, definition inspection, and framework inspection; maps requests; and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/config` | Selects application sources through ConfigKit v1.2.0, supplies the application definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/config` | Selects application sources through ConfigKit v1.2.1, supplies the application definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) |
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output; framework-configuration output uses Promptkit's native captured view and writers. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
Framework implementation packages are provided by
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
[PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
and are not part of this repository.

View File

@@ -5,7 +5,7 @@
This document covers Scriptorium-owned source locations and the restricted HTTP
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
owned by the tagged
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
[PromptKit v0.23.2 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md).
## Application Source Locations
@@ -13,10 +13,12 @@ owned by the tagged
`schema_dir` from application configuration and explicit CLI overrides. It
owns selector-shape validation, not framework file parsing. During engine
construction, `internal/adapter/cli` turns file selections into import-enabled
old-path ConfigKit v0.5.0 inputs and expands directory selections with
ConfigKit inputs and expands directory selections with
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
configuration underlays. The shared Promptkit engine receives the selected
schema directory and retry setting as well.
configuration underlays, one per selector. Directory inputs retain the
helper's strict-composition grouping; no selected source becomes an implicit
framework main. The shared Promptkit engine receives the selected schema
directory and retry setting, and the default OpenRouter bundle remains enabled.
Promptkit uses ConfigKit to load and compose those framework inputs according
to Promptkit's own schema and format. Scriptorium does not parse or validate
@@ -36,9 +38,9 @@ constants; its resolver records only actual leaf-level trimming, path cleaning,
render-format normalization. The validator reports selector-shape, retry,
size-limit, and format errors without mutating the document or exposing
rejected values. Application path values keep working-directory-relative
meaning. ConfigKit v1.2.0 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by Promptkit through
its older ConfigKit under Promptkit's own schema and source contract.
meaning. ConfigKit v1.2.1 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by PromptKit using
the same ConfigKit release under PromptKit's own schema and source contract.
The `Load` boundary selects an explicit file or constructs a native ConfigKit
search over the ordered implicit paths. Discovery exhaustion uses defaults;

View File

@@ -11,7 +11,7 @@ fields, or HTTP wire behavior.
locations, defaults, and credential mapping.
- [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):
- [PromptKit v0.23.2 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md):
prompt, profile, schema, execution-setting, and framework credential
contracts.
- [HTTP API reference](api.md): route, request/response schema, status codes,
@@ -43,7 +43,7 @@ without a report.
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,
construction, PromptKit v0.23.2 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
@@ -61,12 +61,15 @@ resolve from the process working directory, so set that directory deliberately
in the service manager. This configuration-source boundary is distinct from
the HTTP artifact root and does not constrain prompt or schema directories.
When upgrading existing definitions, review selected profile IDs.
`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro` were removed from the
selected catalog. Choose an available catalog profile, one of Promptkit's
maintained names, or a complete application-owned profile. New DeepSeek names
are not aliases for the removed ones; see the
[v0.10 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md).
For independently maintained collections, place checkouts beneath the
directory selected by your framework discovery file. The maintained
[discovery example](../examples/config.discovery.yml) selects optional
`collection.yml` and `collection.yaml` entry files; each checkout owns its
namespace and explicit fragment imports. Update a checkout independently and
invoke the CLI again, or restart a running server to capture the update. Do
not treat arbitrary YAML in a checkout as a framework source. When upgrading
definitions, review exact profile IDs and replace retired catalog references
as described in the [migration guide](consumers/upgrading-promptkit.md).
Run Scriptorium under an identity that can:
@@ -161,7 +164,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.12.0/docs/integrations/openai-compatible-chat.md)
[outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/integrations/openai-compatible-chat.md)
for details.
CLI `run` can set a [whole-run deadline](cli.md) when total execution time must
@@ -169,10 +172,11 @@ be bounded. The existing generation timeout applies afresh to each attempt and
does not cap retry waits or the complete invocation. The whole-run interval
covers the engine call, including capacity waiting and repairs as supported by
context cancellation; it excludes parsing, engine setup, and output writes.
HTTP callers can use [`run_timeout_seconds`](api.md) to shorten their request
context for the same engine interval. The API distinguishes an expired
HTTP callers can use [`run_timeout_seconds`](api.md) to set the engine's
operation budget for the same interval. The API distinguishes a typed expired
execution deadline from caller cancellation and from a provider-attempt
timeout. A canceled capacity waiter releases its Promptkit admission state.
timeout, subject to the documented in-flight transport limitation. A canceled
capacity waiter releases its Promptkit admission state.
Before increasing a limit:

View File

@@ -5,9 +5,8 @@
Material: `docs/policy/oss.md`, `docs/policy/meta.md`,
`docs/policy/agents.md`, `docs/policy/documentation.md`,
`docs/policy/architecture.md`, `docs/policy/testing.md`,
`docs/policy/release.md`, `AGENTS.md`, and the
Policy Reading Guide section of `docs/development.md`, adapted for this
repository.
`docs/policy/release.md`, `AGENTS.md`, and the Policy Reading Guide section
of `docs/development.md`, adapted for this repository.
Copyright (C) 2026 Eric Rakestraw
@@ -16,12 +15,11 @@ SPDX-License-Identifier: CC-BY-SA-4.0
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
## Promptkit
## PromptKit
Selected module: `gitea.maximumdirect.net/eric/promptkit` at `v0.12.0`.
Selected module: `go.maximumdirect.net/promptkit` at `v0.23.2`.
Copyright (C) 2026 Eric Rakestraw
@@ -29,14 +27,13 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/LICENSE).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71).
[Source](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3).
## ConfigKit
## ConfigKit (application)
Selected module: `go.maximumdirect.net/configkit` at `v1.2.0`.
Selected module: `go.maximumdirect.net/configkit` at `v1.2.1`.
Copyright (C) 2026 Eric Rakestraw
@@ -44,102 +41,35 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e).
## ConfigKit (Promptkit dependency)
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.5.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd).
## Promptkit OpenRouter Catalog
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3` at `v3.20260930.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0).
## Promptkit Rakestrawhome Catalog
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3` at `v3.20260930.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
## jsonschema/v6
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.2`.
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71).
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/b0fc661f4939578bc429f408c18202573dbafcc4).
## golang.org/x/text
Selected module: `golang.org/x/text` at `v0.14.0`.
Selected module: `golang.org/x/text` at `v0.44.0`.
Copyright (c) 2009 The Go Authors. All rights reserved.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE).
[Source](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353).
## gopkg.in/yaml.v3
Selected module: `gopkg.in/yaml.v3` at `v3.0.1`.
Copyright (c) 2006-2010 Kirill Simonov
Copyright (c) 2006-2011 Kirill Simonov
Copyright (c) 2011-2019 Canonical Ltd
Copyright 2011-2016 Canonical Ltd.
SPDX-License-Identifier: MIT AND Apache-2.0
License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[Source](https://github.com/go-yaml/yaml/tree/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
[LICENSE](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE).
[Source](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513).
## go.yaml.in/yaml/v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov
@@ -151,7 +81,10 @@ SPDX-License-Identifier: MIT AND Apache-2.0
License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
[Source](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
The module graph can also contain upstream maintainer tools such as ReleaseKit
and their dependencies. Those graph-only tools are not linked into the
Scriptorium runtime binary.

View File

@@ -50,24 +50,24 @@ inventory; [adapter internals](../internal/adapters.md) and
## Framework And Application Boundaries
Scriptorium consumes
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
[PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
through its supported public root package. Promptkit owns prompt execution,
preparation, prompt and profile formats, built-in profiles, model-client
behavior, validation, and framework defaults. Scriptorium owns application
configuration, executable CLI and HTTP adapters, prepared-run and
definition-inspection presentation, captured-configuration inspection
exposure, process behavior, and HTTP deployment policy. The [format
reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md)
reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
and [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/integrations/openai-compatible-chat.md)
remain Promptkit's contracts.
Scriptorium uses ConfigKit v1.2.0 for strict application YAML decoding,
Scriptorium uses ConfigKit v1.2.1 for strict application YAML decoding,
resolution, and validation flow. Scriptorium retains its application schema,
defaults, normalization, validation rules, source selection, and CLI override
mapping. Promptkit uses its own ConfigKit v0.5.0 dependency to decode and
assemble framework sources under Promptkit's schema and format contract; Scriptorium selects
the inputs but does not parse Promptkit definitions. These ConfigKit generations
are loading mechanisms, not owners of either domain schema or HTTP artifact
mapping. PromptKit uses the same ConfigKit generation to decode and assemble
framework sources under its separate schema and format contract; Scriptorium
selects the inputs but does not parse PromptKit definitions. ConfigKit is a
loading mechanism, not the owner of either domain schema or HTTP artifact
containment. The [configuration contract](../config.md) owns externally
observable application behavior, while Promptkit owns framework formats.

View File

@@ -296,6 +296,8 @@ scaffolding, or conversation and coordination features.
## Stage 7: Update canonical docs and component notices
**Status: Complete.**
1. Put before/after application and framework examples in
[upgrading-promptkit.md](../consumers/upgrading-promptkit.md). Explain
that unchanged app fields still work through the one native schema,