lex-apollo 0.3.9 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4b61ece5949747c3f9c63d527451975f1bae1193529322a2dfee5c99fe449f7
-  data.tar.gz: 2a8ee392eda6931f18e0c8740ef3c7a57737fee787f85755fe4531bac44b1e11
+  metadata.gz: 8e6e95c43807f0f9a3eaaaaa0a0d4cadafdbf279acb4829fe0c0ef6ce909e6bc
+  data.tar.gz: c336ca5086ffc85995bf6a8759799d48d65edf905f12458de4aa63c24608d0fe
 SHA512:
-  metadata.gz: beda1e6d911c593184fa43fb457881b7cc2c8c7052761c3172861afa0b6dd39f449ff51484a8a05fba9479957aff0509f27fb4d462c4e15bb979e30ca8a68d68
-  data.tar.gz: d21a75d1bfc573144fab0f83cbf37c691a0fb1d5e9ac403ab6aa735ec04b2842d1cd9aeb431f10cd56f5f61f671b67a010257221aadf1e5844dd2435641ea43f
+  metadata.gz: 84bfc36365061507970f0fb99c084a2729702041b416211791c90309e1f9e3ce54f1ba2fb9986ebf4e5412d327822ce82f51f83274df6cff758e4564d4786f84
+  data.tar.gz: ede777694a9e166d0ce8b8862f444eb02c231204a89c265f850503ca78a8001b89bf3430995a1fb2ca324040467831dee73a5563caa81105a67956721507b505

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.4.0] - 2026-03-23
+
+### Added
+- `Runners::Gas`: 6-phase GAS (Generation-Augmented Storage) pipeline
+  - Phase 1 (Comprehend): LLM-based fact extraction via GaiaCaller, mechanical fallback
+  - Phase 2 (Extract): delegates to existing `EntityExtractor` runner
+  - Phase 3 (Relate): queries Apollo for similar entries, classifies 8 relationship types via LLM, confidence > 0.7 gate
+  - Phase 4 (Synthesize): generates derivative knowledge with geometric mean confidence, capped at 0.7
+  - Phase 5 (Deposit): atomic write of facts to Apollo via `Knowledge.handle_ingest`
+  - Phase 6 (Anticipate): generates follow-up questions, promotes to TBI PatternStore when available
+- `Actor::GasSubscriber`: subscription actor binding to `llm.audit.complete` routing key
+- `Transport::Queues::Gas`: durable queue for GAS audit event processing
+
 ## [0.3.9] - 2026-03-23
 
 ### Fixed

