modelcatalog

package
v0.10.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 5, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ReasoningControlTunable = "tunable"
	ReasoningControlFixed   = "fixed"
	ReasoningControlNone    = "none"

	ReasoningWireProvider = "provider"
	ReasoningWireModelID  = "model_id"
	ReasoningWireNone     = "none"
)

Reasoning capability control values.

View Source
const (
	SamplingControlClientSettable = "client_settable"
	SamplingControlHarnessPinned  = "harness_pinned"
	SamplingControlPartial        = "partial"
)

Sampling-control values for ModelEntry.SamplingControl. See ADR-007 §4.

Variables

This section is empty.

Functions

func BootstrapModelPowers

func BootstrapModelPowers(models map[string]ModelEntry) map[string]ModelEntry

BootstrapModelPowers derives conservative power/eligibility defaults from comparable model metadata. It is side-effect-free so catalog generation can inspect or persist the result explicitly.

func FetchOpenRouterPricing

func FetchOpenRouterPricing(timeout time.Duration) (map[string]openrouterModelEntry, error)

FetchOpenRouterPricing fetches current pricing from OpenRouter /models. Returns a map of OpenRouter model ID → entry.

func UpdateManifestPricing

func UpdateManifestPricing(manifestPath string, timeout time.Duration) (int, []string, error)

UpdateManifestPricing fetches OpenRouter pricing and updates cost fields in the manifest at manifestPath. Creates the file from the embedded default if it doesn't exist. Returns (updated count, not-found IDs, error).

Types

type Alias

type Alias struct {
	Name        string
	Target      string
	Deprecated  bool
	Replacement string
}

Alias describes one catalog alias.

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog resolves logical model references into concrete consumer-specific model IDs.

func Default

func Default() (*Catalog, error)

Default loads the embedded default catalog snapshot.

func Load

func Load(opts LoadOptions) (*Catalog, error)

Load loads a catalog from an external manifest or falls back to the embedded snapshot.

func (*Catalog) Aliases

func (c *Catalog) Aliases() []Alias

Aliases returns all target aliases in deterministic order.

func (*Catalog) AllConcreteModels

func (c *Catalog) AllConcreteModels(surface Surface) map[string]string

AllConcreteModels returns a map from concrete model ID to catalog target ID for every active target that has a mapping for the given surface. The map is safe to use as a membership set for ranking discovered models. All candidate model IDs (not just the primary) are included. When multiple targets share the same concrete model ID, single-string surface entries take priority over candidates-list entries. Among entries of equal priority, the first target ID in lexicographic order wins.

func (*Catalog) AllModels

func (c *Catalog) AllModels() map[string]ModelEntry

AllModels returns all per-model entries from the top-level models: map (manifest v4+), keyed by model ID. Returns an empty map for older manifests.

func (*Catalog) AllModelsInTier

func (c *Catalog) AllModelsInTier(targetID string) []TierModel

AllModelsInTier returns the ordered model entries declared as candidates for a target tier. For older manifests, candidates are synthesized from surface mappings during load.

func (*Catalog) CandidatesFor

func (c *Catalog) CandidatesFor(surface Surface, targetKey string) []string

CandidatesFor returns the ordered list of candidate concrete model IDs for the given surface and target key. For old-style single-string surfaces this returns a one-element slice. Returns nil if the target or surface is absent.

func (*Catalog) ContextWindowForModel

func (c *Catalog) ContextWindowForModel(id string) int

ContextWindowForModel returns the context window in tokens for the given concrete model ID, or 0 if the model is not in the catalog or has no context_window declared. Used as a fallback when the provider's live API does not expose its context window (e.g. LM Studio's /v1/models omits it). Matching is case-insensitive to accept both "qwen3.5-27b" and "Qwen3.5-27B".

func (*Catalog) Current

func (c *Catalog) Current(profile string, opts ResolveOptions) (ResolvedTarget, error)

Current resolves a profile to its current target.

func (*Catalog) LookupModel

func (c *Catalog) LookupModel(id string) (ModelEntry, bool)

LookupModel returns the ModelEntry for the given model ID from the top-level models: map (manifest v4+). The second return value is false if not found.

func (*Catalog) Metadata

func (c *Catalog) Metadata() Metadata

Metadata returns the loaded manifest metadata for inspection surfaces.

func (*Catalog) ModelEligibility

func (c *Catalog) ModelEligibility(id string) (ModelEligibility, bool)

ModelEligibility returns power and automatic-routing eligibility for a catalog model ID or any declared provider surface ID. Unknown models return ok=false; known models with missing/zero power remain exact-pin-capable but are not auto-routable.

func (*Catalog) ModelSamplingControl

func (c *Catalog) ModelSamplingControl(modelID string) string

ModelSamplingControl returns the SamplingControl string for the model ID, or "" when the model is not declared in the catalog or carries no explicit value (treated as the default "client_settable" by callers). Implements the sampling.CatalogLookup interface.

