From 6ce54c1d7936d9b6f385ef37e54ec55ebc780d80 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 22 Sep 2026 12:31:50 +0000 Subject: [PATCH] Document catalog profile compatibility --- README.md | 3 +++ docs/consumers/pkg-promptkit.md | 27 +++++++++++++++++++- docs/development.md | 2 +- docs/formats.md | 45 ++++++++++++--------------------- docs/policy/architecture.md | 13 +++++----- docs/release.md | 37 +++++++++++++++++++++++---- docs/releases/v0.10.0.md | 33 ++++++++++++++++++++++++ docs/roadmap/implementation.md | 2 ++ 8 files changed, 120 insertions(+), 42 deletions(-) create mode 100644 docs/releases/v0.10.0.md diff --git a/README.md b/README.md index 7b2d1e1..c3c5271 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,9 @@ boundary and constraints that framework work must preserve. ## Release Guidance +Consumers preparing for the unreleased `v0.10.0` profile-policy transition +should read the [v0.10.0 transition guide](docs/releases/v0.10.0.md). + Consumers upgrading from `v0.8.0` to `v0.9.0` should read the [v0.9.0 changelog and migration guide](docs/releases/v0.9.0.md). diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index 2a298c2..a13219f 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -232,6 +232,29 @@ For programmatic profiles, [`OpenAICompatibleProfile`](../../profiles.go) converts ordinary OpenAI-compatible settings into a value accepted by `WithProfiles`. +### Choose A Profile Ownership Model + +Choose the profile source that matches the application's continuity needs: + +- Select `promptkit-openrouter-standard` or `promptkit-openrouter-auto` when + the maintained literal name is the desired consumer contract. Their current + selections are in the [format reference](../formats.md#built-in-profile-catalog). +- Select an external catalog profile directly when the application accepts that + profile's catalog volatility. The selected external inventories are linked + from the [format reference](../formats.md#external-profile-inventories). +- Define a complete application-owned profile with an explicit backend or + endpoint, model, and settings when the application owns those choices. + +An application profile that inherits an external base follows later changes to +that base and fails if the base disappears; it is not a frozen copy. Promptkit +tests the catalog versions selected in its module graph. Independently advancing +a catalog dependency can remove an inherited base and produce an untested +combination. Pinning the resolved module graph preserves the embedded data for +a build, but cannot preserve provider availability. Running binaries neither +download catalog updates nor automatically replace withdrawn models. See the +[release policy](../release.md#catalog-profile-compatibility) for the exact +cross-version guarantees. + ### Alias A Built-In Profile Give an application-owned profile ID a built-in base when prompts should select @@ -250,7 +273,9 @@ Select `weather-light` in a prompt or `RunRequest.ProfileID`; it remains the reported selected profile. See the [profile inheritance format reference](../formats.md#profile-inheritance) and the [`Profile` GoDoc](../../types.go) for exact lookup, merging, and validation -behavior. +behavior. If the base is an external profile, apply the volatility guidance +above when deciding whether to use an application-owned complete definition +instead. ### Use The Rakestrawhome Built-In Profile diff --git a/docs/development.md b/docs/development.md index 249c002..ff60124 100644 --- a/docs/development.md +++ b/docs/development.md @@ -34,7 +34,7 @@ Start with: | Root public API | The [architecture policy](policy/architecture.md), [consumer guide](consumers/pkg-promptkit.md), [testing policy](policy/testing.md), and existing GoDoc. | | Prompt, profile, or schema formats | The [framework format reference](formats.md), owning parser or validator package, and [documentation policy](policy/documentation.md). | | Source loading or validation | The [framework format reference](formats.md), [internal source document](internal/sources.md), and owning package tests. | -| Maintained external catalogs or built-ins | The [internal source document](internal/sources.md), [framework format reference](formats.md), [testing policy](policy/testing.md), both catalog module repositories, and each catalog's release procedure. | +| Maintained external catalogs or built-ins | The [internal source document](internal/sources.md), [framework format reference](formats.md), [testing policy](policy/testing.md), both catalog module repositories, each catalog's release procedure, and the selected module versions in `go.mod`. | | Model-client behavior | The [OpenAI-compatible integration contract](integrations/openai-compatible-chat.md), [internal model-client document](internal/llm.md), and owning package tests. | | Internal package implementation | The [architecture policy](policy/architecture.md), [internal component overview](internal/overview.md), and focused internal document listed for that package. | | Tests or test fixtures | The [testing policy](policy/testing.md), owning package, and focused internal document listed by the component overview. | diff --git a/docs/formats.md b/docs/formats.md index a371303..160852c 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -327,7 +327,7 @@ that backend's connection and credential metadata. Profile files do not repeat those values. A configured, application fallback, or in-memory profile with the same profile ID takes precedence. -Promptkit owns two opt-in profiles. Their following definitions are current +Promptkit owns two opt-in profiles. The following definitions are current selections, not automatic defaults: | ID | Current definition | @@ -337,35 +337,22 @@ selections, not automatic defaults: Select either name through an existing request `profile_id` or prompt `default_profile`. Consumers can replace either definition or its inherited -base through the ordinary profile-source precedence above. +base through the ordinary profile-source precedence above. The +[release policy](release.md#catalog-profile-compatibility) defines the +cross-version guarantee for these names. -| Provider | ID | Backend | Model | -| --- | --- | --- | --- | -| aion-labs | `aion-2` | `openrouter` | `aion-labs/aion-2.0` | -| anthropic | `claude-fable-latest` | `openrouter` | `~anthropic/claude-fable-latest` | -| anthropic | `claude-haiku-latest` | `openrouter` | `~anthropic/claude-haiku-latest` | -| anthropic | `claude-opus-latest` | `openrouter` | `~anthropic/claude-opus-latest` | -| anthropic | `claude-sonnet-latest` | `openrouter` | `~anthropic/claude-sonnet-latest` | -| deepseek | `deepseek-3-2` | `openrouter` | `deepseek/deepseek-v3.2` | -| deepseek | `deepseek-4-flash` | `openrouter` | `deepseek/deepseek-v4-flash` | -| deepseek | `deepseek-4-pro` | `openrouter` | `deepseek/deepseek-v4-pro` | -| google | `gemini-2-flash` | `openrouter` | `google/gemini-2.5-flash` | -| google | `gemini-2-flash-lite` | `openrouter` | `google/gemini-2.5-flash-lite` | -| google | `gemini-2-pro` | `openrouter` | `google/gemini-2.5-pro` | -| google | `gemini-3-flash-lite` | `openrouter` | `google/gemini-3.1-flash-lite` | -| google | `gemini-flash-latest` | `openrouter` | `~google/gemini-flash-latest` | -| google | `gemini-pro-latest` | `openrouter` | `~google/gemini-pro-latest` | -| google | `gemma-4-31b` | `openrouter` | `google/gemma-4-31b-it:exacto` | -| google | `rakestrawhome-gemma-4-31b` | `rakestrawhome` | `google/gemma-4-31b-it` | -| minimax | `minimax-m2` | `openrouter` | `minimax/minimax-m2.5` | -| minimax | `minimax-m3` | `openrouter` | `minimax/minimax-m3` | -| mistral | `mistral-large-2512` | `openrouter` | `mistralai/mistral-large-2512` | -| mistral | `mistral-medium-3-5` | `openrouter` | `mistralai/mistral-medium-3-5` | -| mistral | `mistral-small-3` | `openrouter` | `mistralai/mistral-small-3.2-24b-instruct` | -| mistral | `mistral-small-4` | `openrouter` | `mistralai/mistral-small-2603` | -| nvidia | `nemotron-3-ultra` | `openrouter` | `nvidia/nemotron-3-ultra-550b-a55b` | -| openai | `gpt-5-mini` | `openrouter` | `openai/gpt-5.4-mini` | -| openai | `gpt-5-nano` | `openrouter` | `openai/gpt-5.4-nano` | +## External Profile Inventories + +The external profile inventory is defined by the selected catalog modules, not +duplicated here. Browse the exact data selected by this Promptkit version: + +- [OpenRouter catalog v2.20260922.0 profiles](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/tag/v2.20260922.0/catalog/profiles) +- [Rakestrawhome catalog v2.20260922.0 profiles](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/tag/v2.20260922.0/catalog/profiles) + +External profile entries are volatile across catalog releases. The +[release policy](release.md#catalog-profile-compatibility) owns the precise +compatibility boundary; a selected module version identifies tested local data, +not live provider availability. ## Schemas diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 8cbe859..72618fb 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -30,7 +30,8 @@ The implemented internal components consist of: - `internal/filecatalog`, which discovers YAML files and provides source-path helpers for filesystem and `fs.FS` consumers; - `internal/catalog`, which validates immutable external maintained-catalog - assets before they are eligible for engine assembly; + assets and their reserved profile namespace before they are eligible for + engine assembly; - `internal/jsonvalue`, which validates and defensively copies JSON-compatible extra-parameter trees; - `internal/promptdef`, which loads and validates prompt definitions from @@ -63,11 +64,11 @@ policy snapshot, wraps the selected built-in or injected model client, and supplies bounded admission to the runner. The defaults and renderer depend on the domain model. Prompt-definition and profile repositories use the domain model, file catalog, and YAML decoder. The catalog adapter validates imported -immutable maintained data before internal engine assembly supplies it to the profile -package. Artifact reading uses the domain -model and application-neutral defaults. Validation uses the domain model, file -catalog, and JSON Schema implementation. The model client uses the domain -model, application-neutral defaults, and an injected or standard-library HTTP +immutable maintained data, including its reserved namespace, before internal +engine assembly supplies it to the profile package. Artifact reading uses the +domain model and application-neutral defaults. Validation uses the domain model, +file catalog, and JSON Schema implementation. The model client uses the domain +model and application-neutral defaults, and an injected or standard-library HTTP client. The use-case runner depends on the narrow interfaces owned by each internal component, including backend lookup and run admission. diff --git a/docs/release.md b/docs/release.md index 5e6bb84..910508f 100644 --- a/docs/release.md +++ b/docs/release.md @@ -16,6 +16,32 @@ changes, and state any action required of consumers. Promptkit releases are source-only. The annotated tag message is the release note; there is no separate hosted release or binary packaging step. +## Catalog Profile Compatibility + +External catalog profile data may be added, removed, renamed, or modified +without deprecation or advance notice. This exception is limited to profile +data imported from the maintained catalog modules. It does not weaken ordinary +compatibility for Promptkit's public Go API, configuration and format semantics, +runtime behavior, catalog-module APIs, manifest schema, backend definitions, or +consumer-owned definitions. + +Within the catalog versions selected and tested by a Promptkit release, and +unless a consumer overrides the name or its base, Promptkit keeps the literal +profile IDs `promptkit-openrouter-standard` and +`promptkit-openrouter-auto` available. The names do not promise a permanent +model, backend, routing behavior, settings, cost, output, or upstream +availability. The [framework format reference](formats.md#built-in-profile-catalog) +owns their current definitions. + +`v0.10.0` is the initial minor release for this compatibility transition. +Afterward, catalog-only updates and adjustments to the current selections may +ship in a patch release when all other compatibility obligations remain intact. +External profile removals can require consumer action; they are not automatic +migrations. + +Catalog adoption and release validation remain local and offline. They do not +probe provider endpoints, request model lists, or make inference calls. + ## Establish The Candidate Choose a version that has not been published and export it as @@ -147,11 +173,12 @@ Inspect the complete message and confirm that it accurately records the compatibility impact, public API changes, and required consumer action. When a release introduces or updates the maintained external catalogs, state -that it selects two independently versioned data dependencies, preserves the -public API and configuration, requires no consumer migration, and guarantees -only the catalog versions selected and tested by that Promptkit release. Link -to the current architecture and format documentation rather than duplicating -catalog contracts in the release note. +the two independently versioned selected data dependencies and any resulting +consumer action. State that external profile additions, removals, renames, and +selection changes are covered by the catalog-profile policy, while the ordinary +public API and configuration contracts remain in force. Link to the current +format and consumer documentation rather than duplicating catalog inventories +or contracts in the release note. ## Create And Inspect The Tag diff --git a/docs/releases/v0.10.0.md b/docs/releases/v0.10.0.md new file mode 100644 index 0000000..532e5ad --- /dev/null +++ b/docs/releases/v0.10.0.md @@ -0,0 +1,33 @@ +# Promptkit v0.10.0 (Unreleased) + +This supplemental transition guide describes the planned `v0.10.0` catalog +profile-policy change. It is not a release record and does not claim that the +version has been published. The annotated tag, when created, remains the +authoritative release record. + +## Transition Summary + +`v0.10.0` adopts independently versioned OpenRouter and Rakestrawhome catalog +modules whose external profile data can change between catalog releases. It +also introduces the maintained literal names +`promptkit-openrouter-standard` and `promptkit-openrouter-auto`. + +The maintained names provide continuity only within the catalog versions +selected and tested by a Promptkit release and when consumers do not override +the name or its base. Their current selections may change. External catalog +profile IDs can be removed, renamed, or modified, so an application that +selects one directly may need to update its configuration when upgrading. + +## Consumer Migration + +Before upgrading, review every profile ID used by prompts, requests, and +application-owned inheritance. Choose a maintained name, accept an external +catalog profile's volatility, or define a complete application-owned profile +when the application must control its target and settings. An alias that +inherits from an external base is not a frozen copy. + +See the [release policy](../release.md#catalog-profile-compatibility) for the +compatibility boundary, the [format reference](../formats.md#built-in-profile-catalog) +for current Promptkit-owned definitions and selected external inventories, and +the [consumer guide](../consumers/pkg-promptkit.md#choose-a-profile-ownership-model) +for configuration choices. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 9f5bcc1..4e1223c 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -217,6 +217,8 @@ external inventory across releases. ## Stage 6: Publish Durable Policy And Consumer Guidance +**Completed:** 2026-09-22 + 1. Update `docs/release.md`, the release-policy owner: narrow external-profile exception, two-name continuity scope, initial minor transition, and later patch eligibility. Replace its blanket catalog-update instruction to claim