legion-apollo 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 63a18f390ea4ed531450615fbff3877951d39b6a4d60bdf5fbee72a2572f3817
-  data.tar.gz: 9220f43c2c962e936d82257b8e944fb9b82fd7e1c306fbb8462a3323e6e37de6
+  metadata.gz: 487b9b2441548d8c6e112f287119bc230f85d3a329e39b9b0ca5ffad0d483c23
+  data.tar.gz: 1fcd2fc638ea141c8ff48a9e13ff1d56a8e469ade43a6a28242f1d036e0a131a
 SHA512:
-  metadata.gz: '08e857932f343c0b7a5d8ec98abb1e2c2bbb4c4ba3953ef9ae33927b6a0f1861901f8646f900fba9fc233f99737805b355fa0f0176c11771fc664fe97ee54214'
-  data.tar.gz: 1d2bc1a4f9d9bf637731c48061bda8e442316feeb4a0eb29ccf0546d20ea1363be795c737079730706707659b1beef7cb81de63087ff4944084c25a9320e9eda
+  metadata.gz: f4aa0535295bdded7f8fb087b344461cc269f477cd772e0c66c18706ae7f128e4eecac8c7f56c7ac29b808836d2f1c05eafeb088bbbe7f334aa13a256f45aaec
+  data.tar.gz: 7faa330d5b94f70cd0083fbc49b0ccf329c63604f7de35f7196bd552ff356efd2d7c11856efa7138f2313fdb56b3aae4bdc36c07ba402877dd57c19be6604017

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.3.1] - 2026-03-26
+
+### Added
+- `scope:` param on `query`/`retrieve`/`ingest` — `:global` (default), `:local` (SQLite only), `:all` (merged global + local)
+- `Legion::Apollo::Runners::Request` shim — GAIA `knowledge_retrieval` phase now resolves to merged retrieval without any changes to `legion-gaia`
+- Merge helpers: `query_merged`, `normalize_local_entries`, `normalize_global_entries`, `dedup_and_rank`
+- Ingest routing: `ingest_local` and `ingest_all` private helpers
+
 ## [0.3.0] - 2026-03-25
 
 ### Added

data/lib/legion/apollo/runners/request.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Legion
+  module Apollo
+    module Runners
+      # GAIA knowledge_retrieval shim — delegates to Legion::Apollo.retrieve with scope: :all.
+      module Request
+        def self.retrieve(text:, limit: 5, **)
+          Legion::Apollo.retrieve(text: text, limit: limit, scope: :all, **)
+        end
+      end
+    end
+  end
+end

data/lib/legion/apollo/runners.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'runners/request'

data/lib/legion/apollo/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Apollo
-    VERSION = '0.3.0'
+    VERSION = '0.3.1'
   end
 end

data/lib/legion/apollo.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
+require 'digest'
 require_relative 'apollo/version'
 require_relative 'apollo/settings'
 require_relative 'apollo/local'
+require_relative 'apollo/runners'
 
 module Legion
   # Apollo client library — query, ingest, and retrieve with smart routing.
   # Routes to a co-located lex-apollo service when available, falls back to
   # RabbitMQ transport, and degrades gracefully when neither is present.
+  # Supports scope: :global (default), :local (SQLite only), :all (merged).
   module Apollo # rubocop:disable Metrics/ModuleLength
     class << self # rubocop:disable Metrics/ClassLength
       def start
@@ -36,39 +39,49 @@ module Legion
         Legion::Apollo::Local
       end
 
-      def query(text:, limit: nil, min_confidence: nil, tags: nil, **opts) # rubocop:disable Metrics/MethodLength
+      def query(text:, limit: nil, min_confidence: nil, tags: nil, scope: :global, **opts) # rubocop:disable Metrics/MethodLength,Metrics/CyclomaticComplexity,Metrics/ParameterLists
         return not_started_error unless started?
 
-        limit ||= apollo_setting(:default_limit, 5)
+        limit          ||= apollo_setting(:default_limit, 5)
         min_confidence ||= apollo_setting(:min_confidence, 0.3)
 
         payload = { text: text, limit: limit, min_confidence: min_confidence, tags: tags, **opts }
 
-        if co_located_reader?
-          direct_query(payload)
-        elsif transport_available?
-          publish_query(payload)
+        case scope
+        when :local then query_local(payload)
+        when :all   then query_merged(payload)
         else
-          { success: false, error: :no_path_available }
+          if co_located_reader?
+            direct_query(payload)
+          elsif transport_available?
+            publish_query(payload)
+          else
+            { success: false, error: :no_path_available }
+          end
         end
       end
 
-      def ingest(content:, tags: [], **opts)
+      def ingest(content:, tags: [], scope: :global, **opts) # rubocop:disable Metrics/MethodLength
         return not_started_error unless started?
 
         payload = { content: content, tags: Array(tags).first(apollo_setting(:max_tags, 20)), **opts }
 
-        if co_located_writer?
-          direct_ingest(payload)
-        elsif transport_available?
-          publish_ingest(payload)
+        case scope
+        when :local then ingest_local(payload)
+        when :all   then ingest_all(payload)
         else
