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. See section 15.4.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**kwargs) ⇒ Selection

Returns a new instance of Selection.



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

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

def lane_id
  @lane_id
end

#model ⇒ Object (readonly)

Returns the value of attribute model

Returns:

  • (Object) —

    the current value of model



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

def model
  @model
end

#offering_id ⇒ Object (readonly)

Returns the value of attribute offering_id

Returns:

  • (Object) —

    the current value of offering_id



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

def offering_id
  @offering_id
end

#operation ⇒ Object (readonly)

Returns the value of attribute operation

Returns:

  • (Object) —

    the current value of operation



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

def operation
  @operation
end

#preference_ppm ⇒ Object (readonly)

Returns the value of attribute preference_ppm

Returns:

  • (Object) —

    the current value of preference_ppm



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

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



87
88
89
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 87

def weight_inputs
  @weight_inputs
end

Instance Method Details

#attempt_target_key ⇒ Object 



144
145
146
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 144

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

#identity_attributes(kwargs) ⇒ Object

Raises:

  • (errors::ValidationError) 


97
98
99
100
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 97

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], allow_aliases: false)
  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

  offering_id = kwargs[:offering_id]
  validate_offering_id_shape!(offering_id)
  identity.validate_lane_id!(
    value: kwargs[:lane_id], instance_key: instance_key, operation: canonical_operation,
    model: canonical_model, offering_id: offering_id
  )
  validate_publisher_token_id!(kwargs[:publisher_token_id])

  {
    lane_id: kwargs[:lane_id].dup.freeze, instance_key: instance_key, offering_id: offering_id.dup.freeze,
    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 



129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 129

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_offering_id_shape!(offering_id) ⇒ Object

Raises:



148
149
150
151
152
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 148

def validate_offering_id_shape!(offering_id)
  return if offering_id.is_a?(::String) && offering_id.match?(/\Aoff:v1:[0-9a-f]{64}\z/)

  raise Legion::Extensions::Llm::Inventory::Errors::ValidationError, 'offering_id must have the off:v1: shape'
end

#validate_publisher_token_id!(publisher_token_id) ⇒ Object

Raises:



154
155
156
157
158
159
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 154

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

Raises:

  • (errors::ValidationError) 


161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 161

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 positive Integers' unless weight_inputs.values.all? { |value| value.is_a?(::Integer) && value.positive? }

  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) 


174
175
176
177
178
179
180
181
 
# File 'lib/legion/extensions/llm/routing/records.rb', line 174

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