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

126 lines
7.8 KiB
Markdown
Raw Normal View History

2026-07-28 16:52:49 +00:00
# PromptKit Integration
Notarius uses `go.maximumdirect.net/promptkit` at `v0.24.0` from
[the selected release](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0).
[go.mod](../../go.mod) owns the version and [attribution](../oss/attribution.md#promptkit)
owns notices/source revision. The [tagged Go consumer guide][consumer] and
[format reference][formats] 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](pkg-configkit.md) owns that shared load boundary and
the upstream [application-owned-load guide][handoff] 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](../config.md#promptkit-profiles), 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](../cli.md#run-wide-llm-overrides) owns run-wide
controls and [Module Internals](../internal/modules.md) 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][continuation].
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][prepared]
owns lifecycle. [Operations](../operations.md#accepted-result-cache-and-recovery)
owns Notarius reuse policy and [State Internals](../internal/state.md) 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](../config.md#producer-controls)
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][observations]
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](../operations.md#debug-bundles) owns handling.
## Inspection, Preflight, And Verification
[CommandKit/ckprompt](pkg-commandkit.md) 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](../../internal/cli/native_schema_load_test.go),
[producer tests](../../internal/framework/pipeline/producer_test.go),
[nested assessment](../../internal/framework/pipeline/native_assessment_test.go),
and [assembled recovery](../../internal/cli/recovery_contract_test.go) 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](../internal/llm.md) 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.
[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md
[handoff]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load
[continuation]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#coordinate-application-directed-turns
[prepared]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later
[observations]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#collect-selected-execution-facts