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