promptkit/docs/releases/v0.9.0.md

Promptkit v0.9.0

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

Summary

v0.9.0 adds stateless request-message composition and separates maintained provider data from Promptkit's core implementation:

• callers can append already-rendered messages to a configured prompt for application-owned conversations and semantic correction workflows;
• the public package now publishes constants for the four supported text-chat roles, and prompt definitions use the same normalized role vocabulary; and
• the OpenRouter and Rakestrawhome backend/profile catalogs now come from two independently versioned Go module dependencies.

Compatibility

This release adds one field and four constants to the public API and removes no public declarations. Existing keyed RunRequest literals that omit AppendedMessages retain their behavior. Adding the field changes the struct shape, so consumers using positional RunRequest literals must convert them to keyed literals.

Message roles in prompt definitions are now trimmed, lowercased, and required to be developer, system, user, or assistant. Definitions using another role that earlier releases accepted as an arbitrary nonblank string now fail prompt loading. In particular, the text-only message contract does not support tool or the deprecated function role. Otherwise valid roles with different case or surrounding whitespace are normalized rather than rejected.

The catalog extraction preserves Promptkit's public API, built-in backend and profile IDs, configuration, precedence, credential handling, and capacity behavior. Consumers do not import or register either catalog themselves, and no configuration migration is required. Promptkit now selects two independently versioned data dependencies and guarantees only the catalog versions selected and tested by this Promptkit release.

Upgrade

Update the module dependency with:

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

Convert any positional RunRequest literals to keyed literals. Review prompt definitions for unsupported roles, then run the consuming project's ordinary and race-enabled tests.

Appended Request Messages

RunRequest.AppendedMessages accepts caller-owned RenderedMessage values that Promptkit validates, copies, and appends after every rendered prompt-definition message in caller order. Promptkit does not template this content, retain conversation state between calls, impose a retry policy, or apply a message-count, byte-size, token, or context-window limit. Upstream rejections continue through the ordinary generation-error boundary.

This primitive supports application-owned conversation continuations and domain-aware correction loops while preserving Promptkit's existing preparation, hashing, prepared-execution, structural repair, backend-capacity, credential, and cancellation behavior. Appended content can include sensitive model output or application feedback; prepared values expose the complete effective messages by design, while default request formatting reports only the appended-message count.

See the consumer appended-message example, the RunRequest, RenderedMessage, and CacheControl GoDoc, and the OpenAI-compatible request contract for current behavior.

Supported Message Roles

The new RoleDeveloper, RoleSystem, RoleUser, and RoleAssistant constants identify the complete role vocabulary accepted by Promptkit's text-chat message model. The same validation and normalization now apply to prompt-definition messages and request-supplied appended messages. Promptkit does not translate between roles; provider- or model-specific rejection of an otherwise supported role remains an upstream generation error.

See the message format reference for the canonical prompt-definition contract.

Independently Versioned Backend Catalogs

Promptkit imports immutable catalog data for its maintained OpenRouter and Rakestrawhome backends and profiles. Engine construction validates and assembles both catalogs behind the existing built-in registry and profile precedence rules. Promptkit no longer keeps duplicate embedded profile assets or hard-coded definitions for those maintained backends.

The module versions in Promptkit's go.mod identify the catalog releases tested with this release. The built-in backend and profile format reference remains the canonical consumer contract, while the internal source documentation describes the dependency boundary.

Public API Changes

The release adds:

• RunRequest.AppendedMessages;
• RoleDeveloper;
• RoleSystem;
• RoleUser; and
• RoleAssistant.

No public declaration was removed.

Consumer Action

• Convert positional RunRequest literals to keyed literals.
• Replace unsupported prompt-definition roles with an appropriate supported role, or keep richer tool-call protocols in an application-owned client.
• Treat appended messages and prepared effective messages according to the application's sensitive-data policy.
• Do not add direct catalog imports or registration calls; existing Promptkit construction and configuration remain correct.
• Run consumer ordinary and race-enabled tests after updating the module.