From 31f2ce3a090a09b38c3f48d6178c8628278da7d8 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 1 Aug 2026 13:18:46 +0000 Subject: [PATCH] Document Promptkit v0.5.0 --- README.md | 3 + docs/releases/v0.5.0.md | 125 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 docs/releases/v0.5.0.md diff --git a/README.md b/README.md index d95abf3..fc9f92b 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,9 @@ boundary and constraints that framework work must preserve. ## Release Guidance +Consumers upgrading from `v0.4.0` to `v0.5.0` should read the +[v0.5.0 changelog and migration guide](docs/releases/v0.5.0.md). + Consumers upgrading from `v0.3.0` to `v0.4.0` should read the [v0.4.0 changelog and adoption guide](docs/releases/v0.4.0.md). diff --git a/docs/releases/v0.5.0.md b/docs/releases/v0.5.0.md new file mode 100644 index 0000000..733b170 --- /dev/null +++ b/docs/releases/v0.5.0.md @@ -0,0 +1,125 @@ +# Promptkit v0.5.0 + +This supplemental changelog and migration guide summarizes the consumer-facing +changes from `v0.4.0` to `v0.5.0`. The annotated `v0.5.0` tag is the +authoritative release record. Exact current contracts belong to the linked +GoDoc and durable documentation. + +## Summary + +`v0.5.0` makes provider requests less prescriptive and adds an application +fallback layer for profile definitions: + +- unset optional provider controls are omitted from OpenAI-compatible request + bodies instead of being populated with framework values; and +- `WithFallbackProfileFS` lets an application package profile defaults that + operators can override through the existing ordinary profile sources. + +These changes let compatible providers apply their own model defaults while +giving applications stable embedded profile IDs without weakening operator +configuration precedence. + +## Compatibility + +The release adds one public function and removes no public declaration. +Existing source code should continue to compile. + +There is one intentional behavior change: when no profile or runtime override +selects `top_p`, Promptkit no longer sends the former framework value of `1`. +It omits `top_p` and lets the provider choose its behavior. Unset +`temperature` and `max_tokens` are likewise omitted. Explicit nonzero profile +values and runtime values—including explicit runtime zero values—retain their +precedence and wire effect. + +Consumers that relied on Promptkit always sending `top_p: 1` should add that +value to the relevant profile or runtime override before upgrading. Consumers +that did not rely on the implicit sampling value require no migration. + +Application fallback profiles are opt-in. Engines that do not call +`WithFallbackProfileFS` retain the previous profile-source behavior. + +## Upgrade + +Update the module dependency with: + +```sh +go get gitea.maximumdirect.net/eric/promptkit@v0.5.0 +go mod tidy +``` + +Run the consuming project's ordinary and race-enabled tests after upgrading. +If request payloads or model behavior are asserted in fixtures, review them for +the optional-parameter omission described below. + +## Omitted Optional Provider Controls + +The built-in OpenAI-compatible client now includes `temperature`, +`max_tokens`, and `top_p` only when a profile or runtime override selects the +value. An explicit runtime zero remains present because runtime override +pointers distinguish zero from an unspecified value. + +Promptkit's positive generation deadline remains a framework concern and is +not a provider request-body default. Required request fields, session IDs, +structured output, reasoning selection, credentials, and explicit extra +parameters retain their existing behavior. + +See the [framework default and precedence reference](../formats.md#defaults-and-overrides), +the [`ExecutionTargetOverride` GoDoc](../../types.go), and the +[OpenAI-compatible request-body contract](../integrations/openai-compatible-chat.md#request-body) +for current details. + +## Embedded Application Fallback Profiles + +Applications can package ordinary profile YAML in an `fs.FS` and register it +as a fallback source: + +```go +//go:embed profiles/*.yaml +var applicationProfiles embed.FS + +engine, err := promptkit.NewEngine(promptkit.Config{ + PromptDir: "prompts", + ProfileDir: operatorProfileDir, +}, + promptkit.WithFallbackProfileFS(applicationProfiles, "profiles"), +) +``` + +Leave `operatorProfileDir` empty when no operator source is configured. A +configured ordinary source is authoritative: a matching definition overrides +the application fallback, while a read or validation failure remains an error +instead of silently reaching a lower layer. + +Profile definitions resolve in this order: + +1. in-memory profiles supplied with `WithProfiles`; +2. the ordinary configured source selected by `WithProfileFile`, + `WithProfileFS`, or `Config.ProfileDir`; +3. the application source supplied with `WithFallbackProfileFS`; and +4. Promptkit's embedded built-in profiles. + +Only an absent profile ID falls through. Sources provide complete profiles and +do not merge fields. Loading remains lazy, and the new source uses the existing +strict profile YAML and credential rules. + +See the +[embedded-default consumer guidance](../consumers/pkg-promptkit.md#supply-embedded-application-defaults), +the [`WithFallbackProfileFS` GoDoc](../../engine.go), and the +[profile source reference](../formats.md#source-and-profile-precedence) for +current details. + +## Public API Changes + +The release adds: + +- `WithFallbackProfileFS`. + +No public declaration was removed or changed. + +## Consumer Action + +- Review any workflow that depended on Promptkit's implicit `top_p: 1` and + configure the value explicitly when required. +- Optionally adopt `WithFallbackProfileFS` when an application should package + overridable profile defaults. +- Run consumer tests after updating the module dependency.