Module: Legion::LLM::Router

Extended by:
Legion::Logging::Helper
Defined in:
lib/legion/llm/router.rb,
lib/legion/llm/router/rule.rb,
lib/legion/llm/router/arbitrage.rb,
lib/legion/llm/router/resolution.rb,
lib/legion/llm/router/health_tracker.rb,
lib/legion/llm/router/escalation/chain.rb,
lib/legion/llm/router/gateway_interceptor.rb

Defined Under Namespace

Modules: Arbitrage, GatewayInterceptor Classes: EscalationChain, HealthTracker, Resolution, Rule

Constant Summary collapse

PROVIDER_TIER = 
{ bedrock: :cloud, anthropic: :frontier, openai: :frontier,
gemini: :cloud, azure: :cloud, ollama: :local, vllm: :local }.freeze
PROVIDER_ORDER = 
%i[ollama vllm bedrock azure gemini anthropic openai].freeze
OLLAMA_MODEL_PATTERN = 
%r{[:/]}

Class Method Summary collapse

Class Method Details

.health_tracker ⇒ Object 



72
73
74
 
# File 'lib/legion/llm/router.rb', line 72

def health_tracker
  @health_tracker ||= build_health_tracker
end

.infer_provider_for_model(model) ⇒ Object 



24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/legion/llm/router.rb', line 24

def infer_provider_for_model(model)
  return nil if model.nil? || model.to_s.empty?

  model_s = model.to_s
  return :bedrock if model_s.start_with?('us.')
  return :openai if model_s.match?(/\Agpt-|\Ao[134]-/)
  return :anthropic if model_s.start_with?('claude-')
  return :gemini if model_s.start_with?('gemini-')
  return :ollama if model_s.match?(OLLAMA_MODEL_PATTERN)

  nil
end

.reset! ⇒ Object 



85
86
87
 
# File 'lib/legion/llm/router.rb', line 85

def reset!
  @health_tracker = nil
end

.resolve(intent: nil, tier: nil, model: nil, provider: nil, exclude: {}) ⇒ Resolution?

Resolve an LLM routing intent to a tier/provider/model decision.

Parameters:

  • intent (Hash, nil) (defaults to: nil) —

    routing intent (capability, privacy, etc.)

  • tier (Symbol, nil) (defaults to: nil) —

    explicit tier override — skips rule matching

  • model (String, nil) (defaults to: nil) —

    explicit model override

  • provider (Symbol, nil) (defaults to: nil) —

    explicit provider override

Returns:



44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/legion/llm/router.rb', line 44

def resolve(intent: nil, tier: nil, model: nil, provider: nil, exclude: {})
  return explicit_resolution(tier, provider, model) if tier

  return nil unless routing_enabled? && intent

  merged = merge_defaults(intent)
  rules = load_rules
  candidates = select_candidates(rules, merged, exclude: exclude)
  best = pick_best(candidates)
  resolution = best&.to_resolution

  if resolution
    log.info("Routed to tier=#{resolution.tier} provider=#{resolution.provider} model=#{resolution.model} via rule='#{resolution.rule}'")
  else
    log.debug('Router: no rules matched, resolution is nil')
  end

  resolution || arbitrage_fallback(intent)
end

.resolve_chain(intent: nil, tier: nil, model: nil, provider: nil, max_escalations: nil, exclude: {}) ⇒ Object 



64
65
66
67
68
69
70
 
# File 'lib/legion/llm/router.rb', line 64

def resolve_chain(intent: nil, tier: nil, model: nil, provider: nil, max_escalations: nil, exclude: {})
  max = max_escalations || escalation_max_attempts
  return EscalationChain.new(resolutions: [explicit_resolution(tier, provider, model)], max_attempts: max) if tier
  return chain_from_defaults(model, provider, max) unless routing_enabled? && intent

  chain_from_intent(intent, max, exclude: exclude)
end

.routing_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


76
77
78
79
80
81
82
83
 
# File 'lib/legion/llm/router.rb', line 76

def routing_enabled?
  settings = routing_settings
  return false if settings.nil? || settings.empty?
  return false unless settings[:enabled]

  rules = settings[:rules]
  rules.is_a?(Array) && !rules.empty?
end

.tier_available?(tier) ⇒ Boolean

Check whether a tier can be used right now. :local — always available :fleet — available when Legion::Transport is loaded :openai_compat — available when gateways are configured :cloud — available unless privacy mode :frontier — available unless privacy mode

Returns:

  • (Boolean) 


95
96
97
98
99
100
101
102
 
# File 'lib/legion/llm/router.rb', line 95

def tier_available?(tier)
  sym = tier.to_sym
  return false if external_tier?(sym) && privacy_mode?
  return Legion.const_defined?('Transport', false) if sym == :fleet
  return openai_compat_available? if sym == :openai_compat

  true
end