diff --git a/docs/integrations/pkg-promptkit.md b/docs/integrations/pkg-promptkit.md index 74042980..d3fe5ae3 100644 --- a/docs/integrations/pkg-promptkit.md +++ b/docs/integrations/pkg-promptkit.md @@ -1,11 +1,11 @@ # PromptKit Integration Notarius pins -[`gitea.maximumdirect.net/eric/promptkit` v0.10.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0) +[`gitea.maximumdirect.net/eric/promptkit` v0.11.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0) as its in-process prompt engine. The upstream -[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/consumers/pkg-promptkit.md) +[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.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.10.0/docs/formats.md) +[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md) owns prompt, profile, and schema file contracts. ## Supported Boundary @@ -27,7 +27,7 @@ Notarius relies on the root `promptkit` package to: admission exhaustion through `ErrCapacityExceeded`. The pinned -[`BackendLocal`, `LocalBackend`, and `WithBackend` API](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/backends.go) +[`BackendLocal`, `LocalBackend`, and `WithBackend` API](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/backends.go) owns the registration and backend-capacity contract. For one completion, the adapter calls `PrepareExecution`, takes a @@ -71,7 +71,9 @@ 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, and leaves retries to the calling pipeline stage. +error type. PromptKit's built-in client retries eligible transient HTTP failures +with its v0.11.0 default of two additional attempts per generation; Notarius +keeps pipeline-stage retries outside that completion boundary. ## Profile Sources And Compatibility @@ -86,7 +88,7 @@ configuration and deployment workflow are defined in [Operations](../operations.md#promptkit-profile-deployment). PromptKit owns `base_profile` resolution under its -[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/formats.md). +[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md). Notarius records the selected leaf identity and resolved target without parsing or merging inheritance. An unset filesystem `api_key_env` is optional and may reach the provider without authorization, which can result in a 401 or 403. @@ -125,7 +127,7 @@ 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.10.0/docs/release.md#catalog-profile-compatibility). +[catalog compatibility policy](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/policy/release.md#catalog-profile-compatibility). Use a complete operator-owned profile with explicit backend or endpoint, model, and settings when those choices must remain operator-controlled. The embedded @@ -133,7 +135,7 @@ and settings when those choices must remain operator-controlled. The embedded 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.10.0. Its fallback source, +Notarius supports this boundary against PromptKit v0.11.0. Its fallback source, 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, @@ -162,3 +164,9 @@ 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. + +PromptKit v0.11.0 is licensed under +[LGPL-3.0-or-later](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/LICENSE). +Its accompanying [GPLv3 notice](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/COPYING) +is incorporated by that license. This dependency change does not alter +Notarius's source license or distribution workflow. diff --git a/docs/internal/llm.md b/docs/internal/llm.md index 08bad59a..509d67b6 100644 --- a/docs/internal/llm.md +++ b/docs/internal/llm.md @@ -258,14 +258,16 @@ diagnostics; see ## Timeout Ownership The caller context remains the outer cancellation authority. PromptKit applies -a positive effective generation timeout as an inner request deadline; an -explicit zero disables only that generation deadline. The HTTP client timeout -is a separate transport-wide cap. Notarius forwards the caller context and -does not install another timeout wrapper around PromptKit. +a positive effective generation timeout as an inner request deadline for each +built-in generation attempt; an explicit zero disables only that generation +deadline. The HTTP client timeout is a separate transport-wide cap. Notarius +forwards the caller context and does not install another timeout wrapper around +PromptKit. -The selected PromptKit profile owns generation settings. Notarius binding -retries remain outside the adapter and repeat the complete module operation -and validation chain. PromptKit does not add a provider retry loop. +The selected PromptKit profile owns generation settings. PromptKit v0.11.0 +performs up to two additional built-in attempts for eligible transient HTTP +failures in one generation, while Notarius binding retries remain outside the +adapter and repeat the complete module operation and validation chain. Operator-facing behavior is summarized in [Operations](../operations.md#operational-limits), and the pinned upstream contract is identified in diff --git a/docs/operations.md b/docs/operations.md index be6b381e..001135e1 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -352,7 +352,9 @@ Provider execution settings and the generation timeout come from the selected PromptKit profile. The invocation-only **--reasoning-effort** and **--clear-reasoning-effort** controls may replace or clear that profile setting for all LLM-backed calls in one run without changing the profile. PromptKit -structural output repair happens within one structured-completion call. Its +v0.11.0 also retries eligible transient HTTP failures with its built-in default +of two additional attempts per generation. This retry work is separate from +structural output repair, which happens within one structured-completion call. Its effective `structured_output_repair_attempts` limit is resolved from the selected binding, then the pipeline, then the prompt declaration; see [module bindings](config.md#module-bindings-and-validators). This is distinct @@ -360,19 +362,20 @@ from Notarius binding **retries**, which rerun the complete module operation and validation chain and do not consume or replenish the structural-repair limit. The maintained production prompts declare one repair attempt, paid only after a structural failure. One structured completion with repair budget **R** -makes at most **R + 1** serial provider calls. If one stage attempt performs -**C** structured completions, a binding with **retries: N** has a maximum of -**(N + 1) * C * (R + 1)** provider calls; LLM-backed validators have their own -corresponding invocation counts and budgets. This is an upper bound, not a -promise that every call reaches a provider. +contains at most **R + 1** serial generations. Each generation can now contain +more than one provider call when PromptKit retries an eligible transient +failure. LLM-backed validators have their own corresponding invocation and +repair budgets. These are bounds on attempted work, not a promise that every +call reaches a provider. Timeouts are layered. Caller cancellation is the outer authority. A positive -effective generation timeout adds an inner request deadline, while zero -disables only that generation deadline. The HTTP client timeout remains a -transport-wide cap. Notarius does not add another timeout around PromptKit. -Repairs are serial within the same caller context, so their worst-case latency -and cost follow the provider-call bound above; provision run deadlines and -provider budgets accordingly. Credentials remain optional unless the selected +effective generation timeout adds an inner request deadline to each built-in +generation attempt, while zero disables only that generation deadline. The HTTP +client timeout remains a transport-wide cap. Notarius does not add another +timeout around PromptKit. Retries and repairs are serial within the same caller +context, so their worst-case latency and cost can exceed the structural-repair +bound above; provision run deadlines and provider budgets accordingly. +Credentials remain optional unless the selected PromptKit profile requires one, in which case preparation fails before a provider call when its configured credential is unavailable. The pinned upstream boundary and profile-format links are in diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index f130551d..517b979c 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -99,6 +99,8 @@ historical docs and explicit legacy-rejection tests are not defects. ## Stage 2 — Upgrade The PromptKit Runtime Baseline +**Status:** Completed 2026-09-25. + **Goal:** Adopt the compatible upstream dependency and document its changed default before adding Notarius controls. One small prompt. diff --git a/go.mod b/go.mod index d890ec96..6599e3e2 100644 --- a/go.mod +++ b/go.mod @@ -4,7 +4,7 @@ go 1.25.5 require ( gitea.maximumdirect.net/eric/ConfigKit v0.4.0 - gitea.maximumdirect.net/eric/promptkit v0.10.0 + gitea.maximumdirect.net/eric/promptkit v0.11.0 github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 gopkg.in/yaml.v3 v3.0.1 // indirect ) diff --git a/go.sum b/go.sum index 2472a3e5..d119cb88 100644 --- a/go.sum +++ b/go.sum @@ -1,7 +1,7 @@ gitea.maximumdirect.net/eric/ConfigKit v0.4.0 h1:fo+vKff3zTGeWqJIA38NtT84b6OUP//9ZmBH3lFuKgk= gitea.maximumdirect.net/eric/ConfigKit v0.4.0/go.mod h1:tYWpsrbLyu05r8+1MapWp5fN6ZrX9I8hU2xEPedYmYk= -gitea.maximumdirect.net/eric/promptkit v0.10.0 h1:Nyi+YbqvO7tkRjen+Opc79wuzuKIIwcSfkriixPPwrE= -gitea.maximumdirect.net/eric/promptkit v0.10.0/go.mod h1:0zEBVlJJC+ldDdXazAgybYBXNSe74vwFx5dyOuSos/w= +gitea.maximumdirect.net/eric/promptkit v0.11.0 h1:x7JguOUiInPVXK0GEitjyoRFqqvcuSTjYUvqJ+whtik= +gitea.maximumdirect.net/eric/promptkit v0.11.0/go.mod h1:0zEBVlJJC+ldDdXazAgybYBXNSe74vwFx5dyOuSos/w= gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1 h1:S2/Q/JDE+m8Ca3pDhAjVbfYrdlEhs9blj0STgNopHo0= gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v2 v2.20260922.1/go.mod h1:a3VBbh9oaGXD6ruxhtwHj+AWW6DY/SSyby1QtMmYSUo= gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0 h1:Y0EXc3eh12eKW2NrOviVqdk3oBo6UUjopt1YAa1B3Oc= diff --git a/internal/framework/llm/promptkit_profile_fingerprint.go b/internal/framework/llm/promptkit_profile_fingerprint.go index 621ea072..5ef6e092 100644 --- a/internal/framework/llm/promptkit_profile_fingerprint.go +++ b/internal/framework/llm/promptkit_profile_fingerprint.go @@ -17,7 +17,7 @@ const ( promptKitLocalBackendMarker = "notarius:promptkit-local-backend:v1" // The built-in profile catalog is compiled into this pinned PromptKit // release. Update this identity when the dependency is upgraded. - promptKitBuiltinProfileCatalogID = "promptkit:v0.10.0:builtin-profiles" + promptKitBuiltinProfileCatalogID = "promptkit:v0.11.0:builtin-profiles" ) func promptKitProfileFingerprint(profileDir, profileFile, fallbackProfileDigest string) (CheckpointFingerprint, error) {