diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index fd65982..29443ec 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -189,6 +189,33 @@ For programmatic profiles, [`OpenAICompatibleProfile`](../../profiles.go) converts ordinary OpenAI-compatible settings into a value accepted by `WithProfiles`. +### Use The Rakestrawhome Built-In Profile + +Set `RAKESTRAWHOME_INFERENCE_API_KEY` in the application environment, then +select `rakestrawhome-gemma-4-31b` as an ordinary profile ID. For example, a +prepared result identifies the selected built-in through +`BackendRakestrawHome`: + +```go +prepared, err := engine.Prepare(ctx, promptkit.RunRequest{ + PromptID: "meeting.summary", + ProfileID: "rakestrawhome-gemma-4-31b", + Inputs: inputs, +}) +if err != nil { + return err +} +if prepared.SelectedBackendID != promptkit.BackendRakestrawHome { + return fmt.Errorf("unexpected backend %q", prepared.SelectedBackendID) +} +``` + +Do not register `rakestrawhome` manually. When adopting this built-in, remove +an existing `WithBackend` registration with that exact ID; retaining it causes +the intentional duplicate-ID configuration error. Direct request credentials +and runtime endpoint overrides remain supported under their ordinary GoDoc and +format contracts. + ### Inspect A Profile Before Prompt Work Use [`Engine.InspectProfile`](../../engine.go) to validate one configured diff --git a/docs/formats.md b/docs/formats.md index cfe4b5c..a2dc9d1 100644 --- a/docs/formats.md +++ b/docs/formats.md @@ -144,6 +144,17 @@ A request-level `OutputContract` replaces the complete prompt output contract. It does not merge individual fields. If its format is empty, Promptkit uses `text`. +## Built-In Backends + +Every engine provides these reserved OpenAI-compatible backend IDs. Consumers +must not register either ID with `WithBackend`; exact registration and +reservation behavior belongs to the [`Backend` GoDoc](../backends.go). + +| ID | Base endpoint | API-key environment variable | Active generation limit | Default queue capacity | +| --- | --- | --- | ---: | ---: | +| `openrouter` | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` | 16 | 1024 | +| `rakestrawhome` | `https://inference.ai.rakestrawhome.com/v1` | `RAKESTRAWHOME_INFERENCE_API_KEY` | 4 | 1024 | + ## Profile Definitions A profile supplies model execution settings: @@ -182,8 +193,8 @@ variable name in `api_key_env`. Promptkit does not infer a backend from a model or endpoint. Endpoint-only profiles remain supported and have no effective backend ID. -The engine always provides the built-in `openrouter` ID. Consumers can add -engine-scoped IDs with +The engine always provides the built-in `openrouter` and `rakestrawhome` IDs. +Consumers can add engine-scoped IDs with [`WithBackend`](../backends.go); exact registration validation belongs to its GoDoc. @@ -257,39 +268,38 @@ precedence. ## Built-In Profile Catalog -Every built-in selects the `openrouter` backend. The engine's built-in backend -registry supplies `https://openrouter.ai/api/v1` and the environment-variable -name `OPENROUTER_API_KEY`, so individual profiles contain only model and -generation settings. Built-in profile files do not repeat those connection -values. A configured, application fallback, or in-memory profile with the same -profile ID takes precedence. +Every built-in profile selects one maintained built-in backend and inherits +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. -| Provider | ID | Model | -| --- | --- | --- | -| aion-labs | `aion-2` | `aion-labs/aion-2.0` | -| anthropic | `claude-fable-latest` | `~anthropic/claude-fable-latest` | -| anthropic | `claude-haiku-latest` | `~anthropic/claude-haiku-latest` | -| anthropic | `claude-opus-latest` | `~anthropic/claude-opus-latest` | -| anthropic | `claude-sonnet-latest` | `~anthropic/claude-sonnet-latest` | -| deepseek | `deepseek-3-2` | `deepseek/deepseek-v3.2` | -| deepseek | `deepseek-4-flash` | `deepseek/deepseek-v4-flash` | -| deepseek | `deepseek-4-pro` | `deepseek/deepseek-v4-pro` | -| google | `gemini-2-flash` | `google/gemini-2.5-flash` | -| google | `gemini-2-flash-lite` | `google/gemini-2.5-flash-lite` | -| google | `gemini-2-pro` | `google/gemini-2.5-pro` | -| google | `gemini-3-flash-lite` | `google/gemini-3.1-flash-lite` | -| google | `gemini-flash-latest` | `~google/gemini-flash-latest` | -| google | `gemini-pro-latest` | `~google/gemini-pro-latest` | -| google | `gemma-4-31b` | `google/gemma-4-31b-it:exacto` | -| minimax | `minimax-m2` | `minimax/minimax-m2.5` | -| minimax | `minimax-m3` | `minimax/minimax-m3` | -| mistral | `mistral-large-2512` | `mistralai/mistral-large-2512` | -| mistral | `mistral-medium-3-5` | `mistralai/mistral-medium-3-5` | -| mistral | `mistral-small-3` | `mistralai/mistral-small-3.2-24b-instruct` | -| mistral | `mistral-small-4` | `mistralai/mistral-small-2603` | -| nvidia | `nemotron-3-ultra` | `nvidia/nemotron-3-ultra-550b-a55b` | -| openai | `gpt-5-mini` | `openai/gpt-5.4-mini` | -| openai | `gpt-5-nano` | `openai/gpt-5.4-nano` | +| 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` | ## Schemas diff --git a/docs/internal/overview.md b/docs/internal/overview.md index f9b1997..0e0bc05 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -14,7 +14,7 @@ contributor workflow and validation. | Root `promptkit` package | Provides the supported engine facade, source, backend-registration, and injection options, public request, result, prompt-inspection, and profile-inspection values, opaque prepared-execution handles, profile construction, extension interfaces, value conversion, redacted formatting, typed capacity errors, public error mapping, and engine-local profile-source assembly including application fallbacks. | [Package GoDoc](../../doc.go), [prepared execution](../../prepared_execution.go), [backend API](../../backends.go), [engine assembly](../../engine.go) | | `examples/go-library/prepare` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, and `Prepare`. It is not a public library package. | [Example program](../../examples/go-library/prepare/main.go) | | `examples/go-library/run` | Demonstrates an offline downstream consumer using a prompt file, in-memory profile, inline input, an injected deterministic model client, and `Run`. It is not a public library package. | [Example program](../../examples/go-library/run/main.go) | -| `internal/backend` | Constructs each engine's immutable registry from the built-in OpenRouter definition and consumer additions, validates and defensively copies definitions through the shared JSON-value package, and consumes the LLM-owned OpenAI-compatible reserved request-field rule. | [Backend registry](../../internal/backend/registry.go) | +| `internal/backend` | Constructs each engine's immutable registry from the maintained built-in definitions and consumer additions, validates and defensively copies definitions through the shared JSON-value package, and consumes the LLM-owned OpenAI-compatible reserved request-field rule. | [Backend registry](../../internal/backend/registry.go) | | `internal/capacity` | Owns engine-local bounded execution admission and FIFO model-generation permits for limited backend IDs, including cancellation-safe waiter removal and client wrapping. | [Internal capacity management](capacity.md) | | `internal/domain` | Defines internal framework values for requests, artifacts, prompt definitions, profiles, execution targets, rendering, generation, and validation, and owns source-neutral invariants for shared execution settings, OpenAI-compatible base endpoints, session identifiers, and output contracts. Source parsing, required fields, other source-specific normalization, defaulting, and boundary-specific error classification remain with their callers. | [Domain declarations](../../internal/domain/domain.go), [endpoint invariant](../../internal/domain/endpoint.go) | | `internal/defaults` | Defines application-neutral framework constants and constructs the default execution target. It contains no CLI, server, or inbound HTTP limits. | [Framework defaults](../../internal/defaults/defaults.go) | @@ -22,7 +22,7 @@ contributor workflow and validation. | `internal/jsonvalue` | Validates and deeply copies bounded JSON-compatible extra-parameter and prepared-schema trees while preserving supported concrete value types and rejecting cycles or excessive depth and work. | [JSON values](../../internal/jsonvalue/jsonvalue.go) | | `internal/promptdef` | Loads strictly decoded, validated prompt definitions from filesystem and `fs.FS` sources, including version selection and contained file-backed message content. | [Framework formats](../formats.md), [prompt-definition repository](../../internal/promptdef/filesystem_repository.go) | | `internal/profile` | Loads strictly decoded, validated execution profiles, including backend selection, from filesystem and `fs.FS` sources and composes repositories with error-preserving fallback. | [Framework formats](../formats.md), [profile repositories](../../internal/profile/filesystem_repository.go) | -| `internal/profile/builtin` | Embeds the built-in profile catalog, whose entries select OpenRouter. | [Built-in catalog](../formats.md#built-in-profile-catalog), [repository](../../internal/profile/builtin/repository.go) | +| `internal/profile/builtin` | Embeds the built-in profile catalog, whose entries select maintained built-in backends. | [Built-in catalog](../formats.md#built-in-profile-catalog), [repository](../../internal/profile/builtin/repository.go) | | `internal/prompt` | Renders prompt messages from Go templates with artifact, variable, session, and cache-control data. | [Go-template renderer](../../internal/prompt/go_renderer.go) | | `internal/artifact` | Resolves ordinary inline and unrestricted caller-selected file references into copied artifacts with metadata and hashes. | [Internal sources and validation](sources.md) | | `internal/validate` | Validates basic, JSON, and JSON Schema output using operating-system filesystem or `fs.FS` schema sources and creates operation-local validation plans with canonical contained schema resources. | [Framework formats](../formats.md#schemas), [internal sources and validation](sources.md) | diff --git a/docs/internal/sources.md b/docs/internal/sources.md index 075da2c..60952da 100644 --- a/docs/internal/sources.md +++ b/docs/internal/sources.md @@ -69,12 +69,13 @@ profile sources and checks the resolved target without reading prompt, input, or schema sources. It does not retain that lookup for a later execution. `internal/profile/builtin` embeds the maintained built-in profile catalog. -Every embedded profile selects `openrouter` and inherits its endpoint and -credential environment-variable name from the built-in backend registry rather -than repeating those values. Profile loading and overlay behavior are owned by -the [profile repository tests](../../internal/profile/repository_test.go), -while catalog completeness, the backend-selection invariant, and duplicate IDs -are owned by the +Every embedded profile selects a maintained built-in backend and inherits that +backend's endpoint and credential environment-variable name from the built-in +backend registry rather than repeating those values. Profile loading and +overlay behavior are owned by the +[profile repository tests](../../internal/profile/repository_test.go), while +catalog completeness, the backend-selection invariant, and duplicate IDs are +owned by the [built-in repository tests](../../internal/profile/builtin/repository_test.go). ## Ordinary Artifacts diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 9774d6e..2760e3b 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -22,7 +22,7 @@ The implemented internal components consist of: - `internal/domain`, which owns framework data values and source-neutral invariants shared by later internal components; - `internal/backend`, which owns validated immutable OpenAI-compatible backend - definitions and the built-in OpenRouter definition; + definitions and the maintained built-in definitions; - `internal/capacity`, which owns engine-local bounded run admission and model-generation scheduling for limited backends; - `internal/defaults`, which owns application-neutral framework defaults and diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 1034d7b..225c7ab 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -270,6 +270,8 @@ following: test, or hidden generation default was introduced; and - current-state documentation and GoDoc agree with the implemented behavior. +**Status:** Complete. + ## Open Questions None. The feature roadmap and this plan fix every implementation-relevant