Class: Legion::Extensions::Llm::Routing::Selection

Inherits:
Data
  • Object
show all
Defined in:
lib/legion/extensions/llm/routing/records.rb

Overview

An immutable selected target produced by legion-llm's selector and consumed by dispatch. lex-llm validates cross-field identity only; it does not compute routing or choose a lane. lane_id is the 5 tuple tier:provider_family:instance_id:type:model; the tier part is not a Selection member, so cross-field validation covers the four parts the record does carry (family, instance, type-from-operation, model). See section 15.4.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**kwargs) ⇒ Selection

Returns a new instance of Selection.



96
97
98
99
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 96

def initialize(**kwargs)
  Legion::Extensions::Llm::Inventory::RecordSupport.check_unknown_kwargs!(kwargs: kwargs, members: self.class.members)
  super(**identity_attributes(kwargs).merge(scoring_attributes(kwargs)))
end

Instance Attribute Details

#base_weight ⇒ Object (readonly)

Returns the value of attribute base_weight

Returns:

  • (Object) —

    the current value of base_weight



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def base_weight
  @base_weight
end

#callable_handle ⇒ Object (readonly)

Returns the value of attribute callable_handle

Returns:

  • (Object) —

    the current value of callable_handle



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def callable_handle
  @callable_handle
end

#capability_evidence ⇒ Object (readonly)

Returns the value of attribute capability_evidence

Returns:

  • (Object) —

    the current value of capability_evidence



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def capability_evidence
  @capability_evidence
end

#context_evidence ⇒ Object (readonly)

Returns the value of attribute context_evidence

Returns:

  • (Object) —

    the current value of context_evidence



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def context_evidence
  @context_evidence
end

#effective_weight ⇒ Object (readonly)

Returns the value of attribute effective_weight

Returns:

  • (Object) —

    the current value of effective_weight



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def effective_weight
  @effective_weight
end

#instance_id ⇒ Object (readonly)

Returns the value of attribute instance_id

Returns:

  • (Object) —

    the current value of instance_id



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def instance_id
  @instance_id
end

#instance_key ⇒ Object (readonly)

Returns the value of attribute instance_key

Returns:

  • (Object) —

    the current value of instance_key



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def instance_key
  @instance_key
end

#inventory_generation ⇒ Object (readonly)

Returns the value of attribute inventory_generation

Returns:

  • (Object) —

    the current value of inventory_generation



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def inventory_generation
  @inventory_generation
end

#lane_id ⇒ Object (readonly)

Returns the value of attribute lane_id

Returns:

  • (Object) —

    the current value of lane_id



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def lane_id
  @lane_id
end

#model ⇒ Object (readonly)

Returns the value of attribute model

Returns:

  • (Object) —

    the current value of model



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def model
  @model
end

#operation ⇒ Object (readonly)

Returns the value of attribute operation

Returns:

  • (Object) —

    the current value of operation



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def operation
  @operation
end

#preference_ppm ⇒ Object (readonly)

Returns the value of attribute preference_ppm

Returns:

  • (Object) —

    the current value of preference_ppm



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def preference_ppm
  @preference_ppm
end

#provider_family ⇒ Object (readonly)

Returns the value of attribute provider_family

Returns:

  • (Object) —

    the current value of provider_family



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def provider_family
  @provider_family
end

#publisher_token_id ⇒ Object (readonly)

Returns the value of attribute publisher_token_id

Returns:

  • (Object) —

    the current value of publisher_token_id



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def publisher_token_id
  @publisher_token_id
end

#rendezvous_score ⇒ Object (readonly)

Returns the value of attribute rendezvous_score

Returns:

  • (Object) —

    the current value of rendezvous_score



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def rendezvous_score
  @rendezvous_score
end

#weight_inputs ⇒ Object (readonly)

Returns the value of attribute weight_inputs

Returns:

  • (Object) —

    the current value of weight_inputs



91
92
93
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 91

def weight_inputs
  @weight_inputs
end

Instance Method Details

#attempt_target_key ⇒ Object 



163
164
165
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 163

def attempt_target_key
  AttemptTargetKey.new(provider_family: provider_family, instance_id: instance_id, model: model)
end

#identity_attributes(kwargs) ⇒ Object

Raises:

  • (errors::ValidationError) 


101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 101

def identity_attributes(kwargs)
  errors = Legion::Extensions::Llm::Inventory::Errors
  identity = Legion::Extensions::Llm::Inventory::Identity
  instance_key = kwargs[:instance_key]
  callable_handle = kwargs[:callable_handle]
  raise errors::ValidationError, 'instance_key must be an InstanceKey' unless instance_key.is_a?(identity::InstanceKey)
  raise errors::ValidationError, 'callable_handle must be a CallableHandle' unless callable_handle.is_a?(Legion::Extensions::Llm::Inventory::CallableHandle)

  canonical_model = identity.normalize_text(value: kwargs[:model], field: :model)
  canonical_operation = Legion::Extensions::Llm::Taxonomies.normalize_operation(value: kwargs[:operation])
  family = Legion::Extensions::Llm::Inventory::RecordSupport.normalize_provider_family(value: kwargs[:provider_family])
  normalized_instance = identity.normalize_text(value: kwargs[:instance_id], field: :instance_id)
  unless family == instance_key.provider_family && normalized_instance == instance_key.instance_id
    raise errors::ValidationError, 'provider_family and instance_id must equal instance_key'
  end

  identity.validate_lane_id!(value: kwargs[:lane_id])
  validate_lane_id_fields!(kwargs[:lane_id], family, normalized_instance, canonical_operation, canonical_model)
  validate_publisher_token_id!(kwargs[:publisher_token_id])

  {
    lane_id: kwargs[:lane_id].to_s.dup.freeze, instance_key: instance_key,
    provider_family: family, instance_id: normalized_instance, model: canonical_model,
    operation: canonical_operation, callable_handle: callable_handle,
    publisher_token_id: kwargs[:publisher_token_id].dup.freeze
  }
