legionio 1.5.15 → 1.5.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d66368a89ce7ef86f5c62277fe403c840caf722f8e6b840000251775ce74e4a4
-  data.tar.gz: 8a44567875935c668bf2884e7fac6e0831f0dad9f1860f5e2bde28eedb0b7df5
+  metadata.gz: bb76821fb4802e78a19c4518c18f32a961a144cd96f0ef146ce0b582ef96f699
+  data.tar.gz: c9c6eb50bef1df98a3ede6ce943e4a45a9dc4c638ce682519708d3d0008eddd5
 SHA512:
-  metadata.gz: 7e45f6aa1d7838ed5c5ddac267310ea8163f27f1e4c8efd190720da148add55ff9f50e958c8096691d6ce3a613064322f11eba64d8fc0eae79bea26fc1ee1a9c
-  data.tar.gz: ce24287b1dd968ef9e33e053c358b7e182b92685c6696b0074fef7ab3d0447449452f9959a3086148a73b606fefc643444546ad34e596b8c8ea5039b4bf65c17
+  metadata.gz: 2e502641a0f4177baeab32e78b839f80fa163953fe55770cd0a31364b352b5eda156e0971e67057ad5263160cc5f874b7cdbfdafc1a7cc9799fdd7a9ebd73a65
+  data.tar.gz: 90ec056445d835e01d044dd1ca6272c7e30ef5cffa0e30c39d93d4c2e8004f0e4d3ff59d83e12753bc485484a68a2526e90ebe1ccfdd1fb39e12b89e549d01d1

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Legion Changelog
 
