eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Upgrade PromptKit runtime baseline

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-25 21:49:44 +00:00
parent 31b48d2d5e
commit d29a5cecd3
7 changed files with 46 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/integrations/pkg-promptkit.md
View File

@@ -1,11 +1,11 @@
# PromptKit Integration # PromptKit Integration
Notarius pins 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 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 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. owns prompt, profile, and schema file contracts.
## Supported Boundary ## Supported Boundary
@@ -27,7 +27,7 @@ Notarius relies on the root `promptkit` package to:
admission exhaustion through `ErrCapacityExceeded`. admission exhaustion through `ErrCapacityExceeded`.
The pinned 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. owns the registration and backend-capacity contract.
For one completion, the adapter calls `PrepareExecution`, takes a 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 PromptKit capacity rejection into the provider-neutral Notarius
`ErrLLMCapacityExceeded` contract. It may include the normalized selected `ErrLLMCapacityExceeded` contract. It may include the normalized selected
backend ID in safe diagnostic context, without exposing PromptKit's capacity 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 ## Profile Sources And Compatibility
@@ -86,7 +88,7 @@ configuration and deployment workflow are defined in
[Operations](../operations.md#promptkit-profile-deployment). [Operations](../operations.md#promptkit-profile-deployment).
PromptKit owns `base_profile` resolution under its 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 Notarius records the selected leaf identity and resolved target without parsing
or merging inheritance. An unset filesystem `api_key_env` is optional and may 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. 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 `promptkit-openrouter-auto` names provide name continuity within its
selected-and-tested dependency scope, not a fixed model or provider availability selected-and-tested dependency scope, not a fixed model or provider availability
guarantee. See the upstream 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, Use a complete operator-owned profile with explicit backend or endpoint, model,
and settings when those choices must remain operator-controlled. The embedded 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 external catalog profile. An upgrade updates Notarius's compiled-in catalog
checkpoint identity so prior profile-source checkpoints are not reused. 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 prepared-execution, inspection, and typed capacity APIs are used as public
upstream contracts; other PromptKit APIs or file-format behavior are not upstream contracts; other PromptKit APIs or file-format behavior are not
implicitly supported. A dependency upgrade requires reviewing the adapter, 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 production prompts use PromptKit's bounded structural-repair contract; their
current declaration is one additional repair attempt. Notarius retains the current declaration is one additional repair attempt. Notarius retains the
transport-neutral boundary and does not expose PromptKit types to modules. 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.

16
docs/internal/llm.md
View File

@@ -258,14 +258,16 @@ diagnostics; see
## Timeout Ownership ## Timeout Ownership
The caller context remains the outer cancellation authority. PromptKit applies The caller context remains the outer cancellation authority. PromptKit applies
a positive effective generation timeout as an inner request deadline; an a positive effective generation timeout as an inner request deadline for each
explicit zero disables only that generation deadline. The HTTP client timeout built-in generation attempt; an explicit zero disables only that generation
is a separate transport-wide cap. Notarius forwards the caller context and deadline. The HTTP client timeout is a separate transport-wide cap. Notarius
does not install another timeout wrapper around PromptKit. forwards the caller context and does not install another timeout wrapper around
PromptKit.
The selected PromptKit profile owns generation settings. Notarius binding The selected PromptKit profile owns generation settings. PromptKit v0.11.0
retries remain outside the adapter and repeat the complete module operation performs up to two additional built-in attempts for eligible transient HTTP
and validation chain. PromptKit does not add a provider retry loop. 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 Operator-facing behavior is summarized in
[Operations](../operations.md#operational-limits), and the pinned upstream [Operations](../operations.md#operational-limits), and the pinned upstream
contract is identified in contract is identified in

27
docs/operations.md
View File

@@ -352,7 +352,9 @@ Provider execution settings and the generation timeout come from the selected
PromptKit profile. The invocation-only **--reasoning-effort** and PromptKit profile. The invocation-only **--reasoning-effort** and
**--clear-reasoning-effort** controls may replace or clear that profile setting **--clear-reasoning-effort** controls may replace or clear that profile setting
for all LLM-backed calls in one run without changing the profile. PromptKit 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 effective `structured_output_repair_attempts` limit is resolved from the
selected binding, then the pipeline, then the prompt declaration; see selected binding, then the pipeline, then the prompt declaration; see
[module bindings](config.md#module-bindings-and-validators). This is distinct [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 and validation chain and do not consume or replenish the structural-repair
limit. The maintained production prompts declare one repair attempt, paid only limit. The maintained production prompts declare one repair attempt, paid only
after a structural failure. One structured completion with repair budget **R** after a structural failure. One structured completion with repair budget **R**
makes at most **R + 1** serial provider calls. If one stage attempt performs contains at most **R + 1** serial generations. Each generation can now contain
**C** structured completions, a binding with **retries: N** has a maximum of more than one provider call when PromptKit retries an eligible transient
**(N + 1) * C * (R + 1)** provider calls; LLM-backed validators have their own failure. LLM-backed validators have their own corresponding invocation and
corresponding invocation counts and budgets. This is an upper bound, not a repair budgets. These are bounds on attempted work, not a promise that every
promise that every call reaches a provider. call reaches a provider.
Timeouts are layered. Caller cancellation is the outer authority. A positive Timeouts are layered. Caller cancellation is the outer authority. A positive
effective generation timeout adds an inner request deadline, while zero effective generation timeout adds an inner request deadline to each built-in
disables only that generation deadline. The HTTP client timeout remains a generation attempt, while zero disables only that generation deadline. The HTTP
transport-wide cap. Notarius does not add another timeout around PromptKit. client timeout remains a transport-wide cap. Notarius does not add another
Repairs are serial within the same caller context, so their worst-case latency timeout around PromptKit. Retries and repairs are serial within the same caller
and cost follow the provider-call bound above; provision run deadlines and context, so their worst-case latency and cost can exceed the structural-repair
provider budgets accordingly. Credentials remain optional unless the selected 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 PromptKit profile requires one, in which case preparation fails before a
provider call when its configured credential is unavailable. provider call when its configured credential is unavailable.
The pinned upstream boundary and profile-format links are in The pinned upstream boundary and profile-format links are in

2
docs/roadmap/implementation.md
View File

@@ -99,6 +99,8 @@ historical docs and explicit legacy-rejection tests are not defects.
## Stage 2 — Upgrade The PromptKit Runtime Baseline ## Stage 2 — Upgrade The PromptKit Runtime Baseline
**Status:** Completed 2026-09-25.
**Goal:** Adopt the compatible upstream dependency and document its changed **Goal:** Adopt the compatible upstream dependency and document its changed
default before adding Notarius controls. One small prompt. default before adding Notarius controls. One small prompt.

2
go.mod
View File

@@ -4,7 +4,7 @@ go 1.25.5
require ( require (
gitea.maximumdirect.net/eric/ConfigKit v0.4.0 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 github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
gopkg.in/yaml.v3 v3.0.1 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect
) )

4
go.sum
View File

@@ -1,7 +1,7 @@
gitea.maximumdirect.net/eric/ConfigKit v0.4.0 h1:fo+vKff3zTGeWqJIA38NtT84b6OUP//9ZmBH3lFuKgk= 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/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.11.0 h1:x7JguOUiInPVXK0GEitjyoRFqqvcuSTjYUvqJ+whtik=
gitea.maximumdirect.net/eric/promptkit v0.10.0/go.mod h1:0zEBVlJJC+ldDdXazAgybYBXNSe74vwFx5dyOuSos/w= 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 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-openrouter/v2 v2.20260922.1/go.mod h1:a3VBbh9oaGXD6ruxhtwHj+AWW6DY/SSyby1QtMmYSUo=
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0 h1:Y0EXc3eh12eKW2NrOviVqdk3oBo6UUjopt1YAa1B3Oc= gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v2 v2.20260922.0 h1:Y0EXc3eh12eKW2NrOviVqdk3oBo6UUjopt1YAa1B3Oc=

2
internal/framework/llm/promptkit_profile_fingerprint.go
View File

@@ -17,7 +17,7 @@ const (
promptKitLocalBackendMarker = "notarius:promptkit-local-backend:v1" promptKitLocalBackendMarker = "notarius:promptkit-local-backend:v1"
// The built-in profile catalog is compiled into this pinned PromptKit // The built-in profile catalog is compiled into this pinned PromptKit
// release. Update this identity when the dependency is upgraded. // 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) { func promptKitProfileFingerprint(profileDir, profileFile, fallbackProfileDigest string) (CheckpointFingerprint, error) {