81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# PromptKit Integration
|
|
|
|
Notarius pins
|
|
[`gitea.maximumdirect.net/eric/promptkit` v0.5.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.5.0)
|
|
as its in-process prompt engine. The upstream
|
|
[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.5.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.5.0/docs/formats.md)
|
|
owns prompt, profile, and schema file contracts.
|
|
|
|
## Supported Boundary
|
|
|
|
Notarius relies on the root `promptkit` package to:
|
|
|
|
- construct an `Engine` with filesystem-backed prompt, schema, and optional
|
|
operator and application-fallback profile sources;
|
|
- prepare one frozen execution from a `RunRequest` with named inline artifacts,
|
|
variables, a direct session ID, prompt identity, and profile selection, then
|
|
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`;
|
|
- 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.5.0/backends.go)
|
|
owns the registration and backend-capacity contract.
|
|
|
|
When a PromptKit profile and runtime override leave `temperature`, `max_tokens`,
|
|
or `top_p` unset, Notarius leaves that control unset as well. Compatible
|
|
providers therefore apply their own defaults; an operator that requires a
|
|
specific sampling value must select it explicitly in the profile or runtime
|
|
override.
|
|
|
|
Notarius does not use PromptKit's optional `ArtifactReader`. It materializes
|
|
source and reference content itself and supplies owned inline artifacts at the
|
|
adapter boundary. It also retains responsibility for pipeline retries,
|
|
scheduling, debug persistence, redaction, profile provenance, and conversion
|
|
from private model responses into durable domain artifacts.
|
|
|
|
Notarius sends its trimmed run session through PromptKit's direct session
|
|
field, which is authoritative for provider session behavior. It also retains
|
|
the same value as the `session_id` prompt variable for maintained prompt
|
|
compatibility. Session IDs are stable, non-secret correlation identifiers and
|
|
may be exposed to providers and provider observability.
|
|
|
|
Notarius records PromptKit's selected backend ID and effective reasoning
|
|
setting as optional run-manifest provenance. Endpoint-only profiles have no
|
|
backend ID. Debug prompt material also retains the selected backend ID and
|
|
PromptKit's stable lower-case `effective_model_params` JSON, which may include
|
|
`backend_id`. Notarius production configuration exposes one optional
|
|
conventional `local` registration. It does not expose a general user-defined
|
|
PromptKit backend registry. Endpoint-only profiles remain supported unchanged.
|
|
|
|
Notarius retains its application-wide scheduled client around the PromptKit
|
|
adapter. PromptKit may apply a narrower limit for the selected backend;
|
|
endpoint-only profiles have no such backend limit. The adapter translates
|
|
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, and leaves retries to the calling pipeline stage.
|
|
|
|
## Notarius Ownership
|
|
|
|
[LLM Runtime Internals](../internal/llm.md) describes how Notarius mounts
|
|
module assets, maps its transport-neutral completion contract, prepares and
|
|
executes requests, validates output, records provenance, captures debug
|
|
material, redacts errors, and preserves timeout ownership.
|
|
[D&D Module Internals](../internal/dnd.md) owns the embedded
|
|
`dnd-extraction` fallback profile and the maintained D&D prompt defaults.
|
|
[Configuration](../config.md#promptkit-profiles) defines how a Notarius
|
|
configuration selects one PromptKit profile source and optionally registers
|
|
the conventional local backend.
|
|
|
|
PromptKit API or format changes outside this boundary are not implicitly
|
|
supported. Updating the pinned version requires reviewing the adapter and
|
|
profile/configuration contracts against the upstream documentation.
|