126 lines
7.8 KiB
Markdown
126 lines
7.8 KiB
Markdown
# 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
|