126 lines
4.7 KiB
Markdown
126 lines
4.7 KiB
Markdown
# 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.
|