legion-llm 0.3.1

data/lib/legion/llm/transport/messages/escalation_event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Transport
+      module Messages
+        class EscalationEvent < ::Legion::Transport::Message
+          routing_key 'llm.escalation.completed'
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    VERSION = '0.3.1'
+  end
+end

data/lib/legion/llm.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'legion/llm/version'
+require 'legion/llm/settings'
+require 'legion/llm/providers'
+require 'legion/llm/router'
+require 'legion/llm/compressor'
+require 'legion/llm/quality_checker'
+require 'legion/llm/escalation_history'
+
+module Legion
+  module LLM
+    class EscalationExhausted < StandardError; end
+
+    class << self
+      include Legion::LLM::Providers
+
+      def start
+        Legion::Logging.debug 'Legion::LLM is running start'
+
+        configure_providers
+        run_discovery
+        set_defaults
+
+        @started = true
+        Legion::Settings[:llm][:connected] = true
+        Legion::Logging.info 'Legion::LLM started'
+        ping_provider
+      end
+
+      def shutdown
+        Legion::Settings[:llm][:connected] = false
+        @started = false
+        Legion::Logging.info 'Legion::LLM shut down'
+      end
+
+      def started?
+        @started == true
+      end
+
+      def settings
+        if Legion.const_defined?('Settings')
+          Legion::Settings[:llm]
+        else
+          Legion::LLM::Settings.default
+        end
+      end
+
+      # Create a new chat session
+      # @param model [String] model ID (e.g., "us.anthropic.claude-sonnet-4-6-v1")
+      # @param provider [Symbol] provider slug (e.g., :bedrock, :anthropic)
+      # @param intent [Hash, nil] routing intent (capability, privacy, etc.)
+      # @param tier [Symbol, nil] explicit tier override — skips rule matching
+      # @param escalate [Boolean, nil] enable escalation retry loop (nil = auto from settings)
+      # @param max_escalations [Integer, nil] max escalation attempts override
+      # @param quality_check [Proc, nil] custom quality check callable
+      # @param message [String, nil] message to send (required for escalation)
+      # @param kwargs [Hash] additional options passed to RubyLLM.chat
+      # @return [RubyLLM::Chat]
+      # TODO: fleet tier dispatch via Transport (Phase 3)
+      def chat(model: nil, provider: nil, intent: nil, tier: nil, escalate: nil,
+               max_escalations: nil, quality_check: nil, message: nil, **)
+        escalate = escalation_enabled? if escalate.nil?
+
+        if escalate && message
+          chat_with_escalation(
+            model: model, provider: provider, intent: intent, tier: tier,
+            max_escalations: max_escalations, quality_check: quality_check,
+            message: message, **
+          )
+        else
+          chat_single(model: model, provider: provider, intent: intent, tier: tier, **)
+        end
+      end
+
+      # Generate embeddings
+      # @param text [String, Array<String>] text to embed
+      # @param model [String] embedding model ID
+      # @return [RubyLLM::Embedding]
+      def embed(text, model: nil)
+        if model
+          RubyLLM.embed(text, model: model)
+        else
+          RubyLLM.embed(text)
+        end
+      end
+
+      # Create a configured agent instance
+      # @param agent_class [Class] a RubyLLM::Agent subclass
+      # @param kwargs [Hash] additional options
+      # @return [RubyLLM::Agent]
+      def agent(agent_class, **)
+        agent_class.new(**)
+      end
+
+      private
+
+      def chat_single(model:, provider:, intent:, tier:, **kwargs)
+        if (intent || tier) && Router.routing_enabled?
+          resolution = Router.resolve(intent: intent, tier: tier, model: model, provider: provider)
+          if resolution
+            model    = resolution.model
+            provider = resolution.provider
+          end
+        end
+
+        model    ||= settings[:default_model]
+        provider ||= settings[:default_provider]
+
+        opts = {}
+        opts[:model]    = model    if model
+        opts[:provider] = provider if provider
+        opts.merge!(kwargs)
+
+        RubyLLM.chat(**opts)
+      end
+
+      def chat_with_escalation(model:, provider:, intent:, tier:, max_escalations:, quality_check:, message:, **kwargs)
+        chain = Router.resolve_chain(
+          intent: intent, tier: tier, model: model, provider: provider,
+          max_escalations: max_escalations
+        )
+
+        threshold = escalation_quality_threshold
+        history = []
+
+        chain.each do |resolution|
+          start_time = Time.now
+          begin
+            opts = { model: resolution.model, provider: resolution.provider }
+            opts.merge!(kwargs)
+            chat_obj = RubyLLM.chat(**opts)
+            response = chat_obj.ask(message)
+
+            duration_ms = ((Time.now - start_time) * 1000).round
+            result = QualityChecker.check(response, quality_threshold: threshold, quality_check: quality_check)
+
+            if result.passed
+              report_health(:success, resolution, duration_ms)
+              history << build_attempt(resolution, :success, [], duration_ms)
+              attach_escalation_history(response, history, resolution, chain)
+              publish_escalation_event(history, :success) if history.size > 1
+              return response
+            else
+              report_health(:quality_failure, resolution, duration_ms, failures: result.failures)
+              history << build_attempt(resolution, :quality_failure, result.failures, duration_ms)
+            end
+          rescue StandardError => e
+            duration_ms = ((Time.now - start_time) * 1000).round
+            report_health(:error, resolution, duration_ms)
+            history << build_attempt(resolution, :error, [e.class.name], duration_ms)
+          end
+        end
+
+        publish_escalation_event(history, :exhausted) if history.size > 1
+        raise EscalationExhausted, "All #{history.size} escalation attempts failed"
+      end
+
+      def build_attempt(resolution, outcome, failures, duration_ms)
+        { model: resolution.model, provider: resolution.provider, tier: resolution.tier,
+          outcome: outcome, failures: failures, duration_ms: duration_ms }
+      end
+
+      def attach_escalation_history(response, history, resolution, chain)
+        return unless response.respond_to?(:extend)
+
+        response.extend(EscalationHistory)
+        history.each { |h| response.record_escalation_attempt(**h) }
+        response.final_resolution = resolution
+        response.escalation_chain = chain
+      end
+
+      def report_health(signal, resolution, duration_ms, failures: nil)
+        return unless Router.routing_enabled?
+
+        metadata = { duration_ms: duration_ms }
+        metadata[:failures] = failures if failures
+        Router.health_tracker.report(provider: resolution.provider, signal: signal, value: 1, metadata: metadata)
+        Router.health_tracker.report(provider: resolution.provider, signal: :latency, value: duration_ms, metadata: {})
+      end
+
+      def publish_escalation_event(history, final_outcome)
+        return unless defined?(Legion::Transport)
+
+        Legion::Logging.debug("Escalation event: #{final_outcome}, #{history.size} attempts") if Legion.const_defined?('Logging')
+      rescue StandardError
+        nil
+      end
+
+      def escalation_enabled?
+        routing = settings[:routing]
+        return false unless routing.is_a?(Hash)
+
+        esc = routing[:escalation] || {}
+        esc[:enabled] == true
+      end
+
+      def escalation_quality_threshold
+        routing = settings[:routing]
+        return 50 unless routing.is_a?(Hash)
+
+        esc = routing[:escalation] || {}
+        esc.fetch(:quality_threshold, 50)
+      end
+
+      def set_defaults
+        default_model    = settings[:default_model]
+        default_provider = settings[:default_provider]
+
+        RubyLLM.configure do |c|
+          c.default_model = default_model if default_model
+        end
+
+        return unless default_model.nil? && default_provider.nil?
+
+        # Auto-detect: use first enabled provider's sensible default
+        auto_configure_defaults
+      end
+
+      def run_discovery
+        return unless settings.dig(:providers, :ollama, :enabled)
+
+        Discovery::Ollama.refresh!
+        Discovery::System.refresh!
+
+        names = Discovery::Ollama.model_names
+        count = names.size
+        Legion::Logging.info "Ollama: #{count} model#{'s' unless count == 1} available (#{names.join(', ')})"
+        Legion::Logging.info "System: #{Discovery::System.total_memory_mb} MB total, " \
+                             "#{Discovery::System.available_memory_mb} MB available"
+      rescue StandardError => e
+        Legion::Logging.warn "Discovery failed: #{e.message}"
+      end
+
+      def ping_provider
+        model = settings[:default_model]
+        provider = settings[:default_provider]
+        return unless model && provider
+
+        start_time = Time.now
+        RubyLLM.chat(model: model, provider: provider).ask('Respond with only the word: pong')
+        elapsed = ((Time.now - start_time) * 1000).round
+        Legion::Logging.info "LLM ping #{provider}/#{model}: pong (#{elapsed}ms)"
+      rescue StandardError => e
+        Legion::Logging.warn "LLM ping failed for #{provider}/#{model}: #{e.message}"
+      end
+
+      def auto_configure_defaults
+        settings[:providers].each do |provider, config|
+          next unless config&.dig(:enabled)
+
+          model = config[:default_model]
+          next unless model
+
+          settings[:default_model]    = model
+          settings[:default_provider] = provider
+          Legion::Logging.info "Auto-configured default: #{model} via #{provider}"
+          break
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: legion-llm
+version: !ruby/object:Gem::Version
+  version: 0.3.1
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: legion-settings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: tzinfo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Provides LLM capabilities (chat, embeddings, tool use, agents) to LegionIO
+  extensions
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- LICENSE
+- README.md
+- docs/plans/2026-03-15-ollama-discovery-design.md
+- docs/plans/2026-03-15-ollama-discovery-implementation.md
+- legion-llm.gemspec
+- lib/legion/llm.rb
+- lib/legion/llm/bedrock_bearer_auth.rb
+- lib/legion/llm/compressor.rb
+- lib/legion/llm/discovery/ollama.rb
+- lib/legion/llm/discovery/system.rb
+- lib/legion/llm/escalation_history.rb
+- lib/legion/llm/helpers/llm.rb
+- lib/legion/llm/providers.rb
+- lib/legion/llm/quality_checker.rb
+- lib/legion/llm/router.rb
+- lib/legion/llm/router/escalation_chain.rb
+- lib/legion/llm/router/health_tracker.rb
+- lib/legion/llm/router/resolution.rb
+- lib/legion/llm/router/rule.rb
+- lib/legion/llm/settings.rb
+- lib/legion/llm/transport/exchanges/escalation.rb
+- lib/legion/llm/transport/messages/escalation_event.rb
+- lib/legion/llm/version.rb
+homepage: https://github.com/LegionIO/legion-llm
+licenses:
+- Apache-2.0
+metadata:
+  bug_tracker_uri: https://github.com/LegionIO/legion-llm/issues
+  changelog_uri: https://github.com/LegionIO/legion-llm/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/LegionIO/legion-llm
+  homepage_uri: https://github.com/LegionIO/LegionIO
+  source_code_uri: https://github.com/LegionIO/legion-llm
+  wiki_uri: https://github.com/LegionIO/legion-llm/wiki
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LLM integration for the LegionIO framework via ruby_llm
+test_files: []