Documentation
¶
Overview ¶
Package modeltier classifies LLM model IDs into capability tiers (frontier / mid / small) used to tune behavior whose right setting depends on how powerfully the model reasons.
First consumer: the compactor (pkg/agent). A single utilization-threshold (0.85) is fine for frontier models — they reason coherently with 850k tokens of context. Small models degrade much earlier (Flash gets unreliable somewhere in the 200-300k range on a 1M window), so the compaction trigger needs to fire well before 85% to keep the session functional.
Future consumers: anything that wants a tier label (per-tier budget caps, per-tier loop-detection sensitivity, per-tier UI hints in `/stats`). Add lookups here so the model→tier table stays in one place.
Classification is by substring match against the model ID, same approach as pkg/usage/context_window.go's window-size table. Unknown models classify as "" — callers should treat the empty string as "skip the tier-specific behavior" rather than guess.
Maintenance: when a new model ships, add it to one of the case branches in Classify. Substring patterns let the lookup land regardless of date suffix (`-20251001`, `@20251101`, etc.).
Index ¶
Constants ¶
const ( // TierFrontier covers the most capable models in each provider's // lineup — Opus, Pro at the latest generation. They reason // coherently with most of their context window full. TierFrontier = "frontier" // TierMid covers mid-class models — Sonnet, older Pro, GPT-4.1-ish. // Better than small at deep reasoning, but degrade past ~60% context // utilization. TierMid = "mid" // TierSmall covers the cheap-tier models — Flash, Haiku, mini. // Excellent for digesting tool output and short-question Q&A; // degrade fast past ~30% context utilization on long sessions. TierSmall = "small" )
Tier labels. Use these constants rather than string literals so future tier renames are mechanically findable.
Variables ¶
This section is empty.
Functions ¶
func Classify ¶
Classify returns the tier label for modelID, or "" when the model isn't recognized. Substring match — model IDs come in many flavors (date suffixes, "-1m" capacity tags, vertex publication names) and we want the lookup to land regardless.
The classifier is intentionally hand-maintained rather than derived from price metadata. Provider pricing changes independently from the underlying model's reasoning class, and the price-to-tier mapping would drift in ways that don't reflect what we actually care about here.
func DefaultCompactionThresholds ¶
DefaultCompactionThresholds is the per-tier compaction utilization table consumed by pkg/agent's DefaultCompactor. Values are fractions of the model's context window — compaction fires when `used / window >= threshold`.
The numbers are starting points, not measured optima — they're the design doc's best-guess defaults for v2.5. Tune from telemetry once we have it. Frontier stays at 0.85 to match the historical universal default so existing operators on frontier models see no behavior change. Mid and small drop because reasoning quality on those tiers falls off well before they hit the 0.85 line.
func IsSmall ¶
IsSmall reports whether modelID classifies as TierSmall. Unknown models return false rather than guessing — "don't fire the small-tier guard on something we can't classify" is the safer default (the alternative would fire false-positive warnings on every newly-released model the operator picks up before pkg/modeltier catches up).
Used by the small-tier-parent guard (#121) at startup; cheaper than callers re-implementing the Classify == TierSmall check and clearer at the call site.
Types ¶
This section is empty.
Source Files