Documentation
¶
Overview ¶
Package models is the TOML-as-data model catalog (master plan §4.2).
Models live as `<provider>/<model>.toml` files under a catalog root (typically `~/.overkill/models/`). The filename derives the ID (`openai/gpt-5.toml` → ID `openai/gpt-5`) so there's no ID-vs-filename mismatch risk.
Wrapper models (OpenRouter, Groq) use `[extends] from = "..."` to inherit a canonical model's shape and override only cost. 240+ model files collapse to 5-line stubs.
Loading is a single pass:
- Walk the root, parse every `.toml` into a raw Model.
- Resolve `extends` references — wrappers inherit from base.
- Validate required fields and capability flag combinations.
- Build the in-memory Catalog (map[ID]*Model + family index).
The Catalog is read-only after Load. Hot-reload is future work; for now a config change requires a process restart (or a new Catalog instance via Load).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("models: not found")
ErrNotFound is returned by Catalog.Get when no model matches.
Functions ¶
This section is empty.
Types ¶
type Capabilities ¶
type Capabilities struct {
Reasoning bool `toml:"reasoning" json:"reasoning"`
ToolCall bool `toml:"tool_call" json:"tool_call"`
StructuredOutput bool `toml:"structured_output" json:"structured_output"`
Temperature bool `toml:"temperature" json:"temperature"`
Attachment bool `toml:"attachment" json:"attachment"`
OpenWeights bool `toml:"open_weights" json:"open_weights"`
}
Capabilities is the boolean flag set used for family-aware routing + capability filtering. "reasoning" + "tool_call" being booleans means routers can match on `cap.reasoning && cap.tool_call` cheaply.
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog is the in-memory model database. Read-only after Load.
func Load ¶
Load reads every `.toml` file under root, resolves extends references, validates, and returns a Catalog. Missing root returns (empty Catalog, nil) — running with an empty catalog is supported. Parse / validation errors are aggregated and returned as a single error wrapping all per-file failures.
func (*Catalog) CheapestInFamily ¶
CheapestInFamily returns the lowest-output-cost model in the family, honouring deprecation (skipped). Returns ErrNotFound when no non-deprecated models exist in the family.
func (*Catalog) Get ¶
Get returns a copy of the model with the given ID. Copy semantics prevent callers from mutating the catalog's internal state.
func (*Catalog) ListFamily ¶
ListFamily returns every model whose Family matches name. Case- sensitive (families are canonical short strings like "claude-opus").
func (*Catalog) ListWithCapability ¶
func (c *Catalog) ListWithCapability(req Capabilities) []*Model
ListWithCapability returns every model whose Capabilities set contains ALL requested flags as true. Family/tag/etc. filtering can be layered on top by callers.
type Cost ¶
type Cost struct {
Input float64 `toml:"input" json:"input"`
Output float64 `toml:"output" json:"output"`
CacheRead float64 `toml:"cache_read" json:"cache_read,omitempty"`
CacheWrite float64 `toml:"cache_write" json:"cache_write,omitempty"`
AudioIn float64 `toml:"audio_in" json:"audio_in,omitempty"`
AudioOut float64 `toml:"audio_out" json:"audio_out,omitempty"`
Reasoning float64 `toml:"reasoning" json:"reasoning,omitempty"`
TieredOver200K *Cost `toml:"tiered_over_200k" json:"tiered_over_200k,omitempty"`
}
Cost is per-million-tokens by default. Tiered pricing for very-long contexts (typically >200K) goes in TieredOver200K when present.
type Extends ¶
type Extends struct {
From string `toml:"from" json:"from"`
}
Extends is the wrapper-model declaration. `From` is the canonical model ID we inherit from. Wrappers typically override only Cost (different per-token pricing through OpenRouter/Groq/etc.) and optionally Deprecated.
type Modalities ¶
type Modalities struct {
Input []string `toml:"input" json:"input,omitempty"`
Output []string `toml:"output" json:"output,omitempty"`
}
Modalities lists the input/output media types a model accepts / produces. Strings stay free-form (text, image, audio, video) so future modalities don't need a code change.
type Model ¶
type Model struct {
ID string `toml:"-" json:"id"`
Family string `toml:"family" json:"family"`
DisplayName string `toml:"display_name" json:"display_name,omitempty"`
ContextWindow int `toml:"context_window" json:"context_window"`
MaxOutputTokens int `toml:"max_output_tokens" json:"max_output_tokens,omitempty"`
Capabilities Capabilities `toml:"capabilities" json:"capabilities"`
Cost *Cost `toml:"cost" json:"cost"`
Modalities Modalities `toml:"modalities" json:"modalities"`
Extends *Extends `toml:"extends" json:"extends,omitempty"`
Deprecated bool `toml:"deprecated" json:"deprecated,omitempty"`
}
Model is the canonical record for one model in the catalog. Fields loaded from TOML; ID is derived from filename, not declared.
Source Files