func (*Catalog) PricingFor

func (c *Catalog) PricingFor() map[string]CatalogModelPricing

PricingFor returns pricing for all active concrete models across all surfaces. Per-model entries from the top-level models: map (v4+) take precedence over target-level pricing. Only models/targets with a positive input cost are included.

func (*Catalog) Profile

func (c *Catalog) Profile(name string) (Profile, bool)

Profile returns one named profile definition.

func (*Catalog) Profiles

func (c *Catalog) Profiles() []Profile

Profiles returns all named profiles in deterministic order.

func (*Catalog) Resolve

func (c *Catalog) Resolve(ref string, opts ResolveOptions) (ResolvedTarget, error)

Resolve resolves a profile, canonical target, or alias to a concrete model ID.

func (*Catalog) SamplingProfile

func (c *Catalog) SamplingProfile(name string) (sampling.Profile, bool)

SamplingProfile returns the catalog-defined sampling-parameter bundle for the given profile name (e.g., "code"). The second return value is false when the profile is not declared in the manifest. See ADR-007.

func (*Catalog) SamplingProfileNames

func (c *Catalog) SamplingProfileNames() []string

SamplingProfileNames returns the names of all sampling profiles declared in the manifest, sorted lexicographically. Used by `catalog show` and other ops surfaces to advertise what profiles are available.

func (*Catalog) SupportsToolsForModel

func (c *Catalog) SupportsToolsForModel(id string) bool

SupportsToolsForModel reports whether the given concrete model ID supports tool/function calling per the catalog. Returns true when the model is not in the catalog (caller assumes capable by default) and false only when the catalog explicitly marks the model with no_tools=true. Matching is case-insensitive to mirror ContextWindowForModel.

type CatalogModelPricing

type CatalogModelPricing struct {
	InputPerMTok   float64
	OutputPerMTok  float64
	CacheReadPerM  float64
	CacheWritePerM float64
}

CatalogModelPricing holds per-million-token costs for a model as sourced from the catalog.

type DeprecatedTargetError

type DeprecatedTargetError struct {
	CanonicalID string
	Status      string
	Replacement string
}

DeprecatedTargetError indicates that a deprecated or stale target was resolved in strict mode.

func (*DeprecatedTargetError) Error

func (e *DeprecatedTargetError) Error() string

type LoadOptions

type LoadOptions struct {
	ManifestPath    string
	RequireExternal bool
}

LoadOptions configures how a catalog manifest is loaded.

type Metadata

type Metadata struct {
	ManifestSource  string
	ManifestVersion int
	CatalogVersion  string
}

Metadata describes the loaded manifest.

type MissingSurfaceError

type MissingSurfaceError struct {
	CanonicalID string
	Surface     Surface
}

MissingSurfaceError indicates that a target cannot be projected to the requested surface.

func (*MissingSurfaceError) Error

func (e *MissingSurfaceError) Error() string

type ModelEligibility

type ModelEligibility struct {
	Power        int
	ExactPinOnly bool
	AutoRoutable bool
}

ModelEligibility describes whether a catalog model can participate in unpinned automatic routing or only explicit model pins.

type ModelEntry

type ModelEntry struct {
	Family             string                      `yaml:"family,omitempty"`
	DisplayName        string                      `yaml:"display_name,omitempty"`
	Tier               string                      `yaml:"tier,omitempty"`
	Status             string                      `yaml:"status,omitempty"`
	ProviderSystem     string                      `yaml:"provider_system,omitempty"`
	DeploymentClass    string                      `yaml:"deployment_class,omitempty" json:"deployment_class,omitempty"`
	PowerProvenance    PowerProvenance             `yaml:"power_provenance,omitempty" json:"power_provenance,omitempty"`
	CostInputPerM      float64                     `yaml:"cost_input_per_m,omitempty"`
	CostOutputPerM     float64                     `yaml:"cost_output_per_m,omitempty"`
	CostCacheReadPerM  float64                     `yaml:"cost_cache_read_per_m,omitempty"`
	CostCacheWritePerM float64                     `yaml:"cost_cache_write_per_m,omitempty"`
	CostInputPerMTok   float64                     `yaml:"cost_input_per_mtok,omitempty"`
	CostOutputPerMTok  float64                     `yaml:"cost_output_per_mtok,omitempty"`
	SWEBenchVerified   float64                     `yaml:"swe_bench_verified,omitempty"`
	LiveCodeBench      float64                     `yaml:"live_code_bench,omitempty"`
	BenchmarkAsOf      string                      `yaml:"benchmark_as_of,omitempty"`
	OpenRouterID       string                      `yaml:"openrouter_id,omitempty"`
	OpenRouterRefID    string                      `yaml:"openrouter_ref_id,omitempty"`
	Surfaces           map[string]string           `yaml:"surfaces,omitempty"`
	SpeedTokensPerSec  float64                     `yaml:"speed_tokens_per_sec,omitempty"`
	ContextWindow      int                         `yaml:"context_window,omitempty"`
	Power              int                         `yaml:"power,omitempty" json:"power,omitempty"`
	ExactPinOnly       bool                        `yaml:"exact_pin_only,omitempty" json:"exact_pin_only,omitempty"`
	NoTools            bool                        `yaml:"no_tools,omitempty"`
	ReasoningMaxTokens int                         `yaml:"reasoning_max_tokens,omitempty"`
	ReasoningBudgets   map[reasoning.Reasoning]int `yaml:"reasoning_budgets,omitempty"`
	ReasoningLevels    []string                    `yaml:"reasoning_levels,omitempty"`
	ReasoningControl   string                      `yaml:"reasoning_control,omitempty"`
	ReasoningWire      string                      `yaml:"reasoning_wire,omitempty"`
	// SamplingControl declares whether catalog sampling_profiles reach the
	// wire for runs that resolve to this model. See ADR-007 §4.
	//   client_settable (default) — provider honors all five sampler fields.
	//   harness_pinned             — wrapped harness pins samplers internally;
	//                                 the resolver short-circuits to a
	//                                 zero-value bundle.
	//   partial                    — provider honors a subset (reserved; not
	//                                 enforced in v1).
	SamplingControl string `yaml:"sampling_control,omitempty"`
}