data/lib/legion/extensions/apollo/actors/gas_subscriber.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/subscription' if defined?(Legion::Extensions::Actors::Subscription)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Actor
+        class GasSubscriber < Legion::Extensions::Actors::Subscription
+          def runner_class    = 'Legion::Extensions::Apollo::Runners::Gas'
+          def runner_function = 'process'
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def enabled?
+            defined?(Legion::Extensions::Apollo::Runners::Gas) &&
+              defined?(Legion::Transport)
+          rescue StandardError
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,375 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Apollo
+      module Runners
+        module Gas
+          module_function
+
+          def process(audit_event)
+            return { phases_completed: 0, reason: 'no content' } unless processable?(audit_event)
+
+            facts = phase_comprehend(audit_event)
+            entities = phase_extract(audit_event, facts)
+            relations = phase_relate(facts, entities)
+            synthesis = phase_synthesize(facts, relations)
+            deposit_result = phase_deposit(facts, entities, relations, synthesis, audit_event)
+            anticipations = phase_anticipate(facts, synthesis)
+
+            {
+              phases_completed: 6,
+              facts:            facts.length,
+              entities:         entities.length,
+              relations:        relations.length,
+              synthesis:        synthesis.length,
+              deposited:        deposit_result,
+              anticipations:    anticipations.length
+            }
+          rescue StandardError => e
+            Legion::Logging.warn("GAS pipeline error: #{e.message}") if defined?(Legion::Logging)
+            { phases_completed: 0, error: e.message }
+          end
+
+          def processable?(event)
+            event[:messages]&.any? == true && !event[:response_content].nil?
+          end
+
+          # Phase 1: Comprehend - extract typed facts from the exchange
+          def phase_comprehend(audit_event)
+            messages = audit_event[:messages]
+            response = audit_event[:response_content]
+
+            if llm_available?
+              llm_comprehend(messages, response)
+            else
+              mechanical_comprehend(messages, response)
+            end
+          end
+
+          # Phase 2: Extract - entity extraction (delegates to existing EntityExtractor)
+          def phase_extract(audit_event, _facts)
+            return [] unless defined?(Runners::EntityExtractor)
+
+            result = Runners::EntityExtractor.extract_entities(text: audit_event[:response_content])
+            result[:success] ? (result[:entities] || []) : []
+          rescue StandardError
+            []
+          end
+
+          RELATION_TYPES = %w[
+            similar_to contradicts depends_on causes
+            part_of supersedes supports_by extends
+          ].freeze
+
+          RELATE_CONFIDENCE_GATE = 0.7
+
+          # Phase 3: Relate - classify relationships between new and existing entries
+          def phase_relate(facts, _entities)
+            return [] unless defined?(Runners::Knowledge)
+
+            existing = fetch_similar_entries(facts)
+            return [] if existing.empty?
+
+            relations = []
+            facts.each do |fact|
+              existing.each do |entry|
+                relation = classify_relation(fact, entry)
+                relations << relation if relation
+              end
+            end
+            relations
+          end
+
+          SYNTHESIS_CONFIDENCE_CAP = 0.7
+
+          # Phase 4: Synthesize - generate derivative knowledge
+          def phase_synthesize(facts, _relations)
+            return [] if facts.length < 2
+            return [] unless llm_available?
+
+            llm_synthesize(facts)
+          rescue StandardError
+            []
+          end
+
+          # Phase 5: Deposit - atomic write to Apollo
+          def phase_deposit(facts, _entities, _relations, _synthesis, audit_event)
+            return { deposited: 0 } unless defined?(Runners::Knowledge)
+
+            deposited = 0
+            facts.each do |fact|
+              Runners::Knowledge.handle_ingest(
+                content:          fact[:content],
+                content_type:     fact[:content_type].to_s,
+                tags:             %w[gas auto_extracted],
+                source_agent:     'gas_pipeline',
+                source_provider:  audit_event.dig(:routing, :provider)&.to_s,
+                knowledge_domain: 'general',
+                context:          { source_request_id: audit_event[:request_id] }
+              )
+              deposited += 1
+            rescue StandardError => e
+              Legion::Logging.warn("GAS deposit error: #{e.message}") if defined?(Legion::Logging)
+            end
+            { deposited: deposited }
+          end
+
+          MAX_ANTICIPATIONS = 3
+
+          # Phase 6: Anticipate - pre-cache likely follow-up questions
+          def phase_anticipate(facts, _synthesis)
+            return [] if facts.empty?
+            return [] unless llm_available?
+
+            llm_anticipate(facts)
+          rescue StandardError
+            []
+          end
+
+          def fetch_similar_entries(facts)
+            entries = []
+            facts.each do |fact|
+              result = Runners::Knowledge.retrieve_relevant(query: fact[:content], limit: 3, min_confidence: 0.3)
+              entries.concat(result[:entries]) if result[:success] && result[:entries]&.any?
+            rescue StandardError
+              next
+            end
+            entries.uniq { |e| e[:id] }
+          end
+
+          def classify_relation(fact, entry)
+            if llm_available?
+              llm_classify_relation(fact, entry)
+            else
+              { from_content: fact[:content], to_id: entry[:id], relation_type: 'similar_to', confidence: 0.5 }
+            end
+          rescue StandardError
+            { from_content: fact[:content], to_id: entry[:id], relation_type: 'similar_to', confidence: 0.5 }
+          end
+
+          def llm_classify_relation(fact, entry)
+            prompt = <<~PROMPT
+              Classify the relationship between these two knowledge entries.
+              Valid types: #{RELATION_TYPES.join(', ')}
+
+              Entry A (new): #{fact[:content]}
+              Entry B (existing): #{entry[:content]}
+
+              Return JSON with relation_type and confidence (0.0-1.0).
+            PROMPT
+
+            result = Legion::LLM::Pipeline::GaiaCaller.structured(
+              message: prompt.strip,
+              schema:  {
+                type:       :object,
+                properties: {
+                  relations: {
+                    type:  :array,
+                    items: {
+                      type:       :object,
+                      properties: {
+                        relation_type: { type: :string },
+                        confidence:    { type: :number }
+                      },
+                      required:   %w[relation_type confidence]
+                    }
+                  }
+                },
+                required:   ['relations']
+              },
+              phase:   'gas_relate'
+            )
+
+            content = result.respond_to?(:message) ? result.message[:content] : result.to_s
+            parsed = Legion::JSON.load(content)
+            rels = parsed.is_a?(Hash) ? (parsed[:relations] || parsed['relations'] || []) : []
+            best = rels.max_by { |r| r[:confidence] || r['confidence'] || 0 }
+
+            return fallback_relation(fact, entry) unless best
+
+            conf = best[:confidence] || best['confidence'] || 0
+            rtype = best[:relation_type] || best['relation_type']
+            return fallback_relation(fact, entry) if conf < RELATE_CONFIDENCE_GATE || !RELATION_TYPES.include?(rtype)
+
+            { from_content: fact[:content], to_id: entry[:id], relation_type: rtype, confidence: conf }
+          rescue StandardError
+            fallback_relation(fact, entry)
+          end
+
+          def fallback_relation(fact, entry)
+            { from_content: fact[:content], to_id: entry[:id], relation_type: 'similar_to', confidence: 0.5 }
+          end
+
+          def llm_synthesize(facts)
+            facts_text = facts.each_with_index.map { |f, i| "[#{i}] (#{f[:content_type]}) #{f[:content]}" }.join("\n")
+
+            prompt = <<~PROMPT
+              Given these knowledge entries, generate derivative insights (inferences, implications, or connections).
+              Each synthesis should combine information from multiple sources.
+
+              Entries:
+              #{facts_text}
+
+              Return JSON with a "synthesis" array where each item has: content (string), content_type (inference/implication/connection), source_indices (array of entry indices used).
+            PROMPT
+
+            result = Legion::LLM::Pipeline::GaiaCaller.structured(
+              message: prompt.strip,
+              schema:  {
+                type:       :object,
+                properties: {
+                  synthesis: {
+                    type:  :array,
+                    items: {
+                      type:       :object,
+                      properties: {
+                        content:        { type: :string },
+                        content_type:   { type: :string },
+                        source_indices: { type: :array, items: { type: :integer } }
+                      },
+                      required:   %w[content content_type source_indices]
+                    }
+                  }
+                },
+                required:   ['synthesis']
+              },
+              phase:   'gas_synthesize'
+            )
+
+            content = result.respond_to?(:message) ? result.message[:content] : result.to_s
+            parsed = Legion::JSON.load(content)
+            items = parsed.is_a?(Hash) ? (parsed[:synthesis] || parsed['synthesis'] || []) : []
+
+            items.map { |item| build_synthesis_entry(item, facts) }
+          rescue StandardError
+            []
+          end
+
+          def build_synthesis_entry(item, facts)
+            source_indices = item[:source_indices] || item['source_indices'] || []
+            source_confs = source_indices.filter_map { |i| facts[i]&.dig(:confidence) }
+            geo_mean = source_confs.empty? ? 0.5 : geometric_mean(source_confs)
+
+            {
+              content:        item[:content] || item['content'],
+              content_type:   (item[:content_type] || item['content_type'] || 'inference').to_sym,
+              status:         :candidate,
+              confidence:     [geo_mean, SYNTHESIS_CONFIDENCE_CAP].min,
+              source_indices: source_indices
+            }
+          end
+
+          def geometric_mean(values)
+            return 0.0 if values.empty?
+
+            product = values.reduce(1.0) { |acc, v| acc * v }
+            product**(1.0 / values.length)
+          end
+
+          def llm_anticipate(facts)
+            facts_text = facts.map { |f| "(#{f[:content_type]}) #{f[:content]}" }.join("\n")
+
+            prompt = <<~PROMPT
+              Given these knowledge entries, generate 1-3 likely follow-up questions a user might ask.
+
+              Knowledge:
+              #{facts_text}
+
+              Return JSON with a "questions" array of question strings.
+            PROMPT
+
+            result = Legion::LLM::Pipeline::GaiaCaller.structured(
+              message: prompt.strip,
+              schema:  {
+                type:       :object,
+                properties: {
+                  questions: { type: :array, items: { type: :string } }
+                },
+                required:   ['questions']
+              },
+              phase:   'gas_anticipate'
+            )
+
+            content = result.respond_to?(:message) ? result.message[:content] : result.to_s
+            parsed = Legion::JSON.load(content)
+            questions = parsed.is_a?(Hash) ? (parsed[:questions] || parsed['questions'] || []) : []
+            questions = questions.first(MAX_ANTICIPATIONS)
+
+            questions.map do |q|
+              promote_to_pattern_store(question: q, facts: facts)
+              { question: q }
+            end
+          rescue StandardError
+            []
+          end
+
+          def promote_to_pattern_store(question:, facts:)
+            return unless defined?(Legion::Extensions::Agentic::TBI::PatternStore)
+
+            Legion::Extensions::Agentic::TBI::PatternStore.promote_candidate(
+              intent:     question,
+              resolution: { source: 'gas_anticipate', facts: facts.map { |f| f[:content] } },
+              confidence: 0.5
+            )
+          rescue StandardError
+            nil
+          end
+
+          def llm_available?
+            defined?(Legion::LLM::Pipeline::GaiaCaller)
+          rescue StandardError
+            false
+          end
+
+          def mechanical_comprehend(_messages, response)
+            [{ content: response, content_type: :observation }]
+          end
+
+          def llm_comprehend(messages, response)
+            prompt = <<~PROMPT
+              Extract distinct facts from this exchange. Return JSON array of {content:, content_type:} where content_type is one of: fact, concept, procedure, association.
+
+              User: #{messages.last&.dig(:content)}
+              Assistant: #{response}
+            PROMPT
+
+            result = Legion::LLM::Pipeline::GaiaCaller.structured(
+              message: prompt.strip,
+              schema:  {
+                type:       :object,
+                properties: {
+                  facts: {
+                    type:  :array,
+                    items: {
+                      type:       :object,
+                      properties: {
+                        content:      { type: :string },
+                        content_type: { type: :string }
+                      },
+                      required:   %w[content content_type]
+                    }
+                  }
+                },
+                required:   ['facts']
+              },
+              phase:   'gas_comprehend'
+            )
+
+            content = result.respond_to?(:message) ? result.message[:content] : result.to_s
+            parsed = Legion::JSON.load(content)
+            facts_array = parsed.is_a?(Hash) ? (parsed[:facts] || parsed['facts'] || []) : Array(parsed)
+            facts_array.map do |f|
+              {
+                content:      f[:content] || f['content'],
+                content_type: (f[:content_type] || f['content_type'] || 'fact').to_sym
+              }
+            end
+          rescue StandardError
+            mechanical_comprehend(messages, response)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/transport/queues/gas.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/transport/queue' if defined?(Legion::Transport)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Transport
+        module Queues
+          class Gas < Legion::Transport::Queue
+            def queue_name
+              'apollo.gas'
+            end
+
+            def queue_options
+              { manual_ack: true, durable: true, arguments: { 'x-dead-letter-exchange': 'apollo.dlx' } }
+            end
+          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.3.9'
+      VERSION = '0.4.0'
     end
   end
 end

