Prepare the v0.25.0 release documentation

This commit is contained in:
2026-11-22 19:08:29 +00:00
parent 20c5ea47af
commit 207677e994
4 changed files with 94 additions and 945 deletions

88
docs/releases/v0.25.0.md Normal file
View 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)