routing

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: May 15, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package model provides model routing and health checking. Model discovery, pricing, and catalog data are delegated to eyrie. Hawk does NOT carry a hardcoded model catalog.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AllProviders 

func AllProviders() []string

AllProviders returns all provider names from eyrie's catalog.

func CheapestForProvider 

func CheapestForProvider(provider, fallback string) string

CheapestForProvider queries eyrie's catalog at runtime and returns the cheapest model for the given provider. No hardcoded model names.

func DefaultModel 

func DefaultModel(provider string) string

DefaultModel returns the default model for a provider via eyrie.

func MatchScore added in v0.2.0 

func MatchScore(rule TagRule, tags map[string]string) int

MatchScore returns the number of matching tags between a rule and a tag set. Returns 0 if any tag in the rule does not match (all rule tags must be present).

func RegisterDynamic 

func RegisterDynamic(info ModelInfo)

RegisterDynamic adds a model entry at runtime (custom providers).

Types

type Capabilities 

type Capabilities struct {
	Streaming       bool `json:"streaming"`
	FunctionCalling bool `json:"function_calling"`
	Vision          bool `json:"vision"`
	JSON            bool `json:"json"`
	Thinking        bool `json:"thinking"`
}

Capabilities describes what a model supports.

type CascadeRouter 

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

CascadeRouter selects models based on task classification. It uses heuristic keyword matching to avoid LLM calls for routing.

func NewCascadeRouter 

func NewCascadeRouter(roles ModelRoles) *CascadeRouter

NewCascadeRouter creates a cascade router with the given role assignments.

func (*CascadeRouter) ModelForTask 

func (cr *CascadeRouter) ModelForTask(task TaskType) string

ModelForTask returns the model assigned to the given task type.

func (*CascadeRouter) Route 

func (cr *CascadeRouter) Route(message string, hint TaskType) string

Route returns the model name for a given message. If hint is non-empty, it overrides the automatic classification.

type CircuitState 

type CircuitState int

CircuitState represents circuit breaker state. 

const (
	CircuitClosed   CircuitState = iota // normal
	CircuitOpen                         // rejecting
	CircuitHalfOpen                     // testing
)

type CodeHealth 

type CodeHealth struct {
	Complexity   float64 // cyclomatic complexity estimate
	FileSize     int     // lines of code
	Dependencies int     // import count
	TestCoverage float64 // if known (0-1)
	Language     string
}

CodeHealth captures complexity metrics for a source file, used to route tasks to the cheapest model that can handle the file's complexity.

type FallbackChain added in v0.2.0 

type FallbackChain struct {
	Providers      []ProviderConfig
	HealthStatus   map[string]*FallbackProviderHealth
	ActiveProvider string
	// contains filtered or unexported fields
}

FallbackChain manages multi-provider fallback with health tracking.

func NewFallbackChain added in v0.2.0 

func NewFallbackChain(providers []ProviderConfig) *FallbackChain

NewFallbackChain creates a new fallback chain from the given provider configs. Providers are sorted by priority (lower number = higher priority).

func (*FallbackChain) AllDown added in v0.2.0 

func (fc *FallbackChain) AllDown() bool

AllDown returns true if every provider is either down or in cooldown.

func (*FallbackChain) BestLatency added in v0.2.0 

func (fc *FallbackChain) BestLatency() *ProviderConfig

BestLatency returns the provider config with the lowest recent latency among healthy providers. Returns nil if no providers are healthy.

func (*FallbackChain) FormatStatus added in v0.2.0 

func (fc *FallbackChain) FormatStatus() string

FormatStatus returns a human-readable status report of all providers.

func (*FallbackChain) GetFallback added in v0.2.0 

func (fc *FallbackChain) GetFallback(currentProvider string) (*ProviderConfig, error)

GetFallback finds the next healthy provider after the current one in the chain.

func (*FallbackChain) IsHealthy added in v0.2.0 

func (fc *FallbackChain) IsHealthy(provider string) bool

IsHealthy returns true if the named provider is currently healthy and not in cooldown.

func (*FallbackChain) RecordFailure added in v0.2.0 

func (fc *FallbackChain) RecordFailure(provider string, err error)

RecordFailure records a failed call to a provider and applies cooldown if threshold exceeded.

func (*FallbackChain) RecordSuccess added in v0.2.0 

func (fc *FallbackChain) RecordSuccess(provider string, latency time.Duration)

RecordSuccess records a successful call to a provider and resets failure state.

func (*FallbackChain) RecoverProvider added in v0.2.0 

func (fc *FallbackChain) RecoverProvider(provider string)

RecoverProvider manually marks a provider as healthy and clears its cooldown.

