lex-apollo 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c5141f161198efe7dbdd37179e46bf36ec1c58404efa645897bc256975d3f8
-  data.tar.gz: c2ac6728af5ada2ab45eb8fff0a0e80d6bceac5464305bca18bd836c81fc0ffb
+  metadata.gz: 692cd508a98259d83ceaf2c6b752c7c87ddeb219145291bd568fa76430e41577
+  data.tar.gz: b02962423b3dff2950af8b51b0cf5035a8db72f6c2ef80c4f1e54f9f0989e25c
 SHA512:
-  metadata.gz: 45328d181484cabb6a17aceb9d6d1a816a623fbe1dc8f5c80972b9151a2250f244d88ba88551cf0cecac70229732546a35abe32189a2ff75a4026010279a810e
-  data.tar.gz: 1eab2286abce601fe8a95b75c0da2edb0017bebb39e09abe05a1c7dbf72658e7955147b2ab1e1b6ed743788ed61a86c4871919e7ab53762ef3e2e40906eea00f
+  metadata.gz: 7c4989d252540ae09177a73f389a1f4d1a09c51aee09acdf88bdfbb9ffb3e5d7c6522e8cf0953117518011f199f97f1e76dacb6d88aa2f10a48ecfe1da064497
+  data.tar.gz: a806f1485d4f3ef587f2fbd015180c027934ac87b080c4e0264ccb12a478708d89d0aa313ac3c9b2f20ed3c64ec779e2468ec7b457967c7cb6c1ce780324a884

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.4.5] - 2026-03-25
+
+### Added
+- `handle_traverse` method in Knowledge runner: executes recursive CTE graph traversal SQL, returns formatted entries with depth and activation scores (closes #3)
+- `Runners::Request` client-tier runner with `data_required? false`: routes `query`, `retrieve`, `ingest`, `traverse` locally when DB is available or via transport when it isn't (closes #1)
+- REST API (`Api` Sinatra app) with 8 endpoints: health, query, ingest, traverse, retrieve, deprecate, expertise, stats (closes #5)
+- Conditional `require 'legion/extensions/apollo/api'` when Sinatra is available
+
+### Fixed
+- Contradiction detection now orders by embedding distance (`<=>` pgvector operator) before LIMIT, scanning the most semantically similar entries instead of arbitrary rows (closes #4)
+- Whitelisted `relation_types` in `handle_traverse` against `RELATION_TYPES` constant to prevent SQL injection
+
+### Changed
+- GAIA phase wiring updated: `knowledge_retrieval` now targets `Request#retrieve` instead of `Knowledge#retrieve_relevant` (in legion-gaia)
+
 ## [0.4.4] - 2026-03-24
 
 ### Changed

data/lib/legion/extensions/apollo/api.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require 'sinatra/base' unless defined?(Sinatra)
+require 'json'
+
+module Legion
+  module Extensions
+    module Apollo
+      class Api < Sinatra::Base
+        set :host_authorization, permitted: :any
+
+        before do
+          content_type :json
+        end
+
+        helpers do
+          def json_body
+            body = request.body.read
+            return {} if body.empty?
+
+            ::JSON.parse(body, symbolize_names: true)
+          rescue ::JSON::ParserError
+            halt 400, { error: 'invalid JSON' }.to_json
+          end
+
+          def runner
+            @runner ||= begin
+              obj = Object.new
+              obj.extend(Runners::Knowledge)
+              obj
+            end
+          end
+
+          def expertise_runner
+            @expertise_runner ||= begin
+              obj = Object.new
+              obj.extend(Runners::Expertise)
+              obj
+            end
+          end
+        end
+
+        # Health check
+        get '/api/apollo/health' do
+          available = defined?(Legion::Data::Model::ApolloEntry) ? true : false
+          { status: available ? 'ok' : 'degraded', data_available: available }.to_json
+        end
+
+        # Query knowledge (semantic search)
+        post '/api/apollo/query' do
+          req = json_body
+          halt 400, { error: 'query is required' }.to_json unless req[:query]
+
+          result = runner.handle_query(
+            query:          req[:query],
+            limit:          req[:limit] || 10,
+            min_confidence: req[:min_confidence] || 0.3,
+            status:         req[:status] || [:confirmed],
+            tags:           req[:tags],
+            domain:         req[:domain],
+            agent_id:       req[:agent_id] || 'api'
+          )
+          status result[:success] ? 200 : 500
+          result.to_json
+        end
+
+        # Ingest knowledge
+        post '/api/apollo/ingest' do
+          req = json_body
+          halt 400, { error: 'content is required' }.to_json unless req[:content]
+          halt 400, { error: 'content_type is required' }.to_json unless req[:content_type]
+
+          result = runner.handle_ingest(
+            content:          req[:content],
+            content_type:     req[:content_type],
+            tags:             req[:tags] || [],
+            source_agent:     req[:source_agent] || 'api',
+            source_provider:  req[:source_provider],
+            source_channel:   req[:source_channel],
+            knowledge_domain: req[:knowledge_domain],
+            context:          req[:context] || {}
+          )
+          status result[:success] ? 201 : 500
+          result.to_json
+        end
+
+        # Graph traversal
+        post '/api/apollo/traverse' do
+          req = json_body
+          halt 400, { error: 'entry_id is required' }.to_json unless req[:entry_id]
+
+          result = runner.handle_traverse(
+            entry_id:       req[:entry_id],
+            depth:          req[:depth] || 2,
+            relation_types: req[:relation_types],
+            agent_id:       req[:agent_id] || 'api'
+          )
+          status result[:success] ? 200 : 500
+          result.to_json
+        end
+
+        # Retrieve relevant (GAIA-compatible)
+        post '/api/apollo/retrieve' do
+          req = json_body
+          halt 400, { error: 'query is required' }.to_json unless req[:query]
+
+          result = runner.retrieve_relevant(
+            query:          req[:query],
+            limit:          req[:limit] || 5,
+            min_confidence: req[:min_confidence] || 0.3,
+            tags:           req[:tags],
+            domain:         req[:domain]
+          )
+          status result[:success] ? 200 : 500
+          result.to_json
+        end
+
+        # Deprecate entry
+        post '/api/apollo/entries/:id/deprecate' do
+          result = runner.deprecate_entry(
+            entry_id: params[:id],
+            reason:   json_body[:reason] || 'deprecated via API'
+          )
+          result.to_json
+        end
+
+        # Domains at risk — must be declared before /:agent_id to avoid routing conflict
+        get '/api/apollo/expertise/at-risk' do
+          result = expertise_runner.domains_at_risk
+          result.to_json
+        end
+
+        # Expertise for an agent
+        get '/api/apollo/expertise/:agent_id' do
+          result = expertise_runner.agent_profile(agent_id: params[:agent_id])
+          result.to_json
+        end
+
+        # Statistics
+        get '/api/apollo/stats' do
+          stats = {}
+          if defined?(Legion::Data::Model::ApolloEntry)
+            stats[:total_entries] = Legion::Data::Model::ApolloEntry.count
+            stats[:by_status]     = Legion::Data::Model::ApolloEntry.group_and_count(:status).all
+                                                                    .to_h { |r| [r[:status], r[:count]] }
+            stats[:by_content_type] = Legion::Data::Model::ApolloEntry.group_and_count(:content_type).all
+                                                                      .to_h { |r| [r[:content_type], r[:count]] }
+            stats[:total_relations] = Legion::Data::Model::ApolloRelation.count if defined?(Legion::Data::Model::ApolloRelation)
+          else
+            stats[:error] = 'apollo_data_not_available'
+          end
+          stats.to_json
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/runners/knowledge.rb

@@ -140,6 +140,36 @@ module Legion
             { success: false, error: e.message }
           end
 
+          def handle_traverse(entry_id:, depth: Helpers::GraphQuery.default_depth, relation_types: nil, agent_id: 'unknown', **)
+            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+
+            # Whitelist relation_types to prevent SQL injection (they are string-interpolated in build_traversal_sql)
+            if relation_types
+              allowed = Helpers::Confidence::RELATION_TYPES
+              relation_types = relation_types.select { |t| allowed.include?(t.to_s) }
+            end
+
+            sql = Helpers::GraphQuery.build_traversal_sql(depth: depth, relation_types: relation_types)
+            db = Legion::Data::Model::ApolloEntry.db
+            entries = db.fetch(sql, entry_id: entry_id).all
+
+            if entries.any? && agent_id != 'unknown'
+              Legion::Data::Model::ApolloAccessLog.create(
+                entry_id: entry_id, agent_id: agent_id, action: 'query'
+              )
+            end
+
+            formatted = entries.map do |entry|
+              { id: entry[:id], content: entry[:content], content_type: entry[:content_type],
+                confidence: entry[:confidence], tags: entry[:tags], source_agent: entry[:source_agent],
+                depth: entry[:depth], activation: entry[:activation] }
+            end
+
+            { success: true, entries: formatted, count: formatted.size }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
           def redistribute_knowledge(agent_id:, min_confidence: Helpers::Confidence.apollo_setting(:query, :redistribute_min_confidence, default: 0.5), **)
             return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
@@ -281,25 +311,30 @@ module Legion
             sim_threshold = Helpers::Confidence.apollo_setting(:contradiction, :similarity_threshold, default: 0.7)
             rel_weight = Helpers::Confidence.apollo_setting(:contradiction, :relation_weight, default: 0.8)
 
-            similar = Legion::Data::Model::ApolloEntry
-                      .exclude(id: entry_id)
-                      .exclude(embedding: nil)
-                      .limit(sim_limit).all
+            db = Legion::Data::Model::ApolloEntry.db
+            similar = db.fetch(
+              "SELECT id, content, embedding FROM apollo_entries WHERE id != $entry_id AND embedding IS NOT NULL ORDER BY embedding <=> $embedding LIMIT #{sim_limit}", # rubocop:disable Layout/LineLength
+              entry_id:  entry_id,
+              embedding: Sequel.lit("'[#{embedding.join(',')}]'::vector")
+            ).all
 
             contradictions = []
             similar.each do |existing|
-              sim = Helpers::Similarity.cosine_similarity(vec_a: embedding, vec_b: existing.embedding)
+              existing_embedding = existing[:embedding]
+              next unless existing_embedding
+
+              sim = Helpers::Similarity.cosine_similarity(vec_a: embedding, vec_b: existing_embedding)
               next unless sim > sim_threshold
-              next unless llm_detects_conflict?(content, existing.content)
+              next unless llm_detects_conflict?(content, existing[:content])
 
               Legion::Data::Model::ApolloRelation.create(
-                from_entry_id: entry_id, to_entry_id: existing.id,
+                from_entry_id: entry_id, to_entry_id: existing[:id],
                 relation_type: 'contradicts', source_agent: 'system:contradiction',
                 weight: rel_weight
               )
 
-              Legion::Data::Model::ApolloEntry.where(id: [entry_id, existing.id]).update(status: 'disputed')
-              contradictions << existing.id
+              Legion::Data::Model::ApolloEntry.where(id: [entry_id, existing[:id]]).update(status: 'disputed')
+              contradictions << existing[:id]
             end
             contradictions
           rescue Sequel::Error

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Apollo
+      module Runners
+        module Request
+          extend self
+
+          def self.data_required?
+            false
+          end
+
+          def query(text:, limit: Helpers::GraphQuery.default_query_limit, min_confidence: Helpers::GraphQuery.default_query_min_confidence, tags: nil, # rubocop:disable Metrics/ParameterLists
+                    domain: nil, agent_id: 'unknown', **)
+            if local_service_available?
+              knowledge_host.handle_query(query: text, limit: limit, min_confidence: min_confidence,
+                                          tags: tags, domain: domain, agent_id: agent_id)
+            elsif transport_available?
+              publish_query(action: :query, query: text, limit: limit, min_confidence: min_confidence,
+                            tags: tags, domain: domain)
+            else
+              { success: false, error: :no_path_available }
+            end
+          end
+
+          def retrieve(text:, limit: 5, min_confidence: Helpers::GraphQuery.default_query_min_confidence, tags: nil, domain: nil, **)
+            if local_service_available?
+              knowledge_host.retrieve_relevant(query: text, limit: limit, min_confidence: min_confidence,
+                                               tags: tags, domain: domain)
+            elsif transport_available?
+              publish_query(action: :query, query: text, limit: limit, min_confidence: min_confidence,
+                            tags: tags, domain: domain)
+            else
+              { success: false, error: :no_path_available }
+            end
+          end
+
+          def ingest(content:, content_type:, tags: [], source_agent: 'unknown', **)
+            if local_service_available?
+              knowledge_host.handle_ingest(content: content, content_type: content_type,
+                                           tags: tags, source_agent: source_agent, **)
+            elsif transport_available?
+              publish_ingest(content: content, content_type: content_type,
+                             tags: tags, source_agent: source_agent, **)
+            else
+              { success: false, error: :no_path_available }
+            end
+          end
+
+          def traverse(entry_id:, depth: Helpers::GraphQuery.default_depth, relation_types: nil, agent_id: 'unknown', **)
+            if local_service_available?
+              knowledge_host.handle_traverse(entry_id: entry_id, depth: depth,
+                                             relation_types: relation_types, agent_id: agent_id)
+            elsif transport_available?
+              publish_query(action: :traverse, entry_id: entry_id, depth: depth,
+                            relation_types: relation_types)
+            else
+              { success: false, error: :no_path_available }
+            end
+          end
+
+          private
+
+          def knowledge_host
+            @knowledge_host ||= Object.new.extend(Knowledge)
+          end
+
+          def local_service_available?
+            defined?(Legion::Data::Model::ApolloEntry) &&
+              defined?(Knowledge)
+          end
+
+          def transport_available?
+            defined?(Legion::Transport) &&
+              Legion::Transport.respond_to?(:connected?) &&
+              Legion::Transport.connected?
+          end
+
+          def publish_query(**payload)
+            Transport::Messages::Query.new(payload).publish
+            { success: true, dispatched: :transport, payload: payload }
+          rescue StandardError => e
+            { success: false, error: e.message }
+          end
+
+          def publish_ingest(**payload)
+            Transport::Messages::Ingest.new(payload).publish
+            { success: true, dispatched: :transport, payload: payload }
+          rescue StandardError => e
+            { success: false, error: e.message }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Apollo
-      VERSION = '0.4.4'
+      VERSION = '0.4.5'
     end
   end
 end

data/lib/legion/extensions/apollo.rb

@@ -9,6 +9,9 @@ require 'legion/extensions/apollo/runners/expertise'
 require 'legion/extensions/apollo/runners/maintenance'
 require 'legion/extensions/apollo/runners/entity_extractor'
 require 'legion/extensions/apollo/runners/gas'
+require 'legion/extensions/apollo/runners/request'
+
+require 'legion/extensions/apollo/api' if defined?(Sinatra)
 
 if defined?(Legion::Transport)
   require 'legion/extensions/apollo/transport/exchanges/apollo'

data/spec/legion/extensions/apollo/api_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Stub Sinatra before requiring api.rb so the guard `unless defined?(Sinatra)` fires.
+# This avoids a LoadError when sinatra is not in the bundle.
+unless defined?(Sinatra)
+  module Sinatra
+    class Base
+      class << self
+        def set(*, **); end
+        def before(*, &); end
+        def helpers(*, &); end
+        def get(*, &); end
+        def post(*, &); end
+        def put(*, &); end
+        def delete(*, &); end
+      end
+    end
+  end
+end
+
+require 'spec_helper'
+require 'legion/extensions/apollo/api'
+
+RSpec.describe Legion::Extensions::Apollo::Api do
+  it 'is defined as a Sinatra app' do
+    expect(described_class.superclass).to eq(Sinatra::Base)
+  end
+end

data/spec/legion/extensions/apollo/contradiction_spec.rb

@@ -15,5 +15,37 @@ RSpec.describe 'Apollo Contradiction Detection' do
     it 'returns empty when ApolloEntry model unavailable' do
       expect(knowledge.send(:detect_contradictions, 1, nil, 'test')).to eq([])
     end
+
+    it 'returns empty when embedding is nil' do
+      expect(knowledge.send(:detect_contradictions, 'uuid-1', nil, 'test')).to eq([])
+    end
+
+    context 'when entries exist' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+      let(:mock_relation_class) { double('ApolloRelation') }
+      let(:mock_db) { double('db') }
+      let(:embedding) { Array.new(1536, 0.1) }
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        stub_const('Legion::Data::Model::ApolloRelation', mock_relation_class)
+        allow(mock_entry_class).to receive(:db).and_return(mock_db)
+      end
+
+      it 'queries with ORDER BY embedding distance' do
+        allow(mock_db).to receive(:fetch).and_return(double(all: []))
+        knowledge.send(:detect_contradictions, 'uuid-1', embedding, 'test')
+        expect(mock_db).to have_received(:fetch).with(
+          a_string_including('ORDER BY embedding <=> $embedding'),
+          hash_including(:entry_id, :embedding)
+        )
+      end
+
+      it 'returns empty when no similar entries found' do
+        allow(mock_db).to receive(:fetch).and_return(double(all: []))
+        result = knowledge.send(:detect_contradictions, 'uuid-1', embedding, 'test')
+        expect(result).to eq([])
+      end
+    end
   end
 end

data/spec/legion/extensions/apollo/runners/knowledge_spec.rb

@@ -110,6 +110,8 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
       let(:mock_entry) { double('entry', id: 'uuid-123', embedding: nil) }
       let(:empty_dataset) { double('dataset', each: nil) }
 
+      let(:mock_db) { double('db') }
+
       before do
         stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
         stub_const('Legion::Data::Model::ApolloRelation', mock_relation_class)
@@ -119,8 +121,8 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
           .and_return(Array.new(1536, 0.0))
 
         allow(mock_entry_class).to receive(:where).and_return(double(exclude: double(limit: empty_dataset)))
-        allow(mock_entry_class).to receive(:exclude)
-          .and_return(double(exclude: double(limit: double(all: []))))
+        allow(mock_entry_class).to receive(:db).and_return(mock_db)
+        allow(mock_db).to receive(:fetch).and_return(double(all: []))
         allow(mock_entry_class).to receive(:create).and_return(mock_entry)
         allow(mock_expertise_class).to receive(:where).and_return(double(first: nil))
         allow(mock_expertise_class).to receive(:create)
@@ -346,6 +348,83 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
     end
   end
 
+  describe '#handle_traverse' do
+    let(:host) { Object.new.extend(described_class) }
+
+    context 'when Apollo data is not available' do
+      before { hide_const('Legion::Data::Model::ApolloEntry') if defined?(Legion::Data::Model::ApolloEntry) }
+
+      it 'returns a structured error' do
+        result = host.handle_traverse(entry_id: 'uuid-123')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq('apollo_data_not_available')
+      end
+    end
+
+    context 'when Apollo data is available' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+      let(:mock_access_log_class) { double('ApolloAccessLog') }
+      let(:mock_db) { double('db') }
+      let(:traversal_results) do
+        [{ id: 'uuid-1', content: 'root', content_type: 'fact',
+           confidence: 0.8, tags: ['ruby'], source_agent: 'agent-1',
+           depth: 0, activation: 1.0 },
+         { id: 'uuid-2', content: 'related', content_type: 'concept',
+           confidence: 0.6, tags: ['ruby'], source_agent: 'agent-2',
+           depth: 1, activation: 0.48 }]
+      end
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        stub_const('Legion::Data::Model::ApolloAccessLog', mock_access_log_class)
+        allow(mock_entry_class).to receive(:db).and_return(mock_db)
+        allow(mock_db).to receive(:fetch).and_return(double(all: traversal_results))
+        allow(mock_access_log_class).to receive(:create)
+      end
+
+      it 'executes traversal SQL and returns formatted entries' do
+        result = host.handle_traverse(entry_id: 'uuid-1', agent_id: 'agent-x')
+        expect(result[:success]).to be true
+        expect(result[:count]).to eq(2)
+        expect(result[:entries].first[:depth]).to eq(0)
+        expect(result[:entries].last[:activation]).to eq(0.48)
+      end
+
+      it 'logs access for known agents' do
+        expect(mock_access_log_class).to receive(:create).with(
+          hash_including(agent_id: 'agent-x', action: 'query')
+        )
+        host.handle_traverse(entry_id: 'uuid-1', agent_id: 'agent-x')
+      end
+
+      it 'skips access logging for unknown agents' do
+        expect(mock_access_log_class).not_to receive(:create)
+        host.handle_traverse(entry_id: 'uuid-1')
+      end
+
+      it 'filters invalid relation_types' do
+        expect(Legion::Extensions::Apollo::Helpers::GraphQuery).to receive(:build_traversal_sql).with(
+          hash_including(relation_types: ['causes'])
+        ).and_call_original
+        host.handle_traverse(entry_id: 'uuid-1', relation_types: %w[causes invalid_type])
+      end
+    end
+
+    context 'when Sequel raises an error' do
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', Class.new)
+        allow(Legion::Data::Model::ApolloEntry).to receive(:db)
+          .and_raise(Sequel::Error, 'connection lost')
+      end
+
+      it 'returns a structured error' do
+        result = host.handle_traverse(entry_id: 'uuid-1')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq('connection lost')
+      end
+    end
+  end
+
   describe '#redistribute_knowledge' do
     let(:host) { Object.new.extend(described_class) }
 

data/spec/legion/extensions/apollo/runners/request_spec.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/helpers/confidence'
+require 'legion/extensions/apollo/helpers/similarity'
+require 'legion/extensions/apollo/helpers/embedding'
+require 'legion/extensions/apollo/helpers/graph_query'
+require 'legion/extensions/apollo/runners/knowledge'
+require 'legion/extensions/apollo/runners/request'
+
+RSpec.describe Legion::Extensions::Apollo::Runners::Request do
+  before do
+    # Clear cached knowledge_host between examples
+    described_class.instance_variable_set(:@knowledge_host, nil)
+  end
+
+  describe '.data_required?' do
+    it 'returns false' do
+      expect(described_class.data_required?).to be false
+    end
+  end
+
+  describe '.query' do
+    context 'when local service is available' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+      let(:mock_access_log_class) { double('ApolloAccessLog') }
+      let(:mock_db) { double('db') }
+      let(:sample_entries) do
+        [{ id: 'uuid-1', content: 'test', content_type: 'fact',
+           confidence: 0.8, distance: 0.15, tags: ['ruby'], source_agent: 'agent-1' }]
+      end
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        stub_const('Legion::Data::Model::ApolloAccessLog', mock_access_log_class)
+        allow(Legion::Extensions::Apollo::Helpers::Embedding).to receive(:generate)
+          .and_return(Array.new(1536, 0.0))
+        allow(mock_entry_class).to receive(:db).and_return(mock_db)
+        allow(mock_db).to receive(:fetch).and_return(double(all: sample_entries))
+        allow(mock_entry_class).to receive(:where).and_return(double(update: true))
+        allow(mock_access_log_class).to receive(:create)
+      end
+
+      it 'delegates to Knowledge.handle_query' do
+        result = described_class.query(text: 'test query')
+        expect(result[:success]).to be true
+        expect(result[:entries]).to be_an(Array)
+      end
+    end
+
+    context 'when only transport is available' do
+      let(:mock_transport) do
+        Module.new do
+          def self.connected?
+            true
+          end
+
+          def self.respond_to?(method, *args)
+            method == :connected? || super
+          end
+        end
+      end
+      let(:mock_message) { double('message', publish: true) }
+
+      before do
+        hide_const('Legion::Data::Model::ApolloEntry') if defined?(Legion::Data::Model::ApolloEntry)
+        stub_const('Legion::Transport', mock_transport)
+        stub_const('Legion::Extensions::Apollo::Transport::Messages::Query',
+                   double('QueryMsg', new: mock_message))
+      end
+
+      it 'publishes via transport' do
+        result = described_class.query(text: 'test query')
+        expect(result[:success]).to be true
+        expect(result[:dispatched]).to eq(:transport)
+      end
+    end
+
+    context 'when neither local nor transport is available' do
+      before do
+        hide_const('Legion::Data::Model::ApolloEntry') if defined?(Legion::Data::Model::ApolloEntry)
+        hide_const('Legion::Transport') if defined?(Legion::Transport)
+      end
+
+      it 'returns no_path_available error' do
+        result = described_class.query(text: 'test query')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq(:no_path_available)
+      end
+    end
+  end
+
+  describe '.retrieve' do
+    context 'when local service is available' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+      let(:mock_db) { double('db') }
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        allow(Legion::Extensions::Apollo::Helpers::Embedding).to receive(:generate)
+          .and_return(Array.new(1536, 0.0))
+        allow(mock_entry_class).to receive(:db).and_return(mock_db)
+        allow(mock_db).to receive(:fetch).and_return(double(all: []))
+        allow(mock_entry_class).to receive(:where).and_return(double(update: true))
+      end
+
+      it 'delegates to Knowledge.retrieve_relevant' do
+        result = described_class.retrieve(text: 'test query')
+        expect(result[:success]).to be true
+        expect(result[:entries]).to eq([])
+      end
+    end
+
+    context 'when neither path is available' do
+      before do
+        hide_const('Legion::Data::Model::ApolloEntry') if defined?(Legion::Data::Model::ApolloEntry)
+        hide_const('Legion::Transport') if defined?(Legion::Transport)
+      end
+
+      it 'returns no_path_available' do
+        result = described_class.retrieve(text: 'test')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq(:no_path_available)
+      end
+    end
+  end
+
+  describe '.ingest' do
+    context 'when local service is available' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+      let(:mock_expertise_class) { double('ApolloExpertise') }
+      let(:mock_access_log_class) { double('ApolloAccessLog') }
+      let(:mock_entry) { double('entry', id: 'uuid-123', embedding: nil) }
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        stub_const('Legion::Data::Model::ApolloExpertise', mock_expertise_class)
+        stub_const('Legion::Data::Model::ApolloAccessLog', mock_access_log_class)
+        allow(Legion::Extensions::Apollo::Helpers::Embedding).to receive(:generate)
+          .and_return(Array.new(1536, 0.0))
+        allow(mock_entry_class).to receive(:where).and_return(double(exclude: double(limit: double(each: nil))))
+        allow(mock_entry_class).to receive(:exclude)
+          .and_return(double(exclude: double(limit: double(all: []))))
+        allow(mock_entry_class).to receive(:db).and_return(double(fetch: double(all: [])))
+        allow(mock_entry_class).to receive(:create).and_return(mock_entry)
+        allow(mock_expertise_class).to receive(:where).and_return(double(first: nil))
+        allow(mock_expertise_class).to receive(:create)
+        allow(mock_access_log_class).to receive(:create)
+      end
+
+      it 'delegates to Knowledge.handle_ingest' do
+        result = described_class.ingest(content: 'test fact', content_type: 'fact', source_agent: 'agent-1')
+        expect(result[:success]).to be true
+        expect(result[:entry_id]).to eq('uuid-123')
+      end
+    end
+
+    context 'when neither path is available' do
+      before do
+        hide_const('Legion::Data::Model::ApolloEntry') if defined?(Legion::Data::Model::ApolloEntry)
+        hide_const('Legion::Transport') if defined?(Legion::Transport)
+      end
+
+      it 'returns no_path_available' do
+        result = described_class.ingest(content: 'test', content_type: 'fact')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq(:no_path_available)
+      end
+    end
+  end
+
+  describe '.traverse' do
+    context 'when neither path is available' do
+      before do
+        hide_const('Legion::Data::Model::ApolloEntry') if defined?(Legion::Data::Model::ApolloEntry)
+        hide_const('Legion::Transport') if defined?(Legion::Transport)
+      end
+
+      it 'returns no_path_available' do
+        result = described_class.traverse(entry_id: 'uuid-1')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq(:no_path_available)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-apollo
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - Esity
@@ -153,6 +153,7 @@ files:
 - lib/legion/extensions/apollo/actors/gas_subscriber.rb
 - lib/legion/extensions/apollo/actors/ingest.rb
 - lib/legion/extensions/apollo/actors/query_responder.rb
+- lib/legion/extensions/apollo/api.rb
 - lib/legion/extensions/apollo/client.rb
 - lib/legion/extensions/apollo/gaia_integration.rb
 - lib/legion/extensions/apollo/helpers/confidence.rb
@@ -165,6 +166,7 @@ files:
 - lib/legion/extensions/apollo/runners/gas.rb
 - lib/legion/extensions/apollo/runners/knowledge.rb
 - lib/legion/extensions/apollo/runners/maintenance.rb
+- lib/legion/extensions/apollo/runners/request.rb
 - lib/legion/extensions/apollo/transport.rb
 - lib/legion/extensions/apollo/transport/exchanges/apollo.rb
 - lib/legion/extensions/apollo/transport/exchanges/llm_audit.rb
@@ -179,6 +181,7 @@ files:
 - spec/legion/extensions/apollo/actors/expertise_aggregator_spec.rb
 - spec/legion/extensions/apollo/actors/gas_subscriber_spec.rb
 - spec/legion/extensions/apollo/actors/ingest_spec.rb
+- spec/legion/extensions/apollo/api_spec.rb
 - spec/legion/extensions/apollo/client_spec.rb
 - spec/legion/extensions/apollo/contradiction_spec.rb
 - spec/legion/extensions/apollo/gaia_integration_spec.rb
@@ -196,6 +199,7 @@ files:
 - spec/legion/extensions/apollo/runners/gas_synthesize_spec.rb
 - spec/legion/extensions/apollo/runners/knowledge_spec.rb
 - spec/legion/extensions/apollo/runners/maintenance_spec.rb
+- spec/legion/extensions/apollo/runners/request_spec.rb
 - spec/legion/extensions/apollo/transport/messages/ingest_spec.rb
 - spec/legion/extensions/apollo/transport/messages/query_spec.rb
 - spec/spec_helper.rb