lex-apollo 0.3.1 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1478924cdbe16dac455d02313dd3de7b42bb0d022da411213b537f44527d14c0
-  data.tar.gz: 2e72cfa6dab1b790b1fe904ea23fe55ae093e0c6570a3b2790c8b7c0930b64cb
+  metadata.gz: e7d785a9fed9656eb22b307620a384f64e52646bca14728dc0de3ef2b1adb5bd
+  data.tar.gz: c64bcf1b75ee0ed43a747722a610c5cee8de823995d5f7455e31ae5c9174c56d
 SHA512:
-  metadata.gz: a8aafbcf43d73647b48c27a8e400de209a723591b59b15f92f3144fd73ea4ff374a735cc4aa4720ffa48560461fe6951da231a0dc0114064f38d1f9b4cc170a6
-  data.tar.gz: d5d04a370239f53a7ab891a957ace9f52b3d9a459c93494892134a4658153cc13e629de766aaf84f4598b9b0d3c2406df316869156592e778eb46ea89848ce83
+  metadata.gz: 0ff89d33e4993dd8c71e392202c66add619ab04045fa674b5f8f0c4d891b727ca7401865d349c68bdc3a0344e1773db4f86651ed7e96ecbcaf0098a9d05cdbc9
+  data.tar.gz: 29b69744b9870bee8e1fbfc030652aede63a51c3a12cd02a3bc69bfc805b6267cf8045346cb37dc2565e1e103ae6f3b559972536b02f3a62dd4b6f12223361a5

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 # 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
+- `Runners::EntityExtractor`: LLM-backed structured extraction of people, services, repositories, and concepts from arbitrary text
+- `Actors::EntityWatchdog`: interval actor (120s) that reads recent task logs, extracts entities, deduplicates against Apollo, and publishes ingest messages for net-new entities
+- Settings support: `apollo.entity_watchdog.types`, `apollo.entity_watchdog.min_confidence`, `apollo.entity_watchdog.dedup_threshold`
+- Fallback behavior when `Legion::LLM` is unavailable (returns empty entity list, no error)
+
+## [0.3.2] - 2026-03-20
+
+### Changed
+- Replace exponential confidence decay (`confidence * 0.998`) with power-law decay
+  (`confidence / (1 + alpha)` per tick, where `alpha` defaults to 0.1)
+- Configurable via `apollo.power_law_alpha` setting (default: 0.1)
+- Source diversity enforcement in corroboration: same-source corroboration (matching
+  `source_provider`) receives 50% boost weight instead of full weight
+- `check_corroboration` skips auto-promotion when both candidate and match have
+  the same known `source_provider` (correlated error prevention)
+- `apply_corroboration_boost` accepts optional `weight:` kwarg (default: 1.0)
+
+### Added
+- `source_provider` field populated on ingest via explicit kwarg or agent name inference
+- `handle_ingest` accepts `source_provider:` kwarg; derives provider from agent name
+  convention when not explicitly provided
+
 ## [0.3.1] - 2026-03-17
 
 ### Added

data/README.md

@@ -26,40 +26,41 @@ gem 'lex-apollo'
 ```ruby
 require 'legion/extensions/apollo'
 
-client = Legion::Extensions::Apollo::Client.new(agent_id: 'my-agent-001')
+client = Legion::Extensions::Apollo::Client.new
 
-# Store a confirmed knowledge entry
+# Build a store payload (published to RabbitMQ for the Apollo service to persist)
 client.store_knowledge(
-  domain: 'networking',
-  content: 'BGP route reflectors reduce full-mesh IBGP complexity',
-  confidence: 0.9,
-  source_agent_id: 'my-agent-001',
-  tags: ['bgp', 'routing', 'ibgp']
+  content:      'BGP route reflectors reduce full-mesh IBGP complexity',
+  content_type: :fact,
+  source_agent: 'my-agent-001',
+  tags:         ['bgp', 'routing', 'ibgp'],
+  context:      { source: 'network_team_wiki' }
 )
 
-# Query for relevant knowledge
+# Build a query payload
 client.query_knowledge(
-  query: 'BGP route reflector configuration',
-  domain: 'networking',
+  query:          'BGP route reflector configuration',
   min_confidence: 0.6,
-  limit: 10
+  limit:          10
 )
 
 # Get related entries (concept graph traversal)
-client.related_entries(entry_id: 'entry-uuid', max_hops: 2)
+client.related_entries(entry_id: 'entry-uuid', depth: 2)
 
 # Deprecate a stale entry
 client.deprecate_entry(entry_id: 'entry-uuid', reason: 'superseded by RFC 7938')
 ```
 
