notarius/docs/integrations/pkg-promptkit.md

PromptKit Integration

Notarius pins gitea.maximumdirect.net/eric/promptkit v0.5.0 as its in-process prompt engine. The upstream Go package consumer guide owns the public engine API, and the upstream format reference 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 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 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 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. Configuration 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.