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

@@ -99,24 +99,25 @@ Profile deployment has four distinct layers:
| Layer | Owner | Operational role |
| --- | --- | --- |
| Prompts and schemas | Notarius module families | Embedded request and structured-output definitions. They are not deployment profile files. |
| Prompts and schemas | Notarius module families, with optional operator prompt overlays | Embedded request and structured-output definitions; operator configuration may recursively overlay prompt fields. Schemas remain application assets. |
| Fallback profiles | Notarius module families | Embedded application defaults, including D&D's `dnd-extraction` profile. |
| Built-in profiles | PromptKit | Upstream catalog entries available when no higher-precedence source defines an ID. |
| Operator profiles | Deployment filesystem | Complete environment-specific definitions selected by `promptkit.profile_file` or `promptkit.profile_dir`. |
| Operator configuration | Deployment filesystem | Native profile/backend definitions and prompt overlays selected by `promptkit.profile_file` or `promptkit.profile_dir`. |
The maintained D&D pipeline uses the workload ID `dnd-extraction`. The
embedded fallback makes that ID usable without an operator file. Production,
development, and local deployments can each install a different complete
definition for the same ID, retaining the pipeline while choosing their own
model, backend, timeout, or reasoning policy. An operator definition wins over
the fallback; it is not merged with it. The configuration field and full
precedence rules are owned by [Configuration](config.md#promptkit-profiles).
development, and local deployments can each overlay settings for the same ID,
retaining inherited values they do not change. Notarius's registered fallback
configuration precedes the selected operator source, and groups compose by
native recursive overlays; a configured Notarius local backend is applied
after the operator source. The configuration fields and source precedence are
owned by [Configuration](config.md#promptkit-profiles).
Use a profile source owned by the service account, keep it readable only by
the intended operator, and supply provider credentials through the service
environment—not in the Notarius configuration or profile YAML. The maintained
[LLM profile](../examples/llm-profiles/dnd-extraction.yml) is secret-free and
can be copied as a format starting point. Validate a deployment without a
[LLM profiles](../examples/llm-profiles/dnd-extraction.yml) are secret-free
and can be copied as a format starting point. Validate a deployment without a
provider call or credentials:
~~~sh
@@ -132,6 +133,40 @@ surviving declaration. The complete example's
Use absolute paths such as `/etc/notarius/profiles/dnd-extraction.yml` for
services and containers when that is clearer for the deployment.
### Inspect Before Deployment
Use the three configuration reports together when reviewing an operator
source:
~~~sh
notarius config effective --scope promptkit --config /etc/notarius/config.yml
notarius config explain --scope promptkit --config /etc/notarius/config.yml \
/profiles/dnd-extraction/model
notarius config profile --config /etc/notarius/config.yml dnd-extraction
~~~
Each report command constructs an inspection engine from the selected
configuration and registered application assets. Construction validates and
captures the effective definitions; after editing a source, run the command
again to inspect a newly constructed engine. These commands do not resolve
credential values, call a provider, or prepare a request. `config profile`
reports the named profile's resolved target and effective credential metadata,
not whether a credential is available or which profile a particular prompt or
run will select.
Effective and explanation reports can include ordinary inline prompt and
provider-parameter data. Credential-shaped provider parameter keys are
redacted, but the rest of the content is not treated as secret-free. Reports
are written only when requested; Notarius does not automatically persist them
in run output or debug bundles. Operators own their destination, access, and
retention when redirecting or storing reports.
Configuration reports are distinct from a prepared execution or a requested
debug trace. They describe captured definitions and source history, not
rendered request messages, runtime credential values, or an individual
provider interaction. The [CLI reference](cli.md#config-effective) documents
the report syntax and output contracts.
## Run Lifecycle
Use the [run command](cli.md#run) to start a pipeline. A valid invocation loads