Documentation
¶
Index ¶
- Constants
- func BootstrapModelPowers(models map[string]ModelEntry) map[string]ModelEntry
- func FetchOpenRouterPricing(timeout time.Duration) (map[string]openrouterModelEntry, error)
- func UpdateManifestPricing(manifestPath string, timeout time.Duration) (int, []string, error)
- type Alias
- type Catalog
- func (c *Catalog) Aliases() []Alias
- func (c *Catalog) AllConcreteModels(surface Surface) map[string]string
- func (c *Catalog) AllModels() map[string]ModelEntry
- func (c *Catalog) AllModelsInTier(targetID string) []TierModel
- func (c *Catalog) CandidatesFor(surface Surface, targetKey string) []string
- func (c *Catalog) ContextWindowForModel(id string) int
- func (c *Catalog) Current(profile string, opts ResolveOptions) (ResolvedTarget, error)
- func (c *Catalog) LookupModel(id string) (ModelEntry, bool)
- func (c *Catalog) Metadata() Metadata
- func (c *Catalog) ModelEligibility(id string) (ModelEligibility, bool)
- func (c *Catalog) ModelSamplingControl(modelID string) string
- func (c *Catalog) PricingFor() map[string]CatalogModelPricing
- func (c *Catalog) Profile(name string) (Profile, bool)
- func (c *Catalog) Profiles() []Profile
- func (c *Catalog) Resolve(ref string, opts ResolveOptions) (ResolvedTarget, error)
- func (c *Catalog) SamplingProfile(name string) (sampling.Profile, bool)
- func (c *Catalog) SamplingProfileNames() []string
- func (c *Catalog) SupportsToolsForModel(id string) bool
- type CatalogModelPricing
- type DeprecatedTargetError
- type LoadOptions
- type Metadata
- type MissingSurfaceError
- type ModelEligibility
- type ModelEntry
- type PowerProvenance
- type Profile
- type ResolveOptions
- type ResolvedTarget
- type Surface
- type SurfacePolicy
- type TierModel
- type UnknownReferenceError
- type UnknownTargetError
Constants ¶
const ( ReasoningControlTunable = "tunable" ReasoningControlFixed = "fixed" ReasoningControlNone = "none" ReasoningWireProvider = "provider" ReasoningWireModelID = "model_id" ReasoningWireNone = "none" )
Reasoning capability control values.
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 ¶
FetchOpenRouterPricing fetches current pricing from OpenRouter /models. Returns a map of OpenRouter model ID → entry.
func UpdateManifestPricing ¶
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 Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog resolves logical model references into concrete consumer-specific model IDs.
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 ¶
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 ¶
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 ¶
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 ¶
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) 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 ¶
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) 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 ¶
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 ¶
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 ¶
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 ¶
DeprecatedTargetError indicates that a deprecated or stale target was resolved in strict mode.
func (*DeprecatedTargetError) Error ¶
func (e *DeprecatedTargetError) Error() string
type LoadOptions ¶
LoadOptions configures how a catalog manifest is loaded.
type MissingSurfaceError ¶
MissingSurfaceError indicates that a target cannot be projected to the requested surface.
func (*MissingSurfaceError) Error ¶
func (e *MissingSurfaceError) Error() string
type ModelEligibility ¶
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 ResolveOptions ¶
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.
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