legion-llm 0.5.14 → 0.5.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ceb7fa0519b3985439d577579889de688b42a9e8d3c5fdbc6a1be5b22c7fb2ba
-  data.tar.gz: 80fd2cc36a19cf49783f9429e4aca545e26c3b8ca130fa649800955ce52001d2
+  metadata.gz: 42d72ed366b2266f182b9a2e950d02c735956ff0b3ee51f712ed4686370b7274
+  data.tar.gz: 9af0c1f6f15ecea5d029868fde0a51305307a5de14391cf31e7c85307cccdee0
 SHA512:
-  metadata.gz: 82f00569a04406cc64983f447e3fbd5fbb4c9765f9caa59543a7db0dc612ca659368dae3441f4fa77ae27aaf74347dac997cccb842dc3a2e3e99184ac52f591e
-  data.tar.gz: 40d6ec150d5832f0a4d0ac8f9f9e25754c58e6d4d5a528eb13c2c1420a62a8e6e579c3dda417fdd4dcff8f9d6ba888d7613baba266596c442e787f041a1a50a0
+  metadata.gz: 844583a7565f8bbc167f12330b51c32ba57b74802b23e624158f1afbaa3020dffd25e7324ad4ec19fe2ad0eaf2dccdfb6b6d8c673f06805f0b12f2613ac5f6f7
+  data.tar.gz: 26ec627a507e4e8d14e8a9e6155bb852c44d36af9e44b60f02dc247e1d307801bffbdc486a54745894430453c1fde22902662b7253feb8d5c841b92971aa2326

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Legion LLM Changelog
 
+## [0.5.15] - 2026-03-28
+
+### Added
+- `Legion::LLM::Routes` Sinatra extension module (`lib/legion/llm/routes.rb`): contains all `/api/llm/*` route definitions (chat, inference, providers) extracted from `LegionIO/lib/legion/api/llm.rb`. Self-registers with `Legion::API.register_library_routes('llm', Legion::LLM::Routes)` at the end of `Legion::LLM.start`.
+
+### Changed
+- `Legion::LLM.start` now calls `register_routes` after setting `@started = true`, mounting routes onto the API if `Legion::API` is available.
+
 ## [0.5.14] - 2026-03-27
 
 ### Added

data/CLAUDE.md

@@ -8,7 +8,7 @@
 Core LegionIO gem providing LLM capabilities to all extensions. Wraps ruby_llm to provide a consistent interface for chat, embeddings, tool use, and agents across multiple providers (Bedrock, Anthropic, OpenAI, Gemini, Ollama). Includes a dynamic weighted routing engine that dispatches requests across local, fleet, and cloud tiers based on caller intent, priority rules, time schedules, cost multipliers, and real-time provider health.
 
 **GitHub**: https://github.com/LegionIO/legion-llm
-**Version**: 0.5.3
+**Version**: 0.5.15
 **License**: Apache-2.0
 
 ## Architecture
@@ -325,7 +325,7 @@ In-memory signal consumer with pluggable handlers. Adjusts effective priorities
 | `lib/legion/llm/structured_output.rb` | JSON schema enforcement with native response_format and prompt fallback |
 | `lib/legion/llm/errors.rb` | Typed error hierarchy: LLMError base + AuthError, RateLimitError, ContextOverflow, ProviderError, ProviderDown, UnsupportedCapability, PipelineError |
 | `lib/legion/llm/conversation_store.rb` | ConversationStore: in-memory LRU (256 slots) + optional Sequel DB persistence + spool fallback |
-| `lib/legion/llm/version.rb` | Version constant (0.5.3) |
+| `lib/legion/llm/version.rb` | Version constant |
 | `lib/legion/llm/quality_checker.rb` | QualityChecker module with QualityResult struct |
 | `lib/legion/llm/escalation_history.rb` | EscalationHistory mixin: `escalation_history`, `escalated?`, `final_resolution`, `escalation_chain` |
 | `lib/legion/llm/router/escalation_chain.rb` | EscalationChain value object |

data/README.md

