lex-apollo 0.4.4 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c5141f161198efe7dbdd37179e46bf36ec1c58404efa645897bc256975d3f8
-  data.tar.gz: c2ac6728af5ada2ab45eb8fff0a0e80d6bceac5464305bca18bd836c81fc0ffb
+  metadata.gz: 9a1c9042626e5d9e09a783b8c703b11f261573fe1658498a4fa48ad023306baf
+  data.tar.gz: 2f3e561b6851825d9d5c67325007802eafea63c10c93a00e37a40170202a0bdc
 SHA512:
-  metadata.gz: 45328d181484cabb6a17aceb9d6d1a816a623fbe1dc8f5c80972b9151a2250f244d88ba88551cf0cecac70229732546a35abe32189a2ff75a4026010279a810e
-  data.tar.gz: 1eab2286abce601fe8a95b75c0da2edb0017bebb39e09abe05a1c7dbf72658e7955147b2ab1e1b6ed743788ed61a86c4871919e7ab53762ef3e2e40906eea00f
+  metadata.gz: d2dae8784e591deeb1608671dbabbd313813a6f94214b77de0539d2316d6ef3a34e21d5002eb28a262e98c4c4d57773793be4ba006d185e0fd3afcf6816902c5
+  data.tar.gz: 41e11ae62a001fab8e79b514d30c3c28374d38d1d4379926e00752df74e35ccfa79c61b3ac75e7e60341de0420287635413b265eca5fa0cd7fe4e7f02a5fad0f

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [0.4.6] - 2026-03-25
+
+### Added
+- Apollo-specific embedding provider/model settings: `apollo.embedding.provider` and `apollo.embedding.model` override LLM defaults
+- `embedding_opts` helper reads Apollo settings and passes `provider:`/`model:` to `Legion::LLM.embed`
+- Local-first embedding: `detect_local_model` checks Ollama for pulled 1024-dim models (`mxbai-embed-large`, `bge-large`, `snowflake-arctic-embed`) before falling back to cloud provider
+
+### Changed
+- `DEFAULT_DIMENSION` changed from 1536 to 1024 for cross-provider compatibility (Bedrock Titan v2, OpenAI with dimensions:, Ollama models)
+- `Helpers::Embedding.generate` now passes provider/model from Apollo settings, falling back to LLM defaults when not configured
+
+## [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/helpers/embedding.rb

@@ -5,7 +5,9 @@ module Legion
     module Apollo
       module Helpers
         module Embedding
-          DEFAULT_DIMENSION = 1536
+          DEFAULT_DIMENSION = 1024
+
+          LOCAL_EMBEDDING_MODELS = %w[mxbai-embed-large bge-large snowflake-arctic-embed].freeze
 
           module_function
 
@@ -15,8 +17,15 @@ module Legion
               return zero_vector
             end
 
-            result = Legion::LLM.embed(text)
-            vector = result.is_a?(Hash) ? result[:vector] : result
+            local_model = detect_local_model
+            vector = if local_model
+                       ollama_embed(text, local_model)
+                     else
+                       opts = cloud_embedding_opts
+                       result = Legion::LLM.embed(text, **opts)
+                       result.is_a?(Hash) ? result[:vector] : result
+                     end
+
             if vector.is_a?(Array) && vector.any?
               @dimension = vector.size
               vector
@@ -38,6 +47,53 @@ module Legion
             DEFAULT_DIMENSION
           end
 
