promptkit/docs/roadmap/implementation.md

Rakestrawhome Built-In Backend Implementation Plan

Purpose

Implement the target state defined in the Rakestrawhome built-in backend roadmap: make the maintainer's OpenAI-compatible inference service a reserved built-in backend, publish its first built-in model profile, and document the resulting consumer surface.

This is an execution plan, not an additional source of feature policy. When a detail in this plan requires interpretation, preserve the decisions and scope boundaries in the feature roadmap and the ownership rules under docs/policy/.

Fixed Decisions

• The internal and wire-facing backend ID is rakestrawhome; its exported root constant is BackendRakestrawHome.
• Its base endpoint is https://inference.ai.rakestrawhome.com/v1. The existing OpenAI-compatible client composes the final request URL as https://inference.ai.rakestrawhome.com/v1/chat/completions.
• Its API-key environment variable is RAKESTRAWHOME_INFERENCE_API_KEY.
• Each engine permits four active generation calls for this backend. The existing default bounded waiting capacity of 1024 applies.
• The embedded profile ID is rakestrawhome-gemma-4-31b, its backend is rakestrawhome, and its model is google/gemma-4-31b-it.
• The new profile contains no optional generation settings. The existing OpenRouter gemma-4-31b profile remains unchanged.
• Built-in registration is inert: engine construction does not read a credential or contact the service. Existing selection-time credential, endpoint-override, profile-precedence, and error behavior remains in force.
• Consumer backend additions cannot replace either built-in ID. Consumer profile sources may continue to override an embedded profile by profile ID.
• Verification is deterministic and offline. Do not add a live service test, provider-specific client, duplicate concurrency stress matrix, or duplicate endpoint-composition matrix.

Execution Rules

• Implement the stages in numerical order. Treat each stage as one bounded coding-agent prompt, and complete its focused and regression verification before beginning the next stage.
• At the start of each stage, review the feature roadmap and the policy files relevant to that stage. Follow the task-specific reading guide in docs/development.md.
• Preserve unrelated working-tree changes. Do not commit, tag, push, or modify release documentation unless a separate instruction authorizes it.
• Keep tests at their narrowest owner. Extend existing tests where they already own the contract instead of creating parallel test matrices.
• Update current-state documentation only in Stage 3, after the implemented behavior exists.

Stage 1: Generalize Built-In Backend Registration

Objective

Add the exact Rakestrawhome definition to the immutable backend registry and expose its reserved ID through the public facade without changing the generic backend, capacity, or client mechanisms.

Implementation

1. In internal/backend/registry.go, add the stable exported internal ID RakestrawHomeID = "rakestrawhome" and private constants for:
   • endpoint https://inference.ai.rakestrawhome.com/v1;
   • API-key environment variable RAKESTRAWHOME_INFERENCE_API_KEY; and
   • concurrency limit 4.
2. Replace the inline OpenRouter construction in NewRegistry with a private builtInBackends() []domain.Backend factory that returns fresh definitions for OpenRouter and Rakestrawhome on every call. Do not use a mutable package- level slice or map. The Rakestrawhome definition must leave QueueCapacitySet false so the existing normalization path assigns the shared default queue capacity of 1024.
3. Have NewRegistry allocate from len(builtIns) + len(additions), process built-ins before consumer additions, and pass every definition through the existing normalizeBackend and duplicate-ID logic. Preserve defensive-copy behavior and all validation and error contracts.
4. In the root backends.go, expose BackendRakestrawHome = backend.RakestrawHomeID. Update the Backend and WithBackend GoDoc so their reservation language applies to all built-ins, not only OpenRouter. Do not expose endpoint, credential, or capacity constants in the root package.
5. Make no changes to NewEngine, the capacity manager, or the OpenAI- compatible client. They must consume the new definition through their existing registry and policy interfaces.

Tests

1. In internal/backend/registry_test.go, generalize the exact built-in test to assert both definitions. For Rakestrawhome, assert the exact ID, base endpoint, API-key environment-variable name, concurrency limit 4, normalized queue capacity 1024, QueueCapacitySet == true, and absence of extra parameters. Preserve the corresponding exact OpenRouter assertions.
2. Assert that CapacityPolicies contains exactly both built-in policies in a registry with no additions, including the exact concurrency and queue values. Retain lookup-isolation coverage rather than exposing registry- owned data to mutation.
3. Update addition-related expected counts to include two built-ins. Ensure the custom-addition mutation test still proves registry isolation and does not accidentally replace either built-in.
4. Table-drive the existing built-in collision coverage over whitespace- normalized openrouter and rakestrawhome additions. Each must return the existing duplicate-ID configuration error.
5. At the root public-contract owner, extend the existing reserved-backend registration test to cover both BackendOpenRouter and BackendRakestrawHome. Do not duplicate the internal registry's full validation matrix.

Verification

Run the focused backend and root tests first, then the ordinary regression suite:

go test ./internal/backend
go test .
go test ./...

The stage is complete when both exact built-ins are published through the same immutable registry path, both IDs are reserved, and existing custom-backend and OpenRouter behavior remains green.

Stage 2: Add the Built-In Profile and Prove Assembly

Objective

Embed the minimal Gemma profile, generalize built-in catalog assumptions from one backend to the maintained built-in set, and prove ordinary engine assembly without adding provider-specific execution logic.

