Class: Legion::LLM::Router::RequestRequirements

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

Overview

Immutable selector input (SSOT v3 §9.3). Built once per logical request from the canonical Request. Pins come from trusted constraints plus the honored body-model decision (trusted model wins); the routing seed, max attempts, and affinity strength come from the ingress-captured settings snapshot / routing context. No default provider or model exists here.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(request:, operation:, required_capabilities:, estimated_input_bound:, required_output_tokens:, requested_embedding_dimensions:, tier_constraint:, tier_preference:, routing_affinities:, policy_context:) ⇒ RequestRequirements

Returns a new instance of RequestRequirements.



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/legion/llm/router/request_requirements.rb', line 43

def initialize(request:, operation:, required_capabilities:, estimated_input_bound:,
               required_output_tokens:, requested_embedding_dimensions:, tier_constraint:,
               tier_preference:, routing_affinities:, policy_context:)
  snapshot = request.routing_settings_snapshot
  trusted = request.trusted_constraints
  decision = request.body_model_hint_decision

  @operation = validate_operation!(operation)
  @required_capabilities = Legion::Extensions::Llm::Capabilities.normalize(required_capabilities).freeze
  @estimated_input_bound = nonneg_int!(estimated_input_bound, :estimated_input_bound)
  @required_output_tokens = nonneg_int!(required_output_tokens, :required_output_tokens)
  @required_context_budget = @estimated_input_bound + @required_output_tokens
  @requested_embedding_dimensions = validate_dimensions!(requested_embedding_dimensions)

  @provider_pin = trusted.provider&.to_sym
  @instance_pin = trusted.instance_id
  @model_pin = resolve_model_pin(trusted, decision)
  @tier_constraint = validate_tier!(tier_constraint || trusted.tier)
  @tier_preference = validate_tier!(tier_preference)

  @routing_seed = validate_seed!(request.routing_context.routing_seed)
  @maximum_attempts = positive_int!(trusted.maximum_attempts || snapshot.maximum_attempts, :maximum_attempts)
  @affinity_strength_bps = snapshot.affinity_strength_bps
  @routing_affinities = normalize_affinities(routing_affinities)
  @policy_context = deep_freeze(symbolize(policy_context))
  @body_model_hint_decision = decision
  freeze
end

Instance Attribute Details

#affinity_strength_bps ⇒ Object (readonly)

Returns the value of attribute affinity_strength_bps.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def affinity_strength_bps
  @affinity_strength_bps
end

#body_model_hint_decision ⇒ Object (readonly)

Returns the value of attribute body_model_hint_decision.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def body_model_hint_decision
  @body_model_hint_decision
end

#estimated_input_bound ⇒ Object (readonly)

Returns the value of attribute estimated_input_bound.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def estimated_input_bound
  @estimated_input_bound
end

#instance_pin ⇒ Object (readonly)

Returns the value of attribute instance_pin.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def instance_pin
  @instance_pin
end

#maximum_attempts ⇒ Object (readonly)

Returns the value of attribute maximum_attempts.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def maximum_attempts
  @maximum_attempts
end

#model_pin ⇒ Object (readonly)

Returns the value of attribute model_pin.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def model_pin
  @model_pin
end

#operation ⇒ Object (readonly)

Returns the value of attribute operation.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def operation
  @operation
end

#policy_context ⇒ Object (readonly)

Returns the value of attribute policy_context.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def policy_context
  @policy_context
end

#provider_pin ⇒ Object (readonly)

Returns the value of attribute provider_pin.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def provider_pin
  @provider_pin
end

#requested_embedding_dimensions ⇒ Object (readonly)

Returns the value of attribute requested_embedding_dimensions.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def requested_embedding_dimensions
  @requested_embedding_dimensions
end

#required_capabilities ⇒ Object (readonly)

Returns the value of attribute required_capabilities.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def required_capabilities
  @required_capabilities
end

#required_context_budget ⇒ Object (readonly)

Returns the value of attribute required_context_budget.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def required_context_budget
  @required_context_budget
end

#required_output_tokens ⇒ Object (readonly)

Returns the value of attribute required_output_tokens.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def required_output_tokens
  @required_output_tokens
end

#routing_affinities ⇒ Object (readonly)

Returns the value of attribute routing_affinities.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def routing_affinities
  @routing_affinities
end

#routing_seed ⇒ Object (readonly)

Returns the value of attribute routing_seed.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def routing_seed
  @routing_seed
end

#tier_constraint ⇒ Object (readonly)

Returns the value of attribute tier_constraint.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def tier_constraint
  @tier_constraint
end

#tier_preference ⇒ Object (readonly)

Returns the value of attribute tier_preference.



14
15
16
 
# File 'lib/legion/llm/router/request_requirements.rb', line 14

def tier_preference
  @tier_preference
end

Class Method Details

.build(request:, operation:, required_capabilities:, estimated_input_bound:, required_output_tokens:, requested_embedding_dimensions: nil, tier_constraint: nil, tier_preference: nil, routing_affinities: [], policy_context: {}) ⇒ Object 



20
21
22
23
24
25
26
27
 
# File 'lib/legion/llm/router/request_requirements.rb', line 20

def self.build(request:, operation:, required_capabilities:, estimated_input_bound:,
               required_output_tokens:, requested_embedding_dimensions: nil,
               tier_constraint: nil, tier_preference: nil, routing_affinities: [], policy_context: {})
  new(request: request, operation: operation, required_capabilities: required_capabilities,
      estimated_input_bound: estimated_input_bound, required_output_tokens: required_output_tokens,
      requested_embedding_dimensions: requested_embedding_dimensions, tier_constraint: tier_constraint,
      tier_preference: tier_preference, routing_affinities: routing_affinities, policy_context: policy_context)
end

Instance Method Details

#without_model_pin ⇒ Object

SSOT v3 v2-parity hint fallback (Router.next_lane model_hint_miss): a frozen copy with ONLY the model pin cleared, so an honored body-model hint that matched no candidate falls back to normal weighted selection. Trusted X-Legion-Model pins never use this path — explicit pins stay hard.



33
34
35
36
37
38
39
40
41
 
# File 'lib/legion/llm/router/request_requirements.rb', line 33

def without_model_pin
  variant = self.class.allocate
  instance_variables.each do |ivar|
    variant.instance_variable_set(ivar, instance_variable_get(ivar)) unless ivar == :@model_pin
  end
  variant.instance_variable_set(:@model_pin, nil)
  variant.freeze
  variant
end