+Content types: `:fact`, `:concept`, `:procedure`, `:association`, `:observation`
+
 ### Expertise Queries
 
 ```ruby
 # Get proficiency scores for a domain
-client.get_expertise(domain: 'networking', agent_id: 'my-agent-001')
+client.get_expertise(domain: 'networking', min_proficiency: 0.3)
 
-# Find domains where knowledge coverage is thin
-client.domains_at_risk(min_entries: 5, min_confidence: 0.7)
+# Find domains where coverage is thin (below min agent count)
+client.domains_at_risk(min_agents: 2)
 
 # Full agent knowledge profile
 client.agent_profile(agent_id: 'my-agent-001')
@@ -68,11 +69,11 @@ client.agent_profile(agent_id: 'my-agent-001')
 ### Maintenance
 
 ```ruby
-# Force confidence decay cycle
-client.force_decay(domain: 'networking')
+# Force confidence decay cycle (factor multiplied against each entry's confidence)
+client.force_decay(factor: 0.5)
 
-# Archive entries below confidence threshold
-client.archive_stale(max_confidence: 0.2)
+# Archive entries older than N days
+client.archive_stale(days: 90)
 
 # Resolve a corroboration dispute
 client.resolve_dispute(entry_id: 'entry-uuid', resolution: :accept)
