promptkit/docs/releases/v0.5.0.md

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:

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, the ExecutionTargetOverride GoDoc, and the OpenAI-compatible request-body contract 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: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, the WithFallbackProfileFS GoDoc, and the profile source reference 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.