Implementation

1. Add internal/profile/builtin/assets/google/rakestrawhome-gemma-4-31b.yml with exactly these semantic fields and no optional settings:

   id: rakestrawhome-gemma-4-31b
   backend: rakestrawhome
   model: google/gemma-4-31b-it
   

   Keep the asset under google because the existing directory hierarchy groups profiles by model provider; the profile ID and backend field carry the inference-backend distinction.

2. Do not change the embedded repository implementation: its existing recursive assets/**/*.yml pattern must discover the new asset. Do not alter internal/profile/builtin/assets/google/gemma-4-31b.yml.

3. In the built-in repository tests, replace the assumption that every asset selects OpenRouter with an explicit allowed built-in set containing backend.OpenRouterID and backend.RakestrawHomeID. Continue to reject a blank or duplicate profile ID, an unapproved backend ID, raw api_key, endpoint, or api_key_env fields, and any asset that fails ordinary repository parsing and validation.

4. Add a focused assertion that loading rakestrawhome-gemma-4-31b returns the exact backend and model and leaves every optional generation setting, timeout, service tier, endpoint, credential field, and extra-parameter map absent or at its zero value. This protects the deliberate native-default policy rather than merely proving that the YAML parses.

5. Generalize the existing root test that prepares a built-in profile without a profile directory into a small table covering its current OpenRouter case and the new Rakestrawhome case. Supply a synthetic credential with t.Setenv; call preparation only; and assert the selected profile ID, backend ID, base endpoint, credential environment-variable name, and model. Capacity policy has no public inspection seam and is intentionally covered by the registry and existing generic capacity-contract owners instead.

Test Boundaries

• Rely on the registry test for the literal Rakestrawhome capacity values and on the existing generic capacity-contract tests for semaphore and queue behavior. Do not add another four-way goroutine test.
• Rely on the exact registered base endpoint plus the existing generic client endpoint-composition test. Do not make a live request or add a second copy of the transport matrix.
• Preserve existing profile-source precedence tests. The new asset uses the same repository and resolution path, so do not duplicate the complete precedence matrix.

Verification

Run the focused catalog and root tests, then the ordinary regression suite:

go test ./internal/profile/builtin
go test .
go test ./...

The stage is complete when the new ID resolves through the embedded catalog and ordinary engine assembly, contains no unintended request defaults, and does not alter the existing OpenRouter Gemma profile.

Stage 3: Update Canonical Documentation and Complete Validation

Objective

Bring each canonical documentation owner into line with the implemented public and internal state, give manual registrants an explicit migration path, and run the complete maintainer workflow.

Documentation

1. Update docs/policy/architecture.md and docs/internal/overview.md so the backend registry is described as owning multiple maintained built-ins rather than a single inline OpenRouter definition. Keep architectural policy at the ownership level; do not turn it into a catalog of duplicated literal values.
2. Update docs/internal/sources.md to remove the assertion that every built-in profile selects OpenRouter. Explain that embedded profiles inherit connection and credential metadata from whichever maintained built-in backend they select.
3. Update docs/formats.md as the canonical owner of backend definitions and the embedded profile catalog:
   • list OpenRouter and Rakestrawhome with their exact stable IDs, endpoints, API-key environment variables, concurrency limits, and default queue capacity;
   • add a Backend column to the built-in profile table so a mixed-backend catalog is unambiguous; and
   • add rakestrawhome-gemma-4-31b with backend rakestrawhome and model google/gemma-4-31b-it, while preserving every existing catalog row.
4. Update docs/consumers/pkg-promptkit.md with the shortest supported use of the built-in profile and BackendRakestrawHome. State that consumers set RAKESTRAWHOME_INFERENCE_API_KEY, do not register the built-in manually, and must remove an existing WithBackend registration under the exact rakestrawhome ID to avoid the intentional duplicate-ID error. Preserve the documented direct credential and runtime endpoint overrides.
5. Ensure root GoDoc added in Stage 1 documents the exported constant and the plural built-in reservation rule. Leave docs/integrations/openai-compatible-chat.md as the canonical owner of generic endpoint composition and wire behavior; change it only if it contains an inaccurate single-built-in statement. Do not duplicate its transport details in consumer guidance.
6. Do not add release notes in this feature pass. Release documentation and tagging are separate maintainer actions.

Final Verification

Run the complete offline workflow in docs/development.md#maintainer-validation, including:

go test ./...
go test -race ./...
go vet ./...
go build ./...
go run ./examples/go-library/prepare
go run ./examples/go-library/run

Also perform the documented Go-formatting, local Markdown-link, and repository- hygiene checks. Review the examples' deterministic output as instructed. No command may require a real Rakestrawhome credential or contact either provider.

Finally, inspect the diff against the feature roadmap and confirm all of the following:

• only the new public constant and embedded profile ID enlarge the consumer surface;
• OpenRouter's definition and existing gemma-4-31b profile are unchanged;
• both built-in backend IDs are reserved and consumer-added IDs remain extensible;
• no API key value, mutable global registry, provider-specific transport, live test, or hidden generation default was introduced; and
• current-state documentation and GoDoc agree with the implemented behavior.

Open Questions

None. The feature roadmap and this plan fix every implementation-relevant choice required for the three stages.