promptkit/docs/releases/v0.4.0.md

Promptkit v0.4.0

This supplemental changelog and adoption guide summarizes the consumer-facing changes from v0.3.0 to v0.4.0. The annotated v0.4.0 tag is the authoritative release record. Exact current contracts belong to the linked GoDoc and durable documentation.

Summary

v0.4.0 adds four complementary capabilities:

• opaque prepared-execution handles for preparing once, inspecting safe details, and executing the same frozen snapshot;
• exact prompt-definition inspection without profile resolution or execution;
• exact profile inspection without selecting a prompt or checking credential availability; and
• structured backend identity on engine admission-capacity rejection.

These APIs let consumers perform more precise preflight work and retain useful operational context without reproducing Promptkit's internal resolution logic.

Compatibility

The release is additive for v0.3.0 consumers. Existing uses of Prepare, Run, backend registration, endpoint-only profiles, local-backend helpers, runtime overrides, public JSON values, and error sentinels continue to work without migration.

Capacity rejection now returns a structured error while continuing to match ErrCapacityExceeded through errors.Is. Error-string wording and direct sentinel equality were not public contracts.

The new inspection values, capacity error, and prepared-execution handle do not have stable JSON representations. PreparedExecution.Details returns the existing stable PreparedRun value.

Upgrade

Update the module dependency with:

go get gitea.maximumdirect.net/eric/promptkit@v0.4.0
go mod tidy

Run the consuming project's ordinary and race-enabled tests after upgrading. No source migration is required.

Prepare Once And Execute The Same Snapshot

Consumers that need to persist preparation details before generation can now prepare an opaque, engine-bound execution:

prepared, err := engine.PrepareExecution(ctx, request)
if err != nil {
	// Handle preparation failure.
}
defer prepared.Discard()

details := prepared.Details()
// Persist a consumer-selected, appropriately protected preparation record.

result, err := engine.RunPrepared(ctx, prepared)

Preparation freezes the selected sources, rendered messages, effective settings, input content, structured-output metadata, and validation resources needed by execution. Details returns a fresh, caller-owned, credential-redacted PreparedRun.

A handle belongs to its creating engine and permits one execution attempt. RunPrepared consumes that attempt on success and on operational failure. Discard is idempotent and releases an unclaimed handle's execution-only state. Consumers should discard handles they will not execute, particularly when a direct request API key may be retained privately until claim or discard.

Prepared execution does not reserve backend admission during preparation. Credential availability and backend admission are checked when execution begins. The execution context is independent of the preparation context.

See the prepared-execution consumer guide, the PreparedExecution GoDoc, and the Engine.PrepareExecution and Engine.RunPrepared GoDoc for the exact lifecycle, ownership, cancellation, capacity, timing, and failure contracts.

Inspect A Prompt

Engine.InspectPrompt resolves one prompt ID and optional version through the engine's configured prompt source:

inspection, err := engine.InspectPrompt(ctx, "report.summary", "")

The result includes prompt identity, the opaque prompt hash, declared default profile ID, declared input metadata, and normalized output contract. It structurally loads the selected definition and referenced message content but does not resolve a profile, load schemas or artifacts, render templates, reserve capacity, or contact a model.

Use inspection for exact configuration checks and metadata discovery. Use PrepareExecution rather than relying on a prior inspection when later execution must freeze one exact source state, because filesystem-backed inspection is only a point-in-time lookup.

See the prompt-inspection consumer guide and Engine.InspectPrompt GoDoc for exact selection, ownership, and error behavior.

Inspect A Profile

Engine.InspectProfile resolves one explicit profile independently of a prompt:

inspection, err := engine.InspectProfile(ctx, "report-production")

The result includes the resolved effective execution target and whether a later request must provide a direct credential. Environment-variable names may be reported, but inspection does not read credential values or require the named variable to be populated.

Inspection applies the engine's profile source precedence and resolves any selected backend. It does not load a prompt, render content, reserve capacity, or contact a model.

See the profile-inspection consumer guide and Engine.InspectProfile GoDoc for the exact resolution, credential, ownership, and error contracts.

Identify Capacity-Rejected Backends

Calls rejected at Promptkit's bounded engine admission boundary continue to match ErrCapacityExceeded. Consumers can additionally obtain the selected registered backend ID without parsing diagnostic text:

result, err := engine.Run(ctx, request)
if errors.Is(err, promptkit.ErrCapacityExceeded) {
	var capacityErr *promptkit.CapacityError
	if errors.As(err, &capacityErr) {
		// Record capacityErr.BackendID using application-owned diagnostics.
	}

	// Apply application-owned overload or retry policy.
}

The structured error applies to Run and RunPrepared admission rejection. It does not represent provider throttling, quota exhaustion, cancellation while waiting for generation capacity, or another model-client failure. Promptkit does not prescribe retry timing or transport status mapping.

See the error-handling consumer guide, the CapacityError GoDoc, and the ErrCapacityExceeded GoDoc for the canonical contracts.

Public API Additions

The release adds:

• Engine.PrepareExecution;
• Engine.RunPrepared;
• PreparedExecution, including Details, Discard, String, and GoString;
• Engine.InspectPrompt;
• PromptInspection;
• PromptInputDefinition;
• Engine.InspectProfile;
• ProfileInspection; and
• CapacityError.

No public API was removed.

Consumer Action

None. Existing v0.3.0 workflows may upgrade without adopting the new APIs.

Consumers that adopt prepared execution should discard unused handles. Consumers that need backend-specific capacity diagnostics may add an errors.As check while retaining their existing errors.Is classification.