From 5a1bff45297e68df2bd22df669df965c2c34df8a Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 30 Jul 2026 04:01:19 +0000 Subject: [PATCH] Prepare the local backend convenience release --- README.md | 3 ++ docs/consumers/pkg-promptkit.md | 2 +- docs/releases/v0.2.0.md | 2 +- docs/releases/v0.3.0.md | 74 +++++++++++++++++++++++++++++++++ docs/roadmap/concurrency.md | 3 +- public_contract_test.go | 15 +++++-- 6 files changed, 92 insertions(+), 7 deletions(-) create mode 100644 docs/releases/v0.3.0.md diff --git a/README.md b/README.md index fc1b83c..a17fffa 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,9 @@ boundary and constraints that framework work must preserve. ## Release Guidance +Consumers upgrading from `v0.2.0` to `v0.3.0` should read the +[v0.3.0 changelog](docs/releases/v0.3.0.md). + Consumers moving from `v0.1.0` to `v0.2.0` should read the [v0.2.0 changelog and migration guide](docs/releases/v0.2.0.md). diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index 4ae3045..7c9e318 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -124,7 +124,7 @@ providers. The [`RunRequest` and `ExecutionTargetOverride` GoDoc](../../types.go) owns the exact normalization, precedence, error, copying, and exposure contract. -### Register A Custom Backend +### Configure A Local OpenAI-Compatible Endpoint Choose the smallest configuration that fits how the endpoint will be reused. diff --git a/docs/releases/v0.2.0.md b/docs/releases/v0.2.0.md index 2d31144..5859037 100644 --- a/docs/releases/v0.2.0.md +++ b/docs/releases/v0.2.0.md @@ -90,7 +90,7 @@ engine, err := promptkit.NewEngine( ``` See the -[custom-backend consumer guide](../consumers/pkg-promptkit.md#register-a-custom-backend) +[local-endpoint consumer guide](../consumers/pkg-promptkit.md#configure-a-local-openai-compatible-endpoint) for task-oriented usage. The [`Backend` and `WithBackend` GoDoc](../../backends.go) owns exact registration, validation, copying, defaulting, and uniqueness semantics. The diff --git a/docs/releases/v0.3.0.md b/docs/releases/v0.3.0.md new file mode 100644 index 0000000..ba4cf27 --- /dev/null +++ b/docs/releases/v0.3.0.md @@ -0,0 +1,74 @@ +# Promptkit v0.3.0 + +This supplemental changelog summarizes the consumer-facing changes from +`v0.2.0` to `v0.3.0`. The annotated `v0.3.0` tag is the authoritative release +record. Exact current contracts belong to the linked GoDoc and durable +documentation. + +## Summary + +`v0.3.0` adds a concise way to register the common local OpenAI-compatible +backend configuration: + +- `BackendLocal` provides the conventional, non-reserved backend ID `"local"`; + and +- `LocalBackend` constructs an ordinary `Backend` from an endpoint and + concurrency limit. + +The helper is explicit and additive. It does not pre-register a backend, read +environment variables, select a model, or replace the complete `Backend` +configuration interface. + +## Compatibility + +Existing `v0.2.0` consumers require no migration. Endpoint-only profiles, +complete custom `Backend` values, the built-in OpenRouter backend, and existing +registrations using the literal ID `"local"` continue to work unchanged. + +## Upgrade + +Update the module dependency with: + +```sh +go get gitea.maximumdirect.net/eric/promptkit@v0.3.0 +go mod tidy +``` + +Run the consuming project's ordinary tests and race-enabled tests after the +upgrade. + +## Configure A Local Backend + +Register the convenience value through the existing `WithBackend` option and +select it from one or more profiles: + +```go +engine, err := promptkit.NewEngine( + promptkit.Config{PromptDir: "prompts"}, + promptkit.WithBackend( + promptkit.LocalBackend("http://localhost:8000/v1", 2), + ), + promptkit.WithProfiles(promptkit.Profile{ + ID: "local-summary", + BackendID: promptkit.BackendLocal, + Model: "example-model", + }), +) +``` + +Use an endpoint-only profile when shared backend identity and capacity policy +are unnecessary. Continue to use a complete keyed `Backend` value for custom +IDs, authentication, extra request parameters, explicit queue capacity, or +multiple local endpoints. + +See the +[local-endpoint consumer guide](../consumers/pkg-promptkit.md#configure-a-local-openai-compatible-endpoint) +for task-oriented configuration choices. The +[`BackendLocal`, `LocalBackend`, and `WithBackend` GoDoc](../../backends.go) +owns their exact construction, registration, validation, and concurrency +semantics. + +## Consumer Action + +None. Adopt the convenience constructor when it simplifies local endpoint +configuration. diff --git a/docs/roadmap/concurrency.md b/docs/roadmap/concurrency.md index 8eab68a..c6e9c33 100644 --- a/docs/roadmap/concurrency.md +++ b/docs/roadmap/concurrency.md @@ -11,7 +11,8 @@ consumer value, and important policy choices. This document is planning material, not a description of current behavior. Current exported contracts remain owned by Go declarations and GoDoc, backend registration guidance by the -[consumer guide](../consumers/pkg-promptkit.md#register-a-custom-backend), and +[consumer guide](../consumers/pkg-promptkit.md#configure-a-local-openai-compatible-endpoint), +and implemented orchestration by the [internal runner document](../internal/runner.md). diff --git a/public_contract_test.go b/public_contract_test.go index b58aeff..c4efeb8 100644 --- a/public_contract_test.go +++ b/public_contract_test.go @@ -140,11 +140,18 @@ func TestUnknownProfileBackendHasProfileLoadIdentity(t *testing.T) { } func TestLocalBackendConstructsAndRegistersConventionalBackend(t *testing.T) { - const limit = 2 + const ( + localBackendID = "local" + limit = 2 + ) + if promptkit.BackendLocal != localBackendID { + t.Fatalf("BackendLocal=%q, want %q", promptkit.BackendLocal, localBackendID) + } + endpoint := "http://local.example/v1" backend := promptkit.LocalBackend(endpoint, limit) want := promptkit.Backend{ - ID: promptkit.BackendLocal, + ID: localBackendID, Endpoint: endpoint, ConcurrencyLimit: limit, } @@ -157,7 +164,7 @@ func TestLocalBackendConstructsAndRegistersConventionalBackend(t *testing.T) { promptkit.WithBackend(backend), promptkit.WithProfiles(promptkit.Profile{ ID: "local-profile", - BackendID: promptkit.BackendLocal, + BackendID: localBackendID, Model: "model", }), ) @@ -169,7 +176,7 @@ func TestLocalBackendConstructsAndRegistersConventionalBackend(t *testing.T) { if err != nil { t.Fatalf("prepare with local backend: %v", err) } - if prepared.SelectedBackendID != promptkit.BackendLocal || + if prepared.SelectedBackendID != localBackendID || prepared.EffectiveModelParams.Endpoint != endpoint { t.Fatalf("unexpected local backend preparation: %+v", prepared) }