Plan the built-in Rakestrawhome backend
This commit is contained in:
272
docs/roadmap/implementation.md
Normal file
272
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Rakestrawhome Built-In Backend Implementation Plan
|
||||
|
||||
## Purpose
|
||||
|
||||
Implement the target state defined in the
|
||||
[Rakestrawhome built-in backend roadmap](rakestrawhome-backend.md): 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/`](../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`](../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:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```sh
|
||||
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`](../development.md#maintainer-validation),
|
||||
including:
|
||||
|
||||
```sh
|
||||
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.
|
||||
Reference in New Issue
Block a user