Document PromptKit source composition and deployment

This commit is contained in:
2026-10-04 14:04:32 +00:00
parent db8acbea43
commit 169a94f7ea
5 changed files with 193 additions and 29 deletions

View File

@@ -149,7 +149,7 @@ does not independently clear other inherited fields.
`extends` is now a reserved key in every input mapping, including dynamic
module options and named maps. Existing ordinary data or entry names using that
key must be renamed along with any consumer that reads them. Configuration
overlays, pipeline inheritance, and PromptKit profile `base_profile`
overlays, pipeline inheritance, and PromptKit's native profile `extends`
inheritance are separate mechanisms.
## PromptKit Profiles
@@ -185,14 +185,16 @@ file that supplies it. The complete example's
Use absolute paths for services and containers when their deployment layout is
not configuration-relative.
An operator source is optional. For a requested ID, PromptKit checks the
configured operator source first, then Notarius's embedded fallback profiles,
then its own built-in catalog. A matching profile is complete: it replaces a
lower-precedence definition rather than merging with it. The maintained
An operator source is optional. PromptKit's maintained catalog, Notarius's
registered prompt and fallback assets, and the selected operator source are
assembled in that order; a configured `local_backend` contributes its backend
last. Later source groups recursively overlay earlier groups. Within one group,
inputs compose strictly; directory filenames do not provide priority. For a
requested profile ID, an operator definition can partially override the
embedded fallback while retaining unspecified fields. The maintained
[`dnd-extraction` LLM profile](../examples/llm-profiles/dnd-extraction.yml)
is a secret-free deployment artifact; production, development, and local
deployments can each provide a complete definition with that same workload ID.
Use workload-oriented IDs for new profiles instead of model names.
is a secret-free deployment artifact. It also demonstrates a derived
development profile that is not selected by the normal pipeline.
[Operations](operations.md#promptkit-profile-deployment) owns the deployment
workflow and credential-handling guidance.
@@ -205,27 +207,121 @@ a positive value limits simultaneous local generations. The application-wide
backend field has an environment override. Omitting **local_backend** registers
nothing and preserves existing built-in and endpoint-only profile behavior.
A file-backed PromptKit profile selects the registration by its case-sensitive
backend ID:
A PromptKit file uses keyed mappings for profiles, backends, and prompts. A
profile selects a backend by its exact ID:
~~~yaml
id: local-summary
backend: local
model: example-model
profiles:
local-summary:
backend: local
model: example-model
~~~
Keep credentials out of the local-backend object. A PromptKit profile may name
its credential environment variable through `api_key_env`; set that variable
only in the run environment. PromptKit owns the
[pinned profile-file format](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.9.0/docs/formats.md),
including `base_profile` inheritance. Notarius passes profiles through without
merging them. Filesystem profiles cannot express PromptKit's in-memory
`APIKeyRequired` setting; an unset `api_key_env` is optional and may reach the
provider without authorization.
only in the run environment. `api_key_required` is supported in profile files;
inspection reports PromptKit's effective metadata but does not check whether
the named environment variable is set. PromptKit owns the
[pinned v0.12.0 format](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md),
including native `extends` inheritance and field-presence rules. Notarius
selects source groups and passes definitions through PromptKit.
The [PromptKit upstream boundary](integrations/pkg-promptkit.md) identifies the
supported package API, and [Operations](operations.md#operational-limits)
describes the effective concurrency layers.
### Native PromptKit Sources And Migration
The configured `profile_file` or `profile_dir` is a PromptKit configuration
source. It can contain profiles and backends, as well as prompt overlays.
PromptKit's catalog is followed by registered application prompt/fallback
assets and the selected operator source; Notarius's optional programmatic
`local` backend is applied last. Composition, recursion, exact-key inheritance,
and final-value validation are owned by PromptKit and ConfigKit. Explicit
`null`, zero, false, blank, and omission may have different meanings; an empty
map does not clear an inherited map.
When migrating external files from PromptKit before v0.12, place backend and
profile entries beneath their `backends` and `profiles` mappings, and place
prompt versions beneath `prompts.<prompt-id>.v1`. Remove embedded prompt
`id`/`version` fields. Replace `base_profile` with native `extends`. There is
no legacy-format parser or alias layer. Keep Notarius's `version: 5` and
`promptkit.profile_file`/`profile_dir` settings unchanged.
Imports use native ConfigKit declarations relative to the file that declares
them. A file-root layout keeps imported fragments outside a recursively
selected profile directory, avoiding selection of the same definition both by
directory discovery and by import:
~~~yaml
# notarius.yml
version: 5
promptkit:
profile_file: ./promptkit/entry.yml
~~~
~~~yaml
# promptkit/entry.yml
configkit:
imports:
- path: fragments/profiles.yml
profiles:
dnd-extraction-development:
extends: dnd-extraction
temperature: 0.2
~~~
PromptKit recursively discovers YAML files in a selected directory, and its
inputs compose strictly; there is no filename-priority merger. Imports retain
their declaring source roots, so relative message/content files resolve from
the file that declares them. Use a separate file root for related imports
when directory selection would otherwise load those files a second time.
The same unified document can declare a custom backend or select a catalog
backend without redeclaring it:
~~~yaml
backends:
private-compatible:
endpoint: https://llm.example.invalid/v1
api_key_env: PRIVATE_LLM_API_KEY
profiles:
private-summary:
backend: private-compatible
model: summary-model
catalog-summary:
backend: openrouter
model: openai/gpt-5.6-luna
~~~
To override the embedded D&D fallback for a configured local backend, supply
only the changed fields. Explicitly clear inherited settings that do not apply
to the local target:
~~~yaml
profiles:
dnd-extraction:
backend: local
model: local-model
service_tier: null
~~~
The `promptkit.local_backend` configuration registers that conventional
backend. Prompt overlays use the same recursive source composition; for
example, this changes one output setting while retaining the other embedded
definition fields:
~~~yaml
prompts:
dnd.spells:
v1:
output:
repair_attempts: 0
~~~
Sequences such as prompt messages are replaced as a whole when overridden.
Prompt and schema definitions remain subject to final effective validation at
engine construction.
`notarius config validate --pipeline <id>` resolves the selected pipeline and
inspects every explicit effective profile without contacting a provider or
requiring credential values. It rejects absent, malformed, or incompatible