lex-apollo 0.2.0

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

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../helpers/confidence'
+require_relative '../helpers/embedding'
+
+module Legion
+  module Extensions
+    module Apollo
+      module Runners
+        module Knowledge
+          def store_knowledge(content:, content_type:, tags: [], source_agent: nil, context: {}, **)
+            content_type = content_type.to_sym
+            unless Helpers::Confidence::CONTENT_TYPES.include?(content_type)
+              raise ArgumentError, "invalid content_type: #{content_type}. Must be one of #{Helpers::Confidence::CONTENT_TYPES}"
+            end
+
+            {
+              action:       :store,
+              content:      content,
+              content_type: content_type,
+              tags:         Array(tags),
+              source_agent: source_agent,
+              context:      context
+            }
+          end
+
+          def query_knowledge(query:, limit: 10, min_confidence: 0.3, status: [:confirmed], tags: nil, **)
+            {
+              action:         :query,
+              query:          query,
+              limit:          limit,
+              min_confidence: min_confidence,
+              status:         Array(status),
+              tags:           tags
+            }
+          end
+
+          def related_entries(entry_id:, relation_types: nil, depth: 2, **)
+            {
+              action:         :traverse,
+              entry_id:       entry_id,
+              relation_types: relation_types,
+              depth:          depth
+            }
+          end
+
+          def deprecate_entry(entry_id:, reason:, **)
+            {
+              action:   :deprecate,
+              entry_id: entry_id,
+              reason:   reason
+            }
+          end
+
+          def handle_ingest(content:, content_type:, tags: [], source_agent: 'unknown', context: {}, **)
+            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+
+            embedding = Helpers::Embedding.generate(text: content)
+            content_type_sym = content_type.to_s
+            tag_array = Array(tags)
+
+            corroborated, existing_id = find_corroboration(embedding, content_type_sym, source_agent)
+
+            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")
+              )
+              existing_id = new_entry.id
+            end
+
+            upsert_expertise(source_agent: source_agent, domain: tag_array.first || 'general')
+
+            Legion::Data::Model::ApolloAccessLog.create(
+              entry_id: existing_id, agent_id: source_agent, action: 'ingest'
+            )
+
+            { success: true, entry_id: existing_id, status: corroborated ? 'corroborated' : 'candidate',
+              corroborated: corroborated }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          def handle_query(query:, limit: 10, min_confidence: 0.3, status: [:confirmed], tags: nil, agent_id: 'unknown', **) # rubocop:disable Metrics/ParameterLists
+            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+
+            embedding = Helpers::Embedding.generate(text: query)
+            sql = Helpers::GraphQuery.build_semantic_search_sql(
+              limit: limit, min_confidence: min_confidence,
+              statuses: Array(status).map(&:to_s), tags: tags
+            )
+
+            db = Legion::Data::Model::ApolloEntry.db
+            entries = db.fetch(sql, embedding: Sequel.lit("'[#{embedding.join(',')}]'::vector")).all
+
+            entries.each do |entry|
+              Legion::Data::Model::ApolloEntry.where(id: entry[:id]).update(
+                access_count: Sequel.expr(:access_count) + 1,
+                confidence:   Helpers::Confidence.apply_retrieval_boost(
+                  confidence: entry[:confidence]
+                ),
+                updated_at:   Time.now
+              )
+            end
+
+            if entries.any?
+              Legion::Data::Model::ApolloAccessLog.create(
+                entry_id: entries.first&.dig(:id), agent_id: agent_id, action: 'query'
+              )
+            end
+
+            formatted = entries.map do |entry|
+              { id: entry[:id], content: entry[:content], content_type: entry[:content_type],
+                confidence: entry[:confidence], distance: entry[:distance],
+                tags: entry[:tags], source_agent: entry[:source_agent] }
+            end
+
+            { success: true, entries: formatted, count: formatted.size }
+          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
+
+            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+
+            return { success: true, entries: [], count: 0 } if query.nil? || query.to_s.strip.empty?
+
+            embedding = Helpers::Embedding.generate(text: query.to_s)
+            sql = Helpers::GraphQuery.build_semantic_search_sql(
+              limit: limit, min_confidence: min_confidence,
+              statuses: ['confirmed'], tags: tags
+            )
+
+            db = Legion::Data::Model::ApolloEntry.db
+            entries = db.fetch(sql, embedding: Sequel.lit("'[#{embedding.join(',')}]'::vector")).all
+
+            entries.each do |entry|
+              Legion::Data::Model::ApolloEntry.where(id: entry[:id]).update(
+                confidence: Helpers::Confidence.apply_retrieval_boost(confidence: entry[:confidence]),
+                updated_at: Time.now
+              )
+            end
+
+            formatted = entries.map do |entry|
+              { id: entry[:id], content: entry[:content], content_type: entry[:content_type],
+                confidence: entry[:confidence], distance: entry[:distance],
+                tags: entry[:tags], source_agent: entry[:source_agent] }
+            end
+
+            { success: true, entries: formatted, count: formatted.size }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def find_corroboration(embedding, content_type_sym, source_agent)
+            existing = Legion::Data::Model::ApolloEntry
+                       .where(content_type: content_type_sym)
+                       .exclude(embedding: nil)
+                       .limit(50)
+
+            existing.each do |entry|
+              next unless entry.embedding
+
+              sim = Helpers::Similarity.cosine_similarity(vec_a: embedding, vec_b: entry.embedding)
+              next unless Helpers::Similarity.above_corroboration_threshold?(similarity: sim)
+
+              entry.update(
+                confidence: Helpers::Confidence.apply_corroboration_boost(confidence: entry.confidence),
+                updated_at: Time.now
+              )
+              Legion::Data::Model::ApolloRelation.create(
+                from_entry_id: entry.id,
+                to_entry_id:   entry.id,
+                relation_type: 'similar_to',
+                source_agent:  source_agent,
+                weight:        sim
+              )
+              return [true, entry.id]
+            end
+
+            [false, nil]
+          end
+
+          def upsert_expertise(source_agent:, domain:)
+            expertise = Legion::Data::Model::ApolloExpertise
+                        .where(agent_id: source_agent, domain: domain).first
+            if expertise
+              expertise.update(entry_count: expertise.entry_count + 1, last_active_at: Time.now)
+            else
+              Legion::Data::Model::ApolloExpertise.create(
+                agent_id: source_agent, domain: domain, proficiency: 0.0,
+                entry_count: 1, last_active_at: Time.now
+              )
+            end
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/confidence'
+require_relative '../helpers/similarity'
+require_relative '../helpers/embedding'
+
+module Legion
+  module Extensions
+    module Apollo
+      module Runners
+        module Maintenance
+          def force_decay(factor: 0.5, **)
+            { action: :force_decay, factor: factor }
+          end
+
+          def archive_stale(days: 90, **)
+            { action: :archive_stale, days: days }
+          end
+
+          def resolve_dispute(entry_id:, resolution:, **)
+            { action: :resolve_dispute, entry_id: entry_id, resolution: resolution }
+          end
+
+          def check_corroboration(**)
+            return { success: false, error: 'apollo_data_not_available' } unless defined?(Legion::Data::Model::ApolloEntry)
+
+            candidates = Legion::Data::Model::ApolloEntry.where(status: 'candidate').exclude(embedding: nil).all
+            confirmed = Legion::Data::Model::ApolloEntry.where(status: 'confirmed').exclude(embedding: nil).all
+
+            promoted = 0
+
+            candidates.each do |candidate|
+              match = confirmed.find do |conf|
+                next unless conf.content_type == candidate.content_type
+
+                sim = Helpers::Similarity.cosine_similarity(
+                  vec_a: candidate.embedding, vec_b: conf.embedding
+                )
+                Helpers::Similarity.above_corroboration_threshold?(similarity: sim)
+              end
+
+              next unless match
+
+              candidate.update(
+                status:       'confirmed',
+                confirmed_at: Time.now,
+                confidence:   Helpers::Confidence.apply_corroboration_boost(confidence: candidate.confidence),
+                updated_at:   Time.now
+              )
+
+              Legion::Data::Model::ApolloRelation.create(
+                from_entry_id: candidate.id,
+                to_entry_id:   match.id,
+                relation_type: 'similar_to',
+                source_agent:  'system:corroboration',
+                weight:        1.0
+              )
+
+              promoted += 1
+            end
+
+            { success: true, promoted: promoted, scanned: candidates.size }
+          rescue Sequel::Error => e
+            { success: false, error: e.message }
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/transport/exchanges/apollo.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/transport/exchange' if defined?(Legion::Transport)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Transport
+        module Exchanges
+          class Apollo < Legion::Transport::Exchange
+            def exchange_name
+              'apollo'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/transport/messages/ingest.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'legion/transport/message' if defined?(Legion::Transport)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Transport
+        module Messages
+          class Ingest < Legion::Transport::Message
+            def exchange
+              Exchanges::Apollo
+            end
+
+            def routing_key
+              'apollo.ingest'
+            end
+
+            def message
+              {
+                content:      @options[:content],
+                content_type: @options[:content_type],
+                tags:         @options[:tags],
+                source_agent: @options[:source_agent],
+                context:      @options[:context] || {}
+              }
+            end
+
+            def type
+              'apollo_ingest'
+            end
+
+            def validate
+              raise TypeError, 'content is required' unless @options[:content].is_a?(String)
+
+              @valid = true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/transport/messages/query.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'legion/transport/message' if defined?(Legion::Transport)
+
+module Legion
+  module Extensions
+    module Apollo
+      module Transport
+        module Messages
+          class Query < Legion::Transport::Message
+            def exchange
+              Exchanges::Apollo
+            end
+
+            def routing_key
+              'apollo.query'
+            end
+
+            def message
+              {
+                action:         @options[:action],
+                query:          @options[:query],
+                entry_id:       @options[:entry_id],
+                limit:          @options[:limit],
+                min_confidence: @options[:min_confidence],
+                status:         @options[:status],
+                tags:           @options[:tags],
+                relation_types: @options[:relation_types],
+                depth:          @options[:depth],
+                reply_to:       @options[:reply_to],
+                correlation_id: @options[:correlation_id]
+              }.compact
+            end
+
+            def type
+              'apollo_query'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/apollo/transport/queues/ingest.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 Ingest < Legion::Transport::Queue
+            def queue_name
+              'apollo.ingest'
+            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/transport/queues/query.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 Query < Legion::Transport::Queue
+            def queue_name
+              'apollo.query'
+            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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Apollo
+      VERSION = '0.2.0'
+    end
+  end
+end

