Module: Legion::LLM::Discovery::RuleGenerator

Extended by:
Legion::Logging::Helper
Defined in:
lib/legion/llm/discovery/rule_generator.rb

Constant Summary collapse

EMBEDDING_PATTERNS = 
%w[
  embed mxbai-embed nomic-embed bge- snowflake-arctic-embed
  text-embedding titan-embed
].freeze
DISCOVERABLE_PROVIDERS = 
%i[ollama mlx vllm].freeze
TIER_MAP = 
{
  ollama:    :local,
  mlx:       :local,
  vllm:      :fleet,
  openai:    :cloud,
  bedrock:   :cloud,
  azure:     :cloud,
  gemini:    :cloud,
  anthropic: :frontier
}.freeze
DEFAULT_TIER_PRIORITY = 
%i[local direct fleet cloud frontier].freeze
CAPABILITY_ALIASES = 
{
  function_calling: :tools,
  functions:        :tools,
  tool:             :tools,
  tool_use:         :tools,
  stream:           :streaming,
  stream_chat:      :streaming
}.freeze

Class Method Summary collapse

Class Method Details

.blank_array?(value) ⇒ Boolean

Returns:

  • (Boolean) 


311
312
313
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 311

def blank_array?(value)
  Array(value).empty?
end

.build_rule(provider, instance, model_data, capability, tier, priority, instance_capabilities: []) ⇒ Object 



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 135

def build_rule(provider, instance, model_data, capability, tier, priority, instance_capabilities: [])
  model_name = model_data.is_a?(Hash) ? (model_data[:name] || model_data['name']).to_s : model_data.to_s
  sources = extract_capability_sources(model_data)
  target = {
    provider:           provider.to_sym,
    instance:           instance.to_sym,
    model:              model_name,
    tier:               tier,
    effort:             effort_for_tier(tier),
    model_capabilities: merged_capabilities(model_data, instance_capabilities),
    capability_sources: sources.empty? ? nil : sources,
    context_length:     extract_field(model_data, :context_length),
    parameter_count:    extract_field(model_data, :parameter_count),
    loaded:             extract_boolean_field(model_data, :loaded)
  }.compact
  {
    name:     "auto:#{provider}/#{instance}:#{model_name}:#{capability}",
    when:     { operation: operation_for(capability) },
    then:     target,
    priority: priority
  }
end

.effort_for_tier(tier) ⇒ Object 



171
172
173
174
175
176
177
178
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 171

def effort_for_tier(tier)
  case tier&.to_sym
  when :local, :direct then :low
  when :fleet then :moderate
  when :cloud then :high
  when :frontier then :reasoning
  end
end

.embedding_model?(model_data) ⇒ Boolean

Returns:

  • (Boolean) 


95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 95

def embedding_model?(model_data)
  if model_data.is_a?(Hash)
    caps = model_data[:capabilities] || model_data['capabilities']
    return caps.any? { |c| c.to_s == 'embedding' } if caps.is_a?(Array) && caps.any?
  end

  # Fall back to name pattern matching when no capability data
  name = model_data.is_a?(Hash) ? (model_data[:name] || model_data['name']).to_s : model_data.to_s
  name = name.downcase
  EMBEDDING_PATTERNS.any? { |pat| name.include?(pat) }
end

.extension_providers ⇒ Object 



315
316
317
318
319
320
321
322
323
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 315

def extension_providers
  ext = Legion::Settings[:extensions]
  return ext[:llm] if ext.is_a?(Hash) && ext[:llm].is_a?(Hash)

  {}
rescue StandardError => e
  handle_exception(e, level: :debug, handled: true, operation: 'rule_generator.extension_providers')
  {}
end

.extract_boolean_field(model_data, field) ⇒ Object 



271
272
273
274
275
276
277
278
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 271

def extract_boolean_field(model_data, field)
  return nil unless model_data.is_a?(Hash)

  return model_data[field] if model_data.key?(field)
  return model_data[field.to_s] if model_data.key?(field.to_s)

  nil
end

.extract_capabilities(model_data) ⇒ Object 



207
208
209
210
211
212
213
214
215
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 207

def extract_capabilities(model_data)
  return nil unless model_data.is_a?(Hash)

  caps = model_data[:capabilities] || model_data['capabilities']
  normalized = normalize_capabilities(caps)
  return normalized if normalized.any?

  nil