func (*FallbackChain) SelectProvider added in v0.2.0 

func (fc *FallbackChain) SelectProvider() (*ProviderConfig, error)

SelectProvider picks the highest-priority healthy provider, skipping those in cooldown.

type FallbackProviderHealth added in v0.2.0 

type FallbackProviderHealth struct {
	Name                string
	Status              string // "healthy", "degraded", "down"
	LastSuccess         time.Time
	LastFailure         time.Time
	ConsecutiveFailures int
	CooldownUntil       *time.Time
	Latency             time.Duration
}

FallbackProviderHealth tracks detailed health state of a provider in the fallback chain.

type FallbackResult added in v0.2.0 

type FallbackResult struct {
	Provider  string
	Model     string
	Attempts  int
	Fallbacks []string
	Duration  time.Duration
}

FallbackResult captures the outcome of a provider selection with fallback.

type HealthRouter 

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

HealthRouter selects the cheapest appropriate model tier based on a file's code health metrics.

func NewHealthRouter 

func NewHealthRouter() *HealthRouter

NewHealthRouter creates a router with the default tier configuration.

func (*HealthRouter) ComputeHealth 

func (hr *HealthRouter) ComputeHealth(path string) CodeHealth

ComputeHealth estimates code health metrics for a file at the given path. It reads the file and analyses line count, nesting depth, and import count.

func (*HealthRouter) ModelForTask 

func (hr *HealthRouter) ModelForTask(path string, primaryModel string) string

ModelForTask returns the cheapest appropriate model for the file's health level. If the selected tier contains the primaryModel, it is returned. Otherwise, the first model in the selected tier is returned.

func (*HealthRouter) SelectTier 

func (hr *HealthRouter) SelectTier(health CodeHealth) string

SelectTier returns the tier name appropriate for the given code health.

  • "light": simple files (<100 lines, low complexity)
  • "standard": moderate files (100-500 lines)
  • "heavy": complex files (>500 lines, high complexity, many deps)

type LatencyClass 

type LatencyClass string

LatencyClass categorizes model response speed. 

const (
	LatencyFast   LatencyClass = "fast"
	LatencyMedium LatencyClass = "medium"
	LatencySlow   LatencyClass = "slow"
)

type ModelInfo 

type ModelInfo struct {
	Name        string  `json:"name"`
	Provider    string  `json:"provider"`
	ContextSize int     `json:"context_size"`
	InputPrice  float64 `json:"input_price_per_million"`
	OutputPrice float64 `json:"output_price_per_million"`
	Description string  `json:"description,omitempty"`
	Recommended bool    `json:"recommended,omitempty"`
}

