Migrate CLI and module tests to keyed PromptKit sources

This commit is contained in:
2026-10-04 12:29:55 +00:00
parent 8a8ca6d83c
commit ec2ac3369b
23 changed files with 189 additions and 255 deletions

View File

@@ -1,11 +1,11 @@
# PromptKit Integration
Notarius pins
[`gitea.maximumdirect.net/eric/promptkit` v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2)
[`gitea.maximumdirect.net/eric/promptkit` v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0)
as its in-process prompt engine. The upstream
[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
owns the public engine API, and the upstream
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md)
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
owns prompt, profile, and schema file contracts.
## Supported Boundary
@@ -20,15 +20,20 @@ Notarius relies on the root `promptkit` package to:
record credential-redacted details and run that exact execution;
- return rendered debug material, validated structured output, selected
profile, backend, effective model metadata, and token usage;
- register the optional conventional `local` backend through `BackendLocal`,
`LocalBackend`, and `WithBackend`;
- compose profile and backend mappings through `ConfigurationSources`,
`ProfileSource`, and `BackendSource`, retaining filesystem roots with
`FilesystemInputs` and `DirectoryInputs`;
- register the optional conventional `local` backend with `BackendSource`,
`BackendLocal`, and `LocalBackend`;
- distinguish structured-output validation failure from execution failure; and
- identify a missing explicit profile through `ErrProfileNotFound` and backend
admission exhaustion through `ErrCapacityExceeded`.
The pinned
[`BackendLocal`, `LocalBackend`, and `WithBackend` API](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/backends.go)
owns the registration and backend-capacity contract.
[`BackendSource`, `BackendLocal`, and `LocalBackend` API](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/backends.go)
owns keyed backend configuration and backend-capacity semantics. The
[package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
describes source-group assembly.
For one completion, the adapter calls `PrepareExecution`, takes a
caller-owned `Details` snapshot, and calls `RunPrepared` for that same opaque
@@ -72,7 +77,7 @@ PromptKit capacity rejection into the provider-neutral Notarius
`ErrLLMCapacityExceeded` contract. It may include the normalized selected
backend ID in safe diagnostic context, without exposing PromptKit's capacity
error type. PromptKit's built-in client retries eligible transient HTTP failures
with its v0.11.2 default of two additional attempts per generation; Notarius
with its v0.12.0 default of two additional attempts per generation; Notarius
keeps pipeline-stage retries outside that completion boundary.
The adapter projects built-in generation failures as the application-owned
@@ -84,17 +89,17 @@ exposing PromptKit error values to Notarius callers.
## Profile Sources And Compatibility
Notarius gives PromptKit the configured operator profile source, registered
application fallback profile assets, and optional backend registration through
the same construction path for inspection and execution. PromptKit owns the
resulting source precedence and strict profile parsing: a matching operator
profile is a complete replacement for a fallback or built-in profile, while an
invalid matching document fails instead of falling through. The operator
configuration and deployment workflow are defined in
application fallback profile assets, and optional backend configuration
through the same construction path for inspection and execution. PromptKit
owns source precedence, strict group composition, and recursive field overlay:
omitted operator fields retain lower-layer values, while supplied fields
replace them. A malformed final effective definition fails construction. The
operator configuration and deployment workflow are defined in
[Configuration](../config.md#promptkit-profiles) and
[Operations](../operations.md#promptkit-profile-deployment).
PromptKit owns `base_profile` resolution under its
[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
PromptKit and ConfigKit own `extends` inheritance under the
[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
Notarius records the selected leaf identity and resolved target without parsing
or merging inheritance. An unset filesystem `api_key_env` is optional and may
reach the provider without authorization, which can result in a 401 or 403.
@@ -127,13 +132,13 @@ identity, precedence, credential, and capacity ownership.
External catalog profile names and settings can change between dependency
releases, including removal without aliases. Review directly selected IDs and
inherited `base_profile` values when upgrading. An application-owned alias that
inherited `extends` values when upgrading. An application-owned alias that
inherits an external profile does not freeze that profile's settings.
PromptKit's opt-in `promptkit-openrouter-standard` and
`promptkit-openrouter-auto` names provide name continuity within its
selected-and-tested dependency scope, not a fixed model or provider availability
guarantee. See the upstream
[catalog compatibility policy](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/policy/release.md#catalog-profile-compatibility).
[catalog compatibility policy](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/policy/release.md#catalog-profile-compatibility).
Use a complete operator-owned profile with explicit backend or endpoint, model,
and settings when those choices must remain operator-controlled. The embedded
@@ -141,7 +146,7 @@ and settings when those choices must remain operator-controlled. The embedded
external catalog profile. An upgrade updates Notarius's compiled-in catalog
checkpoint identity so prior profile-source checkpoints are not reused.
Notarius supports this boundary against PromptKit v0.11.2. Its fallback source,
Notarius supports this boundary against PromptKit v0.12.0. Its native sources,
prepared-execution, inspection, and typed capacity APIs are used as public
upstream contracts; other PromptKit APIs or file-format behavior are not
implicitly supported. A dependency upgrade requires reviewing the adapter,
@@ -171,8 +176,9 @@ production prompts use PromptKit's bounded structural-repair contract; their
current declaration is one additional repair attempt. Notarius retains the
transport-neutral boundary and does not expose PromptKit types to modules.
The v0.11.2 patch updates upstream policy and licensing documentation without
changing runtime APIs, profile settings, or dependency/catalog versions.
The v0.12.0 upgrade replaces the removed option-based configuration API with
native ConfigKit-backed sources and keyed documents; release pins and notices
are listed in the [canonical attribution](../oss/attribution.md#promptkit).
See the canonical [PromptKit attribution](../oss/attribution.md#promptkit),
[OpenRouter catalog notice](../oss/attribution.md#promptkit-openrouter-catalog),
and [Rakestrawhome catalog notice](../oss/attribution.md#promptkit-rakestrawhome-catalog).