Compare commits
98 Commits
856d0852e7
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 69d2ba7038 | |||
| fbe7dd56e3 | |||
| 99b0ebfc03 | |||
| bcb1a76e34 | |||
| 6ed4ac624a | |||
| c7b9c30c43 | |||
| 5f32a4f2ad | |||
| 8078c6ecc7 | |||
| 66a0954b52 | |||
| 5eeb09d1ec | |||
| f31dec61ef | |||
| 293374d7a7 | |||
| b3a0a73416 | |||
| 3f5e441756 | |||
| 23108bd2f0 | |||
| d97e2b8e30 | |||
| 3105f4d62f | |||
| 6562d63a02 | |||
| dd1915735f | |||
| a2f3588639 | |||
| 3f481ea432 | |||
| ac858be2a2 | |||
| cf50650e55 | |||
| 7afe6ba333 | |||
| 16197ae9dd | |||
| c5e54edaa5 | |||
| 78bcf86619 | |||
| 5d372dd37d | |||
| 9bd1629a9e | |||
| 50c65adac4 | |||
| a2205db152 | |||
| 27db6b6f47 | |||
| f858d57322 | |||
| de7c866662 | |||
| 77f168c660 | |||
| e7a8b0db04 | |||
| ae5344a77d | |||
| 247b67312e | |||
| ca7c7faf5c | |||
| a0134ea49a | |||
| 95a94249f1 | |||
| 87d7240f31 | |||
| 1b1d967fc7 | |||
| 932fd6da25 | |||
| 65bd2da51a | |||
| eec4fa2d91 | |||
| 2c3d8e4c8b | |||
| 79dfe0a3ef | |||
| 03b479b4d7 | |||
| 5c780a4cc0 | |||
| d79e23739f | |||
| 49461b18e4 | |||
| 222f4056e6 | |||
| a5d8394313 | |||
| ba24b7a879 | |||
| 723fee9c46 | |||
| 0cd95f6e8e | |||
| c233d03371 | |||
| 907fc51236 | |||
| cd0811a49e | |||
| 1c8494ec20 | |||
| 58cb02f973 | |||
| beaaea2f1a | |||
| b913ef0d07 | |||
| 411a67b241 | |||
| 2ba2ce1b91 | |||
| c2e2b74f83 | |||
| 9ea9d0706d | |||
| 5c302f18ac | |||
| 54c8e9011e | |||
| 2027b80311 | |||
| 0df2aad3a8 | |||
| 0d5ecfa842 | |||
| c8e2b972f3 | |||
| b1bb55a9a0 | |||
| 82b0f231b6 | |||
| 15e7c1aed9 | |||
| bb5006517b | |||
| bcf2ddf246 | |||
| ddcba9c639 | |||
| 70f7e96d02 | |||
| ea964707f7 | |||
| bbb473a3d9 | |||
| e1ce526114 | |||
| 8b6c12f912 | |||
| 9849c6bda2 | |||
| 777b727602 | |||
| 81e1ef59e6 | |||
| df762c3735 | |||
| 417522f08c | |||
| b3bb36fc86 | |||
| ba0d99f107 | |||
| 538bc27472 | |||
| 1bad076d48 | |||
| 8452b54809 | |||
| d6aecf5c50 | |||
| 83856b4de8 | |||
| 39d3508705 |
@@ -3,11 +3,13 @@ when:
|
|||||||
|
|
||||||
steps:
|
steps:
|
||||||
- name: build-release-assets
|
- name: build-release-assets
|
||||||
image: golang:1.25
|
image: golang:1.27.4
|
||||||
commands:
|
commands:
|
||||||
- |
|
- |
|
||||||
set -eu
|
set -eu
|
||||||
|
|
||||||
|
export GOTOOLCHAIN=local
|
||||||
|
|
||||||
version="$CI_COMMIT_TAG"
|
version="$CI_COMMIT_TAG"
|
||||||
dist="dist"
|
dist="dist"
|
||||||
pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"
|
pkg="gitea.maximumdirect.net/eric/scriptorium/cmd/scriptorium"
|
||||||
|
|||||||
@@ -1,4 +1,6 @@
|
|||||||
Please review `docs/development.md` for initial orientation in this repository and follow its task-specific reading guide.
|
Start with `docs/development.md` for orientation and use its policy reading guide
|
||||||
|
to select the policies applicable to the task. Do not read the entire suite by
|
||||||
|
default.
|
||||||
|
|
||||||
Review and follow `docs/policy/agents.md` before recommending, planning, or
|
Read and follow `docs/policy/agents.md` before recommending, planning, or
|
||||||
implementing changes to this repository.
|
implementing repository changes.
|
||||||
|
|||||||
@@ -5,7 +5,7 @@ Copyright (C) 2026 Eric Rakestraw
|
|||||||
SPDX-License-Identifier: GPL-3.0-or-later
|
SPDX-License-Identifier: GPL-3.0-or-later
|
||||||
|
|
||||||
Scriptorium is free software: you can redistribute it and/or modify it
|
Scriptorium is free software: you can redistribute it and/or modify it
|
||||||
under the terms of the GNU Lesser General Public License as published by
|
under the terms of the GNU General Public License as published by
|
||||||
the Free Software Foundation, either version 3 of the License, or
|
the Free Software Foundation, either version 3 of the License, or
|
||||||
(at your option) any later version.
|
(at your option) any later version.
|
||||||
|
|
||||||
@@ -14,6 +14,10 @@ The GNU General Public License version 3 is provided in LICENSE.
|
|||||||
Scriptorium is distributed in the hope that it will be useful,
|
Scriptorium is distributed in the hope that it will be useful,
|
||||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||||
GNU Lesser General Public License for more details.
|
GNU General Public License for more details.
|
||||||
|
|
||||||
Third-party code and assets are subject to their respective license terms.
|
Third-party code and assets are subject to their respective license terms.
|
||||||
|
|
||||||
|
Policy documents adapted from Standard Repository Policies remain licensed
|
||||||
|
under CC-BY-SA-4.0. See docs/oss/attribution.md for the affected material,
|
||||||
|
upstream credit, and license links.
|
||||||
|
|||||||
15
README.md
15
README.md
@@ -6,7 +6,7 @@ OpenAI-compatible model endpoints, and returns generated output with validation
|
|||||||
metadata.
|
metadata.
|
||||||
|
|
||||||
The application uses
|
The application uses
|
||||||
[Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/)
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/)
|
||||||
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.
|
||||||
@@ -33,25 +33,30 @@ a model. For complete invocation and output behavior, see the
|
|||||||
- [CLI reference](docs/cli.md)
|
- [CLI reference](docs/cli.md)
|
||||||
- [Configuration reference](docs/config.md)
|
- [Configuration reference](docs/config.md)
|
||||||
- [Application configuration inspection](docs/cli.md#application-configuration-inspection)
|
- [Application configuration inspection](docs/cli.md#application-configuration-inspection)
|
||||||
|
- [Framework configuration inspection](docs/cli.md#framework-configuration-inspection)
|
||||||
- [HTTP API reference](docs/api.md)
|
- [HTTP API reference](docs/api.md)
|
||||||
- [Operations guide](docs/operations.md)
|
- [Operations guide](docs/operations.md)
|
||||||
- [Consumer integration overview](docs/consumers/api.md)
|
- [Consumer integration overview](docs/consumers/api.md)
|
||||||
- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md)
|
- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md)
|
||||||
|
- [Upgrade Promptkit source selectors and definitions](docs/consumers/upgrading-promptkit.md)
|
||||||
- [Subprocess integration](docs/integrations/subprocess.md)
|
- [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.11.0/docs/formats.md)
|
- [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md)
|
- [Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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)
|
[composed import/overlay example](examples/config.composed.yml), 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/),
|
- [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/)
|
||||||
- [Render script](examples/render-markdown-summary.sh)
|
- [Render script](examples/render-markdown-summary.sh)
|
||||||
- [HTTP request](examples/http-run.json)
|
- [HTTP request](examples/http-run.json)
|
||||||
|
|
||||||
Scriptorium is licensed under the [BSD 3-Clause License](LICENSE).
|
Scriptorium is licensed under the [GPL v3.0 or later](COPYRIGHT).
|
||||||
|
|
||||||
[Open Source attribution notices](docs/oss/attribution.md) are available.
|
[Open Source attribution notices](docs/oss/attribution.md) are available.
|
||||||
|
|||||||
71
docs/adr/0005-configkit-boundary.md
Normal file
71
docs/adr/0005-configkit-boundary.md
Normal file
@@ -0,0 +1,71 @@
|
|||||||
|
# ADR 0005: Adopt ConfigKit's Configuration Boundary
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted.
|
||||||
|
|
||||||
|
## Date
|
||||||
|
|
||||||
|
2026-10-04.
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Scriptorium uses ConfigKit to resolve application configuration. Adopting its
|
||||||
|
standard semantics across the application suite gives operators a consistent
|
||||||
|
configuration model and keeps configuration processing under a single owner.
|
||||||
|
|
||||||
|
The application supplies its schema and domain rules through ConfigKit's public
|
||||||
|
definition API. ConfigKit returns the resolved configuration and inspection
|
||||||
|
information for use by Scriptorium.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
ConfigKit owns configuration loading and resolution semantics, including
|
||||||
|
decoding, imports, composition, precedence, overlays, inheritance, and
|
||||||
|
inspection. Scriptorium adopts those semantics through ConfigKit's supported
|
||||||
|
public APIs.
|
||||||
|
|
||||||
|
Scriptorium owns its application schema, defaults, value normalization, and
|
||||||
|
domain validation. It supplies these rules through ConfigKit's definition
|
||||||
|
callbacks so they participate in the library's resolution and validation flow.
|
||||||
|
Scriptorium consumes the final, fully resolved configuration returned by that
|
||||||
|
flow.
|
||||||
|
|
||||||
|
Scriptorium also owns application-facing choices: default discovery locations,
|
||||||
|
source and option selection, and the mapping of CLI inputs to ConfigKit options
|
||||||
|
and overrides. ConfigKit determines how the selected inputs are processed.
|
||||||
|
|
||||||
|
Scriptorium may expose ConfigKit's inspection APIs through operator interfaces
|
||||||
|
when demand warrants them. ConfigKit owns the underlying inspection semantics;
|
||||||
|
Scriptorium owns their application-facing presentation.
|
||||||
|
|
||||||
|
Resolution establishes configuration values. Runtime credentials, artifacts,
|
||||||
|
and downstream resources retain their respective preparation and execution
|
||||||
|
lifecycle. Promptkit owns its framework schema and domain rules when using
|
||||||
|
ConfigKit, consistent with [ADR 0004](0004-definition-boundary.md).
|
||||||
|
|
||||||
|
## Alternatives Considered
|
||||||
|
|
||||||
|
### Application-Owned Configuration Processing
|
||||||
|
|
||||||
|
Scriptorium could implement loading and composition locally. This offers
|
||||||
|
application-specific flexibility, but duplicates ConfigKit's responsibilities
|
||||||
|
and creates recurring maintenance and semantic drift across applications.
|
||||||
|
|
||||||
|
### ConfigKit-Owned Application Choices
|
||||||
|
|
||||||
|
Scriptorium could delegate discovery conventions and domain defaults to the
|
||||||
|
library. This reduces local decisions, but places application-specific behavior
|
||||||
|
in a shared configuration mechanism. The selected boundary keeps those choices
|
||||||
|
with the application while using the library's processing semantics.
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
Configuration changes follow the ownership boundary: processing capabilities
|
||||||
|
belong in ConfigKit, and application rules use its supported extension points.
|
||||||
|
ConfigKit upgrades are evaluated for their effects on Scriptorium's selected
|
||||||
|
inputs, domain callbacks, and operator interfaces.
|
||||||
|
|
||||||
|
The [architecture policy](../policy/architecture.md) owns current architectural
|
||||||
|
constraints, and the [configuration contract](../config.md) owns observable
|
||||||
|
application behavior. This ADR records the rationale for the ownership boundary.
|
||||||
53
docs/adr/0006-adopt-commandkit-native-operator-interfaces.md
Normal file
53
docs/adr/0006-adopt-commandkit-native-operator-interfaces.md
Normal file
@@ -0,0 +1,53 @@
|
|||||||
|
# ADR 0006: Adopt CommandKit's Native Operator Interfaces
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Accepted. Complements [ADR 0004](0004-definition-boundary.md) and
|
||||||
|
[ADR 0005](0005-configkit-boundary.md). Both remain accepted and are not
|
||||||
|
superseded.
|
||||||
|
|
||||||
|
## Date
|
||||||
|
|
||||||
|
2026-11-19.
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Scriptorium is adopting CommandKit's native operator interfaces within the
|
||||||
|
PromptKit and ConfigKit boundaries established by ADRs 0004 and 0005.
|
||||||
|
|
||||||
|
## Decision
|
||||||
|
|
||||||
|
Scriptorium adopts CommandKit's native operator interfaces.
|
||||||
|
|
||||||
|
ConfigKit owns configuration policy and everything in the configuration
|
||||||
|
lifecycle before the final, fully resolved configuration handoff. Application
|
||||||
|
schema and domain callbacks operate through ConfigKit's supported extension
|
||||||
|
points within that lifecycle.
|
||||||
|
|
||||||
|
PromptKit owns prompt definitions, preparation, execution, validation, and
|
||||||
|
inspection semantics. Its configuration is resolved through ConfigKit, with
|
||||||
|
PromptKit supplying its domain schema and rules through ConfigKit's supported
|
||||||
|
extension points.
|
||||||
|
|
||||||
|
Scriptorium owns the domain. After the handoff, it interprets the resolved
|
||||||
|
configuration values and uses them to perform useful work that satisfies the
|
||||||
|
user's request. It does not revise what constitutes effective configuration.
|
||||||
|
It supplies requests through PromptKit's supported APIs and uses the returned
|
||||||
|
results without redefining their meaning.
|
||||||
|
|
||||||
|
CommandKit's `ckconfig` and `ckprompt` integrations expose upstream ConfigKit
|
||||||
|
and PromptKit features. Scriptorium neutrally makes those features available
|
||||||
|
through the native interfaces, preserving upstream semantics.
|
||||||
|
|
||||||
|
## Alternatives Considered
|
||||||
|
|
||||||
|
Retaining custom configuration and prompt inspection would duplicate upstream
|
||||||
|
behavior and create another owner for its semantics. Use the native integrations
|
||||||
|
instead.
|
||||||
|
|
||||||
|
## Consequences
|
||||||
|
|
||||||
|
Standard inspection exposes the upstream result without constructing a different
|
||||||
|
effective document, reconciling separate explanation trees, or reinterpreting
|
||||||
|
upstream paths. The [adoption roadmap](../roadmap/commandkit-adoption.md) tracks
|
||||||
|
implementation.
|
||||||
38
docs/api.md
38
docs/api.md
@@ -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 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md).
|
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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 outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
the [PromptKit v0.23.3 outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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,10 +213,11 @@ 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.
|
||||||
|
|
||||||
|
|||||||
175
docs/cli.md
175
docs/cli.md
@@ -24,20 +24,24 @@ 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 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.
|
||||||
- `scriptorium config sources`: show the ordered configuration sources.
|
- `scriptorium config sources`: show the ordered configuration sources.
|
||||||
- `scriptorium config explain`: explain one effective or historical configuration path.
|
- `scriptorium config explain`: explain one effective or historical configuration path.
|
||||||
|
|
||||||
All commands accept `--config <path>` and `--config-overlay <name>` and reject
|
All command families accept `--config <path>` and `--config-overlay <name>`;
|
||||||
positional arguments. `--config-overlay` selects one application configuration
|
positional arguments are rejected. `--config-overlay` selects one application
|
||||||
overlay; it is separate from `--profile`, which selects a Promptkit execution
|
configuration overlay; it is separate from `--profile`, which selects a
|
||||||
profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
|
Promptkit execution profile. See [configuration composition](config.md#explicit-imports-and-selected-overlays)
|
||||||
for name, root, and no-base behavior. `run`,
|
for name, root, and absent-main behavior. `run`, `render`, `serve`, `inspect prompt`,
|
||||||
`render`, `serve`, and `inspect prompt` require an effective `prompt_dir`;
|
`inspect profile`, and `inspect configuration` accept repeated
|
||||||
`inspect profile` does not. Supply the directory through the configuration
|
`--promptkit-source <path>` flags and `--schema-dir <dir>` where applicable.
|
||||||
contract or a supported `--prompt-dir` flag. Explicit application flags,
|
They replace the configured source sequence in flag order. `--prompt-dir` and
|
||||||
|
`--profile-dir` are no longer supported; use `promptkit_sources` in application
|
||||||
|
configuration or the repeated source flags. Application `config` commands
|
||||||
|
remain independent of framework source loading. Explicit application flags,
|
||||||
including empty values, override file settings. Configuration load diagnostics
|
including empty values, override file settings. Configuration load diagnostics
|
||||||
go to stderr and exit with status 1; successful load warnings are printed once
|
go to stderr and exit with status 1; successful load warnings are printed once
|
||||||
before command work.
|
before command work.
|
||||||
@@ -60,10 +64,8 @@ Optional flags:
|
|||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `--config <path>` | Application configuration file. |
|
| `--config <path>` | Application configuration file. |
|
||||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||||
| `--prompt-dir <dir>` | Prompt-definition directory override. |
|
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||||
| `--profile-dir <dir>` | Custom profile-directory override. |
|
|
||||||
| `--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. |
|
||||||
@@ -90,16 +92,15 @@ 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.11.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
[Promptkit outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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.
|
||||||
work.
|
|
||||||
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
|
||||||
@@ -107,10 +108,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
|
||||||
@@ -157,7 +158,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`, `--prompt-dir`, `--profile-dir`, `--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
|
||||||
@@ -172,6 +173,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
|
||||||
@@ -185,8 +197,7 @@ Optional flags:
|
|||||||
| `--config <path>` | Application configuration file. |
|
| `--config <path>` | Application configuration file. |
|
||||||
| `--config-overlay <name>` | Selected application configuration overlay. |
|
| `--config-overlay <name>` | Selected application configuration overlay. |
|
||||||
| `--addr <listen-address>` | HTTP listen-address override. |
|
| `--addr <listen-address>` | HTTP listen-address override. |
|
||||||
| `--prompt-dir <dir>` | Prompt-definition directory override. |
|
| `--promptkit-source <path>` | PromptKit source file or directory; repeat to select ordered sources. |
|
||||||
| `--profile-dir <dir>` | Custom profile-directory override. |
|
|
||||||
| `--schema-dir <dir>` | Schema base-directory override. |
|
| `--schema-dir <dir>` | Schema base-directory override. |
|
||||||
| `--artifact-root <dir>` | Root for HTTP `file` input references. |
|
| `--artifact-root <dir>` | Root for HTTP `file` input references. |
|
||||||
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
| `--max-request-bytes <n>` | Maximum encoded HTTP request-body bytes; `0` disables the limit. |
|
||||||
@@ -199,27 +210,42 @@ 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] [--prompt-dir DIR] [--format text|json] [--out PATH]
|
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||||
```
|
```
|
||||||
|
|
||||||
`--prompt` is required. Inspection uses normal configuration discovery and a
|
`--prompt` is required. Inspection uses normal configuration discovery and the
|
||||||
`--prompt-dir` override, defaults to text regardless of `defaults.render_format`,
|
selected Promptkit sources, defaults to text regardless of
|
||||||
and writes to stdout unless `--out` is supplied. It loads and normalizes the
|
`defaults.render_format`, and writes to stdout unless `--out` is supplied.
|
||||||
selected definition but does not resolve a profile, load a schema, render a
|
|
||||||
template, reserve backend capacity, or call a model.
|
Both definition-inspection commands first construct the same engine used for
|
||||||
|
execution from the complete selected source sequence. Construction resolves
|
||||||
|
and validates all effective definitions, including unused ones, and captures
|
||||||
|
referenced message-file contents and static template syntax. Invalid unused
|
||||||
|
definitions or unreadable message resources can therefore prevent inspection.
|
||||||
|
No prompt collection is mandatory, but selected prompts are not ignored.
|
||||||
|
|
||||||
|
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`
|
## `scriptorium inspect profile`
|
||||||
|
|
||||||
```text
|
```text
|
||||||
scriptorium inspect profile --profile ID
|
scriptorium inspect profile --profile ID
|
||||||
[--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out PATH]
|
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||||
```
|
```
|
||||||
|
|
||||||
`--profile` is required; built-in profiles need no prompt directory. Inspection
|
`--profile` is required. After the [full-source engine construction described
|
||||||
resolves profile inheritance and backend defaults, but never reads a credential
|
above](#scriptorium-inspect-prompt), inspection selects one resolved profile
|
||||||
value, loads a prompt, reserves capacity, or calls a model. Unset provider
|
with inheritance. `profile_model_params` contains only fields present on that
|
||||||
controls are 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
|
||||||
|
|
||||||
@@ -230,19 +256,20 @@ scriptorium config sources [flags]
|
|||||||
scriptorium config explain --path JSON_POINTER [flags]
|
scriptorium config explain --path JSON_POINTER [flags]
|
||||||
```
|
```
|
||||||
|
|
||||||
Each accepts `--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`,
|
Each accepts `--config`, `--config-overlay`, `--schema-dir`, `--addr`,
|
||||||
`--schema-dir`, `--addr`, `--artifact-root`, `--max-request-bytes`,
|
`--artifact-root`, `--max-request-bytes`,
|
||||||
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
|
`--max-artifact-bytes`, and `--max-response-bytes`. These are application
|
||||||
configuration selectors and overrides; request, credential, backend-editing,
|
configuration selectors and overrides; request, credential, backend-editing,
|
||||||
output-format, and output-file flags are not accepted. Positional arguments
|
output-format, and output-file flags are not accepted. Positional arguments
|
||||||
are rejected.
|
are rejected.
|
||||||
|
|
||||||
`validate` writes no success output; status 0 means the application configuration
|
`validate` writes no success output; status 0 means the application configuration
|
||||||
loaded and passed its own validation. It does not establish that a prompt
|
loaded and passed its own validation. It does not establish that selected
|
||||||
directory exists, credentials are present, or Promptkit can construct an
|
Promptkit sources can construct an engine, credentials are present, or a
|
||||||
engine. `show` writes ConfigKit's resolved, redacted YAML snapshot. `sources`
|
provider is available. `show` writes ConfigKit's resolved YAML snapshot. `sources`
|
||||||
writes one newline-terminated JSON array of source records in load order. Each
|
writes one newline-terminated JSON array of source records in load order. Each
|
||||||
record has `id`, `label`, and `layer`, plus `path` when available; explicit CLI
|
record has `id`, `label`, and `layer`, plus `path` when available. Application
|
||||||
|
main-file and import records use the `main` layer; explicit CLI
|
||||||
overrides appear as synthetic sources. Defaults-only input without overrides
|
overrides appear as synthetic sources. Defaults-only input without overrides
|
||||||
produces `[]` for `sources`.
|
produces `[]` for `sources`.
|
||||||
|
|
||||||
@@ -251,18 +278,64 @@ The empty string selects the root; `/server/addr` selects a field; `~1` and
|
|||||||
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
|
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
|
||||||
according to the containing mapping or sequence. Dotted paths, file paths,
|
according to the containing mapping or sequence. Dotted paths, file paths,
|
||||||
and URL fragments are not accepted. ConfigKit writes a human-readable account
|
and URL fragments are not accepted. ConfigKit writes a human-readable account
|
||||||
of the effective value and its chronological default, base, overlay, CLI,
|
of the effective value and its chronological default, file/import, overlay,
|
||||||
and normalization history, including removed historical values. This is not a
|
CLI, normalization, and removed-value history. This is not a JSON schema or a
|
||||||
JSON schema or a byte-for-byte stable prose format. Unknown and malformed paths
|
byte-for-byte stable prose format. Unknown and malformed paths exit 1 without
|
||||||
exit 1 without successful explanation output.
|
successful explanation output.
|
||||||
|
|
||||||
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
|
Diagnostics and warnings go to stderr, never into successful stdout. Parse,
|
||||||
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
|
load, output, and diagnostic-write failures exit 1. Ordinary output writes may
|
||||||
leave partial data on failure. The inspection output can contain paths,
|
leave partial data on failure. Application inspection can contain paths and
|
||||||
identifiers, `api_key_env` reference names, and ordinary `extra_params` values,
|
configured values; protect its output accordingly. Raw API-key values are not
|
||||||
including displaced historical values in explanations;
|
accepted by the application configuration schema.
|
||||||
protect it accordingly. Raw API-key values are not read or emitted by these
|
|
||||||
commands.
|
## Framework configuration inspection
|
||||||
|
|
||||||
|
```text
|
||||||
|
scriptorium inspect configuration validate [flags]
|
||||||
|
scriptorium inspect configuration show [flags]
|
||||||
|
scriptorium inspect configuration sources [flags]
|
||||||
|
scriptorium inspect configuration explain --path JSON_POINTER [flags]
|
||||||
|
```
|
||||||
|
|
||||||
|
Each operation accepts `--config`, `--config-overlay`, repeatable
|
||||||
|
`--promptkit-source`, and `--schema-dir`. These flags select the application
|
||||||
|
settings and framework sources; positional arguments, `--format`, and `--out`
|
||||||
|
are not accepted. Unlike `config validate`, framework `validate` constructs
|
||||||
|
the Promptkit engine and validates all effective definitions, including
|
||||||
|
unused ones. It writes nothing on success and does not prepare a request,
|
||||||
|
resolve a credential, or contact a provider.
|
||||||
|
|
||||||
|
`show` writes Promptkit's native effective YAML, an inspection snapshot rather
|
||||||
|
than a promised reloadable file. `sources` writes a
|
||||||
|
newline-terminated JSON array in captured source order. Each source record has
|
||||||
|
`id`, `label`, `layer`, `kind`, and `underlay_index`, plus `path` when available
|
||||||
|
and `imported_from` for imported sources. That nested object has `source_id`,
|
||||||
|
`line`, and `column`. Values and output structure are a projection of the
|
||||||
|
captured Promptkit view, not Scriptorium's application-source records.
|
||||||
|
|
||||||
|
`explain` requires an explicitly supplied `--path` in ConfigKit JSON Pointer
|
||||||
|
syntax; `--path ''` selects the root. For example,
|
||||||
|
`/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.
|
||||||
|
|
||||||
|
Framework `show` and `explain` use Promptkit's native redaction for its
|
||||||
|
classified credential-shaped provider fields, including historical values.
|
||||||
|
Environment-variable reference names and ordinary provider parameters remain
|
||||||
|
visible. Arbitrary prompt or provider content is not classified as secret by
|
||||||
|
name inspection, so treat these reports as sensitive. This redaction policy is
|
||||||
|
limited to framework configuration reports; it does not add redaction to
|
||||||
|
`inspect profile` or prepared-run output. Credentials are not resolved by any
|
||||||
|
of these inspection operations. Promptkit owns detailed field and source
|
||||||
|
semantics; see its tagged [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||||
|
|
||||||
|
Warnings and errors go to stderr. Successful `validate` writes nothing to
|
||||||
|
stdout; successful `show`, `sources`, and `explain` write their reports there.
|
||||||
|
Parse, load, path, and output failures exit 1. A native writer error may leave
|
||||||
|
partial output.
|
||||||
|
|
||||||
## Input And Variable Syntax
|
## Input And Variable Syntax
|
||||||
|
|
||||||
|
|||||||
267
docs/config.md
267
docs/config.md
@@ -1,68 +1,161 @@
|
|||||||
# Configuration Reference
|
# Configuration Reference
|
||||||
|
|
||||||
This is the canonical reference for Scriptorium application settings. Prompt,
|
This is the canonical reference for Scriptorium application settings. Prompt,
|
||||||
profile, schema, execution-setting, built-in profile, and framework credential
|
profile, backend, schema, execution-setting, built-in profile, and framework
|
||||||
semantics are defined by the
|
credential semantics are defined by the
|
||||||
[Promptkit v0.11.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md).
|
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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).
|
outcomes, see the [HTTP API reference](api.md). For migration examples, see
|
||||||
|
[Upgrading Promptkit sources and definitions](consumers/upgrading-promptkit.md).
|
||||||
|
|
||||||
## Discovery And Precedence
|
## Discovery And Precedence
|
||||||
|
|
||||||
Application settings are resolved in this order:
|
ConfigKit assembles the selected main source, imports, and overlay, resolves
|
||||||
|
inheritance, and decodes the result with Scriptorium's typed defaults. It then
|
||||||
1. built-in Scriptorium defaults;
|
applies explicitly supplied application CLI values, records application
|
||||||
2. a configuration file; then
|
normalization, and validates the result. Source, composition, inheritance, and
|
||||||
3. CLI overrides.
|
decoding failures happen before CLI assignment and cannot be repaired by it;
|
||||||
|
an override can correct a decoded value before application validation.
|
||||||
|
|
||||||
When `--config` is omitted, Scriptorium searches
|
When `--config` is omitted, Scriptorium searches
|
||||||
`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`.
|
`/usr/local/etc/scriptorium/config.yml` and then `/etc/scriptorium/config.yml`.
|
||||||
If neither exists, it uses built-in defaults. An explicit `--config` path must
|
ConfigKit performs this ordered search for each load. If neither exists, it
|
||||||
exist and decode successfully.
|
uses built-in defaults; an error in a selected candidate does not cause a
|
||||||
|
fallback. An explicit `--config` path must exist and decode successfully,
|
||||||
|
including when an empty path is explicitly supplied.
|
||||||
|
|
||||||
The maintained [minimal configuration](../examples/config.yml),
|
The maintained [minimal configuration](../examples/config.yml),
|
||||||
[complete configuration](../examples/config.full.yml), and
|
[complete configuration](../examples/config.full.yml),
|
||||||
[composed configuration](../examples/config.composed.yml) are copyable examples.
|
[composed configuration](../examples/config.composed.yml),
|
||||||
|
[collection configuration](../examples/config.collections.yml), and
|
||||||
|
[framework inheritance configuration](../examples/config.inheritance.yml) are
|
||||||
|
copyable examples.
|
||||||
|
|
||||||
## Application Configuration File
|
## Application Configuration File
|
||||||
|
|
||||||
Configuration is decoded by ConfigKit v0.4.0 as strict YAML. Unknown fields,
|
Application configuration is decoded by ConfigKit v1.2.1 as strict YAML.
|
||||||
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
|
Unknown fields, empty files, multiple YAML documents, and YAML aliases/anchors
|
||||||
An explicit empty string is a value: it clears a file-provided optional path
|
are rejected.
|
||||||
or, for required `prompt_dir`, fails the command's prerequisite. A scalar
|
An explicit empty string is a value and may clear a file-provided optional
|
||||||
`null` is not an empty string and is rejected for scalar fields; nullable
|
string. A scalar `null` is not an empty string and is rejected for non-nullable
|
||||||
fields such as `transient_retries` retain their documented meaning. Raw
|
fields; nullable fields such as `transient_retries` retain their documented
|
||||||
API-key fields are not accepted.
|
meaning. Raw API-key fields and unknown application fields are rejected.
|
||||||
|
|
||||||
ConfigKit applies defaults, the selected file, then only explicitly supplied
|
Only explicitly supplied application CLI flags override decoded settings. Paths
|
||||||
application CLI flags before validating the result. Paths in the application
|
in the application document remain relative to the process working directory, not to the file's
|
||||||
document remain relative to the process working directory, not to the file's
|
|
||||||
directory. Load diagnostics are printed safely on stderr; invalid application
|
directory. Load diagnostics are printed safely on stderr; invalid application
|
||||||
configuration exits with status 1.
|
configuration exits with status 1.
|
||||||
|
|
||||||
|
### Promptkit source selectors
|
||||||
|
|
||||||
|
`promptkit_sources` is an ordered sequence of explicit Promptkit source
|
||||||
|
selectors. Each item must set exactly one of `file` or `directory`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
promptkit_sources:
|
||||||
|
- directory: ./examples/prompts
|
||||||
|
- directory: ./examples/profiles
|
||||||
|
- file: ./examples/framework/backends.yml
|
||||||
|
schema_dir: ./examples/schemas
|
||||||
|
```
|
||||||
|
|
||||||
|
An empty or null final resolved `promptkit_sources` list selects no
|
||||||
|
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.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||||
|
|
||||||
|
Selector paths are relative to the process working directory, not to the
|
||||||
|
application configuration file. Application validation checks the selector
|
||||||
|
shape but does not open or validate Promptkit sources. `config validate`
|
||||||
|
therefore does not prove that selected sources can build an engine; use
|
||||||
|
`inspect configuration validate` for that separate check. Repeated
|
||||||
|
`--promptkit-source` flags replace the entire configured selector sequence
|
||||||
|
and preserve flag order. 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/).
|
||||||
|
|
||||||
|
Entries imported by one discovery file are composed together as peers.
|
||||||
|
Conflicting definitions of the same qualified resource ID fail to load;
|
||||||
|
filename, checkout, and glob order do not set precedence. To override a
|
||||||
|
discovered record, select a separate framework file later in
|
||||||
|
`promptkit_sources` and supply the complete replacement record.
|
||||||
|
|
||||||
### Explicit imports and selected overlays
|
### Explicit imports and selected overlays
|
||||||
|
|
||||||
A file-backed configuration may declare `configkit.imports` with relative
|
Application files declare imports under root `config.imports`. Native `path`,
|
||||||
`path` or `glob` entries. Each entry is explicit; Scriptorium does not scan
|
`dir`, and `glob` selectors, filters, recursion, destinations, and item
|
||||||
for fragments on its own. ConfigKit composes the selected file and imports by
|
placement are available as described in the [pinned ConfigKit contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/config.md).
|
||||||
conflict, so two fragments cannot define the same field merely to establish
|
Imports are optional by default; set `required: true` when absence must fail.
|
||||||
precedence. A required missing import fails; an entry may use
|
The old `optional` field is not supported. Directory selection has no default
|
||||||
`optional: true` to suppress target nonexistence. Imports are resolved from
|
filename filter; author a pattern when only YAML files are intended. ConfigKit
|
||||||
the declaring file's canonical directory and remain within the selected
|
composes peer sources strictly, rather than using filename order to resolve
|
||||||
file's canonical directory by default. Scriptorium does not widen that root.
|
conflicts. Imports are resolved relative to their declaring file within the
|
||||||
|
native source root. Scriptorium does not widen that root.
|
||||||
|
|
||||||
|
Root `config.sequences` can declare an identity key and merge mode for a
|
||||||
|
collection. Scriptorium does not register or infer an identity for
|
||||||
|
`promptkit_sources`: absent an authored policy, unkeyed lists replace across
|
||||||
|
precedence boundaries. The [collection example](../examples/config.collections.yml)
|
||||||
|
declares `file` identity with `upsert`, combines imported file selectors, and
|
||||||
|
lets an overlay add another. CLI list overrides still replace the whole list.
|
||||||
|
|
||||||
|
At application precedence boundaries, omission preserves lower-precedence
|
||||||
|
selectors. Under ordinary list replacement, `[]` clears the selection and
|
||||||
|
`null` resolves to no selectors. Under authored `append` or `upsert`, `[]`
|
||||||
|
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/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.23.3 framework format: its selected framework files use the
|
||||||
|
[Promptkit contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
|
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
|
||||||
and exact lowercase `default` select no overlay. There is no fallback,
|
and exact lowercase `default` select no overlay. There is no fallback,
|
||||||
case folding, inherited stack, or automatic selection; a missing selected
|
case folding, inherited stack, or automatic selection; a missing selected
|
||||||
overlay fails. ConfigKit merges mapping fields and replaces other values,
|
overlay fails. Mappings merge; sequence contributions and nulls at collection
|
||||||
including sequences and explicit nulls, before applying explicit CLI flags.
|
destinations follow the effective collection policy described above. Other
|
||||||
An active overlay needs a selected base file. No-source defaults-only loads
|
explicit nulls replace lower values subject to the application schema.
|
||||||
cannot use imports or an active overlay.
|
Defaults-only loading can enable imports, but an absent main has no import
|
||||||
|
declarations. This CLI supplies no independent overlay root, so an active
|
||||||
|
overlay cannot be located without a selected main context. That is not a general
|
||||||
|
ConfigKit restriction.
|
||||||
|
|
||||||
The [composed example](../examples/config.composed.yml) imports two fragments
|
The [composed example](../examples/config.composed.yml) imports the application
|
||||||
and has a selectable [local overlay](../examples/overlays/local.yml). From the
|
[source-selection fragment](../examples/config-fragments/sources.yml) and has
|
||||||
repository root:
|
a selectable [local overlay](../examples/overlays/local.yml). That fragment
|
||||||
|
selects the [framework backend file](../examples/framework/backends.yml) through
|
||||||
|
`promptkit_sources`; backend definitions are not imported into the application
|
||||||
|
document. From the repository root:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
go run ./cmd/scriptorium render \
|
go run ./cmd/scriptorium render \
|
||||||
@@ -72,15 +165,25 @@ go run ./cmd/scriptorium render \
|
|||||||
--input glossary=./examples/fixtures/glossary.yml
|
--input glossary=./examples/fixtures/glossary.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
Import and overlay file locations are constrained by ConfigKit;
|
Inspect the collection overlay and render without contacting a provider:
|
||||||
*application path values* such as `prompt_dir` remain relative
|
|
||||||
to the process working directory even when authored in a fragment or overlay.
|
```bash
|
||||||
These source constraints are separate from HTTP artifact containment.
|
go run ./cmd/scriptorium config show --config ./examples/config.collections.yml --config-overlay collection
|
||||||
|
go run ./cmd/scriptorium render --config ./examples/config.collections.yml --config-overlay collection \
|
||||||
|
--prompt generic.markdown_summary \
|
||||||
|
--input transcript=./examples/fixtures/transcript.md \
|
||||||
|
--input glossary=./examples/fixtures/glossary.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Import and overlay file locations are constrained by ConfigKit; application
|
||||||
|
path values such as `promptkit_sources`, `schema_dir`, and `server.artifact_root`
|
||||||
|
remain relative to the process working directory even when authored in a
|
||||||
|
fragment or overlay. These source constraints are separate from Promptkit
|
||||||
|
message-resource paths and HTTP artifact containment.
|
||||||
|
|
||||||
| Field | Default | Meaning |
|
| Field | Default | Meaning |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `prompt_dir` | unset | Promptkit prompt-definition source directory. `run`, `render`, `serve`, and `inspect prompt` require an effective value. |
|
| `promptkit_sources` | empty sequence | Ordered file/directory sources for Promptkit backends, profiles, and prompts. |
|
||||||
| `profile_dir` | unset | Optional custom Promptkit profile source directory overlaid on Promptkit built-ins. |
|
|
||||||
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. |
|
| `schema_dir` | `.` | Promptkit schema source directory for relative schema paths. |
|
||||||
| `server.addr` | `:8080` | Address used by `serve`. |
|
| `server.addr` | `:8080` | Address used by `serve`. |
|
||||||
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
|
| `server.artifact_root` | unset | Root that enables HTTP `file` input references. |
|
||||||
@@ -88,7 +191,6 @@ These source constraints are separate from HTTP artifact containment.
|
|||||||
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
||||||
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
|
| `server.max_response_bytes` | `16777216` | Maximum encoded HTTP response bytes; `0` disables the limit. |
|
||||||
| `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. |
|
| `defaults.render_format` | `text` | Default prepared-run output format: `text` or `json`. |
|
||||||
| `backends` | unset | Optional mapping of custom Promptkit backend IDs to engine-scoped connection and capacity settings. |
|
|
||||||
| `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. |
|
| `transient_retries` | Promptkit default | Optional nonnegative count of additional built-in transient generation attempts. Omitted or `null` delegates to Promptkit; `0` disables additional attempts. |
|
||||||
|
|
||||||
The size fields must be zero or greater. The [HTTP API](api.md) defines how
|
The size fields must be zero or greater. The [HTTP API](api.md) defines how
|
||||||
@@ -96,55 +198,31 @@ each limit is enforced and reported. `server.artifact_root` configures an HTTP
|
|||||||
deployment boundary; see [operations](operations.md) for deployment handling.
|
deployment boundary; see [operations](operations.md) for deployment handling.
|
||||||
|
|
||||||
The `config validate`, `config show`, `config sources`, and `config explain`
|
The `config validate`, `config show`, `config sources`, and `config explain`
|
||||||
commands inspect this
|
commands inspect this application configuration without creating a Promptkit
|
||||||
application configuration without creating a Promptkit engine. `show` is a
|
engine. `show` is a resolved inspection snapshot, not necessarily a reloadable
|
||||||
resolved inspection snapshot, not necessarily a reloadable file. Application
|
file. Application validation does not check framework sources, backend
|
||||||
validation does not check framework sources, backend connectivity, or credential
|
connectivity, or credential availability. Use `inspect configuration` for
|
||||||
availability. `api_key_env` is an environment-variable *name* and remains
|
Promptkit's separately captured framework configuration; its four operations
|
||||||
visible in inspection; its environment value is never read by ConfigKit.
|
are documented in the [CLI reference](cli.md#framework-configuration-inspection).
|
||||||
Ordinary backend `extra_params` values also remain visible, so keep secrets out
|
|
||||||
of those fields and protect inspection output as potentially sensitive.
|
|
||||||
`config explain --path /server/addr` uses JSON Pointer syntax to show the
|
`config explain --path /server/addr` uses JSON Pointer syntax to show the
|
||||||
selected field's current value and history from defaults, files, overlays,
|
selected field's current value and history from defaults, files, overlays,
|
||||||
explicit CLI overrides, and normalization. `--path ''` selects the root.
|
explicit CLI overrides, and normalization. `--path ''` selects the root.
|
||||||
History includes replaced and removed values; `show` presents the final
|
History includes replaced and removed values; `show` presents the final
|
||||||
resolved snapshot. Neither renderer looks up credential bytes, and neither
|
resolved snapshot. The application schema rejects raw credential fields, but
|
||||||
claims to identify arbitrary secrets in unclassified parameter values.
|
do not treat inspection as a general-purpose filter for sensitive strings.
|
||||||
|
|
||||||
## Custom Backends
|
|
||||||
|
|
||||||
Use `backends` when a profile selects an application-defined backend ID:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
backends:
|
|
||||||
local-gpu:
|
|
||||||
endpoint: http://localhost:11434/v1
|
|
||||||
api_key_env: LOCAL_GPU_API_KEY
|
|
||||||
extra_params:
|
|
||||||
provider_option: enabled
|
|
||||||
concurrency_limit: 2
|
|
||||||
queue_capacity: 0
|
|
||||||
```
|
|
||||||
|
|
||||||
Each mapping key is the case-sensitive backend ID. `endpoint` is required;
|
|
||||||
`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are
|
|
||||||
optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting
|
|
||||||
`queue_capacity` lets Promptkit use its default for a limited backend, while
|
|
||||||
an explicit `queue_capacity: 0` disables queueing.
|
|
||||||
|
|
||||||
Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit
|
|
||||||
validates backend IDs, endpoints, environment-variable names, extra parameters,
|
|
||||||
and capacity relationships when Scriptorium constructs its engine. There are no
|
|
||||||
backend command-line overrides. Store only an environment-variable name in
|
|
||||||
`api_key_env`; raw API-key fields are not accepted.
|
|
||||||
|
|
||||||
## Framework Source Mapping
|
## Framework Source Mapping
|
||||||
|
|
||||||
Scriptorium passes `prompt_dir`, `profile_dir`, and `schema_dir` to Promptkit
|
Scriptorium assembles selected Promptkit source files and directories in the
|
||||||
when constructing its engine. Scriptorium does not redefine or independently
|
order described above, then constructs the Promptkit engine. Framework
|
||||||
parse those framework file formats.
|
definitions and custom backends belong in those selected source files, not in
|
||||||
|
the Scriptorium application configuration. Message `content_file` paths use
|
||||||
|
the defining source's resource context and are captured when the engine is
|
||||||
|
constructed; schema and request-artifact loading remain preparation-time
|
||||||
|
operations. Scriptorium does not redefine or independently parse framework
|
||||||
|
file formats.
|
||||||
|
|
||||||
- Prompt selection, versions, message templates, inputs, output contracts, and
|
- 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.
|
||||||
@@ -152,19 +230,18 @@ parse those framework file formats.
|
|||||||
contracts.
|
contracts.
|
||||||
|
|
||||||
See the
|
See the
|
||||||
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md)
|
[tagged Promptkit format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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 custom profile 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
|
||||||
|
|
||||||
@@ -195,7 +272,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.11.0/docs/integrations/openai-compatible-chat.md)
|
[OpenAI-compatible integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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.
|
||||||
|
|
||||||
@@ -204,4 +281,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.11.0/docs/formats.md)
|
- [Promptkit framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
|
|||||||
@@ -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.11.0/docs/consumers/pkg-promptkit.md)
|
[Promptkit Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md).
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||||
|
|||||||
@@ -1,10 +1,16 @@
|
|||||||
# 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/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md).
|
||||||
|
|
||||||
## Supported Migration Boundary
|
## Supported Migration Boundary
|
||||||
|
|
||||||
Scriptorium `v0.11.1` at
|
Scriptorium `v0.11.1` at
|
||||||
`gitea.maximumdirect.net/eric/scriptorium` is the final release that provides
|
`gitea.maximumdirect.net/eric/scriptorium` is the final release that provides
|
||||||
the former in-process Go framework. Promptkit `v0.11.0` at
|
the former in-process Go framework. Promptkit `v0.11.1` at
|
||||||
`gitea.maximumdirect.net/eric/promptkit` is the destination for that framework
|
`gitea.maximumdirect.net/eric/promptkit` is the destination for that framework
|
||||||
API. Scriptorium `v0.12.0` and later provide the CLI and HTTP application only.
|
API. Scriptorium `v0.12.0` and later provide the CLI and HTTP application only.
|
||||||
|
|
||||||
@@ -19,7 +25,7 @@ Start from a clean consumer checkout and review the pending diff before
|
|||||||
committing it. Add the published Promptkit module:
|
committing it. Add the published Promptkit module:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
go get gitea.maximumdirect.net/eric/promptkit@v0.11.0
|
go get gitea.maximumdirect.net/eric/promptkit@v0.11.1
|
||||||
```
|
```
|
||||||
|
|
||||||
For an ordinary consumer that imports the former root package under its
|
For an ordinary consumer that imports the former root package under its
|
||||||
@@ -51,14 +57,14 @@ go mod tidy
|
|||||||
go test ./...
|
go test ./...
|
||||||
```
|
```
|
||||||
|
|
||||||
Confirm that `go.mod` selects Promptkit `v0.11.0` and that no Go file imports
|
Confirm that `go.mod` selects Promptkit `v0.11.1` and that no Go file imports
|
||||||
the former Scriptorium package:
|
the former Scriptorium package:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
test "$(
|
test "$(
|
||||||
go list -m -f '{{.Path}}@{{.Version}}' \
|
go list -m -f '{{.Path}}@{{.Version}}' \
|
||||||
gitea.maximumdirect.net/eric/promptkit
|
gitea.maximumdirect.net/eric/promptkit
|
||||||
)" = 'gitea.maximumdirect.net/eric/promptkit@v0.11.0'
|
)" = 'gitea.maximumdirect.net/eric/promptkit@v0.11.1'
|
||||||
if git grep -n \
|
if git grep -n \
|
||||||
'gitea.maximumdirect.net/eric/scriptorium' \
|
'gitea.maximumdirect.net/eric/scriptorium' \
|
||||||
-- '*.go'
|
-- '*.go'
|
||||||
@@ -73,20 +79,20 @@ fi
|
|||||||
Promptkit preserves the established engine, request, result, profile,
|
Promptkit preserves the established engine, request, result, profile,
|
||||||
source-option, model-client, artifact, validation-value, and public-error
|
source-option, model-client, artifact, validation-value, and public-error
|
||||||
shapes where practical. Exact declarations and current behavior belong to the
|
shapes where practical. Exact declarations and current behavior belong to the
|
||||||
tagged [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md)
|
tagged [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md)
|
||||||
and Go source.
|
and Go source.
|
||||||
|
|
||||||
Promptkit also includes migration-relevant public contracts that were not in
|
Promptkit also includes migration-relevant public contracts that were not in
|
||||||
Scriptorium `v0.11.1`:
|
Scriptorium `v0.11.1`:
|
||||||
|
|
||||||
- [`WithArtifactReader`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/engine.go#L169-L174)
|
- [`WithArtifactReader`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/engine.go#L169-L174)
|
||||||
and the
|
and the
|
||||||
[`ArtifactReader` declaration](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/types.go#L315)
|
[`ArtifactReader` declaration](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/types.go#L315)
|
||||||
provide the artifact-reading extension described by the tagged
|
provide the artifact-reading extension described by the tagged
|
||||||
[extension-interface guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md#extension-interfaces).
|
[extension-interface guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md#extension-interfaces).
|
||||||
- [`ErrProfileRequired` and `ErrAPIKeyEnvMissing`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/engine.go#L33-L48)
|
- [`ErrProfileRequired` and `ErrAPIKeyEnvMissing`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/engine.go#L33-L48)
|
||||||
provide the specific identities described by the tagged
|
provide the specific identities described by the tagged
|
||||||
[error guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md#handle-errors).
|
[error guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md#handle-errors).
|
||||||
|
|
||||||
Use those tagged owners for exact signatures, wrapping guarantees, and
|
Use those tagged owners for exact signatures, wrapping guarantees, and
|
||||||
extension behavior.
|
extension behavior.
|
||||||
|
|||||||
110
docs/consumers/upgrading-promptkit.md
Normal file
110
docs/consumers/upgrading-promptkit.md
Normal file
@@ -0,0 +1,110 @@
|
|||||||
|
# Upgrade PromptKit Sources And Definitions
|
||||||
|
|
||||||
|
This guide covers the CLI and framework configuration cutover to
|
||||||
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/configuration-migration.md)
|
||||||
|
and ConfigKit v1.2.1. See the [framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
|
for the full upstream contract.
|
||||||
|
|
||||||
|
Removing version selectors and changing framework definition shapes are
|
||||||
|
intentional incompatible changes under the [release policy](../policy/release.md#versioning-and-compatibility).
|
||||||
|
|
||||||
|
## Application configuration
|
||||||
|
|
||||||
|
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: ./examples/framework/backends.yml
|
||||||
|
schema_dir: ./examples/schemas
|
||||||
|
```
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
## Rewrite framework definitions
|
||||||
|
|
||||||
|
Replace version-keyed prompts and keyed profile/backend mappings with lists
|
||||||
|
of records containing `id`. For example, before:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
prompts:
|
||||||
|
report:
|
||||||
|
"1":
|
||||||
|
default_profile: fast
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Summarize this note.
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
profiles:
|
||||||
|
fast:
|
||||||
|
endpoint: https://example.invalid/v1
|
||||||
|
model: synthetic-model
|
||||||
|
```
|
||||||
|
|
||||||
|
After:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
prompts:
|
||||||
|
- id: report
|
||||||
|
default_profile: fast
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Summarize this note.
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
profiles:
|
||||||
|
- id: fast
|
||||||
|
endpoint: https://example.invalid/v1
|
||||||
|
model: synthetic-model
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
PromptKit resolves `content_file` relative to the source that supplied the
|
||||||
|
field, including imported or inherited definitions. The
|
||||||
|
[framework format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md#messages-and-templates)
|
||||||
|
describes which paths are allowed within the source root.
|
||||||
|
|
||||||
|
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}`.
|
||||||
|
|
||||||
|
Across ordered `promptkit_sources` entries, a later framework underlay replaces
|
||||||
|
the whole record for the same ID. Supply the complete intended replacement,
|
||||||
|
or create a distinct inherited record. Checkouts imported by the same
|
||||||
|
[discovery file](../config.md#collection-checkout-discovery) are peers:
|
||||||
|
conflicting definitions of the same ID fail instead of overriding one another.
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## 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.
|
||||||
@@ -2,23 +2,41 @@
|
|||||||
|
|
||||||
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.11.0 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md);
|
[PromptKit v0.23.3 package](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md);
|
||||||
framework implementation work belongs in Promptkit. Application configuration
|
framework implementation work belongs in Promptkit. Application configuration
|
||||||
uses ConfigKit v0.4.0; keep Scriptorium's schema and source selection local.
|
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
|
## Initial Orientation
|
||||||
|
|
||||||
Before recommending, planning, or implementing work:
|
Before recommending, planning, or implementing work:
|
||||||
|
|
||||||
1. read the [agent policy](policy/agents.md);
|
1. inspect the working tree and preserve unrelated changes;
|
||||||
2. inspect the working tree and preserve unrelated changes;
|
2. use the policy and task-specific reading guides below; and
|
||||||
3. read the [architecture policy](policy/architecture.md);
|
3. inspect the relevant implementation and tests before changing them.
|
||||||
4. follow the task-specific contracts and internal documents below; and
|
|
||||||
5. inspect the relevant implementation and tests before changing them.
|
|
||||||
|
|
||||||
Also read the [documentation policy](policy/documentation.md) before changing
|
## Policy Reading Guide
|
||||||
documentation and the [testing policy](policy/testing.md) before changing
|
|
||||||
tests.
|
| Policy | Read before… |
|
||||||
|
| --- | --- |
|
||||||
|
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
|
||||||
|
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
|
||||||
|
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
|
||||||
|
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
|
||||||
|
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
|
||||||
|
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
|
||||||
|
| [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
|
||||||
|
|
||||||
|
- Read applicable policies before making decisions they govern; multiple policies
|
||||||
|
may apply.
|
||||||
|
- Select policies using the task triggers above. Follow cross-references to
|
||||||
|
relevant sections when needed to resolve a concrete question.
|
||||||
|
- Reuse policies already available in context; reread when changed or no longer
|
||||||
|
available.
|
||||||
|
- Expand reading when the task's scope expands.
|
||||||
|
- When revising a policy itself, read that policy and any provisions elsewhere
|
||||||
|
affected by the revision.
|
||||||
|
|
||||||
## Task-Specific Reading Guide
|
## Task-Specific Reading Guide
|
||||||
|
|
||||||
@@ -29,21 +47,31 @@ tests.
|
|||||||
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
||||||
| 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` |
|
||||||
| Prompt, profile, schema, generation, or validation semantics | [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.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) |
|
||||||
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md) |
|
| Prompt, profile, schema, generation, or validation semantics | [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md) and the [Promptkit consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md) |
|
||||||
|
| OpenAI-compatible outbound behavior or timeout layering | [PromptKit v0.23.3 integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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 format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md), and the related files under `examples/` |
|
| Examples or copyable assets | The owning Scriptorium contract, the relevant [PromptKit v0.23.3 format contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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
|
||||||
the tagged version. Do not commit a Go workspace, local replacement, vendored
|
the tagged version. Do not commit a Go workspace, local replacement, vendored
|
||||||
Promptkit source, or an import of a Promptkit `internal` package.
|
Promptkit source, or an import of a Promptkit `internal` package.
|
||||||
|
The module graph can include upstream maintainer tools such as ReleaseKit and
|
||||||
|
their dependencies even though those graph-only packages are not linked into
|
||||||
|
the Scriptorium runtime; use `go list -deps ./cmd/scriptorium` to distinguish
|
||||||
|
the linked packages.
|
||||||
|
|
||||||
## Baseline Validation
|
## Baseline Validation
|
||||||
|
|
||||||
|
The Go consumer minimum is the version declared in `go.mod`, currently 1.27.0,
|
||||||
|
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).
|
||||||
|
|
||||||
For code changes, run:
|
For code changes, run:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
@@ -55,8 +55,9 @@ 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.
|
||||||
|
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
|
||||||
|
|||||||
@@ -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.11.0/docs/consumers/pkg-promptkit.md).
|
[Go consumer guide](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md).
|
||||||
|
|
||||||
## Components And Collaborators
|
## Components And Collaborators
|
||||||
|
|
||||||
@@ -17,11 +17,14 @@ described by its tagged
|
|||||||
`internal/adapter/cli`.
|
`internal/adapter/cli`.
|
||||||
- `internal/adapter/cli` resolves settings through `internal/config`,
|
- `internal/adapter/cli` resolves settings through `internal/config`,
|
||||||
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
|
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
|
||||||
and owns output files, summaries, and exit codes.
|
exposes application and captured framework configuration inspection, and
|
||||||
|
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. 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.
|
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
|
- `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.
|
||||||
@@ -35,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.
|
||||||
@@ -44,14 +47,26 @@ 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. It constructs the same configuration-aware engine but does not perform
|
data. `inspect profile` maps an explicit profile ID to `Engine.InspectProfile`
|
||||||
preparation or generation.
|
and formats Scriptorium-owned resolved profile data without backend completion.
|
||||||
|
|
||||||
`inspect profile` maps an explicit profile ID to `Engine.InspectProfile` and
|
Both paths construct the same full-source engine as execution before inspecting
|
||||||
formats a safe application-owned effective profile view. It intentionally does
|
the chosen definition; selected prompts are not filtered out. They do not
|
||||||
not require prompt, schema, or artifact sources.
|
perform request preparation or generation. The [CLI definition-inspection
|
||||||
|
contract](../cli.md#scriptorium-inspect-prompt) owns the loading and runtime
|
||||||
|
boundaries, including the distinction between an optional prompt collection
|
||||||
|
and validating any prompts that were selected.
|
||||||
|
|
||||||
|
`inspect configuration` builds the same engine from the selected native
|
||||||
|
Promptkit source sequence, reads its captured configuration view, and delegates
|
||||||
|
effective output and explanation to Promptkit's native writers. The adapter
|
||||||
|
projects captured source records into its small JSON DTO. Its validation
|
||||||
|
operation constructs the engine without preparing a request. Framework source
|
||||||
|
semantics and report redaction are owned by Promptkit; the [CLI
|
||||||
|
contract](../cli.md#framework-configuration-inspection) documents the exposed
|
||||||
|
operations and their deliberately limited redaction scope.
|
||||||
|
|
||||||
The `config` family loads the same application ConfigKit result once and uses
|
The `config` family loads the same application ConfigKit result once and uses
|
||||||
its validation, effective-output, source, and explanation views directly. It
|
its validation, effective-output, source, and explanation views directly. It
|
||||||
@@ -62,11 +77,14 @@ JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers.
|
|||||||
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
||||||
adapter's consumer-owned `Runner` interface, and starts the server.
|
adapter's consumer-owned `Runner` interface, and starts the server.
|
||||||
|
|
||||||
The command paths assemble the engine from the same resolved prompt, profile,
|
The command paths assemble the engine from application-selected framework
|
||||||
and schema directories plus configured custom backends. Each backend is mapped
|
source files and directories plus the schema directory and retry setting.
|
||||||
to Promptkit's public `Backend` value and registered during engine construction,
|
Individual files become import-enabled ConfigKit inputs; directory selections
|
||||||
so one constructed server engine retains one immutable backend registry and its
|
are expanded through Promptkit's directory-input helper. Scriptorium supplies
|
||||||
associated capacity state.
|
those ordered underlays through Promptkit's public configuration API rather
|
||||||
|
than parsing or mapping framework definitions itself. The server constructs
|
||||||
|
one engine, which retains the framework's backend registry and associated
|
||||||
|
capacity state across requests.
|
||||||
|
|
||||||
### HTTP
|
### HTTP
|
||||||
|
|
||||||
@@ -77,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.
|
||||||
|
|
||||||
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
|
||||||
|
|||||||
@@ -7,13 +7,13 @@ public behavior belongs in the linked contracts.
|
|||||||
| Component | Implemented responsibility | References |
|
| Component | Implemented responsibility | References |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `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 and application-configuration inspection commands, resolves settings, constructs Promptkit engines only for execution/definition inspection, maps requests, and owns process output and exit behavior. | [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/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, supplies the ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.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. | [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.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md)
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
|
||||||
and are not part of this repository.
|
and are not part of this repository.
|
||||||
|
|||||||
@@ -5,20 +5,26 @@
|
|||||||
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 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md).
|
[PromptKit v0.23.3 format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md).
|
||||||
|
|
||||||
## Application Source Locations
|
## Application Source Locations
|
||||||
|
|
||||||
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from
|
`internal/config` resolves the ordered `promptkit_sources` sequence and
|
||||||
Scriptorium defaults, configuration files, and CLI overrides. It also resolves
|
`schema_dir` from application configuration and explicit CLI overrides. It
|
||||||
the application-owned `backends` mapping into sorted engine settings.
|
owns selector-shape validation, not framework file parsing. During engine
|
||||||
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps
|
construction, `internal/adapter/cli` turns file selections into import-enabled
|
||||||
each configured backend to Promptkit's public engine registration when
|
ConfigKit inputs and expands directory selections with
|
||||||
constructing an engine shared by the command path.
|
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
|
||||||
|
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.
|
||||||
|
|
||||||
Scriptorium does not search, parse, validate, or overlay framework source files
|
Promptkit uses ConfigKit to load and compose those framework inputs according
|
||||||
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema
|
to Promptkit's own schema and format. Scriptorium does not parse or validate
|
||||||
resolution, ordinary file artifacts, and the related error identities.
|
Promptkit definitions. Promptkit owns definition selection and validation,
|
||||||
|
profile built-ins and overlays, schema resolution, ordinary file artifacts,
|
||||||
|
captured framework configuration inspection, and related error identities.
|
||||||
|
|
||||||
The [configuration reference](../config.md) owns Scriptorium's source-location
|
The [configuration reference](../config.md) owns Scriptorium's source-location
|
||||||
fields and precedence. Maintained files under `examples/` are application
|
fields and precedence. Maintained files under `examples/` are application
|
||||||
@@ -26,33 +32,43 @@ inputs that use Promptkit's tagged formats.
|
|||||||
|
|
||||||
## Application Configuration Boundary
|
## Application Configuration Boundary
|
||||||
|
|
||||||
`internal/config` contains a ConfigKit-native `Document` definition. Its
|
`internal/config` contains the application-owned ConfigKit-native `Document`
|
||||||
fresh defaults come from Scriptorium's existing default constants; its resolver
|
definition. Its fresh defaults come from Scriptorium's existing default
|
||||||
records only actual trimming, path cleaning, and render-format normalization.
|
constants; its resolver records only actual leaf-level trimming, path cleaning, and
|
||||||
The validator reports application retry, size-limit, and format errors without
|
render-format normalization. The validator reports selector-shape, retry,
|
||||||
mutating the document or exposing rejected values. Application path values keep
|
size-limit, and format errors without mutating the document or exposing
|
||||||
working-directory-relative meaning. ConfigKit owns strict YAML decoding and
|
rejected values. Application path values keep working-directory-relative
|
||||||
presence semantics, including dynamic integer values in backend parameters.
|
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, the first existing implicit
|
The `Load` boundary selects an explicit file or constructs a native ConfigKit
|
||||||
configuration file, or ConfigKit's defaults-only source. Only absence advances
|
search over the ordered implicit paths. Discovery exhaustion uses defaults;
|
||||||
implicit discovery. One ConfigKit load applies explicit application overrides
|
a selected-file error stops loading. One ConfigKit load enables imports,
|
||||||
before validation and returns a result containing the resolved document and
|
applies explicitly supplied application overrides after decoding and before
|
||||||
its frozen inspection records. `Settings` converts that document into the
|
resolution and validation, and returns the document and its frozen inspection
|
||||||
existing runtime settings with backend IDs sorted; it does not read files or
|
records. `Settings` copies selectors in their resolved order into runtime
|
||||||
apply another merge. File-backed loads enable explicit ConfigKit imports and
|
settings; it does not read files or apply another merge. ConfigKit uses the selected file's
|
||||||
select one named overlay when requested. ConfigKit uses the selected file's
|
|
||||||
canonical directory as the source root; the application does not widen it.
|
canonical directory as the source root; the application does not widen it.
|
||||||
Application path values retain process-working-directory-relative meaning.
|
Application path values retain process-working-directory-relative meaning.
|
||||||
|
|
||||||
|
Runtime conversion consumes the resolved application values through the
|
||||||
|
existing `Settings` path. Promptkit receives selected framework sources only
|
||||||
|
after application configuration has loaded and validated; its source merge,
|
||||||
|
definition validation, and captured inspection view remain framework-owned.
|
||||||
|
|
||||||
Every configuration-loading command uses this boundary. The CLI maps only
|
Every configuration-loading command uses this boundary. The CLI maps only
|
||||||
explicitly visited application flags to ConfigKit overrides and prints
|
explicitly visited application flags to ConfigKit overrides and prints
|
||||||
structured load diagnostics before engine construction. The old application
|
structured load diagnostics before engine construction. Application and
|
||||||
|
framework load errors and warnings use their respective native writers. The old application
|
||||||
YAML decoder and merge path have been removed.
|
YAML decoder and merge path have been removed.
|
||||||
Application `config` inspection reuses the result's frozen effective,
|
Application `config` inspection reuses the result's frozen effective,
|
||||||
provenance, and history views without constructing an engine or reloading
|
provenance, and history views without constructing an engine or reloading
|
||||||
sources. It does not resolve API-key environment values; ordinary backend
|
sources. It does not resolve credentials. `inspect configuration` separately
|
||||||
parameters remain visible by the selected inspection policy.
|
constructs an engine and exposes Promptkit's captured framework view; only its
|
||||||
|
framework `show` and `explain` reports receive Promptkit's native,
|
||||||
|
credential-shaped redaction. Neither inspection family is a general-purpose
|
||||||
|
filter for arbitrary sensitive values.
|
||||||
|
|
||||||
## Restricted HTTP Artifact Reader
|
## Restricted HTTP Artifact Reader
|
||||||
|
|
||||||
|
|||||||
@@ -9,7 +9,9 @@ fields, or HTTP wire behavior.
|
|||||||
- [CLI reference](cli.md): commands, output destinations, and exit codes.
|
- [CLI reference](cli.md): commands, output destinations, and exit codes.
|
||||||
- [Configuration reference](config.md): application settings, source
|
- [Configuration reference](config.md): application settings, source
|
||||||
locations, defaults, and credential mapping.
|
locations, defaults, and credential mapping.
|
||||||
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md):
|
- [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise
|
||||||
|
source-selector and definition migration examples.
|
||||||
|
- [PromptKit v0.23.3 framework formats](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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,
|
||||||
@@ -39,10 +41,17 @@ without a report.
|
|||||||
|
|
||||||
## Deploy The Filesystem And Process
|
## Deploy The Filesystem And Process
|
||||||
|
|
||||||
Provide the process with readable configured Promptkit prompt, profile, and
|
Provide the process with readable selected Promptkit source files/directories
|
||||||
schema sources that follow the tagged framework formats. For an HTTP deployment
|
and schema sources that follow the tagged framework formats. At engine
|
||||||
that accepts file artifacts, use a dedicated, narrow artifact directory rather
|
construction, PromptKit v0.23.3 validates every selected effective definition,
|
||||||
than a general-purpose or sensitive filesystem tree.
|
including unused definitions, and captures referenced message-file contents
|
||||||
|
and static template syntax. `serve` constructs one engine at startup; it does
|
||||||
|
not reload changed configuration or message content. Restart the process to
|
||||||
|
validate and capture a new configuration. Schema and request-artifact reads,
|
||||||
|
credential resolution, and provider work remain request-preparation or runtime
|
||||||
|
concerns. For an HTTP deployment that accepts file artifacts, use a dedicated,
|
||||||
|
narrow artifact directory rather than a general-purpose or sensitive filesystem
|
||||||
|
tree.
|
||||||
|
|
||||||
If application configuration uses explicit imports or a selected overlay,
|
If application configuration uses explicit imports or a selected overlay,
|
||||||
deploy those files beneath the selected configuration file's canonical
|
deploy those files beneath the selected configuration file's canonical
|
||||||
@@ -52,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:
|
||||||
|
|
||||||
@@ -87,25 +99,27 @@ and apply the same retention and access rules as for model input and output.
|
|||||||
|
|
||||||
Before changing production inputs, profiles, or schemas:
|
Before changing production inputs, profiles, or schemas:
|
||||||
|
|
||||||
1. use `config validate`, `config show`, or `config sources` to check the
|
1. use `config validate`, `config show`, or `config sources` to check
|
||||||
application configuration and its selected sources without constructing an
|
Scriptorium's application configuration; these do not open Promptkit sources
|
||||||
engine; this does not verify prompt files, provider access, or credentials;
|
or construct an engine;
|
||||||
2. confirm the deployed configuration selects the intended sources and model
|
2. use `inspect configuration validate` to construct the engine and validate
|
||||||
credentials;
|
all selected framework definitions; this does not prepare a request, check
|
||||||
3. use [`render`](cli.md) with the same request inputs and variables to confirm
|
credentials, load request-time schemas/artifacts, or contact a provider;
|
||||||
|
3. confirm the deployed configuration selects the intended sources and
|
||||||
|
environment-variable names;
|
||||||
|
4. use [`render`](cli.md) with the same request inputs and variables to confirm
|
||||||
preparation without a model call;
|
preparation without a model call;
|
||||||
4. use [`run`](cli.md) for generation; and
|
5. use [`run`](cli.md) for generation; and
|
||||||
5. retain or discard validation-failed output according to the caller's
|
6. retain or discard validation-failed output according to the caller's
|
||||||
policy.
|
policy.
|
||||||
|
|
||||||
Inspection output can include configuration paths, names, and ordinary backend
|
Application configuration inspection can include paths and configured values.
|
||||||
parameters. `config explain --path` uses JSON Pointer paths and can show
|
Framework `inspect configuration show` and `explain` use Promptkit's native
|
||||||
displaced historical values as well as the final value. Protect both the
|
redaction for classified credential-shaped provider fields, including
|
||||||
selected paths and the output, especially when backend parameters contain
|
historical values, while leaving environment-reference names and ordinary
|
||||||
sensitive identifiers; ConfigKit does not infer arbitrary secrets in those
|
provider parameters visible. Neither report identifies arbitrary sensitive
|
||||||
parameters. Apply
|
content by value or name. Protect inspection output accordingly; Scriptorium
|
||||||
access and retention controls; the application stores only API-key environment
|
stores environment-variable names, not the resolved credential bytes.
|
||||||
reference names, not the resolved credential bytes.
|
|
||||||
|
|
||||||
The [maintained render script](../examples/render-markdown-summary.sh) is a
|
The [maintained render script](../examples/render-markdown-summary.sh) is a
|
||||||
copyable preflight example. The CLI reference owns its complete invocation and
|
copyable preflight example. The CLI reference owns its complete invocation and
|
||||||
@@ -150,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.11.0/docs/integrations/openai-compatible-chat.md)
|
[outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/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
|
||||||
@@ -158,8 +172,8 @@ 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. A canceled capacity waiter releases its Promptkit admission state.
|
||||||
|
|
||||||
|
|||||||
@@ -1,113 +1,82 @@
|
|||||||
# Open-Source Attribution
|
# Open Source Attribution Notices
|
||||||
|
|
||||||
Scriptorium's own terms are in the repository [LICENSE](../../LICENSE).
|
## Standard Repository Policies
|
||||||
The [OSS policy](../policy/oss.md) governs these entries. Dependency versions
|
|
||||||
are recorded in [go.mod](../../go.mod) and [go.sum](../../go.sum); source and
|
|
||||||
notice links below identify the exact commits for the selected versions.
|
|
||||||
|
|
||||||
## Promptkit
|
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.
|
||||||
|
|
||||||
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
Selected module: `go.maximumdirect.net/promptkit` at `v0.23.3`.
|
||||||
|
|
||||||
Copyright (C) 2026 Eric Rakestraw
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
SPDX-License-Identifier: LGPL-3.0-or-later
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
|
|
||||||
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
|
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
|
||||||
[GPL v3 companion](licenses/GPL-3.0.txt) |
|
[GPL 3.0](licenses/GPL-3.0.txt) |
|
||||||
[upstream LICENSE](https://gitea.maximumdirect.net/eric/promptkit/src/commit/db05b56166ca2d8650dfaf660e1cf0eed3932e1d/LICENSE)
|
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/COPYRIGHT) |
|
||||||
|
[LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/LICENSE).
|
||||||
|
|
||||||
Source: [Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/commit/db05b56166ca2d8650dfaf660e1cf0eed3932e1d)
|
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f).
|
||||||
|
|
||||||
## ConfigKit
|
## ConfigKit
|
||||||
|
|
||||||
Upstream copyright statement: no project-specific statement is present in the
|
Selected module: `go.maximumdirect.net/configkit` at `v1.2.1`.
|
||||||
selected module; the FSF copyright in its license text belongs to that license
|
|
||||||
document and is not substituted for a project notice.
|
|
||||||
|
|
||||||
SPDX-License-Identifier: LGPL-3.0-only
|
Copyright (C) 2026 Eric Rakestraw
|
||||||
|
|
||||||
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
|
SPDX-License-Identifier: LGPL-3.0-or-later
|
||||||
[GPL v3 companion](licenses/GPL-3.0.txt) |
|
|
||||||
[upstream LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/LICENSE)
|
|
||||||
|
|
||||||
Source: [ConfigKit v0.4.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258)
|
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/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT) |
|
||||||
|
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/LICENSE).
|
||||||
|
|
||||||
## Promptkit OpenRouter Catalog
|
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
|
||||||
|
|
||||||
Upstream copyright statement: no project-specific statement is present in the
|
|
||||||
selected module. The linked upstream README records the profile assets'
|
|
||||||
Promptkit origin and the copyright holder's deliberate relicensing.
|
|
||||||
|
|
||||||
SPDX-License-Identifier: LGPL-3.0-only
|
|
||||||
|
|
||||||
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
|
|
||||||
[GPL v3 companion](licenses/GPL-3.0.txt) |
|
|
||||||
[upstream LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f7518043ebdd70b8959506201639903dff0b85ab/LICENSE) |
|
|
||||||
[asset licensing notice](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f7518043ebdd70b8959506201639903dff0b85ab/README.md)
|
|
||||||
|
|
||||||
Source: [OpenRouter catalog v2.20260922.1](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f7518043ebdd70b8959506201639903dff0b85ab)
|
|
||||||
|
|
||||||
## Promptkit Rakestrawhome Catalog
|
|
||||||
|
|
||||||
Upstream copyright statement: no project-specific statement is present in the
|
|
||||||
selected module. The linked upstream README records the profile asset's
|
|
||||||
Promptkit origin and the copyright holder's deliberate relicensing.
|
|
||||||
|
|
||||||
SPDX-License-Identifier: LGPL-3.0-only
|
|
||||||
|
|
||||||
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
|
|
||||||
[GPL v3 companion](licenses/GPL-3.0.txt) |
|
|
||||||
[upstream LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/d664696142bf7c2d93db2a6b2e07f3deb55f2226/LICENSE) |
|
|
||||||
[asset licensing notice](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/d664696142bf7c2d93db2a6b2e07f3deb55f2226/README.md)
|
|
||||||
|
|
||||||
Source: [Rakestrawhome catalog v2.20260922.0](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/d664696142bf7c2d93db2a6b2e07f3deb55f2226)
|
|
||||||
|
|
||||||
## jsonschema/v6
|
## jsonschema/v6
|
||||||
|
|
||||||
Upstream copyright statement: no project-specific statement is present in the
|
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
|
||||||
selected module; no substitute statement is inferred here.
|
|
||||||
|
|
||||||
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) |
|
||||||
[upstream LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/29cbed948d24a04700eb94436416b18a07953b71/LICENSE)
|
[LICENSE](https://github.com/santhosh-tekuri/jsonschema/blob/b0fc661f4939578bc429f408c18202573dbafcc4/LICENSE).
|
||||||
|
|
||||||
Source: [jsonschema/v6 v6.0.2](https://github.com/santhosh-tekuri/jsonschema/tree/29cbed948d24a04700eb94436416b18a07953b71)
|
[Source](https://github.com/santhosh-tekuri/jsonschema/tree/b0fc661f4939578bc429f408c18202573dbafcc4).
|
||||||
|
|
||||||
## golang.org/x/text
|
## golang.org/x/text
|
||||||
|
|
||||||
Copyright (c) 2009 The Go Authors. All rights reserved.
|
Selected module: `golang.org/x/text` at `v0.44.0`.
|
||||||
|
|
||||||
|
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/go-x-text-BSD-3-Clause.txt) |
|
||||||
[upstream LICENSE](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353/LICENSE)
|
[LICENSE](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
|
||||||
|
[PATENTS](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513/PATENTS).
|
||||||
|
|
||||||
Source: [golang.org/x/text v0.14.0](https://go.googlesource.com/text/+/6c97a165dd661335ff7bce6104a008558123c353)
|
[Source](https://go.googlesource.com/text/+/6070ac32abcdd1670599eeb3ee4d513c8184a513).
|
||||||
|
|
||||||
## gopkg.in/yaml.v3
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
The upstream LICENSE assigns MIT to files ported from libyaml and Apache 2.0
|
|
||||||
to the remaining files; these are file-specific terms, not alternatives.
|
|
||||||
|
|
||||||
License and notices: [MIT](licenses/MIT.txt) |
|
|
||||||
[Apache 2.0](licenses/Apache-2.0.txt) |
|
|
||||||
[upstream LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
|
|
||||||
[upstream NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE)
|
|
||||||
|
|
||||||
Source: [gopkg.in/yaml.v3 v3.0.1](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`.
|
||||||
|
|
||||||
Copyright 2006-2010 Kirill Simonov
|
Copyright 2006-2010 Kirill Simonov
|
||||||
|
|
||||||
Copyright 2011-2019 Canonical Ltd
|
Copyright 2011-2019 Canonical Ltd
|
||||||
@@ -116,12 +85,9 @@ Copyright 2025 The go-yaml Project Contributors
|
|||||||
|
|
||||||
SPDX-License-Identifier: MIT AND Apache-2.0
|
SPDX-License-Identifier: MIT AND Apache-2.0
|
||||||
|
|
||||||
The upstream NOTICE assigns MIT to files ported from libyaml and Apache 2.0
|
|
||||||
to the remaining files; these are file-specific terms, not alternatives.
|
|
||||||
|
|
||||||
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) |
|
||||||
[upstream LICENSE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/LICENSE) |
|
[LICENSE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/LICENSE) |
|
||||||
[upstream NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE)
|
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
|
||||||
|
|
||||||
Source: [go.yaml.in/yaml/v4 v4.0.0-rc.6](https://github.com/yaml/go-yaml/tree/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125)
|
[Source](https://github.com/yaml/go-yaml/tree/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
|
||||||
|
|||||||
170
docs/oss/licenses/CC-BY-SA-4.0.txt
Normal file
170
docs/oss/licenses/CC-BY-SA-4.0.txt
Normal file
@@ -0,0 +1,170 @@
|
|||||||
|
Creative Commons Attribution-ShareAlike 4.0 International
|
||||||
|
|
||||||
|
Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
|
||||||
|
|
||||||
|
Using Creative Commons Public Licenses
|
||||||
|
|
||||||
|
Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
|
||||||
|
|
||||||
|
Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors.
|
||||||
|
|
||||||
|
Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described.
|
||||||
|
|
||||||
|
Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public.
|
||||||
|
|
||||||
|
Creative Commons Attribution-ShareAlike 4.0 International Public License
|
||||||
|
|
||||||
|
By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-ShareAlike 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
|
||||||
|
|
||||||
|
Section 1 – Definitions.
|
||||||
|
|
||||||
|
a. Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
|
||||||
|
|
||||||
|
b. Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
|
||||||
|
|
||||||
|
c. BY-SA Compatible License means a license listed at creativecommons.org/compatiblelicenses, approved by Creative Commons as essentially the equivalent of this Public License.
|
||||||
|
|
||||||
|
d. Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
|
||||||
|
|
||||||
|
e. Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
|
||||||
|
|
||||||
|
f. Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
|
||||||
|
|
||||||
|
g. License Elements means the license attributes listed in the name of a Creative Commons Public License. The License Elements of this Public License are Attribution and ShareAlike.
|
||||||
|
|
||||||
|
h. Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
|
||||||
|
|
||||||
|
i. Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
|
||||||
|
|
||||||
|
j. Licensor means the individual(s) or entity(ies) granting rights under this Public License.
|
||||||
|
|
||||||
|
k. Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
|
||||||
|
|
||||||
|
l. Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
|
||||||
|
|
||||||
|
m. You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
|
||||||
|
|
||||||
|
Section 2 – Scope.
|
||||||
|
|
||||||
|
a. License grant.
|
||||||
|
|
||||||
|
1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
|
||||||
|
|
||||||
|
A. reproduce and Share the Licensed Material, in whole or in part; and
|
||||||
|
|
||||||
|
B. produce, reproduce, and Share Adapted Material.
|
||||||
|
|
||||||
|
2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
|
||||||
|
|
||||||
|
3. Term. The term of this Public License is specified in Section 6(a).
|
||||||
|
|
||||||
|
4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
|
||||||
|
|
||||||
|
5. Downstream recipients.
|
||||||
|
|
||||||
|
A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
|
||||||
|
|
||||||
|
B. Additional offer from the Licensor – Adapted Material. Every recipient of Adapted Material from You automatically receives an offer from the Licensor to exercise the Licensed Rights in the Adapted Material under the conditions of the Adapter’s License You apply.
|
||||||
|
|
||||||
|
C. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
|
||||||
|
|
||||||
|
6. No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
|
||||||
|
|
||||||
|
b. Other rights.
|
||||||
|
|
||||||
|
1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
|
||||||
|
|
||||||
|
2. Patent and trademark rights are not licensed under this Public License.
|
||||||
|
|
||||||
|
3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
|
||||||
|
|
||||||
|
Section 3 – License Conditions.
|
||||||
|
|
||||||
|
Your exercise of the Licensed Rights is expressly made subject to the following conditions.
|
||||||
|
|
||||||
|
a. Attribution.
|
||||||
|
|
||||||
|
1. If You Share the Licensed Material (including in modified form), You must:
|
||||||
|
|
||||||
|
A. retain the following if it is supplied by the Licensor with the Licensed Material:
|
||||||
|
|
||||||
|
i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
|
||||||
|
|
||||||
|
ii. a copyright notice;
|
||||||
|
|
||||||
|
iii. a notice that refers to this Public License;
|
||||||
|
|
||||||
|
iv. a notice that refers to the disclaimer of warranties;
|
||||||
|
|
||||||
|
v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
|
||||||
|
|
||||||
|
B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
|
||||||
|
|
||||||
|
C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
|
||||||
|
|
||||||
|
2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
|
||||||
|
|
||||||
|
3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
|
||||||
|
|
||||||
|
b. ShareAlike.In addition to the conditions in Section 3(a), if You Share Adapted Material You produce, the following conditions also apply.
|
||||||
|
|
||||||
|
1. The Adapter’s License You apply must be a Creative Commons license with the same License Elements, this version or later, or a BY-SA Compatible License.
|
||||||
|
|
||||||
|
2. You must include the text of, or the URI or hyperlink to, the Adapter's License You apply. You may satisfy this condition in any reasonable manner based on the medium, means, and context in which You Share Adapted Material.
|
||||||
|
|
||||||
|
3. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, Adapted Material that restrict exercise of the rights granted under the Adapter's License You apply.
|
||||||
|
|
||||||
|
Section 4 – Sui Generis Database Rights.
|
||||||
|
|
||||||
|
Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
|
||||||
|
|
||||||
|
a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
|
||||||
|
|
||||||
|
b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material, including for purposes of Section 3(b); and
|
||||||
|
|
||||||
|
c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
|
||||||
|
For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
|
||||||
|
|
||||||
|
Section 5 – Disclaimer of Warranties and Limitation of Liability.
|
||||||
|
|
||||||
|
a. Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.
|
||||||
|
|
||||||
|
b. To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.
|
||||||
|
|
||||||
|
c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
|
||||||
|
|
||||||
|
Section 6 – Term and Termination.
|
||||||
|
|
||||||
|
a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
|
||||||
|
|
||||||
|
b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
|
||||||
|
|
||||||
|
1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
|
||||||
|
|
||||||
|
2. upon express reinstatement by the Licensor.
|
||||||
|
|
||||||
|
c. For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
|
||||||
|
|
||||||
|
d. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
|
||||||
|
|
||||||
|
e. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
|
||||||
|
|
||||||
|
Section 7 – Other Terms and Conditions.
|
||||||
|
|
||||||
|
a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
|
||||||
|
|
||||||
|
b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
|
||||||
|
|
||||||
|
Section 8 – Interpretation.
|
||||||
|
|
||||||
|
a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
|
||||||
|
|
||||||
|
b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
|
||||||
|
|
||||||
|
c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
|
||||||
|
|
||||||
|
d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
|
||||||
|
|
||||||
|
Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
|
||||||
|
|
||||||
|
Creative Commons may be contacted at creativecommons.org.
|
||||||
27
docs/oss/licenses/go-x-text-BSD-3-Clause.txt
Normal file
27
docs/oss/licenses/go-x-text-BSD-3-Clause.txt
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
Copyright 2009 The Go Authors.
|
||||||
|
|
||||||
|
Redistribution and use in source and binary forms, with or without
|
||||||
|
modification, are permitted provided that the following conditions are
|
||||||
|
met:
|
||||||
|
|
||||||
|
* Redistributions of source code must retain the above copyright
|
||||||
|
notice, this list of conditions and the following disclaimer.
|
||||||
|
* Redistributions in binary form must reproduce the above
|
||||||
|
copyright notice, this list of conditions and the following disclaimer
|
||||||
|
in the documentation and/or other materials provided with the
|
||||||
|
distribution.
|
||||||
|
* Neither the name of Google LLC nor the names of its
|
||||||
|
contributors may be used to endorse or promote products derived from
|
||||||
|
this software without specific prior written permission.
|
||||||
|
|
||||||
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||||||
|
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||||||
|
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
||||||
|
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||||||
|
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||||||
|
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||||||
|
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||||||
|
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||||||
|
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||||||
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||||
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
@@ -1,12 +1,14 @@
|
|||||||
# Agent Policy
|
# Agent Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.1
|
**Base Policy Version:** 1.3
|
||||||
|
|
||||||
**Last Updated:** 2026-09-26
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/agents.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
Agents working in this repository must read and adhere to the following house rules.
|
Agents must read and follow these rules.
|
||||||
|
|
||||||
## Implementation Discipline
|
## Implementation Discipline
|
||||||
|
|
||||||
@@ -43,15 +45,15 @@ unless that behavior was expressly selected as part of the contract.
|
|||||||
|
|
||||||
## Git Commit Policy
|
## Git Commit Policy
|
||||||
|
|
||||||
By default, create a commit after completing each coherent unit of work, using a
|
By default, commit each completed, nonempty unit of work using a
|
||||||
concise, plain-English message describing what changed. This policy is standing
|
concise, plain-English message describing what changed. This policy is standing
|
||||||
authorization to create those local commits; a separate user request is not
|
authorization to create those local commits; a separate user request is not
|
||||||
required. An explicit user instruction to leave work uncommitted takes precedence.
|
required. An explicit user instruction to leave work uncommitted takes precedence.
|
||||||
|
|
||||||
A unit of work is a focused, reviewable outcome, including its relevant tests and
|
A unit of work is a focused, reviewable outcome, including its relevant tests and
|
||||||
documentation. Do not commit after every intermediate edit or create empty commits.
|
documentation.
|
||||||
Complete the appropriate validation before committing. If work is incomplete or
|
Complete the appropriate validation before committing. If work is incomplete or
|
||||||
validation is blocked, report that state rather than presenting it as completed.
|
validation is blocked, report that state accurately.
|
||||||
|
|
||||||
Before committing:
|
Before committing:
|
||||||
|
|
||||||
@@ -59,10 +61,10 @@ Before committing:
|
|||||||
changes. Identify changes that predate the current unit of work.
|
changes. Identify changes that predate the current unit of work.
|
||||||
2. Exclude secrets, local environment files, generated junk, and unrelated changes.
|
2. Exclude secrets, local environment files, generated junk, and unrelated changes.
|
||||||
3. Stage only the files or hunks belonging to the completed unit. Use `git add .`
|
3. Stage only the files or hunks belonging to the completed unit. Use `git add .`
|
||||||
only when every included change belongs to that unit. Do not disturb unrelated
|
only when every included change belongs to that unit. Preserve unrelated
|
||||||
staged or unstaged work.
|
staged and unstaged work.
|
||||||
4. Review `git diff --staged` and run appropriate checks for the change. Do not
|
4. Review `git diff --staged` and run appropriate checks for the change. Reuse
|
||||||
repeat checks already passed for unchanged content merely to create a commit.
|
successful checks for unchanged content.
|
||||||
5. Review `git log --oneline -n 10` and use
|
5. Review `git log --oneline -n 10` and use
|
||||||
`git commit -m "<concise plain-English commit message>"`.
|
`git commit -m "<concise plain-English commit message>"`.
|
||||||
6. Report the commit identifier and any remaining uncommitted work.
|
6. Report the commit identifier and any remaining uncommitted work.
|
||||||
|
|||||||
@@ -1,147 +1,124 @@
|
|||||||
# Architecture Policy
|
# Architecture Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.1
|
**Base Policy Version:** 1.3
|
||||||
|
|
||||||
**Last Updated:** 2026-09-26
|
**Last Updated**: 2026-11-19
|
||||||
|
|
||||||
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/architecture.md
|
||||||
|
|
||||||
## Purpose And Ownership
|
## Purpose And Ownership
|
||||||
|
|
||||||
This policy defines Scriptorium's purpose, responsibility and dependency
|
The adopted policy defines the application's purpose and the architectural
|
||||||
boundaries, established invariants, and non-goals. Concrete component inventory
|
constraints contributors must follow. It owns system boundaries, responsibility
|
||||||
and implementation mechanics belong in [internal documentation](../internal/overview.md);
|
and dependency rules, established invariants, and explicit non-goals.
|
||||||
public behavior belongs in its canonical contracts.
|
|
||||||
|
|
||||||
Adopted constraints govern future development without implying that every
|
Describe the concrete package inventory and implementation mechanics in internal
|
||||||
capability they could govern exists or is planned. Keep proposed structure and
|
documentation. Link to canonical public contracts for their exact behavior and
|
||||||
implementation status in roadmaps, and decision rationale in ADRs. Acceptance
|
to ADRs for decision rationale.
|
||||||
of a decision is not proof of implementation. Do not turn incidental choices
|
|
||||||
into architectural invariants.
|
|
||||||
|
|
||||||
## System Shape
|
## Architectural Approach
|
||||||
|
|
||||||
Scriptorium is an executable application with four command entry paths: CLI
|
Hexagonal architecture is strongly recommended, including encapsulating external
|
||||||
`run`, CLI `render`, CLI `inspect`, and the HTTP service started by `serve`.
|
integrations and APIs within internal adapters. Keep domain and application
|
||||||
The `inspect` command has prompt and profile modes. Scriptorium does not expose
|
logic independent of external integration details, and make dependency direction
|
||||||
a reusable root Go package.
|
clear in the adopted policy.
|
||||||
|
|
||||||
The application consumes
|
Implement that separation with proportionate, idiomatic code. Choose interfaces
|
||||||
[Promptkit v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md)
|
and package layout to serve the application's actual boundaries. Use adapters
|
||||||
through its supported root package. Promptkit owns prompt execution,
|
for collaborators with external integration responsibilities.
|
||||||
preparation, source formats, built-in profiles, model-client behavior, and
|
|
||||||
validation. Scriptorium owns application configuration, executable adapters,
|
|
||||||
prepared-run and definition-inspection presentation, process behavior, and HTTP
|
|
||||||
deployment policy.
|
|
||||||
|
|
||||||
Scriptorium also consumes ConfigKit v0.4.0 for application configuration
|
## Adopted Constraints And Implemented Structure
|
||||||
decoding, resolution, and validation flow. Scriptorium owns its application
|
|
||||||
schema, defaults, normalization, validation rules, source selection, and CLI
|
|
||||||
flag mapping; ConfigKit does not own Promptkit framework sources or HTTP
|
|
||||||
artifact containment.
|
|
||||||
|
|
||||||
The concrete package inventory is maintained in the
|
Architectural constraints govern current and future development. Record
|
||||||
[internal overview](../internal/overview.md).
|
implemented structure accurately, proposals and implementation status in the
|
||||||
|
roadmap, and significant decisions and rationale in ADRs. Describe a target
|
||||||
|
structure as implemented when its changes land.
|
||||||
|
|
||||||
As established by [ADR 0004](../adr/0004-definition-boundary.md), Scriptorium
|
Constraints must reflect deliberately selected requirements and decisions.
|
||||||
aims to support the complete set of features in valid Promptkit prompt and
|
Do not promote incidental implementation choices into architectural invariants.
|
||||||
profile definitions for its selected upstream version. Promptkit remains the
|
|
||||||
canonical parser and validator. Library-only features are considered
|
|
||||||
individually against the simple predefined-prompt execution model.
|
|
||||||
|
|
||||||
Maintain adapter boundaries with proportionate, idiomatic code. This approach
|
## Scriptorium's Purpose And System Shape
|
||||||
does not require an interface for every type, additional wrappers, or a fixed
|
|
||||||
directory tree for integrations that do not exist.
|
|
||||||
|
|
||||||
## Dependency Direction
|
Scriptorium is an executable application with CLI `run`, `render`,
|
||||||
|
`inspect`, and `config` command families and an HTTP service started by
|
||||||
|
`serve`. It offers simple, request-independent execution of predefined
|
||||||
|
prompts, not a reusable Scriptorium root Go API or a workflow framework.
|
||||||
|
The [internal overview](../internal/overview.md) owns the concrete package
|
||||||
|
inventory; [adapter internals](../internal/adapters.md) and
|
||||||
|
[source internals](../internal/sources.md) own implementation mechanics.
|
||||||
|
|
||||||
```text
|
## Framework And Application Boundaries
|
||||||
cmd/scriptorium
|
|
||||||
|
|
|
||||||
v
|
|
||||||
CLI and HTTP adapters, configuration, defaults, and formatting
|
|
||||||
|
|
|
||||||
v
|
|
||||||
Promptkit (execution) and ConfigKit (application configuration)
|
|
||||||
```
|
|
||||||
|
|
||||||
- Retained application packages may import Promptkit's root package.
|
Scriptorium consumes
|
||||||
- They must not import Promptkit `internal` packages.
|
[PromptKit v0.23.3](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md)
|
||||||
- They must not import Promptkit catalog modules directly.
|
through its supported public root package. Promptkit owns prompt execution,
|
||||||
- They must not import the removed Scriptorium root facade or recreate former
|
preparation, prompt and profile formats, built-in profiles, model-client
|
||||||
framework package families.
|
behavior, validation, inspection semantics, and framework defaults. Scriptorium
|
||||||
- Adapter-owned interfaces use Promptkit public values when a consumer-side
|
owns the application domain, executable CLI and HTTP adapters, process behavior,
|
||||||
substitution boundary is needed.
|
and HTTP deployment policy. It interprets resolved configuration and uses
|
||||||
- Scriptorium passes omitted framework settings as zero values so Promptkit
|
PromptKit's supported APIs and results to satisfy user requests. The [format
|
||||||
applies its own defaults.
|
reference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/formats.md)
|
||||||
|
and [outbound integration contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/integrations/openai-compatible-chat.md)
|
||||||
|
remain Promptkit's contracts.
|
||||||
|
|
||||||
The repository architecture guard enforces these import and removal
|
ConfigKit v1.2.1 owns configuration policy and the lifecycle through the final,
|
||||||
invariants.
|
fully resolved configuration handoff. Scriptorium supplies application schema
|
||||||
|
and domain callbacks through ConfigKit's supported extension points and consumes
|
||||||
|
the completed result without redefining effective configuration. PromptKit's
|
||||||
|
configuration is also resolved through ConfigKit, with PromptKit supplying its
|
||||||
|
domain schema and rules. The [configuration contract](../config.md) owns
|
||||||
|
externally observable application behavior; PromptKit owns framework formats.
|
||||||
|
|
||||||
Cross-project changes land and release in Promptkit before Scriptorium adopts
|
As decided in [ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md),
|
||||||
the tagged dependency. Do not commit Go workspaces, local replacements,
|
Scriptorium adopts CommandKit's native `ckconfig` and `ckprompt` interfaces to
|
||||||
vendored Promptkit implementation, or unpublished dependency assumptions.
|
neutrally expose upstream features and semantics. The current CLI still uses
|
||||||
|
custom presentation; the [adoption roadmap](../roadmap/commandkit-adoption.md)
|
||||||
|
tracks its replacement. This decision complements ADRs 0004 and 0005.
|
||||||
|
|
||||||
## Retained Boundaries
|
The CLI exposes Promptkit's captured framework configuration inspection. Its
|
||||||
|
`show` and `explain` reports use Promptkit's native redaction for classified
|
||||||
|
credential-shaped fields, including historical values. This scoped behavior is
|
||||||
|
not a general-purpose filter for arbitrary sensitive content and does not
|
||||||
|
extend to application configuration or existing prompt/profile inspection.
|
||||||
|
|
||||||
- `internal/adapter/cli` owns commands, flags, configuration precedence,
|
Application code may import Promptkit's public root package, but not its
|
||||||
process streams, output files, summaries, and exit codes.
|
`internal` packages or catalog modules. It must not recreate the removed
|
||||||
- `internal/adapter/http` owns routes, strict JSON DTOs, size limits, response
|
Scriptorium framework facade or former framework package families.
|
||||||
mapping, status mapping, and the restricted artifact reader.
|
Adapter-owned interfaces use Promptkit public values when a consumer-side
|
||||||
- `internal/config` owns discovery and Scriptorium's application definition;
|
substitution boundary is needed. Omitted framework settings pass as zero
|
||||||
ConfigKit owns strict YAML decoding and the load/override pipeline.
|
values so Promptkit applies its own defaults. Cross-project changes land and
|
||||||
- `internal/defaults` owns Scriptorium application and HTTP defaults only.
|
release in Promptkit before
|
||||||
- `internal/format` owns deterministic prepared-run and definition-inspection
|
Scriptorium adopts its tagged dependency; do not commit Go workspaces, local
|
||||||
text and JSON presentation.
|
replacements, vendored Promptkit source, or unpublished dependency assumptions.
|
||||||
- Promptkit owns framework orchestration and contracts. Its
|
The repository's architecture guard protects these import and removal
|
||||||
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md)
|
boundaries. Adapter separation does not require an interface for every type,
|
||||||
and
|
extra wrappers, or a fixed directory tree.
|
||||||
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md)
|
|
||||||
are canonical.
|
|
||||||
|
|
||||||
## HTTP Artifact Security Boundary
|
## Definition Support And Request State
|
||||||
|
|
||||||
Ordinary CLI file loading is provided by Promptkit. Scriptorium's HTTP adapter
|
As decided in [ADR 0004](../adr/0004-definition-boundary.md), Scriptorium aims
|
||||||
injects a restricted `promptkit.ArtifactReader` for inbound HTTP requests.
|
to support the complete set of features in valid Promptkit prompt and profile
|
||||||
That reader denies file references without an artifact root, enforces the
|
definitions for its selected upstream version. Promptkit remains the canonical
|
||||||
configured byte limit, and applies Scriptorium's lexical root-containment rule.
|
parser and validator. Library-only features are considered individually
|
||||||
The operating system still follows symlinks after the lexical check.
|
against Scriptorium's simple predefined-prompt execution model.
|
||||||
|
|
||||||
This boundary handles untrusted request references under the documented
|
External YAML and JSON decoding remains strict. Adapters map external values
|
||||||
deployment model; it is not a filesystem sandbox. Defending against a
|
through Promptkit public requests and results without taking over framework
|
||||||
privileged actor concurrently modifying the host filesystem is outside the
|
orchestration. Explicit numeric request overrides preserve presence, including
|
||||||
adopted scope, not a claim that such activity cannot occur. Do not infer
|
zero. Adapters map Promptkit public error identities to CLI exits or HTTP
|
||||||
additional defenses or guarantees from hypothetical threats; raise unsettled
|
statuses without classifying by message text. Raw API keys are not accepted
|
||||||
scope decisions under the [agent policy](agents.md).
|
in Scriptorium configuration, CLI arguments, or HTTP payloads, and resolved
|
||||||
|
|
||||||
The [HTTP API](../api.md) owns observable request outcomes, and
|
|
||||||
[operations](../operations.md) owns deployment permissions and root selection.
|
|
||||||
|
|
||||||
## State, Errors, And Secrets
|
|
||||||
|
|
||||||
Scriptorium has no durable run-state store, checkpoint, cache, or resume
|
|
||||||
mechanism. Recovery is a new request after correcting inputs, configuration, or
|
|
||||||
environment.
|
|
||||||
|
|
||||||
Each request is self-contained from the caller's perspective, without
|
|
||||||
conversation or workflow state retained from completed requests. This does
|
|
||||||
not mean the process is internally stateless. Shared engines, backend capacity
|
|
||||||
and queue accounting, in-flight coordination, cancellation, and server
|
|
||||||
lifecycle resources are permitted and must be shared where necessary to
|
|
||||||
enforce configured backend limits across concurrent requests. Such state must
|
|
||||||
be concurrency-safe and does not create a durable user-workflow contract.
|
|
||||||
|
|
||||||
Adapters map Promptkit public error identities into CLI exits or HTTP statuses
|
|
||||||
without classifying by message text. Raw API keys are not accepted in
|
|
||||||
Scriptorium configuration, CLI arguments, or HTTP payloads, and resolved
|
|
||||||
secrets must not be emitted.
|
secrets must not be emitted.
|
||||||
|
|
||||||
## Architectural Invariants
|
Each execution request is self-contained from the caller's perspective; no
|
||||||
|
conversation or workflow state is retained from completed requests. This
|
||||||
- External YAML and JSON decoding remains strict.
|
does not preclude process-scoped operational state. A server shares its
|
||||||
- CLI and HTTP behavior remains presentation and transport logic rather than
|
Promptkit engine, backend registry, capacity admission and queue accounting
|
||||||
framework orchestration.
|
across relevant concurrent requests so configured backend limits cannot be
|
||||||
- Explicit numeric request overrides preserve presence, including zero.
|
bypassed by per-request construction. In-flight coordination, cancellation,
|
||||||
- HTTP artifact containment and byte limits remain Scriptorium policy.
|
and server lifecycle state must be concurrency-safe. None of this creates a
|
||||||
- No application package depends on Promptkit implementation packages.
|
durable workflow, checkpoint, cache, or resume contract; recovery is a new
|
||||||
|
request after correcting inputs, configuration, or environment.
|
||||||
|
|
||||||
## Non-Goals
|
## Non-Goals
|
||||||
|
|
||||||
@@ -153,5 +130,19 @@ secrets must not be emitted.
|
|||||||
- Do not add durable workflow, archive, or resume behavior.
|
- Do not add durable workflow, archive, or resume behavior.
|
||||||
- Do not add application-managed prompt modification, follow-up message flows,
|
- Do not add application-managed prompt modification, follow-up message flows,
|
||||||
conversation management, or multi-step workflow orchestration.
|
conversation management, or multi-step workflow orchestration.
|
||||||
|
## Trust Boundaries And Threat Scope
|
||||||
|
|
||||||
Work that is not implemented belongs in `docs/roadmap/`.
|
Ordinary CLI file loading belongs to Promptkit. For untrusted inbound HTTP
|
||||||
|
artifact references, Scriptorium injects a restricted
|
||||||
|
`promptkit.ArtifactReader`. It denies file references without an artifact
|
||||||
|
root, applies the configured byte limit, and enforces lexical root containment.
|
||||||
|
The operating system follows symlinks after that lexical check. This is not a
|
||||||
|
filesystem sandbox or a defense against a privileged actor concurrently
|
||||||
|
modifying the host filesystem; that threat is outside the adopted scope.
|
||||||
|
Do not infer stronger defenses from hypothetical threats. Raise unsettled
|
||||||
|
scope decisions under the [agent policy](agents.md).
|
||||||
|
|
||||||
|
The [HTTP API](../api.md) owns observable request outcomes, the
|
||||||
|
[configuration contract](../config.md) owns credential supply, and
|
||||||
|
[operations](../operations.md) owns deployment permissions and root selection.
|
||||||
|
The [source internals](../internal/sources.md) describe reader mechanics.
|
||||||
|
|||||||
@@ -1,15 +1,16 @@
|
|||||||
# Documentation Policy
|
# Documentation Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.4
|
**Base Policy Version:** 1.12
|
||||||
|
|
||||||
**Last Updated:** 2026-09-26
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
This policy assigns each documentation topic to one canonical owner. Its goal is
|
This policy assigns each documentation topic to one canonical owner. Its goal is
|
||||||
to keep this repository's documentation accurate, concise, discoverable, and
|
to keep this application's documentation accurate, concise, discoverable, and resistant
|
||||||
resistant to drift for users, operators, developers, integrators, and LLM
|
to drift for users, operators, developers, integrators, and LLM coding agents.
|
||||||
coding agents.
|
|
||||||
|
|
||||||
## Core Rules
|
## Core Rules
|
||||||
|
|
||||||
@@ -17,45 +18,38 @@ coding agents.
|
|||||||
|
|
||||||
Each authoritative fact belongs in one document. A non-owning document may give
|
Each authoritative fact belongs in one document. A non-owning document may give
|
||||||
a short, stable summary for orientation, but it must link to the canonical owner
|
a short, stable summary for orientation, but it must link to the canonical owner
|
||||||
instead of repeating volatile details.
|
for volatile details.
|
||||||
|
|
||||||
Volatile details include commands, flags, configuration fields and defaults,
|
Volatile details include commands, flags, configuration fields and defaults,
|
||||||
module keys, schemas, file names, paths, status codes, retry behavior, and
|
module keys, schemas, file names, paths, status codes, retry behavior, and
|
||||||
runtime guarantees. If readers could reasonably treat a statement as a
|
runtime guarantees. If readers could reasonably treat a statement as a
|
||||||
contract, maintain it only in the owning document.
|
contract, maintain it only in the owning document.
|
||||||
|
|
||||||
Minimal tested usage examples are allowed outside the owning contract when this
|
|
||||||
policy assigns them an orientation or instructional purpose. They must link to
|
|
||||||
the canonical contract and must not redefine complete syntax, defaults, or
|
|
||||||
semantics.
|
|
||||||
|
|
||||||
### Current And Future Behavior
|
### Current And Future Behavior
|
||||||
|
|
||||||
Outside `docs/roadmap/`, documentation describes implemented behavior only.
|
Outside `docs/roadmap/`, documentation describes implemented behavior only.
|
||||||
Partial features may be described only to their implemented boundary.
|
Partial features may be described only to their implemented boundary.
|
||||||
|
|
||||||
Architectural constraints may govern future changes without implying that the
|
Architectural constraints may govern future changes. Describe current structure
|
||||||
components or capabilities they would govern already exist. This does not
|
from implemented behavior.
|
||||||
permit describing a proposed system structure as implemented.
|
|
||||||
|
|
||||||
ADRs may record an accepted architectural decision before implementation, but
|
ADRs may record an accepted architectural decision before implementation. The
|
||||||
acceptance must not be presented as proof that the behavior exists. The roadmap
|
roadmap owns implementation status and sequencing until the decision is
|
||||||
owns implementation status and sequencing until the decision is implemented.
|
implemented. Current architecture, user, operator, integration, and internal
|
||||||
Current architecture, user, operator,
|
documentation are updated when the behavior lands.
|
||||||
integration, and internal documentation are updated when the behavior lands.
|
|
||||||
|
|
||||||
### Audience And Detail
|
### Audience And Detail
|
||||||
|
|
||||||
Write for the document's stated audience and include only the detail needed for
|
Write for the document's stated audience and include only the detail needed for
|
||||||
its owned topic. User and operator docs should not expose implementation detail.
|
its owned topic. Keep user and operator docs focused on using and operating the
|
||||||
Developer docs should link to user-facing and external contracts rather than
|
application. Developer docs should link to user-facing and external contracts
|
||||||
restate them.
|
for their definitions.
|
||||||
|
|
||||||
### Examples
|
### Examples
|
||||||
|
|
||||||
Complete copyable files belong in `examples/`. Documentation may use the
|
Complete copyable files belong in `examples/`. Documentation may use the
|
||||||
smallest illustrative snippet needed to explain its owned topic, but should link
|
smallest illustrative snippet needed to explain its owned topic, but should link
|
||||||
to maintained examples instead of embedding a second complete copy.
|
to maintained examples for complete copyable files.
|
||||||
|
|
||||||
Examples must be valid, secret-free, and tested where practical. Commands and
|
Examples must be valid, secret-free, and tested where practical. Commands and
|
||||||
configuration used in documentation should match the application.
|
configuration used in documentation should match the application.
|
||||||
@@ -71,43 +65,42 @@ secret values.
|
|||||||
|
|
||||||
| Topic | Canonical owner | Owned content | Content owned elsewhere |
|
| Topic | Canonical owner | Owned content | Content owned elsewhere |
|
||||||
| --- | --- | --- | --- |
|
| --- | --- | --- | --- |
|
||||||
| Product orientation and minimal end-to-end quickstart | `README.md` | What this project is, why it is useful, one shortest successful invocation, and links onward, including license and attribution navigation. | Complete command reference, configuration reference, operational procedures, implementation detail. |
|
| Product orientation and minimal end-to-end quickstart | `README.md` | Purpose, value, shortest successful invocation, and navigation, including licensing and attribution. | Complete command reference, configuration reference, operational procedures, implementation detail. |
|
||||||
| Contributor entry point | `docs/development.md` | Task-oriented reading guide, minimal contributor orientation, baseline validation commands, and links to canonical docs. | Package inventory, architecture rules, subsystem behavior, and detailed change recipes, which belong in the relevant internal component document. |
|
| Contributor entry point | `docs/development.md` | Task-oriented reading guide, contributor orientation, baseline validation commands, and canonical links. | Package inventory, architecture rules, subsystem behavior, detailed change recipes. |
|
||||||
| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, architectural boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
|
| Application architecture policy | `docs/policy/architecture.md` | System shape, normative ownership, dependency direction, boundaries, invariants, safety properties, and non-goals. | Concrete package inventory, implementation mechanics, contributor procedures, decision history, future work. |
|
||||||
| Agent policy | `docs/policy/agents.md` | Agent implementation discipline, proportionality, idiomatic simplicity, local commit rules, and rules against inventing requirements, restrictions, guarantees, or repository policy. | Application contracts, architecture, testing policy, and contributor procedures. |
|
| Policy-set provenance and upstream navigation | `docs/policy/meta.md` | Policy-set origin, local authority, adoption baselines, and upstream adoption and update links. | Task-specific reading triggers, detailed adoption procedures, and formal attribution notices. |
|
||||||
| Documentation organization | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
|
| Agent policy | `docs/policy/agents.md` | Proportionate, idiomatic implementation; rules against inventing requirements, restrictions, guarantees, or policy. | Application contracts, architecture, testing policy, and contributor procedures. |
|
||||||
| Testing policy | `docs/policy/testing.md` | Test philosophy, risk-based sufficiency, test boundaries, doubles, coverage guidance, regression-test policy, and criteria for adding, rewriting, or deleting tests. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
|
| Documentation policy | `docs/policy/documentation.md` | Documentation ownership, audience boundaries, maintenance rules, and ADR/document lifecycle. | Application architecture or product behavior. |
|
||||||
|
| Testing policy | `docs/policy/testing.md` | Test philosophy, risk sufficiency, boundaries, doubles, coverage, regressions, and test maintenance. | Subsystem behavior, application contracts, subsystem-specific test inventories, and implementation plans. |
|
||||||
|
| Release policy | `docs/policy/release.md` | Versioning, compatibility, release integrity and immutability, release documentation, proportionate gates, publication controls, completion, and required versus optional checks. | Repository-specific commands, product installation guidance, CLI version semantics, historical release summaries, and CI implementation detail. |
|
||||||
|
| Open source licensing and attribution policy | `docs/policy/oss.md` | License defaults and author choices, COPYRIGHT and attribution formats, license/notice links, discoverability, maintenance, and concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
|
||||||
|
| Project copyright and license grant | `COPYRIGHT` | Project identity, copyright holders and years, SPDX expression, grant, warranty disclaimer, and third-party statement. | Complete license texts and upstream component attribution. |
|
||||||
|
| Project license texts | `LICENSE` | Complete project and incorporated companion license texts, with required project-specific fields. | General licensing policy and upstream component attribution. |
|
||||||
|
| Upstream component attribution | `docs/oss/attribution.md` | House Format component entries: identity, material scope and modifications where applicable, copyright, license, required notices, and license, notice, and source links. | General attribution policy, exception reasoning, research narratives, compliance commentary, and complete standard license texts. |
|
||||||
|
| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by applicable entries. | Project-specific upstream notices, attribution prose, and policy interpretation. |
|
||||||
|
| Repository-specific release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, validation and publication commands and automated guards, asynchronous deliverables, delivery status, optional consumer verification, and recovery. | General release requirements, product installation guidance, historical release summaries, and current compatibility contracts. |
|
||||||
| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
|
| CLI contract | `docs/cli.md` | Commands, arguments, flags, invocation semantics, and exit codes. | End-to-end operating procedures, configuration field definitions, runtime filesystem layout, module implementation details. |
|
||||||
| Configuration contract | `docs/config.md` | Application discovery and precedence, source locations, server fields, render default, HTTP limits, and credential mapping. | Promptkit framework formats and defaults, complete example files, CLI syntax, runtime lifecycle, and implementation detail. |
|
| Configuration contract | `docs/config.md` | Application configuration discovery, precedence, schema, fields, defaults, environment overrides, validation, and selectable module and validator keys. | PromptKit framework formats and defaults, complete example files, CLI syntax, runtime state lifecycle, module implementation details. |
|
||||||
| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache, and debug handling, resume, cleanup, permissions, recovery, and operational limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
|
| Operations | `docs/operations.md` | Runtime workflows, physical filesystem and state layout, output, cache and debug handling, resume, cleanup, permissions, recovery, and limits. | CLI flag syntax, configuration field definitions, logical output schemas, implementation mechanics. |
|
||||||
| Release policy | `docs/policy/release.md` | Versioning and compatibility, release integrity and immutability, documentation requirements, proportionate gates, publication controls, source completion, and optional verification boundaries. | Repository-specific commands, installation guidance, historical summaries, and CI implementation details. |
|
|
||||||
| Release procedure | `docs/release.md` | Maintainer prerequisites, candidate preparation, publication command and guards, asynchronous delivery, optional diagnostics, and failure recovery. | General release requirements, runtime operations, historical announcements, and current application contracts. |
|
|
||||||
| Version-specific release notes | `docs/releases/` | Immutable release summaries, compatibility notices, and migration announcements for one published version. | Complete CLI, HTTP, configuration, operations, or dependency contracts. |
|
|
||||||
| Open source licensing and attribution policy | `docs/policy/oss.md` | House attribution format, license-text and notice-link conventions, discoverability, maintenance, and handling of concrete exceptions. | Component entries, license texts, release commands, and dependency security review. |
|
|
||||||
| Project license | `LICENSE` | The project's own license terms. | Upstream component attribution and dependency license texts. |
|
|
||||||
| Upstream component attribution | `docs/oss/attribution.md` | Component names, copyright statements, license identification, and license, notice, and source links. | General attribution policy and complete standard license texts. |
|
|
||||||
| Standard dependency license texts | `docs/oss/licenses/` | Complete, verbatim standard license texts shared by attribution entries where applicable. | Project-specific upstream notices, attribution prose, and policy interpretation. |
|
|
||||||
| Public HTTP contract | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
|
| Public HTTP contract | `docs/api.md` | Routes, authentication, media types, request and response schemas, status codes, pagination, caching, idempotency, rate limits, and HTTP retry semantics. | Client walkthroughs, upstream or downstream integration internals, implementation detail. |
|
||||||
| Consumer guidance | `docs/consumers/` | Choosing between Scriptorium's executable interfaces and understanding consumer responsibilities. | HTTP wire semantics, CLI syntax, Promptkit's Go package, and internal implementation detail. |
|
| Consumer guidance for executable use and migration | `docs/consumers/` | Task-oriented executable use, migration to PromptKit, minimal examples, and consumer responsibilities. | HTTP wire semantics, CLI syntax, PromptKit's public Go API, external protocol contracts, internal implementation detail. |
|
||||||
| External and durable integration contracts | `docs/integrations/` | Scriptorium-owned process and executable integration contracts. | Promptkit framework formats and outbound provider protocols, physical runtime placement, internal transformations, CLI syntax, and configuration defaults. |
|
| Scriptorium-owned integration contracts | `docs/integrations/` | Scriptorium-owned executable and process contracts, logical output paths and schemas, media types, and compatibility. | PromptKit framework formats and outbound provider protocols, physical runtime placement and lifecycle, internal transformations, CLI syntax, configuration defaults. |
|
||||||
| Implemented component inventory | `docs/internal/overview.md` | Current packages and components, their implemented responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
|
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
|
||||||
| Internal component behavior | Other files under `docs/internal/` | Implementation flow, internal collaborators and state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
|
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
|
||||||
| Architectural decision history | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
|
| Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. |
|
||||||
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status; sequencing; and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
|
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
|
||||||
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other files intended to be copied or run. | Field-by-field reference, command reference, prose explanation. |
|
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
|
||||||
|
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
|
||||||
|
|
||||||
Documents that do not exist are required only when the corresponding interface
|
Create supporting documents for existing interfaces and responsibilities when
|
||||||
or responsibility exists. Do not create placeholder API, consumer, integration,
|
substantive content is available.
|
||||||
or operations documents for behavior the application does not have.
|
|
||||||
|
|
||||||
## Boundary Rules
|
## Boundary Rules
|
||||||
|
|
||||||
### Orientation
|
### Orientation
|
||||||
|
|
||||||
The README owns product orientation. The developer guide routes contributors.
|
Link among orientation, architecture, and internal documents; maintain each
|
||||||
Architecture owns normative structure. Internal overview owns the current
|
package or behavior description in its canonical owner.
|
||||||
concrete component map. These documents may link to one another but should not
|
|
||||||
maintain parallel package or behavior descriptions.
|
|
||||||
|
|
||||||
### Commands, Configuration, And Operations
|
### Commands, Configuration, And Operations
|
||||||
|
|
||||||
@@ -119,26 +112,25 @@ other contracts.
|
|||||||
|
|
||||||
### Releases
|
### Releases
|
||||||
|
|
||||||
The release policy owns release requirements; the release procedure supplies
|
The release policy defines requirements and invariants that every release must
|
||||||
the commands that satisfy them. Release notes are historical summaries, not
|
satisfy. The repository-specific release procedure defines the commands and
|
||||||
current-state contract owners. The checked-in note at an immutable tag records
|
workflow maintainers use to satisfy that policy. Release notes record history
|
||||||
that release; current documentation changes with the behavior it describes.
|
at immutable tags. Maintain current behavior in its canonical documentation,
|
||||||
Neither a procedure nor a note may weaken policy or defer required updates to
|
update it with the corresponding behavior changes, and keep release procedures
|
||||||
canonical contracts.
|
consistent with adopted policy.
|
||||||
|
|
||||||
### Open Source Attribution
|
### Project Licensing And Upstream Attribution
|
||||||
|
|
||||||
The [OSS policy](oss.md) defines the House Format and README and release-link
|
README and release documents link to the canonical licensing and attribution
|
||||||
conventions. Attribution entries own component-specific information. README
|
materials under the [OSS policy](oss.md). The release procedure owns URL
|
||||||
and release documents provide navigation to those canonical materials; the
|
construction and publication mechanics.
|
||||||
release procedure owns URL construction and publication mechanics.
|
|
||||||
|
|
||||||
### Contracts And Implementation
|
### Contracts And Implementation
|
||||||
|
|
||||||
Integration and API documents define externally observable shapes and
|
Integration and API documents define externally observable shapes and
|
||||||
semantics. Internal documents explain how this project implements or consumes
|
semantics. Internal documents explain how this application implements or consumes those
|
||||||
those contracts. Internal docs may name a field, file, or protocol to identify
|
contracts. Internal docs may name a field, file, or protocol to identify a
|
||||||
a dependency, but must link to its canonical contract for the definition.
|
dependency, but must link to its canonical contract for the definition.
|
||||||
|
|
||||||
### Security Topics
|
### Security Topics
|
||||||
|
|
||||||
@@ -160,31 +152,20 @@ Use sequentially numbered ADR filenames such as
|
|||||||
6. alternatives considered;
|
6. alternatives considered;
|
||||||
7. consequences.
|
7. consequences.
|
||||||
|
|
||||||
Use one of these statuses:
|
Treat the decision content of an accepted ADR as immutable. When a decision
|
||||||
|
changes, create a new ADR and update the earlier ADR's status to superseded.
|
||||||
|
|
||||||
- **Proposed:** the decision is under consideration and may change;
|
ADRs should be reserved for major architectural decisions, such as ownership
|
||||||
- **Accepted:** the decision is approved, whether or not implementation is
|
boundaries, large-scale architectural features, or invariants that rise to
|
||||||
complete;
|
the level of architectural significance. Routine choices, implementation
|
||||||
- **Rejected:** the proposed decision was considered and not adopted;
|
decisions, and rejected suggestions do not warrant an ADR unless they
|
||||||
- **Superseded:** a later ADR replaces the accepted decision.
|
otherwise represent a significant architectural decision.
|
||||||
|
|
||||||
A proposed ADR transitions to accepted or rejected. An accepted ADR transitions
|
Roadmaps should preserve plausible future work, not rejected product
|
||||||
to superseded only when a later accepted ADR replaces it. An ADR may be created
|
ideas.
|
||||||
as accepted when the decision has already been made.
|
|
||||||
|
|
||||||
Treat the decision content of an accepted ADR as immutable. Its status and
|
|
||||||
supersession metadata may be updated, but a changed decision requires a new ADR.
|
|
||||||
A superseded ADR must link to its replacement, and the replacement must link
|
|
||||||
back to the superseded ADR. Rejected architectural alternatives belong in the
|
|
||||||
ADR; rejected product ideas belong in the roadmap.
|
|
||||||
|
|
||||||
## Maintenance
|
## Maintenance
|
||||||
|
|
||||||
Every policy document records its underlying template version and local
|
|
||||||
last-updated date immediately below the title. Update the date when revising
|
|
||||||
local policy; change the base version only when adopting a newer template.
|
|
||||||
Do not retain template adoption instructions in the local policy.
|
|
||||||
|
|
||||||
When behavior changes, update its canonical owner in the same change. If
|
When behavior changes, update its canonical owner in the same change. If
|
||||||
ownership moves, remove the old definition and replace it with a link where
|
ownership moves, remove the old definition and replace it with a link where
|
||||||
navigation remains useful.
|
navigation remains useful.
|
||||||
|
|||||||
27
docs/policy/meta.md
Normal file
27
docs/policy/meta.md
Normal file
@@ -0,0 +1,27 @@
|
|||||||
|
# Policy Set Provenance
|
||||||
|
|
||||||
|
**Base Policy Version:** 1.0
|
||||||
|
|
||||||
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/meta.md
|
||||||
|
|
||||||
|
## Origin And Local Authority
|
||||||
|
|
||||||
|
This repository's policy set is adapted from
|
||||||
|
[Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
|
||||||
|
The adopted local policies govern work in this repository. Upstream revisions
|
||||||
|
become local policy through deliberate adoption, preserving local decisions.
|
||||||
|
Each policy's `Upstream Source` identifies its adopted baseline.
|
||||||
|
|
||||||
|
## Adoption And Updates
|
||||||
|
|
||||||
|
For policy adoption, upstream revision reviews, and updates, consult the
|
||||||
|
[upstream adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
|
||||||
|
That guide and the reference example collection are maintained upstream and
|
||||||
|
accessed through links. Keep discovery links pointed at the current upstream
|
||||||
|
project and guide; keep adopted-source and example links pinned to commits.
|
||||||
|
|
||||||
|
The local [developer guide](../development.md) routes tasks to applicable
|
||||||
|
policies. Formal credit and licensing notices for the copied policy material
|
||||||
|
belong in the local [attribution document](../oss/attribution.md).
|
||||||
@@ -1,81 +1,153 @@
|
|||||||
# Open Source Licensing And Attribution Policy
|
# Open Source Licensing And Attribution Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.1
|
**Base Policy Version:** 1.9
|
||||||
|
|
||||||
**Last Updated:** 2026-09-26
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md
|
||||||
|
|
||||||
## Purpose And Scope
|
## Purpose And Scope
|
||||||
|
|
||||||
This policy establishes a repeatable House Format for open source attribution
|
This policy defines project licensing conventions and a repeatable House Format
|
||||||
and license notices. It covers upstream components incorporated into or
|
for upstream attribution and license notices. It covers the project's own code
|
||||||
distributed with the project, including relevant transitive dependencies and
|
and upstream components incorporated into or distributed with the application
|
||||||
copied code or assets. Treatment follows the component's terms and actual use,
|
or library, including relevant transitive dependencies and copied code,
|
||||||
rather than its classification as a direct dependency.
|
documentation, or assets.
|
||||||
|
Determine treatment from the component's terms and actual use.
|
||||||
|
|
||||||
|
Consulting development guidance or using tooling alone does not require an
|
||||||
|
attribution entry. Copying or adapting documentation for inclusion in the
|
||||||
|
repository is different: preserve its applicable attribution and license terms.
|
||||||
|
A material's role as development guidance does not exempt copied documents.
|
||||||
|
Apply any express permissions for attribution-free reuse of example formatting.
|
||||||
|
|
||||||
The baseline is a publicly available source repository with releases published
|
The baseline is a publicly available source repository with releases published
|
||||||
alongside it. The format is independent of language, forge, and build system.
|
alongside it. The format is independent of language, forge, and build system.
|
||||||
It does not require attribution for every development tool, establish license
|
It does not require attribution for every development tool, establish license
|
||||||
compatibility, or resolve obligations beyond attribution and notice handling.
|
compatibility, or resolve every obligation arising from use or distribution.
|
||||||
|
|
||||||
## Canonical Locations
|
## Canonical Locations
|
||||||
|
|
||||||
The [documentation policy](documentation.md) assigns ownership:
|
The [documentation policy](documentation.md) assigns ownership:
|
||||||
|
|
||||||
- `LICENSE` contains the project's own license. Dependency attribution does
|
- `COPYRIGHT`: project name, copyright statements, SPDX expression, grant,
|
||||||
not relicense the project.
|
warranty disclaimer, and third-party statement.
|
||||||
- `docs/oss/attribution.md` contains the canonical component entries.
|
- `LICENSE` contains the complete, unmodified project license text, including
|
||||||
- `docs/oss/licenses/` contains complete, verbatim standard license texts,
|
incorporated companion text. Dependency attribution does not relicense the project.
|
||||||
including companion texts where applicable.
|
- `docs/oss/attribution.md`: canonical component entries.
|
||||||
|
- `docs/oss/licenses/`: complete, verbatim standard and applicable companion texts.
|
||||||
|
|
||||||
Use recognizable license filenames, such as `Apache-2.0.txt` or `LGPL-3.0.txt`.
|
Use recognizable license filenames, such as `Apache-2.0.txt` or `LGPL-3.0.txt`.
|
||||||
A shared standard text may serve multiple entries. Keep explanations outside
|
A shared standard text may serve multiple entries. Keep explanations outside
|
||||||
license texts and preserve distinct versions and exceptions.
|
license texts and preserve distinct versions and exceptions.
|
||||||
|
|
||||||
## House Format
|
## Upstream Reference Examples
|
||||||
|
|
||||||
Each component entry has five fields:
|
Use the commit-pinned upstream examples to create actual project notices.
|
||||||
|
Retain their links and keep the example collection upstream; keep applicable
|
||||||
|
license texts locally as specified above.
|
||||||
|
|
||||||
1. **Project name**, normally as the entry heading.
|
## Project Licensing
|
||||||
|
|
||||||
|
Unless the author specifies otherwise, use **GPL version 3 or later**
|
||||||
|
(`GPL-3.0-or-later`) for applications and **LGPL version 3 or later**
|
||||||
|
(`LGPL-3.0-or-later`) for libraries. An author's explicit choice takes precedence:
|
||||||
|
for example, a one-off script may use MIT. Such a choice requires no exception
|
||||||
|
rationale, additional approval, or compensating controls under this policy.
|
||||||
|
|
||||||
|
These defaults guide new license selection. Adopting this policy does not
|
||||||
|
relicense existing code or override third-party terms. Preserve an existing
|
||||||
|
license unless the author deliberately changes it. For mixed-purpose projects,
|
||||||
|
follow the author's selected scope rather than inferring different licenses for
|
||||||
|
individual packages.
|
||||||
|
|
||||||
|
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
|
||||||
|
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
|
||||||
|
to create the project’s root `COPYRIGHT` file.
|
||||||
|
Use the COPYRIGHT examples exactly as provided, except for placeholder
|
||||||
|
substitutions and changes expressly required or authorized by this policy or
|
||||||
|
the author.
|
||||||
|
Use verified project names, contribution years, and copyright holders.
|
||||||
|
For another selected license, adapt the grant, SPDX expression, disclaimer, and
|
||||||
|
text references together to reflect the author's selected grant.
|
||||||
|
|
||||||
|
For GPLv3 projects, copy the complete GPLv3 text into `LICENSE`. For LGPLv3
|
||||||
|
projects, place the complete LGPLv3 text followed by the complete GPLv3 text in
|
||||||
|
`LICENSE`; the LGPL incorporates the GPL terms. Keep the texts unmodified and
|
||||||
|
place project-specific statements in `COPYRIGHT`. For the default grants, the
|
||||||
|
grant and SPDX expression in `COPYRIGHT` must expressly identify `or-later`;
|
||||||
|
follow the author’s choice if a different grant is selected.
|
||||||
|
|
||||||
|
For other licenses, provide their complete text and any required project-specific
|
||||||
|
fields; the standard reference collection remains unchanged. Keep `COPYRIGHT`,
|
||||||
|
`LICENSE`, SPDX expressions, and README descriptions consistent with the actual
|
||||||
|
grant. This convention introduces no blanket requirement for per-file headers;
|
||||||
|
preserve notices or add them where the applicable terms require them.
|
||||||
|
|
||||||
|
Identify separately licensed documentation or assets in the project grant, with
|
||||||
|
links to their attribution and license information. An application's default
|
||||||
|
code license does not override the terms of incorporated documentation.
|
||||||
|
|
||||||
|
## Upstream Attribution House Format
|
||||||
|
|
||||||
|
Begin `docs/oss/attribution.md` with `# Open Source Attribution Notices`,
|
||||||
|
followed directly by component entries. These comprise the complete document.
|
||||||
|
|
||||||
|
Each entry presents these five fields in order, with blank lines between them:
|
||||||
|
|
||||||
|
1. **Project name** as a level-two heading. An optional identification paragraph
|
||||||
|
may follow, such as `Selected module: MODULE at VERSION.` with the module and
|
||||||
|
version in backticks. For copied documentation, a concise `Material:` sentence
|
||||||
|
may identify the affected files and whether they were adapted or copied
|
||||||
|
without modification. A factual qualifier such as `(transitive dependency)`
|
||||||
|
is permitted. Limit optional identification prose to factual component and
|
||||||
|
material scope.
|
||||||
2. **Upstream copyright statement or statements**, preserving their wording.
|
2. **Upstream copyright statement or statements**, preserving their wording.
|
||||||
3. **SPDX license identifier or expression**, when applicable.
|
Put multiple statements in separate paragraphs. Include this field when the
|
||||||
4. **License and notice links**, covering the applicable standard texts and
|
selected upstream source supplies an applicable statement; otherwise, omit it.
|
||||||
upstream project-specific material.
|
3. **SPDX license identifier or expression**, when applicable, using
|
||||||
5. **Source repository link**, identifying the source corresponding to the
|
`SPDX-License-Identifier: EXPRESSION`.
|
||||||
imported version.
|
4. **License and notice links**, beginning `License and notices:`, separated
|
||||||
|
by ` | `, and ending with a period. Label local standard texts by license
|
||||||
|
name, such as `MIT` or `Apache 2.0`. Label upstream files by their actual
|
||||||
|
filenames, such as `COPYRIGHT`, `LICENSE`, `NOTICE`, or `PATENTS`.
|
||||||
|
5. **Source repository link**, rendered exactly as `[Source](COMMIT_URL).`.
|
||||||
|
|
||||||
Illustrative Markdown, with placeholders for the actual upstream information:
|
Use the upstream [attribution example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/attribution.md)
|
||||||
|
to create the project’s `docs/oss/attribution.md`.
|
||||||
|
The example illustrates omitted fields and multiple copyrights and licenses.
|
||||||
|
Replace the uppercase placeholders and illustrative URLs with actual component
|
||||||
|
information. Local license links are relative to the destination
|
||||||
|
`docs/oss/attribution.md`; copy the applicable texts into its `licenses/`
|
||||||
|
directory. Do not copy example entries for components the project does not use.
|
||||||
|
|
||||||
```markdown
|
These are five fields, not a line limit. Omit the SPDX field when no applicable
|
||||||
## Example Library
|
identifier exists; identify nonstandard terms through the linked text. Preserve
|
||||||
|
licensing alternatives and exceptions, and record a selected option when
|
||||||
|
relevant through the factual license identification. Do not invent an identifier
|
||||||
|
or silently resolve an unsettled licensing choice.
|
||||||
|
|
||||||
Copyright <upstream copyright statement>
|
Keep entries factual. Do not add agent-authored explanations of license
|
||||||
|
expressions, file-level license scope, research performed, retained source
|
||||||
SPDX-License-Identifier: Apache-2.0
|
notices, or compliance conclusions. Avoid filler such as "none is invented
|
||||||
|
here" and embellished link labels such as "upstream LICENSE", "additional
|
||||||
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) | [NOTICE](<upstream NOTICE URL at the imported commit>)
|
patent grant", or "at the imported commit". Preserve actual required upstream
|
||||||
|
content; this rule excludes editorial additions, not required notices. Policy
|
||||||
Source: [Example Library](<upstream repository URL at the imported commit>)
|
interpretation and exception reasoning belong in the adopted OSS policy or an
|
||||||
```
|
appropriate decision record, not the attribution document.
|
||||||
|
|
||||||
These are five fields, not a line limit. Include multiple statements and links
|
|
||||||
where needed. Omit the SPDX field when no applicable identifier exists; identify
|
|
||||||
nonstandard terms accurately through the linked text. Preserve licensing
|
|
||||||
alternatives and exceptions, and record a selected option when relevant. Do not
|
|
||||||
invent an identifier or silently resolve an unsettled licensing choice.
|
|
||||||
|
|
||||||
## License Texts And Upstream Links
|
## License Texts And Upstream Links
|
||||||
|
|
||||||
Link standard license texts to their local copies. Link project-specific
|
Link standard license texts to their local copies. Link project-specific
|
||||||
notices to the upstream copies instead of storing them locally. Every upstream
|
notices to their upstream copies. Every upstream repository or notice link must
|
||||||
repository or notice link must identify the exact commit corresponding to the
|
identify the exact commit corresponding to the
|
||||||
imported version, including the selected source revision for copied material.
|
imported version, including the selected source revision for copied material.
|
||||||
Do not use moving branches or version tags as substitutes for that commit.
|
|
||||||
|
|
||||||
Classify material by its contents, not its filename. An upstream `LICENSE`,
|
Classify material according to its contents. An upstream `LICENSE`,
|
||||||
`COPYING`, or similar file may contain project-specific notices or exceptions
|
`COPYING`, or similar file may contain project-specific notices or exceptions
|
||||||
in addition to standard wording. Link both the local standard text and the
|
in addition to standard wording. Link both the local standard text and the
|
||||||
commit-specific upstream file when needed. Make companion license texts directly
|
commit-specific upstream file when needed. Make companion license texts directly
|
||||||
reachable from the entry rather than leaving readers to infer their location.
|
reachable from the entry.
|
||||||
|
|
||||||
For project-specific license and attribution material, this policy accepts
|
For project-specific license and attribution material, this policy accepts
|
||||||
direct links to the applicable upstream texts as satisfying reproduction,
|
direct links to the applicable upstream texts as satisfying reproduction,
|
||||||
@@ -91,17 +163,18 @@ source files; the central attribution entry does not authorize stripping them.
|
|||||||
## Discoverability
|
## Discoverability
|
||||||
|
|
||||||
End the project's README with two friendly statements linking to its actual
|
End the project's README with two friendly statements linking to its actual
|
||||||
license and the attribution document. For Scriptorium:
|
grant in `COPYRIGHT` and the attribution document. For example, for a project
|
||||||
|
with the stated license:
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
Scriptorium is licensed under the [BSD 3-Clause License](LICENSE).
|
Scriptorium is licensed under the [GPL v3.0 or later](COPYRIGHT).
|
||||||
|
|
||||||
[Open Source attribution notices](docs/oss/attribution.md) are available.
|
[Open Source attribution notices](docs/oss/attribution.md) are available.
|
||||||
```
|
```
|
||||||
|
|
||||||
Each new checked-in release document and its hosted download page must end
|
Each new checked-in release document and its hosted download page must end
|
||||||
with links whose visible text is `LICENSE | ATTRIBUTION`. Use absolute URLs to
|
with links whose visible text is `COPYRIGHT | LICENSE | ATTRIBUTION`. Use absolute
|
||||||
those files at the release's immutable tag or corresponding immutable source
|
URLs to those files at the release's immutable tag or corresponding immutable source
|
||||||
revision so the links work in both locations. This release navigation is distinct
|
revision so the links work in both locations. This release navigation is distinct
|
||||||
from upstream component links, which must use the imported commit.
|
from upstream component links, which must use the imported commit.
|
||||||
|
|
||||||
@@ -113,8 +186,9 @@ assets, source bundles, or a different binary package format.
|
|||||||
|
|
||||||
## Maintenance And Exceptions
|
## Maintenance And Exceptions
|
||||||
|
|
||||||
Update notices in the change that adds, removes, upgrades, copies, or changes
|
Update project licensing statements together when the author changes the grant
|
||||||
the distribution of a relevant component. Check the selected source's license
|
or its scope. Update upstream notices in the change that adds, removes, upgrades,
|
||||||
|
copies, or changes the distribution of a relevant component. Check the selected source's license
|
||||||
and notices rather than assuming they are unchanged. Update affected entries,
|
and notices rather than assuming they are unchanged. Update affected entries,
|
||||||
commit links, and texts; retain historical versions through Git.
|
commit links, and texts; retain historical versions through Git.
|
||||||
|
|
||||||
@@ -128,8 +202,10 @@ to implement this policy.
|
|||||||
Use the House Format routinely. Raise an exception only for a concrete obligation
|
Use the House Format routinely. Raise an exception only for a concrete obligation
|
||||||
or unresolved rights question it does not address, including any arising from a
|
or unresolved rights question it does not address, including any arising from a
|
||||||
particular distribution channel. Record the issue and selected treatment in the
|
particular distribution channel. Record the issue and selected treatment in the
|
||||||
adopted policy or affected attribution entry as appropriate. Resolve the issue
|
adopted OSS policy or an appropriate decision record. Attribution entries
|
||||||
before the affected use or distribution without reopening settled choices.
|
contain the resulting factual identification and required material, without
|
||||||
|
repeating that reasoning. Resolve the issue before the affected use or
|
||||||
|
distribution without reopening settled choices.
|
||||||
Common ownership of projects is neither required nor a blanket exception.
|
Common ownership of projects is neither required nor a blanket exception.
|
||||||
|
|
||||||
Apply the formatting convention prospectively. Do not rewrite published tags,
|
Apply the formatting convention prospectively. Do not rewrite published tags,
|
||||||
|
|||||||
@@ -1,8 +1,10 @@
|
|||||||
# Release Policy
|
# Release Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.2
|
**Base Policy Version:** 1.7
|
||||||
|
|
||||||
**Last Updated:** 2026-09-26
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
@@ -10,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
|
|||||||
intended source revision under a fresh version. Releases should require little
|
intended source revision under a fresh version. Releases should require little
|
||||||
routine intervention, avoid repeated work, and preserve published contents.
|
routine intervention, avoid repeated work, and preserve published contents.
|
||||||
|
|
||||||
|
Adopt stronger verification or reproducibility requirements through an explicit
|
||||||
|
project-specific decision justified by the intended audience and support needs.
|
||||||
|
|
||||||
The repository-specific commands belong in `docs/release.md`. Historical release
|
The repository-specific commands belong in `docs/release.md`. Historical release
|
||||||
summaries belong in `docs/releases/`. The procedure must agree with the adopted
|
summaries belong in `docs/releases/`. The procedure must agree with the adopted
|
||||||
policy and link to it rather than introduce additional release requirements.
|
policy and link to it rather than introduce additional release requirements.
|
||||||
@@ -18,14 +23,13 @@ policy and link to it rather than introduce additional release requirements.
|
|||||||
|
|
||||||
A source release identifies one exact committed source revision through an
|
A source release identifies one exact committed source revision through an
|
||||||
immutable version tag and a version-matched, checked-in release note. The
|
immutable version tag and a version-matched, checked-in release note. The
|
||||||
primary release branch is `main`; the authoritative publication remote is
|
primary release branch is `main` unless the adopted policy specifies otherwise.
|
||||||
`origin`.
|
The procedure must name the authoritative publication remote.
|
||||||
|
|
||||||
A successful push of the intended tag, with its source commit available on the
|
A successful push of the intended tag, with its source commit available on the
|
||||||
authoritative primary branch, completes the release. Publish `main` before
|
authoritative primary branch, completes the release. The source commit may be
|
||||||
invoking the publication command; the command requires
|
pushed before the tag or published together with it through an atomic push.
|
||||||
that the remote branch exactly identifies the validated candidate and pushes
|
The procedure must choose and document the supported approach.
|
||||||
only the selected annotated tag.
|
|
||||||
|
|
||||||
Release commands must finish at successful publication. They must not wait for
|
Release commands must finish at successful publication. They must not wait for
|
||||||
or poll CI, require successful CI status, inspect downloadable artifacts, or
|
or poll CI, require successful CI status, inspect downloadable artifacts, or
|
||||||
@@ -34,19 +38,20 @@ A failed or ambiguous push requires resolving the authoritative remote state
|
|||||||
before declaring success or retrying; successful pushes do not require a
|
before declaring success or retrying; successful pushes do not require a
|
||||||
separate remote read-back gate.
|
separate remote read-back gate.
|
||||||
|
|
||||||
Scriptorium publishes Linux binaries and checksums asynchronously from the
|
Repositories may publish source only. Additional binaries, images, packages,
|
||||||
tagged source. The procedure must identify those deliverables and the
|
checksums, or other declared deliverables may be published asynchronously from
|
||||||
|
the tagged source. The procedure must identify those deliverables and the
|
||||||
responsibility of their automation. Published deliverables must be traceable
|
responsibility of their automation. Published deliverables must be traceable
|
||||||
to that source and identify the same version.
|
to that source and identify the same version.
|
||||||
|
|
||||||
Artifact delivery is a separate status. A successful tag push is not evidence
|
Track source-release completion and artifact delivery separately. Report delivery
|
||||||
that artifacts are available. Delivery failures do not reverse source-release
|
failures and optional investigations under artifact-delivery status.
|
||||||
success, and optional investigation must not delay release completion.
|
|
||||||
|
|
||||||
## Versioning And Compatibility
|
## Versioning And Compatibility
|
||||||
|
|
||||||
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
|
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
|
||||||
no leading zeroes. Prereleases are not part of the adopted release channel.
|
no leading zeroes. Prereleases require an explicit adopted policy defining
|
||||||
|
their format and use.
|
||||||
|
|
||||||
The selected version must be unused locally and on the authoritative remote.
|
The selected version must be unused locally and on the authoritative remote.
|
||||||
Do not require queries to every configured remote or publication service.
|
Do not require queries to every configured remote or publication service.
|
||||||
@@ -57,9 +62,14 @@ requires a deliberate update to the policy and procedure where needed.
|
|||||||
For releases at or after `v1.0.0`:
|
For releases at or after `v1.0.0`:
|
||||||
|
|
||||||
- a major release may make intentional incompatible changes;
|
- a major release may make intentional incompatible changes;
|
||||||
- a minor release may add backward-compatible behavior; and
|
- a minor release may add backward-compatible behavior or raise the Go consumer
|
||||||
|
minimum as described below; and
|
||||||
- a patch release may make backward-compatible fixes.
|
- a patch release may make backward-compatible fixes.
|
||||||
|
|
||||||
|
In this context, "backward-compatible" means only that pre-existing, valid
|
||||||
|
configurations will continue to work following the relase. Behavior need not
|
||||||
|
remain strictly identical.
|
||||||
|
|
||||||
Before `v1.0.0`, a minor release may change a documented public, operational,
|
Before `v1.0.0`, a minor release may change a documented public, operational,
|
||||||
configuration, data, integration, or compatibility contract when the release
|
configuration, data, integration, or compatibility contract when the release
|
||||||
note explains the impact and required consumer action. A patch release must
|
note explains the impact and required consumer action. A patch release must
|
||||||
@@ -69,6 +79,36 @@ Additional compatibility promises and deliberate exceptions belong in the
|
|||||||
adopted policy or canonical contract documentation. Release notes explain
|
adopted policy or canonical contract documentation. Release notes explain
|
||||||
changes; they do not redefine current compatibility contracts.
|
changes; they do not redefine current compatibility contracts.
|
||||||
|
|
||||||
|
## Consumer Minimum And Release Toolchain
|
||||||
|
|
||||||
|
Distinguish the minimum toolchain supported for consumers from the toolchain
|
||||||
|
maintainers use to build and validate a release. Record the consumer minimum in
|
||||||
|
the language's standard metadata and explain its support meaning in canonical
|
||||||
|
documentation. Define the selected release toolchain and its setup commands in
|
||||||
|
`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
|
||||||
|
choices.
|
||||||
|
|
||||||
|
For Go repositories, normally declare the initial stable release of the selected
|
||||||
|
series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
|
||||||
|
when a dependency or an identified correctness fix requires it, and document
|
||||||
|
the reason.
|
||||||
|
|
||||||
|
For release-policy purposes, successful build and release validation on the
|
||||||
|
selected Go patch release are sufficient to presume support across that Go
|
||||||
|
series, subject to the declared consumer minimum and concrete evidence of
|
||||||
|
incompatibility. Investigate specific compatibility concerns as they arise.
|
||||||
|
|
||||||
|
Use the selected release toolchain for candidate validation and release builds,
|
||||||
|
including CI jobs performing those tasks. A newer validation patch version alone
|
||||||
|
leaves the consumer minimum unchanged.
|
||||||
|
|
||||||
|
A minor release may raise the Go consumer minimum, including from one Go series
|
||||||
|
to the next, both before and after `v1.0.0`. This is an explicit exception to the
|
||||||
|
backward-compatibility requirement for minor releases. Patch releases preserve
|
||||||
|
the consumer minimum. Explain an increase's impact and required consumer action
|
||||||
|
in the release note. Other incompatible changes remain subject to the versioning
|
||||||
|
rules above.
|
||||||
|
|
||||||
## Release Documentation And Preparation
|
## Release Documentation And Preparation
|
||||||
|
|
||||||
Every new release must include `docs/releases/<version>.md` in the tagged
|
Every new release must include `docs/releases/<version>.md` in the tagged
|
||||||
@@ -76,9 +116,13 @@ source tree. Use the complete version tag as the filename and begin with a
|
|||||||
title containing the product name and that exact version.
|
title containing the product name and that exact version.
|
||||||
|
|
||||||
Include a short summary and any relevant compatibility impact or upgrade
|
Include a short summary and any relevant compatibility impact or upgrade
|
||||||
instructions. Keep the note proportionate to the change. Fixed sections and
|
instructions. Choose sections suited to the release and keep the note
|
||||||
explicit no-action boilerplate are not required. Existing historical notes
|
proportionate to the change.
|
||||||
need not be rewritten to adopt this format.
|
|
||||||
|
Keep exact current contracts in their canonical documents and update affected
|
||||||
|
documentation with the behavior change. Link to those documents from the note
|
||||||
|
where useful. If annotated tags are used, derive their summary from the
|
||||||
|
checked-in note.
|
||||||
|
|
||||||
Include the release footer defined by the [OSS policy](oss.md#discoverability)
|
Include the release footer defined by the [OSS policy](oss.md#discoverability)
|
||||||
in each new release document and preserve it on the hosted download page. The
|
in each new release document and preserve it on the hosted download page. The
|
||||||
@@ -86,18 +130,11 @@ release procedure defines the concrete URLs and publication mechanics. Prepare
|
|||||||
these links with the release note; they do not add a network check or approval
|
these links with the release note; they do not add a network check or approval
|
||||||
gate.
|
gate.
|
||||||
|
|
||||||
Keep exact current contracts in their canonical documents and update affected
|
Handle version selection, release-note content, and retirement of completed
|
||||||
documentation with the behavior change. Link to those documents from the note
|
roadmaps during preparation. Preserve planned and deferred work and repair
|
||||||
where useful. A release note must not substitute for current documentation.
|
affected links when retiring roadmaps. Reuse ordinary change review for
|
||||||
Use annotated tags with their message derived from the checked-in note rather
|
unintended files, credentials, and private data. Scope release-content review
|
||||||
than requiring a separately authored account of the same release.
|
to the tagged source.
|
||||||
|
|
||||||
Version selection, release-note content, and retirement of completed roadmaps
|
|
||||||
are preparation responsibilities, not separate human approval gates. Preserve
|
|
||||||
planned and deferred work and repair affected links when retiring roadmaps.
|
|
||||||
Ordinary change review covers unintended files, credentials, and private data;
|
|
||||||
do not repeat it as a release-specific sign-off. Ignored local files are not
|
|
||||||
prohibited merely because they exist: they are not included in the tagged source.
|
|
||||||
|
|
||||||
## Candidate Validation
|
## Candidate Validation
|
||||||
|
|
||||||
@@ -107,24 +144,10 @@ mode or command may be provided for diagnosis, but must not be a required step
|
|||||||
before publication repeats the same checks.
|
before publication repeats the same checks.
|
||||||
|
|
||||||
Run the complete deterministic, offline default test suite once for the final
|
Run the complete deterministic, offline default test suite once for the final
|
||||||
candidate, following the [testing policy](testing.md), and verify the required
|
candidate, following the [testing policy](testing.md). For repositories that
|
||||||
build targets. Select those targets for the application's actual support
|
publish builds, verify the required build targets. Select those targets for
|
||||||
commitments; native testing on each platform and access to particular hardware
|
the application's actual support commitments; native testing on each platform
|
||||||
are not default release prerequisites.
|
and access to particular hardware are not default release prerequisites.
|
||||||
|
|
||||||
The selected test invocation includes the race detector because the HTTP
|
|
||||||
service shares engines and backend capacity state across concurrent requests.
|
|
||||||
This single invocation covers both ordinary assertions and race detection.
|
|
||||||
Build both declared Linux architectures with the hosted release flags to catch
|
|
||||||
cross-compilation and packaging failures; native test hardware for each target
|
|
||||||
is not required. Existing architecture tests enforce dependency boundaries.
|
|
||||||
|
|
||||||
Retain narrow source guards against committed workspaces, vendor trees, and
|
|
||||||
module replacements: these can otherwise make a passing local build depend on
|
|
||||||
unpublished or substituted framework code. Disable workspace discovery and
|
|
||||||
vendor mode during validation. These guards preserve the established
|
|
||||||
cross-project boundary; they do not require exact dependency-version audits or
|
|
||||||
module-metadata rewrites at release time.
|
|
||||||
|
|
||||||
Additional gates must address a concrete risk that the existing checks do not
|
Additional gates must address a concrete risk that the existing checks do not
|
||||||
adequately cover. Do not automatically require linting, race testing, module
|
adequately cover. Do not automatically require linting, race testing, module
|
||||||
@@ -134,8 +157,8 @@ checks when their distinct protection justifies their cost. A one-time migration
|
|||||||
check must not silently become a permanent release requirement.
|
check must not silently become a permanent release requirement.
|
||||||
|
|
||||||
Release tests must not require real credentials, mutable application services,
|
Release tests must not require real credentials, mutable application services,
|
||||||
paid APIs, provider probes, or inference calls. The procedure describes
|
paid APIs, provider probes, or inference calls. The procedure may describe dependency
|
||||||
dependency preparation separately from offline validation.
|
preparation separately from offline validation.
|
||||||
|
|
||||||
Avoid duplicate validation across release phases. Successful checks for the
|
Avoid duplicate validation across release phases. Successful checks for the
|
||||||
same final candidate need not be repeated solely to satisfy another phase;
|
same final candidate need not be repeated solely to satisfy another phase;
|
||||||
@@ -158,7 +181,9 @@ Automate the checks needed to publish the intended source under a fresh version:
|
|||||||
- the worktree and index are clean on the primary release branch;
|
- the worktree and index are clean on the primary release branch;
|
||||||
- the source being published is the exact candidate that passed validation,
|
- the source being published is the exact candidate that passed validation,
|
||||||
including its matching release note;
|
including its matching release note;
|
||||||
- the remote primary branch already identifies that exact candidate; and
|
- the remote primary branch already identifies that candidate, or an atomic
|
||||||
|
source/tag push will advance it to that candidate without discarding remote
|
||||||
|
history; and
|
||||||
- the tag identifies the validated candidate and only the intended refs are
|
- the tag identifies the validated candidate and only the intended refs are
|
||||||
published.
|
published.
|
||||||
|
|
||||||
@@ -199,7 +224,8 @@ release without replacing its contents or reusing its version.
|
|||||||
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
|
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
|
||||||
identify:
|
identify:
|
||||||
|
|
||||||
1. prerequisites, primary branch, and authoritative remote;
|
1. prerequisites, selected release toolchain, primary branch, and authoritative
|
||||||
|
remote;
|
||||||
2. version and release-note preparation;
|
2. version and release-note preparation;
|
||||||
3. one publication command with its selected local checks and automated guards;
|
3. one publication command with its selected local checks and automated guards;
|
||||||
4. declared deliverables, required build targets, and automation responsibilities;
|
4. declared deliverables, required build targets, and automation responsibilities;
|
||||||
@@ -211,3 +237,27 @@ Use copyable commands where practical. Keep optional diagnostics and consumer
|
|||||||
verification clearly optional. The procedure must not turn preparation work,
|
verification clearly optional. The procedure must not turn preparation work,
|
||||||
ordinary change review, or post-publication investigation into additional
|
ordinary change review, or post-publication investigation into additional
|
||||||
release gates.
|
release gates.
|
||||||
|
|
||||||
|
## Scriptorium Release Selections
|
||||||
|
|
||||||
|
Scriptorium publishes stable releases from `main` through the authoritative
|
||||||
|
`origin` push endpoint. The validated candidate is published to the remote
|
||||||
|
branch before the annotated version tag; the publication command requires
|
||||||
|
exact agreement between the remote branch and candidate before pushing only
|
||||||
|
that tag. Atomic branch-and-tag publication and source-only delivery remain
|
||||||
|
general alternatives in this policy, not Scriptorium-supported workflows.
|
||||||
|
The tag message derives from the checked-in note. A successful tag push
|
||||||
|
completes the source release; binary delivery is asynchronous and does not
|
||||||
|
gate it.
|
||||||
|
|
||||||
|
The tagged source produces Linux amd64 and arm64 binaries and checksums through
|
||||||
|
the hosted workflow. Candidate validation runs the complete offline Go suite
|
||||||
|
once with the race detector because concurrent HTTP requests share engine and
|
||||||
|
backend capacity state. It builds both declared Linux targets. Narrow guards
|
||||||
|
reject committed workspaces, vendor trees, and module replacements so local
|
||||||
|
substitutions cannot mask unpublished framework code. These selected checks
|
||||||
|
address distinct application and release risks; no CI polling, artifact
|
||||||
|
availability, consumer installation, or new approval gate is required.
|
||||||
|
|
||||||
|
The [release procedure](../release.md) owns exact commands, targets, guards,
|
||||||
|
delivery reporting, and recovery steps.
|
||||||
|
|||||||
@@ -1,14 +1,16 @@
|
|||||||
# Testing Policy
|
# Testing Policy
|
||||||
|
|
||||||
**Base Policy Version:** 1.1
|
**Base Policy Version:** 1.3
|
||||||
|
|
||||||
**Last Updated:** 2026-09-26
|
**Last Updated**: 2026-11-17
|
||||||
|
|
||||||
|
**Upstream Source:** https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/testing.md
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
Our tests exist to make **incorrect changes expensive and correct changes cheap**.
|
Our tests exist to make **incorrect changes expensive and correct changes cheap**.
|
||||||
|
|
||||||
We do not optimize for test count, line coverage, exhaustive isolation, or the fewest possible tests. We optimize for sufficient confidence in important behavior while imposing as little unnecessary friction as possible on future development.
|
We optimize for sufficient confidence in important behavior while minimizing friction on future development.
|
||||||
|
|
||||||
## Every test has a cost
|
## Every test has a cost
|
||||||
|
|
||||||
@@ -22,9 +24,9 @@ Evaluate that tradeoff at two levels:
|
|||||||
1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost?
|
1. **Per test:** What realistic defect does this test detect, how consequential would that defect be, and is that protection worth the test's lifetime cost?
|
||||||
2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would?
|
2. **Across the suite:** Does this collection provide materially more confidence than a smaller, simpler suite would?
|
||||||
|
|
||||||
Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. They should not make ordinary internal changes needlessly expensive.
|
Some friction is intentional. Tests should make dangerous changes—such as breaking compatibility, corrupting data, violating security boundaries, or reintroducing subtle bugs—require deliberate review. Keep ordinary internal changes inexpensive.
|
||||||
|
|
||||||
The cost of a test is not a reason to omit testing by default. Do not cite maintenance cost abstractly. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing.
|
Evaluate maintenance cost against the specific failure being protected. When omitting a plausible test, be able to state why the protected failure is low-risk, already covered, obvious, reversible, or cheaper to detect elsewhere. For consequential, subtle, or difficult-to-observe behavior, the presumption should favor testing.
|
||||||
|
|
||||||
## Default testing style
|
## Default testing style
|
||||||
|
|
||||||
@@ -56,7 +58,7 @@ To the extent the following features are present in the application, prioritize
|
|||||||
6. Previously observed or plausible regressions.
|
6. Previously observed or plausible regressions.
|
||||||
7. Representative integration and end-to-end workflows.
|
7. Representative integration and end-to-end workflows.
|
||||||
|
|
||||||
A package-level contract is behavior relied upon by another package or major collaborator, not every observable detail of a package implementation.
|
A package-level contract comprises behavior relied upon by another package or major collaborator.
|
||||||
|
|
||||||
Choose tests for requested behavior and established contracts. Tests must not
|
Choose tests for requested behavior and established contracts. Tests must not
|
||||||
introduce new restrictions, guarantees, or threat scenarios merely because they
|
introduce new restrictions, guarantees, or threat scenarios merely because they
|
||||||
@@ -75,14 +77,8 @@ Do not add tests merely because a function, branch, or line exists. Do not add a
|
|||||||
|
|
||||||
## Choose the right test boundary
|
## Choose the right test boundary
|
||||||
|
|
||||||
Test through the narrowest stable boundary that expresses the behavior clearly.
|
Choose the narrowest stable boundary that expresses the behavior clearly and
|
||||||
|
provides durable confidence with minimal incidental coupling.
|
||||||
For application configuration, ConfigKit owns exhaustive YAML grammar,
|
|
||||||
source traversal, import/overlay composition, provenance, and inspection
|
|
||||||
renderer tests. Scriptorium tests its selected definition, source discovery,
|
|
||||||
CLI override presence, command prerequisites, runtime conversion, credential
|
|
||||||
boundary, and representative execution/inspection workflows with the tagged
|
|
||||||
library. Do not copy the upstream parser test matrix into this repository.
|
|
||||||
|
|
||||||
This is often the package API, but it may instead be:
|
This is often the package API, but it may instead be:
|
||||||
|
|
||||||
@@ -90,22 +86,15 @@ This is often the package API, but it may instead be:
|
|||||||
- a package-level operation when several internal collaborators jointly produce the behavior; or
|
- a package-level operation when several internal collaborators jointly produce the behavior; or
|
||||||
- a larger integration boundary when correctness emerges from interaction with a real dependency.
|
- a larger integration boundary when correctness emerges from interaction with a real dependency.
|
||||||
|
|
||||||
Do not force all behavior through oversized end-to-end tests. Do not test every private helper merely because it exists. Choose the boundary that gives durable confidence with the least incidental coupling.
|
|
||||||
|
|
||||||
## Test behavior, not implementation
|
## Test behavior, not implementation
|
||||||
|
|
||||||
A test should protect a decision, contract, or invariant. A test must not memorialize the current implementation.
|
A test should protect a selected decision, contract, or invariant.
|
||||||
|
|
||||||
A test is suspect when its main purpose is to detect that someone:
|
A test is suspect when it primarily detects changes to private constants or
|
||||||
|
helpers, equivalent operation ordering, incidental formatting, equivalent
|
||||||
|
algorithms, or internal structure that preserves behavior.
|
||||||
|
|
||||||
- changed an internal constant;
|
Behavioral tests should normally remain stable through internal refactoring that preserves the contract.
|
||||||
- renamed or split a private helper;
|
|
||||||
- reordered equivalent internal operations;
|
|
||||||
- changed incidental formatting;
|
|
||||||
- replaced one correct algorithm with another; or
|
|
||||||
- refactored internal object structure without changing behavior.
|
|
||||||
|
|
||||||
Refactoring should normally require no test edits unless the refactored structure is itself part of the contract.
|
|
||||||
|
|
||||||
## Expected effects of different changes
|
## Expected effects of different changes
|
||||||
|
|
||||||
@@ -122,7 +111,7 @@ A test failing is not the same as a test needing to be edited. Many tests may co
|
|||||||
|
|
||||||
## Separate mechanism from policy
|
## Separate mechanism from policy
|
||||||
|
|
||||||
Configurable thresholds and defaults must not be duplicated throughout the test suite.
|
Derive expectations from test-controlled configuration and relationships.
|
||||||
|
|
||||||
For this example, assume the selected contract rejects a request to start more
|
For this example, assume the selected contract rejects a request to start more
|
||||||
processes than a configured limit. Do not encode its production default indirectly:
|
processes than a configured limit. Do not encode its production default indirectly:
|
||||||
@@ -158,33 +147,52 @@ limit solely to reproduce this example.
|
|||||||
|
|
||||||
The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement.
|
The production default should be tested exactly only when its literal value is itself a public, operational, safety, protocol, or compatibility requirement.
|
||||||
|
|
||||||
Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior, not duplicated literals.
|
Apply the same rule to limits, timeouts, capacities, retry counts, and ranges: test relationships and behavior.
|
||||||
|
|
||||||
For established concurrency limits, distinguish these behaviors where the contract requires them:
|
For established concurrency limits, distinguish these behaviors where the contract requires them:
|
||||||
|
|
||||||
1. **Configuration handling:** values are accepted or rejected according to the selected contract.
|
1. **Configuration handling:** values are accepted or rejected according to the selected contract.
|
||||||
2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit.
|
2. **Runtime enforcement:** observed peak concurrency never exceeds the configured limit.
|
||||||
|
|
||||||
Use a test-controlled limit and measure the behavior relative to that limit. Do not merely assert today's default value.
|
Use a test-controlled limit and measure the behavior relative to that limit.
|
||||||
|
|
||||||
## Avoid semantic duplication across layers
|
## Assign each behavior a test owner
|
||||||
|
|
||||||
Each behavior should have a clear test owner.
|
Where these layers exist, assign ownership as follows:
|
||||||
|
|
||||||
- Configuration tests own application YAML, strict decoding, discovery,
|
- Parser tests own parsing cases.
|
||||||
precedence, and application defaults.
|
- Validator tests own validation rules.
|
||||||
- CLI tests own argument mapping, streams, summaries, exit behavior, and
|
- Domain tests own transformations and invariants.
|
||||||
representative command workflows.
|
- Adapter tests own external integration behavior.
|
||||||
- HTTP tests own DTOs, strict decoding, limits, status mapping, and restricted
|
- Orchestrator tests own coordination and failure propagation.
|
||||||
artifact policy.
|
- CLI tests own argument and configuration mapping.
|
||||||
- Formatter tests own prepared-run and definition-inspection text and JSON
|
- End-to-end tests prove that representative assembled workflows work.
|
||||||
presentation.
|
|
||||||
- Architecture tests own dependency direction and removal invariants.
|
Give each layer its distinct responsibility and keep expectation updates localized to the contract being changed.
|
||||||
|
|
||||||
|
## Scriptorium Test Ownership
|
||||||
|
|
||||||
|
- Application configuration tests own Scriptorium's definition, strict
|
||||||
|
decoding at its boundary, source discovery and selection, explicit CLI
|
||||||
|
override presence, application defaults, runtime conversion, and safe
|
||||||
|
diagnostics. ConfigKit owns exhaustive YAML grammar, source traversal,
|
||||||
|
import and overlay composition, provenance, and inspection renderers.
|
||||||
|
- CLI tests own argument mapping, streams, output, exit behavior, and
|
||||||
|
representative run, render, inspect, serve, and config workflows.
|
||||||
|
- HTTP tests own DTO decoding, transport limits, status and error mapping,
|
||||||
|
restricted artifact reading, and representative server workflows.
|
||||||
|
- Formatting tests own prepared-run and definition-inspection text and JSON
|
||||||
|
presentation. Architecture guards own dependency direction and removed
|
||||||
|
framework-package boundaries.
|
||||||
- Promptkit owns framework parsing, orchestration, validation, profiles, and
|
- Promptkit owns framework parsing, orchestration, validation, profiles, and
|
||||||
model-client behavior. Scriptorium's definition compatibility fixtures protect
|
model-client behavior. Scriptorium's definition and execution fixtures
|
||||||
its adapter plumbing without duplicating the upstream format contract.
|
protect adoption through its public adapter boundary without duplicating
|
||||||
|
Promptkit's exhaustive format matrix.
|
||||||
|
|
||||||
Higher-level tests should not repeat every lower-level case. A single intentional policy change should not require unrelated edits across many test files.
|
HTTP lexical containment, size limits, and shared engine and backend capacity
|
||||||
|
across concurrent requests merit focused adapter coverage because violations
|
||||||
|
cross a security or concurrency boundary. Choose cases by realistic risk
|
||||||
|
rather than a coverage quota or a duplicated upstream matrix.
|
||||||
|
|
||||||
## Use test doubles deliberately
|
## Use test doubles deliberately
|
||||||
|
|
||||||
@@ -205,12 +213,9 @@ Mocks are appropriate when the contract includes facts such as:
|
|||||||
- an expensive API is called no more than once; or
|
- an expensive API is called no more than once; or
|
||||||
- a security audit event is emitted.
|
- a security audit event is emitted.
|
||||||
|
|
||||||
Do not use mocks merely to isolate every object or reproduce the implementation's call graph.
|
|
||||||
|
|
||||||
## Go-specific guidance
|
## Go-specific guidance
|
||||||
|
|
||||||
Select techniques according to the behavior and risk being tested. The following
|
Select techniques by behavior and risk:
|
||||||
are options, not a checklist that every package or application must satisfy:
|
|
||||||
|
|
||||||
- table-driven tests for meaningful behavioral categories and boundaries;
|
- table-driven tests for meaningful behavioral categories and boundaries;
|
||||||
- `t.TempDir()` for real filesystem behavior;
|
- `t.TempDir()` for real filesystem behavior;
|
||||||
@@ -220,55 +225,48 @@ are options, not a checklist that every package or application must satisfy:
|
|||||||
- integration tests where correctness depends on component interaction; and
|
- integration tests where correctness depends on component interaction; and
|
||||||
- a small number of representative end-to-end tests when assembled workflows expose meaningful risks not adequately covered at narrower boundaries.
|
- a small number of representative end-to-end tests when assembled workflows expose meaningful risks not adequately covered at narrower boundaries.
|
||||||
|
|
||||||
Avoid exact error-string assertions unless the wording is itself contractual. Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields.
|
Prefer `errors.Is`, `errors.As`, typed errors, or structured error fields. Use exact error-wording assertions only when the wording is contractual.
|
||||||
|
|
||||||
At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Do not snapshot complete diagnostic wording unless it is contractual.
|
At CLI boundaries, prefer exit classifications, structured output, and the smallest stable semantic fragment needed to identify the error. Use complete diagnostic snapshots only when the wording is contractual.
|
||||||
|
|
||||||
Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update.
|
Golden-file updates must require an explicit local flag. CI must not update golden files automatically, and reviewers must inspect the semantic diff before accepting an update.
|
||||||
|
|
||||||
Keep tests readable and direct. Test helpers and fixture frameworks must earn their own maintenance cost; do not build elaborate test infrastructure for small or isolated needs.
|
Keep tests readable and direct. Size test helpers and fixture frameworks to the maintenance benefit they provide.
|
||||||
|
|
||||||
## Coverage
|
## Coverage
|
||||||
|
|
||||||
Coverage is a diagnostic, not a target.
|
Use coverage to locate untested critical branches and unexpectedly weak packages. Evaluate test quality through meaningful behavioral protection and choose coverage according to risk.
|
||||||
|
|
||||||
Use it to find untested critical branches and unexpectedly weak packages. Do not write low-value tests solely to increase a percentage, and do not infer test quality from coverage alone.
|
Pure domain logic will often warrant higher coverage than CLI wiring or external adapters. Uneven coverage is acceptable when it reflects risk.
|
||||||
|
|
||||||
Security-sensitive HTTP containment and external mappings may warrant denser
|
|
||||||
coverage than straightforward process wiring. Uneven coverage is acceptable
|
|
||||||
when it reflects risk.
|
|
||||||
|
|
||||||
## Regression tests
|
## Regression tests
|
||||||
|
|
||||||
A bug fix should normally include a regression test that fails before the fix and passes afterward.
|
A bug fix should normally include a regression test that fails before the fix and passes afterward.
|
||||||
|
|
||||||
Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant; do not preserve accidental implementation details from the original bug.
|
Retain the test when the defect could realistically recur and its consequences justify the ongoing cost. Prefer the narrowest durable test of the violated contract or invariant.
|
||||||
|
|
||||||
Not every historical bug requires a permanent test. If the underlying design has made recurrence impossible, the test has become redundant, or a stronger invariant test now subsumes it, remove or consolidate it.
|
Remove or consolidate a test when the underlying design has made recurrence impossible, its protection is redundant, or a stronger invariant test subsumes it.
|
||||||
|
|
||||||
## Deleting or rewriting tests
|
## Deleting or rewriting tests
|
||||||
|
|
||||||
Tests are maintained code, not permanent historical artifacts.
|
Delete or rewrite tests when maintenance cost exceeds their continuing
|
||||||
|
protective value.
|
||||||
Delete or rewrite a test when its maintenance cost exceeds the confidence it provides.
|
|
||||||
|
|
||||||
Strong candidates include tests that:
|
Strong candidates include tests that:
|
||||||
|
|
||||||
- require updates after harmless internal changes;
|
- require updates after harmless internal changes;
|
||||||
- directly assert private constants without protecting a real contract;
|
- assert incidental private constants or snapshot large amounts of incidental output;
|
||||||
- duplicate the same policy across several layers;
|
|
||||||
- verify mock choreography rather than outcomes;
|
- verify mock choreography rather than outcomes;
|
||||||
- snapshot large amounts of incidental output;
|
- duplicate policy across layers, retest trivial helpers covered by package
|
||||||
- test trivial private helpers already exercised through stable package behavior;
|
behavior, or protect risks covered more effectively elsewhere;
|
||||||
- protect risks already covered more effectively elsewhere;
|
|
||||||
- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
|
- are flaky, misleading, obsolete, or disproportionately expensive to diagnose; or
|
||||||
- no longer correspond to a plausible failure mode.
|
- no longer correspond to a plausible failure mode.
|
||||||
|
|
||||||
Several brittle tests may encode one genuine requirement. Replace them with one durable behavior-level or invariant test rather than preserving all of them.
|
Several brittle tests may encode one genuine requirement. Consolidate them into one durable behavior-level or invariant test.
|
||||||
|
|
||||||
## Reviewing a proposed test
|
## Reviewing a proposed test
|
||||||
|
|
||||||
Use the following questions when the value, boundary, or durability of a proposed test is not self-evident. Significant test additions should be reviewable against them, but written answers are not required for every routine test.
|
Use the following questions when a proposed test needs closer evaluation. Significant test additions should be reviewable against them; written answers are optional for routine tests.
|
||||||
|
|
||||||
1. Which requested behavior or established contract does it protect, and what realistic defect would violate it?
|
1. Which requested behavior or established contract does it protect, and what realistic defect would violate it?
|
||||||
2. How likely and consequential is that defect, and is it already protected elsewhere?
|
2. How likely and consequential is that defect, and is it already protected elsewhere?
|
||||||
@@ -282,10 +280,9 @@ A test suite is sufficient when:
|
|||||||
|
|
||||||
- important requested behavior and established contracts are protected against realistic, consequential failures;
|
- important requested behavior and established contracts are protected against realistic, consequential failures;
|
||||||
- boundaries and component interactions have coverage where they introduce meaningful risks not protected elsewhere;
|
- boundaries and component interactions have coverage where they introduce meaningful risks not protected elsewhere;
|
||||||
- failures provide useful signal rather than redundant noise;
|
- failures provide useful, distinct signals;
|
||||||
- legitimate internal changes usually do not require test edits; and
|
- tests usually remain stable through legitimate internal changes; and
|
||||||
- additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
|
- additional tests would mostly repeat existing protection or preserve inconsequential implementation details.
|
||||||
|
|
||||||
Sufficiency is a risk judgment, not a coverage percentage, test count, or required
|
Reassess sufficiency as the application, its users, and the consequences of
|
||||||
mix of testing techniques. Reassess it as the application, its users, and the
|
failure evolve.
|
||||||
consequences of failure evolve.
|
|
||||||
|
|||||||
@@ -9,11 +9,31 @@ discoverability requirements.
|
|||||||
## Prepare The Candidate
|
## Prepare The Candidate
|
||||||
|
|
||||||
Use a POSIX shell, Git with a configured tagger identity and access to
|
Use a POSIX shell, Git with a configured tagger identity and access to
|
||||||
`origin`, and a Go toolchain compatible with `go.mod`. The native host must
|
`origin`, and the selected release toolchain, Go 1.27.4. The native host must
|
||||||
support Go's race detector and have its required C compiler. If Git is
|
support Go's race detector and have its required C compiler. If Git is
|
||||||
configured to sign tags, its signing tool and key must be available. Run from the
|
configured to sign tags, its signing tool and key must be available. Run from the
|
||||||
repository root. Provision the toolchain and module cache before offline
|
repository root. The [developer guide](development.md#baseline-validation)
|
||||||
validation; when dependencies are not cached:
|
explains the separate Go consumer minimum; selecting a release toolchain does
|
||||||
|
not raise that minimum.
|
||||||
|
|
||||||
|
Install Go 1.27.4 from the [official downloads](https://go.dev/dl/) or an
|
||||||
|
equivalent package source before validation. Set `release_go_root` to its
|
||||||
|
installation directory, replacing the illustrative path below, and select it
|
||||||
|
in the release shell:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
release_go_root=/path/to/go1.27.4
|
||||||
|
export PATH="$release_go_root/bin:$PATH"
|
||||||
|
export GOTOOLCHAIN=local
|
||||||
|
go version
|
||||||
|
```
|
||||||
|
|
||||||
|
The version output should identify `go1.27.4`. Keep this selection and the
|
||||||
|
hosted workflow's Go image in step when deliberately updating the release
|
||||||
|
toolchain. Ordinary contributor checks may use another compatible toolchain.
|
||||||
|
|
||||||
|
Provision the module cache before offline validation; when dependencies are
|
||||||
|
not cached:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
GOWORK=off go mod download
|
GOWORK=off go mod download
|
||||||
@@ -23,20 +43,19 @@ Choose an unused stable version under the release policy. Commit its note as
|
|||||||
`docs/releases/<version>.md`, beginning with a title such as
|
`docs/releases/<version>.md`, beginning with a title such as
|
||||||
`# Scriptorium v0.14.0` (an example, not an instruction to select that version).
|
`# Scriptorium v0.14.0` (an example, not an instruction to select that version).
|
||||||
Include a concise summary and relevant compatibility impact or upgrade action.
|
Include a concise summary and relevant compatibility impact or upgrade action.
|
||||||
End the note with the following footer, replacing `<version>` in both absolute
|
End the note with the following footer, replacing `<version>` in all three absolute
|
||||||
URLs with the selected version tag (for example, `v0.14.0`):
|
URLs with the selected version tag (for example, `v0.14.0`):
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
[LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/docs/oss/attribution.md)
|
[COPYRIGHT](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/<version>/docs/oss/attribution.md)
|
||||||
```
|
```
|
||||||
|
|
||||||
Check that both URLs name files in the candidate tree at that tag. The tag may
|
Check that all three URLs name files in the candidate tree at that tag. The tag may
|
||||||
not resolve online until publication. The checked-in note is copied unchanged
|
not resolve online until publication. The checked-in note is copied unchanged
|
||||||
into the hosted release body by the existing workflow, so do not maintain a
|
into the hosted release body by the existing workflow, so do not maintain a
|
||||||
second footer there.
|
second footer there.
|
||||||
Update affected canonical documentation with the change, and retire completed
|
Update affected canonical documentation with the change, and retire completed
|
||||||
roadmap material when appropriate while preserving deferred work and links.
|
roadmap material when appropriate while preserving deferred work and links.
|
||||||
No extra release-specific review signoff is required.
|
|
||||||
|
|
||||||
Finish and commit the intended candidate on `main`, then publish that branch:
|
Finish and commit the intended candidate on `main`, then publish that branch:
|
||||||
|
|
||||||
@@ -63,9 +82,8 @@ remote version, exact agreement with authoritative remote `main`, and a
|
|||||||
checked-in note whose first-level title contains Scriptorium and the exact
|
checked-in note whose first-level title contains Scriptorium and the exact
|
||||||
version. Ignored local files do not make the candidate dirty.
|
version. Ignored local files do not make the candidate dirty.
|
||||||
|
|
||||||
The existing source-boundary guards reject committed workspaces, vendor trees,
|
The source-boundary guards reject committed workspaces, vendor trees, and
|
||||||
and module replacements. No migration-specific exact Promptkit version audit
|
module replacements.
|
||||||
is required.
|
|
||||||
|
|
||||||
It then runs the complete suite once with the race detector and builds Linux
|
It then runs the complete suite once with the race detector and builds Linux
|
||||||
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and
|
amd64 and arm64 binaries using `CGO_ENABLED=0`, `-trimpath`, and
|
||||||
|
|||||||
26
docs/releases/v0.15.0.md
Normal file
26
docs/releases/v0.15.0.md
Normal file
@@ -0,0 +1,26 @@
|
|||||||
|
# Scriptorium v0.15.0
|
||||||
|
|
||||||
|
This minor release changes Scriptorium's application grant to GPL version 3 or
|
||||||
|
later, aligns its repository policies and attribution notices, and updates the
|
||||||
|
selected Promptkit and ConfigKit patch releases.
|
||||||
|
|
||||||
|
## Licensing and upgrade impact
|
||||||
|
|
||||||
|
Scriptorium's application source and binaries are now distributed under
|
||||||
|
GPL-3.0-or-later. Review [COPYRIGHT](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/COPYRIGHT)
|
||||||
|
and [LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/LICENSE)
|
||||||
|
before redistributing or incorporating this version. Material adapted from
|
||||||
|
Standard Repository Policies remains separately licensed under CC-BY-SA-4.0;
|
||||||
|
the [attribution notices](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/oss/attribution.md)
|
||||||
|
identify its scope and license text. Existing dependency grants are unchanged,
|
||||||
|
and earlier tagged releases retain their own published terms.
|
||||||
|
|
||||||
|
## Dependency updates
|
||||||
|
|
||||||
|
Scriptorium now selects Promptkit v0.11.2 and ConfigKit v0.4.2. The current
|
||||||
|
[CLI](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/cli.md),
|
||||||
|
[HTTP API](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/api.md),
|
||||||
|
and [configuration](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/config.md)
|
||||||
|
references describe the executable contracts.
|
||||||
|
|
||||||
|
[COPYRIGHT](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.15.0/docs/oss/attribution.md)
|
||||||
334
docs/roadmap/commandkit-adoption.md
Normal file
334
docs/roadmap/commandkit-adoption.md
Normal file
@@ -0,0 +1,334 @@
|
|||||||
|
# CommandKit Adoption
|
||||||
|
|
||||||
|
## Status And Intent
|
||||||
|
|
||||||
|
Initial roadmap, prepared 2026-11-19. The product direction is agreed;
|
||||||
|
implementation has not begun. This document owns the target and product intent,
|
||||||
|
incorporating the decisions in the [migration notepad](commandkit-notepad.md).
|
||||||
|
The notepad remains the discussion
|
||||||
|
record. The [Narratio proposal](narratio-feature-request.md) supplies consumer
|
||||||
|
acceptance scenarios for requirements discovery. The
|
||||||
|
[implementation plan](implementation.md) owns the ordered stages and concrete
|
||||||
|
adapter choices.
|
||||||
|
|
||||||
|
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) records
|
||||||
|
the native-interface adoption and ownership boundaries, complementing ADRs 0004
|
||||||
|
and 0005.
|
||||||
|
|
||||||
|
Make Scriptorium a CommandKit-native executable interface over PromptKit,
|
||||||
|
including ckconfig and ckprompt. Most subprocess consumers should be able to
|
||||||
|
select a stored prompt and consume its resulting artifact directly. Operators
|
||||||
|
and consumers needing inspection or metadata should use native upstream
|
||||||
|
interfaces and reports.
|
||||||
|
|
||||||
|
This is a full CLI cutover. Existing command names, flag spellings, parsing,
|
||||||
|
report shapes, and exit conventions are not compatibility constraints. Release
|
||||||
|
migration guidance replaces a compatibility layer. Implementation may proceed
|
||||||
|
in reviewable increments; this does not require shipping both interfaces.
|
||||||
|
|
||||||
|
## Current Baseline And Upstream References
|
||||||
|
|
||||||
|
Reviewed Scriptorium baseline: `5f32a4f2adb2d382a6cfce3a787ada4576be7705`.
|
||||||
|
The module uses Go 1.27.0, PromptKit v0.23.3, and ConfigKit v1.2.1. CommandKit
|
||||||
|
is not yet a dependency.
|
||||||
|
|
||||||
|
| Current implementation | Migration work |
|
||||||
|
| --- | --- |
|
||||||
|
| `internal/adapter/cli` dispatches and parses commands, resolves configuration, builds engines and requests, writes diagnostics, and returns integer statuses. | Replace dispatch and shared CLI mechanics with CommandKit; retain application loading, request mapping, and effects through its extension points. |
|
||||||
|
| `run` uses flag-based prompt selection and writes generated content; `--execution-report` writes an observer-derived Scriptorium report. | Adopt positional prompt selection, native request flags, and native result reporting. |
|
||||||
|
| `render`, `inspect prompt`, and `inspect profile` use custom presentation in `internal/format`. | Replace with native ckprompt operations and remove unused presentation code. |
|
||||||
|
| `config` and `inspect configuration` separately expose application and framework configuration. | Install one ckconfig family with `app` and `promptkit` scopes, including comparison. |
|
||||||
|
| `internal/config` owns application schema, discovery, defaults, and conversion through ConfigKit. | Adapt its loader and explicit overrides to standard selections and scope capabilities. |
|
||||||
|
| `serve` constructs a restricted HTTP artifact reader and one shared PromptKit engine. | Register it as an application command and preserve existing HTTP behavior. |
|
||||||
|
| `internal/report` also supplies HTTP's optional execution report. | Remove its superseded CLI use; retain functionality still used by HTTP. |
|
||||||
|
|
||||||
|
The [current CLI](../cli.md), [configuration contract](../config.md),
|
||||||
|
[adapter internals](../internal/adapters.md), and
|
||||||
|
[subprocess contract](../integrations/subprocess.md) describe the starting
|
||||||
|
behavior, not a compatibility checklist for this migration.
|
||||||
|
|
||||||
|
The reviewed upstream combination is CommandKit v0.7.0, ckconfig v0.9.0,
|
||||||
|
and ckprompt v0.10.0, documented at revision
|
||||||
|
`d330d7637f2e7507eca931a899397222c82bc892`:
|
||||||
|
|
||||||
|
- [Consumer guide][upstream-guide]: composition, loading, reusable bindings,
|
||||||
|
reporting, and outcomes.
|
||||||
|
- [CLI reference][upstream-cli]: native command grammar and observable behavior.
|
||||||
|
|
||||||
|
The selected released combination retains Scriptorium's adopted PromptKit
|
||||||
|
v0.23.3 fixes and ConfigKit v1.2.1. The reviewed ckprompt release's PromptKit
|
||||||
|
v0.23.2 minimum does not require a downgrade. Supported public APIs and released
|
||||||
|
dependencies remain subject to the existing
|
||||||
|
[architecture policy](../policy/architecture.md).
|
||||||
|
|
||||||
|
No selected-format accessor is required for this migration. The native
|
||||||
|
invocation reporter handles the main result on stdout; the existing writer API
|
||||||
|
handles the separate report with automatic or explicitly selected rendering.
|
||||||
|
The upstream accessor proposal remains optional API work, independent of
|
||||||
|
Scriptorium's adoption.
|
||||||
|
|
||||||
|
## Target End State
|
||||||
|
|
||||||
|
### Responsibilities And Scope
|
||||||
|
|
||||||
|
CommandKit owns command declarations, dispatch, common parsing, help, reporting,
|
||||||
|
and outcome mechanics. ckconfig and ckprompt supply their standard families.
|
||||||
|
ConfigKit owns configuration policy through the fully resolved handoff,
|
||||||
|
including resolution of PromptKit's configuration using PromptKit's schema and
|
||||||
|
rules. PromptKit owns definition, preparation, execution, validation, and
|
||||||
|
inspection semantics. Scriptorium owns the application domain: it interprets
|
||||||
|
resolved values and uses upstream APIs and results to satisfy user requests.
|
||||||
|
Application commands, process lifecycle, and artifact delivery remain local.
|
||||||
|
|
||||||
|
This preserves Scriptorium's request-independent execution model and support
|
||||||
|
for valid definitions under [ADR 0004](../adr/0004-definition-boundary.md).
|
||||||
|
It adds no workflow, conversation, archive, or resume system. HTTP design review
|
||||||
|
remains separate work before v1.0; migrating its startup command does not
|
||||||
|
redesign the HTTP API or its execution-report representation.
|
||||||
|
|
||||||
|
Use shared upstream capabilities where available. A concrete missing shared
|
||||||
|
capability should prompt an upstream discussion before a local substitute.
|
||||||
|
Application-specific loading and effects remain ordinary application work.
|
||||||
|
|
||||||
|
### Command Surface
|
||||||
|
|
||||||
|
| Surface | Target |
|
||||||
|
| --- | --- |
|
||||||
|
| Generation | Application command `run PROMPT_ID`, with a required positional prompt ID and no duplicate prompt flag. |
|
||||||
|
| HTTP service | Application command `serve`. |
|
||||||
|
| Configuration | Native `config` family with `app` and `promptkit` scopes: scope discovery, validation, effective values, sources, explanations, and diff. |
|
||||||
|
| Resource inspection | Native prompt, profile, backend, namespace, and collection inventories and applicable named inspection. |
|
||||||
|
| Dependency discovery | Native `promptkit requirements show PROMPT_ID`. |
|
||||||
|
| Concrete validation | Native `promptkit requirements validate` capability. |
|
||||||
|
| Prepared preview | Native `promptkit show prepared PROMPT_ID`, replacing `render`. |
|
||||||
|
| Provider diagnostics | Native smoke-test commands, invoked explicitly. |
|
||||||
|
| Executable support | Native help, version, reporting modes, outcomes, and shell completion. |
|
||||||
|
|
||||||
|
Install application commands outside the reserved standard families. Enable
|
||||||
|
the native convenience aliases consistently. Prefer shorter spellings such as
|
||||||
|
`--profile`, `--input-file`, `--input-text`, and `--var` in examples and guidance
|
||||||
|
where applicable and unambiguous; canonical `--llm-*` spellings remain available.
|
||||||
|
Aliases retain upstream semantics: `--input` supplies literal text, and file
|
||||||
|
references use `--input-file`.
|
||||||
|
|
||||||
|
Reuse applicable ckprompt resource, input, and execution bindings for `run`.
|
||||||
|
Preserve explicit-value presence, including zero and empty values, and native
|
||||||
|
repeated mapping semantics. Do not carry forward comma splitting or obsolete
|
||||||
|
aliases merely because the old parser accepted them. Keep application source
|
||||||
|
selectors, server settings, output destinations, and whole-operation deadlines
|
||||||
|
distinct from framework request controls.
|
||||||
|
|
||||||
|
Completion initially uses native command, flag, static-value, and path
|
||||||
|
completion, with suitable application hints. Dynamic installed-resource
|
||||||
|
completion is not required. Smoke tests are explicit operator operations;
|
||||||
|
their inclusion does not make provider access a startup or release prerequisite.
|
||||||
|
Preserve native diagnostic findings, including successful invocations whose
|
||||||
|
reports describe unsupported or unsuccessful checks.
|
||||||
|
|
||||||
|
### Configuration Authority And Native Inspection
|
||||||
|
|
||||||
|
The migration implements the ownership decision in
|
||||||
|
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md) through
|
||||||
|
these two boundaries:
|
||||||
|
|
||||||
|
1. **ConfigKit's completed result is authoritative configuration.** Scriptorium
|
||||||
|
supplies its schema, domain defaults, validation, and genuine application
|
||||||
|
configuration-resolution logic through ConfigKit's supported extension
|
||||||
|
points. Those callbacks operate within ConfigKit's lifecycle and evidence
|
||||||
|
model, including recording resolution changes through the supported APIs.
|
||||||
|
Scriptorium consumes the completed result without subsequently revising what
|
||||||
|
effective configuration means. Runtime conversion and request construction
|
||||||
|
may consume resolved values; they do not introduce another configuration
|
||||||
|
merge, defaulting, or normalization pass. This follows the configuration
|
||||||
|
boundary established in [ADR 0005](../adr/0005-configkit-boundary.md).
|
||||||
|
2. **Standard inspection exposes that result through native adapters.**
|
||||||
|
Scriptorium selects and acquires the requested configuration and declares
|
||||||
|
supported capabilities. Use `ckconfig.FromConfigKit` for the application
|
||||||
|
result and `ckprompt.ConfigScope` for PromptKit's captured configuration
|
||||||
|
inspection within the native `ckconfig` family. Scriptorium does not assemble
|
||||||
|
a different effective document, reconcile separate explanation trees, or
|
||||||
|
reinterpret upstream path semantics. Effective values, sources, explanations,
|
||||||
|
metadata, and comparisons come from the acquired upstream result through
|
||||||
|
those adapters. CommandKit owns their standard presentation.
|
||||||
|
|
||||||
|
Application selection and supported configuration overrides feed the loading
|
||||||
|
lifecycle before its completed result is exposed. Adapting loaders or supplying
|
||||||
|
scopes below does not authorize a second configuration-resolution or inspection
|
||||||
|
model. The `app` and `promptkit` scopes retain their respective upstream evidence;
|
||||||
|
they are not combined into a synthetic effective configuration.
|
||||||
|
|
||||||
|
### Configuration, Collections, And Request Context
|
||||||
|
|
||||||
|
Expose application configuration through `app` and captured framework
|
||||||
|
configuration through `promptkit`. Collections are resources within the
|
||||||
|
framework configuration, not separate configuration scopes. Application-only
|
||||||
|
inspection must work without constructing a PromptKit engine.
|
||||||
|
|
||||||
|
`--config` selects Scriptorium application configuration on every applicable
|
||||||
|
command, including framework inspection. That configuration selects framework
|
||||||
|
sources. Adopt native `--overlay` selection and upstream selection presence
|
||||||
|
semantics. For ConfigKit v1.2.1 the supplied value selects an overlay by name,
|
||||||
|
not an arbitrary file path. Map selections through the application's ConfigKit
|
||||||
|
loader rather than retaining the old flag parser as a compatibility layer.
|
||||||
|
Preserve useful application source and server controls through appropriate selectors.
|
||||||
|
|
||||||
|
Enable temporary configuration overrides where the loader supports them,
|
||||||
|
passing native override records into loading. The reviewed PromptKit scope
|
||||||
|
does not support these overrides; do not emulate them locally. Configuration
|
||||||
|
comparison must support independent selections for both sides in both scopes,
|
||||||
|
including corresponding application selectors where needed.
|
||||||
|
|
||||||
|
Keep the established collection-discovery model: ConfigKit imports discover
|
||||||
|
`collection.yml` and `collection.yaml` entry points; each independently
|
||||||
|
maintained collection declares its namespace and imports its own definitions
|
||||||
|
through relative references. Retain the
|
||||||
|
[discovery example](../../examples/config.discovery.yml) and representative
|
||||||
|
multi-definition collection documentation. No Git update manager or custom
|
||||||
|
collection traversal is part of this migration.
|
||||||
|
|
||||||
|
Use native prompt, profile, and backend namespace selectors independently on
|
||||||
|
applicable commands. Short caller-supplied IDs use their selected namespace;
|
||||||
|
qualified IDs remain exact. Selection does not rewrite stored references.
|
||||||
|
Retain upstream inventory filters and defaults, including `--all-namespaces`.
|
||||||
|
Do not add a configurable default namespace in this migration.
|
||||||
|
|
||||||
|
Share applicable configuration selection, engine loading, and request mapping
|
||||||
|
across execution, preview, validation, and discovery. Preserve each operation's
|
||||||
|
upstream lifecycle: discovery can work before artifacts exist; preparation
|
||||||
|
loads and renders without generation. This is consistency of selection and
|
||||||
|
mapping, not a promise that separate invocations see an immutable snapshot.
|
||||||
|
|
||||||
|
### Generation, Reports, And Process Outcomes
|
||||||
|
|
||||||
|
Use a main CommandKit `Report` whose value is PromptKit's native `RunResult` and
|
||||||
|
whose text template emits only the resulting artifact content. The template
|
||||||
|
should emit artifact bytes without presentation decoration. Default/text serves raw
|
||||||
|
artifact consumers; JSON and YAML expose the full native result. The native
|
||||||
|
structured serialization, including its representation of artifact bytes,
|
||||||
|
remains upstream-owned. There is no Scriptorium result envelope.
|
||||||
|
|
||||||
|
| Selection | Behavior |
|
||||||
|
| --- | --- |
|
||||||
|
| Main result | Goes through the native invocation reporter to stdout using the selected format. |
|
||||||
|
| `--format text` or default | Main result contains only the artifact. |
|
||||||
|
| `--format json` or `--format yaml` | Main result contains the native result and metadata. |
|
||||||
|
| `--report PATH` | Additionally write the native result through CommandKit's renderer, independently of the main format and destination. Without `--report-format`, use native automatic rendering. |
|
||||||
|
| `--report-format text\|yaml\|json` | Explicitly select the separate report's native rendering format. |
|
||||||
|
|
||||||
|
The separate report contains the same native `RunResult`, without the main
|
||||||
|
report's artifact-only text template. Omission of `--report-format` leaves the
|
||||||
|
format unset so CommandKit decides how to render it. Its current automatic
|
||||||
|
rendering for structured values is YAML; future upstream default changes flow
|
||||||
|
through. Scriptorium does not set a default report format.
|
||||||
|
|
||||||
|
There is no `--output` or legacy `--out` flag. Callers save the main result by
|
||||||
|
redirecting stdout in a shell or supplying a file as the subprocess stdout
|
||||||
|
destination. Diagnostics remain on stderr. Callers wanting main output omit
|
||||||
|
`--quiet`, including when stdout is redirected. Filename extensions do not
|
||||||
|
select formats. The separate report includes the native result's content as
|
||||||
|
well as metadata; it replaces the CLI's old
|
||||||
|
observer-derived metadata projection. A caller wanting an artifact file plus
|
||||||
|
metadata redirects stdout and selects a separate `--report` path. The caller
|
||||||
|
manages redirected destinations and retention; there is no automatic reporting
|
||||||
|
directory or report collection.
|
||||||
|
|
||||||
|
Native result reporting is available when PromptKit returns a result.
|
||||||
|
Operational errors return nonzero status and native failure diagnostics, without
|
||||||
|
synthesizing replacement results. Preserve PromptKit's distinction between a
|
||||||
|
completed content check reporting `ValidationFailed` and an operational failure
|
||||||
|
to perform the check. Neither extra content judgments nor a structured JSON
|
||||||
|
invocation-error envelope is part of this migration.
|
||||||
|
|
||||||
|
Adopt CommandKit's quiet and verbosity semantics, including rendering and
|
||||||
|
presentation failures. Console results use the invocation reporter; diagnostics
|
||||||
|
use its diagnostic channel. An explicit `--report` write is an application
|
||||||
|
effect rendered through the writer API and still occurs in quiet mode.
|
||||||
|
Quiet does not cancel generation; it suppresses the main result even when
|
||||||
|
stdout is redirected, while failure explanations remain visible. Move any
|
||||||
|
retained generation summary into an appropriate native message category.
|
||||||
|
|
||||||
|
Map typed upstream failures and configuration diagnostics into native outcomes,
|
||||||
|
without parsing error text. Standard statuses remain upstream-owned. Use an
|
||||||
|
application domain outcome for completed validation failure, distinct from
|
||||||
|
usage and diff-check outcomes. The implementation plan specifies the mapping.
|
||||||
|
Delivery failures must produce a nonzero outcome and explanation, preserving
|
||||||
|
native presentation-failure behavior where applicable, including an already
|
||||||
|
nonzero domain outcome. Requested file errors must not disappear merely because
|
||||||
|
they occur outside the invocation reporter.
|
||||||
|
|
||||||
|
For `--report`, use ordinary file replacement without creating parents. Attempt
|
||||||
|
the main output followed by the report, and attempt the report even if main
|
||||||
|
delivery fails. Open the report only when a native result exists. Redirection
|
||||||
|
and its file-creation or truncation behavior belong to the caller. Scriptorium
|
||||||
|
does not manage the main output file or check it against the report path. This
|
||||||
|
adds no rollback or transactional delivery; written bytes may remain after
|
||||||
|
failure.
|
||||||
|
|
||||||
|
Wire signal cancellation through the invocation context. Keep the application
|
||||||
|
whole-operation budget separate from the native per-attempt timeout binding.
|
||||||
|
Use `--run-timeout` with Go duration values mapped to PromptKit's
|
||||||
|
`OperationTimeout`, preserving upstream zero, negative-value, and timeout
|
||||||
|
behavior without a second timeout policy.
|
||||||
|
|
||||||
|
### Preview And Consumer Inspection
|
||||||
|
|
||||||
|
Remove `render`, its compatibility aliases, `defaults.render_format`, and
|
||||||
|
unused prepared-output formatters. Native prepared preview uses its upstream
|
||||||
|
report, default/text YAML presentation, standard formats, request flags,
|
||||||
|
diagnostics, and outcomes. It does not call a model. Consumers save preview
|
||||||
|
output through stdout capture or redirection, as they do for generation.
|
||||||
|
|
||||||
|
Adopt native inspection reports, including captured prompt messages and rendered
|
||||||
|
prepared content, without recreating old summary projections. Native schemas
|
||||||
|
and adopted upstream versions govern structured output; this migration adds no
|
||||||
|
separate schema-version wrapper or compatibility guarantee.
|
||||||
|
|
||||||
|
Implement the [Narratio acceptance scenarios](narratio-feature-request.md#consumer-acceptance-scenarios).
|
||||||
|
Requirements discovery exposes native classification, completeness, and issue
|
||||||
|
codes. Complete discovery is distinct from satisfied bindings and execution
|
||||||
|
readiness; partial discovery can succeed with status zero. Narratio owns its
|
||||||
|
pipeline, binding graph, and policy for incomplete findings. Preserve native
|
||||||
|
metadata without inventing prompt versions, variable defaults, or input schemas.
|
||||||
|
|
||||||
|
## Acceptance And Scope Boundaries
|
||||||
|
|
||||||
|
The target is met when Scriptorium exposes the native command surface and
|
||||||
|
application behavior above, superseded CLI machinery is retired, and maintained
|
||||||
|
documentation and examples describe the shipped interface. In particular:
|
||||||
|
|
||||||
|
- Configuration callbacks, runtime consumers, and native inspection agree on
|
||||||
|
ConfigKit's completed values and evidence. Application-only inspection needs
|
||||||
|
no PromptKit engine, and comparison sides retain independent selections.
|
||||||
|
- Applicable selection and request context remain consistent across execution,
|
||||||
|
preparation, discovery, and inspection of multiple independently maintained
|
||||||
|
collections. Their upstream lifecycle differences remain visible.
|
||||||
|
- Generation defaults to the artifact alone; structured output and separate
|
||||||
|
reports expose the native result. Main output uses stdout and native quiet
|
||||||
|
semantics; the optional report file uses native automatic or explicitly
|
||||||
|
selected rendering, independently of quiet, with useful failure outcomes and
|
||||||
|
nontransactional delivery.
|
||||||
|
- Narratio's linked acceptance scenarios are supported, including useful partial
|
||||||
|
discovery and discovery before generated artifacts exist.
|
||||||
|
- Native help, aliases, completion, and explicit smoke testing are available.
|
||||||
|
Including smoke testing adds no provider access prerequisite to startup or
|
||||||
|
release validation.
|
||||||
|
- Server startup reaches the existing HTTP adapter with its transport,
|
||||||
|
restricted-reading, execution-report, and shared-capacity behavior intact.
|
||||||
|
- Canonical contracts, examples, dependency attribution, and migration guidance
|
||||||
|
reflect the cutover. The CLI migration includes positional prompt selection,
|
||||||
|
command replacements, literal versus file inputs, repeated mappings, overlay
|
||||||
|
selection, native endpoint/timeout controls, stdout redirection in place of
|
||||||
|
output-file flags, content-bearing reports, optional report-format selection,
|
||||||
|
report availability, quiet behavior, and changed exit statuses.
|
||||||
|
|
||||||
|
The [implementation plan](implementation.md) owns task sequencing, concrete
|
||||||
|
adapter mappings, verification steps, and sprint status. There are no unresolved
|
||||||
|
product decisions or selected-format accessor release prerequisite.
|
||||||
|
|
||||||
|
The [release policy](../policy/release.md#versioning-and-compatibility) governs
|
||||||
|
the eventual breaking release version. This migration does not itself select
|
||||||
|
or publish a release, introduce a compatibility layer, or settle the separate
|
||||||
|
pre-v1.0 HTTP design review.
|
||||||
|
|
||||||
|
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
|
||||||
|
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||||
331
docs/roadmap/commandkit-notepad.md
Normal file
331
docs/roadmap/commandkit-notepad.md
Normal file
@@ -0,0 +1,331 @@
|
|||||||
|
# CommandKit migration notepad
|
||||||
|
|
||||||
|
Status: discussion record incorporated into the
|
||||||
|
[adoption roadmap](commandkit-adoption.md) and
|
||||||
|
[ADR 0006](../adr/0006-adopt-commandkit-native-operator-interfaces.md).
|
||||||
|
The roadmap owns implementation work; the ADR records the ownership decision.
|
||||||
|
|
||||||
|
## Product context
|
||||||
|
|
||||||
|
Scriptorium is a neutral executable interface over PromptKit. Its primary
|
||||||
|
consumers are applications that need to run stored prompts and consume their
|
||||||
|
output without importing PromptKit or building an internal prompting workflow.
|
||||||
|
The CLI and its subprocess contract are therefore central to this migration.
|
||||||
|
|
||||||
|
An installation may load many independently maintained collections. The
|
||||||
|
existing collection model remains the starting point: ConfigKit imports discover
|
||||||
|
`collection.yml` or `collection.yaml` entry points, each collection declares its
|
||||||
|
own namespace, and relative imports assemble its profiles and prompts. See the
|
||||||
|
[configuration contract](../config.md) and
|
||||||
|
[discovery example](../../examples/config.discovery.yml).
|
||||||
|
|
||||||
|
HTTP remains secondary to the CLI discussion. A broader HTTP design review is
|
||||||
|
planned before v1.0; adopting CommandKit does not itself settle that design.
|
||||||
|
|
||||||
|
## Agreed direction
|
||||||
|
|
||||||
|
### Full native cutover
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: become a CommandKit-native application, including
|
||||||
|
`ckconfig` and `ckprompt`, and adopt upstream public conventions and
|
||||||
|
recommendations as fully as possible.
|
||||||
|
|
||||||
|
Backward compatibility with existing CLI conventions is an explicit non-goal.
|
||||||
|
Legacy command names, flag spellings, parsing rules, report shapes, and exit
|
||||||
|
semantics do not constrain the new interface. Do not add compatibility wrappers,
|
||||||
|
legacy aliases, or duplicate inspection implementations solely to preserve the
|
||||||
|
old CLI. Adopt upstream convenience aliases as described below.
|
||||||
|
|
||||||
|
Provide migration guidance in release documentation so consumers can update
|
||||||
|
their invocations and output handling. Guidance replaces a compatibility layer;
|
||||||
|
it does not require a transition period with both interfaces. The
|
||||||
|
[release policy](../policy/release.md#versioning-and-compatibility) governs
|
||||||
|
release version selection and documentation of breaking changes.
|
||||||
|
|
||||||
|
### Ownership and integration
|
||||||
|
|
||||||
|
Use CommandKit for command declarations, parsing, help, reporting, and outcomes;
|
||||||
|
use `ckconfig` and `ckprompt` for their standardized operator interfaces.
|
||||||
|
Scriptorium should retire the corresponding custom inspection machinery as
|
||||||
|
those interfaces take over.
|
||||||
|
|
||||||
|
ConfigKit owns configuration policy through the fully resolved handoff,
|
||||||
|
including PromptKit configuration resolution. PromptKit owns prompting and
|
||||||
|
inspection semantics. Scriptorium interprets resolved values and uses upstream
|
||||||
|
APIs and results to satisfy user requests. CommandKit adoption does not introduce
|
||||||
|
workflow or conversation state. ADR 0006 records these boundaries.
|
||||||
|
|
||||||
|
Prefer shared upstream capabilities over new Scriptorium-specific equivalents.
|
||||||
|
If a required shared capability is missing, discuss an upstream request before
|
||||||
|
designing a local substitute. Application-specific behavior still belongs in
|
||||||
|
Scriptorium.
|
||||||
|
|
||||||
|
### Initial capability set
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: include configuration comparison, provider smoke
|
||||||
|
tests, and shell completion in the initial migration, alongside application and
|
||||||
|
PromptKit configuration scopes, resource inventories and inspection,
|
||||||
|
requirements discovery, concrete request validation, and prepared-request
|
||||||
|
preview.
|
||||||
|
|
||||||
|
Use the existing upstream capabilities. Configuration comparison should cover
|
||||||
|
both application and PromptKit scopes, with independent selections for each
|
||||||
|
side. Provider smoke tests run when explicitly invoked; including them does not
|
||||||
|
make them startup checks or release prerequisites. Document provider usage and
|
||||||
|
the distinction between successful diagnostic execution and positive findings.
|
||||||
|
Shell completion should use upstream command, flag, static-value, and path
|
||||||
|
completion, with appropriate hints for application-owned inputs. Dynamic
|
||||||
|
completion of installed resource names is a separate possible enhancement.
|
||||||
|
|
||||||
|
Application-specific wiring remains to be designed, but inclusion of these
|
||||||
|
capabilities is settled. The prepared-request preview decision is recorded below.
|
||||||
|
|
||||||
|
### Generation and subprocess requirements
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: optimize the default generation response for the
|
||||||
|
majority of consumers, who want only the raw resulting artifact. Metadata is
|
||||||
|
optional and available through the native result reporting choices below.
|
||||||
|
|
||||||
|
Prefer native CommandKit reporting and PromptKit result types before introducing
|
||||||
|
a Scriptorium-specific response format. A failure must produce a nonzero process
|
||||||
|
status and information explaining the failure. This does not require a new
|
||||||
|
structured error envelope: native diagnostics are an acceptable way to deliver
|
||||||
|
that information.
|
||||||
|
|
||||||
|
Scriptorium remains a neutral interface to PromptKit. Pass through the errors,
|
||||||
|
validation outcomes, and result information that PromptKit supplies rather than
|
||||||
|
adding independent judgments about generated content or redefining upstream
|
||||||
|
failure semantics. Adapting those outcomes to CommandKit and process exit codes
|
||||||
|
is application work; deciding what constitutes a PromptKit failure is not.
|
||||||
|
|
||||||
|
### Native result reporting and separate report files
|
||||||
|
|
||||||
|
Decision revised 2026-11-19: use a main CommandKit `Report` containing PromptKit's
|
||||||
|
native `RunResult`, with a text template that emits only generated content.
|
||||||
|
Default/text output serves artifact consumers; standard JSON/YAML formats expose
|
||||||
|
the native result and its metadata. This composes existing upstream APIs;
|
||||||
|
ckprompt does not supply a general generation command or prescribe this template.
|
||||||
|
|
||||||
|
Include an optional `--report PATH` flag requiring an explicit file destination.
|
||||||
|
Omitting it creates no separate report file. When requested, pass the native
|
||||||
|
`RunResult` to CommandKit's renderer without an artifact-only text template.
|
||||||
|
Optional `--report-format text|yaml|json` selects the native rendering format.
|
||||||
|
When omitted, leave the format unset and let CommandKit choose; its current
|
||||||
|
structured-value default is YAML, and future upstream changes flow through.
|
||||||
|
There is no Scriptorium default or filename-based selection. Report rendering
|
||||||
|
is independent of the main result's `--format`, representation, and destination.
|
||||||
|
Failure to write a requested report is a delivery failure and must produce a
|
||||||
|
nonzero outcome and diagnostic.
|
||||||
|
|
||||||
|
Do not include a configured reporting directory or automatic report collection
|
||||||
|
in the initial migration. The caller selects the report path and manages its
|
||||||
|
lifecycle. A configured directory may be considered later if automatic
|
||||||
|
collection becomes useful; an explicit report path would take precedence.
|
||||||
|
|
||||||
|
Native result reports are available when PromptKit returns a result. Operational
|
||||||
|
failures produce a nonzero exit and native diagnostics. This follows PromptKit's
|
||||||
|
capabilities and is the intended boundary, not a gap for Scriptorium to address.
|
||||||
|
Do not synthesize replacement results or add an alternative failure-report
|
||||||
|
format to compensate for the absence of a native result.
|
||||||
|
|
||||||
|
### Output destinations and verbosity
|
||||||
|
|
||||||
|
Decision revised 2026-11-19: remove the previously selected `--output` flag.
|
||||||
|
The main result uses the native invocation reporter and stdout. Callers save it
|
||||||
|
through shell redirection or a subprocess stdout destination; diagnostics remain
|
||||||
|
on stderr. Do not retain the old `--out` flag.
|
||||||
|
|
||||||
|
`--format` selects the stdout representation independently of redirection:
|
||||||
|
default/text emits the raw artifact, while JSON/YAML emits the native result
|
||||||
|
with metadata. The filename does not select the format. `--report PATH` remains
|
||||||
|
an additional native result report, so callers can save the raw artifact and its
|
||||||
|
report to separate files by redirecting stdout and supplying `--report`.
|
||||||
|
|
||||||
|
Adopt CommandKit's upstream verbosity and `--quiet` semantics fully, including
|
||||||
|
mode selection, message visibility, rendering, and presentation failures. Do
|
||||||
|
not add Scriptorium-specific exceptions to normal command-output suppression.
|
||||||
|
Quiet mode does not cancel generation, and failure explanations remain visible
|
||||||
|
through the native diagnostic channel.
|
||||||
|
|
||||||
|
An explicit `--report` write remains an application-owned effect in quiet mode,
|
||||||
|
using the existing writer API. Quiet suppresses the main result even when stdout
|
||||||
|
is redirected; callers wanting that result omit quiet. No
|
||||||
|
selected-format accessor is needed, so the upstream proposal is no longer a
|
||||||
|
migration prerequisite. The [upstream reporting contract][upstream-cli] owns the
|
||||||
|
shared verbosity rules.
|
||||||
|
|
||||||
|
### Prepared-request preview
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: replace `render` entirely with the native
|
||||||
|
`promptkit show prepared PROMPT_ID` command, enabled through ckprompt's request
|
||||||
|
preparation integration. Remove `render` without a compatibility alias.
|
||||||
|
|
||||||
|
Use the native prepared-run report, standard request flags, diagnostics,
|
||||||
|
verbosity, and outcomes. Default and explicit text output use the upstream YAML
|
||||||
|
presentation; JSON remains available through `--format json`. Remove
|
||||||
|
`defaults.render_format` and any custom prepared-output formatting code left
|
||||||
|
unused by the migration.
|
||||||
|
|
||||||
|
Share application configuration selection, collection loading, and applicable
|
||||||
|
request construction with generation so previews describe the corresponding
|
||||||
|
execution request. PromptKit continues to own preparation semantics.
|
||||||
|
|
||||||
|
Use the native result stream for preview output; consumers can capture or
|
||||||
|
redirect stdout to save it, as with generation. File-output convenience does
|
||||||
|
not justify retaining a separate preview command. Update maintained examples
|
||||||
|
and release migration guidance to use `promptkit show prepared`.
|
||||||
|
|
||||||
|
### Configuration selection and namespaces
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: fully adopt native configuration and namespace
|
||||||
|
conventions. Expose the `app` and `promptkit` configuration scopes through
|
||||||
|
ckconfig. `app` inspects Scriptorium's application settings; `promptkit`
|
||||||
|
inspects the framework configuration assembled from the selected sources.
|
||||||
|
Collections do not become separate configuration scopes. Application-only
|
||||||
|
inspection must not require constructing a PromptKit engine.
|
||||||
|
|
||||||
|
`--config` consistently selects Scriptorium's application configuration,
|
||||||
|
including when inspecting the `promptkit` scope. That configuration selects
|
||||||
|
the framework sources and collection-discovery file. Adopt the standard
|
||||||
|
`--overlay` spelling and use consistent source-selection and loading rules
|
||||||
|
across generation, preview, inspection, requirements, and other applicable
|
||||||
|
commands. Keep the established ConfigKit collection-import model.
|
||||||
|
|
||||||
|
Enable the native prompt, profile, and backend namespace selectors on
|
||||||
|
applicable commands. They independently scope short caller-supplied resource
|
||||||
|
IDs; qualified IDs remain exact selections. Namespace selection does not
|
||||||
|
rewrite stored references or change collection discovery. Keep configuration
|
||||||
|
scope, resource namespace, and profile selection distinct.
|
||||||
|
|
||||||
|
Use native inventory filters, including namespace selection and
|
||||||
|
`--all-namespaces`, and retain upstream default listing behavior. Support
|
||||||
|
standard temporary configuration overrides where the upstream loader supports
|
||||||
|
them. The reviewed PromptKit configuration scope does not support those
|
||||||
|
overrides; do not add local override semantics to compensate.
|
||||||
|
|
||||||
|
Do not add configurable default namespaces in the initial migration. Use
|
||||||
|
qualified IDs and explicit namespace flags when selecting namespaced resources,
|
||||||
|
while retaining upstream behavior for unqualified IDs. Configurable defaults
|
||||||
|
can be considered later if a need arises.
|
||||||
|
|
||||||
|
### Native inspection reports and consumer requirements
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: adopt native inspection reports and the native
|
||||||
|
`promptkit requirements show` interface for Narratio's early dependency
|
||||||
|
discovery. Its consumer needs and acceptance scenarios are recorded in the
|
||||||
|
[aligned Narratio proposal](narratio-feature-request.md). This direction is
|
||||||
|
accepted; Scriptorium integration remains to be implemented.
|
||||||
|
|
||||||
|
Consume native report fields without a Scriptorium-specific schema-version
|
||||||
|
envelope. Use native nonzero outcomes and diagnostics for invocation failures;
|
||||||
|
JSON report selection does not require JSON errors. Neither a separately
|
||||||
|
versioned envelope nor programmatic invocation-failure categories blocks this
|
||||||
|
migration. A future concrete need for either belongs in an upstream discussion.
|
||||||
|
|
||||||
|
PromptKit owns requirement classification, discovery completeness, and structured
|
||||||
|
discovery issues. Completeness is distinct from satisfied bindings or execution
|
||||||
|
readiness; Narratio owns comparison against its planned inputs. Keep early
|
||||||
|
discovery separate from concrete request validation. Use current exact resource
|
||||||
|
identities and native input/variable metadata, without restoring obsolete prompt
|
||||||
|
versions or inventing input schemas or variable-default semantics.
|
||||||
|
|
||||||
|
Standard prompt inspection includes captured messages; prepared preview includes
|
||||||
|
rendered content. Adopt these native reports without rebuilding Scriptorium's
|
||||||
|
previous summary projections, and explain the changed presentation in migration
|
||||||
|
guidance. Requirements discovery retains its distinct upstream content boundary.
|
||||||
|
|
||||||
|
### Application commands and standard request flags
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: use `run PROMPT_ID` for generation, with the prompt
|
||||||
|
as a required positional operand and no duplicate prompt-selection flag. Keep
|
||||||
|
`serve` as the application command for the HTTP service. Both are CommandKit
|
||||||
|
commands owned by Scriptorium, outside the reserved `config` and `promptkit`
|
||||||
|
families. The CLI migration does not redesign the HTTP API.
|
||||||
|
|
||||||
|
Reuse ckprompt's applicable resource, input, and execution flag bindings.
|
||||||
|
Preserve native parsing, explicit-value presence, repeated mapping semantics,
|
||||||
|
and PromptKit's interpretation of request values. Keep application-specific
|
||||||
|
configuration/source selection, `--report`/`--report-format`, server options,
|
||||||
|
and the whole-operation deadline separate from framework request controls.
|
||||||
|
|
||||||
|
Enable upstream convenience aliases consistently on applicable commands,
|
||||||
|
including `run`. Prefer their shorter spellings in user-facing documentation,
|
||||||
|
examples, migration guidance, and subprocess integration examples wherever they
|
||||||
|
are applicable and unambiguous. For example, prefer `--profile`, `--input-file`,
|
||||||
|
`--input-text`, and `--var` over their `--llm-*` equivalents. Canonical upstream
|
||||||
|
spellings remain available with identical semantics; the preference does not
|
||||||
|
remove or rename them.
|
||||||
|
|
||||||
|
Aliases retain upstream meanings. In particular, `--input` supplies literal
|
||||||
|
text; file references use `--input-file`. Migration guidance must explain this
|
||||||
|
change along with endpoint and timeout naming and repeated mapping values.
|
||||||
|
Use the canonical spelling where a shorter alias would be ambiguous; do not
|
||||||
|
assign an upstream alias a different application-specific meaning.
|
||||||
|
|
||||||
|
## Upstream baseline
|
||||||
|
|
||||||
|
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and
|
||||||
|
ckprompt **v0.10.0**. These are a review baseline, not a final dependency choice
|
||||||
|
for implementation. The [upstream consumer guide][upstream-guide] describes
|
||||||
|
their composition and supported extension points.
|
||||||
|
|
||||||
|
| Component | Relevant capabilities |
|
||||||
|
| --- | --- |
|
||||||
|
| CommandKit | Typed flags and operands with explicit-value presence, generated help and version, shared reporting and outcomes, optional shell completion. |
|
||||||
|
| ckconfig | Configuration scopes; validation, effective values, sources, explanations, and comparisons; temporary overrides where supported by the loader. |
|
||||||
|
| ckprompt | Prompt, profile, backend, namespace, and collection inventories; resource inspection; requirements discovery; optional concrete request validation, prepared-request previews, and provider smoke tests. Reusable request flags also serve application-owned commands. |
|
||||||
|
|
||||||
|
Scriptorium currently uses PromptKit v0.23.3 and ConfigKit v1.2.1. The reviewed
|
||||||
|
ckprompt release declares PromptKit v0.23.2 and ConfigKit v1.2.1. Validate the
|
||||||
|
chosen dependency combination while retaining Scriptorium's adopted PromptKit
|
||||||
|
fixes; the older declared minimum is not a reason to downgrade.
|
||||||
|
|
||||||
|
The [upstream CLI reference][upstream-cli] owns the detailed conventions. The
|
||||||
|
[current Scriptorium CLI](../cli.md) and
|
||||||
|
[subprocess contract](../integrations/subprocess.md) describe the starting point,
|
||||||
|
not requirements to reproduce during migration.
|
||||||
|
|
||||||
|
## Details for the feature roadmap
|
||||||
|
|
||||||
|
The product and interface direction is settled. The following details need
|
||||||
|
concrete implementation choices in the roadmap, but do not require another
|
||||||
|
architectural discussion before drafting it.
|
||||||
|
|
||||||
|
### Outcomes and process lifecycle
|
||||||
|
|
||||||
|
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
|
||||||
|
preserving its distinction between a completed content check reporting
|
||||||
|
`ValidationFailed` and an operational error. Select any necessary domain exit
|
||||||
|
code without reusing the current validation-failure exit 2, which conflicts with
|
||||||
|
CommandKit's usage convention. Also specify artifact/report delivery failures
|
||||||
|
using CommandKit's presentation-failure behavior where applicable. These are
|
||||||
|
adapter mappings, not a new application validation policy.
|
||||||
|
|
||||||
|
Signal cancellation and the whole-operation deadline remain application
|
||||||
|
responsibilities. Specify their mapping to the CommandKit invocation context
|
||||||
|
and PromptKit operation timeout, including the application deadline flag and
|
||||||
|
units, separately from the standard per-attempt timeout flag.
|
||||||
|
|
||||||
|
### File delivery
|
||||||
|
|
||||||
|
The roadmap and implementation plan specify ordinary report-file handling and
|
||||||
|
delivery ordering relative to stdout. The caller owns redirected destinations;
|
||||||
|
Scriptorium does not infer them or check for collisions with the report path.
|
||||||
|
Partial delivery follows native outcomes and the agreed result-availability
|
||||||
|
boundary.
|
||||||
|
|
||||||
|
### Adoption and verification
|
||||||
|
|
||||||
|
Confirm the released dependency combination, complete the application-specific
|
||||||
|
flag and loader mappings, and sequence replacement and removal of CLI code.
|
||||||
|
Define appropriate verification for the selected behavior and update canonical
|
||||||
|
documentation, examples, and release migration guidance as implementation lands.
|
||||||
|
|
||||||
|
## Roadmap handoff
|
||||||
|
|
||||||
|
The [adoption roadmap](commandkit-adoption.md) incorporates these decisions and
|
||||||
|
integration details. Keep implementation status there; retain this notepad as
|
||||||
|
the discussion record.
|
||||||
|
|
||||||
|
[upstream-guide]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/consumers/guide.md
|
||||||
|
[upstream-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md
|
||||||
@@ -1,231 +0,0 @@
|
|||||||
# ConfigKit Adoption
|
|
||||||
|
|
||||||
## Status And Intent
|
|
||||||
|
|
||||||
Implemented feature direction, drafted on 2026-09-26 and delivered through the
|
|
||||||
[implementation plan](implementation.md). This roadmap records the target
|
|
||||||
behavior and changes from the reviewed baseline; the implementation plan owns
|
|
||||||
sequencing, concrete interfaces, and verification evidence.
|
|
||||||
|
|
||||||
The user is adopting ConfigKit across an application suite to standardize
|
|
||||||
configuration semantics. Scriptorium will make a clean cutover to ConfigKit's
|
|
||||||
native conventions, including intentional breaking changes. Preserving the
|
|
||||||
legacy loader's behavior is not a goal: there will be no parallel legacy loader,
|
|
||||||
compatibility mode, or recreation of the old merging rules.
|
|
||||||
|
|
||||||
Alignment applies to application configuration, not to Promptkit-owned prompt,
|
|
||||||
profile, or schema definitions. Departures from ConfigKit conventions require an
|
|
||||||
application-specific reason or a genuine ownership boundary, not backward
|
|
||||||
compatibility alone. The [architecture policy](../policy/architecture.md) and
|
|
||||||
[ADR 0004](../adr/0004-definition-boundary.md) remain the scope boundaries.
|
|
||||||
|
|
||||||
## Reviewed Baseline (Historical)
|
|
||||||
|
|
||||||
Scriptorium consumes Promptkit v0.11.0. Its `internal/config` package uses
|
|
||||||
yaml.v3 directly and manually applies defaults, file settings, and CLI overrides.
|
|
||||||
It has a parser-specific integer decoder, ignores empty string overrides, and
|
|
||||||
treats an empty configuration file as defaults-only input. It has no application
|
|
||||||
configuration imports, selected overlays, or provenance/inspection interface.
|
|
||||||
The [configuration reference](../config.md), [CLI reference](../cli.md), and
|
|
||||||
[source internals](../internal/sources.md) own the current behavior.
|
|
||||||
|
|
||||||
The reviewed ConfigKit release is v0.4.0 at commit
|
|
||||||
`e6ced0d3d1194b58e0b3dc8970089471ba175258`. Adopt that published release as the
|
|
||||||
initial target, rather than a sibling checkout or unpublished replacement.
|
|
||||||
Its canonical references are:
|
|
||||||
|
|
||||||
- [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/config.md).
|
|
||||||
- [Consumer adoption guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/consumers/README.md).
|
|
||||||
- [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/releases/v0.4.0.md).
|
|
||||||
|
|
||||||
ConfigKit requires Go 1.25, within Scriptorium's existing toolchain requirement.
|
|
||||||
It selects `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Removing Scriptorium's direct parser
|
|
||||||
usage does not remove yaml.v3 from the dependency graph: Promptkit still uses it.
|
|
||||||
The initial review passed ConfigKit's default test suite and Scriptorium's
|
|
||||||
configuration and CLI tests; that is baseline evidence, not migration validation.
|
|
||||||
|
|
||||||
## Target Ownership And Loading Model
|
|
||||||
|
|
||||||
| Owner | Responsibility |
|
|
||||||
| --- | --- |
|
|
||||||
| ConfigKit | Application YAML policy, source acquisition, composition, overlays, typed decoding, explicit override application, provenance, and redacted inspection. |
|
|
||||||
| Scriptorium | Source discovery, application schema and defaults, CLI parsing, recorded application normalization, semantic validation, command prerequisites, and runtime conversion. |
|
|
||||||
| Promptkit | Framework definition formats, backend semantics, credential lookup, engine defaults, and prompt execution. |
|
|
||||||
|
|
||||||
`internal/config` becomes a small application-specific ConfigKit integration,
|
|
||||||
not a second general-purpose configuration framework. Execution and inspection
|
|
||||||
share one configuration definition and loading pipeline. Defaults, selected base
|
|
||||||
and imports, selected overlay, and explicit application CLI overrides participate
|
|
||||||
in ConfigKit's lifecycle; resolution and validation follow its upstream rules.
|
|
||||||
Normalization that changes inspected values is recorded through its resolver.
|
|
||||||
Runtime conversion does not perform a hidden second merge or apply new defaults
|
|
||||||
after the inspection snapshot has been created.
|
|
||||||
|
|
||||||
Scriptorium retains its application field names and domain meanings unless a
|
|
||||||
specific change below requires otherwise. ConfigKit's public root API replaces
|
|
||||||
direct YAML decoding and parser-specific hooks. Application defaults remain
|
|
||||||
Scriptorium-owned; omitted framework settings still delegate to Promptkit.
|
|
||||||
Backend conversion retains deterministic registration and engine-scoped shared
|
|
||||||
capacity state. This work does not change the HTTP request contract or move
|
|
||||||
configuration loading into each HTTP request.
|
|
||||||
|
|
||||||
## Native Configuration Semantics
|
|
||||||
|
|
||||||
The target accepts ConfigKit's upstream YAML grammar, schema binding, limits,
|
|
||||||
composition, and value-presence rules without a legacy preprocessing layer.
|
|
||||||
Migration-visible changes include:
|
|
||||||
|
|
||||||
- An existing empty file is invalid; `{}` expresses an empty application mapping.
|
|
||||||
Defaults-only operation with no discovered file uses `NoSource` instead.
|
|
||||||
- Explicit empty strings, false values, and zeroes replace defaults. They are
|
|
||||||
not silently treated as omission. Application validation still decides whether
|
|
||||||
a resulting value is meaningful for its field or selected command.
|
|
||||||
- Null follows the application's declared nullable types. It is not a universal
|
|
||||||
spelling for omission. Scalars and structs do not accept null merely because
|
|
||||||
the former parser tolerated it.
|
|
||||||
- Anchors, aliases, merge keys, explicit tags, additional documents, unsupported
|
|
||||||
scalar spellings, and coercions rejected by ConfigKit are rejected here too.
|
|
||||||
- ConfigKit's reserved `configkit` key and resource limits apply, including in
|
|
||||||
dynamic application data. These constraints do not apply to independently
|
|
||||||
loaded Promptkit definitions or HTTP request bodies.
|
|
||||||
- Dynamic integers in backend `extra_params` use ConfigKit's `int64`
|
|
||||||
representation. Runtime mapping preserves their supported value semantics
|
|
||||||
rather than reserializing through YAML or demanding the old Go scalar type.
|
|
||||||
|
|
||||||
Presence remains meaningful at the framework boundary: omitted/null
|
|
||||||
`transient_retries` delegates to Promptkit, while explicit zero disables retries;
|
|
||||||
omitted backend queue capacity differs from explicit zero. Application HTTP
|
|
||||||
size defaults and zero-as-unlimited behavior remain. No new value ranges or
|
|
||||||
backend restrictions are introduced merely to adopt the library.
|
|
||||||
|
|
||||||
## Discovery, Imports, Overlays, And Paths
|
|
||||||
|
|
||||||
Source discovery remains Scriptorium-owned. The target retains the documented
|
|
||||||
explicit `--config` selection and ordered system-location search. An explicitly
|
|
||||||
empty config path is invalid rather than an implicit request for a default file.
|
|
||||||
If neither implicit candidate exists, loading uses defaults only; a selected
|
|
||||||
file that fails loading is not silently replaced with defaults. No implicit
|
|
||||||
working-directory configuration search, environment overlay, or directory scan
|
|
||||||
is added.
|
|
||||||
|
|
||||||
Application configuration supports ConfigKit's explicit path and glob imports.
|
|
||||||
Imports compose disjoint definitions; repeated non-mapping definitions are
|
|
||||||
conflicts, not last-writer-wins overrides. There is no implicit `conf.d` scan.
|
|
||||||
|
|
||||||
An optional `--config-overlay` selects ConfigKit's one named overlay using its
|
|
||||||
standard `overlays/<name>.yml` location, naming rules, and merge behavior. No
|
|
||||||
overlay is selected by default. Selecting an active overlay without a base
|
|
||||||
source follows ConfigKit's rejection of overlays with `NoSource`; Scriptorium
|
|
||||||
does not invent a root. Application overlays do not replace `--profile`,
|
|
||||||
`profile_dir`, or Promptkit's execution-profile selection.
|
|
||||||
|
|
||||||
Use the selected file's canonical directory as ConfigKit's default import and
|
|
||||||
overlay root. This root governs configuration source traversal only. Values of
|
|
||||||
`prompt_dir`, `profile_dir`, `schema_dir`, and `server.artifact_root` retain
|
|
||||||
working-directory-relative interpretation; absolute values remain absolute.
|
|
||||||
This is an explicit application path policy, not an upstream requirement or a
|
|
||||||
legacy parsing mode. ConfigKit's consumer examples demonstrate alternatives but
|
|
||||||
do not mandate source-file-relative application paths. This adoption does not
|
|
||||||
extend import containment to application data or alter HTTP artifact containment.
|
|
||||||
|
|
||||||
## CLI Overrides And Configuration Inspection
|
|
||||||
|
|
||||||
Only flags explicitly supplied by the user become ConfigKit application
|
|
||||||
override records. Parser defaults do not overwrite file or overlay settings.
|
|
||||||
Explicit empty values are not dropped. The existing invocation-specific prompt,
|
|
||||||
profile, input, model, timeout, output, and reporting options remain invocation
|
|
||||||
state rather than new application configuration fields. In particular, the
|
|
||||||
run/render retry flag remains a request override; it does not mutate the engine's
|
|
||||||
application retry setting or backend state.
|
|
||||||
|
|
||||||
Expose application configuration validation, effective redacted YAML, source
|
|
||||||
provenance, and explanation of an individual configuration path. These are
|
|
||||||
included features, not merely library capabilities available for future work.
|
|
||||||
They use ConfigKit diagnostics and inspection records from the shared loading
|
|
||||||
pipeline, including defaults, imports, overlays, explicit CLI values, and
|
|
||||||
recorded normalization. No separate inspection-only interpretation is maintained.
|
|
||||||
|
|
||||||
Configuration inspection does not execute prompts, make provider calls, or
|
|
||||||
resolve API-key values. Application validation is not a promise that every
|
|
||||||
Promptkit backend or definition is valid or that a provider is reachable.
|
|
||||||
Command-specific execution prerequisites remain with the relevant command;
|
|
||||||
inspection can explain an incomplete application configuration without requiring
|
|
||||||
an executable prompt selection. The interface is a CLI configuration command
|
|
||||||
family, not a second CLI framework or an HTTP configuration endpoint; the
|
|
||||||
implementation plan specifies its concrete commands and mappings.
|
|
||||||
|
|
||||||
Safe diagnostics must not restore raw parser errors or configuration values
|
|
||||||
that ConfigKit deliberately suppresses. Effective output and explanation use
|
|
||||||
the upstream redacted renderers; they are inspection output, not guaranteed
|
|
||||||
reloadable configuration. Under the maintainer's selected policy, backend
|
|
||||||
`extra_params` are visible in effective output and explanation, including
|
|
||||||
historical values. There is no blanket container masking, sensitive-key heuristic,
|
|
||||||
or new selective-redaction configuration surface.
|
|
||||||
|
|
||||||
## Credential Boundary And Deferred Features
|
|
||||||
|
|
||||||
Existing `api_key_env` values remain environment-name strings passed to Promptkit.
|
|
||||||
They do not become ConfigKit `Secret` fields. ConfigKit eagerly resolves effective
|
|
||||||
typed references and requires nonempty values; that would change Promptkit's
|
|
||||||
optional/required and selected-credential behavior. This departure from the
|
|
||||||
secret-reference feature is an ownership decision, not compatibility plumbing.
|
|
||||||
Raw API-key fields remain unsupported under the existing architecture policy.
|
|
||||||
|
|
||||||
API-key values are the only secrets requiring ConfigKit redaction in this
|
|
||||||
adoption. The application configuration holds environment-variable names, not
|
|
||||||
those values, so inspection neither resolves nor contains the actual keys.
|
|
||||||
Reference names remain visible. Do not tag `api_key_env` as secret merely to
|
|
||||||
hide its name, add an eager key lookup, or mask unrelated application settings.
|
|
||||||
The existing raw-key prohibition and Promptkit boundary provide the protection
|
|
||||||
without introducing a redundant credential-bearing configuration field.
|
|
||||||
|
|
||||||
Secrets-directory bootstrap and application schema versioning are deferred until
|
|
||||||
there is a concrete application need. Their availability in ConfigKit does not
|
|
||||||
make them mandatory. Hot reload, runtime resource replacement, remote imports,
|
|
||||||
automatic migrations, and general environment-variable overlays are outside
|
|
||||||
this adoption. These are scope limits for this feature, not new permanent
|
|
||||||
prohibitions on future explicitly requested work.
|
|
||||||
|
|
||||||
## Required Changes And Completion Criteria
|
|
||||||
|
|
||||||
- Replace manual decoding/default/override machinery with the shared ConfigKit
|
|
||||||
integration and retain only application-specific discovery, rules, and mapping.
|
|
||||||
- Support imports and selected overlays across commands that load application
|
|
||||||
configuration, and deliver the configuration inspection capabilities above.
|
|
||||||
- Update application configuration types, presence handling, CLI explicit-set
|
|
||||||
mapping, and diagnostics to match the selected native semantics.
|
|
||||||
- Update maintained examples and canonical configuration, CLI, operations,
|
|
||||||
architecture, and internal documentation when behavior lands. Upstream generic
|
|
||||||
contracts remain linked rather than copied into a competing specification.
|
|
||||||
- Add proportionate integration coverage for the cutover: defaults-only input,
|
|
||||||
explicit values and nulls, imports/conflicts, overlays, CLI precedence,
|
|
||||||
inspection agreement and API-key non-disclosure, visible dynamic backend
|
|
||||||
parameters, unchanged credential ownership, and representative
|
|
||||||
execution/server startup.
|
|
||||||
ConfigKit owns exhaustive parser and composition tests; Scriptorium tests its
|
|
||||||
adoption and application boundaries.
|
|
||||||
- Pin the published dependency and maintain ConfigKit and YAML attribution under
|
|
||||||
the [OSS policy](../policy/oss.md), using imported-commit source/notice links
|
|
||||||
and applicable standard and companion license texts.
|
|
||||||
- Document migration in a release appropriate for the intentional breaking
|
|
||||||
configuration changes under the [release policy](../policy/release.md).
|
|
||||||
Release selection and publication remain separate preparation work; this
|
|
||||||
roadmap adds no release gate, network probe, or new distribution format.
|
|
||||||
|
|
||||||
Completion means one ConfigKit-native application configuration path serves
|
|
||||||
execution and inspection, the selected user-facing features work, and migrated
|
|
||||||
examples and regression coverage demonstrate the documented semantics. It does
|
|
||||||
not require adopting every ConfigKit feature or changing Promptkit definitions.
|
|
||||||
|
|
||||||
## Resolved Inspection Policy
|
|
||||||
|
|
||||||
On 2026-09-26 the maintainer selected no redaction for `extra_params` and limited
|
|
||||||
the relevant secret to the API key. Inspection therefore preserves parameter
|
|
||||||
values and environment-reference names, while actual API-key values remain
|
|
||||||
outside the application configuration pipeline. Visibility is intentional;
|
|
||||||
this is not a promise to detect secrets placed inside arbitrary parameter values.
|
|
||||||
|
|
||||||
The delivered `config show` and `config explain` commands use ConfigKit's
|
|
||||||
inspection writers without secret tags or a second redaction path. Both
|
|
||||||
effective and historical parameter values remain visible; `api_key_env` names
|
|
||||||
remain visible while Promptkit alone resolves selected credential values.
|
|
||||||
File diff suppressed because it is too large
Load Diff
166
docs/roadmap/narratio-feature-request.md
Normal file
166
docs/roadmap/narratio-feature-request.md
Normal file
@@ -0,0 +1,166 @@
|
|||||||
|
# Prompt input requirements for Narratio
|
||||||
|
|
||||||
|
Status: accepted direction, pending implementation through the CommandKit
|
||||||
|
migration. This proposal records Narratio's consumer needs and their mapping
|
||||||
|
to the native interface; it does not describe shipped Scriptorium behavior.
|
||||||
|
The [CommandKit notepad](commandkit-notepad.md) records the migration decisions.
|
||||||
|
|
||||||
|
## Consumer need
|
||||||
|
|
||||||
|
Narratio produces transcripts, extraction outputs, and generated artifacts in
|
||||||
|
a staged pipeline. It binds named inputs to a Scriptorium prompt when generating
|
||||||
|
each analysis artifact. A Narratio source ID and a prompt input name are separate
|
||||||
|
identities: for example, the source
|
||||||
|
`narratio.transcript.final_trimmed_markdown` might be supplied under the prompt
|
||||||
|
input name `transcript`.
|
||||||
|
|
||||||
|
Narratio needs to discover expected input names before running expensive
|
||||||
|
upstream stages and before the eventual input files exist. It can then show
|
||||||
|
operators how prompt inputs map to pipeline products and identify missing
|
||||||
|
bindings without reading prompt definitions or reproducing PromptKit's analysis.
|
||||||
|
|
||||||
|
## Selected native operation
|
||||||
|
|
||||||
|
Expose `scriptorium promptkit requirements show PROMPT_ID` through ckprompt.
|
||||||
|
Subprocess consumers select JSON with the standard `--format json` flag.
|
||||||
|
Default and explicit text output use the native YAML presentation.
|
||||||
|
The [upstream CLI contract][requirements-cli] owns syntax and report details.
|
||||||
|
|
||||||
|
Use the same application configuration and framework source selection as
|
||||||
|
execution, including `--config`, `--overlay`, and applicable application
|
||||||
|
selectors. The preferred native aliases `--profile`, `--var`, `--session-id`, and
|
||||||
|
prompt/profile namespace flags supply the relevant discovery context.
|
||||||
|
Preserve upstream selection semantics, including the prompt's default profile
|
||||||
|
when an explicit profile is omitted. Qualified IDs identify installed resources;
|
||||||
|
there is no separate prompt-version selector or reported prompt-version field.
|
||||||
|
|
||||||
|
The selected profile establishes identity, not execution readiness. Selecting
|
||||||
|
another profile does not itself change the prompt's discovered requirements.
|
||||||
|
Scriptorium's loading and request mapping must preserve the same effective
|
||||||
|
selection and applicable caller context across discovery and execution.
|
||||||
|
|
||||||
|
Discovery requires no input bindings or output-artifact path. PromptKit performs
|
||||||
|
no artifact loading, schema loading, credential resolution, message rendering,
|
||||||
|
capacity reservation, or model call for this operation. Reading configuration
|
||||||
|
and prompt resources needed to build the captured engine is expected. The
|
||||||
|
[PromptKit discovery contract][requirements-api] owns the analysis and its
|
||||||
|
limits.
|
||||||
|
|
||||||
|
## Native response and consumer interpretation
|
||||||
|
|
||||||
|
Consume the native JSON report directly, without a Scriptorium-specific wrapper
|
||||||
|
or schema-version field. Successful report delivery writes one JSON document to
|
||||||
|
stdout, with diagnostics on stderr under CommandKit's standard reporting rules.
|
||||||
|
Consumers requesting a report should not enable quiet mode.
|
||||||
|
|
||||||
|
| Field | Consumer meaning |
|
||||||
|
| --- | --- |
|
||||||
|
| `prompt_id`, `profile_id` | Exact selected resource identities. |
|
||||||
|
| `inputs` | Declared and recognizable template-referenced inputs, including exact `name`, requirement `kind`, `declared`, `content_type`, `description`, and `explanation`. |
|
||||||
|
| `variables` | Recognizable caller-variable keys with `name`, requirement `kind`, `supplied`, and `explanation`. |
|
||||||
|
| `complete` | Whether the supported dependency analysis is complete for the supplied context. |
|
||||||
|
| `issues` | Structured discovery limitations with a `code`, associated input or variable names where known, and a human-readable description. |
|
||||||
|
|
||||||
|
PromptKit sorts input and variable entries by exact name, and deduplicates and
|
||||||
|
orders issues by their code and associated names. Preserve empty inventories
|
||||||
|
and false values. Input metadata distinguishes absent/null values from an
|
||||||
|
explicitly empty string. Explanations and issue descriptions are for display;
|
||||||
|
Narratio must use structured fields rather than parse their prose.
|
||||||
|
|
||||||
|
The native input metadata includes content type and description. Current
|
||||||
|
PromptKit inputs have no per-input schema declaration to project. Do not infer
|
||||||
|
constraints from names or treat the output-validation schema as an input schema.
|
||||||
|
Variable `supplied` records exact-key presence, including an explicitly empty
|
||||||
|
value; this interface does not introduce a separate variable-default system.
|
||||||
|
|
||||||
|
Requirements reports exclude artifact payloads, prompt contents, and unrelated
|
||||||
|
supplied variable values. A supplied value used to resolve an input identifier
|
||||||
|
can appear as that identifier. Keep this native behavior without adding a custom
|
||||||
|
projection of the report.
|
||||||
|
|
||||||
|
The upstream report contract and adopted dependency versions govern the shape.
|
||||||
|
Migration documentation must identify relevant consumer changes; this proposal
|
||||||
|
adds no independent response-versioning mechanism or stronger compatibility
|
||||||
|
guarantee.
|
||||||
|
|
||||||
|
## Conditional and incomplete discovery
|
||||||
|
|
||||||
|
PromptKit classifies dependencies as required, optional, or conditional using
|
||||||
|
the supplied context and its supported template analysis. Recognizable references
|
||||||
|
only on known skipped paths can be optional. Explicit required declarations
|
||||||
|
still apply. Unavailable input contents, unresolved variable values or dynamic
|
||||||
|
names, and unsupported dependency-relevant constructs can leave discovery
|
||||||
|
incomplete. Valid templates are not rejected merely because the analysis cannot
|
||||||
|
fully resolve them.
|
||||||
|
|
||||||
|
Narratio must inspect both the requirements and discovery completeness:
|
||||||
|
|
||||||
|
- `complete: true` establishes discovery coverage, not satisfied bindings,
|
||||||
|
valid future input bytes, or execution readiness. Required inputs or missing
|
||||||
|
required variables may still be present.
|
||||||
|
- `complete: false` preserves useful findings and structured issues. An empty
|
||||||
|
partial inventory does not prove that no inputs are needed.
|
||||||
|
- A partial report can return status zero. An issue is not itself an invocation
|
||||||
|
failure. Narratio owns its policy for proceeding with incomplete dependency
|
||||||
|
information.
|
||||||
|
|
||||||
|
Once input artifacts exist, native `promptkit requirements validate` can check
|
||||||
|
a concrete request through preparation. It is a separate operation and must not
|
||||||
|
replace early discovery. Neither operation guarantees later generation success.
|
||||||
|
Changes to configuration or resources between invocations can change findings.
|
||||||
|
|
||||||
|
## Failures
|
||||||
|
|
||||||
|
Use CommandKit's native nonzero outcomes and diagnostic messages for selection,
|
||||||
|
configuration, operational, and report-delivery failures. JSON report selection
|
||||||
|
does not turn diagnostic messages into a categorized JSON error response.
|
||||||
|
Narratio can attach the diagnostic to its own artifact or pipeline context;
|
||||||
|
it must not depend on parsing the message to recover a stable error category.
|
||||||
|
|
||||||
|
Structured discovery issue codes belong to successful inspection reports and
|
||||||
|
are distinct from invocation failures. Follow PromptKit's distinction between
|
||||||
|
partial discovery and failures that return no inspection. Absence of a future
|
||||||
|
input artifact is not a discovery failure because discovery does not load it.
|
||||||
|
|
||||||
|
The accepted consumer requirement is a nonzero return code plus failure
|
||||||
|
information. If programmatic failure categories or separate schema versioning
|
||||||
|
become necessary, discuss them upstream rather than introducing local wrappers.
|
||||||
|
Neither is a prerequisite for this migration.
|
||||||
|
|
||||||
|
## Consumer acceptance scenarios
|
||||||
|
|
||||||
|
1. A prompt requires `transcript`, but Narratio binds only `session_transcript`.
|
||||||
|
The native inventory identifies the exact required name before either file
|
||||||
|
exists, allowing Narratio to identify the missing binding.
|
||||||
|
2. A template references an undeclared input. Recognizable references appear in
|
||||||
|
the inventory with `declared: false`; unsupported dependency analysis is
|
||||||
|
explicitly incomplete rather than silently claiming full coverage.
|
||||||
|
3. An optional glossary is reported with its native classification, allowing
|
||||||
|
Narratio to distinguish it from a required binding.
|
||||||
|
4. Variables resolve a supported conditional dependency. Unknown conditions
|
||||||
|
retain conditional findings or discovery issues according to PromptKit.
|
||||||
|
5. Selecting another qualified prompt or profile reports the corresponding
|
||||||
|
identities. Prompt selection changes the analyzed definition; profile
|
||||||
|
selection alone does not change its requirements.
|
||||||
|
6. Discovery works with no generated input files, model access, or generation
|
||||||
|
credentials when the selected configuration and resources are readable and
|
||||||
|
valid for discovery.
|
||||||
|
7. An unknown prompt or invalid profile selection returns nonzero with native
|
||||||
|
diagnostics suitable for Narratio to associate with the affected artifact.
|
||||||
|
8. Narratio treats a complete report with missing required bindings differently
|
||||||
|
from a complete, satisfied dependency check, and handles partial reports
|
||||||
|
without assuming that status zero establishes completeness.
|
||||||
|
9. Scriptorium's adapter uses consistent configuration, namespaces, and applicable
|
||||||
|
request context across discovery, validation, preview, and execution.
|
||||||
|
|
||||||
|
## Scope boundary
|
||||||
|
|
||||||
|
Narratio owns its source catalog, stage ordering, source-to-input bindings,
|
||||||
|
artifact dependency graph, and session availability checks. Scriptorium exposes
|
||||||
|
PromptKit's native requirements through CommandKit. Narratio source IDs and
|
||||||
|
pipeline concepts do not become part of that interface. A graph renderer, HTTP
|
||||||
|
endpoint, batch operation, and changes to generation behavior are outside this
|
||||||
|
request.
|
||||||
|
|
||||||
|
[requirements-cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/commit/d330d7637f2e7507eca931a899397222c82bc892/docs/cli.md#promptkit-requirements
|
||||||
|
[requirements-api]: https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/requirements.go
|
||||||
@@ -1,63 +1,223 @@
|
|||||||
# OSS Policy Adoption
|
# Standard Repository Policy Alignment
|
||||||
|
|
||||||
## Status
|
## Status And Intent
|
||||||
|
|
||||||
Completed on 2026-09-26. The upstream template work proposed here is now
|
Agreed and delivered on 2026-09-28. This roadmap replaces the
|
||||||
available and adopted locally. This document records the adoption; the
|
earlier licensing-only proposal with alignment of the complete applicable
|
||||||
[OSS policy](../policy/oss.md) is the canonical owner of the ongoing rules.
|
policy set and its supporting documentation. It defines the targeted end state
|
||||||
|
and required changes. Its completed implementation plan is preserved in Git at
|
||||||
|
`git show 8b6c12f912b28ac00016f047f9846798a5de95d9:docs/roadmap/implementation.md`.
|
||||||
|
|
||||||
The adopted baseline is the standard policy repository at commit
|
The next release summary should mention the policy and licensing alignment,
|
||||||
`eea8bcd21a964b395e31971077d7fddb445f2c28`:
|
the already-selected GPL-3.0-or-later application grant, and the separate
|
||||||
|
CC-BY-SA-4.0 treatment of adapted policy material. Version selection and
|
||||||
|
publication remain release preparation, not part of this delivery.
|
||||||
|
|
||||||
- OSS policy base version 1.1;
|
The goal is identical policy language across adopting projects except where a
|
||||||
- documentation policy base version 1.4; and
|
substantive, locally significant requirement or decision warrants customization.
|
||||||
- release policy base version 1.2.
|
Adopt upstream wording verbatim for non-substantive differences. Existing local
|
||||||
|
phrasing is not, by itself, a reason to retain a variation.
|
||||||
|
|
||||||
Each affected policy records its base version and local update date. Template
|
## Review Revision And Current Baseline
|
||||||
adoption instructions were removed. Unchanged agent, architecture, and testing
|
|
||||||
policies retain their existing versions.
|
|
||||||
|
|
||||||
## Adoption Outcome
|
The fixed upstream review revision is
|
||||||
|
`d84a38ebab26f048cafbe59a2246700c35d29843`.
|
||||||
|
Use the [adoption and update guide at that revision](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
|
||||||
|
for this adoption. The review compared current local documents directly with
|
||||||
|
that revision; reconstruction or assessment of historical adoption baselines
|
||||||
|
is not required.
|
||||||
|
|
||||||
- [Documentation ownership](../policy/documentation.md) distinguishes the
|
The reviewed Scriptorium revision is
|
||||||
project license, component entries, standard texts, and OSS policy.
|
`d6aecf5c50269b7d130dbf19f416a67454cd9778`. It has six adopted policies,
|
||||||
- The [contributor guide](../development.md) routes dependency, copied-asset,
|
without per-document Upstream Source metadata, and no `docs/policy/meta.md`.
|
||||||
attribution, and release-document work to the OSS policy.
|
The policy targets below supersede the earlier roadmap's narrower version
|
||||||
- [Component entries](../oss/attribution.md) cover the six selected direct and
|
targets.
|
||||||
transitive Go modules. Source and project-specific notice links identify the
|
|
||||||
imported commits. LGPL entries link directly to both LGPL v3 and GPL v3.
|
|
||||||
- Project-specific notices are linked upstream under the adopted house
|
|
||||||
interpretation. YAML's former local LICENSE and NOTICE copies were removed;
|
|
||||||
their history remains in Git. Missing upstream copyright statements are
|
|
||||||
identified in the affected entries rather than fabricated.
|
|
||||||
- The five applicable standard texts in `docs/oss/licenses/` match the upstream
|
|
||||||
reference collection byte-for-byte: GPL v3, LGPL v3, Apache 2.0, BSD 3-Clause,
|
|
||||||
and MIT. The reference collection documents their publisher/SPDX provenance.
|
|
||||||
Adoption removed a stray LGPL prefix, restored the complete Apache text,
|
|
||||||
separated the standard BSD text from the Go-specific notice, and added MIT.
|
|
||||||
- The [README](../../README.md) ends with friendly project-license and
|
|
||||||
attribution links. The [release policy](../policy/release.md) delegates footer
|
|
||||||
conventions to the OSS policy; the [release procedure](../release.md) retains
|
|
||||||
Scriptorium's immutable-tag URLs and existing hosted-body reuse.
|
|
||||||
|
|
||||||
## Preserved Scope
|
| Policy and proposed Upstream Source | Current base | Target base | Target treatment |
|
||||||
|
| --- | --- | --- | --- |
|
||||||
|
| [agents.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/agents.md) | 1.1 | 1.3 | Adopt shared rules verbatim, including commit discipline. |
|
||||||
|
| [architecture.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) | 1.1 | 1.3 | Adopt common principles and customize for Scriptorium's established boundaries. |
|
||||||
|
| [documentation.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) | 1.4 | 1.11 | Adopt shared language and tailor the canonical topic map. |
|
||||||
|
| [testing.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/testing.md) | 1.1 | 1.3 | Adopt shared guidance with focused local test ownership. |
|
||||||
|
| [release.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md) | 1.2 | 1.4 | Adopt common rules and retain justified release choices. |
|
||||||
|
| [oss.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md) | 1.1 | 1.8 | Adopt licensing, attribution, and reference-example conventions. |
|
||||||
|
| [meta.md](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/meta.md) | Not adopted | 1.0 | Add provenance, local authority, and upstream discovery. |
|
||||||
|
|
||||||
This adoption changes documentation and attribution, not Scriptorium's license,
|
Every existing policy needs language and provenance updates. No adopted policy
|
||||||
dependencies, application architecture, or release machinery. Published notes,
|
is entirely update-free, but established application decisions, dependency
|
||||||
tags, and assets remain unchanged. Existing source-release completion and
|
licenses, and release mechanics need no substantive change.
|
||||||
asynchronous binary-delivery behavior remain intact.
|
|
||||||
|
|
||||||
There is no new publication-time network check, approval gate, scanner, source
|
Current supporting-document gaps include the README's obsolete BSD project
|
||||||
bundle, downloadable license asset, or modified-dependency rebuild exercise.
|
license statement, the release procedure's two-link footer, an attribution
|
||||||
Concrete exceptions continue to receive the treatment specified by the adopted
|
document that does not follow the new exact House Format, and orientation
|
||||||
OSS policy; the house format is not a universal legal-sufficiency guarantee.
|
guidance that requires architecture reading even for unrelated work.
|
||||||
|
The architecture policy's command inventory also omits the implemented
|
||||||
|
`config` command family.
|
||||||
|
|
||||||
## Validation
|
## Target Policy Language And Local Customizations
|
||||||
|
|
||||||
The standard texts were compared against the upstream reference collection.
|
Remove every `Base Policy Template` section and its adoption instructions.
|
||||||
The BSD reference intentionally retains its publisher's trailing space in the
|
Replace instructional application-specific placeholders with actual decisions;
|
||||||
copyright placeholder; it is not reformatted to satisfy a whitespace check.
|
do not leave template examples describing nonexistent components.
|
||||||
Dependency commit references were resolved from Go module origin metadata or
|
|
||||||
the selected upstream tag, and affected local links and upstream attribution
|
Use upstream common language verbatim. Keep necessary local requirements
|
||||||
destinations were checked. No runtime code, commands, or executable examples
|
clearly identifiable rather than paraphrasing entire shared sections.
|
||||||
changed.
|
The following customizations are justified:
|
||||||
|
|
||||||
|
- **Architecture:** preserve PromptKit and ConfigKit ownership, full support
|
||||||
|
for valid PromptKit definitions, public dependency boundaries, HTTP artifact
|
||||||
|
containment, and simple predefined-prompt execution. Preserve caller-visible
|
||||||
|
request independence alongside shared engine and backend capacity state.
|
||||||
|
These are deliberate product and safety decisions, not generic template
|
||||||
|
choices. Adopt upstream architectural principles proportionately; they do
|
||||||
|
not require a wrapper or interface for every library. Correct the command
|
||||||
|
inventory and keep concrete package mechanics in internal documentation.
|
||||||
|
- **Documentation ownership:** tailor the topic map to the executable CLI and
|
||||||
|
HTTP application. Scriptorium does not offer a reusable public Go API;
|
||||||
|
consumer guidance covers executable use and migration to PromptKit.
|
||||||
|
PromptKit remains the owner of framework formats. Use upstream wording for
|
||||||
|
generic ownership, example, and ADR guidance instead of retaining redundant
|
||||||
|
local paraphrases. Preserve accepted ADR decisions and their history.
|
||||||
|
- **Testing:** retain a short project-specific ownership section distinguishing
|
||||||
|
Scriptorium's integration and adapter tests from upstream framework/parser
|
||||||
|
tests. This prevents duplication of PromptKit and ConfigKit test matrices.
|
||||||
|
HTTP containment and shared-capacity behavior justify focused adapter
|
||||||
|
coverage. Upstream observations about domain coverage are not quotas or a
|
||||||
|
hierarchy that displaces risk-based testing.
|
||||||
|
- **Release:** preserve branch-before-tag publication, annotated tags,
|
||||||
|
Linux amd64/arm64 binaries and checksums, and asynchronous artifact delivery.
|
||||||
|
Retain race testing because the server shares concurrent engine state and
|
||||||
|
source guards because local replacements, workspaces, or vendoring can hide
|
||||||
|
unpublished dependency substitutions. Keep gate rationale in policy and
|
||||||
|
concrete commands, targets, and publication choices in the release procedure.
|
||||||
|
Upstream's optional atomic-push approach does not require a new feature.
|
||||||
|
- **OSS:** use Scriptorium's actual GPL-3.0-or-later grant in the project
|
||||||
|
example. Preserve dependency grants and the settled House Format
|
||||||
|
interpretation for upstream notice links. The code grant does not extend
|
||||||
|
to separately licensed copied policy material.
|
||||||
|
|
||||||
|
No agent-policy exception is needed: upstream already preserves the local
|
||||||
|
commit authorization and safety boundaries. Stylistic preferences, alternate
|
||||||
|
wording, and generic elaboration do not justify additional exceptions.
|
||||||
|
|
||||||
|
## Provenance And Public Discovery
|
||||||
|
|
||||||
|
When adoption lands, each of the seven policies records its target
|
||||||
|
`Base Policy Version`, actual local adoption date in `Last Updated`, and
|
||||||
|
`Upstream Source` pointing to the exact corresponding file linked in the
|
||||||
|
table above. Do not substitute a repository homepage, moving branch, another
|
||||||
|
policy's URL, or a historical source revision for that per-document link.
|
||||||
|
Retain accurate provenance in later local edits.
|
||||||
|
|
||||||
|
The new local `docs/policy/meta.md` follows upstream language after removing
|
||||||
|
its template section. It establishes that adopted local policies govern the
|
||||||
|
repository and that upstream changes require deliberate adoption. Its public
|
||||||
|
discovery links remain current:
|
||||||
|
|
||||||
|
- [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy).
|
||||||
|
- [Current adoption and update guide](https://gitea.maximumdirect.net/eric/policy/src/branch/main/docs/adoption.md).
|
||||||
|
|
||||||
|
Adopted-source and example links remain commit-pinned. Preserve the valid
|
||||||
|
commit-pinned example links supplied in the selected OSS policy; their asset
|
||||||
|
revision need not be rewritten merely to match the policy review revision.
|
||||||
|
Public discovery and attribution in this agreed adoption supersede the earlier
|
||||||
|
instruction not to reference the policy repository.
|
||||||
|
|
||||||
|
## Orientation And Selective Reading
|
||||||
|
|
||||||
|
Adapt [the upstream agent orientation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/agents/AGENTS.md)
|
||||||
|
into [root AGENTS.md](../../AGENTS.md), preserving applicable existing
|
||||||
|
code-discovery instructions. It points to the local contributor guide and
|
||||||
|
requires the agent policy before recommendations, planning, or implementation;
|
||||||
|
it does not require reading the entire suite by default.
|
||||||
|
|
||||||
|
The [contributor guide](../development.md) gains the upstream Policy Reading
|
||||||
|
Guide table and associated selection rules, including the new meta policy.
|
||||||
|
Retain Scriptorium's task-specific contract guide alongside it. Architecture
|
||||||
|
reading becomes task-triggered rather than unconditional. Relevant policies
|
||||||
|
are read before governed decisions, multiple policies may apply, material
|
||||||
|
already available in context may be reused, and expanded scope triggers
|
||||||
|
expanded reading. Policy-reading triggers live here, not in the documentation
|
||||||
|
topic map.
|
||||||
|
|
||||||
|
## Licensing And Attribution
|
||||||
|
|
||||||
|
Follow the [canonical copied-policy attribution entry](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/policy-attribution.md).
|
||||||
|
Insert it directly beneath the prescribed attribution title and replace all
|
||||||
|
three placeholder URLs with the full review commit. Identify the actual
|
||||||
|
copied/adapted scope, including agent-orientation material and copied reading
|
||||||
|
guidance where used, rather than describing only policy files if additional
|
||||||
|
material is incorporated. Preserve creator, copyright, license, disclaimer,
|
||||||
|
and modification information through the supplied notices and links.
|
||||||
|
|
||||||
|
Required supporting changes:
|
||||||
|
|
||||||
|
- Add the complete, unmodified `docs/oss/licenses/CC-BY-SA-4.0.txt` from the
|
||||||
|
selected revision.
|
||||||
|
- Extend [COPYRIGHT](../../COPYRIGHT) to identify the adapted policy material
|
||||||
|
as CC-BY-SA-4.0 and point to attribution for exact scope. Preserve
|
||||||
|
Scriptorium's GPL-3.0-or-later code grant and existing [LICENSE](../../LICENSE).
|
||||||
|
Unrelated application documentation is not automatically relicensed.
|
||||||
|
- Reformat [attribution](../oss/attribution.md) to the v1.8 House Format:
|
||||||
|
`# Open Source Attribution Notices`, followed directly by component entries;
|
||||||
|
factual optional identification; supplied copyrights; SPDX expressions;
|
||||||
|
license/notice links with actual filename labels and terminal periods;
|
||||||
|
and `[Source](COMMIT_URL).`.
|
||||||
|
- Remove its introductory policy prose, missing-copyright filler, and
|
||||||
|
agent-authored license-scope explanations. Omit an unavailable copyright
|
||||||
|
field instead of explaining that none was invented. Preserve actual
|
||||||
|
required upstream notices, applicable license expressions, and imported
|
||||||
|
dependency revisions.
|
||||||
|
- Correct [README](../../README.md) to link its GPL v3 or later statement to
|
||||||
|
`COPYRIGHT`, followed by the attribution link.
|
||||||
|
- Update [the release procedure](../release.md) to use the prospective
|
||||||
|
`COPYRIGHT | LICENSE | ATTRIBUTION` footer, with absolute immutable-release
|
||||||
|
URLs for all three destinations. The existing hosted workflow continues
|
||||||
|
copying the checked-in release note unchanged.
|
||||||
|
|
||||||
|
The documented CC-BY-SA arrangement is agreed for this adoption. Original
|
||||||
|
licensing-example formatting has upstream's CC0 permission; using it alone
|
||||||
|
does not require a separate attribution entry. Reproduced license texts and
|
||||||
|
third-party notices retain their own terms.
|
||||||
|
|
||||||
|
## Local Materials And Upstream References
|
||||||
|
|
||||||
|
Keep applicable adopted policies, Scriptorium's adapted root orientation and
|
||||||
|
developer guide, actual project notices, attribution entries, and required
|
||||||
|
license texts locally.
|
||||||
|
|
||||||
|
Keep the upstream adoption guide, README, root AGENTS.md, developer guide, and
|
||||||
|
example collection upstream. Link to them as appropriate rather than copying
|
||||||
|
them into a parallel local handbook. The upstream `agents/AGENTS.md` is the
|
||||||
|
downstream orientation template, distinct from upstream's own root AGENTS.md.
|
||||||
|
Copy only needed standard license texts, not the entire reference collection.
|
||||||
|
|
||||||
|
## Scope And Completion Criteria
|
||||||
|
|
||||||
|
This work updates policy and supporting documentation. It does not change
|
||||||
|
application code, dependency versions or grants, release scripts, publication
|
||||||
|
mechanics, or accepted ADR decisions. No new scanner, recurring synchronization
|
||||||
|
check, license approval, publication-time network probe, or release gate is
|
||||||
|
introduced. Published releases, tags, notes, and assets remain unchanged.
|
||||||
|
|
||||||
|
Completion means:
|
||||||
|
|
||||||
|
- All seven policy files use the selected versions, accurate source links,
|
||||||
|
adoption dates, and upstream common wording, with template-only content
|
||||||
|
removed and local variations limited to the justified decisions above.
|
||||||
|
- Orientation and selective reading agree, and local links resolve without
|
||||||
|
depending on a sibling checkout.
|
||||||
|
- Policy attribution and document-license scope match the material actually
|
||||||
|
incorporated; required standard texts are complete and unmodified.
|
||||||
|
- README, attribution, release navigation, and still-operative roadmap
|
||||||
|
handoffs agree with the new conventions. Historical implementation evidence
|
||||||
|
remains available through the Git references in the implementation plan,
|
||||||
|
without making old footer directions current policy. The earlier
|
||||||
|
author-selected license change remains in the next release's preparation
|
||||||
|
context; publication remains separate work.
|
||||||
|
- Review checks the resulting rules, source/example URLs, notice facts, local
|
||||||
|
links, license-text fidelity, and final diff. Runtime tests are unnecessary
|
||||||
|
for documentation-only changes. A Git adoption record is sufficient; no
|
||||||
|
additional provenance database or recurring audit is required.
|
||||||
|
|
||||||
|
There are no unresolved policy choices for this scope.
|
||||||
|
|||||||
@@ -3,8 +3,9 @@
|
|||||||
## Status
|
## Status
|
||||||
|
|
||||||
Complete. This document records the delivered feature scope and targeted end
|
Complete. This document records the delivered feature scope and targeted end
|
||||||
state. The completed delivery plan is maintained in
|
state. The completed delivery plan is preserved at
|
||||||
[implementation.md](implementation.md); current behavior remains defined by
|
`git show e4405966c87c8a7843b340146e90cc1e515bef42:docs/roadmap/implementation.md`;
|
||||||
|
current behavior remains defined by
|
||||||
the canonical application contracts linked below.
|
the canonical application contracts linked below.
|
||||||
|
|
||||||
The durable product and integration boundary for this work is established by
|
The durable product and integration boundary for this work is established by
|
||||||
|
|||||||
374
docs/roadmap/promptkit.md
Normal file
374
docs/roadmap/promptkit.md
Normal file
@@ -0,0 +1,374 @@
|
|||||||
|
# PromptKit v0.12.0 Adoption
|
||||||
|
|
||||||
|
## Status And Intent
|
||||||
|
|
||||||
|
Drafted on 2026-10-03; source-selection and framework-inspection decisions
|
||||||
|
confirmed by the maintainer on 2026-10-04. The PromptKit v0.12.0 adoption has
|
||||||
|
been implemented and delivered after the complete audit passed on 2026-10-04.
|
||||||
|
This document remains target and decision context, not an implementation-stage
|
||||||
|
log. Release preparation remains separate; no release version has been
|
||||||
|
selected or published. No significant decisions remain open within this scope.
|
||||||
|
|
||||||
|
Adopt PromptKit's ConfigKit-native configuration boundary while preserving
|
||||||
|
Scriptorium's simple, request-independent execution model. As established in
|
||||||
|
[ADR 0004](../adr/0004-definition-boundary.md), valid prompt and profile
|
||||||
|
definitions for the selected PromptKit version should work without a narrower
|
||||||
|
Scriptorium field-level format. Library-only APIs are considered separately;
|
||||||
|
this upgrade does not turn Scriptorium into a workflow application.
|
||||||
|
|
||||||
|
The maintainer selected a native source cutover and full framework configuration
|
||||||
|
inspection. The latter uses upstream's native redaction in this new interface
|
||||||
|
only. These are deliberate product choices, not requirements inferred merely
|
||||||
|
from new library APIs.
|
||||||
|
|
||||||
|
## Reviewed Baseline And Upstream Target
|
||||||
|
|
||||||
|
The reviewed Scriptorium source is commit
|
||||||
|
`bb5006517b6c27dcbe56074f1d97140bf0999c48`; the last release is v0.15.0.
|
||||||
|
The completed ConfigKit adoption selects ConfigKit
|
||||||
|
v0.5.0. PromptKit remains v0.11.2, with the OpenRouter and Rakestrawhome `/v2`
|
||||||
|
catalog modules at v2.20260926.0.
|
||||||
|
|
||||||
|
Application configuration already uses one ConfigKit loading, inheritance,
|
||||||
|
resolution, validation, and inspection pipeline. Framework construction still
|
||||||
|
passes `prompt_dir` and `profile_dir` into the removed PromptKit directory
|
||||||
|
fields and registers application `backends` with `WithBackend`. Profile
|
||||||
|
inspection substitutes an empty prompt filesystem to avoid loading prompts.
|
||||||
|
Maintained prompt/profile files and inline test fixtures use the old embedded
|
||||||
|
`id`, `version`, and `base_profile` syntax.
|
||||||
|
|
||||||
|
The target is the published PromptKit v0.12.0 release at full commit
|
||||||
|
`4b8169da286917fde7875425bb32b799b12c6af3`. The published tag and downloaded
|
||||||
|
module identify that same revision. Canonical references are:
|
||||||
|
|
||||||
|
- [Release notes](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/releases/v0.12.0.md).
|
||||||
|
- [Framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/formats.md).
|
||||||
|
- [Consumer and migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/consumers/pkg-promptkit.md).
|
||||||
|
- [Configuration ownership decision](https://gitea.maximumdirect.net/eric/promptkit/src/commit/4b8169da286917fde7875425bb32b799b12c6af3/docs/adr/0001-configuration-boundary.md).
|
||||||
|
|
||||||
|
PromptKit now also selects ConfigKit v0.5.0, so no further ConfigKit upgrade is
|
||||||
|
needed. Go 1.25.5 remains sufficient. Its catalog selections are:
|
||||||
|
|
||||||
|
| Module | Version | Full source commit |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `promptkit-backend-openrouter/v3` | `v3.20260930.0` | `f17d208cb7ad1fb043cda2266cd3011d11b40aa0` |
|
||||||
|
| `promptkit-backend-rakestrawhome/v3` | `v3.20260930.0` | `993443d88c451901f4c917fa00c204fd3b54d28d` |
|
||||||
|
|
||||||
|
This review examined upstream contracts and the affected Scriptorium adapters,
|
||||||
|
configuration, presentation, examples, and tests. It did not establish that the
|
||||||
|
unmodified application builds against the new, incompatible construction API.
|
||||||
|
|
||||||
|
## Targeted End State
|
||||||
|
|
||||||
|
### Framework Ownership And Source Assembly
|
||||||
|
|
||||||
|
Scriptorium constructs engines through PromptKit's public root package and
|
||||||
|
`Config.Sources`. ConfigKit owns source composition, overlays, inheritance,
|
||||||
|
presence, null values, and resource origins. PromptKit owns final definition
|
||||||
|
validation, catalog contributions, backend completion, content capture,
|
||||||
|
preparation, execution, and capacity coordination.
|
||||||
|
|
||||||
|
An operator-selected source may contain any combination of keyed `backends`,
|
||||||
|
`profiles`, and versioned `prompts`. Do not partition or filter documents by
|
||||||
|
directory name, filename, or a Scriptorium copy of the framework schema.
|
||||||
|
Do not independently preflight domain fields in lower-priority definitions
|
||||||
|
that the final effective configuration replaces. Syntax and composition
|
||||||
|
failures remain upstream loading failures.
|
||||||
|
|
||||||
|
The selected application interface is an ordered `promptkit_sources` sequence.
|
||||||
|
Each entry selects either a `file` or a `directory` and contributes one caller
|
||||||
|
underlay, from lowest to highest priority. A directory uses
|
||||||
|
`promptkit.DirectoryInputs` and strictly composes its recursively discovered
|
||||||
|
YAML files. A file uses `configkit.File`
|
||||||
|
with declared imports enabled, so an entry document can compose fragments.
|
||||||
|
All caller groups follow PromptKit's maintained catalogs and owned defaults.
|
||||||
|
No separately exposed `Sources.Main` setting is needed for this interface.
|
||||||
|
|
||||||
|
For example, the target application shape is:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
promptkit_sources:
|
||||||
|
- directory: ./examples/prompts
|
||||||
|
- directory: ./examples/profiles
|
||||||
|
- file: ./deployment/promptkit.yml
|
||||||
|
schema_dir: ./examples/schemas
|
||||||
|
```
|
||||||
|
|
||||||
|
Directories retain the helper's default of disabled imports. Enabling imports
|
||||||
|
while also recursively discovering their YAML targets would include those
|
||||||
|
files twice in the same group, which ConfigKit rejects. Use a selected entry
|
||||||
|
file with imports for that layout; do not silently deduplicate, skip files, or
|
||||||
|
convert composition conflicts into precedence.
|
||||||
|
|
||||||
|
Under this decision, `prompt_dir`, `profile_dir`, application `backends`,
|
||||||
|
and their directory flags are replaced, not retained as a second configuration
|
||||||
|
model. Framework backend definitions live with the framework sources rather
|
||||||
|
than passing through Scriptorium's scalar backend schema. A repeatable
|
||||||
|
`--promptkit-source PATH` selects a replacement ordered source list for
|
||||||
|
engine-using commands; each path selects a regular file or directory using the
|
||||||
|
same rules. Only an explicitly supplied flag overrides the configured list.
|
||||||
|
|
||||||
|
Application source discovery, its imports and selected overlay, explicit CLI
|
||||||
|
override handling, and working-directory-relative application paths remain
|
||||||
|
unchanged. `--config-overlay` still selects an application overlay; it does not
|
||||||
|
implicitly select a PromptKit layer or profile. Framework priority is explicit
|
||||||
|
in the source list, with import/resource containment supplied by upstream for
|
||||||
|
each selected root. This is not a new global filesystem sandbox.
|
||||||
|
|
||||||
|
### Complete Definition Support
|
||||||
|
|
||||||
|
The target accepts the keyed v0.12.0 formats without compatibility rewriting:
|
||||||
|
profile and backend IDs are mapping keys, prompt IDs contain keyed string
|
||||||
|
versions, and `extends` replaces `base_profile`. Literal IDs and references
|
||||||
|
retain their exact spelling, including punctuation and meaningful whitespace;
|
||||||
|
filenames do not establish identities.
|
||||||
|
|
||||||
|
All supported prompt/profile fields continue to reach PromptKit, including
|
||||||
|
inputs, message roles and cache metadata, inline and file content, session
|
||||||
|
templates, output validation and repair, backend/endpoint selection,
|
||||||
|
credentials by environment name, generation controls, and provider parameters.
|
||||||
|
The upstream format reference, not this list, owns the complete contract.
|
||||||
|
|
||||||
|
Presence must survive the boundary: omission, explicit zero/false/blank, and
|
||||||
|
null are not interchangeable. Inheritance and layers recursively combine maps;
|
||||||
|
an empty map does not clear inherited entries. Backend defaults apply after
|
||||||
|
effective profile inheritance. Changing a model or backend no longer drops
|
||||||
|
unrelated explicitly inherited settings. Profile null suppression and explicit
|
||||||
|
zero controls must affect outbound requests as specified upstream.
|
||||||
|
|
||||||
|
Partial profiles remain valid when request overrides can complete them.
|
||||||
|
Scriptorium must not introduce a mandatory model, credential, default profile,
|
||||||
|
or directory prerequisite that prevents such a request. With the selected
|
||||||
|
source interface, engine construction may have no prompt collection; missing
|
||||||
|
request selections fail through PromptKit's ordinary public errors rather than
|
||||||
|
a required `prompt_dir` check. Source selection does not imply provider access
|
||||||
|
or credential availability.
|
||||||
|
|
||||||
|
### Captured Definitions And Runtime Lifecycle
|
||||||
|
|
||||||
|
Engine construction validates every final effective definition, including
|
||||||
|
unused entries, and captures message-file content and static template syntax.
|
||||||
|
Invalid unused definitions or unreadable message resources may therefore fail
|
||||||
|
startup or inspection before a request selects them. An overwritten domain
|
||||||
|
value is not independently rejected merely because it appears in history.
|
||||||
|
|
||||||
|
ConfigKit's structural directives now also apply to framework input mappings,
|
||||||
|
including dynamic provider maps. Document the reserved `extends` key and the
|
||||||
|
difference from literal runtime provider parameters; do not invent a quoting
|
||||||
|
escape or a second inheritance resolver.
|
||||||
|
|
||||||
|
Content files use their effective field's source context, including imported
|
||||||
|
and inherited content. Retain those contexts by passing actual upstream
|
||||||
|
inputs; do not flatten files into synthetic mappings that lose origins.
|
||||||
|
Application paths remain working-directory-relative, whereas framework message
|
||||||
|
resources follow PromptKit's source-relative contract. Schema and request
|
||||||
|
artifact reads remain preparation-time resources; credentials and provider
|
||||||
|
operations retain their documented runtime boundaries.
|
||||||
|
|
||||||
|
A server retains one constructed engine across its requests, with shared
|
||||||
|
backend capacity and queue accounting. Definition/message edits require a new
|
||||||
|
engine; for this scope, restarting the server is the supported way to obtain
|
||||||
|
one. CLI invocations naturally construct fresh engines. No file watcher,
|
||||||
|
reload endpoint, per-request server reconstruction, or durable state is added.
|
||||||
|
This is not a transactional snapshot of all external files or credentials.
|
||||||
|
|
||||||
|
### Definition And Application Inspection
|
||||||
|
|
||||||
|
`inspect prompt` and `inspect profile` use the same selected configuration
|
||||||
|
snapshot as execution. Remove the empty-prompt-filesystem substitution.
|
||||||
|
Profile inspection still does not need request inputs, schema reads, model
|
||||||
|
calls, or credential values, but constructing its engine now validates and
|
||||||
|
captures all selected definitions, including prompts. A partial target may be
|
||||||
|
inspected without imposing preparation's completeness requirements.
|
||||||
|
|
||||||
|
`config validate`, `show`, `sources`, and `explain` remain application
|
||||||
|
configuration operations without constructing an engine. Under the selected
|
||||||
|
source cutover, they show source selections rather than the contents of
|
||||||
|
PromptKit's separately loaded definitions. They are not framework validation.
|
||||||
|
The separate framework inspection family below supplies framework validation
|
||||||
|
and captured provenance.
|
||||||
|
|
||||||
|
### Captured Framework Configuration Inspection
|
||||||
|
|
||||||
|
Add the CLI command family `inspect configuration` with `validate`, `show`,
|
||||||
|
`sources`, and `explain` operations. It uses the same application settings,
|
||||||
|
source selections, and engine construction as other engine-using commands,
|
||||||
|
without requiring a prompt/profile selection or request inputs. Each invocation
|
||||||
|
constructs one engine; reporting uses that engine's captured public view rather
|
||||||
|
than loading definitions again.
|
||||||
|
|
||||||
|
- `validate` succeeds when the engine constructs successfully and produces no
|
||||||
|
success report. It validates final definitions and captures message resources,
|
||||||
|
not provider access, credential availability, or request-specific preparation.
|
||||||
|
- `show` writes the captured effective YAML through
|
||||||
|
`ConfigurationInspection.WriteEffective`.
|
||||||
|
- `sources` presents structured JSON source records from
|
||||||
|
`ConfigurationInspection.Sources`, including the source kinds, layers, and
|
||||||
|
underlay positions needed to distinguish maintained and operator inputs.
|
||||||
|
- `explain --path JSON_POINTER` uses the native explanation view and writer
|
||||||
|
for effective values and history. Root and literal mapping-key paths follow
|
||||||
|
the same JSON Pointer conventions as application `config explain`; IDs with
|
||||||
|
slashes or punctuation must not become dotted-path lookups.
|
||||||
|
|
||||||
|
Use PromptKit's public `InspectConfiguration` and its native writers and
|
||||||
|
records. Surface applicable load diagnostics safely on stderr; successful
|
||||||
|
reports go to stdout. Inspection does not resolve credential values, contact
|
||||||
|
a provider, or watch/reopen sources after construction. Captured effective
|
||||||
|
configuration is distinct from backend-completed `inspect profile` output and
|
||||||
|
request-specific prepared output; none substitutes for the others.
|
||||||
|
|
||||||
|
The maintainer explicitly accepts upstream's credential-shaped provider-key
|
||||||
|
redaction for this new family, including effective and historical values.
|
||||||
|
Fields such as `token` and `password` can therefore be redacted here while
|
||||||
|
remaining visible in existing profile/prepared views. This is not blanket
|
||||||
|
redaction of `extra_params`, a change to parameters sent to providers, or a
|
||||||
|
change to existing inspection interfaces. Environment-reference names and
|
||||||
|
ordinary unclassified content can remain visible. Reports may contain prompt
|
||||||
|
text, provider data, paths, and identifiers; native redaction is not a promise
|
||||||
|
that the output is safe to disclose.
|
||||||
|
|
||||||
|
### Requests, Presentation, And Disclosure
|
||||||
|
|
||||||
|
Keep CLI/HTTP request independence, presence-aware execution overrides,
|
||||||
|
generation/whole-run timeout separation, transient retries, execution reports,
|
||||||
|
artifact policy, and public error mapping. Preserve existing serialized results
|
||||||
|
unless an upstream change actually requires an application contract change.
|
||||||
|
Prepared/profile numeric values alone are not proof that a zero control was
|
||||||
|
sent; verify upstream presence through generation or recorded outbound requests.
|
||||||
|
The dependency change alone does not require a new presence DTO. Continue
|
||||||
|
mapping errors by public identity rather than message text.
|
||||||
|
|
||||||
|
Environment-variable names remain visible; resolved API keys are never
|
||||||
|
printed or serialized. Ordinary `extra_params` retain their selected visibility
|
||||||
|
where those values are presented. Moving definitions out of application
|
||||||
|
settings changes what `config` can inspect, not their sensitivity classification.
|
||||||
|
Do not silently adopt broader redaction rules for existing profile/prepared
|
||||||
|
inspection.
|
||||||
|
|
||||||
|
## Work Needed From The Baseline
|
||||||
|
|
||||||
|
- **Dependencies and attribution:** select released PromptKit v0.12.0, tidy the
|
||||||
|
module graph, and use its selected `/v3` catalogs without direct application
|
||||||
|
imports. Remove obsolete `/v2` modules and `gopkg.in/yaml.v3` if no remaining
|
||||||
|
imports require them. Update PromptKit/catalog component entries and exact
|
||||||
|
source, COPYRIGHT, and LICENSE links in `docs/oss/attribution.md`. The reviewed
|
||||||
|
grants remain LGPL-3.0-or-later for PromptKit and MIT for the catalogs; reuse
|
||||||
|
the applicable local license texts. Preserve unrelated attribution entries
|
||||||
|
and historical release documents.
|
||||||
|
- **Application settings and CLI:** implement the selected source interface
|
||||||
|
through `internal/config` and shared CLI override mapping. Retire the backend
|
||||||
|
document/runtime conversion and old directory fields, add ordered source
|
||||||
|
selection, and update command help and prerequisites. Application validation
|
||||||
|
checks its schema and selector shape;
|
||||||
|
framework acquisition and domain validation belong to engine construction.
|
||||||
|
- **Shared engine wiring:** replace removed fields/options with upstream
|
||||||
|
inputs and underlays, retain `SchemaDir`, `TransientRetries`, and runtime
|
||||||
|
collaborator injection, and use the same construction path for execution,
|
||||||
|
rendering, definition inspection, and serving. Preserve identifiable
|
||||||
|
PromptKit and ConfigKit causes and safe diagnostics. Remove obsolete
|
||||||
|
prompt-filesystem inspection scaffolding.
|
||||||
|
- **Captured framework inspection:** add the `inspect configuration` family
|
||||||
|
with `validate`, `show`, `sources`, and `explain` using the shared engine path
|
||||||
|
and its public captured inspection view. Reuse native YAML/explanation writers,
|
||||||
|
preserve useful source-layer information in JSON presentation, and keep application
|
||||||
|
`config` independent of framework loading. Apply the approved native
|
||||||
|
redaction exception only to this new family.
|
||||||
|
- **Definitions and fixtures:** migrate every maintained prompt/profile file
|
||||||
|
under `examples/` and `testdata/`, and inline definitions and construction
|
||||||
|
helpers in CLI, HTTP, and formatting tests. Replace old inheritance syntax
|
||||||
|
and move backend examples into framework definitions. Review old explicit
|
||||||
|
zeros for their changed meaning instead of preserving obsolete expectations
|
||||||
|
mechanically. Keep useful feature-adoption coverage; filenames need not be
|
||||||
|
renamed merely to reduce historical naming.
|
||||||
|
- **Focused adoption coverage:** use real ConfigKit/PromptKit boundaries for
|
||||||
|
representative source order, same-group conflicts, file imports, combined
|
||||||
|
documents, inherited source-relative content, exact IDs/version selection,
|
||||||
|
null suppression, explicit zero/false, and partial-profile completion.
|
||||||
|
Verify eager failures for unused final definitions and unchanged captured
|
||||||
|
message content after file edits on an existing engine. Retain shared-server
|
||||||
|
capacity, retry, cancellation, restricted artifact, output, and error tests.
|
||||||
|
Cover framework inspection's effective YAML, source layers, literal-key
|
||||||
|
explanations, diagnostics, and effective/historical native redaction without
|
||||||
|
provider calls. Protect the distinction between application validation and
|
||||||
|
framework validation, and unchanged visibility in existing profile/prepared
|
||||||
|
inspection. Avoid snapshots of incidental writer prose.
|
||||||
|
Own integration risks locally without recreating upstream's exhaustive parser
|
||||||
|
or inheritance matrices; use offline clients or `httptest` for generation.
|
||||||
|
- **Current documentation and migration guidance:** update owning contracts
|
||||||
|
in `docs/config.md`, `docs/cli.md`, and `docs/operations.md`, affected internal
|
||||||
|
docs, `docs/development.md`, architecture version/ownership references,
|
||||||
|
README, examples, and applicable consumer guidance. Link to v0.12.0 framework
|
||||||
|
contracts rather than copying their specification. Correct statements that
|
||||||
|
ConfigKit does not participate in framework loading. Explain the selected
|
||||||
|
source migration, framework-inspection command family and scoped redaction
|
||||||
|
exception, and engine-rebuild requirement. Preserve accepted ADR
|
||||||
|
decision content. Update HTTP docs only where observable behavior changes.
|
||||||
|
|
||||||
|
## Compatibility And Release Impact
|
||||||
|
|
||||||
|
This is an intentional breaking adoption, not a patch-only dependency refresh.
|
||||||
|
Users must migrate definitions, inheritance syntax, source assembly, and
|
||||||
|
assumptions about numeric presence, recursive maps, eager validation, and file
|
||||||
|
reload. Under the selected native interface they must also migrate the
|
||||||
|
application source selectors and move application backend definitions into
|
||||||
|
PromptKit source files. Provide small before/after examples and runnable
|
||||||
|
offline migration checks when implementation lands; no automatic legacy parser
|
||||||
|
or catalog alias layer is proposed.
|
||||||
|
|
||||||
|
PromptKit's maintained profile IDs remain supported, not frozen to fixed model
|
||||||
|
settings. Review used external catalog IDs against the selected catalogs; do
|
||||||
|
not promise live provider availability or preserve every volatile inventory ID.
|
||||||
|
Hashes remain opaque equality values, not cross-version identity guarantees.
|
||||||
|
|
||||||
|
Under the [release policy](../policy/release.md), the eventual release must be
|
||||||
|
a new pre-1.0 minor version. Do not select or publish a release in this work
|
||||||
|
set. The previously completed ConfigKit work may share that release; final
|
||||||
|
version, notes, and roadmap retirement belong to release preparation.
|
||||||
|
|
||||||
|
## Completion Criteria And Scope Limits
|
||||||
|
|
||||||
|
Adoption is complete when the released dependency graph is selected, the
|
||||||
|
approved source interface reaches the canonical framework boundary without
|
||||||
|
losing definition semantics, maintained examples and fixtures use v0.12.0,
|
||||||
|
and CLI/HTTP workflows and inspection meet the target above. The new framework
|
||||||
|
inspection family must use captured native reports with its explicitly scoped
|
||||||
|
redaction behavior, without changing existing inspection disclosure. Run the
|
||||||
|
existing development checks, affected offline examples, and link/diff checks,
|
||||||
|
with focused new integration tests for the actual migration risks.
|
||||||
|
|
||||||
|
This work does not add conversations, appended/follow-up messages,
|
||||||
|
prepared-handle coordination, semantic retry workflows, embedded configuration
|
||||||
|
bundles, framework internals, or application-owned framework validation.
|
||||||
|
Library availability alone does not justify additional commands, endpoints,
|
||||||
|
resource controls, recurring upstream probes, or release gates. Deferred
|
||||||
|
interfaces are scope choices for this adoption, not permanent prohibitions.
|
||||||
|
|
||||||
|
## Confirmed Decisions
|
||||||
|
|
||||||
|
### Native Source Cutover
|
||||||
|
|
||||||
|
The maintainer accepted the ordered `promptkit_sources` file/directory interface
|
||||||
|
and moving backend definitions out of application settings. This exposes
|
||||||
|
combined definitions, explicit priority, imports, and full presence/null
|
||||||
|
semantics through their canonical owner. It removes duplicated backend
|
||||||
|
representation and avoids translating absent scalar fields into presence-aware
|
||||||
|
overlays. The deliberate application schema and CLI migration accompanies the
|
||||||
|
unavoidable framework format migration.
|
||||||
|
|
||||||
|
Retaining the old directories and application backend surface was considered
|
||||||
|
but not selected: it would reduce migration while retaining duplicate backend
|
||||||
|
configuration, presence/null translation, and a less flexible source interface.
|
||||||
|
|
||||||
|
### Native Framework Inspection With A Scoped Redaction Exception
|
||||||
|
|
||||||
|
The maintainer selected `inspect configuration` using the captured native view,
|
||||||
|
including upstream redaction in this new interface only, rather than deferring
|
||||||
|
the feature. Provenance and history make layered configuration easier to
|
||||||
|
diagnose, and native writers avoid maintaining a parallel representation.
|
||||||
|
|
||||||
|
The accepted tradeoff is different provider-parameter visibility between this
|
||||||
|
new view and existing profile/prepared inspection. Existing API-key-only
|
||||||
|
redaction choices remain otherwise unchanged. Deferral or an upstream
|
||||||
|
consumer-selectable sensitivity API could avoid that difference, but neither is
|
||||||
|
a prerequisite for this adoption. Do not reconstruct private configuration to
|
||||||
|
bypass native writers or depend on an unpublished upstream interface.
|
||||||
@@ -1,77 +0,0 @@
|
|||||||
# Promptkit Upgrade Review Remediation
|
|
||||||
|
|
||||||
## Scope And Status
|
|
||||||
|
|
||||||
Review baseline: `e177d7c`, covering implementation commits after `5c3b0cf`.
|
|
||||||
This document records a resolved test-contract issue; it does not authorize
|
|
||||||
unrelated implementation changes. No runtime defect or missing planned feature
|
|
||||||
was identified in this review. Release preparation remains separate work.
|
|
||||||
|
|
||||||
## R1: Remove The Unrequested Context-Identity Invariant
|
|
||||||
|
|
||||||
Priority: P3 (low). Status: Complete.
|
|
||||||
|
|
||||||
Original location: `internal/adapter/http/handler_test.go:334–349`,
|
|
||||||
`TestHandlerRunTimeoutValidationAndContextMapping`, introduced in `7de2b02`.
|
|
||||||
|
|
||||||
The test's `child` field and `(ctx != parent) != tc.child` assertion required
|
|
||||||
the exact parent context object for omitted/null/zero timeouts and a distinct
|
|
||||||
object for a positive timeout. The requested contract concerns effective
|
|
||||||
deadlines and cancellation propagation, not Go interface identity. In
|
|
||||||
particular, a harmless derived context that preserves the parent's deadline,
|
|
||||||
values, and cancellation would fail the omission cases despite satisfying the
|
|
||||||
application contract.
|
|
||||||
|
|
||||||
This elevated an incidental implementation choice into a test-enforced
|
|
||||||
invariant, contrary to the [agent policy](../policy/agents.md) and
|
|
||||||
[testing policy](../policy/testing.md). The current handler's context behavior
|
|
||||||
is correct; this is a maintainability issue, not a runtime cancellation bug.
|
|
||||||
|
|
||||||
### Required Change
|
|
||||||
|
|
||||||
Remove the identity comparison and the identity-only table field. Retain
|
|
||||||
behavioral assertions that an earlier parent deadline is not extended and
|
|
||||||
parent cancellation reaches execution. For omitted/null/zero values, verify
|
|
||||||
that no deadline is introduced when the parent has none. Retain coverage of
|
|
||||||
positive deadlines and the distinction between a canceled execution context
|
|
||||||
and a provider-attempt timeout while the execution context remains live.
|
|
||||||
|
|
||||||
Use the existing runner seam and focused cases; do not introduce a context
|
|
||||||
wrapper framework, timer abstraction, new public guarantee, or production
|
|
||||||
refactor solely to change this test.
|
|
||||||
|
|
||||||
### Completion Criteria
|
|
||||||
|
|
||||||
- Tests protect effective deadline/cancellation behavior without requiring
|
|
||||||
context object identity.
|
|
||||||
- A semantically equivalent derived context does not fail merely because it
|
|
||||||
is a different object.
|
|
||||||
- Existing timeout validation and HTTP outcome coverage remains intact.
|
|
||||||
|
|
||||||
### Resolution And Validation
|
|
||||||
|
|
||||||
Removed the identity-only table field and context comparisons. The test now
|
|
||||||
checks effective deadlines, including omitted/null/zero requests with no
|
|
||||||
parent deadline, and explicitly checks that parent cancellation reaches the
|
|
||||||
runner. Existing positive-deadline integration tests and live-context
|
|
||||||
provider-timeout mapping remain intact. No production code changed.
|
|
||||||
|
|
||||||
Focused HTTP timeout tests, `go test ./...`, `go test -race ./...`,
|
|
||||||
`go vet ./...`, a native build outside the repository, and `git diff --check`
|
|
||||||
all passed after remediation.
|
|
||||||
|
|
||||||
## Original Review Verification
|
|
||||||
|
|
||||||
- `go test -race -count=1 ./...` passed, including retry, shared-capacity,
|
|
||||||
deadline, report, definition-conformance, and architecture-boundary tests.
|
|
||||||
- `go vet ./...` passed.
|
|
||||||
- A native `cmd/scriptorium` build passed, with output outside the repository.
|
|
||||||
- The selected dependency is Promptkit v0.11.0 with its intended v2 catalogs.
|
|
||||||
- Application code, tests, release automation, and historical releases were
|
|
||||||
not changed during this review.
|
|
||||||
|
|
||||||
The runtime ownership boundaries remain as intended: Promptkit owns framework
|
|
||||||
formats, execution, retries, and backend admission; Scriptorium owns executable
|
|
||||||
adapters, application settings, HTTP artifact policy, deadlines, and terminal
|
|
||||||
report presentation. No additional runtime restrictions, durable workflow
|
|
||||||
state, or extra release compliance gates were identified in the reviewed diff.
|
|
||||||
@@ -8,7 +8,8 @@ and publication remain separate release preparation. The baseline descriptions
|
|||||||
below record the state when this roadmap was written, not current behavior.
|
below record the state when this roadmap was written, not current behavior.
|
||||||
Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening
|
Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening
|
||||||
v0.10.0 catalog transition. This document defines the desired end state and
|
v0.10.0 catalog transition. This document defines the desired end state and
|
||||||
the changes from the current baseline. The [implementation plan](implementation.md)
|
the changes from the current baseline. The historical plan at
|
||||||
|
`git show 43eea5c7c41d2a8134b3dece60f3af5c98b8fd1c:docs/roadmap/implementation.md`
|
||||||
owns sequencing, concrete interface choices, verification steps, and unresolved
|
owns sequencing, concrete interface choices, verification steps, and unresolved
|
||||||
implementation decisions.
|
implementation decisions.
|
||||||
|
|
||||||
@@ -268,6 +269,6 @@ boundaries.
|
|||||||
the version-matched note remain release preparation.
|
the version-matched note remain release preparation.
|
||||||
|
|
||||||
Concrete interface decisions and the selected distribution approach are recorded
|
Concrete interface decisions and the selected distribution approach are recorded
|
||||||
in the completed [implementation plan](implementation.md). They do not expand
|
in that completed historical plan. They do not expand
|
||||||
the product into conversations, follow-up messages, application-owned semantic
|
the product into conversations, follow-up messages, application-owned semantic
|
||||||
retry loops, prepared-handle coordination, or multi-step workflows.
|
retry loops, prepared-handle coordination, or multi-step workflows.
|
||||||
|
|||||||
@@ -1,4 +0,0 @@
|
|||||||
backends:
|
|
||||||
local-gpu:
|
|
||||||
endpoint: http://localhost:11434/v1
|
|
||||||
api_key_env: LOCAL_GPU_API_KEY
|
|
||||||
2
examples/config-fragments/collections/10-backends.yml
Normal file
2
examples/config-fragments/collections/10-backends.yml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
promptkit_sources:
|
||||||
|
- file: ./examples/framework/backends.yml
|
||||||
2
examples/config-fragments/collections/20-profile.yml
Normal file
2
examples/config-fragments/collections/20-profile.yml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
promptkit_sources:
|
||||||
|
- file: ./examples/profiles/local-fast.yaml
|
||||||
2
examples/config-fragments/collections/30-prompt.yml
Normal file
2
examples/config-fragments/collections/30-prompt.yml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
promptkit_sources:
|
||||||
|
- file: ./examples/prompts/generic.markdown_summary.yaml
|
||||||
@@ -1,3 +1,5 @@
|
|||||||
prompt_dir: ./examples/prompts
|
promptkit_sources:
|
||||||
profile_dir: ./examples/profiles
|
- directory: ./examples/prompts
|
||||||
|
- directory: ./examples/profiles
|
||||||
|
- file: ./examples/framework/backends.yml
|
||||||
schema_dir: ./examples/schemas
|
schema_dir: ./examples/schemas
|
||||||
|
|||||||
10
examples/config.collections.yml
Normal file
10
examples/config.collections.yml
Normal file
@@ -0,0 +1,10 @@
|
|||||||
|
config:
|
||||||
|
sequences:
|
||||||
|
- destination: [promptkit_sources]
|
||||||
|
key: file
|
||||||
|
mode: upsert
|
||||||
|
imports:
|
||||||
|
- dir: config-fragments/collections
|
||||||
|
pattern: '*.yml'
|
||||||
|
required: true
|
||||||
|
schema_dir: ./examples/schemas
|
||||||
@@ -1,8 +1,8 @@
|
|||||||
# Select from the repository root; application paths remain working-directory-relative.
|
# Select from the repository root; application paths remain working-directory-relative.
|
||||||
configkit:
|
config:
|
||||||
imports:
|
imports:
|
||||||
- path: config-fragments/sources.yml
|
- path: config-fragments/sources.yml
|
||||||
- path: config-fragments/backend.yml
|
required: true
|
||||||
|
|
||||||
server:
|
server:
|
||||||
addr: :8080
|
addr: :8080
|
||||||
|
|||||||
2
examples/config.discovery.yml
Normal file
2
examples/config.discovery.yml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
promptkit_sources:
|
||||||
|
- file: ./examples/discovery/framework.yml
|
||||||
@@ -1,16 +1,9 @@
|
|||||||
prompt_dir: ./examples/prompts
|
promptkit_sources:
|
||||||
profile_dir: ./examples/profiles
|
- directory: ./examples/prompts
|
||||||
|
- directory: ./examples/profiles
|
||||||
|
- file: ./examples/framework/backends.yml
|
||||||
schema_dir: ./examples/schemas
|
schema_dir: ./examples/schemas
|
||||||
|
|
||||||
backends:
|
|
||||||
local-gpu:
|
|
||||||
endpoint: http://localhost:11434/v1
|
|
||||||
api_key_env: LOCAL_GPU_API_KEY
|
|
||||||
extra_params:
|
|
||||||
provider_option: enabled
|
|
||||||
concurrency_limit: 2
|
|
||||||
queue_capacity: 0
|
|
||||||
|
|
||||||
server:
|
server:
|
||||||
addr: 127.0.0.1:8080
|
addr: 127.0.0.1:8080
|
||||||
artifact_root: .
|
artifact_root: .
|
||||||
|
|||||||
6
examples/config.inheritance.yml
Normal file
6
examples/config.inheritance.yml
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
# Application paths are relative to the repository invocation directory.
|
||||||
|
promptkit_sources:
|
||||||
|
- directory: ./examples/prompts
|
||||||
|
- directory: ./examples/profiles
|
||||||
|
- file: ./examples/framework/inheritance.yml
|
||||||
|
schema_dir: ./examples/schemas
|
||||||
@@ -1,5 +1,7 @@
|
|||||||
prompt_dir: ./examples/prompts
|
promptkit_sources:
|
||||||
profile_dir: ./examples/profiles
|
- directory: ./examples/prompts
|
||||||
|
- directory: ./examples/profiles
|
||||||
|
- file: ./examples/framework/backends.yml
|
||||||
schema_dir: ./examples/schemas
|
schema_dir: ./examples/schemas
|
||||||
|
|
||||||
server:
|
server:
|
||||||
|
|||||||
12
examples/discovery/collections/review-repo/collection.yaml
Normal file
12
examples/discovery/collections/review-repo/collection.yaml
Normal file
@@ -0,0 +1,12 @@
|
|||||||
|
config:
|
||||||
|
imports:
|
||||||
|
- path: profiles/base.yaml
|
||||||
|
destination: [collections, review, profiles]
|
||||||
|
placement: sequence-item
|
||||||
|
required: true
|
||||||
|
- path: prompts/answer.yaml
|
||||||
|
destination: [collections, review, prompts]
|
||||||
|
placement: sequence-item
|
||||||
|
required: true
|
||||||
|
collections:
|
||||||
|
review: {}
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
id: base
|
||||||
|
endpoint: https://example.invalid/v1
|
||||||
|
model: review-example
|
||||||
@@ -0,0 +1,8 @@
|
|||||||
|
id: answer
|
||||||
|
default_profile: review/base
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Review this material and report your findings.
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
20
examples/discovery/collections/support-repo/collection.yml
Normal file
20
examples/discovery/collections/support-repo/collection.yml
Normal file
@@ -0,0 +1,20 @@
|
|||||||
|
config:
|
||||||
|
imports:
|
||||||
|
- path: profiles/base.yml
|
||||||
|
destination: [collections, support, profiles]
|
||||||
|
placement: sequence-item
|
||||||
|
required: true
|
||||||
|
- path: profiles/fast.yml
|
||||||
|
destination: [collections, support, profiles]
|
||||||
|
placement: sequence-item
|
||||||
|
required: true
|
||||||
|
- path: prompts/answer.yml
|
||||||
|
destination: [collections, support, prompts]
|
||||||
|
placement: sequence-item
|
||||||
|
required: true
|
||||||
|
- path: prompts/summarize.yml
|
||||||
|
destination: [collections, support, prompts]
|
||||||
|
placement: sequence-item
|
||||||
|
required: true
|
||||||
|
collections:
|
||||||
|
support: {}
|
||||||
2
examples/discovery/collections/support-repo/other.yml
Normal file
2
examples/discovery/collections/support-repo/other.yml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
repository_metadata:
|
||||||
|
purpose: This file is not a PromptKit framework input.
|
||||||
@@ -0,0 +1,4 @@
|
|||||||
|
id: base
|
||||||
|
endpoint: https://example.invalid/v1
|
||||||
|
model: support-example
|
||||||
|
temperature: 0.2
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
id: fast
|
||||||
|
extends: {id: base}
|
||||||
|
max_tokens: 256
|
||||||
@@ -0,0 +1,3 @@
|
|||||||
|
Answer the support request using this transcript:
|
||||||
|
|
||||||
|
{{input "transcript"}}
|
||||||
@@ -0,0 +1,12 @@
|
|||||||
|
id: answer
|
||||||
|
default_profile: support/fast
|
||||||
|
inputs:
|
||||||
|
- name: transcript
|
||||||
|
required: true
|
||||||
|
content_type: text/markdown
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content_file: ./answer.md
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
@@ -0,0 +1,8 @@
|
|||||||
|
id: summarize
|
||||||
|
default_profile: support/fast
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Summarize the support request concisely.
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
4
examples/discovery/framework.yml
Normal file
4
examples/discovery/framework.yml
Normal file
@@ -0,0 +1,4 @@
|
|||||||
|
config:
|
||||||
|
imports:
|
||||||
|
- glob: collections/*/collection.yml
|
||||||
|
- glob: collections/*/collection.yaml
|
||||||
8
examples/framework/backends.yml
Normal file
8
examples/framework/backends.yml
Normal file
@@ -0,0 +1,8 @@
|
|||||||
|
backends:
|
||||||
|
- id: local-gpu
|
||||||
|
endpoint: http://localhost:11434/v1
|
||||||
|
api_key_env: LOCAL_GPU_API_KEY
|
||||||
|
extra_params:
|
||||||
|
provider_option: enabled
|
||||||
|
concurrency_limit: 2
|
||||||
|
queue_capacity: 0
|
||||||
13
examples/framework/inheritance.yml
Normal file
13
examples/framework/inheritance.yml
Normal file
@@ -0,0 +1,13 @@
|
|||||||
|
backends:
|
||||||
|
- id: local-base
|
||||||
|
endpoint: http://localhost:11434/v1
|
||||||
|
api_key_env: LOCAL_GPU_API_KEY
|
||||||
|
concurrency_limit: 2
|
||||||
|
queue_capacity: 4
|
||||||
|
extra_params:
|
||||||
|
provider_option: true
|
||||||
|
- id: local-gpu
|
||||||
|
extends: {id: local-base}
|
||||||
|
queue_capacity: 0
|
||||||
|
extra_params:
|
||||||
|
provider_option: false
|
||||||
@@ -14,5 +14,6 @@
|
|||||||
"vars": {
|
"vars": {
|
||||||
"session_date": "2026-05-04"
|
"session_date": "2026-05-04"
|
||||||
},
|
},
|
||||||
"include_raw_output": false
|
"include_raw_output": false,
|
||||||
|
"include_execution_report": false
|
||||||
}
|
}
|
||||||
|
|||||||
2
examples/overlays/collection.yml
Normal file
2
examples/overlays/collection.yml
Normal file
@@ -0,0 +1,2 @@
|
|||||||
|
promptkit_sources:
|
||||||
|
- file: ./examples/profiles/local-gpu.yml
|
||||||
@@ -1,4 +1,5 @@
|
|||||||
id: local-fast
|
profiles:
|
||||||
|
- id: local-fast
|
||||||
endpoint: http://localhost:8000/v1
|
endpoint: http://localhost:8000/v1
|
||||||
model: gpt-4o-mini
|
model: gpt-4o-mini
|
||||||
temperature: 0.2
|
temperature: 0.2
|
||||||
|
|||||||
@@ -1,4 +1,5 @@
|
|||||||
id: local-gpu
|
profiles:
|
||||||
|
- id: local-gpu
|
||||||
backend: local-gpu
|
backend: local-gpu
|
||||||
model: local-model
|
model: local-model
|
||||||
reasoning_effort: low
|
reasoning_effort: low
|
||||||
|
|||||||
@@ -1,4 +1,5 @@
|
|||||||
id: local-quality
|
profiles:
|
||||||
|
- id: local-quality
|
||||||
endpoint: http://localhost:8000/v1
|
endpoint: http://localhost:8000/v1
|
||||||
model: gpt-4.1
|
model: gpt-4.1
|
||||||
temperature: 0.0
|
temperature: 0.0
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
id: dnd.session_recap
|
prompts:
|
||||||
version: "1.0.0"
|
- id: dnd.session_recap
|
||||||
default_profile: local-quality
|
default_profile: local-quality
|
||||||
description: Example D&D session recap prompt definition for demonstration only.
|
description: Example D&D session recap prompt definition for demonstration only.
|
||||||
inputs:
|
inputs:
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
id: generic.markdown_summary
|
prompts:
|
||||||
version: "1.0.0"
|
- id: generic.markdown_summary
|
||||||
default_profile: local-fast
|
default_profile: local-fast
|
||||||
description: Generic markdown summary from transcript and glossary.
|
description: Generic markdown summary from transcript and glossary.
|
||||||
inputs:
|
inputs:
|
||||||
|
|||||||
@@ -1,5 +1,5 @@
|
|||||||
id: generic.structured_events
|
prompts:
|
||||||
version: "1.0.0"
|
- id: generic.structured_events
|
||||||
default_profile: local-quality
|
default_profile: local-quality
|
||||||
description: Produce structured event JSON from a transcript.
|
description: Produce structured event JSON from a transcript.
|
||||||
inputs:
|
inputs:
|
||||||
|
|||||||
@@ -7,7 +7,6 @@ cd "$repo_root"
|
|||||||
go run ./cmd/scriptorium render \
|
go run ./cmd/scriptorium render \
|
||||||
--config ./examples/config.full.yml \
|
--config ./examples/config.full.yml \
|
||||||
--prompt generic.markdown_summary \
|
--prompt generic.markdown_summary \
|
||||||
--prompt-version 1.0.0 \
|
|
||||||
--profile local-gpu \
|
--profile local-gpu \
|
||||||
--session-id example-session \
|
--session-id example-session \
|
||||||
--reasoning-effort= \
|
--reasoning-effort= \
|
||||||
|
|||||||
15
go.mod
15
go.mod
@@ -1,17 +1,14 @@
|
|||||||
module gitea.maximumdirect.net/eric/scriptorium
|
module gitea.maximumdirect.net/eric/scriptorium
|
||||||
|
|
||||||
go 1.25.5
|
go 1.27.0
|
||||||
|
|
||||||
require (
|
require (
|
||||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.0
|
go.maximumdirect.net/configkit v1.2.1
|
||||||
gitea.maximumdirect.net/eric/promptkit v0.11.0
|
go.maximumdirect.net/promptkit v0.23.3
|
||||||
)
|
)
|
||||||
|
|
||||||
require (
|
require (
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1 // indirect
|
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 // indirect
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0 // indirect
|
go.yaml.in/yaml/v4 v4.0.0 // indirect
|
||||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
|
golang.org/x/text v0.44.0 // indirect
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
|
|
||||||
golang.org/x/text v0.14.0 // indirect
|
|
||||||
gopkg.in/yaml.v3 v3.0.1 // indirect
|
|
||||||
)
|
)
|
||||||
|
|||||||
28
go.sum
28
go.sum
@@ -1,20 +1,12 @@
|
|||||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.0 h1:fo+vKff3zTGeWqJIA38NtT84b6OUP//9ZmBH3lFuKgk=
|
|
||||||
gitea.maximumdirect.net/eric/ConfigKit v0.4.0/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit v0.11.0 h1:x7JguOUiInPVXK0GEitjyoRFqqvcuSTjYUvqJ+whtik=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit v0.11.0/go.mod h1:0zEBVlJJC+ldDdXazAgybYBXNSe74vwFx5dyOuSos/w=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1 h1:S2/Q/JDE+m8Ca3pDhAjVbfYrdlEhs9blj0STgNopHo0=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1/go.mod h1:a3VBbh9oaGXD6ruxhtwHj+AWW6DY/SSyby1QtMmYSUo=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0 h1:Y0EXc3eh12eKW2NrOviVqdk3oBo6UUjopt1YAa1B3Oc=
|
|
||||||
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0/go.mod h1:mtgD1E0SGm0e/I8Ffhz+AYX7GN7RKUWJXehNFIKHs4Y=
|
|
||||||
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
|
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
|
||||||
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
|
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
|
||||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
|
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
|
||||||
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
|
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
|
go.maximumdirect.net/configkit v1.2.1 h1:f+/6WjNl6CULbMr6ZSVwi4aty9rmuDfJlvpeU7I+HZM=
|
||||||
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
go.maximumdirect.net/configkit v1.2.1/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
|
||||||
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
|
go.maximumdirect.net/promptkit v0.23.3 h1:bKbrkluwfgXUsm0e/mxz/TpV9b60yUtJLVUROLsM3VU=
|
||||||
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
|
go.maximumdirect.net/promptkit v0.23.3/go.mod h1:vPFg76VXcffP0JBFMS2WADCHwV5FYvO2O4bvIoiDlwc=
|
||||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
|
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
|
||||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
|
||||||
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
golang.org/x/text v0.44.0 h1:YItdp/mQNGnsmrgpcdA5yQ3bnRxCfo/Tj/iByGW9GGo=
|
||||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
golang.org/x/text v0.44.0/go.mod h1:S4FR1waQ9LbjQTls97SyRjDaUUVkaM+cXwwuG/G+MwY=
|
||||||
|
|||||||
@@ -6,8 +6,8 @@ import (
|
|||||||
"fmt"
|
"fmt"
|
||||||
"io"
|
"io"
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
|
||||||
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
// applicationOverrides keeps explicit application flags separate from invocation state.
|
// applicationOverrides keeps explicit application flags separate from invocation state.
|
||||||
@@ -16,10 +16,8 @@ func applicationOverrides(fs *flag.FlagSet) []configkit.Override {
|
|||||||
fs.Visit(func(selected *flag.Flag) {
|
fs.Visit(func(selected *flag.Flag) {
|
||||||
var path configkit.Path
|
var path configkit.Path
|
||||||
switch selected.Name {
|
switch selected.Name {
|
||||||
case "prompt-dir":
|
case "promptkit-source":
|
||||||
path = configkit.Keys("prompt_dir")
|
path = configkit.Keys("promptkit_sources")
|
||||||
case "profile-dir":
|
|
||||||
path = configkit.Keys("profile_dir")
|
|
||||||
case "schema-dir":
|
case "schema-dir":
|
||||||
path = configkit.Keys("schema_dir")
|
path = configkit.Keys("schema_dir")
|
||||||
case "addr":
|
case "addr":
|
||||||
@@ -55,6 +53,7 @@ func loadApplicationSettings(configPath, overlay string, explicit bool, override
|
|||||||
func writeApplicationError(output io.Writer, label string, err error) {
|
func writeApplicationError(output io.Writer, label string, err error) {
|
||||||
var loadError *configkit.LoadError
|
var loadError *configkit.LoadError
|
||||||
if errors.As(err, &loadError) {
|
if errors.As(err, &loadError) {
|
||||||
|
_, _ = fmt.Fprintf(output, "%s error:\n", label)
|
||||||
if writeErr := configkit.WriteDiagnostics(output, loadError.Diagnostics()); writeErr != nil {
|
if writeErr := configkit.WriteDiagnostics(output, loadError.Diagnostics()); writeErr != nil {
|
||||||
_, _ = fmt.Fprintf(output, "%s diagnostic write error: %v\n", label, writeErr)
|
_, _ = fmt.Fprintf(output, "%s diagnostic write error: %v\n", label, writeErr)
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -6,8 +6,8 @@ import (
|
|||||||
"fmt"
|
"fmt"
|
||||||
"io"
|
"io"
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
|
||||||
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
type configurationSource struct {
|
type configurationSource struct {
|
||||||
@@ -93,8 +93,6 @@ func configCommand(args []string, stdout, stderr io.Writer) int {
|
|||||||
}
|
}
|
||||||
|
|
||||||
func registerConfigurationOverrides(fs *flag.FlagSet) {
|
func registerConfigurationOverrides(fs *flag.FlagSet) {
|
||||||
fs.String("prompt-dir", "", "prompt-definition directory override")
|
|
||||||
fs.String("profile-dir", "", "profile directory override")
|
|
||||||
fs.String("schema-dir", "", "schema directory override")
|
fs.String("schema-dir", "", "schema directory override")
|
||||||
fs.String("addr", "", "HTTP listen address override")
|
fs.String("addr", "", "HTTP listen address override")
|
||||||
fs.String("artifact-root", "", "HTTP artifact root override")
|
fs.String("artifact-root", "", "HTTP artifact root override")
|
||||||
|
|||||||
@@ -7,6 +7,7 @@ import (
|
|||||||
"io"
|
"io"
|
||||||
"os"
|
"os"
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
|
"reflect"
|
||||||
"strings"
|
"strings"
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
@@ -31,13 +32,43 @@ func TestConfigCommandsInspectApplicationWithoutEngine(t *testing.T) {
|
|||||||
}
|
}
|
||||||
case "sources":
|
case "sources":
|
||||||
var sources []configurationSource
|
var sources []configurationSource
|
||||||
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 1 || sources[0].Layer != "base" {
|
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 1 || sources[0].Layer != "main" {
|
||||||
t.Fatalf("unexpected source records: %q (%v)", stdout, err)
|
t.Fatalf("unexpected source records: %q (%v)", stdout, err)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func TestCollectionExampleLoadsAndRenders(t *testing.T) {
|
||||||
|
t.Chdir(filepath.Join("..", "..", ".."))
|
||||||
|
want := []appconfig.SourceSelection{
|
||||||
|
{File: "examples/framework/backends.yml"},
|
||||||
|
{File: "examples/profiles/local-fast.yaml"},
|
||||||
|
{File: "examples/prompts/generic.markdown_summary.yaml"},
|
||||||
|
}
|
||||||
|
for _, overlay := range []string{"", "collection"} {
|
||||||
|
result, err := appconfig.Load(appconfig.LoadOptions{Path: "examples/config.collections.yml", Explicit: true, Overlay: overlay})
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
expected := append([]appconfig.SourceSelection{}, want...)
|
||||||
|
if overlay != "" {
|
||||||
|
expected = append(expected, appconfig.SourceSelection{File: "examples/profiles/local-gpu.yml"})
|
||||||
|
}
|
||||||
|
if !reflect.DeepEqual(result.Config.PromptKitSources, expected) {
|
||||||
|
t.Fatalf("overlay %q selectors = %+v, want %+v", overlay, result.Config.PromptKitSources, expected)
|
||||||
|
}
|
||||||
|
args := []string{"--config", "examples/config.collections.yml", "--prompt", "generic.markdown_summary", "--input", "transcript=examples/fixtures/transcript.md", "--input", "glossary=examples/fixtures/glossary.yml"}
|
||||||
|
if overlay != "" {
|
||||||
|
args = append(args, "--config-overlay", overlay)
|
||||||
|
}
|
||||||
|
code, stdout, stderr := runCLICommand(t, renderCommand, args)
|
||||||
|
if code != ExitOK || !strings.Contains(stdout, "generic.markdown_summary") || !strings.Contains(stdout, "local-fast") {
|
||||||
|
t.Fatalf("collection render failed: code=%d stdout=%q stderr=%q", code, stdout, stderr)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
|
func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
|
||||||
dir := t.TempDir()
|
dir := t.TempDir()
|
||||||
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
|
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
|
||||||
@@ -45,17 +76,17 @@ func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
|
|||||||
}
|
}
|
||||||
base := filepath.Join(dir, "config.yml")
|
base := filepath.Join(dir, "config.yml")
|
||||||
for path, body := range map[string]string{
|
for path, body := range map[string]string{
|
||||||
base: "configkit:\n imports:\n - path: fragment.yml\nprompt_dir: ' ./before/../prompts '\nprofile_dir: ./profiles\n",
|
base: "config:\n imports:\n - path: fragment.yml\n required: true\npromptkit_sources:\n - directory: ' ./before/../prompts '\nschema_dir: ./schemas\n",
|
||||||
filepath.Join(dir, "fragment.yml"): "server:\n addr: :8081\n",
|
filepath.Join(dir, "fragment.yml"): "server:\n addr: :8081\n",
|
||||||
filepath.Join(dir, "overlays", "local.yml"): "server:\n addr: :9090\n",
|
filepath.Join(dir, "overlays", "local.yml"): "promptkit_sources:\n - directory: ./overlay-prompts\nserver:\n addr: :9090\n",
|
||||||
} {
|
} {
|
||||||
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
|
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
args := []string{"--config", base, "--config-overlay", "local", "--profile-dir=", "--addr", ":7070"}
|
args := []string{"--config", base, "--config-overlay", "local", "--schema-dir=", "--addr", ":7070"}
|
||||||
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"show"}, args...))
|
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"show"}, args...))
|
||||||
if code != ExitOK || stderr != "" || !strings.Contains(stdout, "prompt_dir: prompts") || !strings.Contains(stdout, "profile_dir: ''") || !strings.Contains(stdout, "addr: :7070") {
|
if code != ExitOK || stderr != "" || !strings.Contains(stdout, "directory: overlay-prompts") || !strings.Contains(stdout, "schema_dir: ''") || !strings.Contains(stdout, "addr: :7070") || strings.Contains(stdout, "before/../prompts") {
|
||||||
t.Fatalf("resolved effective output changed: code=%d out=%q err=%q", code, stdout, stderr)
|
t.Fatalf("resolved effective output changed: code=%d out=%q err=%q", code, stdout, stderr)
|
||||||
}
|
}
|
||||||
code, stdout, stderr = runCLICommand(t, configCommand, append([]string{"sources"}, args...))
|
code, stdout, stderr = runCLICommand(t, configCommand, append([]string{"sources"}, args...))
|
||||||
@@ -66,42 +97,52 @@ func TestConfigCommandsExposeComposedSourcesAndResolvedValues(t *testing.T) {
|
|||||||
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 5 {
|
if err := json.Unmarshal([]byte(stdout), &sources); err != nil || len(sources) != 5 {
|
||||||
t.Fatalf("unexpected composed source records: %+v (%v)", sources, err)
|
t.Fatalf("unexpected composed source records: %+v (%v)", sources, err)
|
||||||
}
|
}
|
||||||
for i, layer := range []string{"base", "base", "overlay", "cli", "cli"} {
|
for i, layer := range []string{"main", "main", "overlay", "cli", "cli"} {
|
||||||
if string(sources[i].Layer) != layer {
|
if string(sources[i].Layer) != layer {
|
||||||
t.Fatalf("source %d layer = %q, want %q", i, sources[i].Layer, layer)
|
t.Fatalf("source %d layer = %q, want %q", i, sources[i].Layer, layer)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestConfigInspectionKeepsReferencesAndOrdinaryParameters(t *testing.T) {
|
func TestApplicationInspectionDoesNotAcquireFrameworkSources(t *testing.T) {
|
||||||
const name = "SCRIPTORIUM_CONFIG_TEST_API_KEY"
|
dir := t.TempDir()
|
||||||
const secret = "synthetic-secret-value-should-not-appear"
|
frameworkPath := filepath.Join(dir, "invalid-framework.yml")
|
||||||
path := writeAppConfigFile(t, `backends:
|
if err := os.WriteFile(frameworkPath, []byte("not: [valid\n"), 0o600); err != nil {
|
||||||
synthetic:
|
|
||||||
endpoint: http://127.0.0.1:1/v1
|
|
||||||
api_key_env: SCRIPTORIUM_CONFIG_TEST_API_KEY
|
|
||||||
extra_params:
|
|
||||||
visible_parameter: synthetic-ordinary-value
|
|
||||||
`)
|
|
||||||
t.Setenv(name, secret)
|
|
||||||
for _, present := range []bool{true, false} {
|
|
||||||
if !present {
|
|
||||||
if err := os.Unsetenv(name); err != nil {
|
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
}
|
for _, frameworkSource := range []struct {
|
||||||
code, stdout, stderr := runCLICommand(t, configCommand, []string{"show", "--config", path})
|
name string
|
||||||
if code != ExitOK || stderr != "" || !strings.Contains(stdout, name) || !strings.Contains(stdout, "synthetic-ordinary-value") || strings.Contains(stdout, secret) {
|
path string
|
||||||
t.Fatalf("credential boundary changed with present=%t: code=%d out=%q err=%q", present, code, stdout, stderr)
|
}{
|
||||||
|
{name: "invalid definition", path: frameworkPath},
|
||||||
|
{name: "missing path", path: filepath.Join(dir, "missing-framework.yml")},
|
||||||
|
} {
|
||||||
|
t.Run(frameworkSource.name, func(t *testing.T) {
|
||||||
|
path := writeAppConfigFile(t, "promptkit_sources:\n - file: "+frameworkSource.path+"\n")
|
||||||
|
for _, args := range [][]string{
|
||||||
|
{"validate"},
|
||||||
|
{"show"},
|
||||||
|
{"sources"},
|
||||||
|
{"explain", "--path", "/promptkit_sources/0/file"},
|
||||||
|
} {
|
||||||
|
code, stdout, stderr := runCLICommand(t, configCommand, append(args, "--config", path))
|
||||||
|
if code != ExitOK || stderr != "" {
|
||||||
|
t.Fatalf("application inspection acquired configured framework source: args=%q code=%d out=%q err=%q", args, code, stdout, stderr)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
result, err := appconfig.Load(appconfig.LoadOptions{Path: path, Explicit: true})
|
})
|
||||||
if err != nil {
|
|
||||||
t.Fatal(err)
|
|
||||||
}
|
}
|
||||||
settings := appconfig.Settings(result.Config)
|
}
|
||||||
if len(settings.Backends) != 1 || settings.Backends[0].ExtraParams["visible_parameter"] != "synthetic-ordinary-value" {
|
|
||||||
t.Fatalf("runtime backend parameters changed: %+v", settings.Backends)
|
func TestConfigCommandsRejectRetiredFrameworkFields(t *testing.T) {
|
||||||
|
for _, field := range []string{"prompt_dir", "profile_dir", "backends"} {
|
||||||
|
t.Run(field, func(t *testing.T) {
|
||||||
|
path := writeAppConfigFile(t, field+": {}\n")
|
||||||
|
code, stdout, stderr := runCLICommand(t, configCommand, []string{"validate", "--config", path})
|
||||||
|
if code != ExitRuntimeError || stdout != "" || stderr == "" {
|
||||||
|
t.Fatalf("retired application field %q was accepted: code=%d out=%q err=%q", field, code, stdout, stderr)
|
||||||
|
}
|
||||||
|
})
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -127,51 +168,36 @@ func TestConfigCommandFailuresDoNotProduceSuccessfulOutput(t *testing.T) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestConfigExplainUsesResolvedHistoryAndKeepsParametersVisible(t *testing.T) {
|
func TestConfigExplainUsesResolvedHistory(t *testing.T) {
|
||||||
dir := t.TempDir()
|
dir := t.TempDir()
|
||||||
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
|
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0o755); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
base := filepath.Join(dir, "config.yml")
|
base := filepath.Join(dir, "config.yml")
|
||||||
for path, body := range map[string]string{
|
for path, body := range map[string]string{
|
||||||
base: `prompt_dir: " ./prompts/../prompts "
|
base: `promptkit_sources:
|
||||||
|
- directory: " ./prompts/../prompts "
|
||||||
server:
|
server:
|
||||||
addr: :8080
|
addr: :8080
|
||||||
backends:
|
|
||||||
"team/blue~1":
|
|
||||||
endpoint: http://127.0.0.1:1/v1
|
|
||||||
api_key_env: SCRIPTORIUM_EXPLAIN_KEY
|
|
||||||
extra_params:
|
|
||||||
"0": base-parameter
|
|
||||||
`,
|
|
||||||
filepath.Join(dir, "overlays", "local.yml"): `server:
|
|
||||||
addr: :9090
|
|
||||||
backends:
|
|
||||||
"team/blue~1":
|
|
||||||
extra_params:
|
|
||||||
"0": overlay-parameter
|
|
||||||
`,
|
`,
|
||||||
|
filepath.Join(dir, "overlays", "local.yml"): "server:\n addr: :9090\n",
|
||||||
} {
|
} {
|
||||||
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
|
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
const keyValue = "synthetic-key-bytes-must-not-appear"
|
|
||||||
t.Setenv("SCRIPTORIUM_EXPLAIN_KEY", keyValue)
|
|
||||||
args := []string{"--config", base, "--config-overlay", "local", "--addr", ":9090"}
|
args := []string{"--config", base, "--config-overlay", "local", "--addr", ":9090"}
|
||||||
for _, tc := range []struct {
|
for _, tc := range []struct {
|
||||||
pointer string
|
pointer string
|
||||||
want []string
|
want []string
|
||||||
}{
|
}{
|
||||||
{pointer: "/server/addr", want: []string{":8080", ":9090", "--addr"}},
|
{pointer: "/server/addr", want: []string{":8080", ":9090", "--addr"}},
|
||||||
{pointer: "/prompt_dir", want: []string{"normalized application path", "prompts"}},
|
{pointer: "/promptkit_sources/0/directory", want: []string{"normalized application path", "prompts"}},
|
||||||
{pointer: "/backends/team~1blue~01/extra_params/0", want: []string{"base-parameter", "overlay-parameter"}},
|
{pointer: "", want: []string{"promptkit_sources", "server", "addr"}},
|
||||||
{pointer: "/backends/team~1blue~01/api_key_env", want: []string{"SCRIPTORIUM_EXPLAIN_KEY"}},
|
|
||||||
{pointer: "", want: []string{"base-parameter", "overlay-parameter", "SCRIPTORIUM_EXPLAIN_KEY"}},
|
|
||||||
} {
|
} {
|
||||||
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", tc.pointer}, args...))
|
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", tc.pointer}, args...))
|
||||||
if code != ExitOK || stderr != "" || strings.Contains(stdout, keyValue) {
|
if code != ExitOK || stderr != "" {
|
||||||
t.Fatalf("explain %q failed or disclosed key: code=%d out=%q err=%q", tc.pointer, code, stdout, stderr)
|
t.Fatalf("explain %q failed: code=%d out=%q err=%q", tc.pointer, code, stdout, stderr)
|
||||||
}
|
}
|
||||||
for _, want := range tc.want {
|
for _, want := range tc.want {
|
||||||
if !strings.Contains(stdout, want) {
|
if !strings.Contains(stdout, want) {
|
||||||
@@ -179,13 +205,6 @@ backends:
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
if err := os.Unsetenv("SCRIPTORIUM_EXPLAIN_KEY"); err != nil {
|
|
||||||
t.Fatal(err)
|
|
||||||
}
|
|
||||||
code, stdout, stderr := runCLICommand(t, configCommand, append([]string{"explain", "--path", "/backends/team~1blue~01/api_key_env"}, args...))
|
|
||||||
if code != ExitOK || stderr != "" || !strings.Contains(stdout, "SCRIPTORIUM_EXPLAIN_KEY") || strings.Contains(stdout, keyValue) {
|
|
||||||
t.Fatalf("absent credential changed reference explanation: code=%d out=%q err=%q", code, stdout, stderr)
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestConfigExplainRejectsUnknownOrMalformedPaths(t *testing.T) {
|
func TestConfigExplainRejectsUnknownOrMalformedPaths(t *testing.T) {
|
||||||
|
|||||||
82
internal/adapter/cli/discovery_test.go
Normal file
82
internal/adapter/cli/discovery_test.go
Normal file
@@ -0,0 +1,82 @@
|
|||||||
|
package cli
|
||||||
|
|
||||||
|
import (
|
||||||
|
"fmt"
|
||||||
|
"os"
|
||||||
|
"path/filepath"
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestCollectionCheckoutDiscoveryAcrossInvocations(t *testing.T) {
|
||||||
|
fixture, err := filepath.Abs(filepath.Join("..", "..", "..", "examples", "discovery"))
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
for _, tc := range []struct {
|
||||||
|
name string
|
||||||
|
first string
|
||||||
|
second string
|
||||||
|
}{
|
||||||
|
{name: "yml then yaml", first: "support-repo", second: "review-repo"},
|
||||||
|
{name: "yaml then yml", first: "review-repo", second: "support-repo"},
|
||||||
|
} {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
framework, err := os.ReadFile(filepath.Join(fixture, "framework.yml"))
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
frameworkPath := filepath.Join(root, "framework.yml")
|
||||||
|
if err := os.WriteFile(frameworkPath, framework, 0o644); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
collections := filepath.Join(root, "collections")
|
||||||
|
if err := os.MkdirAll(collections, 0o755); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
install := func(name string) {
|
||||||
|
t.Helper()
|
||||||
|
if err := os.CopyFS(filepath.Join(collections, name), os.DirFS(filepath.Join(fixture, "collections", name))); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
config := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkPath))
|
||||||
|
input := filepath.Join(root, "transcript.md")
|
||||||
|
if err := os.WriteFile(input, []byte("synthetic discovery transcript"), 0o644); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
args := func(name string) []string {
|
||||||
|
if name == "support-repo" {
|
||||||
|
return []string{"--config", config, "--prompt", "support/answer", "--profile", "support/fast", "--input", "transcript=" + input}
|
||||||
|
}
|
||||||
|
return []string{"--config", config, "--prompt", "review/answer", "--profile", "review/base"}
|
||||||
|
}
|
||||||
|
check := func(name string) {
|
||||||
|
t.Helper()
|
||||||
|
code, out, stderr := runCLICommand(t, renderCommand, args(name))
|
||||||
|
if code != ExitOK {
|
||||||
|
t.Fatalf("render %s: code=%d stderr=%s", name, code, stderr)
|
||||||
|
}
|
||||||
|
if name == "support-repo" {
|
||||||
|
for _, want := range []string{"prompt: support/answer", "selected_profile_id: support/fast", "model: support-example", "max_tokens: 256", "Answer the support request", "synthetic discovery transcript"} {
|
||||||
|
if !strings.Contains(out, want) {
|
||||||
|
t.Fatalf("missing %q: %s", want, out)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
} else if !strings.Contains(out, "prompt: review/answer") || !strings.Contains(out, "model: review-example") || !strings.Contains(out, "Review this material") {
|
||||||
|
t.Fatalf("unexpected review render: %s", out)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
install(tc.first)
|
||||||
|
check(tc.first)
|
||||||
|
code, _, _ := runCLICommand(t, renderCommand, args(tc.second))
|
||||||
|
if code != ExitRuntimeError {
|
||||||
|
t.Fatal("uninstalled collection unexpectedly selected")
|
||||||
|
}
|
||||||
|
install(tc.second)
|
||||||
|
check(tc.first)
|
||||||
|
check(tc.second)
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
162
internal/adapter/cli/framework_config.go
Normal file
162
internal/adapter/cli/framework_config.go
Normal file
@@ -0,0 +1,162 @@
|
|||||||
|
package cli
|
||||||
|
|
||||||
|
import (
|
||||||
|
"encoding/json"
|
||||||
|
"errors"
|
||||||
|
"flag"
|
||||||
|
"fmt"
|
||||||
|
"io"
|
||||||
|
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
|
)
|
||||||
|
|
||||||
|
type frameworkConfigurationConfig struct {
|
||||||
|
mode, configPath, configOverlay, schemaDir string
|
||||||
|
path string
|
||||||
|
configExplicit bool
|
||||||
|
pathExplicit bool
|
||||||
|
overrides []configkit.Override
|
||||||
|
diagnostics []configkit.Diagnostic
|
||||||
|
}
|
||||||
|
|
||||||
|
type frameworkConfigurationSource struct {
|
||||||
|
ID string `json:"id"`
|
||||||
|
Label string `json:"label"`
|
||||||
|
Layer configkit.Layer `json:"layer"`
|
||||||
|
Kind configkit.SourceKind `json:"kind"`
|
||||||
|
UnderlayIndex int `json:"underlay_index"`
|
||||||
|
Path string `json:"path,omitempty"`
|
||||||
|
ImportedFrom *frameworkConfigurationLocation `json:"imported_from,omitempty"`
|
||||||
|
}
|
||||||
|
|
||||||
|
type frameworkConfigurationLocation struct {
|
||||||
|
SourceID string `json:"source_id"`
|
||||||
|
Line int `json:"line"`
|
||||||
|
Column int `json:"column"`
|
||||||
|
}
|
||||||
|
|
||||||
|
func inspectFrameworkConfigurationCommand(args []string, stdout, stderr io.Writer) int {
|
||||||
|
cfg, err := parseFrameworkConfigurationArgs(args)
|
||||||
|
if err != nil {
|
||||||
|
writeApplicationError(stderr, "inspect configuration parse", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
var explanationPath configkit.Path
|
||||||
|
if cfg.mode == "explain" {
|
||||||
|
explanationPath, err = configkit.ParsePath(cfg.path)
|
||||||
|
if err != nil {
|
||||||
|
writeApplicationError(stderr, "inspect configuration path", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
}
|
||||||
|
settings, err := resolveAppSettingsForFrameworkConfiguration(cfg)
|
||||||
|
if err != nil {
|
||||||
|
writeApplicationError(stderr, "inspect configuration", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil {
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
engine, err := newEngine(settings)
|
||||||
|
if err != nil {
|
||||||
|
writeApplicationError(stderr, "engine", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
view, err := engine.InspectConfiguration()
|
||||||
|
if err != nil {
|
||||||
|
writeApplicationError(stderr, "inspect configuration", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
if err := configkit.WriteDiagnostics(stderr, view.Diagnostics()); err != nil {
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
if cfg.mode == "validate" {
|
||||||
|
return ExitOK
|
||||||
|
}
|
||||||
|
|
||||||
|
if cfg.mode == "explain" {
|
||||||
|
if err := view.WriteExplanation(stdout, explanationPath); err != nil {
|
||||||
|
fmt.Fprintf(stderr, "inspect configuration explain %q: %v\n", cfg.path, err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
return ExitOK
|
||||||
|
}
|
||||||
|
|
||||||
|
switch cfg.mode {
|
||||||
|
case "show":
|
||||||
|
err = view.WriteEffective(stdout)
|
||||||
|
case "sources":
|
||||||
|
sources := frameworkConfigurationSources(view.Sources())
|
||||||
|
err = json.NewEncoder(stdout).Encode(sources)
|
||||||
|
}
|
||||||
|
if err != nil {
|
||||||
|
fmt.Fprintf(stderr, "inspect configuration output error: %v\n", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
return ExitOK
|
||||||
|
}
|
||||||
|
|
||||||
|
func parseFrameworkConfigurationArgs(args []string) (*frameworkConfigurationConfig, error) {
|
||||||
|
if len(args) == 0 {
|
||||||
|
return nil, errors.New("configuration operation is required")
|
||||||
|
}
|
||||||
|
cfg := &frameworkConfigurationConfig{mode: args[0]}
|
||||||
|
switch cfg.mode {
|
||||||
|
case "validate", "show", "sources", "explain":
|
||||||
|
default:
|
||||||
|
return nil, fmt.Errorf("unknown configuration operation %q", cfg.mode)
|
||||||
|
}
|
||||||
|
|
||||||
|
fs := flag.NewFlagSet("inspect configuration "+cfg.mode, flag.ContinueOnError)
|
||||||
|
fs.SetOutput(io.Discard)
|
||||||
|
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
|
||||||
|
var promptkitSources promptKitSourceFlagValue
|
||||||
|
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
|
||||||
|
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
|
||||||
|
fs.StringVar(&cfg.path, "path", "", "JSON Pointer to explain (required for explain)")
|
||||||
|
if err := fs.Parse(args[1:]); err != nil {
|
||||||
|
return nil, err
|
||||||
|
}
|
||||||
|
if fs.NArg() != 0 {
|
||||||
|
return nil, fmt.Errorf("unexpected positional args: %v", fs.Args())
|
||||||
|
}
|
||||||
|
cfg.configExplicit = flagWasSet(fs, "config")
|
||||||
|
cfg.pathExplicit = flagWasSet(fs, "path")
|
||||||
|
if cfg.mode == "explain" && !cfg.pathExplicit {
|
||||||
|
return nil, errors.New("--path is required for explain")
|
||||||
|
}
|
||||||
|
cfg.overrides = applicationOverrides(fs)
|
||||||
|
return cfg, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func resolveAppSettingsForFrameworkConfiguration(cfg *frameworkConfigurationConfig) (engineSettings, error) {
|
||||||
|
settings, diagnostics, err := loadApplicationSettings(cfg.configPath, cfg.configOverlay, cfg.configExplicit, cfg.overrides)
|
||||||
|
if err != nil {
|
||||||
|
return engineSettings{}, err
|
||||||
|
}
|
||||||
|
cfg.diagnostics = diagnostics
|
||||||
|
return engineSettings{
|
||||||
|
promptkitSources: settings.PromptKitSources,
|
||||||
|
schemaDir: settings.SchemaDir,
|
||||||
|
transientRetries: settings.TransientRetries,
|
||||||
|
}, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func frameworkConfigurationSources(sources []configkit.SourceInfo) []frameworkConfigurationSource {
|
||||||
|
result := make([]frameworkConfigurationSource, 0, len(sources))
|
||||||
|
for _, source := range sources {
|
||||||
|
item := frameworkConfigurationSource{
|
||||||
|
ID: source.ID, Label: source.Label, Layer: source.Layer,
|
||||||
|
Kind: source.Kind, UnderlayIndex: source.UnderlayIndex, Path: source.Path,
|
||||||
|
}
|
||||||
|
if source.ImportedFrom != nil {
|
||||||
|
item.ImportedFrom = &frameworkConfigurationLocation{
|
||||||
|
SourceID: source.ImportedFrom.SourceID,
|
||||||
|
Line: source.ImportedFrom.Line,
|
||||||
|
Column: source.ImportedFrom.Column,
|
||||||
|
}
|
||||||
|
}
|
||||||
|
result = append(result, item)
|
||||||
|
}
|
||||||
|
return result
|
||||||
|
}
|
||||||
391
internal/adapter/cli/framework_config_test.go
Normal file
391
internal/adapter/cli/framework_config_test.go
Normal file
@@ -0,0 +1,391 @@
|
|||||||
|
package cli
|
||||||
|
|
||||||
|
import (
|
||||||
|
"bytes"
|
||||||
|
"encoding/json"
|
||||||
|
"errors"
|
||||||
|
"fmt"
|
||||||
|
"os"
|
||||||
|
"path/filepath"
|
||||||
|
"strings"
|
||||||
|
"testing"
|
||||||
|
|
||||||
|
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
||||||
|
configkit "go.maximumdirect.net/configkit"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestFrameworkConfigurationCommandsNeedNoPromptOrCredential(t *testing.T) {
|
||||||
|
configPath := writeAppConfigFile(t, "{}\n")
|
||||||
|
code, stdout, stderr := runCLICommand(t, inspectCommand, []string{
|
||||||
|
"configuration", "validate", "--config", configPath,
|
||||||
|
})
|
||||||
|
if code != ExitOK || stdout != "" || stderr != "" {
|
||||||
|
t.Fatalf("source-free validation failed: code=%d stdout=%q stderr=%q", code, stdout, stderr)
|
||||||
|
}
|
||||||
|
|
||||||
|
t.Setenv("SCRIPTORIUM_FRAMEWORK_KEY", "")
|
||||||
|
root := t.TempDir()
|
||||||
|
frameworkFile := filepath.Join(root, "framework.yml")
|
||||||
|
writeFrameworkSourceFile(t, root, "framework.yml", `backends:
|
||||||
|
- id: local
|
||||||
|
endpoint: http://127.0.0.1:1/v1
|
||||||
|
api_key_env: SCRIPTORIUM_FRAMEWORK_KEY
|
||||||
|
profiles:
|
||||||
|
- id: protected
|
||||||
|
backend: local
|
||||||
|
model: offline-model
|
||||||
|
api_key_required: true
|
||||||
|
`)
|
||||||
|
configPath = writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkFile))
|
||||||
|
for _, mode := range []string{"validate", "show", "sources"} {
|
||||||
|
code, stdout, stderr = runCLICommand(t, inspectCommand, []string{
|
||||||
|
"configuration", mode, "--config", configPath,
|
||||||
|
})
|
||||||
|
if code != ExitOK || stderr != "" {
|
||||||
|
t.Fatalf("%s required a prompt or credential: code=%d stdout=%q stderr=%q", mode, code, stdout, stderr)
|
||||||
|
}
|
||||||
|
if mode == "validate" && stdout != "" {
|
||||||
|
t.Fatalf("validation wrote success output: %q", stdout)
|
||||||
|
}
|
||||||
|
if mode == "show" && (!strings.Contains(stdout, "profiles:") || !strings.Contains(stdout, "offline-model")) {
|
||||||
|
t.Fatalf("effective framework YAML is missing: %q", stdout)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkConfigurationSourcesProjectsOrderedNativeRecords(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
importDir := filepath.Join(root, "catalog")
|
||||||
|
if err := os.MkdirAll(importDir, 0o755); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
mainPath := writeFrameworkSourceFile(t, root, "main.yml", `config:
|
||||||
|
imports:
|
||||||
|
- path: catalog/fragment.yml
|
||||||
|
required: true
|
||||||
|
backends:
|
||||||
|
- id: local
|
||||||
|
endpoint: http://127.0.0.1:1/v1
|
||||||
|
`)
|
||||||
|
fragmentPath := writeFrameworkSourceFile(t, importDir, "fragment.yml", `profiles:
|
||||||
|
- id: imported
|
||||||
|
model: imported-model
|
||||||
|
`)
|
||||||
|
directory := t.TempDir()
|
||||||
|
directoryPath := writeFrameworkSourceFile(t, directory, "directory.yml", `profiles:
|
||||||
|
- id: directory
|
||||||
|
model: directory-model
|
||||||
|
`)
|
||||||
|
configuredMissing := filepath.Join(root, "configured-but-replaced.yml")
|
||||||
|
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", configuredMissing))
|
||||||
|
args := []string{
|
||||||
|
"configuration", "sources", "--config", configPath,
|
||||||
|
"--promptkit-source", mainPath,
|
||||||
|
"--promptkit-source", directory,
|
||||||
|
}
|
||||||
|
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
|
||||||
|
if code != ExitOK || stderr != "" || !strings.HasSuffix(stdout, "\n") {
|
||||||
|
t.Fatalf("framework sources command failed: code=%d stdout=%q stderr=%q", code, stdout, stderr)
|
||||||
|
}
|
||||||
|
var sources []frameworkConfigurationSource
|
||||||
|
if err := json.Unmarshal([]byte(stdout), &sources); err != nil {
|
||||||
|
t.Fatalf("decode framework source DTOs: %v\n%s", err, stdout)
|
||||||
|
}
|
||||||
|
var rawSources []map[string]any
|
||||||
|
if err := json.Unmarshal([]byte(stdout), &rawSources); err != nil {
|
||||||
|
t.Fatalf("decode framework source fields: %v", err)
|
||||||
|
}
|
||||||
|
mainIndex := findFrameworkSource(t, sources, mainPath)
|
||||||
|
fragmentIndex := findFrameworkSource(t, sources, fragmentPath)
|
||||||
|
directoryIndex := findFrameworkSource(t, sources, directoryPath)
|
||||||
|
main := sources[mainIndex]
|
||||||
|
fragment := sources[fragmentIndex]
|
||||||
|
directorySource := sources[directoryIndex]
|
||||||
|
if !(mainIndex < fragmentIndex && fragmentIndex < directoryIndex) {
|
||||||
|
t.Fatalf("captured source order changed: main=%d fragment=%d directory=%d", mainIndex, fragmentIndex, directoryIndex)
|
||||||
|
}
|
||||||
|
if main.ID == "" || main.Label == "" || main.Layer != configkit.LayerUnderlay || main.Kind != configkit.SourceKindFile || main.UnderlayIndex < 1 {
|
||||||
|
t.Fatalf("explicit file source fields are incomplete: %+v", main)
|
||||||
|
}
|
||||||
|
for _, key := range []string{"id", "label", "layer", "kind", "underlay_index", "path"} {
|
||||||
|
if _, exists := rawSources[mainIndex][key]; !exists {
|
||||||
|
t.Fatalf("source DTO omitted %q: %#v", key, rawSources[mainIndex])
|
||||||
|
}
|
||||||
|
}
|
||||||
|
for _, key := range []string{"ID", "Label", "Layer", "Kind", "UnderlayIndex", "filesystem"} {
|
||||||
|
if _, exists := rawSources[mainIndex][key]; exists {
|
||||||
|
t.Fatalf("source DTO exposed implementation field %q: %#v", key, rawSources[mainIndex])
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if fragment.Layer != configkit.LayerUnderlay || fragment.Kind != configkit.SourceKindFile || fragment.ImportedFrom == nil ||
|
||||||
|
fragment.ImportedFrom.SourceID != main.ID || fragment.ImportedFrom.Line < 1 || fragment.ImportedFrom.Column < 1 {
|
||||||
|
t.Fatalf("import source fields are incomplete: %+v", fragment)
|
||||||
|
}
|
||||||
|
if importedFrom, ok := rawSources[fragmentIndex]["imported_from"].(map[string]any); !ok || importedFrom["source_id"] != main.ID || importedFrom["line"] == nil || importedFrom["column"] == nil {
|
||||||
|
t.Fatalf("import location DTO fields are incomplete: %#v", rawSources[fragmentIndex])
|
||||||
|
}
|
||||||
|
if directorySource.Layer != configkit.LayerUnderlay || directorySource.Kind != configkit.SourceKindFile || directorySource.UnderlayIndex <= main.UnderlayIndex {
|
||||||
|
t.Fatalf("directory-selected source fields/order are incomplete: %+v (main %+v)", directorySource, main)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkConfigurationShowFailsBeforeOutputForInvalidFinalDefinition(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
frameworkFile := writeFrameworkSourceFile(t, root, "invalid.yml", `prompts:
|
||||||
|
- id: unused
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: "{{"
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`)
|
||||||
|
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkFile))
|
||||||
|
code, stdout, stderr := runCLICommand(t, configCommand, []string{"validate", "--config", configPath})
|
||||||
|
if code != ExitOK || stdout != "" || stderr != "" {
|
||||||
|
t.Fatalf("application validation loaded framework definitions: code=%d stdout=%q stderr=%q", code, stdout, stderr)
|
||||||
|
}
|
||||||
|
for _, args := range [][]string{
|
||||||
|
{"configuration", "validate", "--config", configPath},
|
||||||
|
{"configuration", "show", "--config", configPath},
|
||||||
|
{"configuration", "sources", "--config", configPath},
|
||||||
|
{"configuration", "explain", "--config", configPath, "--path", ""},
|
||||||
|
} {
|
||||||
|
code, stdout, stderr = runCLICommand(t, inspectCommand, args)
|
||||||
|
if code != ExitRuntimeError || stdout != "" || stderr == "" {
|
||||||
|
t.Fatalf("invalid final framework definition was reported as success: args=%q code=%d stdout=%q stderr=%q", args, code, stdout, stderr)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkConfigurationCommandsRejectExtraArgumentsAndReportWriterErrors(t *testing.T) {
|
||||||
|
configPath := writeAppConfigFile(t, "{}\n")
|
||||||
|
for _, args := range [][]string{
|
||||||
|
{"configuration"},
|
||||||
|
{"configuration", "explain"},
|
||||||
|
{"configuration", "show", "unexpected"},
|
||||||
|
{"configuration", "sources", "--format", "json"},
|
||||||
|
} {
|
||||||
|
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
|
||||||
|
if code != ExitRuntimeError || stdout != "" || stderr == "" {
|
||||||
|
t.Fatalf("invalid inspection arguments were accepted: args=%q code=%d stdout=%q stderr=%q", args, code, stdout, stderr)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
writerError := errors.New("synthetic framework output failure")
|
||||||
|
var stderr bytes.Buffer
|
||||||
|
code := inspectCommand([]string{"configuration", "show", "--config", configPath}, frameworkConfigurationFailingWriter{err: writerError}, &stderr)
|
||||||
|
if code != ExitRuntimeError || !strings.Contains(stderr.String(), writerError.Error()) {
|
||||||
|
t.Fatalf("effective-output writer failure was not reported: code=%d stderr=%q", code, stderr.String())
|
||||||
|
}
|
||||||
|
stderr.Reset()
|
||||||
|
code = inspectCommand([]string{"configuration", "explain", "--config", configPath, "--path", ""}, frameworkConfigurationFailingWriter{err: writerError}, &stderr)
|
||||||
|
if code != ExitRuntimeError || !strings.Contains(stderr.String(), writerError.Error()) {
|
||||||
|
t.Fatalf("explanation writer failure was not reported: code=%d stderr=%q", code, stderr.String())
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkConfigurationExplainUsesLiteralJSONPointersAndNativeHistory(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
lower := writeFrameworkSourceFile(t, root, "lower.yml", `collections:
|
||||||
|
support:
|
||||||
|
backends:
|
||||||
|
- id: local
|
||||||
|
endpoint: http://127.0.0.1:1/v1
|
||||||
|
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
|
||||||
|
extra_params:
|
||||||
|
token: backend-token-displaced-canary
|
||||||
|
password: backend-password-canary
|
||||||
|
visible_option: backend-visible-value
|
||||||
|
provider.option: dotted-visible-value
|
||||||
|
profiles:
|
||||||
|
- id: summary
|
||||||
|
backend: support/local
|
||||||
|
model: lower-model
|
||||||
|
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
|
||||||
|
extra_params:
|
||||||
|
token: profile-token-displaced-canary
|
||||||
|
password: profile-password-displaced-canary
|
||||||
|
visible_option: profile-visible-value
|
||||||
|
provider.option: dotted-visible-value
|
||||||
|
prompts:
|
||||||
|
- id: explainable
|
||||||
|
default_profile: support/summary
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: hello
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`)
|
||||||
|
upperRoot := t.TempDir()
|
||||||
|
upper := writeFrameworkSourceFile(t, upperRoot, "upper.yml", `collections:
|
||||||
|
support:
|
||||||
|
backends:
|
||||||
|
- id: local
|
||||||
|
endpoint: http://127.0.0.1:1/v1
|
||||||
|
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
|
||||||
|
extra_params:
|
||||||
|
token: backend-token-effective-canary
|
||||||
|
password: backend-password-effective-canary
|
||||||
|
visible_option: backend-visible-value
|
||||||
|
provider.option: dotted-visible-value
|
||||||
|
profiles:
|
||||||
|
- id: summary
|
||||||
|
backend: support/local
|
||||||
|
model: effective-model
|
||||||
|
api_key_env: SCRIPTORIUM_EXPLAIN_REFERENCE
|
||||||
|
extra_params:
|
||||||
|
token: profile-token-effective-canary
|
||||||
|
password: profile-password-effective-canary
|
||||||
|
visible_option: profile-visible-value
|
||||||
|
provider.option: dotted-visible-value
|
||||||
|
`)
|
||||||
|
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n - file: %q\n", lower, upper))
|
||||||
|
const secret = "environment-value-must-never-be-emitted"
|
||||||
|
t.Setenv("SCRIPTORIUM_EXPLAIN_REFERENCE", secret)
|
||||||
|
|
||||||
|
for _, tc := range []struct {
|
||||||
|
path string
|
||||||
|
want []string
|
||||||
|
unwant []string
|
||||||
|
}{
|
||||||
|
{
|
||||||
|
path: "/collections/support/backends/0/extra_params/token",
|
||||||
|
unwant: []string{"backend-token-displaced-canary", "backend-token-effective-canary"},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: "/collections/support/backends/0/extra_params/password",
|
||||||
|
unwant: []string{"backend-password-displaced-canary", "backend-password-effective-canary"},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: "/collections/support/profiles/0/model",
|
||||||
|
want: []string{"effective-model", "lower-model"},
|
||||||
|
unwant: []string{},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: "/collections/support/profiles/0/extra_params/token",
|
||||||
|
unwant: []string{"profile-token-displaced-canary", "profile-token-effective-canary"},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: "/collections/support/profiles/0/extra_params/password",
|
||||||
|
unwant: []string{"profile-password-displaced-canary", "profile-password-effective-canary"},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: "/collections/support/profiles/0/api_key_env",
|
||||||
|
want: []string{"SCRIPTORIUM_EXPLAIN_REFERENCE"},
|
||||||
|
unwant: []string{secret},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: "/collections/support/profiles/0/extra_params/provider.option",
|
||||||
|
want: []string{"dotted-visible-value"},
|
||||||
|
unwant: []string{"provider/option"},
|
||||||
|
},
|
||||||
|
{
|
||||||
|
path: "",
|
||||||
|
want: []string{"profiles:", "effective-model"},
|
||||||
|
unwant: []string{"profile-token-displaced-canary", "backend-password-effective-canary"},
|
||||||
|
},
|
||||||
|
} {
|
||||||
|
args := []string{"configuration", "explain", "--config", configPath, "--path", tc.path}
|
||||||
|
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
|
||||||
|
if code != ExitOK || stderr != "" {
|
||||||
|
t.Fatalf("explain %q failed: code=%d stdout=%q stderr=%q", tc.path, code, stdout, stderr)
|
||||||
|
}
|
||||||
|
if stdout == "" {
|
||||||
|
t.Fatalf("explain %q produced no output", tc.path)
|
||||||
|
}
|
||||||
|
for _, value := range tc.want {
|
||||||
|
if !strings.Contains(stdout, value) {
|
||||||
|
t.Errorf("explain %q omitted %q: %s", tc.path, value, stdout)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
for _, value := range tc.unwant {
|
||||||
|
if strings.Contains(stdout, value) {
|
||||||
|
t.Errorf("explain %q disclosed %q: %s", tc.path, value, stdout)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if strings.Contains(stdout, secret) {
|
||||||
|
t.Errorf("explain %q disclosed the resolved environment value: %s", tc.path, stdout)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
code, stdout, stderr := runCLICommand(t, inspectCommand, []string{"configuration", "show", "--config", configPath})
|
||||||
|
if code != ExitOK || stderr != "" {
|
||||||
|
t.Fatalf("framework show failed: code=%d stderr=%q", code, stderr)
|
||||||
|
}
|
||||||
|
for _, value := range []string{"SCRIPTORIUM_EXPLAIN_REFERENCE", "backend-visible-value", "profile-visible-value", "dotted-visible-value"} {
|
||||||
|
if !strings.Contains(stdout, value) {
|
||||||
|
t.Errorf("effective report omitted visible configuration %q: %s", value, stdout)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
for _, value := range []string{
|
||||||
|
"backend-token-displaced-canary", "backend-token-effective-canary",
|
||||||
|
"backend-password-displaced-canary", "backend-password-effective-canary",
|
||||||
|
"profile-token-displaced-canary", "profile-token-effective-canary",
|
||||||
|
"profile-password-displaced-canary", "profile-password-effective-canary", secret,
|
||||||
|
} {
|
||||||
|
if strings.Contains(stdout, value) {
|
||||||
|
t.Errorf("effective report disclosed classified or resolved value %q: %s", value, stdout)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
profileCode, profileOutput, profileError := runCLICommand(t, inspectCommand, []string{
|
||||||
|
"profile", "--config", configPath, "--profile", "support/summary", "--format", "json",
|
||||||
|
})
|
||||||
|
if profileCode != ExitOK || profileError != "" {
|
||||||
|
t.Fatalf("existing profile inspection failed: code=%d stdout=%q stderr=%q", profileCode, profileOutput, profileError)
|
||||||
|
}
|
||||||
|
var profile renderformat.ProfileInspection
|
||||||
|
if err := json.Unmarshal([]byte(profileOutput), &profile); err != nil {
|
||||||
|
t.Fatalf("decode profile inspection: %v\n%s", err, profileOutput)
|
||||||
|
}
|
||||||
|
if pointerValue(profile.ProfileModelParams.Model) != "effective-model" || pointerValue(profile.ProfileModelParams.ExtraParams)["visible_option"] != "profile-visible-value" {
|
||||||
|
t.Fatalf("existing profile inspection changed configured provider data: %+v", profile.ProfileModelParams)
|
||||||
|
}
|
||||||
|
if strings.Contains(profileOutput, secret) {
|
||||||
|
t.Fatalf("profile inspection emitted resolved environment data: %s", profileOutput)
|
||||||
|
}
|
||||||
|
|
||||||
|
code, rendered, stderr := runCLICommand(t, renderCommand, []string{"--config", configPath, "--prompt", "support/explainable"})
|
||||||
|
if code != ExitOK || stderr != "" {
|
||||||
|
t.Fatalf("prepared output failed: code=%d stdout=%q stderr=%q", code, rendered, stderr)
|
||||||
|
}
|
||||||
|
if !strings.Contains(rendered, "profile-visible-value") || strings.Contains(rendered, secret) {
|
||||||
|
t.Fatalf("prepared output did not preserve ordinary provider data or disclosed environment data: %s", rendered)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkConfigurationExplainRejectsMissingMalformedAndUnknownPaths(t *testing.T) {
|
||||||
|
configPath := writeAppConfigFile(t, "{}\n")
|
||||||
|
for _, args := range [][]string{
|
||||||
|
{"configuration", "explain"},
|
||||||
|
{"configuration", "explain", "--path", "not-a-pointer"},
|
||||||
|
{"configuration", "explain", "--path", "/profiles/team~2summary/model"},
|
||||||
|
{"configuration", "explain", "--config", configPath, "--path", "/profiles/missing/model"},
|
||||||
|
} {
|
||||||
|
code, stdout, stderr := runCLICommand(t, inspectCommand, args)
|
||||||
|
if code != ExitRuntimeError || stdout != "" || stderr == "" {
|
||||||
|
t.Fatalf("invalid explanation path was accepted: args=%q code=%d stdout=%q stderr=%q", args, code, stdout, stderr)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func findFrameworkSource(t *testing.T, sources []frameworkConfigurationSource, path string) int {
|
||||||
|
t.Helper()
|
||||||
|
for index, source := range sources {
|
||||||
|
if filepath.Clean(source.Path) == filepath.Clean(path) {
|
||||||
|
return index
|
||||||
|
}
|
||||||
|
}
|
||||||
|
t.Fatalf("selected source path %q was not present: %+v", path, sources)
|
||||||
|
return -1
|
||||||
|
}
|
||||||
|
|
||||||
|
type frameworkConfigurationFailingWriter struct {
|
||||||
|
err error
|
||||||
|
}
|
||||||
|
|
||||||
|
func (writer frameworkConfigurationFailingWriter) Write([]byte) (int, error) {
|
||||||
|
return 0, writer.err
|
||||||
|
}
|
||||||
75
internal/adapter/cli/framework_sources.go
Normal file
75
internal/adapter/cli/framework_sources.go
Normal file
@@ -0,0 +1,75 @@
|
|||||||
|
package cli
|
||||||
|
|
||||||
|
import (
|
||||||
|
"errors"
|
||||||
|
"fmt"
|
||||||
|
"io"
|
||||||
|
"os"
|
||||||
|
"path/filepath"
|
||||||
|
"strings"
|
||||||
|
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
|
"go.maximumdirect.net/promptkit"
|
||||||
|
)
|
||||||
|
|
||||||
|
type promptKitSourceFlagEntry struct {
|
||||||
|
selector string
|
||||||
|
path string
|
||||||
|
}
|
||||||
|
|
||||||
|
// promptKitSourceFlagValue treats each occurrence as one selected source path.
|
||||||
|
type promptKitSourceFlagValue struct {
|
||||||
|
entries []promptKitSourceFlagEntry
|
||||||
|
}
|
||||||
|
|
||||||
|
func (value *promptKitSourceFlagValue) Set(path string) error {
|
||||||
|
trimmed := strings.TrimSpace(path)
|
||||||
|
if trimmed == "" {
|
||||||
|
return errors.New("--promptkit-source requires a nonblank path")
|
||||||
|
}
|
||||||
|
|
||||||
|
info, err := os.Stat(filepath.Clean(trimmed))
|
||||||
|
if err != nil {
|
||||||
|
reason := "unavailable"
|
||||||
|
if errors.Is(err, os.ErrPermission) {
|
||||||
|
reason = "permission denied"
|
||||||
|
}
|
||||||
|
return fmt.Errorf("--promptkit-source %q: %s", path, reason)
|
||||||
|
}
|
||||||
|
|
||||||
|
selector := ""
|
||||||
|
switch {
|
||||||
|
case info.IsDir():
|
||||||
|
selector = "directory"
|
||||||
|
case info.Mode().IsRegular():
|
||||||
|
selector = "file"
|
||||||
|
default:
|
||||||
|
return fmt.Errorf("--promptkit-source %q must be a regular file or directory", path)
|
||||||
|
}
|
||||||
|
value.entries = append(value.entries, promptKitSourceFlagEntry{selector: selector, path: path})
|
||||||
|
return nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func (value *promptKitSourceFlagValue) Get() any {
|
||||||
|
selections := make([]any, 0, len(value.entries))
|
||||||
|
for _, entry := range value.entries {
|
||||||
|
selections = append(selections, map[string]any{entry.selector: entry.path})
|
||||||
|
}
|
||||||
|
return selections
|
||||||
|
}
|
||||||
|
|
||||||
|
func (value *promptKitSourceFlagValue) String() string {
|
||||||
|
paths := make([]string, 0, len(value.entries))
|
||||||
|
for _, entry := range value.entries {
|
||||||
|
paths = append(paths, entry.path)
|
||||||
|
}
|
||||||
|
return fmt.Sprint(paths)
|
||||||
|
}
|
||||||
|
|
||||||
|
func writeFrameworkDiagnostics(output io.Writer, engine *promptkit.Engine) error {
|
||||||
|
view, err := engine.InspectConfiguration()
|
||||||
|
if err != nil {
|
||||||
|
return fmt.Errorf("inspect captured PromptKit diagnostics: %w", err)
|
||||||
|
}
|
||||||
|
return configkit.WriteDiagnostics(output, view.Diagnostics())
|
||||||
|
}
|
||||||
386
internal/adapter/cli/framework_sources_test.go
Normal file
386
internal/adapter/cli/framework_sources_test.go
Normal file
@@ -0,0 +1,386 @@
|
|||||||
|
package cli
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"encoding/json"
|
||||||
|
"errors"
|
||||||
|
"fmt"
|
||||||
|
"os"
|
||||||
|
"path/filepath"
|
||||||
|
"reflect"
|
||||||
|
"testing"
|
||||||
|
|
||||||
|
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
||||||
|
configkit "go.maximumdirect.net/configkit"
|
||||||
|
"go.maximumdirect.net/promptkit"
|
||||||
|
)
|
||||||
|
|
||||||
|
func TestFrameworkSourceGroupsComposeAndValidateEffectiveDefinitions(t *testing.T) {
|
||||||
|
conflicting := t.TempDir()
|
||||||
|
writeFrameworkSourceFile(t, conflicting, "first.yml", `profiles:
|
||||||
|
- id: selected
|
||||||
|
model: first
|
||||||
|
`)
|
||||||
|
writeFrameworkSourceFile(t, conflicting, "second.yml", `profiles:
|
||||||
|
- id: selected
|
||||||
|
model: second
|
||||||
|
`)
|
||||||
|
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{Directory: conflicting}}}); err == nil {
|
||||||
|
t.Fatal("conflicting files in one source group unexpectedly constructed an engine")
|
||||||
|
}
|
||||||
|
|
||||||
|
lower := t.TempDir()
|
||||||
|
upper := t.TempDir()
|
||||||
|
empty := t.TempDir()
|
||||||
|
writeFrameworkSourceFile(t, lower, "lower.yml", `profiles:
|
||||||
|
- id: selected
|
||||||
|
endpoint: not-a-url
|
||||||
|
model: lower-model
|
||||||
|
temperature: 10
|
||||||
|
`)
|
||||||
|
writeFrameworkSourceFile(t, upper, "upper.yml", `profiles:
|
||||||
|
- id: selected
|
||||||
|
endpoint: http://127.0.0.1:1/v1
|
||||||
|
model: upper-model
|
||||||
|
temperature: 0.5
|
||||||
|
`)
|
||||||
|
engine := newFrameworkSourceTestEngine(t, []appconfig.SourceSelection{
|
||||||
|
{Directory: lower}, {Directory: empty}, {Directory: upper},
|
||||||
|
}, "")
|
||||||
|
inspection, err := engine.InspectProfile(context.Background(), "selected")
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("inspect profile after later source replacement: %v", err)
|
||||||
|
}
|
||||||
|
if pointerValue(inspection.Endpoint) != "http://127.0.0.1:1/v1" || pointerValue(inspection.Model) != "upper-model" || pointerValue(inspection.Temperature) != 0.5 {
|
||||||
|
t.Fatalf("later source did not replace lower values before validation: %+v", inspection)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkSourceConstructionUsesCombinedDocumentAndRejectsInvalidSources(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
combined := filepath.Join(root, "combined.yml")
|
||||||
|
writeFrameworkSourceFile(t, root, "combined.yml", `backends:
|
||||||
|
- id: local
|
||||||
|
endpoint: http://127.0.0.1:1/v1
|
||||||
|
profiles:
|
||||||
|
- id: selected
|
||||||
|
backend: local
|
||||||
|
model: combined-model
|
||||||
|
prompts:
|
||||||
|
- id: combined.prompt
|
||||||
|
default_profile: selected
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: hello
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`)
|
||||||
|
client := &frameworkSourceCaptureClient{}
|
||||||
|
engine := newFrameworkSourceTestEngine(t, []appconfig.SourceSelection{{File: combined}}, "", promptkit.WithLLMClient(client))
|
||||||
|
if _, err := engine.Run(context.Background(), promptkit.RunRequest{PromptID: "combined.prompt"}); err != nil {
|
||||||
|
t.Fatalf("run definitions from one combined document: %v", err)
|
||||||
|
}
|
||||||
|
if len(client.requests) != 1 || client.requests[0].Target.BackendID != "local" || client.requests[0].Target.Model != "combined-model" {
|
||||||
|
t.Fatalf("combined backend/profile/prompt values did not reach generation: %+v", client.requests)
|
||||||
|
}
|
||||||
|
|
||||||
|
malformed := filepath.Join(root, "malformed.yml")
|
||||||
|
writeFrameworkSourceFile(t, root, "malformed.yml", "not: [valid\n")
|
||||||
|
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{File: malformed}}}); err == nil {
|
||||||
|
t.Fatal("malformed framework source unexpectedly constructed an engine")
|
||||||
|
}
|
||||||
|
|
||||||
|
invalidUnused := filepath.Join(root, "invalid-unused.yml")
|
||||||
|
writeFrameworkSourceFile(t, root, "invalid-unused.yml", `prompts:
|
||||||
|
- id: unused.prompt
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: "{{"
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`)
|
||||||
|
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{File: invalidUnused}}}); !errors.Is(err, promptkit.ErrInvalidConfig) {
|
||||||
|
t.Fatalf("invalid unused definition did not fail as framework configuration: %v", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkRejectsObsoleteVersionKeyedPrompt(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
path := writeFrameworkSourceFile(t, root, "obsolete.yml", `prompts:
|
||||||
|
old-prompt:
|
||||||
|
"1":
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: hello
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`)
|
||||||
|
if _, err := newEngine(engineSettings{promptkitSources: []appconfig.SourceSelection{{File: path}}}); !errors.Is(err, promptkit.ErrInvalidConfig) {
|
||||||
|
t.Fatalf("obsolete version-keyed definition was not rejected by PromptKit: %v", err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestFrameworkImportsRetainResourceOriginsAndCaptureAtConstruction(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
catalogDir := filepath.Join(root, "catalog")
|
||||||
|
if err := os.MkdirAll(catalogDir, 0o755); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
schemaDir := filepath.Join(root, "schemas")
|
||||||
|
if err := os.MkdirAll(schemaDir, 0o755); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
mainFile := filepath.Join(root, "main.yml")
|
||||||
|
writeFrameworkSourceFile(t, root, "main.yml", `config:
|
||||||
|
imports:
|
||||||
|
- path: catalog/base.yml
|
||||||
|
required: true
|
||||||
|
`)
|
||||||
|
writeFrameworkSourceFile(t, catalogDir, "base.yml", `profiles:
|
||||||
|
- id: profile-primary
|
||||||
|
endpoint: http://127.0.0.1:1/v1
|
||||||
|
model: imported-model
|
||||||
|
prompts:
|
||||||
|
- id: team-prompt
|
||||||
|
default_profile: profile-primary
|
||||||
|
inputs:
|
||||||
|
- name: source
|
||||||
|
required: true
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content_file: ./body.md
|
||||||
|
- role: user
|
||||||
|
content: 'Artifact: {{input "source"}}'
|
||||||
|
output:
|
||||||
|
format: json
|
||||||
|
validation_mode: json_schema
|
||||||
|
schema_path: response.schema.json
|
||||||
|
`)
|
||||||
|
writeFrameworkSourceFile(t, catalogDir, "body.md", "Captured message for {{.audience}}")
|
||||||
|
artifactPath := filepath.Join(root, "request-artifact.txt")
|
||||||
|
writeFrameworkSourceFile(t, root, "request-artifact.txt", "initial artifact")
|
||||||
|
writeFrameworkSourceFile(t, schemaDir, "response.schema.json", `{"type":"object","title":"initial schema"}`)
|
||||||
|
selections := []appconfig.SourceSelection{{File: mainFile}}
|
||||||
|
engine := newFrameworkSourceTestEngine(t, selections, schemaDir)
|
||||||
|
|
||||||
|
writeFrameworkSourceFile(t, catalogDir, "body.md", "edited message for {{.audience}}")
|
||||||
|
writeFrameworkSourceFile(t, root, "request-artifact.txt", "prepared artifact")
|
||||||
|
writeFrameworkSourceFile(t, schemaDir, "response.schema.json", `{"type":"object","title":"prepared schema"}`)
|
||||||
|
prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{
|
||||||
|
PromptID: "team-prompt",
|
||||||
|
Inputs: map[string]promptkit.ArtifactRef{"source": promptkit.File(artifactPath)},
|
||||||
|
Vars: map[string]string{"audience": "reader"},
|
||||||
|
})
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("prepare inherited imported prompt: %v", err)
|
||||||
|
}
|
||||||
|
if len(prepared.Messages) != 2 || prepared.Messages[0].Content != "Captured message for reader" || prepared.Messages[1].Content != "Artifact: prepared artifact" {
|
||||||
|
t.Fatalf("resource origin or capture/preparation behavior changed: %+v", prepared.Messages)
|
||||||
|
}
|
||||||
|
if prepared.SelectedProfileID != "profile-primary" {
|
||||||
|
t.Fatalf("profile ID was not preserved: %+v", prepared)
|
||||||
|
}
|
||||||
|
if prepared.StructuredOutput == nil || prepared.StructuredOutput.JSONSchema == nil || prepared.StructuredOutput.JSONSchema.Schema.(map[string]any)["title"] != "prepared schema" {
|
||||||
|
t.Fatalf("schema was not loaded during preparation: %+v", prepared.StructuredOutput)
|
||||||
|
}
|
||||||
|
|
||||||
|
newEngine := newFrameworkSourceTestEngine(t, selections, schemaDir)
|
||||||
|
newPrepared, err := newEngine.Prepare(context.Background(), promptkit.RunRequest{
|
||||||
|
PromptID: "team-prompt",
|
||||||
|
Inputs: map[string]promptkit.ArtifactRef{"source": promptkit.File(artifactPath)},
|
||||||
|
Vars: map[string]string{"audience": "reader"},
|
||||||
|
})
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("prepare with newly captured message: %v", err)
|
||||||
|
}
|
||||||
|
if newPrepared.Messages[0].Content != "edited message for reader" {
|
||||||
|
t.Fatalf("new engine did not observe the message edit: %+v", newPrepared.Messages[0])
|
||||||
|
}
|
||||||
|
|
||||||
|
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\nschema_dir: %q\n", mainFile, schemaDir))
|
||||||
|
code, stdout, stderr := runCLICommand(t, renderCommand, []string{
|
||||||
|
"--config", configPath,
|
||||||
|
"--prompt", "team-prompt",
|
||||||
|
"--input", "source=" + artifactPath,
|
||||||
|
"--var", "audience=reader",
|
||||||
|
"--format", "json",
|
||||||
|
})
|
||||||
|
if code != ExitOK {
|
||||||
|
t.Fatalf("render exact literal IDs through CLI: code=%d stderr=%q", code, stderr)
|
||||||
|
}
|
||||||
|
var rendered promptkit.PreparedRun
|
||||||
|
if err := json.Unmarshal([]byte(stdout), &rendered); err != nil {
|
||||||
|
t.Fatalf("decode rendered literal-ID fixture: %v", err)
|
||||||
|
}
|
||||||
|
if rendered.PromptID != "team-prompt" || rendered.SelectedProfileID != "profile-primary" {
|
||||||
|
t.Fatalf("CLI changed exact prompt/profile IDs: %+v", rendered)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestNativeProfileInheritanceAndPresenceReachTheClientBoundary(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
frameworkFile := filepath.Join(root, "framework.yml")
|
||||||
|
writeFrameworkSourceFile(t, root, "framework.yml", `backends:
|
||||||
|
- id: first
|
||||||
|
endpoint: https://first.example/v1
|
||||||
|
api_key_env: FIRST_BACKEND_KEY
|
||||||
|
extra_params:
|
||||||
|
source: first
|
||||||
|
nested:
|
||||||
|
first_backend: true
|
||||||
|
- id: second
|
||||||
|
endpoint: https://second.example/v1
|
||||||
|
api_key_env: SECOND_BACKEND_KEY
|
||||||
|
extra_params:
|
||||||
|
source: second
|
||||||
|
nested:
|
||||||
|
second_backend: true
|
||||||
|
profiles:
|
||||||
|
- id: parent
|
||||||
|
backend: first
|
||||||
|
model: parent-model
|
||||||
|
temperature: 0.7
|
||||||
|
top_p: 0.6
|
||||||
|
max_tokens: 45
|
||||||
|
timeout_seconds: 30
|
||||||
|
service_tier: flex
|
||||||
|
extra_params:
|
||||||
|
nested:
|
||||||
|
parent_profile: true
|
||||||
|
retained: "yes"
|
||||||
|
- id: backend-child
|
||||||
|
extends: {id: parent}
|
||||||
|
backend: second
|
||||||
|
model: child-model
|
||||||
|
- id: presence-child
|
||||||
|
extends: {id: parent}
|
||||||
|
backend: second
|
||||||
|
api_key_env: null
|
||||||
|
temperature: null
|
||||||
|
max_tokens: 0
|
||||||
|
timeout_seconds: 0
|
||||||
|
extra_params:
|
||||||
|
nested:
|
||||||
|
explicit_false: false
|
||||||
|
- id: map-null
|
||||||
|
backend: second
|
||||||
|
model: map-model
|
||||||
|
extra_params: null
|
||||||
|
- id: map-empty
|
||||||
|
backend: second
|
||||||
|
model: map-model
|
||||||
|
extra_params: {}
|
||||||
|
prompts:
|
||||||
|
- id: execution.prompt
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: hello
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`)
|
||||||
|
client := &frameworkSourceCaptureClient{}
|
||||||
|
engine := newFrameworkSourceTestEngine(t, []appconfig.SourceSelection{{File: frameworkFile}}, "", promptkit.WithLLMClient(client))
|
||||||
|
|
||||||
|
for _, profileID := range []string{"backend-child", "presence-child", "map-null", "map-empty"} {
|
||||||
|
if _, err := engine.Run(context.Background(), promptkit.RunRequest{PromptID: "execution.prompt", ProfileID: profileID}); err != nil {
|
||||||
|
t.Fatalf("run profile %q: %v", profileID, err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if len(client.requests) != 4 {
|
||||||
|
t.Fatalf("expected four provider-bound requests, got %d", len(client.requests))
|
||||||
|
}
|
||||||
|
|
||||||
|
backendChild := client.requests[0].Target
|
||||||
|
wantBackendParams := map[string]any{"source": "second", "nested": map[string]any{
|
||||||
|
"second_backend": true, "parent_profile": true, "retained": "yes",
|
||||||
|
}}
|
||||||
|
if backendChild.BackendID != "second" || backendChild.Endpoint != "https://second.example/v1" || backendChild.APIKeyEnv != "SECOND_BACKEND_KEY" || backendChild.Model != "child-model" ||
|
||||||
|
backendChild.Temperature != 0.7 || backendChild.TopP != 0.6 || backendChild.MaxTokens != 45 || backendChild.TimeoutSeconds != 30 || backendChild.ServiceTier != "flex" || !reflect.DeepEqual(backendChild.ExtraParams, wantBackendParams) {
|
||||||
|
t.Fatalf("backend change lost backend-derived or explicit inherited values: %+v", backendChild)
|
||||||
|
}
|
||||||
|
|
||||||
|
presenceRequest := client.requests[1]
|
||||||
|
presenceTarget := presenceRequest.Target
|
||||||
|
if presenceTarget.APIKeyEnv != "SECOND_BACKEND_KEY" || presenceTarget.Temperature != 0 || presenceTarget.MaxTokens != 0 || presenceTarget.TimeoutSeconds != 0 ||
|
||||||
|
!presenceRequest.TargetPresence.MaxTokens || !presenceRequest.TargetPresence.TimeoutSeconds || presenceRequest.TargetPresence.Temperature || !presenceRequest.TargetPresence.TopP {
|
||||||
|
t.Fatalf("explicit null/zero presence did not reach the injected client: target=%+v presence=%+v", presenceTarget, presenceRequest.TargetPresence)
|
||||||
|
}
|
||||||
|
wantPresenceParams := map[string]any{"source": "second", "nested": map[string]any{
|
||||||
|
"second_backend": true, "parent_profile": true, "retained": "yes", "explicit_false": false,
|
||||||
|
}}
|
||||||
|
if !reflect.DeepEqual(presenceTarget.ExtraParams, wantPresenceParams) {
|
||||||
|
t.Fatalf("recursive provider-map retention changed: %#v", presenceTarget.ExtraParams)
|
||||||
|
}
|
||||||
|
if !reflect.DeepEqual(client.requests[2].Target.ExtraParams, map[string]any{"source": "second", "nested": map[string]any{"second_backend": true}}) {
|
||||||
|
t.Fatalf("whole-map null did not fall back to backend defaults: %#v", client.requests[2].Target.ExtraParams)
|
||||||
|
}
|
||||||
|
if !reflect.DeepEqual(client.requests[3].Target.ExtraParams, map[string]any{"source": "second", "nested": map[string]any{"second_backend": true}}) {
|
||||||
|
t.Fatalf("empty provider map unexpectedly cleared backend defaults: %#v", client.requests[3].Target.ExtraParams)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestCLICompletesPartialFrameworkProfileWithRequestOverrides(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
frameworkFile := writeFrameworkSourceFile(t, root, "partial.yml", `profiles:
|
||||||
|
- id: partial
|
||||||
|
prompts:
|
||||||
|
- id: partial.prompt
|
||||||
|
default_profile: partial
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: hello
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`)
|
||||||
|
provider := newTestLLMServer("completed partial profile", nil)
|
||||||
|
defer provider.Close()
|
||||||
|
configPath := writeAppConfigFile(t, fmt.Sprintf("promptkit_sources:\n - file: %q\n", frameworkFile))
|
||||||
|
code, stdout, stderr := runCLICommand(t, runCommand, []string{
|
||||||
|
"--config", configPath,
|
||||||
|
"--prompt", "partial.prompt",
|
||||||
|
"--llm-base-url", provider.URL + "/v1",
|
||||||
|
"--model", "request-model",
|
||||||
|
})
|
||||||
|
if code != ExitOK || stdout != "completed partial profile" {
|
||||||
|
t.Fatalf("request overrides did not complete the partial profile: code=%d stdout=%q stderr=%q", code, stdout, stderr)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func newFrameworkSourceTestEngine(t *testing.T, selections []appconfig.SourceSelection, schemaDir string, options ...promptkit.Option) *promptkit.Engine {
|
||||||
|
t.Helper()
|
||||||
|
engine, err := newEngine(engineSettings{promptkitSources: selections, schemaDir: schemaDir}, options...)
|
||||||
|
if err != nil {
|
||||||
|
var loadError *configkit.LoadError
|
||||||
|
if errors.As(err, &loadError) {
|
||||||
|
t.Fatalf("construct engine from selected framework sources: %v (%+v)", err, loadError.Diagnostics())
|
||||||
|
}
|
||||||
|
t.Fatalf("construct engine from selected framework sources: %v", err)
|
||||||
|
}
|
||||||
|
return engine
|
||||||
|
}
|
||||||
|
|
||||||
|
func writeFrameworkSourceFile(t *testing.T, directory, name, contents string) string {
|
||||||
|
t.Helper()
|
||||||
|
if err := os.MkdirAll(directory, 0o755); err != nil {
|
||||||
|
t.Fatalf("create framework source directory: %v", err)
|
||||||
|
}
|
||||||
|
path := filepath.Join(directory, name)
|
||||||
|
if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
|
||||||
|
t.Fatalf("write framework source %q: %v", path, err)
|
||||||
|
}
|
||||||
|
return path
|
||||||
|
}
|
||||||
|
|
||||||
|
type frameworkSourceCaptureClient struct {
|
||||||
|
requests []promptkit.GenerateRequest
|
||||||
|
}
|
||||||
|
|
||||||
|
func (client *frameworkSourceCaptureClient) Generate(_ context.Context, request promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) {
|
||||||
|
client.requests = append(client.requests, request)
|
||||||
|
return &promptkit.GenerateResponse{Content: "ok"}, nil
|
||||||
|
}
|
||||||
@@ -6,17 +6,15 @@ import (
|
|||||||
"flag"
|
"flag"
|
||||||
"fmt"
|
"fmt"
|
||||||
"io"
|
"io"
|
||||||
"io/fs"
|
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
|
||||||
appformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
appformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
type promptInspectionConfig struct {
|
type promptInspectionConfig struct {
|
||||||
configPath, promptDir, promptID, promptVersion, outputPath string
|
configPath, promptID, schemaDir, outputPath string
|
||||||
configOverlay string
|
configOverlay string
|
||||||
configExplicit bool
|
configExplicit bool
|
||||||
outputFormat appformat.OutputFormat
|
outputFormat appformat.OutputFormat
|
||||||
@@ -25,7 +23,7 @@ type promptInspectionConfig struct {
|
|||||||
}
|
}
|
||||||
|
|
||||||
type profileInspectionConfig struct {
|
type profileInspectionConfig struct {
|
||||||
configPath, profileDir, profileID, outputPath string
|
configPath, profileID, schemaDir, outputPath string
|
||||||
configOverlay string
|
configOverlay string
|
||||||
configExplicit bool
|
configExplicit bool
|
||||||
outputFormat appformat.OutputFormat
|
outputFormat appformat.OutputFormat
|
||||||
@@ -33,15 +31,6 @@ type profileInspectionConfig struct {
|
|||||||
diagnostics []configkit.Diagnostic
|
diagnostics []configkit.Diagnostic
|
||||||
}
|
}
|
||||||
|
|
||||||
// emptyPromptDefinitionFS satisfies Promptkit's engine-level prompt-source
|
|
||||||
// requirement without exposing the caller's working directory. Profile
|
|
||||||
// inspection never reads this source.
|
|
||||||
type emptyPromptDefinitionFS struct{}
|
|
||||||
|
|
||||||
func (emptyPromptDefinitionFS) Open(name string) (fs.File, error) {
|
|
||||||
return nil, &fs.PathError{Op: "open", Path: name, Err: fs.ErrNotExist}
|
|
||||||
}
|
|
||||||
|
|
||||||
func inspectCommand(args []string, stdout, stderr io.Writer) int {
|
func inspectCommand(args []string, stdout, stderr io.Writer) int {
|
||||||
if len(args) == 0 {
|
if len(args) == 0 {
|
||||||
fmt.Fprintln(stderr, "inspect parse error: inspection mode is required")
|
fmt.Fprintln(stderr, "inspect parse error: inspection mode is required")
|
||||||
@@ -50,6 +39,9 @@ func inspectCommand(args []string, stdout, stderr io.Writer) int {
|
|||||||
if args[0] == "profile" {
|
if args[0] == "profile" {
|
||||||
return inspectProfileCommand(args[1:], stdout, stderr)
|
return inspectProfileCommand(args[1:], stdout, stderr)
|
||||||
}
|
}
|
||||||
|
if args[0] == "configuration" {
|
||||||
|
return inspectFrameworkConfigurationCommand(args[1:], stdout, stderr)
|
||||||
|
}
|
||||||
if args[0] != "prompt" {
|
if args[0] != "prompt" {
|
||||||
fmt.Fprintln(stderr, "inspect parse error: unknown inspection mode")
|
fmt.Fprintln(stderr, "inspect parse error: unknown inspection mode")
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
@@ -69,10 +61,14 @@ func inspectCommand(args []string, stdout, stderr io.Writer) int {
|
|||||||
}
|
}
|
||||||
engine, err := newEngine(settings)
|
engine, err := newEngine(settings)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
fmt.Fprintf(stderr, "engine error: %v\n", err)
|
writeApplicationError(stderr, "engine", err)
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
}
|
}
|
||||||
inspection, err := engine.InspectPrompt(context.Background(), cfg.promptID, cfg.promptVersion)
|
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
|
||||||
|
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
inspection, err := engine.InspectPrompt(context.Background(), cfg.promptID)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
fmt.Fprintf(stderr, "inspect error: %v\n", err)
|
fmt.Fprintf(stderr, "inspect error: %v\n", err)
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
@@ -103,9 +99,13 @@ func inspectProfileCommand(args []string, stdout, stderr io.Writer) int {
|
|||||||
if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil {
|
if err := writeApplicationWarnings(stderr, cfg.diagnostics); err != nil {
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
}
|
}
|
||||||
engine, err := newEngine(settings, promptkit.WithPromptFS(emptyPromptDefinitionFS{}, "."))
|
engine, err := newEngine(settings)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
fmt.Fprintf(stderr, "engine error: %v\n", err)
|
writeApplicationError(stderr, "engine", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
|
||||||
|
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
}
|
}
|
||||||
inspection, err := engine.InspectProfile(context.Background(), cfg.profileID)
|
inspection, err := engine.InspectProfile(context.Background(), cfg.profileID)
|
||||||
@@ -130,7 +130,9 @@ func parseProfileInspectionArgs(args []string) (*profileInspectionConfig, error)
|
|||||||
fs := flag.NewFlagSet("inspect profile", flag.ContinueOnError)
|
fs := flag.NewFlagSet("inspect profile", flag.ContinueOnError)
|
||||||
fs.SetOutput(io.Discard)
|
fs.SetOutput(io.Discard)
|
||||||
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
|
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
|
||||||
fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profiles")
|
var promptkitSources promptKitSourceFlagValue
|
||||||
|
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
|
||||||
|
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
|
||||||
fs.StringVar(&cfg.profileID, "profile", "", "profile ID to inspect")
|
fs.StringVar(&cfg.profileID, "profile", "", "profile ID to inspect")
|
||||||
rawFormat := ""
|
rawFormat := ""
|
||||||
fs.StringVar(&rawFormat, "format", "", "output format: text or json")
|
fs.StringVar(&rawFormat, "format", "", "output format: text or json")
|
||||||
@@ -163,7 +165,7 @@ func resolveAppSettingsForProfileInspection(cfg *profileInspectionConfig) (engin
|
|||||||
return engineSettings{}, err
|
return engineSettings{}, err
|
||||||
}
|
}
|
||||||
cfg.diagnostics = diagnostics
|
cfg.diagnostics = diagnostics
|
||||||
return engineSettings{profileDir: settings.ProfileDir, backends: settings.Backends, transientRetries: settings.TransientRetries}, nil
|
return engineSettings{promptkitSources: settings.PromptKitSources, schemaDir: settings.SchemaDir, transientRetries: settings.TransientRetries}, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
func parsePromptInspectionArgs(args []string) (*promptInspectionConfig, error) {
|
func parsePromptInspectionArgs(args []string) (*promptInspectionConfig, error) {
|
||||||
@@ -171,9 +173,10 @@ func parsePromptInspectionArgs(args []string) (*promptInspectionConfig, error) {
|
|||||||
fs := flag.NewFlagSet("inspect prompt", flag.ContinueOnError)
|
fs := flag.NewFlagSet("inspect prompt", flag.ContinueOnError)
|
||||||
fs.SetOutput(io.Discard)
|
fs.SetOutput(io.Discard)
|
||||||
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
|
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
|
||||||
fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definitions")
|
var promptkitSources promptKitSourceFlagValue
|
||||||
|
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
|
||||||
|
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
|
||||||
fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to inspect")
|
fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to inspect")
|
||||||
fs.StringVar(&cfg.promptVersion, "prompt-version", "", "optional prompt version")
|
|
||||||
rawFormat := ""
|
rawFormat := ""
|
||||||
fs.StringVar(&rawFormat, "format", "", "output format: text or json")
|
fs.StringVar(&rawFormat, "format", "", "output format: text or json")
|
||||||
fs.StringVar(&cfg.outputPath, "out", "", "optional output file path")
|
fs.StringVar(&cfg.outputPath, "out", "", "optional output file path")
|
||||||
@@ -205,8 +208,5 @@ func resolveAppSettingsForPromptInspection(cfg *promptInspectionConfig) (engineS
|
|||||||
return engineSettings{}, err
|
return engineSettings{}, err
|
||||||
}
|
}
|
||||||
cfg.diagnostics = diagnostics
|
cfg.diagnostics = diagnostics
|
||||||
if strings.TrimSpace(settings.PromptDir) == "" {
|
return engineSettings{promptkitSources: settings.PromptKitSources, schemaDir: settings.SchemaDir, transientRetries: settings.TransientRetries}, nil
|
||||||
return engineSettings{}, errors.New(errPromptDirRequired)
|
|
||||||
}
|
|
||||||
return engineSettings{promptDir: settings.PromptDir, backends: settings.Backends, transientRetries: settings.TransientRetries}, nil
|
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -13,13 +13,13 @@ import (
|
|||||||
"strings"
|
"strings"
|
||||||
"time"
|
"time"
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
|
||||||
httpadapter "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http"
|
httpadapter "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http"
|
||||||
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
appconfig "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
||||||
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
||||||
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
||||||
executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report"
|
executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report"
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
const (
|
const (
|
||||||
@@ -28,17 +28,11 @@ const (
|
|||||||
ExitValidationFailed = 2
|
ExitValidationFailed = 2
|
||||||
)
|
)
|
||||||
|
|
||||||
const (
|
|
||||||
errPromptDirRequired = "prompt directory is required; provide --prompt-dir or config.yml prompt_dir"
|
|
||||||
)
|
|
||||||
|
|
||||||
type runConfig struct {
|
type runConfig struct {
|
||||||
configPath string
|
configPath string
|
||||||
|
|
||||||
promptDir string
|
promptkitSources []appconfig.SourceSelection
|
||||||
profileDir string
|
|
||||||
promptID string
|
promptID string
|
||||||
promptVersion string
|
|
||||||
profileID string
|
profileID string
|
||||||
sessionID string
|
sessionID string
|
||||||
inputRaw listFlag
|
inputRaw listFlag
|
||||||
@@ -53,7 +47,6 @@ type runConfig struct {
|
|||||||
topP float64
|
topP float64
|
||||||
reasoningEffort string
|
reasoningEffort string
|
||||||
schemaDir string
|
schemaDir string
|
||||||
backends []appconfig.BackendSettings
|
|
||||||
timeout time.Duration
|
timeout time.Duration
|
||||||
runTimeout time.Duration
|
runTimeout time.Duration
|
||||||
transientRetries int
|
transientRetries int
|
||||||
@@ -83,22 +76,19 @@ type serveConfig struct {
|
|||||||
configPath string
|
configPath string
|
||||||
|
|
||||||
addr string
|
addr string
|
||||||
promptDir string
|
promptkitSources []appconfig.SourceSelection
|
||||||
profileDir string
|
|
||||||
schemaDir string
|
schemaDir string
|
||||||
artifactRoot string
|
artifactRoot string
|
||||||
maxRequestBytes int64
|
maxRequestBytes int64
|
||||||
maxArtifactBytes int64
|
maxArtifactBytes int64
|
||||||
maxResponseBytes int64
|
maxResponseBytes int64
|
||||||
backends []appconfig.BackendSettings
|
|
||||||
transientRetries *int
|
transientRetries *int
|
||||||
diagnostics []configkit.Diagnostic
|
diagnostics []configkit.Diagnostic
|
||||||
configOverlay string
|
configOverlay string
|
||||||
}
|
}
|
||||||
|
|
||||||
type commonCommandSettings struct {
|
type commonCommandSettings struct {
|
||||||
promptDir string
|
promptkitSources []appconfig.SourceSelection
|
||||||
profileDir string
|
|
||||||
schemaDir string
|
schemaDir string
|
||||||
serverAddr string
|
serverAddr string
|
||||||
artifactRoot string
|
artifactRoot string
|
||||||
@@ -106,7 +96,6 @@ type commonCommandSettings struct {
|
|||||||
maxArtifactBytes int64
|
maxArtifactBytes int64
|
||||||
maxResponseBytes int64
|
maxResponseBytes int64
|
||||||
defaultRenderFormat renderformat.PreparedRunOutputFormat
|
defaultRenderFormat renderformat.PreparedRunOutputFormat
|
||||||
backends []appconfig.BackendSettings
|
|
||||||
transientRetries *int
|
transientRetries *int
|
||||||
diagnostics []configkit.Diagnostic
|
diagnostics []configkit.Diagnostic
|
||||||
}
|
}
|
||||||
@@ -164,7 +153,11 @@ func runCommand(args []string, stdout, stderr io.Writer) int {
|
|||||||
|
|
||||||
engine, err := newEngine(cfg.engineSettings())
|
engine, err := newEngine(cfg.engineSettings())
|
||||||
if err != nil {
|
if err != nil {
|
||||||
fmt.Fprintf(stderr, "engine error: %v\n", err)
|
writeApplicationError(stderr, "engine", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
|
||||||
|
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
}
|
}
|
||||||
return executeRun(cfg, req, engine.Run, stdout, stderr)
|
return executeRun(cfg, req, engine.Run, stdout, stderr)
|
||||||
@@ -176,16 +169,10 @@ func executeRun(cfg *runConfig, req promptkit.RunRequest, run func(context.Conte
|
|||||||
collector = executionreport.NewCollector()
|
collector = executionreport.NewCollector()
|
||||||
req.Observer = collector.Observe
|
req.Observer = collector.Observe
|
||||||
}
|
}
|
||||||
runContext := context.Background()
|
req.OperationTimeout = cfg.runTimeout
|
||||||
cancel := func() {}
|
res, runErr := run(context.Background(), req)
|
||||||
if cfg.runTimeout > 0 {
|
|
||||||
runContext, cancel = context.WithTimeout(runContext, cfg.runTimeout)
|
|
||||||
}
|
|
||||||
res, runErr := run(runContext, req)
|
|
||||||
contextErr := runContext.Err()
|
|
||||||
cancel()
|
|
||||||
if runErr != nil {
|
if runErr != nil {
|
||||||
if errors.Is(contextErr, context.DeadlineExceeded) {
|
if errors.Is(runErr, promptkit.ErrOperationTimeout) {
|
||||||
fmt.Fprintln(stderr, "run error: execution deadline exceeded")
|
fmt.Fprintln(stderr, "run error: execution deadline exceeded")
|
||||||
} else {
|
} else {
|
||||||
fmt.Fprintln(stderr, runErrorMessage(runErr))
|
fmt.Fprintln(stderr, runErrorMessage(runErr))
|
||||||
@@ -242,7 +229,11 @@ func renderCommand(args []string, stdout, stderr io.Writer) int {
|
|||||||
|
|
||||||
engine, err := newEngine(cfg.runConfig.engineSettings())
|
engine, err := newEngine(cfg.runConfig.engineSettings())
|
||||||
if err != nil {
|
if err != nil {
|
||||||
fmt.Fprintf(stderr, "engine error: %v\n", err)
|
writeApplicationError(stderr, "engine", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
|
||||||
|
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -283,7 +274,11 @@ func serveCommand(args []string, stderr io.Writer) int {
|
|||||||
|
|
||||||
engine, err := newEngine(cfg.engineSettings(), promptkit.WithArtifactReader(artifactReader))
|
engine, err := newEngine(cfg.engineSettings(), promptkit.WithArtifactReader(artifactReader))
|
||||||
if err != nil {
|
if err != nil {
|
||||||
fmt.Fprintf(stderr, "engine error: %v\n", err)
|
writeApplicationError(stderr, "engine", err)
|
||||||
|
return ExitRuntimeError
|
||||||
|
}
|
||||||
|
if err := writeFrameworkDiagnostics(stderr, engine); err != nil {
|
||||||
|
fmt.Fprintf(stderr, "engine diagnostic write error: %v\n", err)
|
||||||
return ExitRuntimeError
|
return ExitRuntimeError
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -400,8 +395,8 @@ func parseServeArgs(args []string) (*serveConfig, error) {
|
|||||||
|
|
||||||
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
|
registerConfigSelectionFlags(fs, &cfg.configPath, &cfg.configOverlay)
|
||||||
fs.StringVar(&cfg.addr, "addr", "", "HTTP listen address")
|
fs.StringVar(&cfg.addr, "addr", "", "HTTP listen address")
|
||||||
fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definition YAML files")
|
var promptkitSources promptKitSourceFlagValue
|
||||||
fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profile YAML files")
|
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
|
||||||
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
|
fs.StringVar(&cfg.schemaDir, "schema-dir", "", "base directory for validation schemas")
|
||||||
fs.StringVar(&cfg.artifactRoot, "artifact-root", "", "base directory for HTTP file input artifacts")
|
fs.StringVar(&cfg.artifactRoot, "artifact-root", "", "base directory for HTTP file input artifacts")
|
||||||
fs.Int64Var(&cfg.maxRequestBytes, "max-request-bytes", 0, "maximum HTTP request body bytes; 0 disables the limit")
|
fs.Int64Var(&cfg.maxRequestBytes, "max-request-bytes", 0, "maximum HTTP request body bytes; 0 disables the limit")
|
||||||
@@ -420,30 +415,23 @@ func parseServeArgs(args []string) (*serveConfig, error) {
|
|||||||
return nil, err
|
return nil, err
|
||||||
}
|
}
|
||||||
|
|
||||||
cfg.promptDir = settings.promptDir
|
cfg.promptkitSources = settings.promptkitSources
|
||||||
cfg.profileDir = settings.profileDir
|
|
||||||
cfg.schemaDir = settings.schemaDir
|
cfg.schemaDir = settings.schemaDir
|
||||||
cfg.addr = settings.serverAddr
|
cfg.addr = settings.serverAddr
|
||||||
cfg.artifactRoot = settings.artifactRoot
|
cfg.artifactRoot = settings.artifactRoot
|
||||||
cfg.maxRequestBytes = settings.maxRequestBytes
|
cfg.maxRequestBytes = settings.maxRequestBytes
|
||||||
cfg.maxArtifactBytes = settings.maxArtifactBytes
|
cfg.maxArtifactBytes = settings.maxArtifactBytes
|
||||||
cfg.maxResponseBytes = settings.maxResponseBytes
|
cfg.maxResponseBytes = settings.maxResponseBytes
|
||||||
cfg.backends = settings.backends
|
|
||||||
cfg.transientRetries = settings.transientRetries
|
cfg.transientRetries = settings.transientRetries
|
||||||
cfg.diagnostics = settings.diagnostics
|
cfg.diagnostics = settings.diagnostics
|
||||||
|
|
||||||
if err := validateRequiredLibraryDirs(cfg.promptDir); err != nil {
|
|
||||||
return nil, err
|
|
||||||
}
|
|
||||||
|
|
||||||
return cfg, nil
|
return cfg, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
func registerExecutionRequestFlags(fs *flag.FlagSet, cfg *runConfig) {
|
func registerExecutionRequestFlags(fs *flag.FlagSet, cfg *runConfig) {
|
||||||
fs.StringVar(&cfg.promptDir, "prompt-dir", "", "directory containing prompt definition YAML files")
|
var promptkitSources promptKitSourceFlagValue
|
||||||
fs.StringVar(&cfg.profileDir, "profile-dir", "", "directory containing execution profile YAML files")
|
fs.Var(&promptkitSources, "promptkit-source", "selected PromptKit source path (repeatable)")
|
||||||
fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to run")
|
fs.StringVar(&cfg.promptID, "prompt", "", "prompt ID to run")
|
||||||
fs.StringVar(&cfg.promptVersion, "prompt-version", "", "optional prompt definition version")
|
|
||||||
fs.StringVar(&cfg.profileID, "profile", "", "optional execution profile ID; if omitted, prompt default_profile is used")
|
fs.StringVar(&cfg.profileID, "profile", "", "optional execution profile ID; if omitted, prompt default_profile is used")
|
||||||
fs.StringVar(&cfg.sessionID, "session-id", "", "optional session ID")
|
fs.StringVar(&cfg.sessionID, "session-id", "", "optional session ID")
|
||||||
fs.Var(&cfg.inputRaw, "input", "input mapping(s): name=path (repeatable, comma-separated)")
|
fs.Var(&cfg.inputRaw, "input", "input mapping(s): name=path (repeatable, comma-separated)")
|
||||||
@@ -472,17 +460,12 @@ func finalizeExecutionRequestConfig(fs *flag.FlagSet, cfg *runConfig) error {
|
|||||||
return err
|
return err
|
||||||
}
|
}
|
||||||
|
|
||||||
cfg.promptDir = settings.promptDir
|
cfg.promptkitSources = settings.promptkitSources
|
||||||
cfg.profileDir = settings.profileDir
|
|
||||||
cfg.schemaDir = settings.schemaDir
|
cfg.schemaDir = settings.schemaDir
|
||||||
cfg.defaultRenderFormat = settings.defaultRenderFormat
|
cfg.defaultRenderFormat = settings.defaultRenderFormat
|
||||||
cfg.backends = settings.backends
|
|
||||||
cfg.configuredTransientRetries = settings.transientRetries
|
cfg.configuredTransientRetries = settings.transientRetries
|
||||||
cfg.diagnostics = settings.diagnostics
|
cfg.diagnostics = settings.diagnostics
|
||||||
|
|
||||||
if err := validateRequiredLibraryDirs(cfg.promptDir); err != nil {
|
|
||||||
return err
|
|
||||||
}
|
|
||||||
if strings.TrimSpace(cfg.promptID) == "" {
|
if strings.TrimSpace(cfg.promptID) == "" {
|
||||||
return errors.New("--prompt is required")
|
return errors.New("--prompt is required")
|
||||||
}
|
}
|
||||||
@@ -524,8 +507,7 @@ func resolveCommonSettings(fs *flag.FlagSet, configPath, overlay string) (common
|
|||||||
return commonCommandSettings{}, err
|
return commonCommandSettings{}, err
|
||||||
}
|
}
|
||||||
return commonCommandSettings{
|
return commonCommandSettings{
|
||||||
promptDir: settings.PromptDir,
|
promptkitSources: settings.PromptKitSources,
|
||||||
profileDir: settings.ProfileDir,
|
|
||||||
schemaDir: settings.SchemaDir,
|
schemaDir: settings.SchemaDir,
|
||||||
serverAddr: settings.ServerAddr,
|
serverAddr: settings.ServerAddr,
|
||||||
artifactRoot: settings.ArtifactRoot,
|
artifactRoot: settings.ArtifactRoot,
|
||||||
@@ -533,54 +515,50 @@ func resolveCommonSettings(fs *flag.FlagSet, configPath, overlay string) (common
|
|||||||
maxArtifactBytes: settings.MaxArtifactBytes,
|
maxArtifactBytes: settings.MaxArtifactBytes,
|
||||||
maxResponseBytes: settings.MaxResponseBytes,
|
maxResponseBytes: settings.MaxResponseBytes,
|
||||||
defaultRenderFormat: settings.DefaultRenderFormat,
|
defaultRenderFormat: settings.DefaultRenderFormat,
|
||||||
backends: settings.Backends,
|
|
||||||
transientRetries: settings.TransientRetries,
|
transientRetries: settings.TransientRetries,
|
||||||
diagnostics: diagnostics,
|
diagnostics: diagnostics,
|
||||||
}, nil
|
}, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
func validateRequiredLibraryDirs(promptDir string) error {
|
|
||||||
if strings.TrimSpace(promptDir) == "" {
|
|
||||||
return errors.New(errPromptDirRequired)
|
|
||||||
}
|
|
||||||
return nil
|
|
||||||
}
|
|
||||||
|
|
||||||
type engineSettings struct {
|
type engineSettings struct {
|
||||||
promptDir string
|
promptkitSources []appconfig.SourceSelection
|
||||||
profileDir string
|
|
||||||
schemaDir string
|
schemaDir string
|
||||||
backends []appconfig.BackendSettings
|
|
||||||
transientRetries *int
|
transientRetries *int
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c runConfig) engineSettings() engineSettings {
|
func (c runConfig) engineSettings() engineSettings {
|
||||||
return engineSettings{promptDir: c.promptDir, profileDir: c.profileDir, schemaDir: c.schemaDir, backends: c.backends, transientRetries: c.configuredTransientRetries}
|
return engineSettings{promptkitSources: c.promptkitSources, schemaDir: c.schemaDir, transientRetries: c.configuredTransientRetries}
|
||||||
}
|
}
|
||||||
|
|
||||||
func (c serveConfig) engineSettings() engineSettings {
|
func (c serveConfig) engineSettings() engineSettings {
|
||||||
return engineSettings{promptDir: c.promptDir, profileDir: c.profileDir, schemaDir: c.schemaDir, backends: c.backends, transientRetries: c.transientRetries}
|
return engineSettings{promptkitSources: c.promptkitSources, schemaDir: c.schemaDir, transientRetries: c.transientRetries}
|
||||||
}
|
}
|
||||||
|
|
||||||
func newEngine(settings engineSettings, options ...promptkit.Option) (*promptkit.Engine, error) {
|
func newEngine(settings engineSettings, options ...promptkit.Option) (*promptkit.Engine, error) {
|
||||||
engineOptions := make([]promptkit.Option, 0, len(settings.backends)+len(options))
|
underlays := make([]configkit.Underlay, 0, len(settings.promptkitSources))
|
||||||
for _, configured := range settings.backends {
|
for index, selection := range settings.promptkitSources {
|
||||||
engineOptions = append(engineOptions, promptkit.WithBackend(promptkit.Backend{
|
var inputs []configkit.Input
|
||||||
ID: configured.ID,
|
switch {
|
||||||
Endpoint: configured.Endpoint,
|
case selection.File != "" && selection.Directory == "":
|
||||||
APIKeyEnv: configured.APIKeyEnv,
|
inputs = []configkit.Input{{Source: configkit.File(selection.File), Imports: true}}
|
||||||
ExtraParams: configured.ExtraParams,
|
case selection.Directory != "" && selection.File == "":
|
||||||
ConcurrencyLimit: configured.ConcurrencyLimit,
|
var err error
|
||||||
QueueCapacity: configured.QueueCapacity,
|
inputs, err = promptkit.DirectoryInputs(selection.Directory)
|
||||||
}))
|
if err != nil {
|
||||||
|
cause := fmt.Errorf("PromptKit source %d directory %q: %w", index+1, selection.Directory, err)
|
||||||
|
return nil, fmt.Errorf("engine initialization from application configuration: %w", errors.Join(promptkit.ErrInvalidConfig, cause))
|
||||||
|
}
|
||||||
|
default:
|
||||||
|
cause := fmt.Errorf("PromptKit source %d must select exactly one file or directory", index+1)
|
||||||
|
return nil, fmt.Errorf("engine initialization from application configuration: %w", errors.Join(promptkit.ErrInvalidConfig, cause))
|
||||||
|
}
|
||||||
|
underlays = append(underlays, configkit.Underlay{Inputs: inputs})
|
||||||
}
|
}
|
||||||
engineOptions = append(engineOptions, options...)
|
|
||||||
engine, err := promptkit.NewEngine(promptkit.Config{
|
engine, err := promptkit.NewEngine(promptkit.Config{
|
||||||
PromptDir: settings.promptDir,
|
Sources: promptkit.ConfigurationSources{Underlays: underlays},
|
||||||
ProfileDir: settings.profileDir,
|
|
||||||
SchemaDir: settings.schemaDir,
|
SchemaDir: settings.schemaDir,
|
||||||
TransientRetries: settings.transientRetries,
|
TransientRetries: settings.transientRetries,
|
||||||
}, engineOptions...)
|
}, options...)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, fmt.Errorf("engine initialization from application configuration: %w", err)
|
return nil, fmt.Errorf("engine initialization from application configuration: %w", err)
|
||||||
}
|
}
|
||||||
@@ -644,7 +622,6 @@ func buildRunRequestFromConfig(cfg *runConfig) (promptkit.RunRequest, error) {
|
|||||||
}
|
}
|
||||||
return promptkit.RunRequest{
|
return promptkit.RunRequest{
|
||||||
PromptID: cfg.promptID,
|
PromptID: cfg.promptID,
|
||||||
PromptVersion: cfg.promptVersion,
|
|
||||||
ProfileID: cfg.profileID,
|
ProfileID: cfg.profileID,
|
||||||
SessionID: cfg.sessionID,
|
SessionID: cfg.sessionID,
|
||||||
Inputs: inputs,
|
Inputs: inputs,
|
||||||
@@ -723,9 +700,8 @@ func printSummary(stderr io.Writer, res *promptkit.RunResult) {
|
|||||||
if res == nil {
|
if res == nil {
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
fmt.Fprintf(stderr, "prompt=%s@%s selected_profile=%s model=%s validation=%s mode=%s validation_errors=%d prompt_hash=%s inputs=%d usage=%d/%d/%d",
|
fmt.Fprintf(stderr, "prompt=%s selected_profile=%s model=%s validation=%s mode=%s validation_errors=%d prompt_hash=%s inputs=%d usage=%d/%d/%d",
|
||||||
res.PromptID,
|
res.PromptID,
|
||||||
res.PromptVersion,
|
|
||||||
res.SelectedProfileID,
|
res.SelectedProfileID,
|
||||||
res.ModelName,
|
res.ModelName,
|
||||||
res.Validation.Status,
|
res.Validation.Status,
|
||||||
@@ -755,10 +731,11 @@ func runErrorMessage(err error) string {
|
|||||||
|
|
||||||
func printUsage(w io.Writer) {
|
func printUsage(w io.Writer) {
|
||||||
fmt.Fprintln(w, "usage: scriptorium <run|render|serve|inspect|config> ...")
|
fmt.Fprintln(w, "usage: scriptorium <run|render|serve|inspect|config> ...")
|
||||||
fmt.Fprintln(w, " run: scriptorium run [--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR] --prompt ID [--prompt-version VERSION] [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--out path] [--execution-report path] [--timeout 10m] [--run-timeout 10m] [--transient-retries N]")
|
fmt.Fprintln(w, " run: scriptorium run [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] --prompt ID [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--out path] [--execution-report path] [--timeout 10m] [--run-timeout 10m] [--transient-retries N]")
|
||||||
fmt.Fprintln(w, " render: scriptorium render [--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR] --prompt ID [--prompt-version VERSION] [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--format text|json] [--out path] [--timeout 10m] [--transient-retries N]")
|
fmt.Fprintln(w, " render: scriptorium render [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] --prompt ID [--input name=path] [--profile ID] [--session-id ID] [--llm-base-url URL] [--model NAME] [--api-key-env ENV] [--temperature N] [--max-tokens N] [--top-p N] [--reasoning-effort VALUE] [--var k=v] [--format text|json] [--out path] [--timeout 10m] [--transient-retries N]")
|
||||||
fmt.Fprintf(w, " serve: scriptorium serve [--config PATH] [--config-overlay NAME] [--addr %s] [--prompt-dir DIR] [--profile-dir DIR] [--schema-dir DIR] [--artifact-root DIR] [--max-request-bytes N] [--max-artifact-bytes N] [--max-response-bytes N]\n", defaults.HTTPAddrDefault)
|
fmt.Fprintf(w, " serve: scriptorium serve [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--addr %s] [--schema-dir DIR] [--artifact-root DIR] [--max-request-bytes N] [--max-artifact-bytes N] [--max-response-bytes N]\n", defaults.HTTPAddrDefault)
|
||||||
fmt.Fprintln(w, " inspect prompt: scriptorium inspect prompt --prompt ID [--prompt-version VERSION] [--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out path]")
|
fmt.Fprintln(w, " inspect prompt: scriptorium inspect prompt --prompt ID [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out path]")
|
||||||
fmt.Fprintln(w, " inspect profile: scriptorium inspect profile --profile ID [--config PATH] [--config-overlay NAME] [--profile-dir DIR] [--format text|json] [--out path]")
|
fmt.Fprintln(w, " inspect profile: scriptorium inspect profile --profile ID [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out path]")
|
||||||
|
fmt.Fprintln(w, " inspect configuration: scriptorium inspect configuration <validate|show|sources|explain> [--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--path JSON_POINTER (required for explain)]")
|
||||||
fmt.Fprintln(w, " config: scriptorium config <validate|show|sources|explain> [--config PATH] [--config-overlay NAME] [application overrides] [--path /pointer for explain]")
|
fmt.Fprintln(w, " config: scriptorium config <validate|show|sources|explain> [--config PATH] [--config-overlay NAME] [application overrides] [--path /pointer for explain]")
|
||||||
}
|
}
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@@ -15,7 +15,7 @@ import (
|
|||||||
|
|
||||||
const (
|
const (
|
||||||
scriptoriumModulePath = "gitea.maximumdirect.net/eric/scriptorium"
|
scriptoriumModulePath = "gitea.maximumdirect.net/eric/scriptorium"
|
||||||
promptkitInternalPath = "gitea.maximumdirect.net/eric/promptkit/internal"
|
promptkitInternalPath = "go.maximumdirect.net/promptkit/internal"
|
||||||
promptkitOpenRouterCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-openrouter"
|
promptkitOpenRouterCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-openrouter"
|
||||||
promptkitRakestrawhomeCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome"
|
promptkitRakestrawhomeCatalogPath = "gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome"
|
||||||
)
|
)
|
||||||
@@ -149,7 +149,7 @@ func TestForbiddenImportScannerAllowsRetainedApplicationPackages(t *testing.T) {
|
|||||||
source := `package consumer
|
source := `package consumer
|
||||||
|
|
||||||
import (
|
import (
|
||||||
_ "gitea.maximumdirect.net/eric/promptkit"
|
_ "go.maximumdirect.net/promptkit"
|
||||||
_ "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http"
|
_ "gitea.maximumdirect.net/eric/scriptorium/internal/adapter/http"
|
||||||
_ "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
_ "gitea.maximumdirect.net/eric/scriptorium/internal/config"
|
||||||
_ "gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
_ "gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
||||||
|
|||||||
@@ -6,12 +6,13 @@ import (
|
|||||||
"errors"
|
"errors"
|
||||||
"fmt"
|
"fmt"
|
||||||
"io"
|
"io"
|
||||||
|
"math"
|
||||||
"mime"
|
"mime"
|
||||||
"os"
|
"os"
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
var (
|
var (
|
||||||
@@ -136,7 +137,11 @@ func readArtifactFile(path string, maxBytes int64) (*promptkit.Artifact, error)
|
|||||||
|
|
||||||
var reader io.Reader = file
|
var reader io.Reader = file
|
||||||
if maxBytes > 0 {
|
if maxBytes > 0 {
|
||||||
reader = io.LimitReader(file, maxBytes+1)
|
readLimit := maxBytes
|
||||||
|
if readLimit < math.MaxInt64 {
|
||||||
|
readLimit++ // Read one extra byte to detect an oversized file.
|
||||||
|
}
|
||||||
|
reader = io.LimitReader(file, readLimit)
|
||||||
}
|
}
|
||||||
body, err := io.ReadAll(reader)
|
body, err := io.ReadAll(reader)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
|
|||||||
@@ -3,14 +3,45 @@ package httpadapter
|
|||||||
import (
|
import (
|
||||||
"context"
|
"context"
|
||||||
"errors"
|
"errors"
|
||||||
|
"math"
|
||||||
"mime"
|
"mime"
|
||||||
"os"
|
"os"
|
||||||
"path/filepath"
|
"path/filepath"
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
|
func TestRestrictedArtifactReaderReturnsDetachedBodies(t *testing.T) {
|
||||||
|
root := t.TempDir()
|
||||||
|
if err := os.WriteFile(filepath.Join(root, "input.txt"), []byte("original"), 0o644); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
reader, err := NewRestrictedArtifactReader(root, 0)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
for _, ref := range []promptkit.ArtifactRef{promptkit.Inline("original"), promptkit.File("input.txt")} {
|
||||||
|
first, err := reader.Read(context.Background(), ref)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
second, err := reader.Read(context.Background(), ref)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
first.Body[0] = 'X'
|
||||||
|
first.Name = "changed"
|
||||||
|
if string(second.Body) != "original" || second.Name == "changed" {
|
||||||
|
t.Fatalf("read results share mutable state: %+v", second)
|
||||||
|
}
|
||||||
|
second.Body[1] = 'Y'
|
||||||
|
if string(first.Body) != "Xriginal" {
|
||||||
|
t.Fatalf("reader retained a body alias: %q", first.Body)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
func TestRestrictedArtifactReaderReadsContainedFiles(t *testing.T) {
|
func TestRestrictedArtifactReaderReadsContainedFiles(t *testing.T) {
|
||||||
root := t.TempDir()
|
root := t.TempDir()
|
||||||
outside := t.TempDir()
|
outside := t.TempDir()
|
||||||
@@ -150,6 +181,15 @@ func TestRestrictedArtifactReaderEnforcesLimits(t *testing.T) {
|
|||||||
t.Fatalf("expected unlimited artifact, got %#v and %v", artifact, err)
|
t.Fatalf("expected unlimited artifact, got %#v and %v", artifact, err)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
maxLimited, err := NewRestrictedArtifactReader(root, math.MaxInt64)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("construct reader at maximum limit: %v", err)
|
||||||
|
}
|
||||||
|
artifact, err = maxLimited.Read(context.Background(), promptkit.File("large.txt"))
|
||||||
|
if err != nil || string(artifact.Body) != "123456" || artifact.Size != 6 {
|
||||||
|
t.Fatalf("expected full artifact at maximum limit, got %#v and %v", artifact, err)
|
||||||
|
}
|
||||||
|
|
||||||
if _, err := NewRestrictedArtifactReader(root, -1); err == nil {
|
if _, err := NewRestrictedArtifactReader(root, -1); err == nil {
|
||||||
t.Fatal("expected negative limit to fail")
|
t.Fatal("expected negative limit to fail")
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -8,7 +8,6 @@ import (
|
|||||||
|
|
||||||
type runRequestDTO struct {
|
type runRequestDTO struct {
|
||||||
PromptID string `json:"prompt_id"`
|
PromptID string `json:"prompt_id"`
|
||||||
PromptVersion string `json:"prompt_version,omitempty"`
|
|
||||||
ProfileID string `json:"profile_id,omitempty"`
|
ProfileID string `json:"profile_id,omitempty"`
|
||||||
SessionID string `json:"session_id,omitempty"`
|
SessionID string `json:"session_id,omitempty"`
|
||||||
Inputs map[string]inputRefDTO `json:"inputs"`
|
Inputs map[string]inputRefDTO `json:"inputs"`
|
||||||
@@ -59,28 +58,21 @@ type artifactDTO struct {
|
|||||||
type metadataDTO struct {
|
type metadataDTO struct {
|
||||||
RunID string `json:"run_id"`
|
RunID string `json:"run_id"`
|
||||||
PromptID string `json:"prompt_id"`
|
PromptID string `json:"prompt_id"`
|
||||||
PromptVersion string `json:"prompt_version"`
|
|
||||||
PromptHash string `json:"prompt_hash"`
|
PromptHash string `json:"prompt_hash"`
|
||||||
RenderedPromptHash string `json:"rendered_prompt_hash"`
|
RenderedPromptHash string `json:"rendered_prompt_hash"`
|
||||||
SelectedProfileID string `json:"selected_profile_id"`
|
SelectedProfileID string `json:"selected_profile_id"`
|
||||||
SelectedBackendID string `json:"selected_backend_id,omitempty"`
|
SelectedBackendID string `json:"selected_backend_id,omitempty"`
|
||||||
SessionID string `json:"session_id,omitempty"`
|
SessionID string `json:"session_id,omitempty"`
|
||||||
ModelName string `json:"model_name"`
|
|
||||||
Endpoint string `json:"endpoint"`
|
|
||||||
ModelParams modelParamsDTO `json:"model_params"`
|
ModelParams modelParamsDTO `json:"model_params"`
|
||||||
InputHashes map[string]string `json:"input_hashes"`
|
InputHashes map[string]string `json:"input_hashes"`
|
||||||
Usage tokenUsageDTO `json:"usage"`
|
Usage tokenUsageDTO `json:"usage"`
|
||||||
StartTime time.Time `json:"start_time"`
|
StartTime time.Time `json:"start_time"`
|
||||||
EndTime time.Time `json:"end_time"`
|
EndTime time.Time `json:"end_time"`
|
||||||
DurationMS int64 `json:"duration_ms"`
|
DurationMS int64 `json:"duration_ms"`
|
||||||
ValidationMode string `json:"validation_mode"`
|
|
||||||
ValidationStatus string `json:"validation_status"`
|
|
||||||
RepairAttemptsUsed int `json:"repair_attempts_used"`
|
|
||||||
}
|
}
|
||||||
|
|
||||||
type modelParamsDTO struct {
|
type modelParamsDTO struct {
|
||||||
Endpoint string `json:"endpoint"`
|
Endpoint string `json:"endpoint"`
|
||||||
BackendID string `json:"backend_id,omitempty"`
|
|
||||||
Model string `json:"model"`
|
Model string `json:"model"`
|
||||||
Temperature float64 `json:"temperature"`
|
Temperature float64 `json:"temperature"`
|
||||||
MaxTokens int `json:"max_tokens"`
|
MaxTokens int `json:"max_tokens"`
|
||||||
|
|||||||
@@ -10,9 +10,9 @@ import (
|
|||||||
"strings"
|
"strings"
|
||||||
"time"
|
"time"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
|
||||||
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
||||||
executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report"
|
executionreport "gitea.maximumdirect.net/eric/scriptorium/internal/report"
|
||||||
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
type Runner interface {
|
type Runner interface {
|
||||||
@@ -106,38 +106,36 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
|||||||
model = executionTargetOverrideFromModelOverrideDTO(req.Model)
|
model = executionTargetOverrideFromModelOverrideDTO(req.Model)
|
||||||
}
|
}
|
||||||
|
|
||||||
runContext := r.Context()
|
var operationTimeout time.Duration
|
||||||
if req.RunTimeoutSeconds != nil && *req.RunTimeoutSeconds > 0 {
|
if req.RunTimeoutSeconds != nil && *req.RunTimeoutSeconds > 0 {
|
||||||
var cancel context.CancelFunc
|
operationTimeout = time.Duration(*req.RunTimeoutSeconds) * time.Second
|
||||||
runContext, cancel = context.WithTimeout(runContext, time.Duration(*req.RunTimeoutSeconds)*time.Second)
|
|
||||||
defer cancel()
|
|
||||||
}
|
}
|
||||||
mappedRequest := promptkit.RunRequest{
|
mappedRequest := promptkit.RunRequest{
|
||||||
PromptID: req.PromptID,
|
PromptID: req.PromptID,
|
||||||
PromptVersion: req.PromptVersion,
|
|
||||||
ProfileID: req.ProfileID,
|
ProfileID: req.ProfileID,
|
||||||
SessionID: req.SessionID,
|
SessionID: req.SessionID,
|
||||||
Inputs: mappedInputs,
|
Inputs: mappedInputs,
|
||||||
Vars: req.Vars,
|
Vars: req.Vars,
|
||||||
Execution: model,
|
Execution: model,
|
||||||
TransientRetries: req.TransientRetries,
|
TransientRetries: req.TransientRetries,
|
||||||
|
OperationTimeout: operationTimeout,
|
||||||
}
|
}
|
||||||
var collector *executionreport.Collector
|
var collector *executionreport.Collector
|
||||||
if req.IncludeExecutionReport {
|
if req.IncludeExecutionReport {
|
||||||
collector = executionreport.NewCollector()
|
collector = executionreport.NewCollector()
|
||||||
mappedRequest.Observer = collector.Observe
|
mappedRequest.Observer = collector.Observe
|
||||||
}
|
}
|
||||||
res, err := h.runner.Run(runContext, mappedRequest)
|
res, err := h.runner.Run(r.Context(), mappedRequest)
|
||||||
var execution *executionreport.Execution
|
var execution *executionreport.Execution
|
||||||
if collector != nil {
|
if collector != nil {
|
||||||
execution = collector.Snapshot()
|
execution = collector.Snapshot()
|
||||||
}
|
}
|
||||||
if err != nil {
|
if err != nil {
|
||||||
switch runContext.Err() {
|
switch {
|
||||||
case context.DeadlineExceeded:
|
case errors.Is(err, promptkit.ErrOperationTimeout), errors.Is(err, context.DeadlineExceeded) && errors.Is(r.Context().Err(), context.DeadlineExceeded):
|
||||||
writeRunFailure(w, http.StatusGatewayTimeout, "deadline_exceeded", "run execution deadline exceeded", execution, h.options.MaxResponseBytes)
|
writeRunFailure(w, http.StatusGatewayTimeout, "deadline_exceeded", "run execution deadline exceeded", execution, h.options.MaxResponseBytes)
|
||||||
return
|
return
|
||||||
case context.Canceled:
|
case errors.Is(err, context.Canceled) && errors.Is(r.Context().Err(), context.Canceled):
|
||||||
writeRunFailure(w, http.StatusRequestTimeout, "request_canceled", "run request canceled", execution, h.options.MaxResponseBytes)
|
writeRunFailure(w, http.StatusRequestTimeout, "request_canceled", "run request canceled", execution, h.options.MaxResponseBytes)
|
||||||
return
|
return
|
||||||
}
|
}
|
||||||
@@ -159,14 +157,11 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
|||||||
Metadata: metadataDTO{
|
Metadata: metadataDTO{
|
||||||
RunID: res.RunID,
|
RunID: res.RunID,
|
||||||
PromptID: res.PromptID,
|
PromptID: res.PromptID,
|
||||||
PromptVersion: res.PromptVersion,
|
|
||||||
PromptHash: res.PromptHash,
|
PromptHash: res.PromptHash,
|
||||||
RenderedPromptHash: res.RenderedPromptHash,
|
RenderedPromptHash: res.RenderedPromptHash,
|
||||||
SelectedProfileID: res.SelectedProfileID,
|
SelectedProfileID: res.SelectedProfileID,
|
||||||
SelectedBackendID: res.SelectedBackendID,
|
SelectedBackendID: res.SelectedBackendID,
|
||||||
SessionID: res.SessionID,
|
SessionID: res.SessionID,
|
||||||
ModelName: res.ModelName,
|
|
||||||
Endpoint: res.Endpoint,
|
|
||||||
ModelParams: modelParamsDTOFromExecutionTarget(res.EffectiveModelParams),
|
ModelParams: modelParamsDTOFromExecutionTarget(res.EffectiveModelParams),
|
||||||
InputHashes: res.InputHashes,
|
InputHashes: res.InputHashes,
|
||||||
Usage: tokenUsageDTO{
|
Usage: tokenUsageDTO{
|
||||||
@@ -179,9 +174,6 @@ func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
|
|||||||
StartTime: res.StartTime,
|
StartTime: res.StartTime,
|
||||||
EndTime: res.EndTime,
|
EndTime: res.EndTime,
|
||||||
DurationMS: res.Duration.Milliseconds(),
|
DurationMS: res.Duration.Milliseconds(),
|
||||||
ValidationMode: string(res.Validation.Mode),
|
|
||||||
ValidationStatus: string(res.Validation.Status),
|
|
||||||
RepairAttemptsUsed: res.Validation.RepairAttempts,
|
|
||||||
},
|
},
|
||||||
Execution: execution,
|
Execution: execution,
|
||||||
}
|
}
|
||||||
@@ -221,7 +213,6 @@ func executionTargetOverrideFromModelOverrideDTO(dto *modelOverrideRequestDTO) *
|
|||||||
func modelParamsDTOFromExecutionTarget(target promptkit.ExecutionTarget) modelParamsDTO {
|
func modelParamsDTOFromExecutionTarget(target promptkit.ExecutionTarget) modelParamsDTO {
|
||||||
return modelParamsDTO{
|
return modelParamsDTO{
|
||||||
Endpoint: target.Endpoint,
|
Endpoint: target.Endpoint,
|
||||||
BackendID: target.BackendID,
|
|
||||||
Model: target.Model,
|
Model: target.Model,
|
||||||
Temperature: target.Temperature,
|
Temperature: target.Temperature,
|
||||||
MaxTokens: target.MaxTokens,
|
MaxTokens: target.MaxTokens,
|
||||||
@@ -255,16 +246,16 @@ func mapRunError(err error) (int, string, string) {
|
|||||||
return http.StatusBadRequest, "profile_required", "profile_id is required when prompt default_profile is not set"
|
return http.StatusBadRequest, "profile_required", "profile_id is required when prompt default_profile is not set"
|
||||||
case errors.Is(err, promptkit.ErrAPIKeyEnvMissing):
|
case errors.Is(err, promptkit.ErrAPIKeyEnvMissing):
|
||||||
return http.StatusBadRequest, "api_key_env_missing", "api_key_env is set but the environment variable is missing"
|
return http.StatusBadRequest, "api_key_env_missing", "api_key_env is set but the environment variable is missing"
|
||||||
|
case errors.Is(err, ErrFileNotAllowed), errors.Is(err, ErrFileOutsideRoot):
|
||||||
|
return http.StatusBadRequest, "artifact_not_allowed", "file input artifact is not allowed"
|
||||||
|
case errors.Is(err, ErrFileTooLarge):
|
||||||
|
return http.StatusRequestEntityTooLarge, "artifact_too_large", "file input artifact is too large"
|
||||||
case errors.Is(err, promptkit.ErrPromptLoad):
|
case errors.Is(err, promptkit.ErrPromptLoad):
|
||||||
return http.StatusBadRequest, "prompt_load_failed", "failed to load prompt definition"
|
return http.StatusBadRequest, "prompt_load_failed", "failed to load prompt definition"
|
||||||
case errors.Is(err, promptkit.ErrProfileLoad):
|
case errors.Is(err, promptkit.ErrProfileLoad):
|
||||||
return http.StatusBadRequest, "profile_load_failed", "failed to load execution profile"
|
return http.StatusBadRequest, "profile_load_failed", "failed to load execution profile"
|
||||||
case errors.Is(err, promptkit.ErrInvalidRequest):
|
case errors.Is(err, promptkit.ErrInvalidRequest):
|
||||||
return http.StatusBadRequest, "invalid_request", "invalid run request"
|
return http.StatusBadRequest, "invalid_request", "invalid run request"
|
||||||
case errors.Is(err, ErrFileNotAllowed), errors.Is(err, ErrFileOutsideRoot):
|
|
||||||
return http.StatusBadRequest, "artifact_not_allowed", "file input artifact is not allowed"
|
|
||||||
case errors.Is(err, ErrFileTooLarge):
|
|
||||||
return http.StatusRequestEntityTooLarge, "artifact_too_large", "file input artifact is too large"
|
|
||||||
case errors.Is(err, promptkit.ErrArtifactLoad):
|
case errors.Is(err, promptkit.ErrArtifactLoad):
|
||||||
return http.StatusBadRequest, "artifact_read_failed", "failed to read input artifact"
|
return http.StatusBadRequest, "artifact_read_failed", "failed to read input artifact"
|
||||||
case errors.Is(err, promptkit.ErrPromptRender):
|
case errors.Is(err, promptkit.ErrPromptRender):
|
||||||
|
|||||||
@@ -4,6 +4,7 @@ import (
|
|||||||
"bytes"
|
"bytes"
|
||||||
"context"
|
"context"
|
||||||
"encoding/json"
|
"encoding/json"
|
||||||
|
"errors"
|
||||||
"fmt"
|
"fmt"
|
||||||
"net/http"
|
"net/http"
|
||||||
"net/http/httptest"
|
"net/http/httptest"
|
||||||
@@ -15,7 +16,8 @@ import (
|
|||||||
"testing"
|
"testing"
|
||||||
"time"
|
"time"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
"go.maximumdirect.net/configkit"
|
||||||
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
type fakeRunner struct {
|
type fakeRunner struct {
|
||||||
@@ -335,11 +337,13 @@ func TestHandlerRunTimeoutValidationAndContextMapping(t *testing.T) {
|
|||||||
name, body string
|
name, body string
|
||||||
parent context.Context
|
parent context.Context
|
||||||
wantDeadline time.Time
|
wantDeadline time.Time
|
||||||
|
wantTimeout time.Duration
|
||||||
}{
|
}{
|
||||||
{name: "omitted inherits deadline", body: `{"prompt_id":"p"}`, parent: parent, wantDeadline: parentDeadline},
|
{name: "omitted inherits deadline", body: `{"prompt_id":"p"}`, parent: parent, wantDeadline: parentDeadline},
|
||||||
{name: "null inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: parent, wantDeadline: parentDeadline},
|
{name: "null inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: parent, wantDeadline: parentDeadline},
|
||||||
{name: "zero inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: parent, wantDeadline: parentDeadline},
|
{name: "zero inherits deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: parent, wantDeadline: parentDeadline},
|
||||||
{name: "positive preserves earlier deadline", body: `{"prompt_id":"p","run_timeout_seconds":10}`, parent: parent, wantDeadline: parentDeadline},
|
{name: "positive preserves earlier deadline", body: `{"prompt_id":"p","run_timeout_seconds":10}`, parent: parent, wantDeadline: parentDeadline, wantTimeout: 10 * time.Second},
|
||||||
|
{name: "positive adds operation budget", body: `{"prompt_id":"p","run_timeout_seconds":2}`, parent: context.Background(), wantTimeout: 2 * time.Second},
|
||||||
{name: "omitted adds no deadline", body: `{"prompt_id":"p"}`, parent: context.Background()},
|
{name: "omitted adds no deadline", body: `{"prompt_id":"p"}`, parent: context.Background()},
|
||||||
{name: "null adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: context.Background()},
|
{name: "null adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":null}`, parent: context.Background()},
|
||||||
{name: "zero adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: context.Background()},
|
{name: "zero adds no deadline", body: `{"prompt_id":"p","run_timeout_seconds":0}`, parent: context.Background()},
|
||||||
@@ -352,6 +356,9 @@ func TestHandlerRunTimeoutValidationAndContextMapping(t *testing.T) {
|
|||||||
if ok != !tc.wantDeadline.IsZero() || (ok && !deadline.Equal(tc.wantDeadline)) {
|
if ok != !tc.wantDeadline.IsZero() || (ok && !deadline.Equal(tc.wantDeadline)) {
|
||||||
t.Fatalf("execution deadline: got %v (present=%t), want %v", deadline, ok, tc.wantDeadline)
|
t.Fatalf("execution deadline: got %v (present=%t), want %v", deadline, ok, tc.wantDeadline)
|
||||||
}
|
}
|
||||||
|
if req.OperationTimeout != tc.wantTimeout {
|
||||||
|
t.Fatalf("operation timeout = %v, want %v", req.OperationTimeout, tc.wantTimeout)
|
||||||
|
}
|
||||||
return &promptkit.RunResult{}, nil
|
return &promptkit.RunResult{}, nil
|
||||||
}))
|
}))
|
||||||
w := httptest.NewRecorder()
|
w := httptest.NewRecorder()
|
||||||
@@ -381,6 +388,22 @@ func TestHandlerRunTimeoutValidationAndContextMapping(t *testing.T) {
|
|||||||
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":10}`)))
|
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":10}`)))
|
||||||
assertHTTPErrorCode(t, w, http.StatusBadGateway, "llm_failed")
|
assertHTTPErrorCode(t, w, http.StatusBadGateway, "llm_failed")
|
||||||
|
|
||||||
|
expired, cancelExpired := context.WithDeadline(context.Background(), time.Now().Add(-time.Second))
|
||||||
|
defer cancelExpired()
|
||||||
|
h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) {
|
||||||
|
return nil, fmt.Errorf("run failed: %w", ctx.Err())
|
||||||
|
}))
|
||||||
|
w = httptest.NewRecorder()
|
||||||
|
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)).WithContext(expired))
|
||||||
|
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
|
||||||
|
|
||||||
|
h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) {
|
||||||
|
return nil, errors.Join(promptkit.ErrOperationTimeout, context.Canceled)
|
||||||
|
}))
|
||||||
|
w = httptest.NewRecorder()
|
||||||
|
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)).WithContext(canceled))
|
||||||
|
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
|
||||||
|
|
||||||
successContext, cancelSuccess := context.WithCancel(context.Background())
|
successContext, cancelSuccess := context.WithCancel(context.Background())
|
||||||
h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) {
|
h = NewHandler(runnerFunc(func(ctx context.Context, req promptkit.RunRequest) (*promptkit.RunResult, error) {
|
||||||
cancelSuccess()
|
cancelSuccess()
|
||||||
@@ -446,7 +469,6 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
|
|||||||
},
|
},
|
||||||
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true},
|
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true},
|
||||||
PromptID: "prompt-1",
|
PromptID: "prompt-1",
|
||||||
PromptVersion: "1.0.0",
|
|
||||||
PromptHash: "phash",
|
PromptHash: "phash",
|
||||||
RenderedPromptHash: "rhash",
|
RenderedPromptHash: "rhash",
|
||||||
SelectedProfileID: "exec-default",
|
SelectedProfileID: "exec-default",
|
||||||
@@ -507,8 +529,10 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
|
|||||||
if metadata["prompt_id"] != "prompt-1" {
|
if metadata["prompt_id"] != "prompt-1" {
|
||||||
t.Fatalf("unexpected metadata.prompt_id: %#v", metadata["prompt_id"])
|
t.Fatalf("unexpected metadata.prompt_id: %#v", metadata["prompt_id"])
|
||||||
}
|
}
|
||||||
if metadata["prompt_version"] != "1.0.0" {
|
for _, field := range []string{"prompt_version", "model_name", "endpoint", "validation_mode", "validation_status", "repair_attempts_used"} {
|
||||||
t.Fatalf("unexpected metadata.prompt_version: %#v", metadata["prompt_version"])
|
if _, ok := metadata[field]; ok {
|
||||||
|
t.Fatalf("redundant metadata field %q: %#v", field, metadata)
|
||||||
|
}
|
||||||
}
|
}
|
||||||
if metadata["selected_profile_id"] != "exec-default" {
|
if metadata["selected_profile_id"] != "exec-default" {
|
||||||
t.Fatalf("unexpected metadata.selected_profile_id: %#v", metadata["selected_profile_id"])
|
t.Fatalf("unexpected metadata.selected_profile_id: %#v", metadata["selected_profile_id"])
|
||||||
@@ -516,9 +540,6 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
|
|||||||
if metadata["selected_backend_id"] != "local" {
|
if metadata["selected_backend_id"] != "local" {
|
||||||
t.Fatalf("unexpected metadata.selected_backend_id: %#v", metadata["selected_backend_id"])
|
t.Fatalf("unexpected metadata.selected_backend_id: %#v", metadata["selected_backend_id"])
|
||||||
}
|
}
|
||||||
if metadata["model_name"] != "m1" || metadata["endpoint"] != "http://llm/v1" {
|
|
||||||
t.Fatalf("unexpected model metadata: name=%#v endpoint=%#v", metadata["model_name"], metadata["endpoint"])
|
|
||||||
}
|
|
||||||
usage := metadata["usage"].(map[string]any)
|
usage := metadata["usage"].(map[string]any)
|
||||||
if usage["prompt_tokens"] != float64(1) || usage["completion_tokens"] != float64(2) || usage["total_tokens"] != float64(3) {
|
if usage["prompt_tokens"] != float64(1) || usage["completion_tokens"] != float64(2) || usage["total_tokens"] != float64(3) {
|
||||||
t.Fatalf("unexpected base usage metadata: %#v", usage)
|
t.Fatalf("unexpected base usage metadata: %#v", usage)
|
||||||
@@ -527,8 +548,8 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
|
|||||||
t.Fatalf("unexpected cache usage metadata: %#v", usage)
|
t.Fatalf("unexpected cache usage metadata: %#v", usage)
|
||||||
}
|
}
|
||||||
modelParams := metadata["model_params"].(map[string]any)
|
modelParams := metadata["model_params"].(map[string]any)
|
||||||
if modelParams["backend_id"] != "local" {
|
if _, ok := modelParams["backend_id"]; ok || modelParams["model"] != "m1" || modelParams["endpoint"] != "http://llm/v1" {
|
||||||
t.Fatalf("expected model_params.backend_id=local, got %#v", modelParams["backend_id"])
|
t.Fatalf("unexpected model parameters: %#v", modelParams)
|
||||||
}
|
}
|
||||||
if modelParams["api_key_env"] != envName {
|
if modelParams["api_key_env"] != envName {
|
||||||
t.Fatalf("expected model_params.api_key_env=%q, got %#v", envName, modelParams["api_key_env"])
|
t.Fatalf("expected model_params.api_key_env=%q, got %#v", envName, modelParams["api_key_env"])
|
||||||
@@ -560,7 +581,7 @@ func TestHandlerPostRunsSuccessWithExplicitProfileID(t *testing.T) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) {
|
func TestHandlerAllowsOmittedInputsAndPreservesQualifiedIDs(t *testing.T) {
|
||||||
r := &fakeRunner{result: &promptkit.RunResult{
|
r := &fakeRunner{result: &promptkit.RunResult{
|
||||||
Artifact: promptkit.Artifact{Body: []byte("ok")},
|
Artifact: promptkit.Artifact{Body: []byte("ok")},
|
||||||
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationNone, IsValid: true},
|
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationNone, IsValid: true},
|
||||||
@@ -569,8 +590,8 @@ func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) {
|
|||||||
h := NewHandler(r)
|
h := NewHandler(r)
|
||||||
|
|
||||||
for _, body := range []string{
|
for _, body := range []string{
|
||||||
`{"prompt_id":"prompt-1","prompt_version":"2"}`,
|
`{"prompt_id":"support/prompt-1","profile_id":"support/profile-1"}`,
|
||||||
`{"prompt_id":"prompt-1","prompt_version":"2","inputs":{}}`,
|
`{"prompt_id":"support/prompt-1","profile_id":"support/profile-1","inputs":{}}`,
|
||||||
} {
|
} {
|
||||||
req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(body))
|
req := httptest.NewRequest(http.MethodPost, "/v1/runs", bytes.NewBufferString(body))
|
||||||
w := httptest.NewRecorder()
|
w := httptest.NewRecorder()
|
||||||
@@ -579,8 +600,8 @@ func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) {
|
|||||||
if w.Code != http.StatusOK {
|
if w.Code != http.StatusOK {
|
||||||
t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
|
t.Fatalf("expected 200, got %d body=%s", w.Code, w.Body.String())
|
||||||
}
|
}
|
||||||
if r.last.PromptVersion != "2" {
|
if r.last.PromptID != "support/prompt-1" || r.last.ProfileID != "support/profile-1" {
|
||||||
t.Fatalf("expected prompt version to be mapped, got %q", r.last.PromptVersion)
|
t.Fatalf("qualified IDs changed: %+v", r.last)
|
||||||
}
|
}
|
||||||
if r.last.Inputs != nil {
|
if r.last.Inputs != nil {
|
||||||
t.Fatalf("expected omitted or empty inputs to remain nil, got %#v", r.last.Inputs)
|
t.Fatalf("expected omitted or empty inputs to remain nil, got %#v", r.last.Inputs)
|
||||||
@@ -588,6 +609,16 @@ func TestHandlerAllowsOmittedInputsAndMapsPromptVersion(t *testing.T) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func TestHandlerRejectsRemovedPromptVersion(t *testing.T) {
|
||||||
|
runner := &fakeRunner{result: &promptkit.RunResult{}}
|
||||||
|
w := httptest.NewRecorder()
|
||||||
|
NewHandler(runner).ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","prompt_version":"1"}`)))
|
||||||
|
assertHTTPErrorCode(t, w, http.StatusBadRequest, "invalid_json")
|
||||||
|
if runner.last.PromptID != "" {
|
||||||
|
t.Fatal("runner invoked for removed selector")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
func TestHandlerDelegatesDefinitionInputRequirements(t *testing.T) {
|
func TestHandlerDelegatesDefinitionInputRequirements(t *testing.T) {
|
||||||
tests := []struct {
|
tests := []struct {
|
||||||
name string
|
name string
|
||||||
@@ -597,8 +628,8 @@ func TestHandlerDelegatesDefinitionInputRequirements(t *testing.T) {
|
|||||||
}{
|
}{
|
||||||
{
|
{
|
||||||
name: "no declared inputs",
|
name: "no declared inputs",
|
||||||
definition: `id: p
|
definition: `prompts:
|
||||||
version: "1"
|
- id: p
|
||||||
default_profile: exec
|
default_profile: exec
|
||||||
messages:
|
messages:
|
||||||
- role: user
|
- role: user
|
||||||
@@ -611,8 +642,8 @@ output:
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
name: "optional input omitted",
|
name: "optional input omitted",
|
||||||
definition: `id: p
|
definition: `prompts:
|
||||||
version: "1"
|
- id: p
|
||||||
default_profile: exec
|
default_profile: exec
|
||||||
inputs:
|
inputs:
|
||||||
- name: note
|
- name: note
|
||||||
@@ -628,8 +659,8 @@ output:
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
name: "required input omitted",
|
name: "required input omitted",
|
||||||
definition: `id: p
|
definition: `prompts:
|
||||||
version: "1"
|
- id: p
|
||||||
default_profile: exec
|
default_profile: exec
|
||||||
inputs:
|
inputs:
|
||||||
- name: note
|
- name: note
|
||||||
@@ -646,8 +677,8 @@ output:
|
|||||||
},
|
},
|
||||||
{
|
{
|
||||||
name: "template input omitted",
|
name: "template input omitted",
|
||||||
definition: `id: p
|
definition: `prompts:
|
||||||
version: "1"
|
- id: p
|
||||||
default_profile: exec
|
default_profile: exec
|
||||||
messages:
|
messages:
|
||||||
- role: user
|
- role: user
|
||||||
@@ -781,7 +812,6 @@ func TestHandlerPostRunsSuccessUsingPromptDefaultProfile(t *testing.T) {
|
|||||||
r := &fakeRunner{result: &promptkit.RunResult{
|
r := &fakeRunner{result: &promptkit.RunResult{
|
||||||
Artifact: promptkit.Artifact{Body: []byte("ok")},
|
Artifact: promptkit.Artifact{Body: []byte("ok")},
|
||||||
PromptID: "prompt-1",
|
PromptID: "prompt-1",
|
||||||
PromptVersion: "1.0.0",
|
|
||||||
SelectedProfileID: "prompt-default",
|
SelectedProfileID: "prompt-default",
|
||||||
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true},
|
Validation: promptkit.ValidationResult{Status: promptkit.ValidationPassed, Mode: promptkit.ValidationBasic, IsValid: true},
|
||||||
EffectiveModelParams: promptkit.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
|
EffectiveModelParams: promptkit.ExecutionTarget{Endpoint: "http://llm/v1", Model: "m1"},
|
||||||
@@ -988,7 +1018,7 @@ func TestHandlerSessionIDUsesPromptkitResolution(t *testing.T) {
|
|||||||
if tc.definitionSession != "" {
|
if tc.definitionSession != "" {
|
||||||
sessionLine = " session_id: " + tc.definitionSession + "\n"
|
sessionLine = " session_id: " + tc.definitionSession + "\n"
|
||||||
}
|
}
|
||||||
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte("id: p\nversion: \"1\"\ndefault_profile: exec\n"+sessionLine+`messages:
|
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte("prompts:\n - id: p\n default_profile: exec\n"+sessionLine+` messages:
|
||||||
- role: user
|
- role: user
|
||||||
content: "hi"
|
content: "hi"
|
||||||
output:
|
output:
|
||||||
@@ -997,13 +1027,10 @@ output:
|
|||||||
`), 0o644); err != nil {
|
`), 0o644); err != nil {
|
||||||
t.Fatalf("write prompt fixture: %v", err)
|
t.Fatalf("write prompt fixture: %v", err)
|
||||||
}
|
}
|
||||||
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("id: exec\nendpoint: http://127.0.0.1:1/v1\nmodel: test\n"), 0o644); err != nil {
|
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("profiles:\n - id: exec\n endpoint: http://127.0.0.1:1/v1\n model: test\n"), 0o644); err != nil {
|
||||||
t.Fatalf("write profile fixture: %v", err)
|
t.Fatalf("write profile fixture: %v", err)
|
||||||
}
|
}
|
||||||
engine, err := promptkit.NewEngine(promptkit.Config{PromptDir: promptDir, ProfileDir: profileDir}, promptkit.WithLLMClient(handlerLLMClient{}))
|
engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, nil, promptkit.WithLLMClient(handlerLLMClient{}))
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("new engine: %v", err)
|
|
||||||
}
|
|
||||||
|
|
||||||
body := `{"prompt_id":"p"}`
|
body := `{"prompt_id":"p"}`
|
||||||
if tc.requestSession != "" {
|
if tc.requestSession != "" {
|
||||||
@@ -1035,8 +1062,8 @@ output:
|
|||||||
func TestHandlerSharesBackendCapacityAcrossConcurrentRequests(t *testing.T) {
|
func TestHandlerSharesBackendCapacityAcrossConcurrentRequests(t *testing.T) {
|
||||||
promptDir := t.TempDir()
|
promptDir := t.TempDir()
|
||||||
profileDir := t.TempDir()
|
profileDir := t.TempDir()
|
||||||
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`id: p
|
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`prompts:
|
||||||
version: "1"
|
- id: p
|
||||||
default_profile: limited
|
default_profile: limited
|
||||||
messages:
|
messages:
|
||||||
- role: user
|
- role: user
|
||||||
@@ -1047,7 +1074,8 @@ output:
|
|||||||
`), 0o644); err != nil {
|
`), 0o644); err != nil {
|
||||||
t.Fatalf("write prompt fixture: %v", err)
|
t.Fatalf("write prompt fixture: %v", err)
|
||||||
}
|
}
|
||||||
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`id: limited
|
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`profiles:
|
||||||
|
- id: limited
|
||||||
backend: limited
|
backend: limited
|
||||||
model: test
|
model: test
|
||||||
`), 0o644); err != nil {
|
`), 0o644); err != nil {
|
||||||
@@ -1055,19 +1083,8 @@ model: test
|
|||||||
}
|
}
|
||||||
queueCapacity := 0
|
queueCapacity := 0
|
||||||
client := &blockingLLMClient{started: make(chan struct{}, 1), release: make(chan struct{})}
|
client := &blockingLLMClient{started: make(chan struct{}, 1), release: make(chan struct{})}
|
||||||
engine, err := promptkit.NewEngine(
|
backend := promptkit.BackendConfig{ID: "limited", Endpoint: stringPointer("http://127.0.0.1:1/v1"), ConcurrencyLimit: intPointer(1), QueueCapacity: &queueCapacity}
|
||||||
promptkit.Config{PromptDir: promptDir, ProfileDir: profileDir},
|
engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, &backend, promptkit.WithLLMClient(client))
|
||||||
promptkit.WithBackend(promptkit.Backend{
|
|
||||||
ID: "limited",
|
|
||||||
Endpoint: "http://127.0.0.1:1/v1",
|
|
||||||
ConcurrencyLimit: 1,
|
|
||||||
QueueCapacity: &queueCapacity,
|
|
||||||
}),
|
|
||||||
promptkit.WithLLMClient(client),
|
|
||||||
)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("new engine: %v", err)
|
|
||||||
}
|
|
||||||
h := NewHandler(engine)
|
h := NewHandler(engine)
|
||||||
first := httptest.NewRecorder()
|
first := httptest.NewRecorder()
|
||||||
firstDone := make(chan struct{})
|
firstDone := make(chan struct{})
|
||||||
@@ -1198,14 +1215,49 @@ func TestHandlerDeadlineCancelsBuiltInRetryWait(t *testing.T) {
|
|||||||
}))
|
}))
|
||||||
defer provider.Close()
|
defer provider.Close()
|
||||||
h := newRetryHandler(t, provider.URL+"/v1", intPointer(1), 0, nil)
|
h := newRetryHandler(t, provider.URL+"/v1", intPointer(1), 0, nil)
|
||||||
w := httptest.NewRecorder()
|
w, err := serveObservedTimeoutRequest(h, `{"prompt_id":"p","run_timeout_seconds":1}`)
|
||||||
h.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":1}`)))
|
|
||||||
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
|
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
|
||||||
|
if !errors.Is(err, promptkit.ErrOperationTimeout) {
|
||||||
|
t.Fatalf("engine did not attribute retry wait to operation timeout: %v", err)
|
||||||
|
}
|
||||||
if atomic.LoadInt32(&hits) != 1 {
|
if atomic.LoadInt32(&hits) != 1 {
|
||||||
t.Fatalf("expected one provider call before canceled retry wait, got %d", atomic.LoadInt32(&hits))
|
t.Fatalf("expected one provider call before canceled retry wait, got %d", atomic.LoadInt32(&hits))
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func TestHandlerDeadlineDuringBuiltInGeneration(t *testing.T) {
|
||||||
|
started := make(chan struct{}, 1)
|
||||||
|
release := make(chan struct{})
|
||||||
|
provider := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||||
|
started <- struct{}{}
|
||||||
|
<-release
|
||||||
|
}))
|
||||||
|
defer provider.Close()
|
||||||
|
defer close(release)
|
||||||
|
h := newRetryHandler(t, provider.URL+"/v1", intPointer(0), 0, nil)
|
||||||
|
w, err := serveObservedTimeoutRequest(h, `{"prompt_id":"p","run_timeout_seconds":1,"include_execution_report":true}`)
|
||||||
|
select {
|
||||||
|
case <-started:
|
||||||
|
default:
|
||||||
|
t.Fatal("provider call did not start")
|
||||||
|
}
|
||||||
|
if !errors.Is(err, promptkit.ErrOperationTimeout) || !errors.Is(err, context.DeadlineExceeded) {
|
||||||
|
t.Errorf("engine did not attribute in-flight generation to operation timeout: %v (deadline cause: %t)", err, errors.Is(err, context.DeadlineExceeded))
|
||||||
|
}
|
||||||
|
var response struct {
|
||||||
|
Execution *struct {
|
||||||
|
Failure string `json:"failure"`
|
||||||
|
} `json:"execution"`
|
||||||
|
}
|
||||||
|
if err := json.Unmarshal(w.Body.Bytes(), &response); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if response.Execution == nil || response.Execution.Failure != "deadline" {
|
||||||
|
t.Errorf("terminal report did not classify deadline: %+v", response.Execution)
|
||||||
|
}
|
||||||
|
assertHTTPErrorCode(t, w, http.StatusGatewayTimeout, "deadline_exceeded")
|
||||||
|
}
|
||||||
|
|
||||||
func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) {
|
func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) {
|
||||||
started := make(chan struct{}, 1)
|
started := make(chan struct{}, 1)
|
||||||
release := make(chan struct{})
|
release := make(chan struct{})
|
||||||
@@ -1228,20 +1280,24 @@ func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) {
|
|||||||
}()
|
}()
|
||||||
queue := 1
|
queue := 1
|
||||||
h := newRetryHandler(t, provider.URL+"/v1", intPointer(0), 1, &queue)
|
h := newRetryHandler(t, provider.URL+"/v1", intPointer(0), 1, &queue)
|
||||||
|
firstCtx, cancelFirst := context.WithTimeout(context.Background(), 10*time.Second)
|
||||||
|
defer cancelFirst()
|
||||||
first := httptest.NewRecorder()
|
first := httptest.NewRecorder()
|
||||||
done := make(chan struct{})
|
done := make(chan struct{})
|
||||||
go func() {
|
go func() {
|
||||||
defer close(done)
|
defer close(done)
|
||||||
h.ServeHTTP(first, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)))
|
h.ServeHTTP(first, httptest.NewRequestWithContext(firstCtx, http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)))
|
||||||
}()
|
}()
|
||||||
select {
|
select {
|
||||||
case <-started:
|
case <-started:
|
||||||
case <-time.After(3 * time.Second):
|
case <-time.After(3 * time.Second):
|
||||||
t.Fatal("first provider call did not start")
|
t.Fatal("first provider call did not start")
|
||||||
}
|
}
|
||||||
waiting := httptest.NewRecorder()
|
waiting, err := serveObservedTimeoutRequest(h, `{"prompt_id":"p","run_timeout_seconds":1}`)
|
||||||
h.ServeHTTP(waiting, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p","run_timeout_seconds":1}`)))
|
|
||||||
assertHTTPErrorCode(t, waiting, http.StatusGatewayTimeout, "deadline_exceeded")
|
assertHTTPErrorCode(t, waiting, http.StatusGatewayTimeout, "deadline_exceeded")
|
||||||
|
if !errors.Is(err, promptkit.ErrOperationTimeout) {
|
||||||
|
t.Fatalf("engine did not attribute capacity wait to operation timeout: %v", err)
|
||||||
|
}
|
||||||
if atomic.LoadInt32(&hits) != 1 {
|
if atomic.LoadInt32(&hits) != 1 {
|
||||||
t.Fatalf("capacity waiter reached provider: hits=%d", atomic.LoadInt32(&hits))
|
t.Fatalf("capacity waiter reached provider: hits=%d", atomic.LoadInt32(&hits))
|
||||||
}
|
}
|
||||||
@@ -1254,27 +1310,48 @@ func TestHandlerDeadlineCancelsCapacityWaitAndReleasesAdmission(t *testing.T) {
|
|||||||
if first.Code != http.StatusOK {
|
if first.Code != http.StatusOK {
|
||||||
t.Fatalf("first request: status=%d body=%s", first.Code, first.Body.String())
|
t.Fatalf("first request: status=%d body=%s", first.Code, first.Body.String())
|
||||||
}
|
}
|
||||||
third := httptest.NewRecorder()
|
third, _ := serveObservedTimeoutRequest(h, `{"prompt_id":"p"}`)
|
||||||
h.ServeHTTP(third, httptest.NewRequest(http.MethodPost, "/v1/runs", strings.NewReader(`{"prompt_id":"p"}`)))
|
|
||||||
if third.Code != http.StatusOK || atomic.LoadInt32(&hits) != 2 {
|
if third.Code != http.StatusOK || atomic.LoadInt32(&hits) != 2 {
|
||||||
t.Fatalf("admission was not released: status=%d hits=%d body=%s", third.Code, atomic.LoadInt32(&hits), third.Body.String())
|
t.Fatalf("admission was not released: status=%d hits=%d body=%s", third.Code, atomic.LoadInt32(&hits), third.Body.String())
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func serveObservedTimeoutRequest(h *Handler, body string) (*httptest.ResponseRecorder, error) {
|
||||||
|
// Bound the test independently of the shorter operation budget under test.
|
||||||
|
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
|
||||||
|
defer cancel()
|
||||||
|
var runErr error
|
||||||
|
observed := NewHandlerWithOptions(runnerFunc(func(ctx context.Context, request promptkit.RunRequest) (*promptkit.RunResult, error) {
|
||||||
|
result, err := h.runner.Run(ctx, request)
|
||||||
|
runErr = err
|
||||||
|
return result, err
|
||||||
|
}), h.options)
|
||||||
|
w := httptest.NewRecorder()
|
||||||
|
observed.ServeHTTP(w, httptest.NewRequestWithContext(ctx, http.MethodPost, "/v1/runs", strings.NewReader(body)))
|
||||||
|
return w, runErr
|
||||||
|
}
|
||||||
|
|
||||||
func newRetryHandler(t *testing.T, endpoint string, retries *int, concurrency int, queue *int) *Handler {
|
func newRetryHandler(t *testing.T, endpoint string, retries *int, concurrency int, queue *int) *Handler {
|
||||||
t.Helper()
|
t.Helper()
|
||||||
promptDir := t.TempDir()
|
promptDir := t.TempDir()
|
||||||
profileDir := t.TempDir()
|
profileDir := t.TempDir()
|
||||||
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte("id: p\nversion: \"1\"\ndefault_profile: limited\nmessages:\n - role: user\n content: hi\noutput:\n format: text\n validation_mode: none\n"), 0o644); err != nil {
|
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`prompts:
|
||||||
|
- id: p
|
||||||
|
default_profile: limited
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: hi
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
`), 0o644); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("id: limited\nbackend: limited\nmodel: test\n"), 0o644); err != nil {
|
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte("profiles:\n - id: limited\n backend: limited\n model: test\n"), 0o644); err != nil {
|
||||||
t.Fatal(err)
|
|
||||||
}
|
|
||||||
engine, err := promptkit.NewEngine(promptkit.Config{PromptDir: promptDir, ProfileDir: profileDir, TransientRetries: retries}, promptkit.WithBackend(promptkit.Backend{ID: "limited", Endpoint: endpoint, ConcurrencyLimit: concurrency, QueueCapacity: queue}))
|
|
||||||
if err != nil {
|
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
|
backend := promptkit.BackendConfig{ID: "limited", Endpoint: &endpoint, ConcurrencyLimit: &concurrency, QueueCapacity: queue}
|
||||||
|
engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, retries, &backend)
|
||||||
return NewHandler(engine)
|
return NewHandler(engine)
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -1626,6 +1703,7 @@ func TestHandlerPublicErrorMapping(t *testing.T) {
|
|||||||
{name: "file denied", err: ErrFileNotAllowed, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
|
{name: "file denied", err: ErrFileNotAllowed, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
|
||||||
{name: "file outside root", err: ErrFileOutsideRoot, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
|
{name: "file outside root", err: ErrFileOutsideRoot, status: http.StatusBadRequest, code: "artifact_not_allowed", message: "file input artifact is not allowed"},
|
||||||
{name: "file too large", err: ErrFileTooLarge, status: http.StatusRequestEntityTooLarge, code: "artifact_too_large", message: "file input artifact is too large"},
|
{name: "file too large", err: ErrFileTooLarge, status: http.StatusRequestEntityTooLarge, code: "artifact_too_large", message: "file input artifact is too large"},
|
||||||
|
{name: "file too large with broad category", err: errors.Join(ErrFileTooLarge, promptkit.ErrInvalidRequest, promptkit.ErrArtifactLoad), status: http.StatusRequestEntityTooLarge, code: "artifact_too_large", message: "file input artifact is too large"},
|
||||||
{name: "artifact", err: wrap(promptkit.ErrArtifactLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "artifact_read_failed", message: "failed to read input artifact", avoidCause: "read failed"},
|
{name: "artifact", err: wrap(promptkit.ErrArtifactLoad, fmt.Errorf("read failed")), status: http.StatusBadRequest, code: "artifact_read_failed", message: "failed to read input artifact", avoidCause: "read failed"},
|
||||||
{name: "prompt render", err: wrap(promptkit.ErrPromptRender, fmt.Errorf("render failed")), status: http.StatusBadRequest, code: "prompt_render_failed", message: "failed to render prompt", avoidCause: "render failed"},
|
{name: "prompt render", err: wrap(promptkit.ErrPromptRender, fmt.Errorf("render failed")), status: http.StatusBadRequest, code: "prompt_render_failed", message: "failed to render prompt", avoidCause: "render failed"},
|
||||||
{name: "capacity", err: &promptkit.CapacityError{BackendID: "private-backend"}, status: http.StatusServiceUnavailable, code: "capacity_exceeded", message: "model backend capacity is exhausted", avoidCause: "private-backend"},
|
{name: "capacity", err: &promptkit.CapacityError{BackendID: "private-backend"}, status: http.StatusServiceUnavailable, code: "capacity_exceeded", message: "model backend capacity is exhausted", avoidCause: "private-backend"},
|
||||||
@@ -1770,8 +1848,8 @@ func newHandlerEngineWithOptions(t *testing.T, options ...promptkit.Option) *pro
|
|||||||
|
|
||||||
promptDir := t.TempDir()
|
promptDir := t.TempDir()
|
||||||
profileDir := t.TempDir()
|
profileDir := t.TempDir()
|
||||||
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`id: p
|
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(`prompts:
|
||||||
version: "1"
|
- id: p
|
||||||
default_profile: exec
|
default_profile: exec
|
||||||
messages:
|
messages:
|
||||||
- role: user
|
- role: user
|
||||||
@@ -1783,21 +1861,15 @@ output:
|
|||||||
`), 0o644); err != nil {
|
`), 0o644); err != nil {
|
||||||
t.Fatalf("write prompt fixture: %v", err)
|
t.Fatalf("write prompt fixture: %v", err)
|
||||||
}
|
}
|
||||||
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`id: exec
|
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`profiles:
|
||||||
|
- id: exec
|
||||||
endpoint: http://example.invalid/v1
|
endpoint: http://example.invalid/v1
|
||||||
model: model
|
model: model
|
||||||
`), 0o644); err != nil {
|
`), 0o644); err != nil {
|
||||||
t.Fatalf("write profile fixture: %v", err)
|
t.Fatalf("write profile fixture: %v", err)
|
||||||
}
|
}
|
||||||
|
|
||||||
engine, err := promptkit.NewEngine(promptkit.Config{
|
return newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, nil, options...)
|
||||||
PromptDir: promptDir,
|
|
||||||
ProfileDir: profileDir,
|
|
||||||
}, options...)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatalf("construct public engine: %v", err)
|
|
||||||
}
|
|
||||||
return engine
|
|
||||||
}
|
}
|
||||||
|
|
||||||
func newDefinitionHandler(t *testing.T, definition string) *Handler {
|
func newDefinitionHandler(t *testing.T, definition string) *Handler {
|
||||||
@@ -1808,21 +1880,46 @@ func newDefinitionHandler(t *testing.T, definition string) *Handler {
|
|||||||
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(definition), 0o644); err != nil {
|
if err := os.WriteFile(filepath.Join(promptDir, "prompt.yaml"), []byte(definition), 0o644); err != nil {
|
||||||
t.Fatalf("write prompt fixture: %v", err)
|
t.Fatalf("write prompt fixture: %v", err)
|
||||||
}
|
}
|
||||||
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`id: exec
|
if err := os.WriteFile(filepath.Join(profileDir, "profile.yaml"), []byte(`profiles:
|
||||||
|
- id: exec
|
||||||
endpoint: http://example.invalid/v1
|
endpoint: http://example.invalid/v1
|
||||||
model: model
|
model: model
|
||||||
`), 0o644); err != nil {
|
`), 0o644); err != nil {
|
||||||
t.Fatalf("write profile fixture: %v", err)
|
t.Fatalf("write profile fixture: %v", err)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
engine := newHandlerEngineFromDirectories(t, promptDir, profileDir, nil, nil, promptkit.WithLLMClient(handlerLLMClient{}))
|
||||||
|
return NewHandler(engine)
|
||||||
|
}
|
||||||
|
|
||||||
|
func newHandlerEngineFromDirectories(t *testing.T, promptDir, profileDir string, retries *int, backend *promptkit.BackendConfig, options ...promptkit.Option) *promptkit.Engine {
|
||||||
|
t.Helper()
|
||||||
|
|
||||||
|
promptInputs, err := promptkit.DirectoryInputs(promptDir)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("load prompt inputs: %v", err)
|
||||||
|
}
|
||||||
|
profileInputs, err := promptkit.DirectoryInputs(profileDir)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("load profile inputs: %v", err)
|
||||||
|
}
|
||||||
|
underlays := []configkit.Underlay{{Inputs: promptInputs}, {Inputs: profileInputs}}
|
||||||
|
if backend != nil {
|
||||||
|
underlays = append(underlays, configkit.Underlay{Inputs: []configkit.Input{{Source: promptkit.BackendSource("test backend", []promptkit.BackendConfig{*backend})}}})
|
||||||
|
}
|
||||||
|
|
||||||
engine, err := promptkit.NewEngine(promptkit.Config{
|
engine, err := promptkit.NewEngine(promptkit.Config{
|
||||||
PromptDir: promptDir,
|
Sources: promptkit.ConfigurationSources{Underlays: underlays},
|
||||||
ProfileDir: profileDir,
|
TransientRetries: retries,
|
||||||
}, promptkit.WithLLMClient(handlerLLMClient{}))
|
}, options...)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatalf("construct public engine: %v", err)
|
t.Fatalf("construct public engine: %v", err)
|
||||||
}
|
}
|
||||||
return NewHandler(engine)
|
return engine
|
||||||
|
}
|
||||||
|
|
||||||
|
func stringPointer(value string) *string {
|
||||||
|
return &value
|
||||||
}
|
}
|
||||||
|
|
||||||
func assertHTTPErrorCode(t *testing.T, w *httptest.ResponseRecorder, status int, code string) {
|
func assertHTTPErrorCode(t *testing.T, w *httptest.ResponseRecorder, status int, code string) {
|
||||||
|
|||||||
@@ -4,28 +4,24 @@ import (
|
|||||||
"path/filepath"
|
"path/filepath"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
|
||||||
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
"gitea.maximumdirect.net/eric/scriptorium/internal/defaults"
|
||||||
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
// Document is Scriptorium's ConfigKit-native application configuration shape.
|
// Document is Scriptorium's ConfigKit-native application configuration shape.
|
||||||
type Document struct {
|
type Document struct {
|
||||||
PromptDir string `yaml:"prompt_dir"`
|
PromptKitSources []SourceSelection `yaml:"promptkit_sources"`
|
||||||
ProfileDir string `yaml:"profile_dir"`
|
|
||||||
SchemaDir string `yaml:"schema_dir"`
|
SchemaDir string `yaml:"schema_dir"`
|
||||||
TransientRetries *int `yaml:"transient_retries"`
|
TransientRetries *int `yaml:"transient_retries"`
|
||||||
Server ServerDocument `yaml:"server"`
|
Server ServerDocument `yaml:"server"`
|
||||||
Defaults DefaultsDocument `yaml:"defaults"`
|
Defaults DefaultsDocument `yaml:"defaults"`
|
||||||
Backends map[string]BackendDocument `yaml:"backends"`
|
|
||||||
}
|
}
|
||||||
|
|
||||||
type BackendDocument struct {
|
// SourceSelection identifies one PromptKit configuration file or directory.
|
||||||
Endpoint string `yaml:"endpoint"`
|
type SourceSelection struct {
|
||||||
APIKeyEnv string `yaml:"api_key_env"`
|
File string `yaml:"file"`
|
||||||
ExtraParams map[string]any `yaml:"extra_params"`
|
Directory string `yaml:"directory"`
|
||||||
ConcurrencyLimit int `yaml:"concurrency_limit"`
|
|
||||||
QueueCapacity *int `yaml:"queue_capacity"`
|
|
||||||
}
|
}
|
||||||
|
|
||||||
type ServerDocument struct {
|
type ServerDocument struct {
|
||||||
@@ -77,8 +73,11 @@ func resolveDocument(document *Document, resolution *configkit.Resolution) error
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
normalizePath(configkit.Keys("prompt_dir"), &document.PromptDir)
|
for i := range document.PromptKitSources {
|
||||||
normalizePath(configkit.Keys("profile_dir"), &document.ProfileDir)
|
path := configkit.Keys("promptkit_sources").Index(i)
|
||||||
|
normalizePath(path.Key("file"), &document.PromptKitSources[i].File)
|
||||||
|
normalizePath(path.Key("directory"), &document.PromptKitSources[i].Directory)
|
||||||
|
}
|
||||||
normalizePath(configkit.Keys("schema_dir"), &document.SchemaDir)
|
normalizePath(configkit.Keys("schema_dir"), &document.SchemaDir)
|
||||||
normalizePath(configkit.Keys("server", "artifact_root"), &document.Server.ArtifactRoot)
|
normalizePath(configkit.Keys("server", "artifact_root"), &document.Server.ArtifactRoot)
|
||||||
normalizeString(configkit.Keys("server", "addr"), &document.Server.Addr,
|
normalizeString(configkit.Keys("server", "addr"), &document.Server.Addr,
|
||||||
@@ -89,6 +88,13 @@ func resolveDocument(document *Document, resolution *configkit.Resolution) error
|
|||||||
}
|
}
|
||||||
|
|
||||||
func validateDocument(document *Document, validation *configkit.Validation) {
|
func validateDocument(document *Document, validation *configkit.Validation) {
|
||||||
|
for i, source := range document.PromptKitSources {
|
||||||
|
hasFile := source.File != ""
|
||||||
|
hasDirectory := source.Directory != ""
|
||||||
|
if hasFile == hasDirectory {
|
||||||
|
validation.Error(configkit.Keys("promptkit_sources").Index(i), "exactly one of file or directory must be non-empty")
|
||||||
|
}
|
||||||
|
}
|
||||||
if document.TransientRetries != nil && *document.TransientRetries < 0 {
|
if document.TransientRetries != nil && *document.TransientRetries < 0 {
|
||||||
validation.Error(configkit.Keys("transient_retries"), "must be greater than or equal to zero")
|
validation.Error(configkit.Keys("transient_retries"), "must be greater than or equal to zero")
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -7,7 +7,7 @@ import (
|
|||||||
"strings"
|
"strings"
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
"go.maximumdirect.net/configkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
func loadDocumentBytes(content string) (*configkit.Result[Document], error) {
|
func loadDocumentBytes(content string) (*configkit.Result[Document], error) {
|
||||||
@@ -25,8 +25,9 @@ func TestDocumentDefaultsAndExplicitValues(t *testing.T) {
|
|||||||
t.Fatalf("unexpected defaults-only result: %+v sources=%+v", defaultsOnly.Config, defaultsOnly.Sources())
|
t.Fatalf("unexpected defaults-only result: %+v sources=%+v", defaultsOnly.Config, defaultsOnly.Sources())
|
||||||
}
|
}
|
||||||
|
|
||||||
result, err := loadDocumentBytes(`prompt_dir: ""
|
result, err := loadDocumentBytes(`promptkit_sources:
|
||||||
profile_dir: ""
|
- file: " ./bundle/../framework.yml "
|
||||||
|
- directory: "./profiles"
|
||||||
schema_dir: ""
|
schema_dir: ""
|
||||||
transient_retries: 0
|
transient_retries: 0
|
||||||
server:
|
server:
|
||||||
@@ -37,12 +38,6 @@ server:
|
|||||||
max_response_bytes: 0
|
max_response_bytes: 0
|
||||||
defaults:
|
defaults:
|
||||||
render_format: " JSON "
|
render_format: " JSON "
|
||||||
backends:
|
|
||||||
local:
|
|
||||||
endpoint: "http://fixture.invalid/v1"
|
|
||||||
queue_capacity: 0
|
|
||||||
extra_params:
|
|
||||||
sample_count: 23
|
|
||||||
`)
|
`)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatalf("explicit-value load: %v", err)
|
t.Fatalf("explicit-value load: %v", err)
|
||||||
@@ -54,30 +49,70 @@ backends:
|
|||||||
if config.TransientRetries == nil || *config.TransientRetries != 0 {
|
if config.TransientRetries == nil || *config.TransientRetries != 0 {
|
||||||
t.Fatalf("explicit zero retry budget lost: %+v", config.TransientRetries)
|
t.Fatalf("explicit zero retry budget lost: %+v", config.TransientRetries)
|
||||||
}
|
}
|
||||||
if backend := config.Backends["local"]; backend.QueueCapacity == nil || *backend.QueueCapacity != 0 || backend.ExtraParams["sample_count"] != int64(23) {
|
if want := []SourceSelection{{File: "framework.yml"}, {Directory: "profiles"}}; !reflect.DeepEqual(config.PromptKitSources, want) {
|
||||||
t.Fatalf("backend presence or dynamic integer changed: %+v", backend)
|
t.Fatalf("source selectors did not decode: %+v", config.PromptKitSources)
|
||||||
}
|
}
|
||||||
if config.Defaults.RenderFormat != "json" {
|
if config.Defaults.RenderFormat != "json" {
|
||||||
t.Fatalf("render format normalization failed: %q", config.Defaults.RenderFormat)
|
t.Fatalf("render format normalization failed: %q", config.Defaults.RenderFormat)
|
||||||
}
|
}
|
||||||
|
|
||||||
nullable, err := loadDocumentBytes("transient_retries: null\nbackends:\n local:\n queue_capacity: null\n")
|
nullable, err := loadDocumentBytes("transient_retries: null\npromptkit_sources: null\n")
|
||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatalf("nullable-value load: %v", err)
|
t.Fatalf("nullable-value load: %v", err)
|
||||||
}
|
}
|
||||||
if nullable.Config.TransientRetries != nil || nullable.Config.Backends["local"].QueueCapacity != nil {
|
if nullable.Config.TransientRetries != nil || nullable.Config.PromptKitSources != nil {
|
||||||
t.Fatalf("nullable fields did not remain nil: %+v", nullable.Config)
|
t.Fatalf("nullable fields did not remain nil: %+v", nullable.Config)
|
||||||
}
|
}
|
||||||
|
}
|
||||||
|
|
||||||
nullBackends, err := loadDocumentBytes("backends: null\n")
|
func TestDocumentSourceSelectionsDoNotAcquirePaths(t *testing.T) {
|
||||||
if err != nil || nullBackends.Config.Backends != nil {
|
for _, tc := range []struct {
|
||||||
t.Fatalf("nullable backend map did not remain nil: %+v error=%v", nullBackends, err)
|
name string
|
||||||
|
content string
|
||||||
|
want []SourceSelection
|
||||||
|
}{
|
||||||
|
{name: "omitted", content: "{}\n"},
|
||||||
|
{name: "null", content: "promptkit_sources: null\n"},
|
||||||
|
{name: "empty", content: "promptkit_sources: []\n"},
|
||||||
|
{name: "nonexistent file", content: "promptkit_sources:\n - file: ./missing/framework.yml\n", want: []SourceSelection{{File: "missing/framework.yml"}}},
|
||||||
|
{name: "nonexistent directory", content: "promptkit_sources:\n - directory: ./missing/framework\n", want: []SourceSelection{{Directory: "missing/framework"}}},
|
||||||
|
} {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
result, err := loadDocumentBytes(tc.content)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("load source selectors: %v", err)
|
||||||
|
}
|
||||||
|
if len(result.Config.PromptKitSources) != len(tc.want) || len(tc.want) > 0 && !reflect.DeepEqual(result.Config.PromptKitSources, tc.want) {
|
||||||
|
t.Fatalf("source selectors changed: got=%+v want=%+v", result.Config.PromptKitSources, tc.want)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestSettingsCopiesPromptKitSourcesInOrder(t *testing.T) {
|
||||||
|
document := Document{PromptKitSources: []SourceSelection{
|
||||||
|
{File: "./first.yml"},
|
||||||
|
{Directory: "./second"},
|
||||||
|
}}
|
||||||
|
settings := Settings(document)
|
||||||
|
if !reflect.DeepEqual(settings.PromptKitSources, document.PromptKitSources) {
|
||||||
|
t.Fatalf("source ordering changed: got=%+v want=%+v", settings.PromptKitSources, document.PromptKitSources)
|
||||||
|
}
|
||||||
|
document.PromptKitSources[0].File = "changed.yml"
|
||||||
|
if settings.PromptKitSources[0].File != "./first.yml" {
|
||||||
|
t.Fatalf("settings retained the document's source slice: %+v", settings.PromptKitSources)
|
||||||
|
}
|
||||||
|
if empty := Settings(Document{PromptKitSources: []SourceSelection{}}).PromptKitSources; empty == nil {
|
||||||
|
t.Fatal("explicit empty source list was not copied")
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestDocumentRecordsEffectiveNormalization(t *testing.T) {
|
func TestDocumentRecordsEffectiveNormalization(t *testing.T) {
|
||||||
result, err := loadDocumentBytes(`prompt_dir: " ./one/../two "
|
result, err := loadDocumentBytes(`promptkit_sources:
|
||||||
profile_dir: " "
|
- file: " ./one/../two "
|
||||||
|
- file: "./blank.yml"
|
||||||
|
directory: " "
|
||||||
|
- directory: "./three/../three"
|
||||||
server:
|
server:
|
||||||
artifact_root: " ./data/../artifacts "
|
artifact_root: " ./data/../artifacts "
|
||||||
addr: " :9000 "
|
addr: " :9000 "
|
||||||
@@ -87,19 +122,22 @@ defaults:
|
|||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatalf("load normalized document: %v", err)
|
t.Fatalf("load normalized document: %v", err)
|
||||||
}
|
}
|
||||||
if result.Config.PromptDir != "two" || result.Config.ProfileDir != "" || result.Config.Server.ArtifactRoot != "artifacts" || result.Config.Server.Addr != ":9000" {
|
if want := []SourceSelection{{File: "two"}, {File: "blank.yml"}, {Directory: "three"}}; !reflect.DeepEqual(result.Config.PromptKitSources, want) {
|
||||||
|
t.Fatalf("unexpected normalized source selections: %+v", result.Config.PromptKitSources)
|
||||||
|
}
|
||||||
|
if result.Config.Server.ArtifactRoot != "artifacts" || result.Config.Server.Addr != ":9000" {
|
||||||
t.Fatalf("unexpected normalized values: %+v", result.Config)
|
t.Fatalf("unexpected normalized values: %+v", result.Config)
|
||||||
}
|
}
|
||||||
var effective bytes.Buffer
|
var effective bytes.Buffer
|
||||||
if err := result.WriteEffective(&effective); err != nil {
|
if err := result.WriteEffective(&effective); err != nil {
|
||||||
t.Fatalf("write effective configuration: %v", err)
|
t.Fatalf("write effective configuration: %v", err)
|
||||||
}
|
}
|
||||||
for _, fragment := range []string{"prompt_dir: two", "profile_dir: ''", "artifact_root: artifacts", "addr: :9000", "render_format: json"} {
|
for _, fragment := range []string{"file: two", "directory: ''", "directory: three", "artifact_root: artifacts", "addr: :9000", "render_format: json"} {
|
||||||
if !strings.Contains(effective.String(), fragment) {
|
if !strings.Contains(effective.String(), fragment) {
|
||||||
t.Fatalf("effective output omitted %q: %s", fragment, effective.String())
|
t.Fatalf("effective output omitted %q: %s", fragment, effective.String())
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
explanation, known := result.Explain(configkit.Keys("prompt_dir"))
|
explanation, known := result.Explain(configkit.Keys("promptkit_sources").Index(0).Key("file"))
|
||||||
if !known || explanation.Effective.YAML != "two\n" {
|
if !known || explanation.Effective.YAML != "two\n" {
|
||||||
t.Fatalf("explanation does not agree with effective value: %+v known=%t", explanation, known)
|
t.Fatalf("explanation does not agree with effective value: %+v known=%t", explanation, known)
|
||||||
}
|
}
|
||||||
@@ -112,10 +150,26 @@ defaults:
|
|||||||
if !found {
|
if !found {
|
||||||
t.Fatalf("normalization was not recorded: %+v", explanation.History)
|
t.Fatalf("normalization was not recorded: %+v", explanation.History)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
unchanged, err := loadDocumentBytes("promptkit_sources:\n - file: framework.yml\n")
|
||||||
|
if err != nil {
|
||||||
|
t.Fatalf("load unchanged source path: %v", err)
|
||||||
|
}
|
||||||
|
unchangedExplanation, known := unchanged.Explain(configkit.Keys("promptkit_sources").Index(0).Key("file"))
|
||||||
|
if !known {
|
||||||
|
t.Fatal("unchanged source path was not inspectable")
|
||||||
|
}
|
||||||
|
for _, change := range unchangedExplanation.History {
|
||||||
|
if change.Origin.Operation == configkit.ChangeNormalization {
|
||||||
|
t.Fatalf("unchanged source path recorded a normalization: %+v", unchangedExplanation.History)
|
||||||
|
}
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestDocumentValidationIsSafeAndPathSpecific(t *testing.T) {
|
func TestDocumentValidationIsSafeAndPathSpecific(t *testing.T) {
|
||||||
for _, tc := range []struct{ name, content, path string }{
|
for _, tc := range []struct{ name, content, path string }{
|
||||||
|
{"empty source selector", "promptkit_sources:\n - file: ''\n", "/promptkit_sources/0"},
|
||||||
|
{"multiple source selectors", "promptkit_sources:\n - file: secret-path\n directory: private-path\n", "/promptkit_sources/0"},
|
||||||
{"negative retry", "transient_retries: -9173\n", "/transient_retries"},
|
{"negative retry", "transient_retries: -9173\n", "/transient_retries"},
|
||||||
{"negative request limit", "server:\n max_request_bytes: -9173\n", "/server/max_request_bytes"},
|
{"negative request limit", "server:\n max_request_bytes: -9173\n", "/server/max_request_bytes"},
|
||||||
{"negative artifact limit", "server:\n max_artifact_bytes: -9173\n", "/server/max_artifact_bytes"},
|
{"negative artifact limit", "server:\n max_artifact_bytes: -9173\n", "/server/max_artifact_bytes"},
|
||||||
@@ -134,7 +188,7 @@ func TestDocumentValidationIsSafeAndPathSpecific(t *testing.T) {
|
|||||||
if diagnostic.Code == configkit.CodeValidateError && diagnostic.Path.String() == tc.path {
|
if diagnostic.Code == configkit.CodeValidateError && diagnostic.Path.String() == tc.path {
|
||||||
found = true
|
found = true
|
||||||
}
|
}
|
||||||
if strings.Contains(diagnostic.Message, "9173") || strings.Contains(diagnostic.Message, "private-invalid-value") {
|
if strings.Contains(diagnostic.Message, "9173") || strings.Contains(diagnostic.Message, "private-invalid-value") || strings.Contains(diagnostic.Message, "secret-path") || strings.Contains(diagnostic.Message, "private-path") {
|
||||||
t.Fatalf("diagnostic disclosed rejected value: %+v", diagnostic)
|
t.Fatalf("diagnostic disclosed rejected value: %+v", diagnostic)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@@ -153,7 +207,13 @@ func TestDocumentRejectsNativeShapeErrors(t *testing.T) {
|
|||||||
"server:\n max_request_bytes: null\n",
|
"server:\n max_request_bytes: null\n",
|
||||||
"defaults:\n render_format: null\n",
|
"defaults:\n render_format: null\n",
|
||||||
"server:\n unknown_field: 1\n",
|
"server:\n unknown_field: 1\n",
|
||||||
"backends:\n local:\n unknown_field: 1\n",
|
"promptkit_sources:\n - file: ./selected.yml\n unknown_field: 1\n",
|
||||||
|
"promptkit_sources:\n - file: ./selected.yml\n directory: ./also-selected\n",
|
||||||
|
"promptkit_sources:\n - file: null\n",
|
||||||
|
"promptkit_sources: ./not-a-sequence.yml\n",
|
||||||
|
"prompt_dir: ./old-prompts\n",
|
||||||
|
"profile_dir: ./old-profiles\n",
|
||||||
|
"backends:\n local:\n endpoint: http://example.invalid/v1\n",
|
||||||
} {
|
} {
|
||||||
_, err := loadDocumentBytes(content)
|
_, err := loadDocumentBytes(content)
|
||||||
if err == nil {
|
if err == nil {
|
||||||
|
|||||||
@@ -1,13 +1,10 @@
|
|||||||
package config
|
package config
|
||||||
|
|
||||||
import (
|
import (
|
||||||
"errors"
|
|
||||||
"fmt"
|
"fmt"
|
||||||
"os"
|
|
||||||
"sort"
|
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
|
||||||
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
renderformat "gitea.maximumdirect.net/eric/scriptorium/internal/format"
|
||||||
|
"go.maximumdirect.net/configkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
// LoadOptions selects one application source and explicit configuration values.
|
// LoadOptions selects one application source and explicit configuration values.
|
||||||
@@ -21,35 +18,15 @@ type LoadOptions struct {
|
|||||||
// Load resolves one ConfigKit document and retains its inspection snapshot.
|
// Load resolves one ConfigKit document and retains its inspection snapshot.
|
||||||
func Load(options LoadOptions) (*configkit.Result[Document], error) {
|
func Load(options LoadOptions) (*configkit.Result[Document], error) {
|
||||||
var source configkit.Source
|
var source configkit.Source
|
||||||
fileBacked := false
|
|
||||||
if options.Explicit {
|
if options.Explicit {
|
||||||
source = configkit.File(options.Path)
|
source = configkit.File(options.Path)
|
||||||
fileBacked = true
|
|
||||||
} else {
|
} else {
|
||||||
selected := ""
|
source = configkit.SearchConfig("scriptorium", configkit.SearchPaths(defaultConfigSearchPaths...))
|
||||||
for _, candidate := range defaultConfigSearchPaths {
|
|
||||||
if _, err := os.Stat(candidate); err == nil {
|
|
||||||
selected = candidate
|
|
||||||
break
|
|
||||||
} else if !errors.Is(err, os.ErrNotExist) {
|
|
||||||
reason := "filesystem error"
|
|
||||||
if errors.Is(err, os.ErrPermission) {
|
|
||||||
reason = "permission denied"
|
|
||||||
}
|
|
||||||
return nil, fmt.Errorf("cannot inspect configuration path %q: %s", candidate, reason)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
if selected == "" {
|
|
||||||
source = configkit.NoSource()
|
|
||||||
} else {
|
|
||||||
source = configkit.File(selected)
|
|
||||||
fileBacked = true
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
result, err := configkit.Load(source, configkit.Options[Document]{
|
result, err := configkit.Load(source, configkit.Options[Document]{
|
||||||
Definition: documentDefinition(),
|
Definition: documentDefinition(),
|
||||||
Imports: fileBacked,
|
Imports: true,
|
||||||
Overlay: options.Overlay,
|
Overlay: options.Overlay,
|
||||||
Overrides: options.Overrides,
|
Overrides: options.Overrides,
|
||||||
})
|
})
|
||||||
@@ -62,8 +39,6 @@ func Load(options LoadOptions) (*configkit.Result[Document], error) {
|
|||||||
// Settings converts a validated document without another merge or normalization.
|
// Settings converts a validated document without another merge or normalization.
|
||||||
func Settings(document Document) AppSettings {
|
func Settings(document Document) AppSettings {
|
||||||
settings := AppSettings{
|
settings := AppSettings{
|
||||||
PromptDir: document.PromptDir,
|
|
||||||
ProfileDir: document.ProfileDir,
|
|
||||||
SchemaDir: document.SchemaDir,
|
SchemaDir: document.SchemaDir,
|
||||||
ServerAddr: document.Server.Addr,
|
ServerAddr: document.Server.Addr,
|
||||||
ArtifactRoot: document.Server.ArtifactRoot,
|
ArtifactRoot: document.Server.ArtifactRoot,
|
||||||
@@ -73,24 +48,8 @@ func Settings(document Document) AppSettings {
|
|||||||
DefaultRenderFormat: renderformat.PreparedRunOutputFormat(document.Defaults.RenderFormat),
|
DefaultRenderFormat: renderformat.PreparedRunOutputFormat(document.Defaults.RenderFormat),
|
||||||
TransientRetries: document.TransientRetries,
|
TransientRetries: document.TransientRetries,
|
||||||
}
|
}
|
||||||
if document.Backends != nil {
|
if document.PromptKitSources != nil {
|
||||||
ids := make([]string, 0, len(document.Backends))
|
settings.PromptKitSources = append([]SourceSelection{}, document.PromptKitSources...)
|
||||||
for id := range document.Backends {
|
|
||||||
ids = append(ids, id)
|
|
||||||
}
|
|
||||||
sort.Strings(ids)
|
|
||||||
settings.Backends = make([]BackendSettings, 0, len(ids))
|
|
||||||
for _, id := range ids {
|
|
||||||
backend := document.Backends[id]
|
|
||||||
settings.Backends = append(settings.Backends, BackendSettings{
|
|
||||||
ID: id,
|
|
||||||
Endpoint: backend.Endpoint,
|
|
||||||
APIKeyEnv: backend.APIKeyEnv,
|
|
||||||
ExtraParams: backend.ExtraParams,
|
|
||||||
ConcurrencyLimit: backend.ConcurrencyLimit,
|
|
||||||
QueueCapacity: backend.QueueCapacity,
|
|
||||||
})
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
return settings
|
return settings
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -8,7 +8,7 @@ import (
|
|||||||
"strings"
|
"strings"
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
configkit "gitea.maximumdirect.net/eric/ConfigKit"
|
"go.maximumdirect.net/configkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
func useConfigSearchPaths(t *testing.T, paths ...string) {
|
func useConfigSearchPaths(t *testing.T, paths ...string) {
|
||||||
@@ -29,19 +29,19 @@ func TestLoadSelectsOrderedSourceAndKeepsItsSnapshot(t *testing.T) {
|
|||||||
dir := t.TempDir()
|
dir := t.TempDir()
|
||||||
first := filepath.Join(dir, "first.yml")
|
first := filepath.Join(dir, "first.yml")
|
||||||
second := filepath.Join(dir, "second.yml")
|
second := filepath.Join(dir, "second.yml")
|
||||||
writeApplicationFile(t, first, "prompt_dir: ./first\n")
|
writeApplicationFile(t, first, "promptkit_sources:\n - file: ./first.yml\n")
|
||||||
writeApplicationFile(t, second, "prompt_dir: ./second\n")
|
writeApplicationFile(t, second, "promptkit_sources:\n - directory: ./second\n")
|
||||||
useConfigSearchPaths(t, first, second)
|
useConfigSearchPaths(t, first, second)
|
||||||
|
|
||||||
result, err := Load(LoadOptions{Path: filepath.Join(dir, "ignored.yml")})
|
result, err := Load(LoadOptions{Path: filepath.Join(dir, "ignored.yml")})
|
||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatalf("load first implicit source: %v", err)
|
t.Fatalf("load first implicit source: %v", err)
|
||||||
}
|
}
|
||||||
if result.Config.PromptDir != "first" || len(result.Sources()) != 1 || result.Sources()[0].Path != first {
|
if !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "first.yml"}}) || len(result.Sources()) != 1 || result.Sources()[0].Path != first {
|
||||||
t.Fatalf("unexpected implicit source: config=%+v sources=%+v", result.Config, result.Sources())
|
t.Fatalf("unexpected implicit source: config=%+v sources=%+v", result.Config, result.Sources())
|
||||||
}
|
}
|
||||||
writeApplicationFile(t, first, "prompt_dir: ./changed\n")
|
writeApplicationFile(t, first, "promptkit_sources:\n - file: ./changed.yml\n")
|
||||||
if result.Config.PromptDir != "first" {
|
if !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "first.yml"}}) {
|
||||||
t.Fatalf("result did not retain resolved snapshot: %+v", result.Config)
|
t.Fatalf("result did not retain resolved snapshot: %+v", result.Config)
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -49,7 +49,7 @@ func TestLoadSelectsOrderedSourceAndKeepsItsSnapshot(t *testing.T) {
|
|||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
result, err = Load(LoadOptions{})
|
result, err = Load(LoadOptions{})
|
||||||
if err != nil || result.Config.PromptDir != "second" || result.Sources()[0].Path != second {
|
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{Directory: "second"}}) || result.Sources()[0].Path != second {
|
||||||
t.Fatalf("second implicit source not selected: result=%+v err=%v", result, err)
|
t.Fatalf("second implicit source not selected: result=%+v err=%v", result, err)
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -113,7 +113,7 @@ func TestLoadDefaultsOnlyAndOverridesBeforeValidation(t *testing.T) {
|
|||||||
if err != nil || result.Config.Defaults.RenderFormat != "json" {
|
if err != nil || result.Config.Defaults.RenderFormat != "json" {
|
||||||
t.Fatalf("override did not precede validation: result=%+v err=%v", result, err)
|
t.Fatalf("override did not precede validation: result=%+v err=%v", result, err)
|
||||||
}
|
}
|
||||||
if len(result.Sources()) != 2 || result.Sources()[0].Layer != configkit.LayerBase || result.Sources()[1].Layer != configkit.LayerCLI {
|
if len(result.Sources()) != 2 || result.Sources()[0].Layer != configkit.LayerMain || result.Sources()[1].Layer != configkit.LayerCLI {
|
||||||
t.Fatalf("source order changed: %+v", result.Sources())
|
t.Fatalf("source order changed: %+v", result.Sources())
|
||||||
}
|
}
|
||||||
writeApplicationFile(t, path, "defaults: [\n")
|
writeApplicationFile(t, path, "defaults: [\n")
|
||||||
@@ -124,8 +124,11 @@ func TestLoadDefaultsOnlyAndOverridesBeforeValidation(t *testing.T) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestSettingsCopiesResolvedValuesAndSortsBackends(t *testing.T) {
|
func TestSettingsCopiesResolvedValuesAndSourceOrder(t *testing.T) {
|
||||||
result, err := loadDocumentBytes(`schema_dir: ""
|
result, err := loadDocumentBytes(`schema_dir: ""
|
||||||
|
promptkit_sources:
|
||||||
|
- directory: ./profiles
|
||||||
|
- file: ./framework.yml
|
||||||
transient_retries: 0
|
transient_retries: 0
|
||||||
server:
|
server:
|
||||||
addr: ""
|
addr: ""
|
||||||
@@ -133,13 +136,6 @@ server:
|
|||||||
max_request_bytes: 0
|
max_request_bytes: 0
|
||||||
defaults:
|
defaults:
|
||||||
render_format: json
|
render_format: json
|
||||||
backends:
|
|
||||||
zed:
|
|
||||||
endpoint: http://zed.invalid/v1
|
|
||||||
extra_params:
|
|
||||||
count: 4
|
|
||||||
alpha:
|
|
||||||
queue_capacity: 0
|
|
||||||
`)
|
`)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
@@ -151,31 +147,49 @@ backends:
|
|||||||
if settings.TransientRetries == nil || *settings.TransientRetries != 0 {
|
if settings.TransientRetries == nil || *settings.TransientRetries != 0 {
|
||||||
t.Fatalf("retry presence lost: %+v", settings.TransientRetries)
|
t.Fatalf("retry presence lost: %+v", settings.TransientRetries)
|
||||||
}
|
}
|
||||||
if len(settings.Backends) != 2 || settings.Backends[0].ID != "alpha" || settings.Backends[1].ID != "zed" {
|
if want := []SourceSelection{{Directory: "profiles"}, {File: "framework.yml"}}; !reflect.DeepEqual(settings.PromptKitSources, want) {
|
||||||
t.Fatalf("backend order changed: %+v", settings.Backends)
|
t.Fatalf("source ordering changed: got=%+v want=%+v", settings.PromptKitSources, want)
|
||||||
}
|
|
||||||
if settings.Backends[0].QueueCapacity == nil || *settings.Backends[0].QueueCapacity != 0 || settings.Backends[1].QueueCapacity != nil {
|
|
||||||
t.Fatalf("queue presence changed: %+v", settings.Backends)
|
|
||||||
}
|
|
||||||
if value := settings.Backends[1].ExtraParams["count"]; value != int64(4) {
|
|
||||||
t.Fatalf("dynamic number changed shape: %T %v", value, value)
|
|
||||||
}
|
}
|
||||||
|
|
||||||
if got := Settings(documentDefaults()); got.TransientRetries != nil || got.Backends != nil {
|
if got := Settings(documentDefaults()); got.TransientRetries != nil || got.PromptKitSources != nil {
|
||||||
t.Fatalf("default nullable values changed: %+v", got)
|
t.Fatalf("default nullable values changed: %+v", got)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestLoadDiscoveryErrorQuotesPath(t *testing.T) {
|
func TestLoadDiscoveryErrorQuotesPath(t *testing.T) {
|
||||||
dir := t.TempDir()
|
dir := t.TempDir()
|
||||||
loop := filepath.Join(dir, "loop-\n.yml")
|
path := filepath.Join(dir, "directory-\n.yml")
|
||||||
if err := os.Symlink(loop, loop); err != nil {
|
if err := os.Mkdir(path, 0o700); err != nil {
|
||||||
t.Skipf("symlink unavailable: %v", err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
useConfigSearchPaths(t, loop)
|
useConfigSearchPaths(t, path)
|
||||||
_, err := Load(LoadOptions{})
|
_, err := Load(LoadOptions{})
|
||||||
if err == nil || !strings.Contains(err.Error(), `\n`) || strings.Contains(err.Error(), "loop-\n.yml") {
|
var loadError *configkit.LoadError
|
||||||
t.Fatalf("discovery error did not quote path safely: %v", err)
|
if !errors.As(err, &loadError) {
|
||||||
|
t.Fatalf("expected structured error: %v", err)
|
||||||
|
}
|
||||||
|
var diagnostics strings.Builder
|
||||||
|
if err := configkit.WriteDiagnostics(&diagnostics, loadError.Diagnostics()); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if !strings.Contains(diagnostics.String(), string(configkit.CodeSourceNotRegular)) || strings.Contains(diagnostics.String(), "directory-\n.yml") {
|
||||||
|
t.Fatalf("discovery diagnostics exposed an unescaped path: %s", diagnostics.String())
|
||||||
|
}
|
||||||
|
|
||||||
|
// A decoding diagnostic can contain an authored configuration path even
|
||||||
|
// though the nonregular-file diagnostic omits its filesystem path.
|
||||||
|
file := filepath.Join(dir, "invalid.yml")
|
||||||
|
writeApplicationFile(t, file, "server:\n \"bad\\nkey\": value\n")
|
||||||
|
_, err = Load(LoadOptions{Path: file, Explicit: true})
|
||||||
|
if !errors.As(err, &loadError) {
|
||||||
|
t.Fatalf("expected decoding diagnostic: %v", err)
|
||||||
|
}
|
||||||
|
diagnostics.Reset()
|
||||||
|
if err := configkit.WriteDiagnostics(&diagnostics, loadError.Diagnostics()); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
if !strings.Contains(diagnostics.String(), `\n`) || strings.Contains(diagnostics.String(), "bad\nkey") {
|
||||||
|
t.Fatalf("diagnostic path was not escaped: %q", diagnostics.String())
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -188,25 +202,29 @@ func TestLoadComposesExplicitImportsAndSelectedOverlay(t *testing.T) {
|
|||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
base := filepath.Join(dir, "config.yml")
|
base := filepath.Join(dir, "config.yml")
|
||||||
writeApplicationFile(t, base, "configkit:\n imports:\n - glob: fragments/*.yml\nprompt_dir: ./base-prompts\nserver:\n addr: :8081\n")
|
writeApplicationFile(t, base, "config:\n imports:\n - glob: fragments/*.yml\n required: true\npromptkit_sources:\n - file: ./base-framework.yml\n")
|
||||||
writeApplicationFile(t, filepath.Join(dir, "fragments", "a.yml"), "backends:\n alpha:\n endpoint: http://alpha.invalid/v1\n")
|
writeApplicationFile(t, filepath.Join(dir, "fragments", "a.yml"), "server:\n addr: :8081\n")
|
||||||
writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "backends:\n beta:\n endpoint: http://beta.invalid/v1\n")
|
writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "defaults:\n render_format: json\n")
|
||||||
writeApplicationFile(t, filepath.Join(dir, "overlays", "local.yml"), "prompt_dir: ./overlay-prompts\nserver:\n addr: :9090\n")
|
writeApplicationFile(t, filepath.Join(dir, "overlays", "local.yml"), "promptkit_sources:\n - directory: ./overlay-framework\nserver:\n addr: :9090\n")
|
||||||
|
|
||||||
result, err := Load(LoadOptions{Path: base, Explicit: true})
|
result, err := Load(LoadOptions{Path: base, Explicit: true})
|
||||||
if err != nil || result.Config.PromptDir != "base-prompts" || len(result.Config.Backends) != 2 || len(result.Sources()) != 3 {
|
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "base-framework.yml"}}) || result.Config.Server.Addr != ":8081" || result.Config.Defaults.RenderFormat != "json" || len(result.Sources()) != 3 {
|
||||||
t.Fatalf("disjoint imports did not compose: result=%+v err=%v", result, err)
|
t.Fatalf("disjoint imports did not compose: result=%+v err=%v", result, err)
|
||||||
}
|
}
|
||||||
result, err = Load(LoadOptions{Path: base, Explicit: true, Overlay: "local", Overrides: []configkit.Override{{
|
result, err = Load(LoadOptions{Path: base, Explicit: true, Overlay: "local", Overrides: []configkit.Override{{
|
||||||
Path: configkit.Keys("server", "addr"), Value: ":7070", Flag: "--addr",
|
Path: configkit.Keys("promptkit_sources"), Value: []any{map[string]any{"file": "./cli-framework.yml"}}, Flag: "--promptkit-source",
|
||||||
}}})
|
}}})
|
||||||
if err != nil || result.Config.PromptDir != "overlay-prompts" || result.Config.Server.Addr != ":7070" || len(result.Sources()) != 5 {
|
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "cli-framework.yml"}}) || result.Config.Server.Addr != ":9090" || len(result.Sources()) != 5 {
|
||||||
t.Fatalf("overlay or explicit override changed: result=%+v err=%v", result, err)
|
t.Fatalf("overlay or explicit override changed: result=%+v err=%v", result, err)
|
||||||
}
|
}
|
||||||
|
result, err = Load(LoadOptions{Path: base, Explicit: true, Overlay: "local"})
|
||||||
|
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{Directory: "overlay-framework"}}) {
|
||||||
|
t.Fatalf("overlay did not replace the source list: result=%+v err=%v", result, err)
|
||||||
|
}
|
||||||
if _, err := Load(LoadOptions{Path: base, Explicit: true, Overlay: "missing"}); err == nil {
|
if _, err := Load(LoadOptions{Path: base, Explicit: true, Overlay: "missing"}); err == nil {
|
||||||
t.Fatal("missing selected overlay accepted")
|
t.Fatal("missing selected overlay accepted")
|
||||||
}
|
}
|
||||||
writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "backends:\n alpha:\n endpoint: http://conflict.invalid/v1\n")
|
writeApplicationFile(t, filepath.Join(dir, "fragments", "b.yml"), "server:\n addr: :8082\n")
|
||||||
if _, err := Load(LoadOptions{Path: base, Explicit: true}); err == nil {
|
if _, err := Load(LoadOptions{Path: base, Explicit: true}); err == nil {
|
||||||
t.Fatal("conflicting import accepted")
|
t.Fatal("conflicting import accepted")
|
||||||
} else {
|
} else {
|
||||||
@@ -217,17 +235,103 @@ func TestLoadComposesExplicitImportsAndSelectedOverlay(t *testing.T) {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestLoadRejectsOverlayWithoutBase(t *testing.T) {
|
func TestLoadOverlayWithoutMainContext(t *testing.T) {
|
||||||
useConfigSearchPaths(t, filepath.Join(t.TempDir(), "absent.yml"))
|
useConfigSearchPaths(t, filepath.Join(t.TempDir(), "absent.yml"))
|
||||||
if _, err := Load(LoadOptions{Overlay: "local"}); err == nil {
|
if _, err := Load(LoadOptions{Overlay: "local"}); err == nil {
|
||||||
t.Fatal("overlay without base accepted")
|
t.Fatal("overlay without a main context accepted")
|
||||||
} else {
|
} else {
|
||||||
var loadError *configkit.LoadError
|
var loadError *configkit.LoadError
|
||||||
if !errors.As(err, &loadError) {
|
if !errors.As(err, &loadError) {
|
||||||
t.Fatalf("no-base overlay lost structured diagnostic: %v", err)
|
t.Fatalf("no-context overlay lost structured diagnostic: %v", err)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
if _, err := Load(LoadOptions{Overlay: "default"}); err != nil {
|
if _, err := Load(LoadOptions{Overlay: "default"}); err != nil {
|
||||||
t.Fatalf("default must select no overlay: %v", err)
|
t.Fatalf("default must select no overlay: %v", err)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
func TestLoadDoesNotFallThroughSelectedInvalidSource(t *testing.T) {
|
||||||
|
dir := t.TempDir()
|
||||||
|
first, second := filepath.Join(dir, "first.yml"), filepath.Join(dir, "second.yml")
|
||||||
|
writeApplicationFile(t, first, "server: [\n")
|
||||||
|
writeApplicationFile(t, second, "server:\n addr: ':9090'\n")
|
||||||
|
useConfigSearchPaths(t, first, second)
|
||||||
|
if _, err := Load(LoadOptions{}); err == nil {
|
||||||
|
t.Fatal("malformed selected file fell through to the second candidate")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestLoadImportRequirednessAndDestination(t *testing.T) {
|
||||||
|
dir := t.TempDir()
|
||||||
|
main := filepath.Join(dir, "config.yml")
|
||||||
|
for _, tc := range []struct {
|
||||||
|
name, declaration string
|
||||||
|
wantError bool
|
||||||
|
}{
|
||||||
|
{"optional by default", "- path: absent.yml", false},
|
||||||
|
{"required", "- path: absent.yml\n required: true", true},
|
||||||
|
{"removed optional field", "- path: absent.yml\n optional: true", true},
|
||||||
|
} {
|
||||||
|
t.Run(tc.name, func(t *testing.T) {
|
||||||
|
writeApplicationFile(t, main, "config:\n imports:\n "+tc.declaration+"\n")
|
||||||
|
_, err := Load(LoadOptions{Path: main, Explicit: true})
|
||||||
|
if (err != nil) != tc.wantError {
|
||||||
|
t.Fatalf("load error = %v, want error %t", err, tc.wantError)
|
||||||
|
}
|
||||||
|
})
|
||||||
|
}
|
||||||
|
fragments := filepath.Join(dir, "fragments")
|
||||||
|
if err := os.Mkdir(fragments, 0o700); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
writeApplicationFile(t, filepath.Join(fragments, "server.yml"), "addr: ':8181'\n")
|
||||||
|
writeApplicationFile(t, main, "config:\n imports:\n - dir: fragments\n pattern: '*.yml'\n destination: [server]\n required: true\n")
|
||||||
|
result, err := Load(LoadOptions{Path: main, Explicit: true})
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
info, ok := result.Metadata().Lookup(configkit.Keys("server", "addr"))
|
||||||
|
if result.Config.Server.Addr != ":8181" || !ok || len(info.Origin.Locations) == 0 {
|
||||||
|
t.Fatalf("mounted value or origin missing: config=%+v origin=%+v", result.Config.Server, info)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestLoadAuthoredSelectorCollection(t *testing.T) {
|
||||||
|
dir := t.TempDir()
|
||||||
|
for _, subdir := range []string{"fragments", "overlays"} {
|
||||||
|
if err := os.Mkdir(filepath.Join(dir, subdir), 0o700); err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
main := filepath.Join(dir, "config.yml")
|
||||||
|
writeApplicationFile(t, main, "config:\n sequences:\n - destination: [promptkit_sources]\n key: file\n mode: upsert\n imports:\n - dir: fragments\n pattern: '*.yml'\n required: true\n")
|
||||||
|
writeApplicationFile(t, filepath.Join(dir, "fragments", "a.yml"), "promptkit_sources:\n - file: a.yml\n")
|
||||||
|
peer := filepath.Join(dir, "fragments", "b.yml")
|
||||||
|
writeApplicationFile(t, peer, "promptkit_sources:\n - file: b.yml\n")
|
||||||
|
writeApplicationFile(t, filepath.Join(dir, "overlays", "local.yml"), "promptkit_sources:\n - file: c.yml\n")
|
||||||
|
result, err := Load(LoadOptions{Path: main, Explicit: true, Overlay: "local"})
|
||||||
|
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "a.yml"}, {File: "b.yml"}, {File: "c.yml"}}) {
|
||||||
|
t.Fatalf("authored upsert did not retain selectors: result=%+v err=%v", result, err)
|
||||||
|
}
|
||||||
|
result, err = Load(LoadOptions{Path: main, Explicit: true, Overlay: "local", Overrides: []configkit.Override{{
|
||||||
|
Path: configkit.Keys("promptkit_sources"), Value: []any{map[string]any{"file": "cli.yml"}}, Flag: "--promptkit-source",
|
||||||
|
}}})
|
||||||
|
if err != nil || !reflect.DeepEqual(result.Config.PromptKitSources, []SourceSelection{{File: "cli.yml"}}) {
|
||||||
|
t.Fatalf("CLI list did not replace selectors: result=%+v err=%v", result, err)
|
||||||
|
}
|
||||||
|
writeApplicationFile(t, peer, "promptkit_sources:\n - file: a.yml\n")
|
||||||
|
if _, err := Load(LoadOptions{Path: main, Explicit: true}); err == nil {
|
||||||
|
t.Fatal("duplicate authored peer identity accepted")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
func TestLoadOverrideCannotRepairDecodeError(t *testing.T) {
|
||||||
|
path := filepath.Join(t.TempDir(), "config.yml")
|
||||||
|
writeApplicationFile(t, path, "server:\n max_request_bytes: not-a-number\n")
|
||||||
|
_, err := Load(LoadOptions{Path: path, Explicit: true, Overrides: []configkit.Override{{
|
||||||
|
Path: configkit.Keys("server", "max_request_bytes"), Value: int64(12), Flag: "--max-request-bytes",
|
||||||
|
}}})
|
||||||
|
if err == nil {
|
||||||
|
t.Fatal("override repaired an undecodable source value")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|||||||
@@ -14,8 +14,7 @@ var defaultConfigSearchPaths = []string{
|
|||||||
|
|
||||||
// AppSettings holds the validated application values used by executable adapters.
|
// AppSettings holds the validated application values used by executable adapters.
|
||||||
type AppSettings struct {
|
type AppSettings struct {
|
||||||
PromptDir string
|
PromptKitSources []SourceSelection
|
||||||
ProfileDir string
|
|
||||||
SchemaDir string
|
SchemaDir string
|
||||||
ServerAddr string
|
ServerAddr string
|
||||||
ArtifactRoot string
|
ArtifactRoot string
|
||||||
@@ -23,15 +22,5 @@ type AppSettings struct {
|
|||||||
MaxArtifactBytes int64
|
MaxArtifactBytes int64
|
||||||
MaxResponseBytes int64
|
MaxResponseBytes int64
|
||||||
DefaultRenderFormat renderformat.PreparedRunOutputFormat
|
DefaultRenderFormat renderformat.PreparedRunOutputFormat
|
||||||
Backends []BackendSettings
|
|
||||||
TransientRetries *int
|
TransientRetries *int
|
||||||
}
|
}
|
||||||
|
|
||||||
type BackendSettings struct {
|
|
||||||
ID string
|
|
||||||
Endpoint string
|
|
||||||
APIKeyEnv string
|
|
||||||
ExtraParams map[string]any
|
|
||||||
ConcurrencyLimit int
|
|
||||||
QueueCapacity *int
|
|
||||||
}
|
|
||||||
|
|||||||
@@ -7,50 +7,49 @@ import (
|
|||||||
"fmt"
|
"fmt"
|
||||||
"strconv"
|
"strconv"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
type PromptInspection struct {
|
type PromptInspection struct {
|
||||||
PromptID string `json:"prompt_id"`
|
PromptID string `json:"prompt_id"`
|
||||||
PromptVersion string `json:"prompt_version"`
|
|
||||||
PromptHash string `json:"prompt_hash"`
|
PromptHash string `json:"prompt_hash"`
|
||||||
DefaultProfileID string `json:"default_profile_id"`
|
DefaultProfileID *string `json:"default_profile_id,omitempty"`
|
||||||
Inputs []PromptInspectionInput `json:"inputs"`
|
Inputs *[]PromptInspectionInput `json:"inputs,omitempty"`
|
||||||
OutputContract OutputContract `json:"output_contract"`
|
OutputContract OutputContract `json:"output_contract"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type PromptInspectionInput struct {
|
type PromptInspectionInput struct {
|
||||||
Name string `json:"name"`
|
Name string `json:"name"`
|
||||||
Required bool `json:"required"`
|
Required *bool `json:"required,omitempty"`
|
||||||
ContentType string `json:"content_type"`
|
ContentType *string `json:"content_type,omitempty"`
|
||||||
Description string `json:"description"`
|
Description *string `json:"description,omitempty"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type OutputContract struct {
|
type OutputContract struct {
|
||||||
Format string `json:"format"`
|
Format string `json:"format"`
|
||||||
ValidationMode string `json:"validation_mode"`
|
ValidationMode string `json:"validation_mode"`
|
||||||
SchemaPath string `json:"schema_path"`
|
SchemaPath *string `json:"schema_path,omitempty"`
|
||||||
RepairAttempts int `json:"repair_attempts"`
|
RepairAttempts *int `json:"repair_attempts,omitempty"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type ProfileInspection struct {
|
type ProfileInspection struct {
|
||||||
ProfileID string `json:"profile_id"`
|
ProfileID string `json:"profile_id"`
|
||||||
EffectiveModelParams ProfileModelParams `json:"effective_model_params"`
|
ProfileModelParams ProfileModelParams `json:"profile_model_params"`
|
||||||
APIKeyRequired bool `json:"api_key_required"`
|
APIKeyRequired *bool `json:"api_key_required,omitempty"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type ProfileModelParams struct {
|
type ProfileModelParams struct {
|
||||||
BackendID string `json:"backend_id"`
|
BackendID *string `json:"backend_id,omitempty"`
|
||||||
Endpoint string `json:"endpoint"`
|
Endpoint *string `json:"endpoint,omitempty"`
|
||||||
Model string `json:"model"`
|
Model *string `json:"model,omitempty"`
|
||||||
Temperature float64 `json:"temperature"`
|
Temperature *float64 `json:"temperature,omitempty"`
|
||||||
MaxTokens int `json:"max_tokens"`
|
MaxTokens *int `json:"max_tokens,omitempty"`
|
||||||
TopP float64 `json:"top_p"`
|
TopP *float64 `json:"top_p,omitempty"`
|
||||||
TimeoutSeconds int `json:"timeout_seconds"`
|
TimeoutSeconds *int `json:"timeout_seconds,omitempty"`
|
||||||
ServiceTier string `json:"service_tier"`
|
ServiceTier *string `json:"service_tier,omitempty"`
|
||||||
ReasoningEffort string `json:"reasoning_effort"`
|
ReasoningEffort *string `json:"reasoning_effort,omitempty"`
|
||||||
APIKeyEnv string `json:"api_key_env"`
|
APIKeyEnv *string `json:"api_key_env,omitempty"`
|
||||||
ExtraParams map[string]any `json:"extra_params"`
|
ExtraParams *map[string]any `json:"extra_params,omitempty"`
|
||||||
}
|
}
|
||||||
|
|
||||||
func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat OutputFormat) ([]byte, error) {
|
func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat OutputFormat) ([]byte, error) {
|
||||||
@@ -58,12 +57,15 @@ func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat Outp
|
|||||||
return nil, errors.New("prompt inspection is nil")
|
return nil, errors.New("prompt inspection is nil")
|
||||||
}
|
}
|
||||||
dto := PromptInspection{
|
dto := PromptInspection{
|
||||||
PromptID: value.PromptID, PromptVersion: value.PromptVersion, PromptHash: value.PromptHash, DefaultProfileID: value.DefaultProfileID,
|
PromptID: value.PromptID, PromptHash: value.PromptHash, DefaultProfileID: value.DefaultProfileID,
|
||||||
Inputs: make([]PromptInspectionInput, len(value.Inputs)),
|
|
||||||
OutputContract: OutputContract{Format: string(value.OutputContract.Format), ValidationMode: string(value.OutputContract.ValidationMode), SchemaPath: value.OutputContract.SchemaPath, RepairAttempts: value.OutputContract.RepairAttempts},
|
OutputContract: OutputContract{Format: string(value.OutputContract.Format), ValidationMode: string(value.OutputContract.ValidationMode), SchemaPath: value.OutputContract.SchemaPath, RepairAttempts: value.OutputContract.RepairAttempts},
|
||||||
}
|
}
|
||||||
for i, input := range value.Inputs {
|
if value.Inputs != nil {
|
||||||
dto.Inputs[i] = PromptInspectionInput{Name: input.Name, Required: input.Required, ContentType: input.ContentType, Description: input.Description}
|
inputs := make([]PromptInspectionInput, len(*value.Inputs))
|
||||||
|
for i, input := range *value.Inputs {
|
||||||
|
inputs[i] = PromptInspectionInput{Name: input.Name, Required: input.Required, ContentType: input.ContentType, Description: input.Description}
|
||||||
|
}
|
||||||
|
dto.Inputs = &inputs
|
||||||
}
|
}
|
||||||
switch outputFormat {
|
switch outputFormat {
|
||||||
case OutputFormatJSON:
|
case OutputFormatJSON:
|
||||||
@@ -74,16 +76,36 @@ func FormatPromptInspection(value *promptkit.PromptInspection, outputFormat Outp
|
|||||||
return append(data, '\n'), nil
|
return append(data, '\n'), nil
|
||||||
case OutputFormatText:
|
case OutputFormatText:
|
||||||
var b bytes.Buffer
|
var b bytes.Buffer
|
||||||
fmt.Fprintf(&b, "prompt_id: %s\nprompt_version: %s\nprompt_hash: %s\ndefault_profile_id: %s\ninputs:", dto.PromptID, dto.PromptVersion, dto.PromptHash, dto.DefaultProfileID)
|
fmt.Fprintf(&b, "prompt_id: %s\nprompt_hash: %s\n", dto.PromptID, dto.PromptHash)
|
||||||
if len(dto.Inputs) == 0 {
|
if dto.DefaultProfileID != nil {
|
||||||
fmt.Fprintln(&b, " []")
|
fmt.Fprintf(&b, "default_profile_id: %s\n", *dto.DefaultProfileID)
|
||||||
|
}
|
||||||
|
if dto.Inputs != nil {
|
||||||
|
if len(*dto.Inputs) == 0 {
|
||||||
|
fmt.Fprintln(&b, "inputs: []")
|
||||||
} else {
|
} else {
|
||||||
fmt.Fprintln(&b)
|
fmt.Fprintln(&b, "inputs:")
|
||||||
for _, input := range dto.Inputs {
|
for _, input := range *dto.Inputs {
|
||||||
fmt.Fprintf(&b, " - name: %s\n required: %t\n content_type: %s\n description: %s\n", input.Name, input.Required, input.ContentType, strconv.Quote(input.Description))
|
fmt.Fprintf(&b, " - name: %s\n", input.Name)
|
||||||
|
if input.Required != nil {
|
||||||
|
fmt.Fprintf(&b, " required: %t\n", *input.Required)
|
||||||
|
}
|
||||||
|
if input.ContentType != nil {
|
||||||
|
fmt.Fprintf(&b, " content_type: %s\n", *input.ContentType)
|
||||||
|
}
|
||||||
|
if input.Description != nil {
|
||||||
|
fmt.Fprintf(&b, " description: %s\n", strconv.Quote(*input.Description))
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
fmt.Fprintf(&b, "output_contract:\n format: %s\n validation_mode: %s\n schema_path: %s\n repair_attempts: %d\n", dto.OutputContract.Format, dto.OutputContract.ValidationMode, dto.OutputContract.SchemaPath, dto.OutputContract.RepairAttempts)
|
}
|
||||||
|
}
|
||||||
|
fmt.Fprintf(&b, "output_contract:\n format: %s\n validation_mode: %s\n", dto.OutputContract.Format, dto.OutputContract.ValidationMode)
|
||||||
|
if dto.OutputContract.SchemaPath != nil {
|
||||||
|
fmt.Fprintf(&b, " schema_path: %s\n", *dto.OutputContract.SchemaPath)
|
||||||
|
}
|
||||||
|
if dto.OutputContract.RepairAttempts != nil {
|
||||||
|
fmt.Fprintf(&b, " repair_attempts: %d\n", *dto.OutputContract.RepairAttempts)
|
||||||
|
}
|
||||||
return b.Bytes(), nil
|
return b.Bytes(), nil
|
||||||
default:
|
default:
|
||||||
return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat)
|
return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat)
|
||||||
@@ -94,12 +116,11 @@ func FormatProfileInspection(value *promptkit.ProfileInspection, outputFormat Ou
|
|||||||
if value == nil {
|
if value == nil {
|
||||||
return nil, errors.New("profile inspection is nil")
|
return nil, errors.New("profile inspection is nil")
|
||||||
}
|
}
|
||||||
target := value.EffectiveModelParams
|
dto := ProfileInspection{ProfileID: value.ProfileID, APIKeyRequired: value.APIKeyRequired, ProfileModelParams: ProfileModelParams{
|
||||||
params := map[string]any{}
|
BackendID: value.Backend, Endpoint: value.Endpoint, Model: value.Model, Temperature: value.Temperature,
|
||||||
for key, item := range target.ExtraParams {
|
MaxTokens: value.MaxTokens, TopP: value.TopP, TimeoutSeconds: value.TimeoutSeconds, ServiceTier: value.ServiceTier,
|
||||||
params[key] = item
|
ReasoningEffort: value.ReasoningEffort, APIKeyEnv: value.APIKeyEnv, ExtraParams: value.ExtraParams,
|
||||||
}
|
}}
|
||||||
dto := ProfileInspection{ProfileID: value.ProfileID, APIKeyRequired: value.APIKeyRequired, EffectiveModelParams: ProfileModelParams{BackendID: target.BackendID, Endpoint: target.Endpoint, Model: target.Model, Temperature: target.Temperature, MaxTokens: target.MaxTokens, TopP: target.TopP, TimeoutSeconds: target.TimeoutSeconds, ServiceTier: target.ServiceTier, ReasoningEffort: target.ReasoningEffort, APIKeyEnv: target.APIKeyEnv, ExtraParams: params}}
|
|
||||||
switch outputFormat {
|
switch outputFormat {
|
||||||
case OutputFormatJSON:
|
case OutputFormatJSON:
|
||||||
data, err := json.MarshalIndent(dto, "", " ")
|
data, err := json.MarshalIndent(dto, "", " ")
|
||||||
@@ -109,12 +130,48 @@ func FormatProfileInspection(value *promptkit.ProfileInspection, outputFormat Ou
|
|||||||
return append(data, '\n'), nil
|
return append(data, '\n'), nil
|
||||||
case OutputFormatText:
|
case OutputFormatText:
|
||||||
var b bytes.Buffer
|
var b bytes.Buffer
|
||||||
fmt.Fprintf(&b, "profile_id: %s\neffective_model_params:\n backend_id: %s\n endpoint: %s\n model: %s\n temperature: %g\n max_tokens: %d\n top_p: %g\n timeout_seconds: %d\n service_tier: %s\n reasoning_effort: %s\n api_key_env: %s\n extra_params: ", dto.ProfileID, dto.EffectiveModelParams.BackendID, dto.EffectiveModelParams.Endpoint, dto.EffectiveModelParams.Model, dto.EffectiveModelParams.Temperature, dto.EffectiveModelParams.MaxTokens, dto.EffectiveModelParams.TopP, dto.EffectiveModelParams.TimeoutSeconds, dto.EffectiveModelParams.ServiceTier, dto.EffectiveModelParams.ReasoningEffort, dto.EffectiveModelParams.APIKeyEnv)
|
fmt.Fprintf(&b, "profile_id: %s\nprofile_model_params:\n", dto.ProfileID)
|
||||||
paramsJSON, err := json.Marshal(dto.EffectiveModelParams.ExtraParams)
|
p := dto.ProfileModelParams
|
||||||
|
if p.BackendID != nil {
|
||||||
|
fmt.Fprintf(&b, " backend_id: %s\n", *p.BackendID)
|
||||||
|
}
|
||||||
|
if p.Endpoint != nil {
|
||||||
|
fmt.Fprintf(&b, " endpoint: %s\n", *p.Endpoint)
|
||||||
|
}
|
||||||
|
if p.Model != nil {
|
||||||
|
fmt.Fprintf(&b, " model: %s\n", *p.Model)
|
||||||
|
}
|
||||||
|
if p.Temperature != nil {
|
||||||
|
fmt.Fprintf(&b, " temperature: %g\n", *p.Temperature)
|
||||||
|
}
|
||||||
|
if p.MaxTokens != nil {
|
||||||
|
fmt.Fprintf(&b, " max_tokens: %d\n", *p.MaxTokens)
|
||||||
|
}
|
||||||
|
if p.TopP != nil {
|
||||||
|
fmt.Fprintf(&b, " top_p: %g\n", *p.TopP)
|
||||||
|
}
|
||||||
|
if p.TimeoutSeconds != nil {
|
||||||
|
fmt.Fprintf(&b, " timeout_seconds: %d\n", *p.TimeoutSeconds)
|
||||||
|
}
|
||||||
|
if p.ServiceTier != nil {
|
||||||
|
fmt.Fprintf(&b, " service_tier: %s\n", *p.ServiceTier)
|
||||||
|
}
|
||||||
|
if p.ReasoningEffort != nil {
|
||||||
|
fmt.Fprintf(&b, " reasoning_effort: %s\n", *p.ReasoningEffort)
|
||||||
|
}
|
||||||
|
if p.APIKeyEnv != nil {
|
||||||
|
fmt.Fprintf(&b, " api_key_env: %s\n", *p.APIKeyEnv)
|
||||||
|
}
|
||||||
|
if p.ExtraParams != nil {
|
||||||
|
paramsJSON, err := json.Marshal(p.ExtraParams)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
return nil, err
|
return nil, err
|
||||||
}
|
}
|
||||||
fmt.Fprintf(&b, "%s\napi_key_required: %t\n", paramsJSON, dto.APIKeyRequired)
|
fmt.Fprintf(&b, " extra_params: %s\n", paramsJSON)
|
||||||
|
}
|
||||||
|
if dto.APIKeyRequired != nil {
|
||||||
|
fmt.Fprintf(&b, "api_key_required: %t\n", *dto.APIKeyRequired)
|
||||||
|
}
|
||||||
return b.Bytes(), nil
|
return b.Bytes(), nil
|
||||||
default:
|
default:
|
||||||
return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat)
|
return nil, fmt.Errorf("%w: %q", ErrUnknownPreparedRunFormat, outputFormat)
|
||||||
|
|||||||
@@ -5,120 +5,91 @@ import (
|
|||||||
"strings"
|
"strings"
|
||||||
"testing"
|
"testing"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
func TestFormatPromptInspectionPreservesDeclaredOrderAndEmptyValues(t *testing.T) {
|
func ptr[T any](value T) *T { return &value }
|
||||||
value := &promptkit.PromptInspection{PromptID: "p", PromptVersion: "1", PromptHash: "hash", Inputs: []promptkit.PromptInputDefinition{{Name: "first", Required: true, ContentType: "text/plain", Description: "first input"}, {Name: "second"}}, OutputContract: promptkit.OutputContract{Format: "text", ValidationMode: promptkit.ValidationNone}}
|
|
||||||
text, err := FormatPromptInspection(value, OutputFormatText)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatal(err)
|
|
||||||
}
|
|
||||||
if !strings.Contains(string(text), "default_profile_id: \ninputs:\n - name: first") || strings.Index(string(text), "name: first") > strings.Index(string(text), "name: second") {
|
|
||||||
t.Fatalf("unexpected text inspection: %s", text)
|
|
||||||
}
|
|
||||||
jsonOutput, err := FormatPromptInspection(value, OutputFormatJSON)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatal(err)
|
|
||||||
}
|
|
||||||
if !strings.HasSuffix(string(jsonOutput), "\n") || !strings.Contains(string(jsonOutput), `"default_profile_id": ""`) {
|
|
||||||
t.Fatalf("unexpected json inspection: %s", jsonOutput)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
func TestFormatPromptInspectionRejectsNil(t *testing.T) {
|
func TestPromptInspectionOptionalFieldsAndDisclosure(t *testing.T) {
|
||||||
|
inputs := []promptkit.PromptInputInspection{{Name: "first", Required: ptr(false), ContentType: ptr(""), Description: ptr("")}, {Name: "second"}}
|
||||||
|
value := &promptkit.PromptInspection{PromptID: "support/p", PromptHash: "hash", DefaultProfileID: ptr(""), Inputs: &inputs,
|
||||||
|
Messages: []promptkit.PromptMessageInspection{{Role: "user", Content: "private message"}}, Description: ptr("private description"), SessionID: ptr("private session"),
|
||||||
|
OutputContract: promptkit.PromptOutputInspection{Format: "text", ValidationMode: promptkit.ValidationNone, SchemaPath: ptr(""), RepairAttempts: ptr(0)}}
|
||||||
|
for _, format := range []OutputFormat{OutputFormatText, OutputFormatJSON} {
|
||||||
|
output, err := FormatPromptInspection(value, format)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
s := string(output)
|
||||||
|
for _, forbidden := range []string{"private message", "private description", "private session", "prompt_version"} {
|
||||||
|
if strings.Contains(s, forbidden) {
|
||||||
|
t.Fatalf("inspection exposed %q: %s", forbidden, s)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if strings.Index(s, "first") > strings.Index(s, "second") {
|
||||||
|
t.Fatalf("input order changed: %s", s)
|
||||||
|
}
|
||||||
|
if !strings.Contains(s, "default_profile_id") || !strings.Contains(s, "repair_attempts") || !strings.Contains(s, "required") {
|
||||||
|
t.Fatalf("present empty values missing: %s", s)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
value.DefaultProfileID, value.Inputs = nil, nil
|
||||||
|
value.OutputContract.SchemaPath, value.OutputContract.RepairAttempts = nil, nil
|
||||||
|
for _, format := range []OutputFormat{OutputFormatText, OutputFormatJSON} {
|
||||||
|
output, err := FormatPromptInspection(value, format)
|
||||||
|
if err != nil {
|
||||||
|
t.Fatal(err)
|
||||||
|
}
|
||||||
|
for _, absent := range []string{"default_profile_id", "inputs", "schema_path", "repair_attempts"} {
|
||||||
|
if strings.Contains(string(output), absent) {
|
||||||
|
t.Fatalf("absent %s rendered: %s", absent, output)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
empty := []promptkit.PromptInputInspection{}
|
||||||
|
value.Inputs = &empty
|
||||||
|
output, err := FormatPromptInspection(value, OutputFormatJSON)
|
||||||
|
if err != nil || !strings.Contains(string(output), `"inputs": []`) {
|
||||||
|
t.Fatalf("empty inputs lost: %s %v", output, err)
|
||||||
|
}
|
||||||
if _, err := FormatPromptInspection(nil, OutputFormatText); err == nil {
|
if _, err := FormatPromptInspection(nil, OutputFormatText); err == nil {
|
||||||
t.Fatal("expected nil inspection error")
|
t.Fatal("nil prompt accepted")
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
func TestFormatProfileInspectionPreservesSafeEffectiveValues(t *testing.T) {
|
func TestProfileInspectionPreservesOnlyPresentValues(t *testing.T) {
|
||||||
const secret = "sentinel-secret-must-not-appear"
|
params := map[string]any{}
|
||||||
t.Setenv("FIXTURE_PROFILE_API_KEY", secret)
|
value := &promptkit.ProfileInspection{ProfileID: "support/fast", Backend: ptr("backend"), Model: ptr(""), Temperature: ptr(0.0), MaxTokens: ptr(0), APIKeyRequired: ptr(false), ExtraParams: ¶ms}
|
||||||
|
for _, format := range []OutputFormat{OutputFormatText, OutputFormatJSON} {
|
||||||
value := &promptkit.ProfileInspection{
|
output, err := FormatProfileInspection(value, format)
|
||||||
ProfileID: "custom-derived",
|
|
||||||
EffectiveModelParams: promptkit.ExecutionTarget{
|
|
||||||
BackendID: "fixture-custom",
|
|
||||||
Endpoint: "http://127.0.0.1:11434/v1",
|
|
||||||
Model: "fixture-model",
|
|
||||||
Temperature: 0.25,
|
|
||||||
MaxTokens: 640,
|
|
||||||
TopP: 0.9,
|
|
||||||
TimeoutSeconds: 45,
|
|
||||||
ServiceTier: "flex",
|
|
||||||
ReasoningEffort: "high",
|
|
||||||
APIKeyEnv: "FIXTURE_PROFILE_API_KEY",
|
|
||||||
ExtraParams: map[string]any{
|
|
||||||
"zeta": true,
|
|
||||||
"alpha": map[string]any{"nested": []any{"first", 2.0}},
|
|
||||||
},
|
|
||||||
},
|
|
||||||
APIKeyRequired: true,
|
|
||||||
}
|
|
||||||
|
|
||||||
jsonOutput, err := FormatProfileInspection(value, OutputFormatJSON)
|
|
||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
secondJSONOutput, err := FormatProfileInspection(value, OutputFormatJSON)
|
s := string(output)
|
||||||
|
for _, key := range []string{"profile_model_params", "backend_id", "model", "temperature", "max_tokens", "api_key_required", "extra_params"} {
|
||||||
|
if !strings.Contains(s, key) {
|
||||||
|
t.Fatalf("present %s missing: %s", key, s)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
for _, key := range []string{"effective_model_params", "endpoint", "api_key_env", "top_p"} {
|
||||||
|
if strings.Contains(s, key) {
|
||||||
|
t.Fatalf("absent %s appeared: %s", key, s)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
output, err := FormatProfileInspection(value, OutputFormatJSON)
|
||||||
if err != nil {
|
if err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
if string(jsonOutput) != string(secondJSONOutput) || !strings.HasSuffix(string(jsonOutput), "\n") {
|
var decoded map[string]any
|
||||||
t.Fatalf("expected deterministic newline-terminated JSON, got %q", jsonOutput)
|
if err := json.Unmarshal(output, &decoded); err != nil {
|
||||||
}
|
|
||||||
if strings.Contains(string(jsonOutput), secret) {
|
|
||||||
t.Fatalf("inspection exposed an environment secret: %s", jsonOutput)
|
|
||||||
}
|
|
||||||
|
|
||||||
var decoded ProfileInspection
|
|
||||||
if err := json.Unmarshal(jsonOutput, &decoded); err != nil {
|
|
||||||
t.Fatalf("decode profile inspection: %v", err)
|
|
||||||
}
|
|
||||||
if decoded.ProfileID != "custom-derived" || decoded.EffectiveModelParams.BackendID != "fixture-custom" {
|
|
||||||
t.Fatalf("unexpected profile identity: %+v", decoded)
|
|
||||||
}
|
|
||||||
if decoded.EffectiveModelParams.APIKeyEnv != "FIXTURE_PROFILE_API_KEY" || !decoded.APIKeyRequired {
|
|
||||||
t.Fatalf("unexpected credential metadata: %+v", decoded)
|
|
||||||
}
|
|
||||||
alpha, ok := decoded.EffectiveModelParams.ExtraParams["alpha"].(map[string]any)
|
|
||||||
if !ok || len(alpha["nested"].([]any)) != 2 {
|
|
||||||
t.Fatalf("nested extra parameters were not preserved: %#v", decoded.EffectiveModelParams.ExtraParams)
|
|
||||||
}
|
|
||||||
|
|
||||||
textOutput, err := FormatProfileInspection(value, OutputFormatText)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
textValue := string(textOutput)
|
p := decoded["profile_model_params"].(map[string]any)
|
||||||
if !strings.Contains(textValue, "backend_id: fixture-custom") ||
|
if p["backend_id"] != "backend" || p["model"] != "" || p["temperature"] != float64(0) || decoded["api_key_required"] != false || len(p["extra_params"].(map[string]any)) != 0 {
|
||||||
!strings.Contains(textValue, "api_key_env: FIXTURE_PROFILE_API_KEY") ||
|
t.Fatalf("wrong values: %#v", decoded)
|
||||||
!strings.Contains(textValue, `extra_params: {"alpha":{"nested":["first",2]},"zeta":true}`) ||
|
|
||||||
!strings.Contains(textValue, "api_key_required: true") {
|
|
||||||
t.Fatalf("unexpected text inspection: %s", textValue)
|
|
||||||
}
|
|
||||||
if strings.Contains(textValue, secret) {
|
|
||||||
t.Fatalf("text inspection exposed an environment secret: %s", textValue)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
func TestFormatProfileInspectionPreservesEmptyBackendAndRejectsNil(t *testing.T) {
|
|
||||||
output, err := FormatProfileInspection(&promptkit.ProfileInspection{
|
|
||||||
ProfileID: "endpoint-only",
|
|
||||||
EffectiveModelParams: promptkit.ExecutionTarget{
|
|
||||||
Endpoint: "http://127.0.0.1:8000/v1",
|
|
||||||
Model: "fixture-model",
|
|
||||||
},
|
|
||||||
}, OutputFormatJSON)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatal(err)
|
|
||||||
}
|
|
||||||
if !strings.Contains(string(output), `"backend_id": ""`) ||
|
|
||||||
!strings.Contains(string(output), `"extra_params": {}`) {
|
|
||||||
t.Fatalf("expected explicit empty backend and object extra params, got %s", output)
|
|
||||||
}
|
}
|
||||||
if _, err := FormatProfileInspection(nil, OutputFormatText); err == nil {
|
if _, err := FormatProfileInspection(nil, OutputFormatText); err == nil {
|
||||||
t.Fatal("expected nil profile inspection error")
|
t.Fatal("nil profile accepted")
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -9,7 +9,7 @@ import (
|
|||||||
"sort"
|
"sort"
|
||||||
"strings"
|
"strings"
|
||||||
|
|
||||||
"gitea.maximumdirect.net/eric/promptkit"
|
"go.maximumdirect.net/promptkit"
|
||||||
)
|
)
|
||||||
|
|
||||||
var ErrUnknownPreparedRunFormat = errors.New("unknown prepared run format")
|
var ErrUnknownPreparedRunFormat = errors.New("unknown prepared run format")
|
||||||
@@ -106,7 +106,6 @@ func (textPreparedRunFormatter) Format(prepared *promptkit.PreparedRun) ([]byte,
|
|||||||
|
|
||||||
var b bytes.Buffer
|
var b bytes.Buffer
|
||||||
fmt.Fprintf(&b, "prompt: %s\n", prepared.PromptID)
|
fmt.Fprintf(&b, "prompt: %s\n", prepared.PromptID)
|
||||||
fmt.Fprintf(&b, "prompt_version: %s\n", prepared.PromptVersion)
|
|
||||||
fmt.Fprintf(&b, "selected_profile_id: %s\n", prepared.SelectedProfileID)
|
fmt.Fprintf(&b, "selected_profile_id: %s\n", prepared.SelectedProfileID)
|
||||||
if prepared.SelectedBackendID != "" {
|
if prepared.SelectedBackendID != "" {
|
||||||
fmt.Fprintf(&b, "selected_backend_id: %s\n", prepared.SelectedBackendID)
|
fmt.Fprintf(&b, "selected_backend_id: %s\n", prepared.SelectedBackendID)
|
||||||
|
|||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user