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 BillingModel
- type Catalog
- func (c *Catalog) AllConcreteModels(surface Surface) map[string]string
- func (c *Catalog) AllModels() map[string]ModelEntry
- func (c *Catalog) CandidatesFor(surface Surface, key string) []string
- func (c *Catalog) ContextWindowForModel(id string) int
- func (c *Catalog) Current(policy 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) Policies() []Policy
- func (c *Catalog) Policy(name string) (Policy, bool)
- func (c *Catalog) PricingFor() map[string]CatalogModelPricing
- func (c *Catalog) Providers() []Provider
- 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 Policy
- type PowerProvenance
- type Provider
- type ResolveOptions
- type ResolvedTarget
- type Surface
- type SurfacePolicy
- type UnknownReferenceError
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 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 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 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 ¶
CandidatesFor returns the ordered concrete model IDs for a policy or model.
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(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) 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) Policies ¶ added in v0.11.0
Policies returns all canonical policies in deterministic order.
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
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 ¶
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 ¶
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 ¶
LoadOptions configures how a catalog manifest is loaded.
type MissingSurfaceError ¶
MissingSurfaceError indicates that a model 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"`
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 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 ¶
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.
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