data/lib/legion/extensions/apollo.rb

@@ -8,11 +8,13 @@ require 'legion/extensions/apollo/runners/knowledge'
 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'
 
 if defined?(Legion::Transport)
   require 'legion/extensions/apollo/transport/exchanges/apollo'
   require 'legion/extensions/apollo/transport/queues/ingest'
   require 'legion/extensions/apollo/transport/queues/query'
+  require 'legion/extensions/apollo/transport/queues/gas'
   require 'legion/extensions/apollo/transport/messages/ingest'
   require 'legion/extensions/apollo/transport/messages/query'
 end

data/spec/legion/extensions/apollo/actors/gas_subscriber_spec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Subscription)
+  module Legion
+    module Extensions
+      module Actors
+        class Subscription; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+$LOADED_FEATURES << 'legion/extensions/actors/subscription' unless $LOADED_FEATURES.include?('legion/extensions/actors/subscription')
+
+require 'legion/extensions/apollo/runners/gas'
+require 'legion/extensions/apollo/actors/gas_subscriber'
+
+RSpec.describe Legion::Extensions::Apollo::Actor::GasSubscriber do
+  subject(:actor) { described_class.new }
+
+  it 'uses Gas runner_class as string' do
+    expect(actor.runner_class).to eq('Legion::Extensions::Apollo::Runners::Gas')
+  end
+
+  it 'runs process function' do
+    expect(actor.runner_function).to eq('process')
+  end
+
+  it 'does not generate tasks' do
+    expect(actor.generate_task?).to be false
+  end
+
+  it 'does not check subtasks' do
+    expect(actor.check_subtask?).to be false
+  end
+
+  describe '#enabled?' do
+    it 'returns truthy when Gas runner and Transport are defined' do
+      stub_const('Legion::Transport', Module.new)
+      expect(actor.enabled?).to be_truthy
+    end
+
+    it 'returns falsey when Transport is not defined' do
+      hide_const('Legion::Transport') if defined?(Legion::Transport)
+      expect(actor.enabled?).to be_falsey
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/runners/gas'
+
+RSpec.describe Legion::Extensions::Apollo::Runners::Gas, '.phase_anticipate' do
+  let(:facts) do
+    [
+      { content: 'pgvector uses HNSW indexes', content_type: :fact },
+      { content: 'cosine distance measures similarity', content_type: :concept }
+    ]
+  end
+
+  let(:synthesis) do
+    [
+      { content: 'pgvector achieves fast search via HNSW', content_type: :inference, status: :candidate }
+    ]
+  end
+
+  context 'when GaiaCaller is unavailable' do
+    it 'returns empty array' do
+      result = described_class.phase_anticipate(facts, synthesis)
+      expect(result).to eq([])
+    end
+  end
+
+  context 'when GaiaCaller is available' do
+    let(:gaia_caller) { double('GaiaCaller') }
+    let(:mock_response) do
+      double(
+        'Response',
+        message: {
+          content: '{"questions":["How fast is pgvector HNSW search?","What distance metrics does pgvector support?"]}'
+        }
+      )
+    end
+
+    before do
+      stub_const('Legion::LLM::Pipeline::GaiaCaller', gaia_caller)
+      allow(gaia_caller).to receive(:structured).and_return(mock_response)
+      allow(Legion::JSON).to receive(:load).and_return(
+        { 'questions' => ['How fast is pgvector HNSW search?', 'What distance metrics does pgvector support?'] }
+      )
+    end
+
+    it 'generates anticipated questions' do
+      result = described_class.phase_anticipate(facts, synthesis)
+      expect(result).not_to be_empty
+      expect(result.length).to be <= 3
+    end
+
+    it 'returns question strings' do
+      result = described_class.phase_anticipate(facts, synthesis)
+      result.each do |item|
+        expect(item[:question]).to be_a(String)
+      end
+    end
+
+    context 'when PatternStore is available' do
+      let(:pattern_store) { double('PatternStore') }
+
+      before do
+        stub_const('Legion::Extensions::Agentic::TBI::PatternStore', pattern_store)
+        allow(pattern_store).to receive(:promote_candidate)
+      end
+
+      it 'promotes candidates to PatternStore' do
+        described_class.phase_anticipate(facts, synthesis)
+        expect(pattern_store).to have_received(:promote_candidate).at_least(:once)
+      end
+    end
+
+    context 'when PatternStore is not available' do
+      it 'still returns questions without error' do
+        result = described_class.phase_anticipate(facts, synthesis)
+        expect(result).not_to be_empty
+      end
+    end
+  end
+
+  context 'when LLM call fails' do
+    let(:gaia_caller) { double('GaiaCaller') }
+
+    before do
+      stub_const('Legion::LLM::Pipeline::GaiaCaller', gaia_caller)
+      allow(gaia_caller).to receive(:structured).and_raise(StandardError, 'timeout')
+    end
+
+    it 'returns empty array on error' do
+      result = described_class.phase_anticipate(facts, synthesis)
+      expect(result).to eq([])
+    end
+  end
+
+  context 'with empty facts' do
+    it 'returns empty array' do
+      result = described_class.phase_anticipate([], [])
+      expect(result).to eq([])
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/runners/gas'
+
+RSpec.describe Legion::Extensions::Apollo::Runners::Gas, '.phase_relate' do
+  let(:facts) do
+    [
+      { content: 'pgvector uses HNSW indexes', content_type: :fact },
+      { content: 'cosine distance measures similarity', content_type: :concept }
+    ]
+  end
+  let(:entities) do
+    [{ name: 'pgvector', type: 'technology' }]
+  end
+
+  context 'when Apollo Knowledge is unavailable' do
+    before do
+      hide_const('Legion::Extensions::Apollo::Runners::Knowledge') if defined?(Legion::Extensions::Apollo::Runners::Knowledge)
+    end
+
+    it 'returns empty array' do
+      result = described_class.phase_relate(facts, entities)
+      expect(result).to eq([])
+    end
+  end
+
+  context 'when Apollo has similar entries' do
+    let(:knowledge_runner) { double('Knowledge') }
+    let(:similar_entries) do
+      {
+        success: true,
+        entries: [
+          { id: 'e1', content: 'HNSW is an approximate nearest neighbor algorithm', content_type: 'concept', confidence: 0.85 }
+        ],
+        count:   1
+      }
+    end
+
+    before do
+      stub_const('Legion::Extensions::Apollo::Runners::Knowledge', knowledge_runner)
+      allow(knowledge_runner).to receive(:retrieve_relevant).and_return(similar_entries)
+    end
+
+    context 'when GaiaCaller is unavailable' do
+      it 'falls back to similar_to relations' do
+        result = described_class.phase_relate(facts, entities)
+        expect(result).to all(include(relation_type: 'similar_to'))
+      end
+
+      it 'returns relations for each fact-entry pair' do
+        result = described_class.phase_relate(facts, entities)
+        expect(result).not_to be_empty
+      end
+    end
+
+    context 'when GaiaCaller is available' do
+      let(:gaia_caller) { double('GaiaCaller') }
+      let(:mock_response) do
+        double(
+          'Response',
+          message: {
+            content: '{"relations":[{"relation_type":"depends_on","confidence":0.85}]}'
+          }
+        )
+      end
+
+      before do
+        stub_const('Legion::LLM::Pipeline::GaiaCaller', gaia_caller)
+        stub_const('Legion::JSON', double(load: { 'relations' => [{ 'relation_type' => 'depends_on', 'confidence' => 0.85 }] }))
+        allow(gaia_caller).to receive(:structured).and_return(mock_response)
+      end
+
+      it 'classifies relations via LLM' do
+        result = described_class.phase_relate(facts, entities)
+        expect(result).not_to be_empty
+        expect(result.first[:relation_type]).to eq('depends_on')
+      end
+
+      it 'gates on confidence > 0.7' do
+        low_conf_response = double(
+          'Response',
+          message: {
+            content: '{"relations":[{"relation_type":"contradicts","confidence":0.3}]}'
+          }
+        )
+        allow(gaia_caller).to receive(:structured).and_return(low_conf_response)
+        allow(Legion::JSON).to receive(:load).and_return(
+          { 'relations' => [{ 'relation_type' => 'contradicts', 'confidence' => 0.3 }] }
+        )
+
+        result = described_class.phase_relate(facts, entities)
+        # Low confidence relations should fall back to similar_to
+        classified = result.select { |r| r[:relation_type] == 'contradicts' }
+        expect(classified).to be_empty
+      end
+    end
+  end
+
+  context 'when Apollo returns no similar entries' do
+    let(:knowledge_runner) { double('Knowledge') }
+
+    before do
+      stub_const('Legion::Extensions::Apollo::Runners::Knowledge', knowledge_runner)
+      allow(knowledge_runner).to receive(:retrieve_relevant).and_return(
+        { success: true, entries: [], count: 0 }
+      )
+    end
+
+    it 'returns empty array' do
+      result = described_class.phase_relate(facts, entities)
+      expect(result).to eq([])
+    end
+  end
+end

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/runners/gas'
+
+RSpec.describe Legion::Extensions::Apollo::Runners::Gas do
+  describe '.process' do
+    let(:audit_event) do
+      {
+        request_id:       'req_abc',
+        messages:         [{ role: :user, content: 'How does pgvector work?' }],
+        response_content: 'pgvector uses HNSW indexes for approximate nearest neighbor search.',
+        routing:          { provider: :anthropic, model: 'claude-opus-4-6' },
+        tokens:           { input: 50, output: 30, total: 80 },
+        caller:           { requested_by: { identity: 'user:matt', type: :user } },
+        timestamp:        Time.now
+      }
+    end
+
+    it 'runs all 6 phases in order' do
+      allow(described_class).to receive(:phase_comprehend).and_return([{ content: 'fact', content_type: :fact }])
+      allow(described_class).to receive(:phase_extract).and_return([{ name: 'pgvector', type: 'technology' }])
+      allow(described_class).to receive(:phase_relate).and_return([])
+      allow(described_class).to receive(:phase_synthesize).and_return([])
+      allow(described_class).to receive(:phase_deposit).and_return({ deposited: 1 })
+      allow(described_class).to receive(:phase_anticipate).and_return([])
+
+      result = described_class.process(audit_event)
+      expect(result).to be_a(Hash)
+      expect(result[:phases_completed]).to eq(6)
+    end
+
+    it 'skips when audit event has no content' do
+      result = described_class.process({ request_id: 'req_abc' })
+      expect(result[:phases_completed]).to eq(0)
+    end
+
+    it 'skips when response_content is nil' do
+      result = described_class.process({ request_id: 'req_abc', messages: [{ role: :user, content: 'hi' }] })
+      expect(result[:phases_completed]).to eq(0)
+    end
+
+    it 'returns error details on failure' do
+      allow(described_class).to receive(:phase_comprehend).and_raise(StandardError, 'boom')
+
+      result = described_class.process(audit_event)
+      expect(result[:phases_completed]).to eq(0)
+      expect(result[:error]).to eq('boom')
+    end
+  end
+
+  describe '.processable?' do
+    it 'returns true with messages and response_content' do
+      event = { messages: [{ role: :user, content: 'hi' }], response_content: 'hello' }
+      expect(described_class.processable?(event)).to be true
+    end
+
+    it 'returns false without messages' do
+      expect(described_class.processable?({ response_content: 'hello' })).to be false
+    end
+
+    it 'returns false without response_content' do
+      expect(described_class.processable?({ messages: [{ role: :user, content: 'hi' }] })).to be false
+    end
+  end
+
+  describe '.mechanical_comprehend' do
+    it 'wraps response as a single observation' do
+      messages = [{ role: :user, content: 'hi' }]
+      result = described_class.mechanical_comprehend(messages, 'pgvector is fast')
+      expect(result).to eq([{ content: 'pgvector is fast', content_type: :observation }])
+    end
+  end
+
+  describe '.phase_extract' do
+    it 'returns empty array when EntityExtractor not defined' do
+      hide_const('Legion::Extensions::Apollo::Runners::EntityExtractor') if defined?(Legion::Extensions::Apollo::Runners::EntityExtractor)
+      result = described_class.phase_extract({ response_content: 'test' }, [])
+      expect(result).to eq([])
+    end
+  end
+
+  describe '.phase_relate' do
+    it 'returns empty array (stub)' do
+      expect(described_class.phase_relate([], [])).to eq([])
+    end
+  end
+
+  describe '.phase_synthesize' do
+    it 'returns empty array (stub)' do
+      expect(described_class.phase_synthesize([], [])).to eq([])
+    end
+  end
+
+  describe '.phase_anticipate' do
+    it 'returns empty array (stub)' do
+      expect(described_class.phase_anticipate([], [])).to eq([])
+    end
+  end
+
+  describe '.phase_deposit' do
+    it 'returns deposited 0 when Knowledge not defined' do
+      hide_const('Legion::Extensions::Apollo::Runners::Knowledge') if defined?(Legion::Extensions::Apollo::Runners::Knowledge)
+      result = described_class.phase_deposit([], [], [], [], { request_id: 'req_1' })
+      expect(result).to eq({ deposited: 0 })
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/runners/gas'
+
+RSpec.describe Legion::Extensions::Apollo::Runners::Gas, '.phase_synthesize' do
+  let(:facts) do
+    [
+      { content: 'pgvector uses HNSW indexes', content_type: :fact, confidence: 0.9 },
+      { content: 'HNSW provides logarithmic search time', content_type: :fact, confidence: 0.85 }
+    ]
+  end
+
+  let(:relations) do
+    [
+      { from_content: 'pgvector uses HNSW indexes', to_id: 'e1', relation_type: 'depends_on', confidence: 0.8 }
+    ]
+  end
+
+  context 'when GaiaCaller is unavailable' do
+    it 'returns empty array' do
+      result = described_class.phase_synthesize(facts, relations)
+      expect(result).to eq([])
+    end
+  end
+
+  context 'when GaiaCaller is available' do
+    let(:gaia_caller) { double('GaiaCaller') }
+    let(:mock_response) do
+      double(
+        'Response',
+        message: {
+          content: '{"synthesis":[{"content":"pgvector achieves fast search via HNSW",' \
+                   '"content_type":"inference","source_indices":[0,1]}]}'
+        }
+      )
+    end
+
+    before do
+      stub_const('Legion::LLM::Pipeline::GaiaCaller', gaia_caller)
+      allow(gaia_caller).to receive(:structured).and_return(mock_response)
+      allow(Legion::JSON).to receive(:load).and_return(
+        {
+          'synthesis' => [
+            {
+              'content'        => 'pgvector achieves fast similarity search through HNSW logarithmic indexing',
+              'content_type'   => 'inference',
+              'source_indices' => [0, 1]
+            }
+          ]
+        }
+      )
+    end
+
+    it 'generates derivative knowledge entries' do
+      result = described_class.phase_synthesize(facts, relations)
+      expect(result).not_to be_empty
+      expect(result.first[:content]).to include('pgvector')
+    end
+
+    it 'marks entries as candidate status' do
+      result = described_class.phase_synthesize(facts, relations)
+      expect(result.first[:status]).to eq(:candidate)
+    end
+
+    it 'caps confidence at 0.7' do
+      result = described_class.phase_synthesize(facts, relations)
+      result.each do |entry|
+        expect(entry[:confidence]).to be <= 0.7
+      end
+    end
+
+    it 'includes depends_on source indices' do
+      result = described_class.phase_synthesize(facts, relations)
+      expect(result.first[:source_indices]).to eq([0, 1])
+    end
+  end
+
+  context 'when LLM call fails' do
+    let(:gaia_caller) { double('GaiaCaller') }
+
+    before do
+      stub_const('Legion::LLM::Pipeline::GaiaCaller', gaia_caller)
+      allow(gaia_caller).to receive(:structured).and_raise(StandardError, 'LLM timeout')
+    end
+
+    it 'returns empty array on error' do
+      result = described_class.phase_synthesize(facts, relations)
+      expect(result).to eq([])
+    end
+  end
+
+  context 'with empty inputs' do
+    it 'returns empty array when no facts' do
+      result = described_class.phase_synthesize([], [])
+      expect(result).to eq([])
+    end
+
+    it 'returns empty array when single fact (nothing to synthesize)' do
+      result = described_class.phase_synthesize(
+        [{ content: 'one fact', content_type: :fact, confidence: 0.9 }],
+        []
+      )
+      expect(result).to eq([])
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-apollo
 version: !ruby/object:Gem::Version
