Prepare the v0.25.0 release documentation
This commit is contained in:
88
docs/releases/v0.25.0.md
Normal file
88
docs/releases/v0.25.0.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Promptkit v0.25.0
|
||||
|
||||
This minor release adds invocation-scoped execution observation, provider-specific
|
||||
reasoning and cache usage, and optional USD cost reporting. Backend definitions
|
||||
can now select API conventions independently of their names and endpoints.
|
||||
Consumers upgrading from v0.24.x should review the configuration and accounting
|
||||
changes below.
|
||||
|
||||
## Added And Changed
|
||||
|
||||
- `WithExecutionObserver` selects observation through a caller-owned context
|
||||
across nested, concurrent, coordinated, and multi-engine calls. Request
|
||||
observers run before contextual observers. Prepared handles retain their
|
||||
explicit request observer but select contextual observers when executed,
|
||||
not when prepared. Each execution retains independent accounting; groups
|
||||
count each run's first terminal once. See the
|
||||
[observation guide](../consumers/pkg-promptkit.md#observe-an-ordinary-run)
|
||||
and [offline example](../../examples/go-library/observe/main.go).
|
||||
- Backend `provider` selects `openai-compatible`, `openrouter`, or `vllm`
|
||||
conventions. Omitted, null, or blank selects the generic OpenAI-compatible
|
||||
behavior. The bundled OpenRouter backend explicitly selects `openrouter`.
|
||||
`InspectBackend` exposes declared provider and `zero_cost` settings without
|
||||
manufacturing runtime defaults. See the
|
||||
[backend reference](../formats.md#backend-definitions).
|
||||
- Usage values, presence indicators, observations, and group summaries include
|
||||
`ReasoningTokens`. OpenRouter and vLLM decoding includes their respective
|
||||
reasoning, cache-read, and cache-write fields. Reasoning is a subset of
|
||||
completion tokens; cache activity does not add to reported token totals.
|
||||
`ObservedTokenUsage.CacheHitRatio` derives a ratio from complete, consistent
|
||||
input and cache-read totals. See the
|
||||
[response contract](../integrations/openai-compatible-chat.md#response-handling).
|
||||
- `RunResult.CostUSD`, execution events, and group summaries report a USD
|
||||
subtotal with availability, completeness, and source metadata. OpenRouter
|
||||
supplies optional `usage.cost`; injected clients can supply
|
||||
`GenerateResponse.CostUSD`. Explicit backend `zero_cost: true` supplies a
|
||||
zero fallback when no usable amount is reported. A reported amount, including
|
||||
zero, takes precedence. See the [cost GoDoc](../../cost.go).
|
||||
- Authentication diagnostics can use provider defaults: `openrouter_key` for
|
||||
OpenRouter and the new `vllm_models` adapter for vLLM. The latter probes
|
||||
base-relative `/models` and reports recognized response facts without
|
||||
asserting authentication enforcement or inference authorization. See the
|
||||
[diagnostic integration contract](../integrations/openai-compatible-chat.md#explicit-smoke-diagnostics).
|
||||
|
||||
## Compatibility And Upgrade
|
||||
|
||||
- For application-defined OpenRouter backends, set `provider: openrouter` to
|
||||
enable OpenRouter-specific usage and cost decoding and its authentication
|
||||
default. Backend IDs and endpoint hostnames do not select conventions.
|
||||
Generic backends retain their existing request and token conventions and
|
||||
do not decode monetary cost. Unsupported nonblank provider names are
|
||||
configuration errors; supplied names are trimmed and lowercased.
|
||||
- OpenRouter cache-write reporting now reads
|
||||
`usage.prompt_tokens_details.cache_write_tokens`, not the generic top-level
|
||||
`usage.cache_write_tokens` field. vLLM uses
|
||||
`usage.prompt_tokens_details.created_cache_tokens`. Missing or unusable new
|
||||
details remain unknown rather than invalidating otherwise usable content.
|
||||
Availability depends on the provider and server settings; consult the
|
||||
[response contract](../integrations/openai-compatible-chat.md#response-handling).
|
||||
- A supplied authentication object no longer requires `kind`: an omitted or
|
||||
null kind uses the provider default. Clearing the authentication block also
|
||||
restores that default. Set `kind: none` to declare authentication testing
|
||||
inapplicable. The generic provider has no authentication default; explicit
|
||||
adapters remain supported independently of provider selection. Probes still
|
||||
run only when explicitly requested. See the
|
||||
[backend reference](../formats.md#backend-definitions).
|
||||
- Cost includes all dispatched attempts, including transient retries and
|
||||
structural repairs, and is available on successful results without an
|
||||
observer. On operational failure, observations can retain cost even though
|
||||
no partial result is returned. Existing `RunResult.Usage` continues to sum
|
||||
successful generation responses; presence-aware observations cover all
|
||||
dispatched attempts. Do not add terminal totals to attempt totals.
|
||||
- Unknown cost is distinct from reported or configured zero. No backend is
|
||||
automatically declared zero-cost, and no token-rate estimation is performed.
|
||||
Group cost completeness describes included terminals, independently of
|
||||
terminal coverage. Consumers own presentation and interpretation; complete
|
||||
reporting does not verify billing.
|
||||
- Result JSON adds `cost_usd`, and token JSON adds `reasoning_tokens`.
|
||||
Update strict decoders if necessary. Older result JSON without cost decodes
|
||||
to unknown cost. Consumers using positional literals for expanded public
|
||||
structs may need to update them. See the [public types](../../types.go).
|
||||
|
||||
The Go consumer minimum remains 1.27.0; dependencies are unchanged from v0.24.0.
|
||||
|
||||
```sh
|
||||
go get go.maximumdirect.net/promptkit@v0.25.0
|
||||
```
|
||||
|
||||
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.25.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.25.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.25.0/docs/oss/attribution.md)
|
||||
Reference in New Issue
Block a user