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

@@ -6,7 +6,7 @@ OpenAI-compatible model endpoints, and returns generated output with validation
metadata. metadata.
The application uses The application uses
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/) [PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/)
for prompt, profile, schema, preparation, generation, and validation behavior. for prompt, profile, schema, preparation, generation, and validation behavior.
Scriptorium owns executable configuration, CLI and HTTP mapping, process Scriptorium owns executable configuration, CLI and HTTP mapping, process
behavior, output presentation, and HTTP artifact-containment policy. behavior, output presentation, and HTTP artifact-containment policy.
@@ -41,15 +41,16 @@ a model. For complete invocation and output behavior, see the
- [Upgrade Promptkit source selectors and definitions](docs/consumers/upgrading-promptkit.md) - [Upgrade Promptkit source selectors and definitions](docs/consumers/upgrading-promptkit.md)
- [Subprocess integration](docs/integrations/subprocess.md) - [Subprocess integration](docs/integrations/subprocess.md)
- [Architecture policy](docs/policy/architecture.md) - [Architecture policy](docs/policy/architecture.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)
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) - [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md)
## Examples ## Examples
- [Minimal configuration](examples/config.yml) and - [Minimal configuration](examples/config.yml) and
[complete configuration](examples/config.full.yml), plus a [complete configuration](examples/config.full.yml), plus a
[composed import/overlay example](examples/config.composed.yml), a [composed import/overlay example](examples/config.composed.yml), a
[collection composition example](examples/config.collections.yml), and a [collection composition example](examples/config.collections.yml), a
[collection checkout discovery example](examples/config.discovery.yml), and a
[backend inheritance example](examples/config.inheritance.yml) [backend inheritance example](examples/config.inheritance.yml)
- [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), - [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/),
[schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/) [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/)

View File