+## [1.5.19] - 2026-03-26
+
+### Added
+- `legion knowledge` CLI subcommand: query, retrieve, ingest, status (closes #36)
+  - `legion knowledge query QUESTION` — synthesized LLM answer + ranked source chunks
+  - `legion knowledge retrieve QUESTION` — raw source chunks without synthesis
+  - `legion knowledge ingest PATH` — ingest file or directory corpus
+  - `legion knowledge status` — show corpus file count and size
+
+## [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/cli/knowledge_command.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    class Knowledge < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      class_option :json,     type: :boolean, default: false, desc: 'Output as JSON'
+      class_option :no_color, type: :boolean, default: false, desc: 'Disable color output'
+
+      desc 'query QUESTION', 'Query the knowledge base with optional LLM synthesis'
+      option :top_k,      type: :numeric, default: 5, desc: 'Number of source chunks'
+      option :synthesize, type: :boolean, default: true,  desc: 'Synthesize an LLM answer'
+      option :verbose,    type: :boolean, default: false, desc: 'Show full source metadata'
+      def query(question)
+        require_knowledge!
+        result = knowledge_query.query(question: question, top_k: options[:top_k],
+                                       synthesize: options[:synthesize])
+        out = formatter
+        if options[:json]
+          out.json(result)
+        elsif result[:success]
+          out.header('Knowledge Query')
+          if result[:answer]
+            out.spacer
+            puts result[:answer]
+            out.spacer
+          end
+          print_sources(result[:sources] || [], out, verbose: options[:verbose])
+        else
+          out.warn("Query failed: #{result[:error]}")
+        end
+      end
+      default_task :help
+
+      desc 'retrieve QUESTION', 'Retrieve source chunks without LLM synthesis'
+      option :top_k, type: :numeric, default: 5, desc: 'Number of source chunks'
+      def retrieve(question)
+        require_knowledge!
+        result = knowledge_query.retrieve(question: question, top_k: options[:top_k])
+        out = formatter
+        if options[:json]
+          out.json(result)
+        elsif result[:success]
+          out.header("Knowledge Retrieve (#{(result[:sources] || []).size} chunks)")
+          print_sources(result[:sources] || [], out, verbose: true)
+        else
+          out.warn("Retrieve failed: #{result[:error]}")
+        end
+      end
+
+      desc 'ingest PATH', 'Ingest a file or directory into the knowledge base'
+      option :force,   type: :boolean, default: false, desc: 'Re-ingest even unchanged files'
+      option :dry_run, type: :boolean, default: false, desc: 'Preview without writing'
+      def ingest(path)
+        require_ingest!
+        result = if ::File.directory?(path)
+                   knowledge_ingest.ingest_corpus(path: path, force: options[:force],
+                                                  dry_run: options[:dry_run])
+                 else
+                   knowledge_ingest.ingest_file(file_path: path, force: options[:force],
+                                                dry_run: options[:dry_run])
+                 end
+        out = formatter
+        if options[:json]
+          out.json(result)
+        elsif result[:success]
+          out.success('Ingest complete')
+          out.detail(result.except(:success))
+        else
+          out.warn("Ingest failed: #{result[:error]}")
+        end
+      end
+
+      desc 'status', 'Show knowledge base status'
+      def status
+        require_ingest!
+        result = knowledge_ingest.scan_corpus(path: ::Dir.pwd)
+        out = formatter
+        if options[:json]
+          out.json(result)
+        else
+          out.header('Knowledge Status')
+          out.detail({
+                       'Path'       => result[:path].to_s,
+                       'Files'      => result[:file_count].to_s,
+                       'Total size' => "#{result[:total_bytes]} bytes"
+                     })
+        end
+      end
+
+      no_commands do
+        def formatter
+          @formatter ||= Output::Formatter.new(json: options[:json], color: !options[:no_color])
+        end
+
+        def require_knowledge!
+          return if defined?(Legion::Extensions::Knowledge::Runners::Query)
+
+          raise CLI::Error, 'lex-knowledge extension is not loaded. Install and enable it first.'
+        end
+
+        def require_ingest!
+          return if defined?(Legion::Extensions::Knowledge::Runners::Ingest)
+
+          raise CLI::Error, 'lex-knowledge extension is not loaded. Install and enable it first.'
+        end
+
+        def knowledge_query
+          Legion::Extensions::Knowledge::Runners::Query
+        end
+
+        def knowledge_ingest
+          Legion::Extensions::Knowledge::Runners::Ingest
+        end
+
+        def print_sources(sources, out, verbose:)
+          return out.warn('No sources found') if sources.empty?
+
+          out.header("Sources (#{sources.size})")
+          sources.each_with_index do |s, i|
+            score   = format('%.2f', s[:score].to_f)
+            heading = s[:heading].to_s.empty? ? '' : " \u00a7 #{s[:heading]}"
+            puts "  #{i + 1}. #{s[:source_file]}#{heading}   score: #{score}"
+            puts "     #{truncate(s[:content].to_s, 100)}" if verbose
+          end
+        end
+
+        def truncate(text, max)
+          return text if text.length <= max
+          return text[0, max] if max < 4
+
+          "#{text[0, max - 3]}..."
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli.rb

@@ -42,6 +42,7 @@ module Legion
     autoload :Eval,       'legion/cli/eval_command'
     autoload :Update,     'legion/cli/update_command'
     autoload :Init,       'legion/cli/init_command'
+    autoload :Knowledge,  'legion/cli/knowledge_command'
     autoload :Setup,      'legion/cli/setup_command'
     autoload :Skill,      'legion/cli/skill_command'
     autoload :Prompt,     'legion/cli/prompt_command'
@@ -256,6 +257,9 @@ module Legion
       desc 'apollo SUBCOMMAND', 'Apollo knowledge graph'
       subcommand 'apollo', Legion::CLI::Apollo
 
+      desc 'knowledge SUBCOMMAND', 'Search and manage the document knowledge base'
+      subcommand 'knowledge', Legion::CLI::Knowledge
+
       desc 'schedule SUBCOMMAND', 'Manage schedules'
       subcommand 'schedule', Legion::CLI::Schedule
 
@@ -348,7 +352,7 @@ module Legion
 
       desc 'tree', 'Print a tree of all available commands'
       def tree
-        legion_print_command_tree(self.class, 'legion', '')
+        legion_print_command_tree(self.class, ::File.basename($PROGRAM_NAME), '')
       end
 
       desc 'ask TEXT', 'Quick AI prompt (shortcut for chat prompt)'

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.19'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.5.15
+  version: 1.5.19
 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
@@ -616,6 +630,7 @@ files:
 - lib/legion/cli/init/environment_detector.rb
 - lib/legion/cli/init_command.rb
 - lib/legion/cli/interactive.rb
+- lib/legion/cli/knowledge_command.rb
 - lib/legion/cli/lex/actor.rb
 - lib/legion/cli/lex/exchange.rb
 - lib/legion/cli/lex/message.rb
@@ -746,7 +761,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