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