data/lib/legion/extensions/apollo.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/apollo/version'
+require 'legion/extensions/apollo/helpers/confidence'
+require 'legion/extensions/apollo/helpers/similarity'
+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'
+
+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/messages/ingest'
+  require 'legion/extensions/apollo/transport/messages/query'
+end
+
+module Legion
+  module Extensions
+    module Apollo
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Every)
+  module Legion
+    module Extensions
+      module Actors
+        class Every; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+$LOADED_FEATURES << 'legion/extensions/actors/every' unless $LOADED_FEATURES.include?('legion/extensions/actors/every')
+
+require 'legion/extensions/apollo/runners/maintenance'
+require 'legion/extensions/apollo/actors/decay'
+
+RSpec.describe Legion::Extensions::Apollo::Actor::Decay do
+  subject(:actor) { described_class.new }
+
+  it 'uses Maintenance runner_class' do
+    expect(actor.runner_class).to eq(Legion::Extensions::Apollo::Runners::Maintenance)
+  end
+
+  it 'runs force_decay function' do
+    expect(actor.runner_function).to eq('force_decay')
+  end
+
+  it 'runs every 3600 seconds' do
+    expect(actor.time).to eq(3600)
+  end
+
+  it 'does not run immediately' do
+    expect(actor.run_now?).to be false
+  end
+
+  it 'does not use runner framework' do
+    expect(actor.use_runner?).to be false
+  end
+
+  it 'does not generate tasks' do
+    expect(actor.generate_task?).to be false
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Every)
+  module Legion
+    module Extensions
+      module Actors
+        class Every; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+$LOADED_FEATURES << 'legion/extensions/actors/every' unless $LOADED_FEATURES.include?('legion/extensions/actors/every')
+
+require 'legion/extensions/apollo/runners/expertise'
+require 'legion/extensions/apollo/actors/expertise_aggregator'
+
+RSpec.describe Legion::Extensions::Apollo::Actor::ExpertiseAggregator do
+  subject(:actor) { described_class.new }
+
+  it 'uses Expertise runner_class' do
+    expect(actor.runner_class).to eq(Legion::Extensions::Apollo::Runners::Expertise)
+  end
+
+  it 'runs aggregate function' do
+    expect(actor.runner_function).to eq('aggregate')
+  end
+
+  it 'runs every 1800 seconds' do
+    expect(actor.time).to eq(1800)
+  end
+
+  it 'does not run immediately' do
+    expect(actor.run_now?).to be false
+  end
+
+  it 'does not generate tasks' do
+    expect(actor.generate_task?).to be false
+  end
+end

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

