legion-llm 0.3.1

data/legion-llm.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/llm/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'legion-llm'
+  spec.version       = Legion::LLM::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+  spec.summary       = 'LLM integration for the LegionIO framework via ruby_llm'
+  spec.description   = 'Provides LLM capabilities (chat, embeddings, tool use, agents) to LegionIO extensions'
+  spec.homepage      = 'https://github.com/LegionIO/legion-llm'
+  spec.license       = 'Apache-2.0'
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.4'
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.extra_rdoc_files = %w[README.md LICENSE CHANGELOG.md]
+  spec.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'
+  }
+
+  spec.add_dependency 'legion-logging'
+  spec.add_dependency 'legion-settings'
+  spec.add_dependency 'ruby_llm', '>= 1.0'
+  spec.add_dependency 'tzinfo', '>= 2.0'
+end

data/lib/legion/llm/bedrock_bearer_auth.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Monkey-patch RubyLLM's Bedrock provider to support AWS Bearer Token
+# authentication (Identity Center / SSO) as an alternative to SigV4.
+#
+# When `bedrock_bearer_token` is set on the RubyLLM configuration,
+# requests use a simple `Authorization: Bearer <token>` header instead
+# of the full SigV4 signing process.
+
+require 'ruby_llm'
+
+module RubyLLM
+  class Configuration
+    attr_accessor :bedrock_bearer_token
+  end
+
+  module Providers
+    class Bedrock
+      class << self
+        def configuration_requirements
+          config = RubyLLM.config
+          if config.bedrock_bearer_token
+            %i[bedrock_bearer_token bedrock_region]
+          else
+            %i[bedrock_api_key bedrock_secret_key bedrock_region]
+          end
+        end
+      end
+
+      module Auth
+        private
+
+        alias sigv4_sign_headers sign_headers
+
+        def sign_headers(method, path, body, base_url: api_base)
+          if @config.bedrock_bearer_token
+            bearer_headers(path, body)
+          else
+            sigv4_sign_headers(method, path, body, base_url: base_url)
+          end
+        end
+
+        def bearer_headers(_path, body)
+          {
+            'Authorization'        => "Bearer #{@config.bedrock_bearer_token}",
+            'Content-Type'         => 'application/json',
+            'X-Amz-Content-Sha256' => Digest::SHA256.hexdigest(body)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/compressor.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Compressor
+      NONE       = 0
+      LIGHT      = 1
+      MODERATE   = 2
+      AGGRESSIVE = 3
+
+      LEVEL_WORDS = {
+        1 => %w[a an the just very really basically actually simply quite rather somewhat],
+        2 => %w[however moreover furthermore additionally consequently therefore thus hence
+                meanwhile nevertheless nonetheless accordingly indeed certainly],
+        3 => %w[also then still even already yet again please note that]
+      }.freeze
+
+      class << self
+        def compress(text, level: LIGHT)
+          return text if text.nil? || text.empty? || level <= NONE
+
+          segments = split_segments(text)
+          result = segments.map { |seg| seg[:protected] ? seg[:text] : compress_prose(seg[:text], level) }.join
+
+          result = collapse_whitespace(result) if level >= AGGRESSIVE
+          result
+        end
+
+        def stopwords_for_level(level)
+          return [] if level <= NONE
+
+          (1..[level, AGGRESSIVE].min).flat_map { |l| LEVEL_WORDS.fetch(l, []) }
+        end
+
+        private
+
+        def split_segments(text)
+          segments = []
+
+          # Split on fenced code blocks first (```...```)
+          parts = text.split(/(```.*?```)/m)
+          parts.each do |part|
+            if part.start_with?('```')
+              segments << { text: part, protected: true }
+            else
+              # Within non-fenced text, split on inline code (`...`)
+              subparts = part.split(/(`[^`\n]+`)/)
+              subparts.each do |sub|
+                protected = sub.start_with?('`') && sub.end_with?('`') && sub.length > 1
+                segments << { text: sub, protected: protected }
+              end
+            end
+          end
+
+          segments
+        end
+
+        def compress_prose(text, level)
+          words = stopwords_for_level(level)
+          return text if words.empty?
+
+          pattern = /\b(#{words.join('|')})\b ?/i
+          result = text.gsub(pattern, '')
+
+          # Clean up double spaces left by removals
+          result.gsub(/  +/, ' ')
+        end
+
+        def collapse_whitespace(text)
+          text.gsub(/\n{3,}/, "\n\n")
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/discovery/ollama.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Legion
+  module LLM
+    module Discovery
+      module Ollama
+        class << self
+          def models
+            ensure_fresh
+            @models || []
+          end
+
+          def model_names
+            models.map { |m| m['name'] }
+          end
+
+          def model_available?(name)
+            model_names.include?(name)
+          end
+
+          def model_size(name)
+            models.find { |m| m['name'] == name }&.dig('size')
+          end
+
+          def refresh!
+            response = connection.get('/api/tags')
+            if response.success?
+              parsed = ::JSON.parse(response.body)
+              @models = parsed['models'] || []
+            else
+              @models ||= []
+            end
+          rescue StandardError
+            @models ||= []
+          ensure
+            @last_refreshed_at = Time.now
+          end
+
+          def reset!
+            @models = nil
+            @last_refreshed_at = nil
+          end
+
+          def stale?
+            return true if @last_refreshed_at.nil?
+
+            ttl = discovery_settings[:refresh_seconds] || 60
+            Time.now - @last_refreshed_at > ttl
+          end
+
+          private
+
+          def ensure_fresh
+            refresh! if stale?
+          end
+
+          def connection
+            base = ollama_base_url
+            Faraday.new(url: base) do |f|
+              f.options.timeout = 2
+              f.options.open_timeout = 2
+              f.adapter Faraday.default_adapter
+            end
+          end
+
+          def ollama_base_url
+            return 'http://localhost:11434' unless Legion.const_defined?('Settings')
+
+            Legion::Settings[:llm].dig(:providers, :ollama, :base_url) || 'http://localhost:11434'
+          rescue StandardError
+            'http://localhost:11434'
+          end
+
+          def discovery_settings
+            return {} unless Legion.const_defined?('Settings')
+
+            Legion::Settings[:llm][:discovery] || {}
+          rescue StandardError
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/discovery/system.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Discovery
+      module System
+        class << self
+          def total_memory_mb
+            ensure_total_fresh
+            @total_memory_mb
+          end
+
+          def available_memory_mb
+            ensure_available_fresh
+            @available_memory_mb
+          end
+
+          def memory_pressure?
+            avail = available_memory_mb
+            return false if avail.nil?
+
+            floor = discovery_settings[:memory_floor_mb] || 2048
+            avail < floor
+          end
+
+          def platform
+            @platform ||= detect_platform
+          end
+
+          def refresh!
+            @total_fetched_at = nil
+            @available_fetched_at = nil
+            @total_memory_mb = nil
+            @available_memory_mb = nil
+            @last_refreshed_at = Time.now
+          end
+
+          def reset!
+            @total_memory_mb = nil
+            @available_memory_mb = nil
+            @total_fetched_at = nil
+            @available_fetched_at = nil
+            @last_refreshed_at = nil
+            @platform = nil
+          end
+
+          def stale?
+            return true if @last_refreshed_at.nil?
+
+            ttl = discovery_settings[:refresh_seconds] || 60
+            Time.now - @last_refreshed_at > ttl
+          end
+
+          private
+
+          def ensure_total_fresh
+            refresh! if stale?
+            return unless @total_fetched_at.nil?
+
+            fetch_total
+            @total_fetched_at = Time.now
+          end
+
+          def ensure_available_fresh
+            refresh! if stale?
+            return unless @available_fetched_at.nil?
+
+            fetch_available
+            @available_fetched_at = Time.now
+          end
+
+          def fetch_total
+            case platform
+            when :macos then fetch_macos_total
+            when :linux then fetch_linux_total
+            end
+          end
+
+          def fetch_available
+            case platform
+            when :macos then fetch_macos_available
+            when :linux then fetch_linux_available
+            end
+          end
+
+          def detect_platform
+            case RbConfig::CONFIG['host_os']
+            when /darwin/i then :macos
+            when /linux/i  then :linux
+            else :unknown
+            end
+          end
+
+          def fetch_macos_total
+            raw = `sysctl -n hw.memsize`.strip.to_i
+            @total_memory_mb = raw / 1024 / 1024
+          rescue StandardError
+            @total_memory_mb = nil
+          end
+
+          def fetch_macos_available
+            vm_output = `vm_stat`
+            page_size = vm_output[/page size of (\d+) bytes/, 1]&.to_i || 16_384
+            free     = vm_output[/Pages free:\s+(\d+)/, 1].to_i
+            inactive = vm_output[/Pages inactive:\s+(\d+)/, 1].to_i
+            @available_memory_mb = (free + inactive) * page_size / 1024 / 1024
+          rescue StandardError
+            @available_memory_mb = nil
+          end
+
+          def fetch_linux_total
+            meminfo = File.read('/proc/meminfo')
+            total_kb = meminfo[/MemTotal:\s+(\d+)/, 1].to_i
+            @total_memory_mb = total_kb / 1024
+          rescue StandardError
+            @total_memory_mb = nil
+          end
+
+          def fetch_linux_available
+            meminfo = File.read('/proc/meminfo')
+            free_kb     = meminfo[/MemFree:\s+(\d+)/, 1].to_i
+            inactive_kb = meminfo[/Inactive:\s+(\d+)/, 1].to_i
+            @available_memory_mb = (free_kb + inactive_kb) / 1024
+          rescue StandardError
+            @available_memory_mb = nil
+          end
+
+          def discovery_settings
+            return {} unless Legion.const_defined?('Settings')
+
+            Legion::Settings[:llm][:discovery] || {}
+          rescue StandardError
+            {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/escalation_history.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module EscalationHistory
+      attr_accessor :final_resolution, :escalation_chain
+
+      def escalation_history
+        @escalation_history ||= []
+      end
+
+      def escalated?
+        escalation_history.size > 1
+      end
+
+      def record_escalation_attempt(model:, provider:, tier:, outcome:, failures:, duration_ms:)
+        escalation_history << {
+          model:       model,
+          provider:    provider,
+          tier:        tier,
+          outcome:     outcome,
+          failures:    failures,
+          duration_ms: duration_ms
+        }
+      end
+    end
+  end
+end

data/lib/legion/llm/helpers/llm.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Helpers
+      module LLM
+        # Quick chat from any extension runner
+        # @param message [String] the prompt
+        # @param model [String] optional model override
+        # @param provider [Symbol] optional provider override
+        # @param intent [Hash, nil] routing intent (capability, privacy, etc.)
+        # @param tier [Symbol, nil] explicit tier override
+        # @param tools [Array<Class>] optional RubyLLM::Tool subclasses
+        # @param instructions [String] optional system instructions
+        # @param escalate [Boolean, nil] enable model escalation on low-quality responses
+        # @param max_escalations [Integer, nil] max escalation attempts
+        # @param quality_check [Proc, nil] callable that returns true if response is acceptable
+        # @return [RubyLLM::Message] the assistant response
+        def llm_chat(message, model: nil, provider: nil, intent: nil, tier: nil, tools: [], instructions: nil, # rubocop:disable Metrics/ParameterLists
+                     compress: 0, escalate: nil, max_escalations: nil, quality_check: nil)
+          if compress.positive?
+            message = Legion::LLM::Compressor.compress(message, level: compress)
+            instructions = Legion::LLM::Compressor.compress(instructions, level: compress) if instructions
+          end
+
+          # When escalation is active, chat() handles ask() internally via message: kwarg
+          if escalate
+            return Legion::LLM.chat(model: model, provider: provider, intent: intent, tier: tier,
+                                    escalate: true, max_escalations: max_escalations,
+                                    quality_check: quality_check, message: message)
+          end
+
+          chat = Legion::LLM.chat(model: model, provider: provider, intent: intent, tier: tier, escalate: false)
+          chat.with_instructions(instructions) if instructions
+          chat.with_tools(*tools) unless tools.empty?
+          chat.ask(message)
+        end
+
+        # Quick embed from any extension runner
+        # @param text [String, Array<String>] text to embed
+        # @param model [String] optional model override
+        # @return [RubyLLM::Embedding]
+        def llm_embed(text, model: nil)
+          Legion::LLM.embed(text, model: model)
+        end
+
+        # Get a raw chat object for multi-turn conversations
+        # @param model [String] optional model override
+        # @param provider [Symbol] optional provider override
+        # @param intent [Hash, nil] routing intent (capability, privacy, etc.)
+        # @param tier [Symbol, nil] explicit tier override
+        # @return [RubyLLM::Chat]
+        def llm_session(model: nil, provider: nil, intent: nil, tier: nil)
+          Legion::LLM.chat(model: model, provider: provider, intent: intent, tier: tier, escalate: false)
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/providers.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Providers
+      def configure_providers
+        settings[:providers].each do |provider, config|
+          next unless config[:enabled]
+
+          apply_provider_config(provider, config)
+        end
+      end
+
+      def apply_provider_config(provider, config)
+        case provider
+        when :bedrock
+          configure_bedrock(config)
+        when :anthropic
+          configure_anthropic(config)
+        when :openai
+          configure_openai(config)
+        when :gemini
+          configure_gemini(config)
+        when :ollama
+          configure_ollama(config)
+        else
+          Legion::Logging.warn "Unknown LLM provider: #{provider}"
+        end
+      end
+
+      def configure_bedrock(config)
+        has_sigv4  = config[:api_key] && config[:secret_key]
+        has_bearer = config[:bearer_token]
+        return unless has_sigv4 || has_bearer
+
+        require 'legion/llm/bedrock_bearer_auth' if has_bearer
+
+        RubyLLM.configure do |c|
+          if has_bearer
+            c.bedrock_bearer_token = config[:bearer_token]
+          else
+            c.bedrock_api_key       = config[:api_key]
+            c.bedrock_secret_key    = config[:secret_key]
+            c.bedrock_session_token = config[:session_token] if config[:session_token]
+          end
+          c.bedrock_region = config[:region] || 'us-east-2'
+        end
+
+        auth_mode = has_bearer ? 'bearer token' : 'SigV4'
+        Legion::Logging.info "Configured Bedrock provider (#{config[:region]}, #{auth_mode})"
+      end
+
+      def configure_anthropic(config)
+        return unless config[:api_key]
+
+        RubyLLM.configure do |c|
+          c.anthropic_api_key = config[:api_key]
+        end
+        Legion::Logging.info 'Configured Anthropic provider'
+      end
+
+      def configure_openai(config)
+        return unless config[:api_key]
+
+        RubyLLM.configure do |c|
+          c.openai_api_key = config[:api_key]
+        end
+        Legion::Logging.info 'Configured OpenAI provider'
+      end
+
+      def configure_gemini(config)
+        return unless config[:api_key]
+
+        RubyLLM.configure do |c|
+          c.gemini_api_key = config[:api_key]
+        end
+        Legion::Logging.info 'Configured Gemini provider'
+      end
+
+      def configure_ollama(config)
+        RubyLLM.configure do |c|
+          c.ollama_api_base = config[:base_url] if config[:base_url]
+        end
+        Legion::Logging.info "Configured Ollama provider (#{config[:base_url]})"
+      end
+    end
+  end
+end

data/lib/legion/llm/quality_checker.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Legion
+  module LLM
+    module QualityChecker
+      QualityResult = Struct.new(:passed, :failures)
+
+      REPETITION_MIN_LENGTH = 20
+      REPETITION_THRESHOLD  = 3
+      DEFAULT_QUALITY_THRESHOLD = 50
+
+      class << self
+        def check(response, quality_threshold: DEFAULT_QUALITY_THRESHOLD, json_expected: false, quality_check: nil)
+          failures = []
+          content = response.content
+
+          failures << :empty_response if content.nil? || content.strip.empty?
+
+          unless failures.include?(:empty_response)
+            failures << :too_short if content.length < quality_threshold
+            failures << :repetition if repetitive?(content)
+            failures << :json_parse_failure if json_expected && !valid_json?(content)
+          end
+
+          failures << :custom_check_failed if quality_check.respond_to?(:call) && !quality_check.call(response)
+
+          QualityResult.new(passed: failures.empty?, failures: failures)
+        end
+
+        private
+
+        def repetitive?(content)
+          return false if content.length < REPETITION_MIN_LENGTH * REPETITION_THRESHOLD
+
+          seen = {}
+          (0..(content.length - REPETITION_MIN_LENGTH)).step(REPETITION_MIN_LENGTH) do |i|
+            chunk = content[i, REPETITION_MIN_LENGTH]
+            seen[chunk] = (seen[chunk] || 0) + 1
+            return true if seen[chunk] >= REPETITION_THRESHOLD
+          end
+
+          false
+        end
+
+        def valid_json?(content)
+          ::JSON.parse(content)
+          true
+        rescue ::JSON::ParserError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/legion/llm/router/escalation_chain.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Legion
+  module LLM
+    module Router
+      class EscalationChain
+        include Enumerable
+
+        attr_reader :max_attempts
+
+        def initialize(resolutions:, max_attempts: 3)
+          @resolutions = resolutions.dup.freeze
+          @max_attempts = max_attempts
+        end
+
+        def primary
+          @resolutions.first
+        end
+
+        def each(&)
+          return enum_for(:each) unless block_given?
+
+          padded_resolutions.each(&)
+        end
+
+        def size
+          @resolutions.size
+        end
+
+        def empty?
+          @resolutions.empty?
+        end
+
+        def to_a
+          @resolutions.dup
+        end
+
+        private
+
+        def padded_resolutions
+          return @resolutions.first(@max_attempts) if @resolutions.size >= @max_attempts
+
+          last = @resolutions.last
+          (@resolutions + Array.new(@max_attempts - @resolutions.size) { last }).first(@max_attempts)
+        end
+      end
+    end
+  end
+end