+          def ollama_embed(text, model)
+            require 'faraday'
+            base_url = ollama_base_url
+            Legion::Logging.debug("[apollo] embedding via local Ollama: #{model}") if defined?(Legion::Logging)
+            conn = Faraday.new(url: base_url) { |f| f.options.timeout = 10 }
+            response = conn.post('/api/embed', { model: model, input: text }.to_json,
+                                 'Content-Type' => 'application/json')
+            return nil unless response.success?
+
+            parsed = ::JSON.parse(response.body)
+            parsed['embeddings']&.first
+          rescue StandardError => e
+            Legion::Logging.warn("[apollo] local Ollama embed failed: #{e.message}") if defined?(Legion::Logging)
+            nil
+          end
+
+          def ollama_base_url
+            return 'http://localhost:11434' unless defined?(Legion::Settings)
+
+            Legion::Settings[:llm].dig(:providers, :ollama, :base_url) || 'http://localhost:11434'
+          rescue StandardError
+            'http://localhost:11434'
+          end
+
+          def cloud_embedding_opts
+            return {} unless defined?(Legion::Settings) && !Legion::Settings[:apollo].nil?
+
+            embedding = Legion::Settings[:apollo][:embedding] || {}
+            opts = {}
+            opts[:provider] = embedding[:provider].to_sym if embedding[:provider]
+            opts[:model]    = embedding[:model] if embedding[:model]
+            opts
+          rescue StandardError
+            {}
+          end
+
+          def detect_local_model
+            return nil unless defined?(Legion::LLM::Discovery::Ollama)
+
+            LOCAL_EMBEDDING_MODELS.find do |m|
+              Legion::LLM::Discovery::Ollama.model_available?(m) ||
+                Legion::LLM::Discovery::Ollama.model_available?("#{m}:latest")
+            end
+          rescue StandardError
+            nil
+          end
+
           def zero_vector
             Array.new(dimension, 0.0)
           end

data/lib/legion/extensions/apollo/helpers/graph_query.rb

@@ -32,7 +32,7 @@ module Legion
                 SELECT e.id, e.content, e.content_type, e.confidence, e.tags, e.source_agent,
                        0 AS depth, 1.0::float AS activation
                 FROM apollo_entries e
-                WHERE e.id = $entry_id
+                WHERE e.id = :entry_id
 
                 UNION ALL
 
@@ -72,11 +72,11 @@ module Legion
             <<~SQL
               SELECT e.id, e.content, e.content_type, e.confidence, e.tags, e.source_agent,
                      e.access_count, e.created_at, e.knowledge_domain,
-                     (e.embedding <=> $embedding) AS distance
+                     (e.embedding <=> :embedding) AS distance
               FROM apollo_entries e
               WHERE #{where_clause}
                 AND e.embedding IS NOT NULL
-              ORDER BY e.embedding <=> $embedding
+              ORDER BY e.embedding <=> :embedding
               LIMIT #{limit}
             SQL
           end

data/lib/legion/extensions/apollo/helpers/similarity.rb

@@ -10,6 +10,10 @@ module Legion
           module_function
 
           def cosine_similarity(vec_a:, vec_b:, **)
+            vec_a = parse_vector(vec_a)
+            vec_b = parse_vector(vec_b)
+            return 0.0 unless vec_a.is_a?(Array) && vec_b.is_a?(Array)
+
             dot = vec_a.zip(vec_b).sum { |x, y| x * y }
             mag_a = Math.sqrt(vec_a.sum { |x| x**2 })
             mag_b = Math.sqrt(vec_b.sum { |x| x**2 })
@@ -18,6 +22,15 @@ module Legion
             dot / (mag_a * mag_b)
           end
 
+          def parse_vector(vec)
+            return vec if vec.is_a?(Array)
+            return nil unless vec.is_a?(String)
+
+            ::JSON.parse(vec)
+          rescue StandardError
+            nil
+          end
+
           def above_corroboration_threshold?(similarity:, **)
             similarity >= Confidence::CORROBORATION_SIMILARITY_THRESHOLD
           end

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

@@ -112,6 +112,8 @@ module Legion
             db = Legion::Data::Model::ApolloEntry.db
             entries = db.fetch(sql, embedding: Sequel.lit("'[#{embedding.join(',')}]'::vector")).all
 
