Document PromptKit source migration
This commit is contained in:
@@ -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.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/)
|
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/)
|
||||||
for prompt, profile, schema, preparation, generation, and validation behavior.
|
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,14 +33,16 @@ 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.2/docs/formats.md)
|
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
|
||||||
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
- [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
|
||||||
|
|
||||||
## Examples
|
## Examples
|
||||||
|
|
||||||
|
|||||||
123
docs/cli.md
123
docs/cli.md
@@ -25,19 +25,23 @@ go run ./cmd/scriptorium render \
|
|||||||
- `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 effective profile without model execution.
|
||||||
|
- `scriptorium inspect configuration`: validate or inspect Promptkit's captured framework configuration.
|
||||||
- `scriptorium config validate`: validate application configuration without building an engine.
|
- `scriptorium config 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 no-base 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,8 +64,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. |
|
||||||
| `--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. |
|
| `--prompt-version <version>` | Optional prompt-definition version selector. |
|
||||||
| `--profile <id>` | Execution-profile override. |
|
| `--profile <id>` | Execution-profile override. |
|
||||||
@@ -90,7 +93,7 @@ only; the caller context and configured transport cap remain active. CLI
|
|||||||
durations are converted to whole seconds by truncation toward zero, so any
|
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.2/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
[Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
|
||||||
With the built-in client, each transient retry gets a fresh generation timeout;
|
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
|
||||||
@@ -157,7 +160,7 @@ scriptorium render [flags]
|
|||||||
```
|
```
|
||||||
|
|
||||||
`--prompt <id>` is required. The following optional flags are supported:
|
`--prompt <id>` is required. The following optional flags are supported:
|
||||||
`--config`, `--config-overlay`, `--prompt-dir`, `--profile-dir`, `--schema-dir`, `--prompt-version`, `--profile`,
|
`--config`, `--config-overlay`, repeatable `--promptkit-source`, `--schema-dir`, `--prompt-version`, `--profile`,
|
||||||
`--input`, `--var`, `--out`, `--llm-base-url`,
|
`--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
|
||||||
@@ -185,8 +188,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. |
|
||||||
@@ -200,26 +202,26 @@ schemas, and error codes are defined in the [HTTP API reference](api.md).
|
|||||||
|
|
||||||
```text
|
```text
|
||||||
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
scriptorium inspect prompt --prompt ID [--prompt-version VERSION]
|
||||||
[--config PATH] [--config-overlay NAME] [--prompt-dir DIR] [--format text|json] [--out PATH]
|
[--config PATH] [--config-overlay NAME] [--promptkit-source PATH ...] [--schema-dir DIR] [--format text|json] [--out PATH]
|
||||||
```
|
```
|
||||||
|
|
||||||
`--prompt` is required. Inspection uses normal configuration discovery and a
|
`--prompt` 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. It
|
||||||
selected definition but does not resolve a profile, load a schema, render a
|
loads and normalizes the selected definition but does not resolve a profile,
|
||||||
template, reserve backend capacity, or call a model.
|
load a schema, render a template, reserve backend capacity, or call a model.
|
||||||
|
|
||||||
## `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. Inspection resolves profile inheritance and backend
|
||||||
resolves profile inheritance and backend defaults, but never reads a credential
|
defaults from the selected sources, but never reads a credential value, loads
|
||||||
value, loads a prompt, reserves capacity, or calls a model. Unset provider
|
a prompt, reserves capacity, or calls a model. Unset provider controls are
|
||||||
controls are shown as zero values when Promptkit leaves them unspecified.
|
shown as zero values when Promptkit leaves them unspecified.
|
||||||
|
|
||||||
## Application configuration inspection
|
## Application configuration inspection
|
||||||
|
|
||||||
@@ -230,17 +232,17 @@ 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; explicit CLI
|
||||||
overrides appear as synthetic sources. Defaults-only input without overrides
|
overrides appear as synthetic sources. Defaults-only input without overrides
|
||||||
@@ -251,19 +253,64 @@ The empty string selects the root; `/server/addr` selects a field; `~1` and
|
|||||||
`~0` escape `/` and `~` inside mapping keys. Numeric tokens are interpreted
|
`~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,
|
||||||
normalization, and structural-inheritance history, including consumed
|
CLI, normalization, and removed-value history. This is not a JSON schema or a
|
||||||
`extends` directives and removed values. This is not a JSON schema or a
|
|
||||||
byte-for-byte stable prose format. Unknown and malformed paths exit 1 without
|
byte-for-byte stable prose format. Unknown and malformed paths 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,
|
||||||
|
`/profiles/team~1summary/model` addresses the `model` field of the literal
|
||||||
|
profile ID `team/summary`. Escape `/` as `~1` and `~` as `~0`; dots in a key
|
||||||
|
remain literal. Malformed and unknown pointers exit 1 without a successful
|
||||||
|
report. Explanation prose is native and is not a stable machine-readable
|
||||||
|
format.
|
||||||
|
|
||||||
|
Framework `show` and `explain` use Promptkit's native redaction for its
|
||||||
|
classified credential-shaped provider fields, including historical values.
|
||||||
|
Environment-variable reference names and ordinary provider parameters remain
|
||||||
|
visible. Arbitrary prompt or provider content is not classified as secret by
|
||||||
|
name inspection, so treat these reports as sensitive. This redaction policy is
|
||||||
|
limited to framework configuration reports; it does not add redaction to
|
||||||
|
`inspect profile` or prepared-run output. Credentials are not resolved by any
|
||||||
|
of these inspection operations. Promptkit owns detailed field and source
|
||||||
|
semantics; see its tagged [format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
|
||||||
|
|
||||||
|
Warnings and errors go to stderr. Successful `validate` writes nothing to
|
||||||
|
stdout; successful `show`, `sources`, and `explain` write their reports there.
|
||||||
|
Parse, load, path, and output failures exit 1. A native writer error may leave
|
||||||
|
partial output.
|
||||||
|
|
||||||
## Input And Variable Syntax
|
## Input And Variable Syntax
|
||||||
|
|
||||||
|
|||||||
167
docs/config.md
167
docs/config.md
@@ -1,11 +1,12 @@
|
|||||||
# 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.2 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
|
||||||
For command syntax, see the [CLI reference](cli.md); for HTTP request shapes and
|
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
|
||||||
|
|
||||||
@@ -21,20 +22,19 @@ If neither exists, it uses built-in defaults. An explicit `--config` path must
|
|||||||
exist and decode successfully.
|
exist and decode successfully.
|
||||||
|
|
||||||
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), and
|
[composed configuration](../examples/config.composed.yml), and
|
||||||
[backend inheritance configuration](../examples/config.inheritance.yml) are
|
[framework inheritance configuration](../examples/config.inheritance.yml) are
|
||||||
copyable examples.
|
copyable examples.
|
||||||
|
|
||||||
## Application Configuration File
|
## Application Configuration File
|
||||||
|
|
||||||
Configuration is decoded by ConfigKit v0.5.0 as strict YAML. Unknown fields,
|
Configuration is decoded by ConfigKit v0.5.0 as strict YAML. Unknown fields,
|
||||||
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
|
empty files, multiple YAML documents, and YAML aliases/anchors are rejected.
|
||||||
An explicit empty string is a value: it clears a file-provided optional path
|
An explicit empty string is a value and may clear a file-provided optional
|
||||||
or, for required `prompt_dir`, fails the command's prerequisite. A scalar
|
string. A scalar `null` is not an empty string and is rejected for non-nullable
|
||||||
`null` is not an empty string and is rejected for scalar fields; nullable
|
fields; nullable fields such as `transient_retries` retain their documented
|
||||||
fields such as `transient_retries` retain their documented meaning. Raw
|
meaning. Raw API-key fields and unknown application fields are rejected.
|
||||||
API-key fields are not accepted.
|
|
||||||
|
|
||||||
ConfigKit applies defaults, the selected file, then only explicitly supplied
|
ConfigKit applies defaults, the selected file, then only explicitly supplied
|
||||||
application CLI flags before validating the result. Paths in the application
|
application CLI flags before validating the result. Paths in the application
|
||||||
@@ -42,6 +42,36 @@ document remain relative to the process working directory, not to the file's
|
|||||||
directory. Load diagnostics are printed safely on stderr; invalid application
|
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
|
||||||
|
```
|
||||||
|
|
||||||
|
Omitting the field or setting it to `[]` (or `null`) selects no
|
||||||
|
application-supplied framework sources; Promptkit's selected catalog and
|
||||||
|
maintained definitions still apply. A later sequence item overlays an earlier
|
||||||
|
one. Files within a selected directory are composed together, so conflicting
|
||||||
|
definitions in that group fail instead of using filename order as precedence.
|
||||||
|
An explicit file may use ConfigKit imports. The complete framework format and
|
||||||
|
source rules belong to the [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
|
||||||
|
|
||||||
|
Selector paths are relative to the process working directory, not to the
|
||||||
|
application configuration file. Application validation checks the selector
|
||||||
|
shape but does not open or validate Promptkit sources. `config validate`
|
||||||
|
therefore does not prove that selected sources can build an engine; use
|
||||||
|
`inspect configuration validate` for that separate check. Repeated
|
||||||
|
`--promptkit-source` flags replace the entire configured selector sequence
|
||||||
|
and preserve flag order. A selected application overlay that defines
|
||||||
|
`promptkit_sources` replaces the prior sequence as a whole.
|
||||||
|
|
||||||
### Explicit imports and selected overlays
|
### Explicit imports and selected overlays
|
||||||
|
|
||||||
A file-backed configuration may declare `configkit.imports` with relative
|
A file-backed configuration may declare `configkit.imports` with relative
|
||||||
@@ -74,15 +104,15 @@ go run ./cmd/scriptorium render \
|
|||||||
--input glossary=./examples/fixtures/glossary.yml
|
--input glossary=./examples/fixtures/glossary.yml
|
||||||
```
|
```
|
||||||
|
|
||||||
Import and overlay file locations are constrained by ConfigKit;
|
Import and overlay file locations are constrained by ConfigKit; application
|
||||||
*application path values* such as `prompt_dir` remain relative
|
path values such as `promptkit_sources`, `schema_dir`, and `server.artifact_root`
|
||||||
to the process working directory even when authored in a fragment or overlay.
|
remain relative to the process working directory even when authored in a
|
||||||
These source constraints are separate from HTTP artifact containment.
|
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. |
|
||||||
@@ -90,7 +120,6 @@ These source constraints are separate from HTTP artifact containment.
|
|||||||
| `server.max_artifact_bytes` | `16777216` | Maximum HTTP file-input artifact bytes; `0` disables the limit. |
|
| `server.max_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
|
||||||
@@ -98,91 +127,29 @@ each limit is enforced and reported. `server.artifact_root` configures an HTTP
|
|||||||
deployment boundary; see [operations](operations.md) for deployment handling.
|
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.
|
||||||
|
|
||||||
### Application mapping inheritance
|
|
||||||
|
|
||||||
Any application input mapping may use ConfigKit's `extends: sibling-name`
|
|
||||||
directive to inherit from a mapping among its immediate siblings. Names are
|
|
||||||
exact, and lookup does not search ancestor or unrelated mappings. ConfigKit
|
|
||||||
resolves inheritance after imports, a selected overlay, and explicit CLI
|
|
||||||
overrides have been assembled, and before typed decoding. It resolves every
|
|
||||||
effective relationship, even for a backend the selected profile does not use;
|
|
||||||
an invalid relationship in such a mapping still fails the load.
|
|
||||||
|
|
||||||
The child retains its own mapping name. Explicit child values replace inherited
|
|
||||||
values, including zero, false, empty strings, sequences, and null where the
|
|
||||||
application field permits null; omitted values inherit. `extends: null`
|
|
||||||
cancels inheritance and keeps the child's own settings. The parent remains an
|
|
||||||
ordinary configured entry: a parent backend is registered and validated by
|
|
||||||
Promptkit along with other configured backends, not treated as an abstract
|
|
||||||
template. Inheritance copies settings but does not create a shared capacity
|
|
||||||
pool across distinct backend IDs. The maintained [backend inheritance
|
|
||||||
example](../examples/config.inheritance.yml) shows a complete parent and child.
|
|
||||||
|
|
||||||
ConfigKit retains inherited origins and displaced values for inspection:
|
|
||||||
`show` presents the resolved result and `explain` describes derivation and
|
|
||||||
history. Inherited application paths retain their working-directory-relative
|
|
||||||
meaning. An inherited `api_key_env` remains a visible environment-variable
|
|
||||||
name passed to Promptkit; ConfigKit does not read its value. Promptkit prompt,
|
|
||||||
profile, and schema formats and HTTP request payloads are independently parsed
|
|
||||||
and do not acquire this directive. See the pinned [ConfigKit v0.5.0 inheritance
|
|
||||||
contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance)
|
|
||||||
for exact semantics.
|
|
||||||
|
|
||||||
`extends` is reserved across application input mappings, not only under
|
|
||||||
`backends`; quoting the key does not make it ordinary data. This can affect a
|
|
||||||
mapping name (such as a backend ID) or a literal provider parameter with that
|
|
||||||
name. Rename an application-owned name where appropriate. A provider-required
|
|
||||||
literal key cannot generally be renamed without provider support, and this
|
|
||||||
ConfigKit version has no escape or opt-out; a concrete need must be addressed
|
|
||||||
upstream.
|
|
||||||
|
|
||||||
## Custom Backends
|
|
||||||
|
|
||||||
Use `backends` when a profile selects an application-defined backend ID:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
backends:
|
|
||||||
local-gpu:
|
|
||||||
endpoint: http://localhost:11434/v1
|
|
||||||
api_key_env: LOCAL_GPU_API_KEY
|
|
||||||
extra_params:
|
|
||||||
provider_option: enabled
|
|
||||||
concurrency_limit: 2
|
|
||||||
queue_capacity: 0
|
|
||||||
```
|
|
||||||
|
|
||||||
Each mapping key is the case-sensitive backend ID. `endpoint` is required;
|
|
||||||
`api_key_env`, `extra_params`, `concurrency_limit`, and `queue_capacity` are
|
|
||||||
optional. `concurrency_limit: 0` leaves the backend unlimited. Omitting
|
|
||||||
`queue_capacity` lets Promptkit use its default for a limited backend, while
|
|
||||||
an explicit `queue_capacity: 0` disables queueing.
|
|
||||||
|
|
||||||
Configuration strictly owns the YAML shape and rejects unknown fields. Promptkit
|
|
||||||
validates backend IDs, endpoints, environment-variable names, extra parameters,
|
|
||||||
and capacity relationships when Scriptorium constructs its engine. There are no
|
|
||||||
backend command-line overrides. Store only an environment-variable name in
|
|
||||||
`api_key_env`; raw API-key fields are not accepted.
|
|
||||||
|
|
||||||
## 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, versions, message templates, inputs, output contracts, and
|
||||||
session IDs are Promptkit contracts.
|
session IDs are Promptkit contracts.
|
||||||
@@ -192,7 +159,7 @@ 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.2/docs/formats.md)
|
[tagged Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
|
||||||
for all of those definitions. The files under
|
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
|
||||||
@@ -201,7 +168,7 @@ application inputs using that tagged format.
|
|||||||
|
|
||||||
Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and
|
Promptkit supplies the opt-in profile IDs `promptkit-openrouter-standard` and
|
||||||
`promptkit-openrouter-auto`. They can be selected as a prompt default or request
|
`promptkit-openrouter-auto`. They can be selected as a prompt default or request
|
||||||
profile, and custom profile sources retain precedence. Their effective model
|
profile, and selected application sources retain precedence. Their effective model
|
||||||
settings may change with a catalog upgrade; use a complete application-owned
|
settings may change with a catalog upgrade; use a complete application-owned
|
||||||
profile when fixed settings are required. See the tagged format reference for
|
profile when fixed settings are required. See the tagged format reference for
|
||||||
the maintained-profile contract.
|
the maintained-profile contract.
|
||||||
@@ -235,7 +202,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.2/docs/integrations/openai-compatible-chat.md)
|
[OpenAI-compatible integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md)
|
||||||
defines outbound authentication, provider request mapping, transport limits,
|
defines outbound authentication, provider request mapping, transport limits,
|
||||||
and timeout layering.
|
and timeout layering.
|
||||||
|
|
||||||
@@ -244,4 +211,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.2/docs/formats.md)
|
- [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
|
||||||
|
|||||||
175
docs/consumers/upgrading-promptkit.md
Normal file
175
docs/consumers/upgrading-promptkit.md
Normal file
@@ -0,0 +1,175 @@
|
|||||||
|
# Upgrade Promptkit Sources And Definitions
|
||||||
|
|
||||||
|
This guide moves Scriptorium application configuration and framework files to
|
||||||
|
the Promptkit v0.12.0 source model. It covers the executable CLI and HTTP
|
||||||
|
application, not the former Scriptorium Go package. For exact framework
|
||||||
|
semantics, see the tagged [Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
|
||||||
|
and [release notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/releases/v0.12.0.md).
|
||||||
|
|
||||||
|
## Move source selectors into an ordered sequence
|
||||||
|
|
||||||
|
Replace the old application directory settings:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
prompt_dir: ./examples/prompts
|
||||||
|
profile_dir: ./examples/profiles
|
||||||
|
```
|
||||||
|
|
||||||
|
with an ordered `promptkit_sources` sequence:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
promptkit_sources:
|
||||||
|
- directory: ./examples/prompts
|
||||||
|
- directory: ./examples/profiles
|
||||||
|
- file: ./framework/backends.yml
|
||||||
|
schema_dir: ./examples/schemas
|
||||||
|
```
|
||||||
|
|
||||||
|
Each item selects exactly one `file` or `directory`. Later items overlay
|
||||||
|
earlier items; conflicts within one directory source group are errors. Paths
|
||||||
|
are relative to the process working directory. An omitted or empty sequence
|
||||||
|
selects no application-supplied framework sources, while Promptkit's selected
|
||||||
|
catalog and maintained definitions remain available. A selected application
|
||||||
|
overlay replaces the whole sequence, and repeated `--promptkit-source` flags
|
||||||
|
replace it in command-line order rather than appending to it.
|
||||||
|
|
||||||
|
The former `--prompt-dir` and `--profile-dir` flags are removed. Replace them
|
||||||
|
with repeated source flags, for example:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
scriptorium render \
|
||||||
|
--config ./examples/config.yml \
|
||||||
|
--promptkit-source ./examples/prompts \
|
||||||
|
--promptkit-source ./examples/profiles \
|
||||||
|
--promptkit-source ./examples/framework/backends.yml \
|
||||||
|
--prompt generic.markdown_summary \
|
||||||
|
--input transcript=./examples/fixtures/transcript.md \
|
||||||
|
--input glossary=./examples/fixtures/glossary.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the same source selectors with `run`, `serve`, and the supported
|
||||||
|
`inspect` commands. The [CLI reference](../cli.md) lists each command's
|
||||||
|
accepted flags.
|
||||||
|
|
||||||
|
## Relocate backend definitions
|
||||||
|
|
||||||
|
Custom backends no longer belong in Scriptorium's application configuration.
|
||||||
|
Move them into a selected Promptkit framework source file. For example, move
|
||||||
|
this old application section:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
backends:
|
||||||
|
local-gpu:
|
||||||
|
endpoint: http://localhost:11434/v1
|
||||||
|
api_key_env: LOCAL_GPU_API_KEY
|
||||||
|
```
|
||||||
|
|
||||||
|
to `framework/backends.yml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
backends:
|
||||||
|
local-gpu:
|
||||||
|
endpoint: http://localhost:11434/v1
|
||||||
|
api_key_env: LOCAL_GPU_API_KEY
|
||||||
|
```
|
||||||
|
|
||||||
|
Then select that file in `promptkit_sources`. Keep only the environment
|
||||||
|
variable name in `api_key_env`; never put the credential value in a file or
|
||||||
|
command line.
|
||||||
|
|
||||||
|
## Convert embedded identities to mapping keys
|
||||||
|
|
||||||
|
Prompt, version, profile, and backend IDs are mapping keys. Old embedded
|
||||||
|
`id`, `version`, and `base_profile` fields are not accepted. Change a standalone
|
||||||
|
prompt definition such as:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
id: meeting.summary
|
||||||
|
version: "1.0.0"
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Summarize this synthetic note.
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
```
|
||||||
|
|
||||||
|
to keyed definitions:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
prompts:
|
||||||
|
meeting.summary:
|
||||||
|
"1.0.0":
|
||||||
|
messages:
|
||||||
|
- role: user
|
||||||
|
content: Summarize this synthetic note.
|
||||||
|
output:
|
||||||
|
format: text
|
||||||
|
validation_mode: none
|
||||||
|
```
|
||||||
|
|
||||||
|
Retain the other valid definition content from your source. Likewise, replace profile
|
||||||
|
`base_profile: common` with `extends: common` inside the profile mapping.
|
||||||
|
`extends` names an exact sibling profile ID. It is resolved while sources are
|
||||||
|
composed, before Promptkit validates the final definitions.
|
||||||
|
|
||||||
|
For example, move an old standalone profile:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
id: fast
|
||||||
|
base_profile: common
|
||||||
|
timeout_seconds: 30
|
||||||
|
```
|
||||||
|
|
||||||
|
under its keyed mapping and rename the inheritance field:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
profiles:
|
||||||
|
fast:
|
||||||
|
extends: common
|
||||||
|
timeout_seconds: 30
|
||||||
|
```
|
||||||
|
|
||||||
|
## Review presence, null, and map values
|
||||||
|
|
||||||
|
Omitted values inherit or receive defaults; an explicit value can override
|
||||||
|
them even when it is `0`, `false`, or an empty string. For example,
|
||||||
|
`max_tokens: 0` is an explicit provider control, not omission. `null` is
|
||||||
|
field-specific: for example, a null `model` is unspecified, null
|
||||||
|
`timeout_seconds` restores its 600-second default, and null `extra_params`
|
||||||
|
clears the configured provider map. Check each field in the format reference
|
||||||
|
before converting old defaults or sentinel values.
|
||||||
|
|
||||||
|
For example, express the intended behavior directly:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
profiles:
|
||||||
|
explicit-zero:
|
||||||
|
temperature: 0
|
||||||
|
leave-temperature-unset:
|
||||||
|
model: explicit-model
|
||||||
|
overlay-provider-options:
|
||||||
|
extra_params:
|
||||||
|
provider_option: local
|
||||||
|
clear-provider-options:
|
||||||
|
extra_params: null
|
||||||
|
```
|
||||||
|
|
||||||
|
Maps overlay recursively. An empty map does not erase keys inherited from a
|
||||||
|
parent or backend; use `extra_params: null` to suppress the configured map.
|
||||||
|
If changing only a model or backend, review other inherited fields because
|
||||||
|
they can remain effective. Do not infer inheritance or replacement from the
|
||||||
|
old loader's behavior.
|
||||||
|
|
||||||
|
## Validate without a provider call
|
||||||
|
|
||||||
|
`scriptorium config validate --config PATH` validates Scriptorium's application
|
||||||
|
configuration, including selector shape, but does not open framework sources.
|
||||||
|
Then run `scriptorium inspect configuration validate --config PATH` to build
|
||||||
|
the engine and validate all selected Promptkit definitions, including unused
|
||||||
|
ones. It does not prepare a request, resolve credentials, contact a provider,
|
||||||
|
or load request-time schemas and artifacts. A running `serve` process captures
|
||||||
|
its configuration and message content at startup; restart it after changing
|
||||||
|
those inputs. See the [configuration](../config.md) and
|
||||||
|
[operations](../operations.md) contracts for path ownership and runtime
|
||||||
|
boundaries.
|
||||||
@@ -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.2/docs/formats.md):
|
- [Promptkit source upgrade guide](consumers/upgrading-promptkit.md): concise
|
||||||
|
source-selector and definition migration examples.
|
||||||
|
- [Promptkit v0.12.0 framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md):
|
||||||
prompt, profile, schema, execution-setting, and framework credential
|
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.12 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
|
||||||
@@ -87,25 +96,27 @@ and apply the same retention and access rules as for model input and output.
|
|||||||
|
|
||||||
Before changing production inputs, profiles, or schemas:
|
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 +161,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.2/docs/integrations/openai-compatible-chat.md)
|
[outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/integrations/openai-compatible-chat.md)
|
||||||
for details.
|
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
|
||||||
|
|||||||
@@ -3,8 +3,8 @@
|
|||||||
## Status, Baseline, And Authority
|
## Status, Baseline, And Authority
|
||||||
|
|
||||||
Planned on 2026-10-04 against Scriptorium
|
Planned on 2026-10-04 against Scriptorium
|
||||||
`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–10 are complete; stages
|
`82b0f231b6ba71328f65f9a501143b2eedbe5d9c`. Stages 1–11 are complete; stages
|
||||||
11–13 are pending.
|
12–13 are pending.
|
||||||
This plan is for a Luna coding agent: implement the stages in sequential order,
|
This plan is for a Luna coding agent: implement the stages in sequential order,
|
||||||
normally one stage per implementation prompt. The
|
normally one stage per implementation prompt. The
|
||||||
[feature roadmap](promptkit.md) owns the target state, scope, and confirmed
|
[feature roadmap](promptkit.md) owns the target state, scope, and confirmed
|
||||||
@@ -615,7 +615,23 @@ redaction exception limited to it and application/framework scopes distinguishab
|
|||||||
|
|
||||||
## Stage 11: Update User Contracts And Upgrade Guidance
|
## Stage 11: Update User Contracts And Upgrade Guidance
|
||||||
|
|
||||||
Status: Pending. Depends on Stage 10.
|
Status: Complete. The configuration reference now owns the ordered
|
||||||
|
`promptkit_sources` sequence, empty/default behavior, source precedence and
|
||||||
|
paths, application imports/overlays, and the separation from Promptkit
|
||||||
|
definition and message-resource semantics; obsolete application backend and
|
||||||
|
directory settings were removed. The CLI reference documents repeated source
|
||||||
|
flags, removed flags, command-specific options, all four framework inspection
|
||||||
|
operations, their JSON source projection, JSON Pointer behavior, output and
|
||||||
|
exit behavior, and limited native redaction. Operations distinguish
|
||||||
|
application validation from eager framework construction and describe message
|
||||||
|
capture, restart, runtime schema/artifact/credential boundaries, and sensitive
|
||||||
|
report handling. A separate executable migration guide covers selector
|
||||||
|
replacement, backend relocation, keyed IDs/versions, `base_profile` to
|
||||||
|
`extends`, and zero/null/map review. README dependency/navigation links were
|
||||||
|
updated while the historical Go-package migration and licensing footer remain
|
||||||
|
intact. The README and composed render examples, both maintained render
|
||||||
|
scripts, application validate/explain examples, and framework validate/explain
|
||||||
|
examples ran offline; `git diff --check` passes.
|
||||||
|
|
||||||
Files: `docs/config.md`, `docs/cli.md`, `docs/operations.md`, `README.md`,
|
Files: `docs/config.md`, `docs/cli.md`, `docs/operations.md`, `README.md`,
|
||||||
affected executable-consumer guidance and example scripts.
|
affected executable-consumer guidance and example scripts.
|
||||||
|
|||||||
Reference in New Issue
Block a user