end

#scoring_attributes(kwargs) ⇒ Object 



148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 148

def scoring_attributes(kwargs)
  support = Legion::Extensions::Llm::Inventory::RecordSupport
  base_weight = kwargs[:base_weight]
  frozen_weight_inputs = validate_weight_inputs!(kwargs[:weight_inputs], base_weight)
  validate_weights!(base_weight, kwargs[:preference_ppm], kwargs[:effective_weight], kwargs[:rendezvous_score])

  {
    inventory_generation: support.nonnegative_integer(value: kwargs[:inventory_generation], field: :inventory_generation),
    capability_evidence: support.validate_capability_evidence!(kwargs[:capability_evidence]),
    context_evidence: support.positive_int_value_evidence!(kwargs[:context_evidence], :context_evidence),
    weight_inputs: frozen_weight_inputs, base_weight: base_weight, preference_ppm: kwargs[:preference_ppm],
    effective_weight: kwargs[:effective_weight], rendezvous_score: kwargs[:rendezvous_score]
  }
end

#validate_lane_id_fields!(lane_id, family, instance_id, operation, model) ⇒ Object

Cross-field check of the 5 tuple against the parts the Selection carries: provider_family (part 2), instance_id (part 3), type from the operation (part 4), and model (part 5, colons preserved by the bounded parse). Part 1 (tier) is checked against Taxonomies::TIERS by validate_lane_id!.

Raises:

  • (errors::ValidationError) 


134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 134

def validate_lane_id_fields!(lane_id, family, instance_id, operation, model)
  errors = Legion::Extensions::Llm::Inventory::Errors
  identity = Legion::Extensions::Llm::Inventory::Identity
  parts = identity.parse_lane_id(lane_id)
  raise errors::ValidationError, 'lane_id provider_family does not match the selection' \
    unless parts[1] == family.to_s
  raise errors::ValidationError, 'lane_id instance_id does not match the selection' \
    unless parts[2] == instance_id
  raise errors::ValidationError, 'lane_id type does not match the selection operation' \
    unless parts[3] == Legion::Extensions::Llm::Taxonomies.lane_type_for(operation: operation).to_s
  raise errors::ValidationError, 'lane_id model does not match the selection' \
    unless parts[4] == model
end

#validate_publisher_token_id!(publisher_token_id) ⇒ Object

Raises:



167
168
169
170
171
172
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 167

def validate_publisher_token_id!(publisher_token_id)
  return if publisher_token_id.is_a?(::String) && publisher_token_id.start_with?('ptok:v1:') &&
            publisher_token_id.length > 'ptok:v1:'.length

  raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'publisher_token_id must be a ptok:v1: String'
end

#validate_weight_inputs!(weight_inputs, base_weight) ⇒ Object

U4: structural verification only — same semantics as RecordSupport.validated_weight_pair, never a second weight policy. 0 is a legal value (operator disable, 07 W3); base_weight must equal the product of the inputs.

Raises:

  • (errors::ValidationError) 


178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 178

def validate_weight_inputs!(weight_inputs, base_weight)
  errors = Legion::Extensions::Llm::Inventory::Errors
  unless weight_inputs.is_a?(::Hash) && weight_inputs.keys.sort == %i[instance model_or_offering provider tier]
    raise errors::ValidationError, 'weight_inputs must have keys tier/provider/instance/model_or_offering'
  end
  raise errors::ValidationError, 'weight_inputs values must be nonnegative Integers' unless weight_inputs.values.all? { |value| value.is_a?(::Integer) && !value.negative? }

  product = weight_inputs.values.reduce(1, :*)
  raise errors::ValidationError, 'base_weight must equal the product of weight_inputs' unless base_weight == product

  weight_inputs.dup.freeze
end

#validate_weights!(base_weight, preference_ppm, effective_weight, rendezvous_score) ⇒ Object

Raises:

  • (errors::ValidationError) 


191
192
193
194
195
196
197
198
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 191

def validate_weights!(base_weight, preference_ppm, effective_weight, rendezvous_score)
  errors = Legion::Extensions::Llm::Inventory::Errors
  raise errors::ValidationError, 'preference_ppm must be an Integer in 500_000..1_500_000' unless preference_ppm.is_a?(::Integer) && (500_000..1_500_000).cover?(preference_ppm)
  raise errors::ValidationError, 'effective_weight must equal base_weight * preference_ppm' unless effective_weight == base_weight * preference_ppm
  return if rendezvous_score.is_a?(::Integer) && (0...(2**256)).cover?(rendezvous_score)

  raise errors::ValidationError, 'rendezvous_score must be an Integer in 0...(2**256)'
end