diff --git a/README.md b/README.md index a02acee..25f407e 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ OpenAI-compatible model endpoints, and returns generated output with validation metadata. The application uses -[Promptkit v0.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. Scriptorium owns executable configuration, CLI and HTTP mapping, process 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) - [Subprocess integration](docs/integrations/subprocess.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 Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md) +- [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/formats.md) +- [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/docs/consumers/pkg-promptkit.md) ## Examples - [Minimal configuration](examples/config.yml) and [complete configuration](examples/config.full.yml), plus 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) - [Prompt definitions](examples/prompts/), [execution profiles](examples/profiles/), [schemas](examples/schemas/), and [synthetic input fixtures](examples/fixtures/) diff --git a/docs/api.md b/docs/api.md index a79b1a4..4266f3f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -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 diff --git a/docs/cli.md b/docs/cli.md index 41c8a8f..506dffc 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -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 ` | Selected application configuration overlay. | | `--promptkit-source ` | PromptKit source file or directory; repeat to select ordered sources. | | `--schema-dir ` | Schema base-directory override. | -| `--prompt-version ` | Optional prompt-definition version selector. | | `--profile ` | Execution-profile override. | | `--session-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 ` 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. diff --git a/docs/config.md b/docs/config.md index 78ae2dd..8c905bc 100644 --- a/docs/config.md +++ b/docs/config.md @@ -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) diff --git a/docs/consumers/api.md b/docs/consumers/api.md index 5a251ae..adc7d5a 100644 --- a/docs/consumers/api.md +++ b/docs/consumers/api.md @@ -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). diff --git a/docs/consumers/migrating-to-promptkit.md b/docs/consumers/migrating-to-promptkit.md index 2bfefff..3fcaa34 100644 --- a/docs/consumers/migrating-to-promptkit.md +++ b/docs/consumers/migrating-to-promptkit.md @@ -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 diff --git a/docs/consumers/upgrading-promptkit.md b/docs/consumers/upgrading-promptkit.md index 02bd97f..25b30f5 100644 --- a/docs/consumers/upgrading-promptkit.md +++ b/docs/consumers/upgrading-promptkit.md @@ -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. diff --git a/docs/development.md b/docs/development.md index a307b5d..7f52b15 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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). diff --git a/docs/integrations/subprocess.md b/docs/integrations/subprocess.md index 530a11d..bae09be 100644 --- a/docs/integrations/subprocess.md +++ b/docs/integrations/subprocess.md @@ -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 diff --git a/docs/internal/adapters.md b/docs/internal/adapters.md index 37ed1b2..d81e490 100644 --- a/docs/internal/adapters.md +++ b/docs/internal/adapters.md @@ -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 diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 4535fc6..088d555 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -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. diff --git a/docs/internal/sources.md b/docs/internal/sources.md index 349d067..23c0eb3 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -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; diff --git a/docs/operations.md b/docs/operations.md index 409b200..01df1f2 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -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: diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index 845bb70..57958dc 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -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. diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index d3c898f..3e08247 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 5f79043..7c11b2b 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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,