notarius/docs/integrations/pkg-promptkit.md

PromptKit Integration

Notarius pins gitea.maximumdirect.net/eric/promptkit v0.2.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 and run a RunRequest with named inline artifacts, variables, a direct session ID, prompt identity, and profile selection;
• return rendered debug material, validated structured output, selected profile and model metadata, and token usage;
• distinguish structured-output validation failure from execution failure; and
• identify a missing explicit profile through ErrProfileNotFound.

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 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.

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.