end

.extract_capability_sources(model_data) ⇒ Object 



280
281
282
283
284
285
286
287
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 280

def extract_capability_sources(model_data)
  return {} unless model_data.is_a?(Hash)

  sources = model_data[:capability_sources] || model_data['capability_sources']
  return {} unless sources.is_a?(Hash)

  sources.transform_keys { |k| k.respond_to?(:to_sym) ? k.to_sym : k }
end

.extract_field(model_data, field) ⇒ Object 



265
266
267
268
269
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 265

def extract_field(model_data, field)
  return nil unless model_data.is_a?(Hash)

  model_data[field] || model_data[field.to_s]
end

.extract_instance_capabilities(instance_data) ⇒ Object

Capabilities advertised by the instance (provider-level) — the provider extension’s ‘discover_instances` may declare e.g. `capabilities: %i[completion streaming vision tools]` for an OpenAI-compatible instance even when its per-model offerings hash does not. Those capabilities flow through to chat rules so the router can satisfy `required_capabilities=` intents (G14).



90
91
92
93
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 90

def extract_instance_capabilities(instance_data)
  caps = instance_data[:capabilities] || instance_data['capabilities']
  normalize_capabilities(caps)
end

.generate(discovered_instances) ⇒ Object 



41
42
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
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 41

def generate(discovered_instances)
  rules = []
  discovered_instances.each do |provider, instances|
    next unless DISCOVERABLE_PROVIDERS.include?(provider.to_sym)
    next unless instances.is_a?(Hash)

    tier = TIER_MAP[provider.to_sym] || :local
    order = 0
    instances.each do |instance_id, data|
      models = data.is_a?(Hash) ? Array(data[:models]) : []
      instance_capabilities = data.is_a?(Hash) ? extract_instance_capabilities(data) : []

      models.each do |model|
        model_data = model.is_a?(Hash) ? model : { name: model.to_s }
        model_name = (model_data[:name] || model_data['name']).to_s
        next if model_name.empty?

        model_tier = extract_field(model_data, :tier)&.to_sym ||
                     extract_field(model_data, 'tier')&.to_sym ||
                     tier
        capability = embedding_model?(model_data) ? :embed : :chat
        priority = tier_weight(model_tier) - order
        rules << build_rule(provider, instance_id, model_data, capability, model_tier, priority,
                            instance_capabilities: instance_capabilities)
        if capability == :chat
          if supports_streaming?(model_data, instance_capabilities: instance_capabilities)
            rules << build_rule(provider, instance_id, model_data, :stream, model_tier, priority,
                                instance_capabilities: instance_capabilities)
          end
          if supports_tools?(model_data, instance_capabilities: instance_capabilities)
            rules << build_rule(provider, instance_id, model_data, :tools, model_tier, priority,
                                instance_capabilities: instance_capabilities)
          end
        end
        order += 1
      end
    end
  end

  rules += generate_configured_provider_rules
  rules.sort_by { |r| -r[:priority] }
end

.generate_configured_provider_rules ⇒ Object 



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 107

def generate_configured_provider_rules
  rules = []
  providers_config = extension_providers
  return rules unless providers_config.is_a?(Hash)

  providers_config.each do |provider_name, config|
    next unless config.is_a?(Hash)
    next if config[:enabled] == false
    next if DISCOVERABLE_PROVIDERS.include?(provider_name.to_sym)

    tier = TIER_MAP[provider_name.to_sym]
    next unless tier

    default_model = config[:default_model]
    next unless default_model

    model_data = { name: default_model }
    priority = tier_weight(tier)
    rules << build_rule(provider_name, :default, model_data, :chat, tier, priority)
    rules << build_rule(provider_name, :default, model_data, :stream, tier, priority)
  end

  rules
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'llm.discovery.rule_generator.configured_providers')
  []
end

.merged_capabilities(model_data, instance_capabilities) ⇒ Object

Merge per-model capabilities with instance-level capabilities. When the model carries source-tagged capability data (capability_sources), only capabilities with a positive (truthy) value are included. Instance capabilities are NOT merged in this case — the source-tagged data is authoritative and instance caps must not override an explicit false. When no sources are present, fall back to the legacy merge behavior.



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 186

def merged_capabilities(model_data, instance_capabilities)
  sources = extract_capability_sources(model_data)
  if sources.any?
    # Source-tagged: only include capabilities confirmed true by sources.
    confirmed = sources.each_with_object([]) do |(cap, meta), acc|
      acc << cap.to_sym if meta.is_a?(Hash) && meta[:value] != false
    end
    normalized = normalize_capabilities(confirmed)
    # Also include per-model capabilities that are not overridden by sources
    per_model = extract_capabilities(model_data) || []
    source_keys = sources.keys.map { |k| k.to_s.downcase.strip.to_sym }
    non_overridden = per_model.reject { |c| source_keys.include?(c) }
    merged = (normalized + non_overridden).uniq
    return merged.empty? ? nil : merged
  end

  per_model = extract_capabilities(model_data) || []
  merged = (per_model + Array(instance_capabilities)).uniq
  merged.empty? ? nil : merged
end

.normalize_capabilities(capabilities) ⇒ Object 



252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 252

def normalize_capabilities(capabilities)
  Array(capabilities).compact.each_with_object([]) do |capability, normalized|
    next unless capability.respond_to?(:to_s)

    capability_sym = capability.to_s.downcase.strip.to_sym
    next if capability_sym.to_s.empty?

    normalized << capability_sym
    alias_sym = CAPABILITY_ALIASES[capability_sym]
    normalized << alias_sym if alias_sym
  end.uniq
end

.operation_for(capability) ⇒ Object 



158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 158

def operation_for(capability)
  case capability.to_sym
  when :chat, :tools
    :chat
  when :stream
    :stream
  when :embed
    :embed
  else
    capability.to_sym
  end
end

.supports_streaming?(model_data, instance_capabilities: []) ⇒ Boolean

Returns:

  • (Boolean) 


217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 217

def supports_streaming?(model_data, instance_capabilities: [])
  sources = extract_capability_sources(model_data)
  if sources.any?
    streaming_source = sources[:streaming] || sources['streaming']
    # If source explicitly says false, no streaming rule
    return false if streaming_source.is_a?(Hash) && streaming_source[:value] == false
    # If source explicitly says true, emit streaming rule
    return true if streaming_source.is_a?(Hash) && streaming_source[:value] == true

    # No explicit streaming source — do NOT assume streaming
    return false
  end

  merged = merged_capabilities(model_data, instance_capabilities)
  return true if merged.nil?

  merged.include?(:streaming)
end

.supports_tools?(model_data, instance_capabilities: []) ⇒ Boolean

Returns:

  • (Boolean) 


236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 236

def supports_tools?(model_data, instance_capabilities: [])
  sources = extract_capability_sources(model_data)
  if sources.any?
    tools_source = sources[:tools] || sources['tools']
    return false if tools_source.is_a?(Hash) && tools_source[:value] == false
    return true if tools_source.is_a?(Hash) && tools_source[:value] == true

    return false
  end

  merged = merged_capabilities(model_data, instance_capabilities)
  return false if merged.nil?

  merged.include?(:tools)
end

.tier_priority ⇒ Object 



297
298
299
300
301
302
303
304
305
306
307
308
309
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 297

def tier_priority
  configured = Legion::Settings[:llm][:tier_order]
  configured = Legion::Settings[:llm][:routing][:tier_order] if blank_array?(configured)
  configured = Legion::Settings[:llm][:routing][:tier_priority] if blank_array?(configured)
  normalized = Array(configured).filter_map do |tier|
    tier.to_sym if tier.respond_to?(:to_sym)
  end
  normalized = DEFAULT_TIER_PRIORITY if normalized.empty?
  (normalized + DEFAULT_TIER_PRIORITY).uniq
rescue StandardError => e
  handle_exception(e, level: :warn, handled: true, operation: 'rule_generator.tier_priority')
  DEFAULT_TIER_PRIORITY
end

.tier_weight(tier) ⇒ Object 



289
290
291
292
293
294
295
 
# File 'lib/legion/llm/discovery/rule_generator.rb', line 289

def tier_weight(tier)
  tier_sym = tier.respond_to?(:to_sym) ? tier.to_sym : tier
  index = tier_priority.index(tier_sym)
  return 0 unless index

  (tier_priority.length - index) * 100
end