ModelEntry holds per-model metadata introduced in manifest v4.

func (ModelEntry) AutoRoutable

func (m ModelEntry) AutoRoutable() bool

AutoRoutable reports whether a model is eligible for unpinned automatic routing. Unknown-power and exact-pin-only entries remain usable by explicit model pin when live discovery confirms availability.

type PowerProvenance

type PowerProvenance struct {
	Method          string             `yaml:"method,omitempty" json:"method,omitempty"`
	Benchmarks      map[string]float64 `yaml:"benchmarks,omitempty" json:"benchmarks,omitempty"`
	Recency         string             `yaml:"recency,omitempty" json:"recency,omitempty"`
	CostInputPerM   float64            `yaml:"cost_input_per_m,omitempty" json:"cost_input_per_m,omitempty"`
	CostOutputPerM  float64            `yaml:"cost_output_per_m,omitempty" json:"cost_output_per_m,omitempty"`
	DeploymentClass string             `yaml:"deployment_class,omitempty" json:"deployment_class,omitempty"`
	OverrideReason  string             `yaml:"override_reason,omitempty" json:"override_reason,omitempty"`
}

PowerProvenance records why a model received its catalog power score.

type Profile

type Profile struct {
	Name               string
	Target             string
	ProviderPreference string
}

Profile describes one named catalog profile.

type ResolveOptions

type ResolveOptions struct {
	Surface         Surface
	AllowDeprecated bool
}

ResolveOptions configures how model references are resolved.

type ResolvedTarget

type ResolvedTarget struct {
	Ref             string
	Profile         string
	Family          string
	CanonicalID     string
	ConcreteModel   string
	SurfacePolicy   SurfacePolicy
	Deprecated      bool
	Replacement     string
	CatalogVersion  string
	ManifestSource  string
	ManifestVersion int
	// Pricing (USD per 1M tokens, 0 = unknown/free)
	CostInputPerM      float64
	CostOutputPerM     float64
	CostCacheReadPerM  float64
	CostCacheWritePerM float64
	// Context
	ContextWindow int
	// Benchmarks
	SWEBenchVerified float64
	LiveCodeBench    float64
	BenchmarkAsOf    string
	// OpenRouter
	OpenRouterRefID string
}

ResolvedTarget is the resolved output for a model reference.

type Surface

type Surface string

Surface identifies the consumer-specific naming surface for a model target.

const (
	SurfaceAgentOpenAI    Surface = "agent.openai"
	SurfaceAgentAnthropic Surface = "agent.anthropic"
	SurfaceCodex          Surface = "codex"
	SurfaceClaudeCode     Surface = "claude-code"
	SurfaceGemini         Surface = "gemini"
)

type SurfacePolicy

type SurfacePolicy struct {
	ReasoningDefault       reasoning.Reasoning
	PlacementOrder         []string
	MaxInputCostPerMTokUSD *float64
	FailurePolicy          string
}

SurfacePolicy captures optional routing metadata for a resolved surface.

type TierModel

type TierModel struct {
	ID    string
	Entry ModelEntry
}

TierModel is one concrete model entry referenced by a catalog tier.

type UnknownReferenceError

type UnknownReferenceError struct {
	Ref string
}

UnknownReferenceError indicates that a reference is not known to the catalog.

func (*UnknownReferenceError) Error

func (e *UnknownReferenceError) Error() string

type UnknownTargetError

type UnknownTargetError struct {
	CanonicalID string
}

UnknownTargetError indicates an internal invariant break where a referenced target is absent.

func (*UnknownTargetError) Error

func (e *UnknownTargetError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL