legionio 1.5.15 → 1.5.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d66368a89ce7ef86f5c62277fe403c840caf722f8e6b840000251775ce74e4a4
-  data.tar.gz: 8a44567875935c668bf2884e7fac6e0831f0dad9f1860f5e2bde28eedb0b7df5
+  metadata.gz: fa969cacd00cbd7fcd3234d1d7b46e720da00a4193b4faa967d0f4e9b662b4e4
+  data.tar.gz: 2afe90f9456b0c5abf07f7180d562dd84ac7c901e81aea1b841288f3aae929d6
 SHA512:
-  metadata.gz: 7e45f6aa1d7838ed5c5ddac267310ea8163f27f1e4c8efd190720da148add55ff9f50e958c8096691d6ce3a613064322f11eba64d8fc0eae79bea26fc1ee1a9c
-  data.tar.gz: ce24287b1dd968ef9e33e053c358b7e182b92685c6696b0074fef7ab3d0447449452f9959a3086148a73b606fefc643444546ad34e596b8c8ea5039b4bf65c17
+  metadata.gz: bf23f83209770f3e9b7c66bd59ccae187f24c136b94059b5bc54a58e9e80188280a94f01ce557eab19eb1a903bcd9e1a9d69cf7a46077ab89297f934ca1b5244
+  data.tar.gz: cf041438573f2eb546929ef68e35c527b52af9f552e129fd79b6c94f75862361eeee9d63d4f1fc2b26fecbd70078cc97614c6e928c7fa45cb317b3de858c4eea

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Legion Changelog
 
+## [1.5.18] - 2026-03-25
+
+### Added
+- `scope:` parameter on `Helpers::Knowledge` (`ingest_knowledge` and `query_knowledge`)
+- Scope routing: `:local` -> `Apollo::Local`, `:global` -> `Apollo`, `:all` -> both with local-first dedup
+- Default query scope configurable via `Settings[:apollo][:local][:default_query_scope]`
+- `setup_apollo` now starts `Apollo::Local` when available
+
+## [1.5.17] - 2026-03-25
+
+### Added
+- `Helpers::Knowledge` — universal `ingest_knowledge` and `query_knowledge` mixin for all extensions; included automatically in `Extensions::Core`
+- Automatic file extraction via `Legion::Data::Extract` when a file path is passed to `ingest_knowledge`
+- Graceful degradation when `Legion::Apollo` or `Legion::Data::Extract` are not available
+- `setup_apollo` in `Service` boot sequence (between LLM and GAIA); wires `Legion::Apollo.start` with `LoadError`/`StandardError` rescue
+- `:apollo` added to `Readiness::COMPONENTS` between `:llm` and `:gaia`
+- `legion-apollo >= 0.2.1` dependency in gemspec
+- `Helpers::LLM#llm_embed` in LegionIO now forwards all keyword arguments (`provider:`, `dimensions:`, etc.) via anonymous `**` forwarding
+
 ## [1.5.15] - 2026-03-25
 
 ### Removed

data/Gemfile

