Document PromptKit source composition and deployment
This commit is contained in:
134
docs/config.md
134
docs/config.md
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user