Document native kit integration contracts and ownership

This commit is contained in:
2026-11-22 06:52:56 +00:00
parent aa4ce04683
commit b76d511571
4 changed files with 302 additions and 207 deletions

View File

@@ -1,212 +1,125 @@
# PromptKit Integration
Notarius pins
[`gitea.maximumdirect.net/eric/promptkit` v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0)
as its in-process prompt engine. The upstream
[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
owns the public engine API, and the upstream
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
owns prompt, profile, and schema file contracts.
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.
## Supported Boundary
## Configuration And Resources
Notarius relies on the root `promptkit` package to:
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.
- 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;
- compose profile and backend mappings through `ConfigurationSources`,
`ProfileSource`, and `BackendSource`, retaining filesystem roots with
`FilesystemInputs` and `DirectoryInputs`;
- register the optional conventional `local` backend with `BackendSource`,
`BackendLocal`, and `LocalBackend`;
- distinguish structured-output validation failure from execution failure; and
- identify a missing explicit profile through `ErrProfileNotFound` and backend
admission exhaustion through `ErrCapacityExceeded`.
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.
The pinned
[`BackendSource`, `BackendLocal`, and `LocalBackend` API](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/backends.go)
owns keyed backend configuration and backend-capacity semantics. The
[package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
describes source-group assembly.
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.
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.
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.
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.
## Execution, Interpretation, And Continuation
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.
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.
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.
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.
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.
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].
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.12.0 default of two additional attempts per generation; Notarius
keeps pipeline-stage retries outside that completion boundary.
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.
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.
## Prepared Reuse, Admission, And Execution Facts
## Profile Sources And Compatibility
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.
Notarius gives PromptKit the configured operator profile source, registered
application fallback profile assets, and optional backend configuration
through the same construction path for inspection and execution. PromptKit
owns source precedence, strict group composition, and recursive field overlay:
omitted operator fields retain lower-layer values, while supplied fields
replace them. The application group retains registered filesystem roots; the
operator may be one file with native imports or a recursively discovered
directory. Imports resolve resources from their declaring file. Prompt and
profile definitions are validated after source composition, so a malformed
lower-layer value superseded by a valid overlay is not separately audited. A
malformed final effective definition fails construction. The operator
configuration and deployment workflow are defined in
[Configuration](../config.md#promptkit-profiles) and
[Operations](../operations.md#promptkit-profile-deployment).
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.
PromptKit and ConfigKit own `extends` inheritance under the
[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
Notarius records the selected leaf identity and resolved target without parsing
or merging inheritance. `api_key_env` names the environment variable; inspection
does not check whether it is set. PromptKit's effective `api_key_required`
metadata is supported in file-backed profiles and reported as metadata, not
as an availability check. Whether a usable credential reaches the provider
remains an execution concern.
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.
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`.
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.
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.
## Inspection, Preflight, And Verification
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.
[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.
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.
The selected integration modules are
[`promptkit-backend-openrouter/v3`](../oss/attribution.md#promptkit-openrouter-catalog)
and
[`promptkit-backend-rakestrawhome/v3`](../oss/attribution.md#promptkit-rakestrawhome-catalog),
both pinned at `v3.20260930.0` for this compatibility boundary.
[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.
External catalog profile names and settings can change between dependency
releases, including removal without aliases. Review directly selected IDs and
inherited `extends` 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](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/policy/release.md#catalog-profile-compatibility).
[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.
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.12.0. Its native sources,
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.
PromptKit v0.12.0 exposes old-path ConfigKit v0.5.0 types and reads its operator
documents with that engine. Notarius application configuration uses the separate
new-path ConfigKit integration; the adapter does not translate source graphs
between the two.
Captured inspection describes one engine's immutable effective view. Source
edits require constructing a new engine to become visible. Effective and
explanation reports retain PromptKit's redacted configuration and source
history contracts; the profile command is a separate Notarius-owned projection
of copied, provider-neutral metadata. None of these views reads credential
values or predicts provider defaults. See the public [CLI reference](../cli.md#config-effective),
[explanation](../cli.md#config-explain), and
[profile](../cli.md#config-profile) entries for their syntax and output
contracts.
## Notarius Ownership
[LLM Runtime Internals](../internal/llm.md) 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](../internal/dnd.md) owns the embedded
`dnd-extraction` fallback profile and the maintained D&D prompt defaults.
[Configuration](../config.md#promptkit-profiles) 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.
The v0.12.0 upgrade replaces the removed option-based configuration API with
native ConfigKit-backed sources and keyed documents; release pins and notices
are listed in the [canonical attribution](../oss/attribution.md#promptkit).
See the canonical [PromptKit attribution](../oss/attribution.md#promptkit),
[OpenRouter catalog notice](../oss/attribution.md#promptkit-openrouter-catalog),
and [Rakestrawhome catalog notice](../oss/attribution.md#promptkit-rakestrawhome-catalog).
[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