-  version: 0.3.9
+  version: 0.4.0
 platform: ruby
 authors:
 - Esity
@@ -150,6 +150,7 @@ files:
 - lib/legion/extensions/apollo/actors/decay.rb
 - lib/legion/extensions/apollo/actors/entity_watchdog.rb
 - lib/legion/extensions/apollo/actors/expertise_aggregator.rb
+- 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/client.rb
@@ -161,18 +162,21 @@ files:
 - lib/legion/extensions/apollo/helpers/similarity.rb
 - lib/legion/extensions/apollo/runners/entity_extractor.rb
 - lib/legion/extensions/apollo/runners/expertise.rb
+- 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/transport.rb
 - lib/legion/extensions/apollo/transport/exchanges/apollo.rb
 - lib/legion/extensions/apollo/transport/messages/ingest.rb
 - lib/legion/extensions/apollo/transport/messages/query.rb
+- lib/legion/extensions/apollo/transport/queues/gas.rb
 - lib/legion/extensions/apollo/transport/queues/ingest.rb
 - lib/legion/extensions/apollo/transport/queues/query.rb
 - lib/legion/extensions/apollo/version.rb
 - spec/legion/extensions/apollo/actors/decay_spec.rb
 - spec/legion/extensions/apollo/actors/entity_watchdog_spec.rb
 - 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/client_spec.rb
 - spec/legion/extensions/apollo/contradiction_spec.rb
@@ -185,6 +189,10 @@ files:
 - spec/legion/extensions/apollo/runners/decay_cycle_spec.rb
 - spec/legion/extensions/apollo/runners/entity_extractor_spec.rb
 - spec/legion/extensions/apollo/runners/expertise_spec.rb
+- spec/legion/extensions/apollo/runners/gas_anticipate_spec.rb
+- spec/legion/extensions/apollo/runners/gas_relate_spec.rb
+- spec/legion/extensions/apollo/runners/gas_spec.rb
+- 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/transport/messages/ingest_spec.rb