+            entries = entries.reject { |e| e[:distance].respond_to?(:nan?) && e[:distance].nan? }
+
             entries.each do |entry|
               Legion::Data::Model::ApolloEntry.where(id: entry[:id]).update(
                 access_count: Sequel.expr(:access_count) + 1,
@@ -130,7 +132,7 @@ module Legion
 
             formatted = entries.map do |entry|
               { id: entry[:id], content: entry[:content], content_type: entry[:content_type],
-                confidence: entry[:confidence], distance: entry[:distance],
+                confidence: entry[:confidence], distance: entry[:distance]&.to_f,
                 tags: entry[:tags], source_agent: entry[:source_agent],
                 knowledge_domain: entry[:knowledge_domain] }
             end
@@ -140,6 +142,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)
 
@@ -188,6 +220,7 @@ module Legion
 
             db = Legion::Data::Model::ApolloEntry.db
             entries = db.fetch(sql, embedding: Sequel.lit("'[#{embedding.join(',')}]'::vector")).all
+            entries = entries.reject { |e| e[:distance].respond_to?(:nan?) && e[:distance].nan? }
 
             entries.each do |entry|
               Legion::Data::Model::ApolloEntry.where(id: entry[:id]).update(
@@ -198,7 +231,7 @@ module Legion
 
             formatted = entries.map do |entry|
               { id: entry[:id], content: entry[:content], content_type: entry[:content_type],
-                confidence: entry[:confidence], distance: entry[:distance],
+                confidence: entry[:confidence], distance: entry[:distance]&.to_f,
                 tags: entry[:tags], source_agent: entry[:source_agent],
                 knowledge_domain: entry[:knowledge_domain] }
             end
@@ -281,25 +314,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.6'
     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/helpers/embedding_spec.rb

@@ -12,8 +12,8 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::Embedding do
 
       it 'returns a zero vector of the correct dimension' do
         result = described_class.generate(text: 'hello world')
-        expect(result).to eq(Array.new(1536, 0.0))
-        expect(result.size).to eq(1536)
+        expect(result).to eq(Array.new(1024, 0.0))
+        expect(result.size).to eq(1024)
       end
     end
 
@@ -24,12 +24,12 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::Embedding do
 
       it 'returns a zero vector' do
         result = described_class.generate(text: 'hello world')
-        expect(result).to eq(Array.new(1536, 0.0))
+        expect(result).to eq(Array.new(1024, 0.0))
       end
     end
 
     context 'when Legion::LLM is available and started' do
-      let(:mock_vector) { Array.new(1536) { rand(-1.0..1.0) } }
+      let(:mock_vector) { Array.new(1024) { rand(-1.0..1.0) } }
 
       before do
         llm = Module.new do
@@ -44,7 +44,7 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::Embedding do
       it 'returns the vector from the LLM response hash' do
         result = described_class.generate(text: 'hello world')
         expect(result).to eq(mock_vector)
-        expect(Legion::LLM).to have_received(:embed).with('hello world')
+        expect(Legion::LLM).to have_received(:embed).with('hello world', **{})
       end
     end
 
@@ -120,7 +120,7 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::Embedding do
       end
 
       it 'returns the default dimension' do
-        expect(described_class.configured_dimension).to eq(1536)
+        expect(described_class.configured_dimension).to eq(1024)
       end
     end
   end

data/spec/legion/extensions/apollo/helpers/graph_query_spec.rb

@@ -24,7 +24,7 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::GraphQuery do
       expect(sql).to include('apollo_entries')
       expect(sql).to include('apollo_relations')
       expect(sql).to include('WITH RECURSIVE')
-      expect(sql).to include('$entry_id')
+      expect(sql).to include(':entry_id')
     end
 
     it 'includes relation type filter when specified' do
@@ -49,7 +49,7 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::GraphQuery do
     it 'returns SQL with vector placeholder' do
       sql = described_class.build_semantic_search_sql(limit: 5, min_confidence: 0.3)
       expect(sql).to include('apollo_entries')
-      expect(sql).to include('$embedding')
+      expect(sql).to include(':embedding')
       expect(sql).to include('<=>')
       expect(sql).to include('LIMIT 5')
     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.6
 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