Class: Legion::LLM::Router::SettingsSnapshot

Inherits:
Object
  • Object
show all
Includes:
Legion::Logging::Helper
Defined in:
lib/legion/llm/router/settings_snapshot.rb

Overview

Immutable, validated snapshot of all selection-relevant settings for one reload generation. Built once by SettingsState.install!/reload! and consumed read-only by every selection call. Runtime selection never reaches back into Legion::Settings.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#affinity_strength_bps ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def affinity_strength_bps
  @affinity_strength_bps
end

#allow_body_routing_hints ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def allow_body_routing_hints
  @allow_body_routing_hints
end

#auto_routing_model_alias_metadata ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def auto_routing_model_alias_metadata
  @auto_routing_model_alias_metadata
end

#auto_routing_model_aliases ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def auto_routing_model_aliases
  @auto_routing_model_aliases
end

#body_model_hint_blacklist ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def body_model_hint_blacklist
  @body_model_hint_blacklist
end

#body_model_hint_whitelist ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def body_model_hint_whitelist
  @body_model_hint_whitelist
end

#context_headroom_ppm ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def context_headroom_ppm
  @context_headroom_ppm
end

#generation ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def generation
  @generation
end

#input_framing_overhead_tokens ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def input_framing_overhead_tokens
  @input_framing_overhead_tokens
end

#maximum_attempts ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def maximum_attempts
  @maximum_attempts
end

#routing_too_early_retry_after ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def routing_too_early_retry_after
  @routing_too_early_retry_after
end

#tier_weights ⇒ Object (readonly)

------------------------------------------------------------------ # Readers # ------------------------------------------------------------------ #



41
42
43
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 41

def tier_weights
  @tier_weights
end

Class Method Details

.build(generation:, llm_settings:, extension_settings:) ⇒ Object

------------------------------------------------------------------ # Public factory # ------------------------------------------------------------------ #



29
30
31
32
33
34
35
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 29

def self.build(generation:, llm_settings:, extension_settings:)
  snap = new(generation:         generation,
             llm_settings:       llm_settings,
             extension_settings: extension_settings)
  snap.freeze
  snap
end

Instance Method Details

#capability_override_for(provider_family:, instance_id:, capability:, model:) ⇒ Object

The operator's cascaded enable_ routing override for the exact instance (config name), resolved through the lex-llm 3-level cascade (provider -> instance -> model, most-specific-first). Returns true or false when the operator configured it; nil when unset. Routing-side read only: providers do not publish the override as capability evidence (config remains unknown-only evidence).



98
99
100
101
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 98

def capability_override_for(provider_family:, instance_id:, capability:, model:)
  cascade_value(provider_family: provider_family, instance_id: instance_id,
                key: :"enable_#{capability}", model: model)
end

#model_policy_for(offering:) ⇒ Object

Returns { whitelist: Array, blacklist: Array } using the §9.5 specificity cascade: exact provider+instance → provider → global. "First scope whose key EXISTS, including explicit empty Array."



106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 106

def model_policy_for(offering:)
  ik   = offering.instance_key
  pf   = ik.provider_family   # Symbol
  iid  = ik.instance_id       # String
  prov = ext_llm_provider(pf)
  inst = ext_llm_instance(prov, iid)

  wl = first_existing_policy(inst, prov, :model_whitelist)
  bl = first_existing_policy(inst, prov, :model_blacklist)

  { whitelist: Array(wl).freeze, blacklist: Array(bl).freeze }.freeze
end

#preferred_context_range_for(lane:) ⇒ Object

Returns { min: Integer_or_nil, max: Integer_or_nil } or nil when no preferred range is configured. Resolved through the lex-llm 3-level cascade (provider -> instance -> model, most-specific-first) keyed by the config name, so a provider- or model-level leg can supply either bound.



82
83
84
85
86
87
88
89
90
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 82

def preferred_context_range_for(lane:)
  min_v = cascade_value(provider_family: lane.provider_family, instance_id: lane.instance_id,
                        key: :preferred_min_context_tokens, model: lane.model)
  max_v = cascade_value(provider_family: lane.provider_family, instance_id: lane.instance_id,
                        key: :preferred_max_context_tokens, model: lane.model)
  return nil unless min_v || max_v

  { min: min_v, max: max_v }.freeze
end

#weight_inputs_for(lane:) ⇒ Object

Returns a frozen Hash { tier:, provider:, instance:, model_or_offering: } where each value is a positive Integer >= 1 (missing component → identity 1). The provider/instance/model scopes are read through the lex-llm cascade, keyed by the config name (lane.instance_id): the instance leg is instances., the model leg is the instance's models. entry overriding the provider's models. entry. A zero tier weight is stored as-is (disabled lane); callers check for zero.



65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/legion/llm/router/settings_snapshot.rb', line 65

def weight_inputs_for(lane:)
  tier_w  = tier_weights[lane.tier] || IDENTITY_WEIGHT
  prov    = ext_llm_provider(lane.provider_family)
  inst    = ext_llm_instance(prov, lane.instance_id)
  prov_w  = CASCADE.lookup(prov, :weight) || IDENTITY_WEIGHT
  inst_w  = CASCADE.lookup(inst, :weight) || IDENTITY_WEIGHT
  off_entry = CASCADE.lookup(CASCADE.lookup(prov, :offerings), lane.offering_id)
  model_cfg = CASCADE.merge_model_scopes(provider_conf: prov, instance_cfg: inst, model: lane.model)
  model_w = CASCADE.lookup(off_entry, :weight) || CASCADE.lookup(model_cfg, :weight) || IDENTITY_WEIGHT
  { tier: tier_w, provider: prov_w, instance: inst_w, model_or_offering: model_w }.freeze
end