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

Document the bundled OpenRouter configuration

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-03 15:39:04 +00:00
parent 43f55edb98
commit 2b3d165ce2
12 changed files with 114 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/consumers/configuration-migration.md
View File

@@ -3,7 +3,7 @@
This breaking pre-v1 minor migration adopts Promptkit's vanity module path,
changes the v0.16-era keyed resources to identified lists, adopts ConfigKit v1,
and removes prompt-version labels.
Promptkit does not install a provider catalog; applications choose configuration
Promptkit installs a default-on bundled OpenRouter catalog; applications choose configuration
inputs explicitly, and execution selects one prompt by its exact ID. This guide
explains the shape changes and decisions an application must make; it is not an
automatic migration tool. The [framework format reference](../formats.md) owns

32
docs/consumers/pkg-promptkit.md
View File

@@ -52,6 +52,32 @@ Create an engine with [`NewEngine`](../../engine.go). Select each directory
explicitly and place its inputs in an ordered ConfigKit underlay. A group
strictly composes its files; later groups can overlay earlier ones:
The bundled OpenRouter backend and profiles are installed in a lower underlay
by default. Select a profile explicitly, for example:
```go
input := configkit.Input{Source: configkit.Mapping("application", map[string]any{
"prompts": []any{map[string]any{
"id": "my-prompt",
"messages": []any{map[string]any{"role": "user", "content": "Hello"}},
"output": map[string]any{"format": "text", "validation_mode": "none"},
}},
})}
engine, err := promptkit.NewEngine(promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &input}})
if err != nil { return err }
result, err := engine.Run(ctx, promptkit.RunRequest{PromptID: "my-prompt", ProfileID: "gpt-luna-latest"})
```
The backend looks up
`OPENROUTER_API_KEY` when available; credentials are not required at engine
construction. For the complete inventory and diagnostic defaults see the
[format reference](../formats.md#bundled-openrouter-configuration). Use
`promptkit.WithBundledOpenRouter(false)` for application-only inventories.
Caller records replace matching bundled records in full; use `extends` with a
distinct ID to inherit. Replacing `auto` also changes its cost-tier children's
inherited target, while their plugins remain. External collections remain
supported.
```go
promptInputs, err := promptkit.DirectoryInputs("prompts")
if err != nil { return err }
@@ -665,9 +691,9 @@ the engine to pick up changed definitions or message files.
### Choose A Profile Ownership Model
Supply backend and profile definitions through the configuration sources your
application selects. PromptKit does not install provider catalogs or built-in
profile inventories; conventional backend ID constants are names only. Define
the model, endpoint, credentials lookup, and settings that your application
application selects, alongside the default-on bundled OpenRouter inventory.
Conventional backend ID constants are names only. Define or replace the model,
endpoint, credentials lookup, and settings that your application
intends to support. A profile may inherit a sibling profile by its local key in
the same root or collection list; its backend reference uses the exact
configured identity. Caller-selected source layers determine the final values. The

55
docs/formats.md
View File

@@ -14,8 +14,8 @@ A configuration document may contain top-level `backends`, `profiles`, and
`prompts` lists, plus a `collections` mapping of namespaced resource groups.
Each resource has an explicit literal `id`, not a filename-derived identity.
IDs and references must be nonblank and remain exact: Promptkit does not trim or
re-key them. Unknown fields are errors. Promptkit installs no provider or
profile catalog; callers select the definitions they need.
re-key them. Unknown fields are errors. Promptkit installs a default-on bundled
OpenRouter underlay; callers still explicitly select a profile.
```yaml
backends:
@@ -332,9 +332,58 @@ For example, a runtime `extra_params["extends"]` key is ordinary provider
data, not a configuration inheritance instruction. An explicit zero timeout
does not disable the caller context or HTTP transport timeout.
### Bundled OpenRouter Configuration
The default bundle installs root backend `openrouter`, endpoint
`https://openrouter.ai/api/v1`, optional credential environment name
`OPENROUTER_API_KEY`, and smoke metadata selecting `gpt-luna-latest` with the
`openrouter_key` authentication adapter. Existing diagnostic endpoint fallback
applies. No prompt, implicit profile selection, or tuning defaults are installed.
Disable the entire bundle with `WithBundledOpenRouter(false)`.
The root profile IDs and their models are:
| Profile | Model |
| --- | --- |
| `gpt-astra-latest` | `~openai/gpt-astra-latest` |
| `gpt-sol-latest` | `~openai/gpt-sol-latest` |
| `gpt-terra-latest` | `~openai/gpt-terra-latest` |
| `gpt-luna-latest` | `~openai/gpt-luna-latest` |
| `claude-fable-latest` | `~anthropic/claude-fable-latest` |
| `claude-opus-latest` | `~anthropic/claude-opus-latest` |
| `claude-sonnet-latest` | `~anthropic/claude-sonnet-latest` |
| `claude-haiku-latest` | `~anthropic/claude-haiku-latest` |
| `gemini-pro-latest` | `~google/gemini-pro-latest` |
| `gemini-flash-latest` | `~google/gemini-flash-latest` |
| `auto` | `openrouter/auto` |
| `free` | `openrouter/free` |
The profiles `auto-low`, `auto-medium`, `auto-high`, `auto-xhigh`, and
`auto-max` extend `auto` and add an `auto-router` plugin with the corresponding
`cost_tier`. Replacing `auto` changes their inherited backend and model while
retaining their plugins. These are root IDs even when a model contains `/`.
For example, a caller can replace `auto` as a complete record and extend another
bundled profile under a new ID:
```yaml
profiles:
- id: auto
backend: openrouter
model: openrouter/free
- id: my-luna
extends: {id: gpt-luna-latest}
timeout_seconds: 60
```
See OpenRouter's [alias examples](https://openrouter.ai/~openai/gpt-luna-latest),
[auto router and cost tiers](https://openrouter.ai/docs/guides/routing/routers/auto-router),
and [free router](https://openrouter.ai/docs/guides/routing/routers/free-router)
for provider behavior and availability.
### Source And Profile Precedence
`NewEngine` composes caller underlays in their given order, followed by an
`NewEngine` composes the bundled OpenRouter underlay first by default, then
caller underlays in their given order, followed by an
optional main input. Later layers overlay earlier ones. Inputs within one
underlay group are strictly composed: conflicting contributions are errors,
not priority signals. The directory helpers discover `.yaml` and `.yml` files recursively

4
docs/internal/sources.md
View File

@@ -52,7 +52,9 @@ captured values without consulting ConfigKit or copying resource definitions.
The root `DirectoryInputs` and `FilesystemInputs` helpers discover sorted YAML
files under an explicit root, provide resource context, and leave imports
disabled. Each returned slice belongs to one strict-composition group; file
order does not confer priority. Caller underlays are composed in their given
order does not confer priority. Engine assembly prepends a dedicated embedded
OpenRouter underlay unless disabled, without modifying caller-owned slices.
Caller underlays are composed in their given
order, followed by the optional main input. The
[configuration tests](../../internal/configuration/load_test.go) exercise the
real loader and final-value handoff.

13
docs/releases/v0.18.0.md
View File

@@ -1,8 +1,9 @@
# Promptkit v0.18.0
Configuration inspection now exposes Promptkit's recorded field normalization
and derived queue-capacity defaults through ConfigKit v1.1.0. Execution behavior
is unchanged, and the minimum supported Go version remains 1.27.0.
and derived queue-capacity defaults through ConfigKit v1.1.0. Engines also
include a default-on OpenRouter configuration. The minimum supported Go
version remains 1.27.0.
## Recorded Configuration Normalization
@@ -18,7 +19,13 @@ overrides; see the [configuration inspection guide](../consumers/pkg-promptkit.m
## Compatibility And Upgrade
No application-code or configuration-format migration is required from v0.17.0.
New engines install a bundled OpenRouter backend and root profiles by default.
Inventory listings and inspection sources therefore change, and references to
bundled IDs that previously failed may now resolve. Pass
`promptkit.WithBundledOpenRouter(false)` to retain application-only behavior.
Caller records can replace bundled definitions through ordinary composition;
see the [bundle inventory and precedence](../formats.md#bundled-openrouter-configuration).
No configuration-format migration is required from v0.17.0.
Consumers that display or compare configuration inspection results should account
for normalized values and derived defaults replacing their earlier authored
representations. Request-time overrides and caller-appended messages retain

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

@@ -2,7 +2,8 @@
## Status And Purpose
Design decisions settled; implementation has not started.
Implemented: engine construction installs the embedded OpenRouter underlay by
default, with an option to disable it and ordinary caller composition.
Ship a small OpenRouter configuration bundle with PromptKit so consumers
can begin using named profiles without installing a separate catalog. Include
@@ -14,10 +15,10 @@ the need for PromptKit releases just to refresh individual model versions.
This is a convenience catalog, not an exhaustive model inventory or a promise
of stable upstream model behavior.
## Current Baseline
## Historical Baseline
PromptKit depends on ConfigKit v1.1.0 and records field normalization and derived
defaults during resolution. It currently installs no backend or profile
defaults during resolution. At that baseline it installed no backend or profile
definitions. Consumers supply configuration inputs, which ConfigKit composes
before PromptKit validates and materializes effective resources.

4
docs/roadmap/implementation.md
View File

@@ -298,3 +298,7 @@ Completion requires default availability, full disabling, ordinary caller
composition and provenance, correct cost-tier payloads and explicit diagnostic
fallbacks, and current documentation. There are no unresolved product choices,
external publication prerequisites, or new recurring release gates.
Completion: public guidance, GoDoc, offline examples, and the unreleased v0.18.0
note describe the bundle and opt-out. The race-enabled suite, vet, three example
commands, and diff checks passed on Go 1.27.0; no release was published.