@@ -43,7 +43,6 @@ copyable shape. At the HTTP adapter boundary, the smallest valid shape is:
| Field | Required | Meaning | | Field | Required | Meaning |
| --- | --- | --- | | --- | --- | --- |
| `prompt_id` | yes | Non-blank prompt ID. | | `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`. | | `profile_id` | no | Execution-profile ID; otherwise the prompt must set `default_profile`. |
| `session_id` | no | Optional direct, non-secret session identifier. | | `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. | | `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_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. | | `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. | | `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` An input reference has a required `type` of `file` or `inline`. A `file`
reference requires `uri`; an `inline` reference requires `body`. 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`, `max_tokens`, `top_p`, `timeout_seconds`, `service_tier`,
`reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and `reasoning_effort`, `api_key_env`, and `extra_params`. Numeric ranges and
framework credential semantics are defined by the 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 Explicit zero values for the numeric fields are overrides; zero
`timeout_seconds` disables the per-attempt generation deadline only, retaining the `timeout_seconds` disables the per-attempt generation deadline only, retaining the
request context and configured transport cap. The timeout layers are defined in 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 Each built-in transient retry gets a fresh generation timeout; the caller's
request context remains the outer cancellation boundary. request context remains the outer cancellation boundary.
Raw API-key values are not accepted. `api_key` and any other unknown model Raw API-key values are not accepted. `api_key`, the removed `prompt_version`,
field cause `400 invalid_json`. 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 `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 inherits the selected profile, a non-empty string replaces its value, and an
@@ -116,14 +116,14 @@ validation contract. The response contains:
optional `uri`; optional `uri`;
- `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus - `validation`: `status`, `mode`, `repair_attempts`, `is_valid`, plus
optional `errors` and `schema_path`; optional `errors` and `schema_path`;
- `metadata`: run, prompt, rendered-prompt, profile, optional backend identity, model, input-hash, usage, - `metadata`: run, prompt, rendered-prompt, profile, optional backend identity,
timing, validation, and repair-attempt metadata; and model parameters, input hashes, usage, and timing; and
- optional `raw_model_output` when requested. - optional `raw_model_output` when requested.
- optional `execution` when requested and a terminal observation exists. - optional `execution` when requested and a terminal observation exists.
`metadata.model_params` has `endpoint`, `model`, `temperature`, `metadata.model_params` has `endpoint`, `model`, `temperature`,
`max_tokens`, `top_p`, and `timeout_seconds`, plus optional `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`, `metadata.usage` always includes `prompt_tokens`, `completion_tokens`,
`total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable `total_tokens`, `cached_tokens`, and `cache_write_tokens`; unavailable
cache usage is reported as zero. 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 `metadata.session_id` contains that effective result value. It is omitted when
no effective session ID exists. no effective session ID exists.
`metadata.selected_backend_id` and `metadata.model_params.backend_id` report `metadata.selected_backend_id` is omitted for an endpoint-only profile;
the corresponding Promptkit result fields independently when present. Both are Scriptorium does not infer backend identity from an endpoint. The redundant
omitted for an endpoint-only profile; Scriptorium does not infer backend `prompt_version`, `model_name`, `endpoint`, `validation_mode`,
identity from an endpoint. `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`, A validation failure has `validation.status: "failed"`, `is_valid: false`,
and any available diagnostic errors, while still returning the artifact and 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 | | 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. | | `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. | | `failure` | The known terminal failure category, `none`, or `other` for an unrecognized value. |
| `status_code` | Provider status, omitted when unavailable. | | `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` | `prompt_render_failed` | Prompt template rendering failed. |
| `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. | | `400` | `api_key_env_missing` | The selected credential environment variable is unset or empty. |
| `404` | `not_found` | Route does not exist. | | `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. | | `404` | `profile_not_found` | Profile ID does not exist. |
| `405` | `method_not_allowed` | The route does not accept the method. | | `405` | `method_not_allowed` | The route does not accept the method. |
| `408` | `request_canceled` | The caller context was canceled during a failed run. | | `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. | | `500` | `internal_error` | Unclassified server failure. |
| `502` | `llm_failed` | Outbound model request failed. | | `502` | `llm_failed` | Outbound model request failed. |
| `503` | `capacity_exceeded` | The selected model backend has no admission capacity. No retry timing is supplied. | | `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 An operation timeout is checked before parent cancellation; a failed run
attempt timeout while it remains live retains `502 llm_failed`. A successful 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; run remains successful even if cancellation races with response formatting;
delivery after a client disconnect cannot be guaranteed. 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 ## Retry And Idempotency
Scriptorium provides no idempotency keys, pagination, caching headers, or rate 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 render`: prepare a prompt and write prepared-run output.
- `scriptorium serve`: start the HTTP server. - `scriptorium serve`: start the HTTP server.
- `scriptorium inspect prompt`: inspect one prompt definition without model execution. - `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 inspect configuration`: validate or inspect Promptkit's captured framework configuration.
- `scriptorium config validate`: validate application configuration without building an engine. - `scriptorium config validate`: validate application configuration without building an engine.
- `scriptorium config show`: show the resolved application configuration. - `scriptorium config show`: show the resolved application configuration.
@@ -66,7 +66,6 @@ Optional flags:
| `--config-overlay <name>` | Selected application configuration overlay. | | `--config-overlay <name>` | Selected application configuration overlay. |
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. | | `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
| `--schema-dir <dir>` | Schema base-directory override. | | `--schema-dir <dir>` | Schema base-directory override. |
| `--prompt-version <version>` | Optional prompt-definition version selector. |
| `--profile <id>` | Execution-profile override. | | `--profile <id>` | Execution-profile override. |
| `--session-id <id>` | Optional direct session identifier. | | `--session-id <id>` | Optional direct session identifier. |
| `--input name=path` | Optional input file mapping; repeat or use comma-separated mappings. | | `--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 durations are converted to whole seconds by truncation toward zero, so any
duration whose absolute value is below one second becomes an explicit duration whose absolute value is below one second becomes an explicit
zero-second override. The timeout layers are defined in the 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; With the built-in client, each transient retry gets a fresh generation timeout;
this flag does not limit the complete run. this flag does not limit the complete run.
`--run-timeout` keeps subsecond precision and starts immediately before engine `--run-timeout` keeps subsecond precision and starts immediately before engine
execution. It bounds preparation, capacity waits, retry waits, generation, and execution. It bounds preparation, capacity waits, retry waits, generation, and
repairs where they honor context. Parsing, engine construction, and output repairs where they honor context. Parsing, engine construction, and output
writes are outside that interval. A failed run whose execution context reaches writes are outside that interval. A failed run identified by PromptKit as an
this deadline exits 1 with a safe deadline diagnostic; a completed invalid operation timeout exits 1 with a safe deadline diagnostic; a completed invalid
output still exits 2. It does not promise immediate interruption of synchronous output still exits 2. Synchronous work may not stop immediately. The selected
work. 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 Omitting `--transient-retries` inherits the application setting or Promptkit's
current default of two additional attempts. The flag overrides only this current default of two additional attempts. The flag overrides only this
request; it does not alter the configured engine. Structural repair generations 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`. There is no raw API-key flag. Use `--api-key-env`.
`--prompt-version` is passed directly to Promptkit. When it is omitted, the Prompt and profile IDs are passed unchanged, including collection-qualified
selected prompt ID must have exactly one available version. `--input` is IDs. The removed `--prompt-version` flag is rejected. `--input` is optional
optional at the CLI boundary: Promptkit decides whether the selected definition at the CLI boundary: PromptKit decides whether the selected definition requires
requires declared inputs or template-referenced values. declared inputs or template-referenced values.
`--session-id` supplies a direct, non-secret session identifier. A nonblank `--session-id` supplies a direct, non-secret session identifier. A nonblank
value replaces a definition-rendered session ID; an omitted or blank value lets 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: `--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`, `--input`, `--var`, `--out`, `--llm-base-url`,
`--model`, `--api-key-env`, `--temperature`, `--max-tokens`, `--top-p`, `--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 `--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 `render` resolves profiles and schemas as part of preparation but
does not call an LLM. 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` ## `scriptorium serve`
```text ```text
@@ -201,7 +212,7 @@ schemas, and error codes are defined in the [HTTP API reference](api.md).
## `scriptorium inspect prompt` ## `scriptorium inspect prompt`
```text ```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] [--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. artifacts, resolve credential values, reserve backend capacity, or call a model.
Prompt inspection does not select an execution profile or render request-specific Prompt inspection does not select an execution profile or render request-specific
templates. 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` ## `scriptorium inspect profile`
@@ -229,9 +243,11 @@ scriptorium inspect profile --profile ID
``` ```
`--profile` is required. After the [full-source engine construction described `--profile` is required. After the [full-source engine construction described
above](#scriptorium-inspect-prompt), inspection selects one effective profile above](#scriptorium-inspect-prompt), inspection selects one resolved profile
with resolved inheritance and backend defaults. Unset provider controls are with inheritance. `profile_model_params` contains only fields present on that
shown as zero values when Promptkit leaves them unspecified. 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 ## 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 `explain` requires an explicitly supplied `--path` in ConfigKit JSON Pointer
syntax; `--path ''` selects the root. For example, syntax; `--path ''` selects the root. For example,
`/profiles/team~1summary/model` addresses the `model` field of the literal `/collections/support/profiles/0/model` addresses the first support profile's
profile ID `team/summary`. Escape `/` as `~1` and `~` as `~0`; dots in a key 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 remain literal. Malformed and unknown pointers exit 1 without a successful
report. Explanation prose is native and is not a stable machine-readable report. Explanation prose is native and is not a stable machine-readable
format. 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 limited to framework configuration reports; it does not add redaction to
`inspect profile` or prepared-run output. Credentials are not resolved by any `inspect profile` or prepared-run output. Credentials are not resolved by any
of these inspection operations. Promptkit owns detailed field and source 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 Warnings and errors go to stderr. Successful `validate` writes nothing to
stdout; successful `show`, `sources`, and `explain` write their reports there. 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, This is the canonical reference for Scriptorium application settings. Prompt,
profile, backend, schema, execution-setting, built-in profile, and framework profile, backend, schema, execution-setting, built-in profile, and framework
credential semantics are defined by the 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 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 outcomes, see the [HTTP API reference](api.md). For migration examples, see
[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md). [Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md).
@@ -33,7 +33,7 @@ copyable examples.
## Application Configuration File ## 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 Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors
are rejected. are rejected.
An explicit empty string is a value and may clear a file-provided optional 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 An empty or null final resolved `promptkit_sources` list selects no
application-supplied framework sources; Promptkit's selected catalog and application-supplied framework sources; PromptKit's bundled OpenRouter underlay
maintained definitions still apply. A later sequence item overlays an earlier still applies. A later sequence item overlays an earlier
one. Files within a selected directory are composed together, so conflicting one. Files within a selected directory are composed together, so conflicting
definitions in that group fail instead of using filename order as precedence. definitions in that group fail instead of using filename order as precedence.
An explicit file may use ConfigKit imports. The complete framework format and 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 Selector paths are relative to the process working directory, not to the
application configuration file. Application validation checks the selector 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 overlay replaces `promptkit_sources` as a whole; a declared sequence policy
may instead combine the lists. 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 ### Explicit imports and selected overlays
Application files declare imports under root `config.imports`. Native `path`, Application files declare imports under root `config.imports`. Native `path`,
`dir`, and `glob` selectors, filters, recursion, destinations, and item `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. Imports are optional by default; set `required: true` when absence must fail.
The old `optional` field is not supported. Directory selection has no default The old `optional` field is not supported. Directory selection has no default
filename filter; author a pattern when only YAML files are intended. ConfigKit 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 inherited policy, declare `mode: replace` at
`destination: [promptkit_sources]` in the higher-precedence source and supply `destination: [promptkit_sources]` in the higher-precedence source and supply
`promptkit_sources: []`. See `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. for policy lifetime and combination rules.
These application root `config` controls do not change the separate These application root `config` controls do not change the separate
Promptkit v0.12.0 framework format: its selected framework files use the PromptKit v0.23.2 framework format: its selected framework files use the
[Promptkit contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) [Promptkit contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
and its older ConfigKit controls. and their own native ConfigKit `config` controls.
`--config-overlay NAME` selects one file at `overlays/NAME.yml` below that `--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 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 operations. Scriptorium does not redefine or independently parse framework
file formats. 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. session IDs are Promptkit contracts.
- Profile fields, numeric ranges, execution defaults, overlay precedence, - Profile fields, numeric ranges, execution defaults, overlay precedence,
built-in profiles, and credential rules are Promptkit contracts. built-in profiles, and credential rules are Promptkit contracts.
@@ -203,19 +224,18 @@ file formats.
contracts. contracts.
See the 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 for all of those definitions. The files under
[`examples/prompts`](../examples/prompts/), [`examples/prompts`](../examples/prompts/),
[`examples/profiles`](../examples/profiles/), and [`examples/profiles`](../examples/profiles/), and
[`examples/schemas`](../examples/schemas/) are maintained Scriptorium [`examples/schemas`](../examples/schemas/) are maintained Scriptorium
application inputs using that tagged format. application inputs using that tagged format.
Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and PromptKit supplies a default-on OpenRouter bundle as the lowest-priority
`promptkit-openrouter-auto`. They can be selected as a prompt default or request underlay. Choose an actual bundled profile such as `auto`, or a complete
profile, and selected application sources retain precedence. Their effective model application-owned profile; old catalog IDs are not aliases. Caller definitions
settings may change with a catalog upgrade; use a complete application-owned can replace bundled records by normal composition. Bundle availability is not
profile when fixed settings are required. See the tagged format reference for a readiness check or a promise of a fixed provider model.
the maintained-profile contract.
## Credentials And Outbound Behavior ## Credentials And Outbound Behavior
@@ -246,7 +266,7 @@ client retains its own retry behavior. The tagged integration contract owns
eligibility and timing. eligibility and timing.
Promptkit's 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, defines outbound authentication, provider request mapping, transport limits,
and timeout layering. and timeout layering.
@@ -255,4 +275,4 @@ and timeout layering.
- [CLI reference](cli.md) - [CLI reference](cli.md)
- [HTTP API reference](api.md) - [HTTP API reference](api.md)
- [Operations guide](operations.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) - Application configuration: [configuration reference](../config.md)
Go applications that need an in-process prompt framework should import Go applications that need an in-process prompt framework should import
Promptkit directly. The tagged `go.maximumdirect.net/promptkit` directly. The tagged
[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) [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. owns that interface; Scriptorium does not provide a Go library package.
Consumers arriving from the former Scriptorium Go API should follow the Consumers arriving from the former Scriptorium Go API should follow the
[migration guide](migrating-to-promptkit.md). [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 and can incur another provider request. CLI exits belong to the
[CLI reference](../cli.md), HTTP status behavior belongs to the [CLI reference](../cli.md), HTTP status behavior belongs to the
[HTTP API reference](../api.md), and framework semantics belong to [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 # 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 ## Supported Migration Boundary
Scriptorium `v0.11.1` at 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 This guide covers the CLI and framework configuration cutover to
the Promptkit v0.12.0 source model. It covers the executable CLI and HTTP [PromptKit v0.23.2](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/configuration-migration.md)
application, not the former Scriptorium Go package. For exact framework and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
semantics, see the tagged [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) for the full upstream contract.
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 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 Existing application fields that already select the desired sources retain
prompt_dir: ./examples/prompts their meaning. For example, this application configuration works both before
profile_dir: ./examples/profiles and after the cutover:
```
with an ordered `promptkit_sources` sequence:
```yaml ```yaml
promptkit_sources: promptkit_sources:
- directory: ./examples/prompts - directory: ./examples/prompts
- directory: ./examples/profiles - directory: ./examples/profiles
- file: ./framework/backends.yml - file: ./examples/framework/backends.yml
schema_dir: ./examples/schemas schema_dir: ./examples/schemas
``` ```
Each item selects exactly one `file` or `directory`. Later items overlay The selected framework files must still be rewritten as described below.
earlier items; conflicts within one directory source group are errors. Paths Scriptorium uses one native application schema: discovery, imports, selected
are relative to the process working directory. An omitted or empty sequence overlays, source order, explicit overrides, and working-directory-relative
selects no application-supplied framework sources, while Promptkit's selected selector paths remain application configuration behavior. It loads framework
catalog and maintained definitions remain available. A selected application sources separately with PromptKit's schema. No second application schema or
overlay replaces the whole sequence, and repeated `--promptkit-source` flags legacy definition reader is provided. See the [configuration reference](../config.md).
replace it in command-line order rather than appending to it.
The former `--prompt-dir` and `--profile-dir` flags are removed. Replace them ## Rewrite framework definitions
with repeated source flags, for example:
```sh Replace version-keyed prompts and keyed profile/backend mappings with lists
scriptorium render \ of records containing `id`. For example, before:
--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 ```yaml
prompts: prompts:
meeting.summary: report:
"1.0.0": "1":
default_profile: fast
messages: messages:
- role: user - role: user
content: Summarize this synthetic note. content: Summarize this note.
output: output:
format: text format: text
validation_mode: none 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: profiles:
fast: fast:
extends: common endpoint: https://example.invalid/v1
timeout_seconds: 30 model: synthetic-model
``` ```
## Review presence, null, and map values After:
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 ```yaml
prompts:
- id: report
default_profile: fast
messages:
- role: user
content: Summarize this note.
output:
format: text
validation_mode: none
profiles: profiles:
explicit-zero: - id: fast
temperature: 0 endpoint: https://example.invalid/v1
leave-temperature-unset: model: synthetic-model
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 Select prompts by exact ID; `--prompt-version` is rejected. If multiple former
parent or backend; use `extra_params: null` to suppress the configured map. versions must remain independently selectable, give them distinct IDs and
If changing only a model or backend, review other inherited fields because update callers. Qualified IDs such as `support/answer` are passed unchanged.
they can remain effective. Do not infer inheritance or replacement from the Keep relative message files beside their owning definitions. Convert framework
old loader's behavior. 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 ## Replace catalog selections
configuration, including selector shape, but does not open framework sources.
Then run `scriptorium inspect configuration validate --config PATH` to build The default-on OpenRouter bundle supplies actual profiles such as `auto` and
the engine and validate all selected Promptkit definitions, including unused `gpt-sol-latest`. Former catalog and `promptkit-openrouter-*` IDs are not
ones. It does not prepare a request, resolve credentials, contact a provider, compatibility aliases. Choose an intended current bundled profile explicitly,
or load request-time schemas and artifacts. A running `serve` process captures or define a complete local profile with the endpoint, model, and settings you
its configuration and message content at startup; restart it after changing need. Do not assume a new default model. The bundle is an underlay and caller
those inputs. See the [configuration](../config.md) and records can replace it through ordinary composition.
[operations](../operations.md) contracts for path ownership and runtime
boundaries. 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 This is the contributor entry point for Scriptorium. Scriptorium is an
application that consumes the public 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 framework implementation work belongs in Promptkit. Application configuration
uses ConfigKit v1.2.0; keep Scriptorium's schema and source selection local. uses ConfigKit v1.2.1; keep Scriptorium's schema and source selection local.
Promptkit uses ConfigKit v0.5.0 to load framework sources under its own PromptKit uses the same ConfigKit release to load framework sources under its
schema and format contract. own separate schema and format contract.
## Initial Orientation ## 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 | | 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` | | 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) | | 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) | | 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.12.0 integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.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) | | Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
| Runtime operation or recovery | [Operations](operations.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) | | 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) | | 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 | | 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 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 ## Baseline Validation
The Go consumer minimum is the version declared in `go.mod`, currently 1.27.0, 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 require a Go installation. Release validation and builds use
the separately selected toolchain in the [release procedure](release.md). 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 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 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; does not include child startup or output writing. A typed operation deadline
supervisors still own process termination when they need to stop the child 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. outside that engine interval.
For deployment, filesystem permissions, and sensitive-artifact handling, see 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 External contracts are canonical in the [CLI reference](../cli.md) and
[HTTP API reference](../api.md). Promptkit's public engine contract is [HTTP API reference](../api.md). Promptkit's public engine contract is
described by its tagged 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 ## Components And Collaborators
@@ -20,11 +20,11 @@ described by its tagged
exposes application and captured framework configuration inspection, and exposes application and captured framework configuration inspection, and
owns output files, summaries, and exit codes. owns output files, summaries, and exit codes.
- `internal/config` delegates application YAML decoding, default resolution, - `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 explicitly visited application flags as overrides and renders safe structured
load diagnostics on stderr. Promptkit uses old-path ConfigKit v0.5.0 to load load diagnostics on stderr. PromptKit uses the same ConfigKit release to
framework sources under its own definition and format contract. Errors and load framework sources under its own definition and format contract. Both
warnings are written by the owning generation's native diagnostic writer. domains use ConfigKit's native diagnostic writer.
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit - `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
public values, calls its adapter-owned `Runner` interface, and maps results public values, calls its adapter-owned `Runner` interface, and maps results
and errors to HTTP DTOs. and errors to HTTP DTOs.
@@ -38,7 +38,7 @@ described by its tagged
### CLI ### CLI
`run` calls `promptkit.Engine.Run`; `render` calls `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 and profile selection, optional file inputs, variables, and presence-aware
execution overrides. Omitted framework settings remain zero values so Promptkit execution overrides. Omitted framework settings remain zero values so Promptkit
resolves its own defaults and definition-required inputs. 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 setting and retains one backend admission state. Render prepares without
generation. 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 `promptkit.Engine.InspectPrompt`, then formats Scriptorium-owned inspection
data. `inspect profile` maps an explicit profile ID to `Engine.InspectProfile` 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 Both paths construct the same full-source engine as execution before inspecting
the chosen definition; selected prompts are not filtered out. They do not 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 The command paths assemble the engine from application-selected framework
source files and directories plus the schema directory and retry setting. 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 are expanded through Promptkit's directory-input helper. Scriptorium supplies
those ordered underlays through Promptkit's public configuration API rather those ordered underlays through Promptkit's public configuration API rather
than parsing or mapping framework definitions itself. The server constructs 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 The optional HTTP retry count maps to `RunRequest.TransientRetries` without
mutating the shared engine. Negative values are rejected before invocation; mutating the shared engine. Negative values are rejected before invocation;
Promptkit controls retries and backend admission for concurrent requests. 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 Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader 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) | | `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/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/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/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/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) | | `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
Framework implementation packages are provided by 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. and are not part of this repository.

View File

@@ -5,7 +5,7 @@
This document covers Scriptorium-owned source locations and the restricted HTTP This document covers Scriptorium-owned source locations and the restricted HTTP
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
owned by the tagged 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 ## Application Source Locations
@@ -13,10 +13,12 @@ owned by the tagged
`schema_dir` from application configuration and explicit CLI overrides. It `schema_dir` from application configuration and explicit CLI overrides. It
owns selector-shape validation, not framework file parsing. During engine owns selector-shape validation, not framework file parsing. During engine
construction, `internal/adapter/cli` turns file selections into import-enabled 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 `promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
configuration underlays. The shared Promptkit engine receives the selected configuration underlays, one per selector. Directory inputs retain the
schema directory and retry setting as well. 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 Promptkit uses ConfigKit to load and compose those framework inputs according
to Promptkit's own schema and format. Scriptorium does not parse or validate 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, render-format normalization. The validator reports selector-shape, retry,
size-limit, and format errors without mutating the document or exposing size-limit, and format errors without mutating the document or exposing
rejected values. Application path values keep working-directory-relative rejected values. Application path values keep working-directory-relative
meaning. ConfigKit v1.2.0 owns strict application YAML decoding and presence meaning. ConfigKit v1.2.1 owns strict application YAML decoding and presence
semantics. Framework configuration is separately loaded by Promptkit through semantics. Framework configuration is separately loaded by PromptKit using
its older ConfigKit under Promptkit's own schema and source contract. the same ConfigKit release under PromptKit's own schema and source contract.
The `Load` boundary selects an explicit file or constructs a native ConfigKit The `Load` boundary selects an explicit file or constructs a native ConfigKit
search over the ordered implicit paths. Discovery exhaustion uses defaults; 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. locations, defaults, and credential mapping.
- [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise - [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise
source-selector and definition migration examples. 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 prompt, profile, schema, execution-setting, and framework credential
contracts. contracts.
- [HTTP API reference](api.md): route, request/response schema, status codes, - [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 Provide the process with readable selected Promptkit source files/directories
and schema sources that follow the tagged framework formats. At engine 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 including unused definitions, and captures referenced message-file contents
and static template syntax. `serve` constructs one engine at startup; it does and static template syntax. `serve` constructs one engine at startup; it does
not reload changed configuration or message content. Restart the process to 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 in the service manager. This configuration-source boundary is distinct from
the HTTP artifact root and does not constrain prompt or schema directories. the HTTP artifact root and does not constrain prompt or schema directories.
When upgrading existing definitions, review selected profile IDs. For independently maintained collections, place checkouts beneath the
`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro` were removed from the directory selected by your framework discovery file. The maintained
selected catalog. Choose an available catalog profile, one of Promptkit's [discovery example](../examples/config.discovery.yml) selects optional
maintained names, or a complete application-owned profile. New DeepSeek names `collection.yml` and `collection.yaml` entry files; each checkout owns its
are not aliases for the removed ones; see the namespace and explicit fragment imports. Update a checkout independently and
[v0.10 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md). 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: 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 attempts. Existing generation timeouts apply
per attempt, while the caller context covers the complete operation. Provider per attempt, while the caller context covers the complete operation. Provider
`Retry-After` timing can exceed Promptkit's ordinary backoff cap; consult the `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. for details.
CLI `run` can set a [whole-run deadline](cli.md) when total execution time must 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 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 covers the engine call, including capacity waiting and repairs as supported by
context cancellation; it excludes parsing, engine setup, and output writes. context cancellation; it excludes parsing, engine setup, and output writes.
HTTP callers can use [`run_timeout_seconds`](api.md) to shorten their request HTTP callers can use [`run_timeout_seconds`](api.md) to set the engine's
context for the same engine interval. The API distinguishes an expired operation budget for the same interval. The API distinguishes a typed expired
execution deadline from caller cancellation and from a provider-attempt 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: Before increasing a limit:

View File

@@ -5,9 +5,8 @@
Material: `docs/policy/oss.md`, `docs/policy/meta.md`, Material: `docs/policy/oss.md`, `docs/policy/meta.md`,
`docs/policy/agents.md`, `docs/policy/documentation.md`, `docs/policy/agents.md`, `docs/policy/documentation.md`,
`docs/policy/architecture.md`, `docs/policy/testing.md`, `docs/policy/architecture.md`, `docs/policy/testing.md`,
`docs/policy/release.md`, `AGENTS.md`, and the `docs/policy/release.md`, `AGENTS.md`, and the Policy Reading Guide section
Policy Reading Guide section of `docs/development.md`, adapted for this of `docs/development.md`, adapted for this repository.
repository.
Copyright (C) 2026 Eric Rakestraw 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) | 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) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE). [LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4). [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 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) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) | [GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/COPYRIGHT) | [COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/LICENSE). [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.1`.
Selected module: `go.maximumdirect.net/configkit` at `v1.2.0`.
Copyright (C) 2026 Eric Rakestraw 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) | License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) | [GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/COPYRIGHT) | [COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/LICENSE). [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
[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).
## jsonschema/v6 ## 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 SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) | License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE). [LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/b0fc661f4939578bc429f408c18202573dbafcc4).
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71).
## golang.org/x/text ## 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 SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) | License and notices: [BSD 3-Clause](licenses/BSD-3-Clause.txt) |
[LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE). [LICENSE](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE).
[Source](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513).
[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).
## go.yaml.in/yaml/v4 ## 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 Copyright 2006-2010 Kirill Simonov
@@ -151,7 +81,10 @@ SPDX-License-Identifier: MIT AND Apache-2.0
License and notices: [MIT](licenses/MIT.txt) | License and notices: [MIT](licenses/MIT.txt) |
[Apache 2.0](licenses/Apache-2.0.txt) | [Apache 2.0](licenses/Apache-2.0.txt) |
[LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) | [LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE). [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 ## Framework And Application Boundaries
Scriptorium consumes 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, through its supported public root package. Promptkit owns prompt execution,
preparation, prompt and profile formats, built-in profiles, model-client preparation, prompt and profile formats, built-in profiles, model-client
behavior, validation, and framework defaults. Scriptorium owns application behavior, validation, and framework defaults. Scriptorium owns application
configuration, executable CLI and HTTP adapters, prepared-run and configuration, executable CLI and HTTP adapters, prepared-run and
definition-inspection presentation, captured-configuration inspection definition-inspection presentation, captured-configuration inspection
exposure, process behavior, and HTTP deployment policy. The [format exposure, process behavior, and HTTP deployment policy. The [format
reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md) reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md)
and [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.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. 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, resolution, and validation flow. Scriptorium retains its application schema,
defaults, normalization, validation rules, source selection, and CLI override defaults, normalization, validation rules, source selection, and CLI override
mapping. Promptkit uses its own ConfigKit v0.5.0 dependency to decode and mapping. PromptKit uses the same ConfigKit generation to decode and assemble
assemble framework sources under Promptkit's schema and format contract; Scriptorium selects framework sources under its separate schema and format contract; Scriptorium
the inputs but does not parse Promptkit definitions. These ConfigKit generations selects the inputs but does not parse PromptKit definitions. ConfigKit is a
are loading mechanisms, not owners of either domain schema or HTTP artifact loading mechanism, not the owner of either domain schema or HTTP artifact
containment. The [configuration contract](../config.md) owns externally containment. The [configuration contract](../config.md) owns externally
observable application behavior, while Promptkit owns framework formats. 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 ## Stage 7: Update canonical docs and component notices
**Status: Complete.**
1. Put before/after application and framework examples in 1. Put before/after application and framework examples in
[upgrading-promptkit.md](../consumers/upgrading-promptkit.md). Explain [upgrading-promptkit.md](../consumers/upgrading-promptkit.md). Explain
that unchanged app fields still work through the one native schema, that unchanged app fields still work through the one native schema,