@@ -104,12 +105,13 @@ Apollo is wired into the GAIA tick cycle at the `knowledge_retrieval` phase (pha
 
 Entries have a confidence score between 0.0 and 1.0:
 
-- New entries start at the caller-supplied confidence value
-- Corroboration from multiple agents boosts confidence
-- Entries below `WRITE_GATE_THRESHOLD` are rejected on ingest
-- Confidence decays hourly; entries below `ARCHIVE_THRESHOLD` are archived
+- New entries start at `INITIAL_CONFIDENCE` (0.5) with status `candidate`
+- Corroboration from a semantically similar entry (cosine > 0.9) boosts confidence by 0.3 and promotes to `confirmed`
+- Each retrieval adds a small boost (+0.02, capped at 1.0)
+- Confidence decays hourly by factor 0.998; entries below 0.1 are archived
+- The GAIA write gate (`meets_write_gate?`) requires confidence > 0.6 and novelty > 0.3 for the tick write-back path
 
-See `helpers/confidence.rb` for decay constants and boost logic.
+See `helpers/confidence.rb` for all constants and math helpers.
 
 ## Requirements
 

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+require_relative '../runners/knowledge'
+require_relative '../runners/entity_extractor'
+
+module Legion
+  module Extensions
+    module Apollo
+      module Actor
+        class EntityWatchdog < Legion::Extensions::Actors::Every
+          include Legion::Extensions::Apollo::Runners::Knowledge
+          include Legion::Extensions::Apollo::Runners::EntityExtractor
+
+          DEDUP_THRESHOLD_DEFAULT   = 0.92
+          TASK_LOG_LOOKBACK_SECONDS = 300
+          TASK_LOG_LIMIT            = 50
+
+          def runner_class    = Legion::Extensions::Apollo::Runners::EntityExtractor
+          def runner_function = 'scan_and_ingest'
+          def time            = 120
+          def run_now?        = false
+          def use_runner?     = false
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def enabled?
+            defined?(Legion::Extensions::Apollo::Runners::EntityExtractor) &&
+              defined?(Legion::Transport)
+          rescue StandardError
+            false
+          end
+
+          def scan_and_ingest
+            texts = recent_task_log_texts
+            return { success: true, ingested: 0, reason: :no_logs } if texts.empty?
+
+            ingested = 0
+            texts.each do |text|
+              result = extract_entities(
+                text:           text,
+                entity_types:   entity_types,
+                min_confidence: min_entity_confidence
+              )
+              next unless result[:success]
+
+              result[:entities].each do |entity|
+                next if entity_exists_in_apollo?(entity)
+
+                publish_entity_ingest(entity)
+                ingested += 1
+              end
+            end
+
+            log_debug("EntityWatchdog: ingested #{ingested} new entities from #{texts.size} log entries")
+            { success: true, ingested: ingested, logs_scanned: texts.size }
+          rescue StandardError => e
+            log_error("EntityWatchdog scan_and_ingest failed: #{e.message}")
+            { success: false, error: e.message }
+          end
+
+          def recent_task_log_texts
+            return [] unless defined?(Legion::Data) && defined?(Legion::Data::Model::TaskLog)
+
+            cutoff = Time.now - TASK_LOG_LOOKBACK_SECONDS
+            logs = Legion::Data::Model::TaskLog
+                   .where { created_at >= cutoff }
+                   .order(Sequel.desc(:created_at))
+                   .limit(TASK_LOG_LIMIT)
+                   .select_map(:message)
+            logs.map(&:to_s).reject(&:empty?).uniq
+          rescue StandardError
+            []
+          end
+
+          def entity_exists_in_apollo?(entity)
+            result = retrieve_relevant(
+              query:          entity[:name].to_s,
+              limit:          1,
+              min_confidence: 0.1,
+              tags:           [entity[:type].to_s]
+            )
+            return false unless result[:success] && result[:count].positive?
+
+            closest = result[:entries].first
+            distance = closest[:distance].to_f
+            distance <= (1.0 - dedup_similarity_threshold)
+          rescue StandardError
+            false
+          end
+
+          def publish_entity_ingest(entity)
+            return unless defined?(Legion::Extensions::Apollo::Transport::Messages::Ingest)
+
+            Legion::Extensions::Apollo::Transport::Messages::Ingest.new(
+              content:      "#{entity[:type].to_s.capitalize}: #{entity[:name]}",
+              content_type: 'concept',
+              tags:         [entity[:type].to_s, 'entity_watchdog'],
+              source_agent: 'lex-apollo:entity_watchdog',
+              context:      { entity_type: entity[:type], original_name: entity[:name] }
+            ).publish
+          rescue StandardError => e
+            log_error("EntityWatchdog publish failed: #{e.message}")
+          end
+
+          def entity_types
+            if defined?(Legion::Settings)
+              types = Legion::Settings.dig(:apollo, :entity_watchdog, :types)
+              return Array(types).map(&:to_s) if types
+            end
+            %w[person service repository concept]
+          end
+
+          def min_entity_confidence
+            if defined?(Legion::Settings)
+              val = Legion::Settings.dig(:apollo, :entity_watchdog, :min_confidence)
+              return val.to_f if val
+            end
+            0.7
+          end
+
+          def dedup_similarity_threshold
+            if defined?(Legion::Settings)
+              val = Legion::Settings.dig(:apollo, :entity_watchdog, :dedup_threshold)
+              return val.to_f if val
+            end
+            DEDUP_THRESHOLD_DEFAULT
+          end
+
+          private
+
+          def log_debug(message)
+            Legion::Logging.debug(message) if defined?(Legion::Logging)
+          end
+
+          def log_error(message)
+            Legion::Logging.error(message) if defined?(Legion::Logging)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -8,7 +8,7 @@ module Legion
           INITIAL_CONFIDENCE = 0.5
           CORROBORATION_BOOST = 0.3
           RETRIEVAL_BOOST = 0.02
-          HOURLY_DECAY_FACTOR = 0.998
+          POWER_LAW_ALPHA = 0.1
           DECAY_THRESHOLD = 0.1
           CORROBORATION_SIMILARITY_THRESHOLD = 0.9
           WRITE_CONFIDENCE_GATE = 0.6
@@ -20,16 +20,21 @@ module Legion
 
           module_function
 
-          def apply_decay(confidence:, factor: HOURLY_DECAY_FACTOR, **)
-            [confidence * factor, 0.0].max
+          def apply_decay(confidence:, age_hours: nil, alpha: POWER_LAW_ALPHA, **)
+            if age_hours
+              [confidence * ((age_hours.clamp(0, Float::INFINITY) + 2.0)**(-alpha)) / ((age_hours.clamp(0, Float::INFINITY) + 1.0)**(-alpha)), 0.0].max
+            else
+              factor = 1.0 / (1.0 + alpha)
+              [confidence * factor, 0.0].max
+            end
           end
 
           def apply_retrieval_boost(confidence:, **)
             [confidence + RETRIEVAL_BOOST, 1.0].min
           end
 
-          def apply_corroboration_boost(confidence:, **)
-            [confidence + CORROBORATION_BOOST, 1.0].min
+          def apply_corroboration_boost(confidence:, weight: 1.0, **)
+            [confidence + (CORROBORATION_BOOST * weight), 1.0].min
           end
 
           def decayed?(confidence:, **)

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/entity_extractor.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Apollo
+      module Runners
+        module EntityExtractor
+          DEFAULT_ENTITY_TYPES = %w[person service repository concept].freeze
+          DEFAULT_MIN_CONFIDENCE = 0.7
+
+          def extract_entities(text:, entity_types: nil, min_confidence: DEFAULT_MIN_CONFIDENCE, **)
+            return { success: true, entities: [], source: :empty } if text.to_s.strip.empty?
+
+            return { success: true, entities: [], source: :unavailable } unless defined?(Legion::LLM) && Legion::LLM.started?
+
+            types = Array(entity_types).map(&:to_s)
+            types = DEFAULT_ENTITY_TYPES if types.empty?
+
+            result = Legion::LLM.structured(
+              messages: [
+                { role: 'user', content: entity_extraction_prompt(text: text, entity_types: types) }
+              ],
+              schema:   entity_schema
+            )
+
+            raw_entities = result.dig(:data, :entities) || []
+            filtered = raw_entities.select do |entity|
+              (entity[:confidence] || 0.0) >= min_confidence &&
+                (types.empty? || types.include?(entity[:type].to_s))
+            end
+
+            { success: true, entities: filtered, source: :llm }
+          rescue StandardError => e
+            { success: false, entities: [], error: e.message, source: :error }
+          end
+
+          def entity_extraction_prompt(text:, entity_types:, **)
+            type_list = Array(entity_types).join(', ')
+            <<~PROMPT.strip
+              Extract named entities from the following text. Return only entities of these types: #{type_list}.
+
+              For each entity provide:
+              - name: the canonical name as it appears (string)
+              - type: one of #{type_list} (string)
+              - confidence: your confidence this is a real entity of that type (float 0.0-1.0)
+
+              Text:
+              #{text}
+            PROMPT
+          end
+
+          def entity_schema
+            {
+              type:       'object',
+              properties: {
+                entities: {
+                  type:  'array',
+                  items: {
+                    type:       'object',
+                    properties: {
+                      name:       { type: 'string' },
+                      type:       { type: 'string' },
+                      confidence: { type: 'number' }
+                    },
+                    required:   %w[name type confidence]
+                  }
+                }
+              },
+              required:   ['entities']
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -53,7 +53,7 @@ module Legion
             }
           end
 
-          def handle_ingest(content:, content_type:, tags: [], source_agent: 'unknown', context: {}, **)
+          def handle_ingest(content:, content_type:, tags: [], source_agent: 'unknown', source_provider: nil, context: {}, **) # rubocop:disable Metrics/ParameterLists
             return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
 
             embedding = Helpers::Embedding.generate(text: content)
@@ -64,14 +64,15 @@ module Legion
 
             unless corroborated
               new_entry = Legion::Data::Model::ApolloEntry.create(
-                content:        content,
-                content_type:   content_type_sym,
-                confidence:     Helpers::Confidence::INITIAL_CONFIDENCE,
-                source_agent:   source_agent,
-                source_context: ::JSON.dump(context.is_a?(Hash) ? context : {}),
-                tags:           Sequel.pg_array(tag_array),
-                status:         'candidate',
-                embedding:      Sequel.lit("'[#{embedding.join(',')}]'::vector")
+                content:         content,
+                content_type:    content_type_sym,
+                confidence:      Helpers::Confidence::INITIAL_CONFIDENCE,
+                source_agent:    source_agent,
+                source_provider: source_provider || derive_provider_from_agent(source_agent),
+                source_context:  ::JSON.dump(context.is_a?(Hash) ? context : {}),
+                tags:            Sequel.pg_array(tag_array),
+                status:          'candidate',
+                embedding:       Sequel.lit("'[#{embedding.join(',')}]'::vector")
               )
               existing_id = new_entry.id
             end
@@ -220,8 +221,9 @@ module Legion
               sim = Helpers::Similarity.cosine_similarity(vec_a: embedding, vec_b: entry.embedding)
               next unless Helpers::Similarity.above_corroboration_threshold?(similarity: sim)
 
+              weight = same_source_provider?(source_agent, entry) ? 0.5 : 1.0
               entry.update(
-                confidence: Helpers::Confidence.apply_corroboration_boost(confidence: entry.confidence),
+                confidence: Helpers::Confidence.apply_corroboration_boost(confidence: entry.confidence, weight: weight),
                 updated_at: Time.now
               )
               Legion::Data::Model::ApolloRelation.create(
@@ -237,6 +239,20 @@ module Legion
             [false, nil]
           end
 
+          def same_source_provider?(submitting_agent, entry)
+            stored = entry.respond_to?(:source_provider) ? entry.source_provider : nil
+            return false if stored.nil? || stored.to_s.empty? || stored.to_s == 'unknown'
+
+            derive_provider_from_agent(submitting_agent) == stored.to_s
+          end
+
+          def derive_provider_from_agent(source_agent)
+            return 'unknown' if source_agent.nil? || source_agent == 'unknown'
+
+            provider = source_agent.to_s.split(/[-_]/).first.downcase
+            %w[claude openai gemini human system].include?(provider) ? provider : 'unknown'
+          end
+
           def upsert_expertise(source_agent:, domain:)
             expertise = Legion::Data::Model::ApolloExpertise
                         .where(agent_id: source_agent, domain: domain).first

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

@@ -62,6 +62,11 @@ module Legion
 
               next unless match
 
+              candidate_provider = candidate.respond_to?(:source_provider) ? candidate.source_provider : nil
+              match_provider     = match.respond_to?(:source_provider) ? match.source_provider : nil
+              both_known = known_provider?(candidate_provider) && known_provider?(match_provider)
+              next if both_known && candidate_provider == match_provider
+
               candidate.update(
                 status:       'confirmed',
                 confirmed_at: Time.now,
@@ -88,7 +93,13 @@ module Legion
           private
 
           def decay_rate
-            (defined?(Legion::Settings) && Legion::Settings.dig(:apollo, :decay_rate)) || 0.998
+            alpha = (defined?(Legion::Settings) && Legion::Settings.dig(:apollo, :power_law_alpha)) ||
+                    Helpers::Confidence::POWER_LAW_ALPHA
+            1.0 / (1.0 + alpha)
+          end
+
+          def known_provider?(provider)
+            !provider.nil? && !provider.to_s.empty? && provider.to_s != 'unknown'
           end
 
           def decay_threshold

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Apollo
-      VERSION = '0.3.1'
+      VERSION = '0.3.4'
     end
   end
 end

data/lib/legion/extensions/apollo.rb

@@ -7,6 +7,7 @@ require 'legion/extensions/apollo/helpers/graph_query'
 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'
 
 if defined?(Legion::Transport)
   require 'legion/extensions/apollo/transport/exchanges/apollo'
@@ -23,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/actors/entity_watchdog_spec.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Every)
+  module Legion
+    module Extensions
+      module Actors
+        class Every
+          def initialize(**_opts); end
+        end
+      end
+    end
+  end
+end
+$LOADED_FEATURES << 'legion/extensions/actors/every' unless $LOADED_FEATURES.include?('legion/extensions/actors/every')
+
+require 'legion/extensions/apollo/runners/knowledge'
+require 'legion/extensions/apollo/runners/entity_extractor'
+require 'legion/extensions/apollo/actors/entity_watchdog'
+
+RSpec.describe Legion::Extensions::Apollo::Actor::EntityWatchdog do
+  subject(:actor) { described_class.allocate }
+
+  describe 'actor configuration' do
+    it 'uses EntityExtractor as runner_class' do
+      expect(actor.runner_class).to eq(Legion::Extensions::Apollo::Runners::EntityExtractor)
+    end
+
+    it 'runs scan_and_ingest function' do
+      expect(actor.runner_function).to eq('scan_and_ingest')
+    end
+
+    it 'runs every 120 seconds' do
+      expect(actor.time).to eq(120)
+    end
+
+    it 'does not run immediately' do
+      expect(actor.run_now?).to be false
+    end
+
+    it 'does not use the runner framework (calls manual directly)' do
+      expect(actor.use_runner?).to be false
+    end
+
+    it 'does not generate tasks' do
+      expect(actor.generate_task?).to be false
+    end
+  end
+
+  describe '#scan_and_ingest' do
+    let(:entities) { [{ name: 'lex-synapse', type: 'repository', confidence: 0.95 }] }
+    let(:no_match) { { success: true, entries: [], count: 0 } }
+
+    before do
+      allow(actor).to receive(:recent_task_log_texts).and_return(['deploying lex-synapse to nomad'])
+      allow(actor).to receive(:extract_entities).with(text:           'deploying lex-synapse to nomad',
+                                                      entity_types:   anything,
+                                                      min_confidence: anything)
+                                                .and_return({ success: true, entities: entities, source: :llm })
+      allow(actor).to receive(:retrieve_relevant).and_return(no_match)
+      allow(actor).to receive(:publish_entity_ingest)
+    end
+
+    it 'calls publish_entity_ingest for new entities' do
+      actor.scan_and_ingest
+      expect(actor).to have_received(:publish_entity_ingest).once
+    end
+
+    context 'when entity already exists in Apollo (high similarity)' do
+      let(:existing_match) do
+        { success: true, entries: [{ id: 42, content: 'lex-synapse', distance: 0.02 }], count: 1 }
+      end
+
+      before { allow(actor).to receive(:retrieve_relevant).and_return(existing_match) }
+
+      it 'does not publish for duplicate entities' do
+        actor.scan_and_ingest
+        expect(actor).not_to have_received(:publish_entity_ingest)
+      end
+    end
+
+    context 'when LLM extraction returns nothing' do
+      before do
+        allow(actor).to receive(:extract_entities).and_return({ success: true, entities: [], source: :unavailable })
+      end
+
+      it 'does not publish anything' do
+        actor.scan_and_ingest
+        expect(actor).not_to have_received(:publish_entity_ingest)
+      end
+    end
+
+    context 'when data layer is unavailable' do
+      before { allow(actor).to receive(:recent_task_log_texts).and_return([]) }
+
+      it 'returns early without calling extract_entities' do
+        expect(actor).not_to receive(:extract_entities)
+        actor.scan_and_ingest
+      end
+    end
+  end
+
+  describe '#entity_types' do
+    it 'returns the default list when settings are absent' do
+      expect(actor.entity_types).to eq(%w[person service repository concept])
+    end
+  end
+
+  describe '#dedup_similarity_threshold' do
+    it 'returns a float between 0 and 1' do
+      threshold = actor.dedup_similarity_threshold
+      expect(threshold).to be_a(Float)
+      expect(threshold).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#recent_task_log_texts' do
+    context 'when legion-data is not available' do
+      before { hide_const('Legion::Data') if defined?(Legion::Data) }
+
+      it 'returns an empty array' do
+        expect(actor.recent_task_log_texts).to eq([])
+      end
+    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/confidence_spec.rb

@@ -17,8 +17,8 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::Confidence do
       expect(described_class::RETRIEVAL_BOOST).to eq(0.02)
     end
 
-    it 'defines HOURLY_DECAY_FACTOR' do
-      expect(described_class::HOURLY_DECAY_FACTOR).to eq(0.998)
+    it 'defines POWER_LAW_ALPHA' do
+      expect(described_class::POWER_LAW_ALPHA).to eq(0.1)
     end
 
     it 'defines DECAY_THRESHOLD' do
@@ -43,20 +43,28 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::Confidence do
   end
 
   describe '.apply_decay' do
-    it 'multiplies confidence by HOURLY_DECAY_FACTOR' do
+    it 'applies power-law decay with default alpha when no age given' do
       result = described_class.apply_decay(confidence: 1.0)
-      expect(result).to eq(0.998)
+      expected = 1.0 / (1.0 + 0.1) # ~0.909091
+      expect(result).to be_within(0.0001).of(expected)
     end
 
-    it 'accepts a custom factor' do
-      result = described_class.apply_decay(confidence: 1.0, factor: 0.5)
-      expect(result).to eq(0.5)
+    it 'applies age-based power-law decay when age_hours is provided' do
+      result = described_class.apply_decay(confidence: 1.0, age_hours: 10)
+      expect(result).to be > 0.0
+      expect(result).to be < 1.0
     end
 
     it 'clamps to 0.0 minimum' do
-      result = described_class.apply_decay(confidence: 0.001, factor: 0.001)
+      result = described_class.apply_decay(confidence: 0.001)
       expect(result).to be >= 0.0
     end
+
+    it 'accepts a custom alpha' do
+      result = described_class.apply_decay(confidence: 1.0, alpha: 0.5)
+      expected = 1.0 / (1.0 + 0.5) # ~0.6667
+      expect(result).to be_within(0.0001).of(expected)
+    end
   end
 
   describe '.apply_retrieval_boost' do
@@ -81,6 +89,11 @@ RSpec.describe Legion::Extensions::Apollo::Helpers::Confidence do
       result = described_class.apply_corroboration_boost(confidence: 0.9)
       expect(result).to eq(1.0)
     end
+
+    it 'applies half weight for same-source corroboration' do
+      result = described_class.apply_corroboration_boost(confidence: 0.5, weight: 0.5)
+      expect(result).to eq(0.65)
+    end
   end
 
   describe '.decayed?' do

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/decay_cycle_spec.rb

@@ -13,8 +13,9 @@ RSpec.describe 'Apollo Decay Cycle' do
   end
 
   describe '#decay_rate' do
-    it 'returns default rate when settings unavailable' do
-      expect(maintenance.send(:decay_rate)).to eq(0.998)
+    it 'returns power-law derived rate when settings unavailable' do
+      expected = 1.0 / (1.0 + 0.1) # ~0.909091
+      expect(maintenance.send(:decay_rate)).to be_within(0.0001).of(expected)
     end
   end
 

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+require 'legion/extensions/apollo/helpers/confidence'
+require 'legion/extensions/apollo/helpers/similarity'
+require 'legion/extensions/apollo/helpers/graph_query'
+require 'legion/extensions/apollo/runners/entity_extractor'
+
+RSpec.describe Legion::Extensions::Apollo::Runners::EntityExtractor do
+  let(:runner) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  describe '#extract_entities' do
+    context 'when Legion::LLM is not available' do
+      before { hide_const('Legion::LLM') if defined?(Legion::LLM) }
+
+      it 'returns an empty entity list' do
+        result = runner.extract_entities(text: 'Jane works on lex-synapse')
+        expect(result[:success]).to be true
+        expect(result[:entities]).to eq([])
+        expect(result[:source]).to eq(:unavailable)
+      end
+    end
+
+    context 'when Legion::LLM is available' do
+      let(:llm_result) do
+        {
+          data: {
+            entities: [
+              { name: 'lex-synapse', type: 'repository', confidence: 0.9 },
+              { name: 'Jane Doe',    type: 'person',     confidence: 0.8 }
+            ]
+          }
+        }
+      end
+
+      before do
+        stub_const('Legion::LLM', Module.new do
+          def self.started? = true
+
+          def self.structured(**_opts) = { data: { entities: [] } }
+        end)
+        allow(Legion::LLM).to receive(:structured).and_return(llm_result)
+      end
+
+      it 'returns extracted entities' do
+        result = runner.extract_entities(text: 'Jane works on lex-synapse')
+        expect(result[:success]).to be true
+        expect(result[:entities].size).to eq(2)
+        expect(result[:source]).to eq(:llm)
+      end
+
+      it 'filters to configured entity types' do
+        result = runner.extract_entities(
+          text:         'Jane works on lex-synapse',
+          entity_types: ['repository']
+        )
+        expect(result[:entities].all? { |e| e[:type] == 'repository' }).to be true
+      end
+
+      it 'applies minimum confidence filter' do
+        result = runner.extract_entities(
+          text:           'Jane works on lex-synapse',
+          min_confidence: 0.85
+        )
+        expect(result[:entities].size).to eq(1)
+        expect(result[:entities].first[:name]).to eq('lex-synapse')
+      end
+    end
+
+    context 'when LLM raises' do
+      before do
+        stub_const('Legion::LLM', Module.new do
+          def self.started? = true
+
+          def self.structured(**_opts) = raise(StandardError, 'timeout')
+        end)
+      end
+
+      it 'returns success false with error message' do
+        result = runner.extract_entities(text: 'anything')
+        expect(result[:success]).to be false
+        expect(result[:error]).to include('timeout')
+      end
+    end
+
+    context 'with empty text' do
+      it 'returns early with empty list' do
+        result = runner.extract_entities(text: '')
+        expect(result[:success]).to be true
+        expect(result[:entities]).to eq([])
+      end
+
+      it 'handles nil text' do
+        result = runner.extract_entities(text: nil)
+        expect(result[:success]).to be true
+        expect(result[:entities]).to eq([])
+      end
+    end
+  end
+
+  describe '#entity_extraction_prompt' do
+    it 'returns a non-empty string' do
+      prompt = runner.entity_extraction_prompt(
+        text: 'test text', entity_types: %w[person service]
+      )
+      expect(prompt).to be_a(String)
+      expect(prompt).to include('person')
+      expect(prompt).to include('service')
+    end
+  end
+
+  describe '#entity_schema' do
+    it 'returns a JSON Schema hash' do
+      schema = runner.entity_schema
+      expect(schema[:type]).to eq('object')
+      expect(schema[:properties]).to have_key(:entities)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-apollo
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.4
 platform: ruby
 authors:
 - Esity
@@ -50,6 +50,7 @@ files:
 - lib/legion/extensions/apollo.rb
 - lib/legion/extensions/apollo/actors/corroboration_checker.rb
 - 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/ingest.rb
 - lib/legion/extensions/apollo/actors/query_responder.rb
@@ -57,8 +58,10 @@ 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
 - lib/legion/extensions/apollo/runners/expertise.rb
 - lib/legion/extensions/apollo/runners/knowledge.rb
 - lib/legion/extensions/apollo/runners/maintenance.rb
@@ -70,6 +73,7 @@ files:
 - 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/ingest_spec.rb
 - spec/legion/extensions/apollo/client_spec.rb
@@ -77,9 +81,11 @@ 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
+- spec/legion/extensions/apollo/runners/entity_extractor_spec.rb
 - spec/legion/extensions/apollo/runners/expertise_spec.rb
 - spec/legion/extensions/apollo/runners/knowledge_spec.rb
 - spec/legion/extensions/apollo/runners/maintenance_spec.rb