ModelInfo describes a known LLM model (hawk's internal representation).

func ByProvider 

func ByProvider(provider string) []ModelInfo

ByProvider returns all models for a given provider from eyrie's catalog.

func Find 

func Find(name string) (ModelInfo, bool)

Find looks up a model by name across eyrie's catalog and dynamic entries. 

func Recommended(provider string) (ModelInfo, bool)

Recommended returns the recommended model for a provider. Delegates to eyrie's GetProviderDefaultModel.

type ModelRoles 

type ModelRoles struct {
	Planner  string `json:"planner,omitempty"`
	Coder    string `json:"coder,omitempty"`
	Reviewer string `json:"reviewer,omitempty"`
	Commit   string `json:"commit,omitempty"`
}

ModelRoles maps each role to a specific model name. Empty fields fall back to the primary (coder) model.

func DefaultRoles 

func DefaultRoles(primaryModel string) ModelRoles

DefaultRoles returns a ModelRoles where every role uses primaryModel except Commit, which defaults to the cheapest available model from the catalog.

func (ModelRoles) ModelForRole 

func (r ModelRoles) ModelForRole(role Role) string

ModelForRole returns the model name assigned to role, falling back to the Coder model (primary) if the role-specific field is empty.

type ModelTier 

type ModelTier struct {
	Name          string   // "light", "standard", "heavy"
	Models        []string // model names in this tier
	MaxComplexity float64  // max code health score for this tier
}

ModelTier groups models by the code complexity they can handle.

func DefaultTiers 

func DefaultTiers() []ModelTier

DefaultTiers returns the standard three-tier configuration.

type ProviderConfig added in v0.2.0 

type ProviderConfig struct {
	Name             string
	Model            string
	Priority         int
	Weight           float64
	MaxRetries       int
	CooldownDuration time.Duration
}

ProviderConfig describes a provider entry in the fallback chain.

type ProviderHealth 

type ProviderHealth struct {
	Available        bool      `json:"available"`
	LastCheck        time.Time `json:"last_check"`
	LastSuccess      time.Time `json:"last_success"`
	ConsecutiveFails int       `json:"consecutive_fails"`
	AvgLatencyMs     float64   `json:"avg_latency_ms"`
}

ProviderHealth tracks the health state of a provider.

type Role 

type Role string

Role identifies the purpose of a model within a multi-model workflow. 

const (
	RolePlanner  Role = "planner"
	RoleCoder    Role = "coder"
	RoleReviewer Role = "reviewer"
	RoleCommit   Role = "commit"
)

type Router 

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

Router provides health-aware provider routing with fallback.

func NewRouter 

func NewRouter(strategy RoutingStrategy) *Router

NewRouter creates a new provider router with a default fallback chain.

func (*Router) HealthStatus 

func (r *Router) HealthStatus() map[string]*ProviderHealth

HealthStatus returns health info for all tracked providers.

func (*Router) RecordFailure 

func (r *Router) RecordFailure(provider string, err error)

RecordFailure records a failed API call for a provider.

func (*Router) RecordSuccess 

func (r *Router) RecordSuccess(provider string, latency time.Duration)

RecordSuccess records a successful API call for a provider.

func (*Router) Score 

func (r *Router) Score(provider string) float64

Score returns a routing score for a provider (lower is better).

func (*Router) SelectProvider 

func (r *Router) SelectProvider(preferred string) (string, error)

SelectProvider chooses the best available provider, falling back if needed.

func (*Router) SelectProviderForModel 

func (r *Router) SelectProviderForModel(modelName string) (string, ModelInfo, error)

SelectProviderForModel chooses the best provider for a specific model.

func (*Router) SetFallbackChain 

func (r *Router) SetFallbackChain(chain []string)

SetFallbackChain sets the provider fallback order.

type RoutingDecision added in v0.2.0 

type RoutingDecision struct {
	Model       string   `json:"model"`
	Provider    string   `json:"provider"`
	MatchedRule *TagRule `json:"matched_rule,omitempty"`
	Reason      string   `json:"reason"`
}

RoutingDecision holds the result of tag-based routing.

type RoutingStrategy 

type RoutingStrategy string

RoutingStrategy determines how the router selects providers. 

const (
	StrategyLatency  RoutingStrategy = "latency"
	StrategyCost     RoutingStrategy = "cost"
	StrategyBalanced RoutingStrategy = "balanced"
)

type TagRouter added in v0.2.0 

type TagRouter struct {
	Rules        []TagRule `json:"rules"`
	DefaultModel string    `json:"default_model"`
	// contains filtered or unexported fields
}

TagRouter routes LLM requests to specific models based on metadata tags.

func NewTagRouter added in v0.2.0 

func NewTagRouter(defaultModel string) *TagRouter

NewTagRouter creates a new TagRouter with a default model and built-in rules.

func (*TagRouter) AddRule added in v0.2.0 

func (tr *TagRouter) AddRule(rule TagRule)

AddRule adds a routing rule to the router.

func (*TagRouter) FormatRules added in v0.2.0 

func (tr *TagRouter) FormatRules() string

FormatRules returns a human-readable summary of all routing rules.

func (*TagRouter) Load added in v0.2.0 

func (tr *TagRouter) Load(path string) error

Load reads the router's rules from a JSON file at the given path.

func (*TagRouter) Route added in v0.2.0 

func (tr *TagRouter) Route(tags map[string]string) *RoutingDecision

Route finds the best model for the given tags by matching against rules. All tags in a rule must match the request tags for the rule to apply. Among matching rules, the highest priority wins. Ties are broken by match score.

func (*TagRouter) RouteByContext added in v0.2.0 

func (tr *TagRouter) RouteByContext(task, language, complexity string) *RoutingDecision

RouteByContext auto-generates tags from context parameters and routes accordingly.

func (*TagRouter) Save added in v0.2.0 

func (tr *TagRouter) Save(path string) error

Save persists the router's rules to a JSON file at the given path.

type TagRule added in v0.2.0 

type TagRule struct {
	Tags        map[string]string `json:"tags"`
	Model       string            `json:"model"`
	Provider    string            `json:"provider"`
	Priority    int               `json:"priority"`
	Description string            `json:"description"`
}

TagRule defines a routing rule that maps metadata tags to a model/provider.

type TaskType 

type TaskType string

TaskType classifies a user message for model routing. 

const (
	TaskPlanning TaskType = "planning"
	TaskCoding   TaskType = "coding"
	TaskSummary  TaskType = "summary"
	TaskReview   TaskType = "review"
	TaskGeneral  TaskType = "general"
)

func ClassifyTask 

func ClassifyTask(message string) TaskType

ClassifyTask uses keyword heuristics to determine the task type from a message.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.