lex-apollo 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5f9f60cb9a67bc5d4cd35af051b1abe3251787d0da55ac092c1898942bd2144
-  data.tar.gz: 8b0cd86443469ae7a0d5d857a127f855cd0e68f8d967c94a727e8f166372e483
+  metadata.gz: 6156122baf8989f96a09685918e8ed6f6608730c8e19e442a632f5faa8853ee7
+  data.tar.gz: 478d0003003a76abc6ffdc0c39a7be3b06d8e75f91e1c88a6edfa5e46a05634a
 SHA512:
-  metadata.gz: 3f239c19c6212f7c142aec1e0fe34aed651928f5a4c37acfcf54152d6719594f94b6ddb037bf48666eb93f9c747d341a477039e320e2e74fef17a8188519e0a9
-  data.tar.gz: 6227ef5fffa37ad570940591d390ac594d71f10a49de1e75a6ce568b075ac6c0293ba13478130eebbc366c6195b383327dab2b7400398bc2fe6f1f274f4b61ca
+  metadata.gz: 898147c2dbe69430a0dc4606db21a82100de37a1865b9d56157499530c7e7a205e8cc44cd39f23410293a8f3874c9dadacf9c5aa47c89bd5b61a7a39b9067951
+  data.tar.gz: 8ed9fe61c718b12abfd8b5b2c6a75e249e47491c6bf8068df984f6f18c8943ee5d3d56b3b2def551703b4cd7b0463942e20a4803a740ca7da65d25a87b90c344

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.4] - 2026-03-20
+
+### Added
+- `Helpers::EntityWatchdog`: regex-based entity detection for persons, services, repos, and configurable concepts
+- GAIA `post_tick_reflection` handler for passive entity detection (enabled via `apollo.entity_watchdog.enabled`)
+- Deduplication by type+value, configurable type filtering, and `link_or_create` for Apollo integration
+
 ## [0.3.3] - 2026-03-20
 
 ### Added

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Apollo
+      module Helpers
+        module EntityWatchdog
+          ENTITY_PATTERNS = {
+            person:  /\b[A-Z][a-z]+(?:\s[A-Z][a-z]+)+\b/,
+            service: %r{\bhttps?://[^\s]+\b},
+            repo:    %r{\b[a-zA-Z0-9_-]+/[a-zA-Z0-9_.-]+\b}
+          }.freeze
+
+          class << self
+            def detect_entities(text:, types: nil)
+              return [] if text.nil? || text.empty?
+
+              types = (types || default_types).map(&:to_sym)
+              entities = []
+
+              types.each do |type_sym|
+                pattern = type_sym == :concept ? concept_pattern : ENTITY_PATTERNS[type_sym]
+                next unless pattern
+
+                text.scan(pattern).each do |match|
+                  entities << { type: type_sym, value: match.strip, confidence: 0.5 }
+                end
+              end
+
+              entities.uniq { |e| [e[:type], e[:value].downcase] }
+            end
+
+            def link_or_create(entities:, source_context: nil)
+              return { success: true, linked: 0, created: 0 } if entities.nil? || entities.empty?
+
+              linked = 0
+              created = 0
+
+              entities.each do |entity|
+                existing = find_existing(entity)
+                if existing
+                  bump_confidence(existing, source_context)
+                  linked += 1
+                else
+                  create_candidate(entity, source_context)
+                  created += 1
+                end
+              end
+
+              { success: true, linked: linked, created: created }
+            end
+
+            def concept_pattern
+              keywords = if defined?(Legion::Settings)
+                           Legion::Settings.dig(:apollo, :entity_watchdog, :concept_keywords) || []
+                         else
+                           []
+                         end
+              return nil if keywords.empty?
+
+              Regexp.new("\\b(?:#{keywords.map { |k| Regexp.escape(k) }.join('|')})\\b", Regexp::IGNORECASE)
+            end
+
+            private
+
+            def default_types
+              if defined?(Legion::Settings)
+                Legion::Settings.dig(:apollo, :entity_watchdog, :types) || %w[person service repo concept]
+              else
+                %w[person service repo concept]
+              end
+            end
+
+            def find_existing(_entity)
+              return nil unless defined?(Runners::Knowledge) && respond_to?(:retrieve_relevant, true)
+
+              nil
+            end
+
+            def bump_confidence(_entry, _source_context)
+              # Increment retrieval confidence on existing Apollo entry
+            end
+
+            def create_candidate(entity, _source_context)
+              return unless defined?(Runners::Knowledge)
+
+              Legion::Logging.debug "[entity_watchdog] candidate: #{entity[:type]}=#{entity[:value]}" if defined?(Legion::Logging)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -130,6 +130,39 @@ module Legion
             { success: false, error: e.message }
           end
 
+          def redistribute_knowledge(agent_id:, min_confidence: 0.5, **)
+            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+
+            entries = Legion::Data::Model::ApolloEntry
+                      .where(source_agent: agent_id, status: 'confirmed')
+                      .where { confidence > min_confidence }
+                      .all
+
+            return { success: true, redistributed: 0 } if entries.empty?
+
+            store = (Legion::Extensions::Agentic::Memory::Trace.shared_store if defined?(Legion::Extensions::Agentic::Memory::Trace))
+
+            redistributed = 0
+            entries.each do |entry|
+              if store
+                trace = Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace.new_trace(
+                  type:            :semantic,
+                  content_payload: { content: entry.content, source_agent: agent_id,
+                                     content_type: entry.content_type, tags: Array(entry.tags) },
+                  strength:        entry.confidence.to_f,
+                  domain_tag:      Array(entry.tags).first || 'general'
+                )
+                store.store(trace)
+              end
+              redistributed += 1
+            end
+
+            Legion::Logging.info "[apollo] redistributed #{redistributed} entries from departing agent=#{agent_id}"
+            { success: true, redistributed: redistributed, agent_id: agent_id }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
           def retrieve_relevant(query: nil, limit: 5, min_confidence: 0.3, tags: nil, skip: false, **)
             return { status: :skipped } if skip
 

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Apollo
-      VERSION = '0.3.3'
+      VERSION = '0.3.5'
     end
   end
 end

data/lib/legion/extensions/apollo.rb

@@ -24,3 +24,20 @@ module Legion
     end
   end
 end
+
+# Entity watchdog on post_tick_reflection
+if defined?(Legion::Gaia::PhaseWiring) && begin
+  Legion::Settings.dig(:apollo, :entity_watchdog, :enabled)
+rescue StandardError
+  false
+end
+  require 'legion/extensions/apollo/helpers/entity_watchdog'
+  Legion::Gaia::PhaseWiring.register_handler(:post_tick_reflection) do |tick_results|
+    text = tick_results.is_a?(Hash) ? (tick_results[:content] || tick_results[:output] || '').to_s : tick_results.to_s
+    entities = Legion::Extensions::Apollo::Helpers::EntityWatchdog.detect_entities(text: text)
+    if entities.any?
+      Legion::Extensions::Apollo::Helpers::EntityWatchdog.link_or_create(entities:       entities,
+                                                                         source_context: tick_results[:tick_id])
+    end
+  end
+end

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

@@ -45,4 +45,29 @@ RSpec.describe Legion::Extensions::Apollo::GaiaIntegration do
       expect(result).to eq({ success: true })
     end
   end
+
+  describe 'entity watchdog phase handler' do
+    it 'detects entities from tick results' do
+      require 'legion/extensions/apollo/helpers/entity_watchdog'
+      tick_results = { content: 'Jane Doe deployed to https://api.example.com', tick_id: 'tick-1' }
+      entities = Legion::Extensions::Apollo::Helpers::EntityWatchdog.detect_entities(text: tick_results[:content])
+      expect(entities.size).to be >= 2
+    end
+
+    it 'links or creates entities from tick results' do
+      require 'legion/extensions/apollo/helpers/entity_watchdog'
+      tick_results = { content: 'Jane Doe at LegionIO/lex-mesh', tick_id: 'tick-2' }
+      entities = Legion::Extensions::Apollo::Helpers::EntityWatchdog.detect_entities(text: tick_results[:content])
+      result = Legion::Extensions::Apollo::Helpers::EntityWatchdog.link_or_create(
+        entities: entities, source_context: tick_results[:tick_id]
+      )
+      expect(result[:success]).to be true
+    end
+
+    it 'entry point has entity watchdog registration block' do
+      entry_point = File.read(File.expand_path('../../../../lib/legion/extensions/apollo.rb', __dir__))
+      expect(entry_point).to include('entity_watchdog')
+      expect(entry_point).to include('PhaseWiring.register_handler(:post_tick_reflection)')
+    end
+  end
 end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/helpers/entity_watchdog'
+
+RSpec.describe Legion::Extensions::Apollo::Helpers::EntityWatchdog do
+  describe '.detect_entities' do
+    it 'detects person names (capitalized multi-word)' do
+      entities = described_class.detect_entities(text: 'Talked to Jane Doe about the project')
+      person = entities.find { |e| e[:type] == :person }
+      expect(person).not_to be_nil
+      expect(person[:value]).to eq('Jane Doe')
+    end
+
+    it 'detects service URLs' do
+      entities = described_class.detect_entities(text: 'Deployed to https://api.example.com/v1')
+      service = entities.find { |e| e[:type] == :service }
+      expect(service).not_to be_nil
+      expect(service[:value]).to include('example.com')
+    end
+
+    it 'detects repo references' do
+      entities = described_class.detect_entities(text: 'Check LegionIO/lex-mesh for the code')
+      repo = entities.find { |e| e[:type] == :repo }
+      expect(repo).not_to be_nil
+      expect(repo[:value]).to eq('LegionIO/lex-mesh')
+    end
+
+    it 'detects concept keywords from settings' do
+      allow(described_class).to receive(:concept_pattern).and_return(/\b(?:kubernetes|terraform)\b/i)
+      entities = described_class.detect_entities(text: 'Using Terraform to deploy Kubernetes')
+      concepts = entities.select { |e| e[:type] == :concept }
+      expect(concepts.size).to eq(2)
+    end
+
+    it 'deduplicates entities by type and lowercase value' do
+      entities = described_class.detect_entities(text: 'Jane Doe met Jane Doe again')
+      persons = entities.select { |e| e[:type] == :person }
+      expect(persons.size).to eq(1)
+    end
+
+    it 'returns empty array for text with no entities' do
+      entities = described_class.detect_entities(text: 'nothing special here')
+      expect(entities).to be_empty
+    end
+
+    it 'filters by specified types' do
+      entities = described_class.detect_entities(
+        text:  'Jane Doe at https://example.com with LegionIO/lex-mesh',
+        types: [:person]
+      )
+      expect(entities.all? { |e| e[:type] == :person }).to be true
+    end
+  end
+
+  describe '.link_or_create' do
+    it 'returns counts for empty entities' do
+      result = described_class.link_or_create(entities: [])
+      expect(result[:success]).to be true
+      expect(result[:linked]).to eq(0)
+      expect(result[:created]).to eq(0)
+    end
+  end
+end

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

@@ -307,4 +307,88 @@ RSpec.describe Legion::Extensions::Apollo::Runners::Knowledge do
       end
     end
   end
+
+  describe '#redistribute_knowledge' 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.redistribute_knowledge(agent_id: 'agent-x')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq('apollo_data_not_available')
+      end
+    end
+
+    context 'when the departing agent has no confirmed entries' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        chain = double('chain')
+        allow(mock_entry_class).to receive(:where).and_return(chain)
+        allow(chain).to receive(:where).and_return(double(all: []))
+      end
+
+      it 'returns success with zero redistributed' do
+        result = host.redistribute_knowledge(agent_id: 'departed-1')
+        expect(result[:success]).to be true
+        expect(result[:redistributed]).to eq(0)
+      end
+    end
+
+    context 'when the departing agent has confirmed entries' do
+      let(:mock_entry_class) { double('ApolloEntry') }
+      let(:mock_entry) do
+        double('entry', content: 'Ruby is fast', content_type: 'fact',
+                        confidence: 0.8, tags: ['ruby'])
+      end
+
+      before do
+        stub_const('Legion::Data::Model::ApolloEntry', mock_entry_class)
+        chain = double('chain')
+        allow(mock_entry_class).to receive(:where).and_return(chain)
+        allow(chain).to receive(:where).and_return(double(all: [mock_entry]))
+      end
+
+      it 'returns the count of redistributed entries' do
+        result = host.redistribute_knowledge(agent_id: 'departed-2')
+        expect(result[:success]).to be true
+        expect(result[:redistributed]).to eq(1)
+        expect(result[:agent_id]).to eq('departed-2')
+      end
+
+      it 'stores into trace shared_store when Memory::Trace is available' do
+        mock_store = double('store')
+        mock_trace_helpers = Module.new do
+          def self.new_trace(type:, content_payload: nil, **kwargs) # rubocop:disable Lint/UnusedMethodArgument
+            { trace_id: 'trace-abc', trace_type: type, strength: kwargs[:strength] || 0.5 }
+          end
+        end
+        stub_const('Legion::Extensions::Agentic::Memory::Trace', Module.new)
+        stub_const('Legion::Extensions::Agentic::Memory::Trace::Helpers::Trace', mock_trace_helpers)
+        allow(Legion::Extensions::Agentic::Memory::Trace).to receive(:shared_store).and_return(mock_store)
+        allow(mock_store).to receive(:store)
+
+        result = host.redistribute_knowledge(agent_id: 'departed-3')
+        expect(result[:redistributed]).to eq(1)
+        expect(mock_store).to have_received(:store).once
+      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(:where)
+          .and_raise(Sequel::Error, 'db error')
+      end
+
+      it 'returns a structured error' do
+        result = host.redistribute_knowledge(agent_id: 'agent-x')
+        expect(result[:success]).to be false
+        expect(result[:error]).to eq('db error')
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-apollo
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.5
 platform: ruby
 authors:
 - Esity
@@ -58,6 +58,7 @@ files:
 - lib/legion/extensions/apollo/gaia_integration.rb
 - lib/legion/extensions/apollo/helpers/confidence.rb
 - lib/legion/extensions/apollo/helpers/embedding.rb
+- lib/legion/extensions/apollo/helpers/entity_watchdog.rb
 - lib/legion/extensions/apollo/helpers/graph_query.rb
 - lib/legion/extensions/apollo/helpers/similarity.rb
 - lib/legion/extensions/apollo/runners/entity_extractor.rb
@@ -80,6 +81,7 @@ files:
 - spec/legion/extensions/apollo/gaia_integration_spec.rb
 - spec/legion/extensions/apollo/helpers/confidence_spec.rb
 - spec/legion/extensions/apollo/helpers/embedding_spec.rb
+- spec/legion/extensions/apollo/helpers/entity_watchdog_spec.rb
 - spec/legion/extensions/apollo/helpers/graph_query_spec.rb
 - spec/legion/extensions/apollo/helpers/similarity_spec.rb
 - spec/legion/extensions/apollo/runners/decay_cycle_spec.rb