@@ -11,6 +11,7 @@ gem 'legion-logging', path: '../legion-logging' if File.exist?(File.expand_path(
 gem 'legion-mcp', path: '../legion-mcp' if File.exist?(File.expand_path('../legion-mcp', __dir__))
 gem 'legion-settings', path: '../legion-settings' if File.exist?(File.expand_path('../legion-settings', __dir__))
 
+gem 'legion-apollo', path: '../legion-apollo' if File.exist?(File.expand_path('../legion-apollo', __dir__))
 gem 'lex-agentic-memory', path: '../extensions-agentic/lex-agentic-memory' if File.exist?(File.expand_path('../extensions-agentic/lex-agentic-memory', __dir__))
 gem 'lex-llm-gateway', path: '../extensions-core/lex-llm-gateway' if File.exist?(File.expand_path('../extensions-core/lex-llm-gateway', __dir__))
 gem 'lex-microsoft_teams', path: '../extensions/lex-microsoft_teams' if File.exist?(File.expand_path('../extensions/lex-microsoft_teams', __dir__))

data/legionio.gemspec

@@ -60,6 +60,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-settings', '>= 1.3.19'
   spec.add_dependency 'legion-transport', '>= 1.4.0'
 
+  spec.add_dependency 'legion-apollo', '>= 0.2.1'
   spec.add_dependency 'legion-gaia', '>= 0.9.24'
   spec.add_dependency 'legion-llm', '>= 0.5.8'
   spec.add_dependency 'legion-tty', '>= 0.4.35'

data/lib/legion/extensions/core.rb

@@ -21,6 +21,18 @@ rescue LoadError => e
   Legion::Logging.debug "Extensions::Core: legion-llm helpers not available: #{e.message}" if defined?(Legion::Logging)
 end
 
+begin
+  require_relative 'helpers/llm'
+rescue LoadError => e
+  Legion::Logging.debug "Extensions::Core: local llm helper not available: #{e.message}" if defined?(Legion::Logging)
+end
+
+begin
+  require_relative 'helpers/knowledge'
+rescue LoadError => e
+  Legion::Logging.debug "Extensions::Core: knowledge helper not available: #{e.message}" if defined?(Legion::Logging)
+end
+
 require_relative 'actors/base'
 require_relative 'actors/every'
 require_relative 'actors/loop'
@@ -35,6 +47,7 @@ module Legion
     module Core
       include Legion::Extensions::Helpers::Transport
       include Legion::Extensions::Helpers::Lex
+      include Legion::Extensions::Helpers::Knowledge if defined?(Legion::Extensions::Helpers::Knowledge)
 
       include Legion::Extensions::Builder::Runners
       include Legion::Extensions::Builder::Helpers

data/lib/legion/extensions/helpers/knowledge.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Helpers
+      module Knowledge
+        def ingest_knowledge(content_or_path, type: :auto, tags: [], scope: :global, **opts)
+          target = resolve_ingest_target(scope)
+          return { success: false, error: :apollo_not_available } unless target
+
+          text, metadata = extract_if_needed(content_or_path, type: type)
+          return { success: false, error: :extraction_failed, detail: metadata } unless text
+
+          extraction_tags = metadata_to_tags(metadata) if metadata
+          all_tags = Array(tags) + Array(extraction_tags)
+
+          target.ingest(
+            content:        text,
+            tags:           all_tags,
+            source_channel: opts[:source_channel] || derive_lex_name,
+            **opts.except(:source_channel)
+          )
+        end
+
+        def query_knowledge(text:, limit: 5, scope: nil, **)
+          scope ||= default_query_scope
+
+          case scope.to_sym
+          when :local  then query_local(text: text, limit: limit, **)
+          when :global then query_global(text: text, limit: limit, **)
+          else              query_all(text: text, limit: limit, **)
+          end
+        end
+
+        private
+
+        def resolve_ingest_target(scope)
+          case scope.to_sym
+          when :local
+            local_available? ? Legion::Apollo::Local : nil
+          else
+            global_available? ? Legion::Apollo : nil
+          end
+        end
+
+        def query_local(text:, limit:, **)
+          unless local_available?
+            Legion::Logging.debug 'query_knowledge(:local) called but Apollo::Local is not available' if defined?(Legion::Logging)
+            return { success: false, error: :apollo_not_available }
+          end
+
+          Legion::Apollo::Local.query(text: text, limit: limit, **)
+        end
+
+        def query_global(text:, limit:, **)
+          unless global_available?
+            Legion::Logging.debug 'query_knowledge(:global) called but Apollo is not available' if defined?(Legion::Logging)
+            return { success: false, error: :apollo_not_available }
+          end
+
+          Legion::Apollo.query(text: text, limit: limit, **)
+        end
+
+        def query_all(text:, limit:, **)
+          local_results  = local_available?  ? Array((Legion::Apollo::Local.query(text: text, limit: limit, **) || {})[:results]) : []
+          global_results = global_available? ? Array((Legion::Apollo.query(text: text, limit: limit, **) || {})[:results]) : []
+
+          return { success: false, error: :apollo_not_available } if local_results.empty? && global_results.empty? && !local_available? && !global_available?
+
+          merged = merge_results(local_results, global_results)
+          { success: true, results: merged.first(limit), count: [merged.size, limit].min, mode: :all }
+        end
+
+        def merge_results(local_results, global_results)
+          seen = {}
+          merged = []
+
+          local_results.each do |r|
+            key = r[:content_hash] || r[:content]
+            seen[key] = true
+            merged << r
+          end
+
+          global_results.each do |r|
+            key = r[:content_hash] || r[:content]
+            merged << r unless seen[key]
+          end
+
+          merged
+        end
+
+        def global_available?
+          defined?(Legion::Apollo) && Legion::Apollo.started?
+        end
+
+        def local_available?
+          defined?(Legion::Apollo::Local) && Legion::Apollo::Local.started?
+        end
+
+        def default_query_scope
+          return :all unless defined?(Legion::Settings)
+
+          scope = Legion::Settings.dig(:apollo, :local, :default_query_scope)
+          scope ? scope.to_sym : :all
+        rescue StandardError
+          :all
+        end
+
+        def extract_if_needed(content_or_path, type:)
+          return extract_file(content_or_path, type: type) if content_or_path.is_a?(String) && File.exist?(content_or_path)
+          return extract_file(content_or_path, type: type) if content_or_path.respond_to?(:read)
+
+          [content_or_path.to_s, nil]
+        end
+
+        def extract_file(source, type:)
+          return [source.to_s, nil] unless defined?(Legion::Data::Extract)
+
+          result = Legion::Data::Extract.extract(source, type: type)
+          if result[:text]
+            [result[:text], result[:metadata]]
+          else
+            [nil, result]
+          end
+        end
+
+        def metadata_to_tags(metadata)
+          tags = []
+          tags << metadata[:type].to_s if metadata[:type]
+          tags << "pages:#{metadata[:pages]}" if metadata[:pages]
+          tags
+        end
+
+        def derive_lex_name
+          parts = self.class.name&.split('::')
+          parts && parts[2] ? parts[2].downcase : 'unknown'
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Helpers
+      module LLM
+        # Quick embed from any extension runner, forwarding all keyword arguments.
+        # Supports provider:, dimensions:, and any future parameters.
+        # @param text [String, Array<String>] text to embed
+        # @param kwargs [Hash] forwarded to Legion::LLM.embed (model:, provider:, dimensions:, etc.)
+        # @return [Hash] embedding result with :vector, :dimensions, :model, :provider
+        def llm_embed(text, **)
+          Legion::LLM.embed(text, **)
+        end
+      end
+    end
+  end
+end

data/lib/legion/readiness.rb

@@ -2,7 +2,7 @@
 
 module Legion
   module Readiness
-    COMPONENTS = %i[settings crypt transport cache data rbac llm gaia extensions api].freeze
+    COMPONENTS = %i[settings crypt transport cache data rbac llm apollo gaia extensions api].freeze
     DRAIN_TIMEOUT = 5
 
     class << self

data/lib/legion/service.rb

@@ -98,6 +98,15 @@ module Legion
         end
       end
 
+      begin
+        setup_apollo
+        Legion::Readiness.mark_ready(:apollo)
+      rescue LoadError
+        Legion::Logging.info 'Legion::Apollo gem is not installed, starting without Apollo'
+      rescue StandardError => e
+        Legion::Logging.warn "Legion::Apollo failed to load: #{e.message}"
+      end
+
       if gaia
         begin
           setup_gaia
@@ -317,6 +326,18 @@ module Legion
       Legion::Logging.warn "Legion::Gaia failed to load: #{e.message}"
     end
 
+    def setup_apollo
+      Legion::Logging.info 'Setting up Legion::Apollo'
+      require 'legion/apollo'
+      Legion::Apollo.start
+      Legion::Apollo::Local.start if defined?(Legion::Apollo::Local)
+      Legion::Logging.info 'Legion::Apollo started'
+    rescue LoadError
+      Legion::Logging.info 'Legion::Apollo gem is not installed, starting without Apollo'
+    rescue StandardError => e
+      Legion::Logging.warn "Legion::Apollo failed to load: #{e.message}"
+    end
+
     def setup_transport
       Legion::Logging.info 'Setting up Legion::Transport'
       require 'legion/transport'

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.5.15'
+  VERSION = '1.5.18'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.5.15
+  version: 1.5.18
 platform: ruby
 authors:
 - Esity
@@ -317,6 +317,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.4.0
+- !ruby/object:Gem::Dependency
+  name: legion-apollo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: legion-gaia
   requirement: !ruby/object:Gem::Requirement
@@ -746,7 +760,9 @@ files:
 - lib/legion/extensions/helpers/cache.rb
 - lib/legion/extensions/helpers/core.rb
 - lib/legion/extensions/helpers/data.rb
+- lib/legion/extensions/helpers/knowledge.rb
 - lib/legion/extensions/helpers/lex.rb
+- lib/legion/extensions/helpers/llm.rb
 - lib/legion/extensions/helpers/logger.rb
 - lib/legion/extensions/helpers/segments.rb
 - lib/legion/extensions/helpers/task.rb