110 lines
4.8 KiB
Markdown
110 lines
4.8 KiB
Markdown
# Promptkit v0.8.0
|
|
|
|
This supplemental changelog and migration guide summarizes the consumer-facing
|
|
changes from `v0.7.0` to `v0.8.0`. The annotated `v0.8.0` tag is the
|
|
authoritative release record. Exact current contracts belong to the linked
|
|
GoDoc and durable documentation.
|
|
|
|
## Summary
|
|
|
|
`v0.8.0` activates Promptkit's bounded output-repair workflow:
|
|
|
|
- failed nonempty-text, JSON, and JSON Schema validation can make a limited
|
|
number of corrective model calls;
|
|
- corrective calls preserve the original rendered conversation, effective
|
|
target, session, structured-output contract, and backend capacity policy;
|
|
- results report cumulative usage and the number of corrective calls actually
|
|
made; and
|
|
- explicitly empty OpenAI-compatible response content now reaches output
|
|
validation instead of being classified as a malformed provider envelope.
|
|
|
|
## Compatibility
|
|
|
|
This release adds no public declarations or fields and removes none. Existing
|
|
source code remains source-compatible.
|
|
|
|
The behavior of the existing `OutputContract.RepairAttempts` field and prompt
|
|
YAML `repair_attempts` field has changed. A positive value now authorizes real
|
|
additional model calls after eligible validation failures; earlier releases
|
|
accepted the field but the public engine remained single-pass. Consumers that
|
|
set a positive value should expect additional latency, token usage, and
|
|
provider cost when repair is needed.
|
|
|
|
Repair budgets must now be between zero and three. A positive budget requires
|
|
`basic`, `json`, or `json_schema` validation. Values above three and a positive
|
|
budget paired with `none` are invalid contracts rather than ignored settings.
|
|
|
|
An explicitly present empty or whitespace-only string returned by the built-in
|
|
OpenAI-compatible client is now a completed generation candidate. `none`
|
|
validation permits it, while `basic`, `json`, and `json_schema` classify it
|
|
under their ordinary validation rules and may repair it when configured.
|
|
Missing, `null`, or non-string content remains a malformed provider response.
|
|
|
|
## Upgrade
|
|
|
|
Update the module dependency with:
|
|
|
|
```sh
|
|
go get gitea.maximumdirect.net/eric/promptkit@v0.8.0
|
|
go mod tidy
|
|
```
|
|
|
|
Review every prompt definition and request override that sets a positive repair
|
|
budget. Use zero or omit the field to retain single-pass execution. Ensure each
|
|
positive budget is no greater than three and uses an eligible validation mode,
|
|
then run the consuming project's ordinary and race-enabled tests.
|
|
|
|
## Bounded Output Repair
|
|
|
|
`repair_attempts` counts corrective calls in addition to the initial model
|
|
call. Promptkit validates each completed candidate, stops at the first valid
|
|
one, and never exceeds the configured bound. If every candidate remains
|
|
invalid, the run completes successfully with the final candidate and its
|
|
failed validation result rather than returning an operational error.
|
|
|
|
Each correction starts from the original rendered messages and includes only
|
|
the latest invalid candidate and latest validation diagnostics. JSON Schema
|
|
mode retains the provider-native structured-output request as its first line of
|
|
defense. Promptkit performs only deterministic structural validation; a valid
|
|
response is not necessarily factual or correct for an application's domain.
|
|
|
|
Usage in the final result is cumulative across the initial response and every
|
|
completed corrective response. `ValidationResult.RepairAttempts` reports the
|
|
number of corrective calls actually made. Corrective generation failures use
|
|
the same public generation-error categories and structured provider details as
|
|
an initial generation failure.
|
|
|
|
See the [output-contract format reference](../formats.md#output-contract), the
|
|
[consumer repair example](../consumers/pkg-promptkit.md#repair-a-structured-result),
|
|
and the [`OutputContract` and `ValidationResult` GoDoc](../../types.go) for the
|
|
current contracts.
|
|
|
|
## Explicit Empty Content
|
|
|
|
The built-in OpenAI-compatible client now distinguishes an explicitly present
|
|
empty string from a missing or malformed `content` field. This aligns built-in
|
|
and injected clients by letting the selected output contract decide whether an
|
|
empty candidate is acceptable, invalid, or eligible for repair.
|
|
|
|
See the
|
|
[OpenAI-compatible response contract](../integrations/openai-compatible-chat.md#response-handling)
|
|
for the exact envelope behavior.
|
|
|
|
## Public API Changes
|
|
|
|
None. This release activates and tightens the documented behavior of existing
|
|
fields.
|
|
|
|
## Consumer Action
|
|
|
|
- Remove or set `repair_attempts` to zero where execution must remain
|
|
single-pass.
|
|
- Keep every positive repair budget at three or fewer and pair it with
|
|
`basic`, `json`, or `json_schema` validation.
|
|
- Account for additional latency, usage, and provider cost when enabling
|
|
repair.
|
|
- Continue checking the returned validation status because bounded repair can
|
|
exhaust without producing a valid candidate.
|
|
- Review workflows that previously treated explicit empty provider content as
|
|
a generation error.
|