promptkit/docs/releases/v0.8.0.md

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:

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, the consumer repair example, and the OutputContract and ValidationResult GoDoc 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 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.