-          { success: false, error: :no_path_available }
+          if co_located_writer?
+            direct_ingest(payload)
+          elsif transport_available?
+            publish_ingest(payload)
+          else
+            { success: false, error: :no_path_available }
+          end
         end
       end
 
-      def retrieve(text:, limit: 5, **)
-        query(text: text, limit: limit, **)
+      def retrieve(text:, limit: 5, scope: :global, **)
+        query(text: text, limit: limit, scope: scope, **)
       end
 
       def transport_available?
@@ -150,6 +163,128 @@ module Legion
         { success: false, error: e.message }
       end
 
+      def query_local(payload)
+        return { success: false, error: :no_path_available } unless Legion::Apollo::Local.started?
+
+        result = Legion::Apollo::Local.query(**payload.slice(:text, :limit, :min_confidence, :tags))
+        return result unless result[:success]
+
+        entries = normalize_local_entries(Array(result[:results]))
+        { success: true, entries: entries, count: entries.size, mode: :local }
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      def query_merged(payload) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        entries = []
+        attempted = false
+        any_success = false
+        errors = []
+
+        if co_located_reader?
+          attempted = true
+          global = direct_query(payload)
+          if global[:success]
+            any_success = true
+            entries.concat(normalize_global_entries(Array(global[:entries]))) if global[:entries]
+          else
+            errors << global[:error]
+          end
+        end
+
+        if Legion::Apollo::Local.started?
+          attempted = true
+          local = Legion::Apollo::Local.query(**payload.slice(:text, :limit, :min_confidence, :tags))
+          if local[:success]
+            any_success = true
+            entries.concat(normalize_local_entries(Array(local[:results]))) if local[:results]
+          else
+            errors << local[:error]
+          end
+        end
+
+        return { success: false, error: :no_path_available } unless attempted
+
+        unless any_success
+          combined_error = errors.compact.map(&:to_s).reject(&:empty?).join('; ')
+          combined_error = :upstream_query_failed if combined_error.empty?
+          return { success: false, error: combined_error }
+        end
+
+        ranked = dedup_and_rank(entries, limit: payload[:limit])
+        { success: true, entries: ranked, count: ranked.size, mode: :merged }
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      def normalize_local_entries(entries) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+        entries.map do |e|
+          hash = e[:content_hash] || Digest::MD5.hexdigest(e[:content].to_s.strip.downcase.gsub(/\s+/, ' '))
+          tags = if e[:tags].is_a?(String)
+                   begin
+                     ::JSON.parse(e[:tags])
+                   rescue StandardError
+                     []
+                   end
+                 else
+                   Array(e[:tags])
+                 end
+          { id: e[:id], content: e[:content], content_hash: hash,
+            confidence: e[:confidence] || 0.5, content_type: 'fact', tags: tags, source: :local }
+        end
+      end
+
+      def normalize_global_entries(entries)
+        entries.map do |e|
+          hash = e[:content_hash] || Digest::MD5.hexdigest(e[:content].to_s.strip.downcase.gsub(/\s+/, ' '))
+          { id: e[:id], content: e[:content], content_hash: hash,
+            confidence: e[:confidence] || 0.5, content_type: e[:content_type] || 'fact',
+            tags: Array(e[:tags]), source: :global }
+        end
+      end
+
+      def dedup_and_rank(entries, limit:)
+        sorted = entries
+                 .sort_by { |e| -(e[:confidence] || 0) }
+                 .uniq { |e| e[:content_hash] }
+
+        limit ? sorted.first(limit) : sorted
+      end
+
+      def ingest_local(payload)
+        return { success: false, error: :no_path_available } unless Legion::Apollo::Local.started?
+
+        Legion::Apollo::Local.ingest(**payload)
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
+      def ingest_all(payload) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+        results = []
+
+        if co_located_writer?
+          results << direct_ingest(payload)
+        elsif transport_available?
+          results << publish_ingest(payload)
+        end
+
+        results << Legion::Apollo::Local.ingest(**payload) if Legion::Apollo::Local.started?
+
+        return { success: false, error: :no_path_available } if results.empty?
+
+        overall_success = results.any? { |r| r.respond_to?(:[]) && r[:success] }
+
+        if overall_success
+          { success: true, mode: :all, results: results }
+        else
+          errors = results.select { |r| r.respond_to?(:[]) }.map { |r| r[:error] }.compact.uniq
+          error_value = errors.length <= 1 ? errors.first : errors
+          { success: false, mode: :all, results: results, error: error_value }
+        end
+      rescue StandardError => e
+        { success: false, error: e.message }
+      end
+
       def apollo_setting(key, default)
         return default unless defined?(Legion::Settings) && !Legion::Settings[:apollo].nil?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-apollo
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Esity
@@ -76,6 +76,8 @@ files:
 - lib/legion/apollo/messages/ingest.rb
 - lib/legion/apollo/messages/query.rb
 - lib/legion/apollo/messages/writeback.rb
+- lib/legion/apollo/runners.rb
+- lib/legion/apollo/runners/request.rb
 - lib/legion/apollo/settings.rb
 - lib/legion/apollo/version.rb
 homepage: https://github.com/LegionIO/legion-apollo