notarius/docs/integrations/pkg-promptkit.md

PromptKit Integration

Notarius pins gitea.maximumdirect.net/eric/promptkit v0.11.1 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, profile selection, and optional appended rendered messages, 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'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. PromptKit's built-in client retries eligible transient HTTP failures with its v0.11.1 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 LLMGenerationError, retaining a safe failure kind, HTTP status when present, and retry-exhaustion attempt count. Transport, malformed successful envelopes, provider statuses, and generic generation failures remain distinct without 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 Configuration and Operations.

PromptKit owns base_profile resolution under its pinned format rules. 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.

PromptKit accepts only the developer, system, user, and assistant text-chat roles after normalizing case and surrounding whitespace. Maintained Notarius prompt definitions use only system and user.

For application-owned semantic correction, Notarius uses PromptKit's RunRequest.AppendedMessages after the ordinary rendered prompt. It supplies exactly two messages in order: the latest validated producer response with role assistant, then deterministic validation guidance with role user. It never exposes a general caller-selected role API, accumulates earlier correction turns, or changes the ordinary prompt prefix. Ordinary requests leave appended messages unset.

PromptKit preserves supplied content but does not own Notarius's correction bounds. Notarius rejects invalid UTF-8, blank, or oversized assistant material (at most 1 MiB), guidance (at most 64 KiB), and combined content (at most 1,114,112 bytes) before preparing the request. The transport-neutral application contract owns defensive copying and these limits. Default request and terminal summaries retain only safe counts, digests, identities, and usage; complete appended messages remain limited to the explicitly requested detailed debug trace.

PromptKit obtains its maintained OpenRouter and Rakestrawhome backend and profile catalogs from independently versioned transitive modules. Notarius does not import or register either catalog; PromptKit retains catalog source, 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 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.

Use a complete operator-owned profile with explicit backend or endpoint, model, and settings when those choices must remain operator-controlled. The embedded dnd-extraction fallback already follows this model and does not inherit an 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.1. 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.

PromptKit provider error details do not cross the ordinary completion boundary. Notarius exposes a provider-neutral generation category and optional status; redacted provider details are retained only in requested debug material. 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. Maintained 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.

PromptKit's LGPL-3.0-or-later grant and combined LGPLv3 and GPLv3 text are maintained upstream. The v0.11.1 patch changes licensing documentation and updates both backend catalogs to MIT-licensed v2.20260926.0 releases; it does not change runtime APIs or profile settings. See the upstream dependency attribution for catalog notices. Notarius's source license and distribution workflow are unchanged.