promptkit/docs/releases/v0.7.0.md

Promptkit v0.7.0

This supplemental changelog and migration guide summarizes the consumer-facing changes from v0.6.0 to v0.7.0. The annotated v0.7.0 tag is the authoritative release record. Exact current contracts belong to the linked GoDoc and durable documentation.

Summary

v0.7.0 expands provider integration and profile composition while making credential and generation-failure handling more flexible:

• Promptkit now includes the rakestrawhome backend and its Gemma profile;
• built-in generation failures expose bounded structured provider details;
• an unavailable optional API-key environment source no longer prevents a request from reaching an upstream that permits unauthenticated access; and
• profiles can inherit from and selectively refine another profile.

Compatibility

This release adds public declarations and fields but removes none. Existing keyed configuration literals and ordinary errors.Is handling continue to work.

Adding BaseProfileID to Profile and OpenAICompatibleProfileConfig changes their struct shape. Consumers using positional composite literals for either type must convert them to keyed literals. Existing keyed literals require no change.

The rakestrawhome backend ID is now built in and reserved. A consumer that previously registered that exact ID with WithBackend must remove its manual registration before upgrading. Other custom backend registrations are unchanged.

When an optional backend, profile, or request APIKeyEnv is unset, empty, or whitespace-only, the built-in client now omits Authorization and sends the request. Previously this condition could fail before transport. Set Profile.APIKeyRequired when missing credentials must remain a local preflight error.

Provider non-success responses continue to match ErrLLMGenerate. Their rendered wording is not a compatibility contract; consumers can now use errors.As with *GenerationError when structured status information is needed.

Upgrade

Update the module dependency with:

go get gitea.maximumdirect.net/eric/promptkit@v0.7.0
go mod tidy

Remove any manual rakestrawhome backend registration, convert positional profile literals to keyed literals, and run the consuming project's ordinary and race-enabled tests.

Rakestrawhome Built-In Backend And Profile

Every engine now includes the reserved rakestrawhome backend, identified by BackendRakestrawHome. The built-in rakestrawhome-gemma-4-31b profile selects that backend. Consumers can use the maintained endpoint, credential, capacity, and model defaults without registering either definition themselves.

See the built-in backend and profile catalogs and the consumer adoption example for the current contracts.

Structured Generation Errors

Non-2xx responses from the built-in OpenAI-compatible client now return an immutable *GenerationError. Consumers can inspect the HTTP status and any safely extracted provider code, type, or message while retaining the ordinary generation-error category:

var generationErr *promptkit.GenerationError
if errors.As(err, &generationErr) {
	status := generationErr.StatusCode()
	_ = status
}

Provider fields are bounded and normalized but remain untrusted and may contain sensitive request or schema details. Default and Go-syntax formatting omit those fields. Applications must apply their own disclosure policy before logging or presenting accessor values.

See the GenerationError GoDoc, the consumer error-handling guide, and the OpenAI-compatible response contract.

Optional Credential Sources

APIKeyEnv names an optional environment lookup source unless the selected profile explicitly sets APIKeyRequired. When neither a direct request key nor a usable environment value exists, the built-in client omits the bearer header and handles the upstream response normally. This supports local and other OpenAI-compatible providers that permit unauthenticated requests without hiding an authentication error returned by a provider that requires one.

The credential format reference, the Backend GoDoc, the ExecutionTargetOverride GoDoc, and the authentication integration contract define the current precedence and availability rules.

Profile Inheritance

YAML profiles can name one parent with base_profile; in-memory profiles use Profile.BaseProfileID, and OpenAICompatibleProfileConfig forwards the same field. A profile can act as an application-owned alias of a built-in or refine selected inherited settings:

promptkit.WithProfiles(promptkit.Profile{
	ID:              "weather-light",
	BaseProfileID:   "deepseek-4-flash",
	ReasoningEffort: "high",
})

Base lookup observes the existing source precedence. Chains are linear, cycle-safe, and resolved afresh for ordinary operations. Prepared execution freezes the fully resolved target. The selected leaf ID remains public while effective execution settings reflect the resolved chain.

See the profile inheritance format reference, the consumer alias example, and the Profile GoDoc for exact merge and validation behavior.

Public API Changes

The release adds:

• BackendRakestrawHome;
• GenerationError, including StatusCode, ProviderCode, ProviderType, ProviderMessage, Error, GoString, and Unwrap;
• Profile.BaseProfileID; and
• OpenAICompatibleProfileConfig.BaseProfileID.

No public declaration was removed.

Consumer Action

• Remove a manual backend registration whose ID is exactly rakestrawhome.
• Convert positional Profile or OpenAICompatibleProfileConfig literals to keyed literals.
• Set Profile.APIKeyRequired where a missing credential must fail locally instead of reaching the provider unauthenticated.
• Treat GenerationError provider fields as untrusted and potentially sensitive when adopting the new accessors.
• Run consumer ordinary and race-enabled tests after updating the module.