# 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.