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 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 owns the registration and backend-capacity contract.

For one completion, the adapter calls PrepareExecution, takes a caller-owned Details snapshot, and calls RunPrepared for that same opaque prepared execution. It defers Discard for every unexecuted handle. Explicit profile preflight uses Engine.InspectProfile; it does not prepare a synthetic prompt. PromptKit's prepared handle, inspection result, and capacity-error types stay inside the Notarius LLM adapter.

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 one stable effective 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. The generated identifier is 76 ASCII characters, within PromptKit v0.5.0's 256-code-point session limit. Session IDs are non-secret correlation identifiers and may be exposed to providers and provider observability. The CLI contract owns generation and override behavior.

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.

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 Configuration and Operations.

Notarius supports this boundary against PromptKit v0.5.0. Its fallback source, 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, profile-source construction, and this compatibility statement against the pinned upstream documentation.

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. D&D Module Internals owns the embedded dnd-extraction fallback profile and the maintained D&D prompt defaults. 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.