Files
notarius/docs/integrations/pkg-promptkit.md

7.8 KiB

PromptKit Integration

Notarius uses go.maximumdirect.net/promptkit at v0.24.0 from the selected release. go.mod owns the version and attribution owns notices/source revision. The tagged Go consumer guide and format reference own native API, resource, and schema mechanics.

Configuration And Resources

The application embeds native promptkit.Settings, composes rules with Configure, and supplies its successful original ConfigKit result to NewFromConfig. It selects the bundled OpenRouter underlay before loading; engine construction does not add sources or reinterpret YAML. ConfigKit integration owns that shared load boundary and the upstream application-owned-load guide owns the library contract.

Ordinary embedded prompt/profile declarations retain native filesystem contexts. Main-relative operator companions, main imports, overlays, and explicit overrides participate in the same application result. Qualified resources, whole-record replacement/inheritance, null/presence, schema roots, and operator selection belong in Configuration, not a private profile/catalog parser.

Prompt declarations select default output contracts and schemas. Native preparation resolves the selected schema and performs structural validation/ repair; Notarius does not register response schemas or pin omitted native repair counts. Intrinsic durable artifact schemas remain application codec contracts. Native backend/profile configuration is available directly; no conventional local-backend wrapper or separate operator profile file setting is required.

One captured engine serves every model role in an invocation. Runtime-only client/HTTP settings and an optional native LLMClient injection remain native construction options. Request-specific execution/transient-retry selections remain requests, not mutation of captured settings. Notarius adds no blanket transport retry/repair or backend-admission defaults; declared profiles and native policy control effective values.

Execution, Interpretation, And Continuation

Modules build RunRequest with selected prompt/profile/session, owned inline artifacts and variables; they interpret RunResult into typed domain values. Notarius materializes source/references and contextual identity projections before execution. It uses native session selection rather than a compatibility prompt variable. CLI Reference owns run-wide controls and Module Internals owns the extension recipe.

The shared producer path uses ordinary Run, or the retained prepared handle described below. Native error and validation status are checked before interpretation, including structural failure with no Go error. The application assesses usable candidates through its complete configured chain.

For actionable semantic correction, native Coordinate starts from a captured exchange. Fixed inputs and prior responses remain in growing native history; the follow-up adds new findings/assignment, not manually replayed latest-only messages. Every delivered usable revision, including the final allowed response, receives complete assessment. Native stopped/exhausted status is not domain acceptance. Result-less failures do not recover earlier proposals, and undelivered responses are unassessed. See the continuation/coordination guide.

LLM validators call the same engine directly and return domain judgments or unavailable assessment, without a producer turn loop. Native typed errors/causes remain inspectable; Notarius adds context/disposition rather than a provider-neutral replacement error taxonomy. Caller cancellation and native operation timeouts remain distinguishable.

Prepared Reuse, Admission, And Execution Facts

For eligible cached producers, PrepareExecution supplies initial Details().MessageContentHash; a miss executes that same handle with RunPrepared, and unused handles are discarded. A hit reuses the accepted typed artifact or checked plan without native execution, exchange restoration, semantic reassessment, or historical usage. Correction retains the initial key. Native preparation does not reserve model capacity; the prepared-handle contract owns lifecycle. Operations owns Notarius reuse policy and State Internals its implementation.

Native backend admission is independent of application ready-job workers. No global LLM scheduler, extra admission queue, or application retry extends native budgets. Completed producer turns release admission before assessment, so nested validators can use the same limited backend. Strict/permissive terminal handling and supported fallback remain application choices; Configuration owns those controls.

One invocation ExecutionGroup enrolls actual initial, continuation, and nested validator calls once through composed observers. Native run/parent identity, terminal coverage, and unknown usage remain native facts, not copied totals or a durable profile ledger. The upstream execution-facts guide owns grouping semantics.

Optional capture retains available prepared/results/raw response/full exchange views plus application context, without another preparation or model call. Native credential omissions and ConfigKit marked-secret views remain intact; ordinary content is not heuristically rewritten. Debug serialization is private, not a consumer protocol. Operations owns handling.

Inspection, Preflight, And Verification

CommandKit/ckprompt supplies resource inspection, requirements, concrete request validation/preparation, namespaces, and explicit smoke testing through the same loaders. Offline pipeline preflight checks declared prompts and applicable profiles without synthetic requests, execution input reads, credential lookup, or provider work. Partial profiles can pass inspection while concrete preparation remains a later readiness boundary. Smoke execution is explicit.

Native schema tests, producer tests, nested assessment, and assembled recovery verify the selected integration using real libraries and fake providers. They cover custom contracts, native status/causes, final-turn assessment, same-backend liveness, initial-key reuse, fallback qualification, and observations without production model-quality claims.

LLM Integration Internals locates current call sites. An upgrade requires reviewing these native contracts, declaration/schema contexts, command integrations, retained domain behavior, and notices together; there is no private completion adapter to preserve.