modelcatalog

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: May 9, 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 BillingModel added in v0.11.0

type BillingModel string

BillingModel describes how a provider or harness is paid for.

const (
	BillingModelUnknown      BillingModel = ""
	BillingModelFixed        BillingModel = "fixed"
	BillingModelPerToken     BillingModel = "per_token"
	BillingModelSubscription BillingModel = "subscription"
)

func BillingForHarness added in v0.11.0

func BillingForHarness(harness string) BillingModel

BillingForHarness returns the billing model for built-in harnesses whose usage is governed by subscription/account limits rather than per-token user provider configuration.

func BillingForProviderSystem added in v0.11.0

func BillingForProviderSystem(system string) BillingModel

BillingForProviderSystem returns the catalog's built-in billing model for a known provider system. Unknown systems return BillingModelUnknown so user manifests can require an explicit provider billing field.

type Catalog

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

Catalog exposes the loaded v5 model catalog.

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) AllConcreteModels

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

AllConcreteModels returns a map from concrete model ID to canonical model ID for every active model that has a mapping for the given surface.

func (*Catalog) AllModels

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

AllModels returns all per-model entries, keyed by model ID.

func (*Catalog) CandidatesFor

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

CandidatesFor returns the ordered concrete model IDs for a policy or model.

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(policy string, opts ResolveOptions) (ResolvedTarget, error)

Current resolves a policy to its selected concrete model for a surface.

func (*Catalog) LookupModel

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

LookupModel returns the ModelEntry for the given model ID.

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) Policies added in v0.11.0

func (c *Catalog) Policies() []Policy

Policies returns all canonical policies in deterministic order.

func (*Catalog) Policy added in v0.11.0

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

Policy returns one canonical policy definition.

func (*Catalog) PricingFor

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

PricingFor returns pricing for all active concrete models across all surfaces.

func (*Catalog) Providers added in v0.11.0

func (c *Catalog) Providers() []Provider

Providers returns all catalog-declared provider systems in deterministic order.

func (*Catalog) Resolve

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

Resolve resolves a canonical policy or model ID 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
	SuggestedProfile  string
	SuggestedMinPower int
	SuggestedMaxPower int
}

DeprecatedTargetError indicates that a deprecated or stale model 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 model 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"`
	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"`
	ReasoningDefault   reasoning.Reasoning         `yaml:"reasoning_default,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 from the v5 manifest.

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 Policy added in v0.11.0

type Policy struct {
	Name       string
	MinPower   int
	MaxPower   int
	AllowLocal bool
	Require    []string
}

Policy describes one canonical catalog routing policy.

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 Provider added in v0.11.0

type Provider struct {
	Name             string
	Type             string
	IncludeByDefault bool
	Billing          BillingModel
}

Provider describes one catalog-declared provider system.

type ResolveOptions

type ResolveOptions struct {
	Surface         Surface
	AllowDeprecated bool
}

ResolveOptions configures compatibility model-reference resolution.

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
	CostInputPerM      float64
	CostOutputPerM     float64
	CostCacheReadPerM  float64
	CostCacheWritePerM float64
	ContextWindow      int
	SWEBenchVerified   float64
	LiveCodeBench      float64
	BenchmarkAsOf      string
	OpenRouterRefID    string
}

ResolvedTarget is the compatibility output for model-reference resolution. In v5 CanonicalID is either a policy name or canonical model ID; there is no catalog alias concept behind it.

type Surface

type Surface string

Surface identifies a consumer-specific concrete model naming surface.

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 is kept as a narrow compatibility container for callers that have not yet moved reasoning defaults from surface projections to model entries.

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

Jump to

Keyboard shortcuts

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