arbitrage

Documentation

Overview

Package arbitrage provides cost optimization for model selection. It scores task complexity and compares pricing across providers to suggest the most cost-effective model that meets the task's capability requirements.

Index

• func ShouldArbitrage(currentCost, alternativeCost, threshold float64) bool
• type ArbitrageRecommendation
  • func Recommend(models []types.ModelInfo, task types.Task, threshold float64) (*ArbitrageRecommendation, error)
• type ComplexityLevel
• type CostEstimate
  • func CompareModels(models []types.ModelInfo, inputTokens, outputTokens int) []CostEstimate
• type Scorer
  • func NewScorer(simpleThreshold, complexThreshold int) *Scorer
  • func (s *Scorer) EstimateTokens(complexity ComplexityLevel, task types.Task) (int, int)
  • func (s *Scorer) Score(task types.Task) (ComplexityLevel, int)

Functions

func ShouldArbitrage

func ShouldArbitrage(currentCost, alternativeCost, threshold float64) bool

ShouldArbitrage returns true when switching from the current model to the alternative would save more than the threshold proportion of the current cost.

Types

type ArbitrageRecommendation

type ArbitrageRecommendation struct {
	RecommendedModel CostEstimate    `json:"recommended_model"`
	Alternatives     []CostEstimate  `json:"alternatives"`
	Complexity       ComplexityLevel `json:"complexity"`
	Savings          float64         `json:"savings"`
	Reason           string          `json:"reason"`
}

ArbitrageRecommendation holds the recommended model and alternatives.

func Recommend

func Recommend(models []types.ModelInfo, task types.Task, threshold float64) (*ArbitrageRecommendation, error)

Recommend scores a task, estimates tokens, compares models, and returns the best model recommendation. For complex tasks the cheapest model may be rejected if its context window is insufficient (<=64K). When the cheapest is rejected, the next model whose cost is within the threshold factor is selected.

type ComplexityLevel

type ComplexityLevel string

ComplexityLevel represents the complexity classification of a task.

const (
	ComplexitySimple   ComplexityLevel = "simple"
	ComplexityModerate ComplexityLevel = "moderate"
	ComplexityComplex  ComplexityLevel = "complex"
)

type CostEstimate

type CostEstimate struct {
	ModelID      string  `json:"model_id"`
	Provider     string  `json:"provider"`
	InputCost    float64 `json:"input_cost"`
	OutputCost   float64 `json:"output_cost"`
	TotalCost    float64 `json:"total_cost"`
	Currency     string  `json:"currency"`
	InputTokens  int     `json:"input_tokens"`
	OutputTokens int     `json:"output_tokens"`
}

CostEstimate holds the cost estimate for a model given estimated token counts.

func CompareModels

func CompareModels(models []types.ModelInfo, inputTokens, outputTokens int) []CostEstimate

CompareModels computes cost estimates for each model and returns them sorted ascending by TotalCost. Models where both Pricing fields are zero are skipped.

type Scorer

type Scorer struct {
	SimpleThreshold  int
	ComplexThreshold int
}

Scorer evaluates task complexity and estimates token usage.

func NewScorer

func NewScorer(simpleThreshold, complexThreshold int) *Scorer

NewScorer creates a Scorer with the given thresholds. Values <= 0 are replaced with defaults (SimpleThreshold=2000, ComplexThreshold=8000).

func (*Scorer) EstimateTokens

func (s *Scorer) EstimateTokens(complexity ComplexityLevel, task types.Task) (int, int)

EstimateTokens returns estimated input and output tokens for a given complexity level and task. Per-file adjustments add 500 tokens each.

func (*Scorer) Score

func (s *Scorer) Score(task types.Task) (ComplexityLevel, int)

Score classifies task complexity based on keyword analysis and boost rules. Returns the complexity level and the estimated total token count.