base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Set root identities and expand bundled profile plan

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-03 14:26:50 +00:00
parent 5ce6e01f27
commit 75204d6134
1 changed files with 62 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/roadmap/bundled-openrouter.md
View File

@@ -4,7 +4,7 @@
Proposed; no implementation changes yet. Proposed; no implementation changes yet.
Ship a small OpenRouter configuration collection with PromptKit so consumers Ship a small OpenRouter configuration bundle with PromptKit so consumers
can begin using named profiles without installing a separate catalog. Include can begin using named profiles without installing a separate catalog. Include
the backend definition those profiles require. Keep separately maintained the backend definition those profiles require. Keep separately maintained
operator collections fully supported through the existing configuration path. operator collections fully supported through the existing configuration path.
@@ -36,7 +36,7 @@ that release; no further upstream enhancement is required for this feature.
### Ordinary Embedded Configuration ### Ordinary Embedded Configuration
Embed a small YAML collection in PromptKit and load it through the existing Embed a small YAML bundle in PromptKit and load it through the existing
ConfigKit adapter. Place it in its own lowest-priority underlay, before every ConfigKit adapter. Place it in its own lowest-priority underlay, before every
caller underlay and the main input. Preserve the existing order and grouping caller underlay and the main input. Preserve the existing order and grouping
of caller inputs. of caller inputs.
@@ -56,9 +56,23 @@ listing and inspection APIs. Source explanations should identify embedded
configuration meaningfully. There is no need for a parallel built-in catalog configuration meaningfully. There is no need for a parallel built-in catalog
API or special provenance model. API or special provenance model.
### Root Resource Layout
Use root entries for both the backend and all built-in profiles. The backend
ID is `openrouter`; each bundled profile references `backend: openrouter` and
is selected using its unqualified ID. No built-in `openrouter` collection is
created, so an externally supplied collection can expose names such as
`openrouter/gpt-sol-latest` alongside the root `gpt-sol-latest` profile.
Built-ins at the root and external libraries under `collections` is a
convention, not an enforced distinction. Applications may supply root entries,
override built-ins, and organize external configuration using either form.
Root names favor convenient selection; their backend remains explicit in the
definition and inspection even though it is absent from the profile ID.
### OpenRouter Backend ### OpenRouter Backend
Include a backend with OpenRouter's API base endpoint, Include the root `openrouter` backend with OpenRouter's API base endpoint,
`https://openrouter.ai/api/v1`, and the conventional environment-variable name `https://openrouter.ai/api/v1`, and the conventional environment-variable name
`OPENROUTER_API_KEY`. Store the name only; no credential value belongs in the `OPENROUTER_API_KEY`. Store the name only; no credential value belongs in the
bundle. Reuse the existing OpenAI-compatible client and credential resolution. bundle. Reuse the existing OpenAI-compatible client and credential resolution.
@@ -70,18 +84,29 @@ diagnostics or select an inference smoke-test profile.
### Small Profile Set ### Small Profile Set
The proposed initial set contains these three model selections: The initial set contains twelve root profiles:
| Proposed profile ID | OpenRouter model value | Purpose | | Profile ID | Intended model selection |
| --- | --- | --- | | --- | --- |
| `openrouter/gpt-sol-latest` | `~openai/gpt-sol-latest` | Follow the current GPT Sol family model. | | `gpt-astra-latest` | OpenAI GPT Astra latest-family alias through OpenRouter. |
| `openrouter/auto` | `openrouter/auto` | Delegate model selection to OpenRouter's auto router. | | `gpt-sol-latest` | OpenAI GPT Sol latest-family alias (`~openai/gpt-sol-latest`). |
| `openrouter/free` | `openrouter/free` | Select OpenRouter's free-model router. | | `gpt-terra-latest` | OpenAI GPT Terra latest-family alias through OpenRouter. |
| `gpt-luna-latest` | OpenAI GPT Luna latest-family alias through OpenRouter. |
| `claude-fable-latest` | Anthropic Claude Fable latest-family alias through OpenRouter. |
| `claude-opus-latest` | Anthropic Claude Opus latest-family alias through OpenRouter. |
| `claude-sonnet-latest` | Anthropic Claude Sonnet latest-family alias through OpenRouter. |
| `claude-haiku-latest` | Anthropic Claude Haiku latest-family alias through OpenRouter. |
| `gemini-pro-latest` | Google Gemini Pro latest-family alias through OpenRouter. |
| `gemini-flash-latest` | Google Gemini Flash latest-family alias through OpenRouter. |
| `auto` | OpenRouter auto router (`openrouter/auto`). |
| `free` | OpenRouter free-model router (`openrouter/free`). |
These names distinguish PromptKit resource IDs from provider model values: These profile IDs are selected. Confirm the exact provider `model` slugs for
the tilde and slash in a provider model slug remain part of that value. all family aliases during implementation rather than deriving them mechanically
Additional latest-family aliases can be selected before implementation or added from profile IDs. If a requested alias is unavailable, surface that mismatch
later when useful; completeness across vendors is not a launch requirement. instead of silently substituting a pinned model or dropping the profile.
The tilde and slash in a provider model slug remain part of that value; they
do not change the root placement of the PromptKit profile.
Each profile should primarily specify its backend and model. Avoid baking in Each profile should primarily specify its backend and model. Avoid baking in
temperature, reasoning, token-budget, timeout, or capability assumptions merely temperature, reasoning, token-budget, timeout, or capability assumptions merely
@@ -121,8 +146,8 @@ does not identify or pin the concrete model selected upstream.
## Implementation Work ## Implementation Work
1. Resolve the identity layout and diagnostic-metadata decisions below. Confirm 1. Resolve the diagnostic-metadata decision below. Verify the provider endpoint
the initial profile list and current provider endpoint/model values. and exact model values for the twelve selected root profiles.
2. Add the embedded YAML backend and profiles, and integrate their dedicated 2. Add the embedded YAML backend and profiles, and integrate their dedicated
underlay with engine construction. Add the disable option using the existing underlay with engine construction. Add the disable option using the existing
facade option pattern. Apply the ordinary load/normalize/validate lifecycle. facade option pattern. Apply the ordinary load/normalize/validate lifecycle.
@@ -147,31 +172,29 @@ needed solely to distribute this data.
## Open Decisions ## Open Decisions
### 1. Backend Identity And Collection Layout ### Smoke-Test Metadata In The Bundled Backend
**Recommendation:** Put profiles in the `openrouter` collection with the local **Recommendation:** Include `smoke_tests.authentication.kind: openrouter_key`
IDs shown above, and put the backend in that collection as local ID `default`. using the existing adapter's backend-relative `/key` endpoint. Leave a separate
Profiles would reference `openrouter/default`. This keeps the bundle together, reachability endpoint and inference `default_profile` unspecified. The adapter
avoids an ambiguous doubled provider name, and supports normal collection already exists, so this is a small configuration addition that makes explicit
inspection. Applications can still replace those exact IDs. API-key diagnostics useful out of the box without choosing an inference model.
OpenRouter documents the authenticated
[current-key endpoint](https://openrouter.ai/docs/api/api-reference/api-keys/get-current-api-key).
Its acceptance of a key is evidence about that endpoint, not a guarantee that
an arbitrary inference request will succeed.
**Alternative:** Use a root backend ID `openrouter` with namespaced profiles. This revises the initial recommendation to omit diagnostic metadata: given the
This is concise and may align better with existing operator catalogs. Its existing adapter and the bundle's convenience purpose, the added utility seems
drawback is splitting the bundle between root and collection resources, and worth maintaining the small declaration. The decision remains open pending
making a common root backend name the shared override target. Before choosing, maintainer agreement.
compare maintained OpenRouter catalog conventions; the layout should minimize
consumer confusion rather than establish a new naming restriction.
### 2. Smoke-Test Metadata In The Bundled Backend **Alternative:** Include only the backend endpoint and credential-variable name.
This keeps the shipped configuration smaller and leaves diagnostic declarations
entirely with the consumer, but applications wanting authentication diagnostics
must configure the existing adapter themselves. Ordinary inference is unaffected.
**Recommendation:** Include only the endpoint and credential-variable name in Either approach uses existing diagnostic APIs and execution rules. Neither
the initial backend. Existing diagnostic behavior remains available, and the implies automatic diagnostics during construction or execution. Selecting a
feature stays focused on configuration convenience without choosing a diagnostic built-in inference smoke-test default would be a separate choice; this proposal
inference model or expanding the maintained provider-specific configuration. leaves callers able to select a profile explicitly without prescribing one.
**Alternative:** Also provide the existing OpenRouter authentication diagnostic
configuration, after verifying its endpoint and behavior, while leaving the
inference smoke-test profile unselected. This makes the bundle more useful for
explicit preflight calls with little data, but adds another upstream convention
to maintain and test. Neither option implies automatic diagnostics during
construction or execution.