@@ -2,7 +2,7 @@
 
 LLM integration for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Wraps [ruby_llm](https://github.com/crmne/ruby_llm) to provide chat, embeddings, tool use, and agent capabilities to any Legion extension.
 
-**Version**: 0.5.3
+**Version**: 0.5.15
 
 ## Installation
 
@@ -652,7 +652,7 @@ bundle exec rspec
 Tests use stubbed `Legion::Logging` and `Legion::Settings` modules (no need for the full LegionIO stack):
 
 ```bash
-bundle exec rspec                              # Run all 882 tests
+bundle exec rspec                              # Run all tests
 bundle exec rubocop                            # Lint (0 offenses)
 bundle exec rspec spec/legion/llm_spec.rb      # Run specific test file
 bundle exec rspec spec/legion/llm/router_spec.rb  # Router tests only

data/lib/legion/llm/conversation_store.rb

@@ -26,7 +26,7 @@ module Legion
         end
 
         def create_conversation(conversation_id, **metadata)
-          conversations[conversation_id] = { messages: [], metadata: metadata, accessed_at: Time.now }
+          conversations[conversation_id] = { messages: [], metadata: metadata, lru_tick: next_tick }
           evict_if_needed
           persist_conversation(conversation_id, metadata)
         end
@@ -41,6 +41,7 @@ module Legion
 
         def reset!
           @conversations = {}
+          @lru_counter   = 0
         end
 
         private
@@ -49,6 +50,10 @@ module Legion
           @conversations ||= {}
         end
 
+        def next_tick
+          @lru_counter = (@lru_counter || 0) + 1
+        end
+
         def ensure_conversation(conversation_id)
           return if in_memory?(conversation_id)
 
@@ -63,13 +68,13 @@ module Legion
         def touch(conversation_id)
           return unless in_memory?(conversation_id)
 
-          conversations[conversation_id][:accessed_at] = Time.now
+          conversations[conversation_id][:lru_tick] = next_tick
         end
 
         def evict_if_needed
           return unless conversations.size > self::MAX_CONVERSATIONS
 
-          oldest_id = conversations.min_by { |_, v| v[:accessed_at] }&.first
+          oldest_id = conversations.min_by { |_, v| v[:lru_tick] }&.first
           conversations.delete(oldest_id) if oldest_id
         end
 

data/lib/legion/llm/routes.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+
+# Self-registering route module for legion-llm.
+# All routes previously defined in LegionIO/lib/legion/api/llm.rb now live here
+# and are mounted via Legion::API.register_library_routes when legion-llm boots.
+#
+# LegionIO/lib/legion/api/llm.rb is preserved for backward compatibility but guards
+# its registration with defined?(Legion::LLM::Routes) so double-registration is avoided.
+
+require 'securerandom'
+
+module Legion
+  module LLM
+    module Routes
+      def self.registered(app) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity,Metrics/AbcSize,Metrics/MethodLength
+        app.helpers do # rubocop:disable Metrics/BlockLength
+          # Minimal fallback implementations of shared API helpers.
+          # These are used when Legion::LLM::Routes is mounted on a bare Sinatra app.
+          # When mounted via Legion::API (the normal path), Legion::API::Helpers and
+          # Legion::API::Validators provide full implementations that take precedence.
+          unless method_defined?(:parse_request_body)
+            define_method(:parse_request_body) do
+              raw = request.body.read
+              return {} if raw.nil? || raw.empty?
+
+              begin
+                parsed = Legion::JSON.load(raw)
+              rescue StandardError
+                halt 400, { 'Content-Type' => 'application/json' },
+                     Legion::JSON.dump({ error: { code: 'invalid_json', message: 'request body is not valid JSON' } })
+              end
+
+              unless parsed.respond_to?(:transform_keys)
+                halt 400, { 'Content-Type' => 'application/json' },
+                     Legion::JSON.dump({ error: { code:    'invalid_request_body',
+                                                  message: 'request body must be a JSON object' } })
+              end
+
+              parsed.transform_keys(&:to_sym)
+            end
+          end
+
+          unless method_defined?(:validate_required!)
+            define_method(:validate_required!) do |body, *keys|
+              missing = keys.select { |k| body[k].nil? || (body[k].respond_to?(:empty?) && body[k].empty?) }
+              return if missing.empty?
+
+              halt 400, { 'Content-Type' => 'application/json' },
+                   Legion::JSON.dump({ error: { code:    'missing_fields',
+                                                message: "required: #{missing.join(', ')}" } })
+            end
+          end
+
+          unless method_defined?(:json_response)
+            define_method(:json_response) do |data, status_code: 200|
+              content_type :json
+              status status_code
+              Legion::JSON.dump({ data: data })
+            end
+          end
+
+          unless method_defined?(:json_error)
+            define_method(:json_error) do |code, message, status_code: 400|
+              content_type :json
+              status status_code
+              Legion::JSON.dump({ error: { code: code, message: message } })
+            end
+          end
+
+          unless method_defined?(:require_llm!)
+            define_method(:require_llm!) do
+              return if defined?(Legion::LLM) &&
+                        Legion::LLM.respond_to?(:started?) &&
+                        Legion::LLM.started?
+
+              halt 503, { 'Content-Type' => 'application/json' },
+                   Legion::JSON.dump({ error: { code:    'llm_unavailable',
+                                                message: 'LLM subsystem is not available' } })
+            end
+          end
+
+          unless method_defined?(:cache_available?)
+            define_method(:cache_available?) do
+              defined?(Legion::Cache) &&
+                Legion::Cache.respond_to?(:connected?) &&
+                Legion::Cache.connected?
+            end
+          end
+
+          unless method_defined?(:gateway_available?)
+            define_method(:gateway_available?) do
+              defined?(Legion::Extensions::LLM::Gateway::Runners::Inference)
+            end
+          end
+
+          unless method_defined?(:validate_tools!)
+            define_method(:validate_tools!) do |tool_list|
+              unless tool_list.is_a?(Array) && tool_list.all? { |t| t.respond_to?(:transform_keys) }
+                halt 400, { 'Content-Type' => 'application/json' },
+                     Legion::JSON.dump({ error: { code:    'invalid_tools',
+                                                  message: 'tools must be an array of objects' } })
+              end
+
+              invalid = tool_list.any? do |t|
+                ts = t.transform_keys(&:to_sym)
+                ts[:name].to_s.empty?
+              end
+              return unless invalid
+
+              halt 400, { 'Content-Type' => 'application/json' },
+                   Legion::JSON.dump({ error: { code:    'invalid_tools',
+                                                message: 'each tool must have a non-empty name' } })
+            end
+          end
+
+          unless method_defined?(:validate_messages!)
+            define_method(:validate_messages!) do |msg_list|
+              valid = msg_list.all? do |m|
+                next false unless m.respond_to?(:key?) && m.respond_to?(:[])
+
+                role          = m[:role] || m['role']
+                content_value = m[:content] || m['content']
+
+                !role.to_s.empty? &&
+                  (m.key?(:content) || m.key?('content')) &&
+                  !content_value.nil? &&
+                  !(content_value.respond_to?(:empty?) && content_value.empty?)
+              end
+              return if valid
+
+              halt 400, { 'Content-Type' => 'application/json' },
+                   Legion::JSON.dump({ error: { code:    'invalid_messages',
+                                                message: 'each message must be an object with non-empty role and content' } })
+            end
+          end
+        end
+
+        register_chat(app)
+        register_providers(app)
+      end
+
+      def self.register_chat(app) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        register_inference(app)
+
+        app.post '/api/llm/chat' do # rubocop:disable Metrics/BlockLength
+          Legion::Logging.debug "API: POST /api/llm/chat params=#{params.keys}" if defined?(Legion::Logging)
+          require_llm!
+
+          body = parse_request_body
+          validate_required!(body, :message)
+
+          message = body[:message]
+
+          if defined?(Legion::MCP::TierRouter)
+            tier_result = Legion::MCP::TierRouter.route(
+              intent:  message,
+              params:  body.except(:message, :model, :provider, :request_id),
+              context: {}
+            )
+            if tier_result[:tier]&.zero?
+              halt json_response({
+                                   response:           tier_result[:response],
+                                   tier:               0,
+                                   latency_ms:         tier_result[:latency_ms],
+                                   pattern_confidence: tier_result[:pattern_confidence]
+                                 })
+            end
+          end
+
+          request_id = body[:request_id] || SecureRandom.uuid
+          model      = body[:model]
+          provider   = body[:provider]
+
+          if gateway_available?
+            ingress_result = Legion::Ingress.run(
+              payload:      { message: message, model: model, provider: provider,
+                              request_id: request_id },
+              runner_class: 'Legion::Extensions::LLM::Gateway::Runners::Inference',
+              function:     'chat',
+              source:       'api'
+            )
+
+            unless ingress_result[:success]
+              Legion::Logging.error "[api/llm/chat] ingress failed: #{ingress_result}" if defined?(Legion::Logging)
+              err = ingress_result[:error] || ingress_result[:status]
+              err_code    = err.respond_to?(:dig) ? (err[:code] || 'gateway_error') : err.to_s
+              err_message = err.respond_to?(:dig) ? (err[:message] || err.to_s) : err.to_s
+              halt json_error(err_code, err_message, status_code: 502)
+            end
+
+            result = ingress_result[:result]
+
+            if result.nil?
+              Legion::Logging.warn "[api/llm/chat] runner returned nil (status=#{ingress_result[:status]})" if defined?(Legion::Logging)
+              halt json_error('empty_result', 'Gateway runner returned no result', status_code: 502)
+            end
+
+            if result.is_a?(Hash) && result[:error]
+              re = result[:error]
+              re_code    = re.respond_to?(:dig) ? (re[:code] || 'gateway_error') : re.to_s
+              re_message = re.respond_to?(:dig) ? (re[:message] || re.to_s) : re.to_s
+              halt json_error(re_code, re_message, status_code: 502)
+            end
+
+            response_content = if result.respond_to?(:content)
+                                 result.content
+                               elsif result.is_a?(Hash)
+                                 result[:response] || result[:content] || result.to_s
+                               else
+                                 result.to_s
+                               end
+
+            meta = { routed_via: 'gateway' }
+            meta[:model] = result.model.to_s if result.respond_to?(:model)
+            meta[:tokens_in] = result.input_tokens if result.respond_to?(:input_tokens)
+            meta[:tokens_out] = result.output_tokens if result.respond_to?(:output_tokens)
+
+            halt json_response({ response: response_content, meta: meta }, status_code: 201)
+          end
+
+          if cache_available? && env['HTTP_X_LEGION_SYNC'] != 'true'
+            llm = Legion::LLM
+            rc  = Legion::LLM::ResponseCache
+            rc.init_request(request_id)
+
+            Thread.new do
+              session  = llm.chat_direct(model: model, provider: provider)
+              response = session.ask(message)
+              rc.complete(
+                request_id,
+                response: response.content,
+                meta:     {
+                  model:      session.model.to_s,
+                  tokens_in:  response.respond_to?(:input_tokens) ? response.input_tokens : nil,
+                  tokens_out: response.respond_to?(:output_tokens) ? response.output_tokens : nil
+                }
+              )
+            rescue StandardError => e
+              Legion::Logging.error "API POST /api/llm/chat async: #{e.class} — #{e.message}" if defined?(Legion::Logging)
+              rc.fail_request(request_id, code: 'llm_error', message: e.message)
+            end
+
+            Legion::Logging.info "API: LLM chat request #{request_id} queued async" if defined?(Legion::Logging)
+            json_response({ request_id: request_id, poll_key: "llm:#{request_id}:status" },
+                          status_code: 202)
+          else
+            session  = Legion::LLM.chat(model: model, provider: provider,
+                                        caller: { source: 'api', path: request.path })
+            response = session.ask(message)
+            Legion::Logging.info "API: LLM chat request #{request_id} completed sync model=#{session.model}" if defined?(Legion::Logging)
+            json_response(
+              {
+                response: response.content,
+                meta:     {
+                  model:      session.model.to_s,
+                  tokens_in:  response.respond_to?(:input_tokens) ? response.input_tokens : nil,
+                  tokens_out: response.respond_to?(:output_tokens) ? response.output_tokens : nil
+                }
+              },
+              status_code: 201
+            )
+          end
+        end
+      end
+
+      def self.register_inference(app) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        app.post '/api/llm/inference' do # rubocop:disable Metrics/BlockLength
+          require_llm!
+          body = parse_request_body
+          validate_required!(body, :messages)
+
+          messages = body[:messages]
+          raw_tools = body[:tools]
+          model    = body[:model]
+          provider = body[:provider]
+
+          unless messages.is_a?(Array)
+            halt 400, { 'Content-Type' => 'application/json' },
+                 Legion::JSON.dump({ error: { code: 'invalid_messages', message: 'messages must be an array' } })
+          end
+
+          validate_messages!(messages)
+
+          unless raw_tools.nil? || raw_tools.is_a?(Array)
+            halt 400, { 'Content-Type' => 'application/json' },
+                 Legion::JSON.dump({ error: { code: 'invalid_tools', message: 'tools must be an array' } })
+          end
+
+          tools = raw_tools || []
+
+          session = Legion::LLM.chat(
+            model:    model,
+            provider: provider,
+            caller:   { source: 'api', path: request.path }
+          )
+
+          unless tools.empty?
+            validate_tools!(tools)
+
+            tool_declarations = tools.map do |t|
+              ts = t.respond_to?(:transform_keys) ? t.transform_keys(&:to_sym) : t
+              tname  = ts[:name].to_s
+              tdesc  = ts[:description].to_s
+              tparams = ts[:parameters] || {}
+              Class.new do
+                define_singleton_method(:tool_name)   { tname }
+                define_singleton_method(:description) { tdesc }
+                define_singleton_method(:parameters)  { tparams }
+                define_method(:call) { |**_| raise NotImplementedError, "#{tname} executes client-side only" }
+              end
+            end
+            session.with_tools(*tool_declarations)
+          end
+
+          last_user = messages.select { |m| (m[:role] || m['role']).to_s == 'user' }.last
+          prior_messages = if last_user
+                             idx = messages.rindex(last_user)
+                             if idx
+                               duped = messages.dup
+                               duped.delete_at(idx)
+                               duped
+                             else
+                               messages
+                             end
+                           else
+                             messages
+                           end
+          prior_messages.each { |m| session.add_message(m) }
+
+          prompt   = (last_user || {})[:content] || (last_user || {})['content'] || ''
+          response = session.ask(prompt)
+
+          tc_list = if response.respond_to?(:tool_calls) && response.tool_calls
+                      Array(response.tool_calls).map do |tc|
+                        {
+                          id:        tc.respond_to?(:id) ? tc.id : nil,
+                          name:      tc.respond_to?(:name) ? tc.name : tc.to_s,
+                          arguments: tc.respond_to?(:arguments) ? tc.arguments : {}
+                        }
+                      end
+                    end
+
+          json_response({
+                          content:       response.content,
+                          tool_calls:    tc_list,
+                          stop_reason:   response.respond_to?(:stop_reason) ? response.stop_reason : nil,
+                          model:         session.model.to_s,
+                          input_tokens:  response.respond_to?(:input_tokens) ? response.input_tokens : nil,
+                          output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil
+                        }, status_code: 200)
+        rescue StandardError => e
+          Legion::Logging.error "[api/llm/inference] #{e.class}: #{e.message}" if defined?(Legion::Logging)
+          json_error('inference_error', e.message, status_code: 500)
+        end
+      end
+
+      def self.register_providers(app)
+        app.get '/api/llm/providers' do
+          require_llm!
+          unless gateway_available? && defined?(Legion::Extensions::LLM::Gateway::Runners::ProviderStats)
+            halt json_error('gateway_unavailable', 'LLM gateway is not loaded', status_code: 503)
+          end
+
+          stats = Legion::Extensions::LLM::Gateway::Runners::ProviderStats
+          json_response({
+                          providers: stats.health_report,
+                          summary:   stats.circuit_summary
+                        })
+        end
+
+        app.get '/api/llm/providers/:name' do
+          require_llm!
+          unless gateway_available? && defined?(Legion::Extensions::LLM::Gateway::Runners::ProviderStats)
+            halt json_error('gateway_unavailable', 'LLM gateway is not loaded', status_code: 503)
+          end
+
+          stats = Legion::Extensions::LLM::Gateway::Runners::ProviderStats
+          detail = stats.provider_detail(provider: params[:name])
+          json_response(detail)
+        end
+      end
+
+      class << self
+        private :register_chat, :register_inference, :register_providers
+      end
+    end
+  end
+end

data/lib/legion/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module LLM
-    VERSION = '0.5.14'
+    VERSION = '0.5.15'
   end
 end

data/lib/legion/llm.rb

@@ -24,6 +24,7 @@ require_relative 'llm/off_peak'
 require_relative 'llm/cost_tracker'
 require_relative 'llm/tool_registry'
 require_relative 'llm/override_confidence'
+require_relative 'llm/routes'
 
 module Legion
   module LLM
@@ -51,6 +52,7 @@ module Legion
         @started = true
         Legion::Settings[:llm][:connected] = true
         Legion::Logging.info 'Legion::LLM started'
+        register_routes
         ping_provider
       end
 
@@ -658,6 +660,15 @@ module Legion
         Legion::Logging.warn "LLM ping failed for #{provider}/#{model}: #{e.message}"
       end
 
+      def register_routes
+        return unless defined?(Legion::API) && Legion::API.respond_to?(:register_library_routes)
+
+        Legion::API.register_library_routes('llm', Legion::LLM::Routes)
+        Legion::Logging.debug 'Legion::LLM routes registered with API'
+      rescue StandardError => e
+        Legion::Logging.warn "Legion::LLM route registration failed: #{e.message}" if defined?(Legion::Logging)
+      end
+
       def auto_configure_defaults
         settings[:providers].each do |provider, config|
           next unless config&.dig(:enabled)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-llm
 version: !ruby/object:Gem::Version
-  version: 0.5.14
+  version: 0.5.15
 platform: ruby
 authors:
 - Esity
@@ -270,6 +270,7 @@ files:
 - lib/legion/llm/router/health_tracker.rb
 - lib/legion/llm/router/resolution.rb
 - lib/legion/llm/router/rule.rb
+- lib/legion/llm/routes.rb
 - lib/legion/llm/scheduling.rb
 - lib/legion/llm/settings.rb
 - lib/legion/llm/shadow_eval.rb