@@ -0,0 +1,33 @@
+# 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/knowledge'
+require 'legion/extensions/apollo/actors/ingest'
+
+RSpec.describe Legion::Extensions::Apollo::Actor::Ingest do
+  subject(:actor) { described_class.new }
+
+  it 'uses Knowledge runner_class as string' do
+    expect(actor.runner_class).to eq('Legion::Extensions::Apollo::Runners::Knowledge')
+  end
+
+  it 'runs handle_ingest function' do
+    expect(actor.runner_function).to eq('handle_ingest')
+  end
+
+  it 'does not generate tasks' do
+    expect(actor.generate_task?).to be false
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/apollo/client'
+
+RSpec.describe Legion::Extensions::Apollo::Client do
+  let(:client) { described_class.new(agent_id: 'test-agent') }
+
+  describe '#initialize' do
+    it 'stores agent_id' do
+      expect(client.agent_id).to eq('test-agent')
+    end
+
+    it 'defaults agent_id to unknown' do
+      c = described_class.new
+      expect(c.agent_id).to eq('unknown')
+    end
+  end
+
+  describe 'Knowledge runner' do
+    it 'responds to store_knowledge' do
+      expect(client).to respond_to(:store_knowledge)
+    end
+
+    it 'injects source_agent from client agent_id' do
+      result = client.store_knowledge(content: 'test fact', content_type: :fact)
+      expect(result[:source_agent]).to eq('test-agent')
+    end
+
+    it 'allows source_agent override' do
+      result = client.store_knowledge(content: 'test', content_type: :fact, source_agent: 'other')
+      expect(result[:source_agent]).to eq('other')
+    end
+
+    it 'responds to query_knowledge' do
+      expect(client).to respond_to(:query_knowledge)
+    end
+
+    it 'responds to related_entries' do
+      expect(client).to respond_to(:related_entries)
+    end
+
+    it 'responds to deprecate_entry' do
+      expect(client).to respond_to(:deprecate_entry)
+    end
+  end
+
+  describe 'Expertise runner' do
+    it 'responds to get_expertise' do
+      expect(client).to respond_to(:get_expertise)
+    end
+
+    it 'responds to domains_at_risk' do
+      expect(client).to respond_to(:domains_at_risk)
+    end
+
+    it 'responds to agent_profile' do
+      expect(client).to respond_to(:agent_profile)
+    end
+  end
+
+  describe 'Maintenance runner' do
+    it 'responds to force_decay' do
+      expect(client).to respond_to(:force_decay)
+    end
+
+    it 'responds to archive_stale' do
+      expect(client).to respond_to(:archive_stale)
+    end
+
+    it 'responds to resolve_dispute' do
+      expect(client).to respond_to(:resolve_dispute)
+    end
+  end
+end