activematrix 0.0.5 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fd68a9263d0fb04aaa3f2d0d3160b26b995e783ebc12fa0cf9d67c0084e3d5b
-  data.tar.gz: b282050de6c58f9c470a19f1f17c44f1d6cba0e60b0ee0907e9dd1f82d1395e7
+  metadata.gz: 91157233aaf3c81b35092f75d78eb3ebab06a9f0d93c40a9b098283cec571add
+  data.tar.gz: f9b0de48655ee41174628f26d6683caca5b35aa4e3e54664d79ae859086fa670
 SHA512:
-  metadata.gz: 6f90166bf9f0e25db87953d2a79bfec7ddf04542ff975ddf15602f00fbcad5b0f909be3652b85c97ee771e3aab8aca79bb2e01226d35a59c79ba1ae338f2a722
-  data.tar.gz: 969d6efbe9f3a65294b983410c3737939dca5cb281fa52f55baaa8de317151126e9cc245b1a693398819053bad8e40c7391157f00a55f3835b98d178cd4fa0e7
+  metadata.gz: 13a5cf30e83f2b665cd52fd110b4d2bf1ae4bb95a41586e8fa8c670c0cc2370c8bfbff16d835aacf4d8b484ea2cd59096fc542b5bc5643d060dbf307c2f00502
+  data.tar.gz: bc74041cc3d86999d9113a6c4e6a273aeef54f6ba3682981b180b5c3006ab7c6bd85f4049461cb908253ae1471a78f62245bddd8f3b099be715548c4761ebc7a

data/README.md

@@ -2,23 +2,31 @@
 
 A Rails-native Matrix SDK for building multi-agent bot systems and real-time communication features. This gem is a fork of the [matrix-sdk](https://github.com/ananace/ruby-matrix-sdk) gem, extensively enhanced with Rails integration, multi-agent architecture, and persistent state management.
 
+## Requirements
+
+- **Ruby 3.4+**
+- **Rails 8.0+**
+- **PostgreSQL 18+** (required for UUIDv7 primary keys)
+
 ## Features
 
-- **Multi-Agent Architecture**: Run multiple bots concurrently with lifecycle management
+- **Multi-Agent Architecture**: Run multiple bots concurrently with async fiber-based lifecycle management
+- **Daemon Binary**: Production-ready `activematrix` daemon with multi-process workers and health probes
 - **Rails Integration**: Deep integration with ActiveRecord, Rails.cache, and Rails.logger
 - **State Machines**: state_machines-powered state management for bot lifecycle
 - **Memory System**: Three-tier memory architecture (agent, conversation, global)
 - **Event Routing**: Intelligent event distribution to appropriate agents
-- **Client Pooling**: Efficient connection management for multiple bots
+- **Client Pooling**: Efficient connection management with async semaphores
 - **Generators**: Rails generators for quick bot creation
 - **Inter-Agent Communication**: Built-in messaging between bots
+- **PostgreSQL 18 Features**: UUIDv7 primary keys, JSONB with GIN indexes
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'activematrix', '~> 0.0.3'
+gem 'activematrix'
 ```
 
 And then execute:
@@ -43,7 +51,7 @@ This creates a bot class in `app/bots/captain_bot.rb`:
 class CaptainBot < ActiveMatrix::Bot::MultiInstanceBase
   set :accept_invites, true
   set :command_prefix, '!'
-  
+
   command :status,
           desc: 'Get system status',
           args: '[component]' do |component = nil|
@@ -56,7 +64,7 @@ class CaptainBot < ActiveMatrix::Bot::MultiInstanceBase
       room.send_notice("All systems operational!")
     end
   end
-  
+
   command :deploy,
           desc: 'Deploy to production',
           args: 'target' do |target|
@@ -64,17 +72,17 @@ class CaptainBot < ActiveMatrix::Bot::MultiInstanceBase
     deployments = conversation_memory.remember(:deployments) { [] }
     deployments << { target: target, time: Time.current }
     conversation_memory[:deployments] = deployments
-    
+
     # Notify other agents
     broadcast_to_agents(:lieutenant, {
       type: 'deployment',
       target: target,
       initiated_by: agent_name
     })
-    
+
     room.send_notice("Deploying to #{target}...")
   end
-  
+
   # Handle inter-agent messages
   def receive_message(data, from:)
     case data[:type]
@@ -90,7 +98,7 @@ end
 
 ```ruby
 # Create agent records in Rails console or seeds
-captain = MatrixAgent.create!(
+captain = ActiveMatrix::Agent.create!(
   name: 'captain',
   homeserver: 'https://matrix.org',
   username: 'captain_bot',
@@ -102,8 +110,8 @@ captain = MatrixAgent.create!(
   }
 )
 
-lieutenant = MatrixAgent.create!(
-  name: 'lieutenant', 
+lieutenant = ActiveMatrix::Agent.create!(
+  name: 'lieutenant',
   homeserver: 'https://matrix.org',
   username: 'lieutenant_bot',
   password: 'secure_password',
@@ -111,10 +119,47 @@ lieutenant = MatrixAgent.create!(
 )
 ```
 
-### Managing Agents
+### Running the Daemon
+
+The `activematrix` binary manages your bots in production, similar to Sidekiq or GoodJob:
+
+```bash
+# Start in foreground
+bundle exec activematrix start
+
+# Start with multiple worker processes
+bundle exec activematrix start --workers 3
+
+# Start specific agents only
+bundle exec activematrix start --agents captain,lieutenant
+
+# Daemonize with PID file
+bundle exec activematrix start --daemon --pidfile tmp/pids/activematrix.pid
+
+# Check status (queries health probe)
+bundle exec activematrix status
+
+# Graceful shutdown
+bundle exec activematrix stop
+
+# Reload agent configuration
+bundle exec activematrix reload
+```
+
+**Health Probes** (for Kubernetes/Docker):
+- `GET /health` - Returns 200 if healthy
+- `GET /status` - JSON with detailed agent status
+- `GET /metrics` - Prometheus-compatible metrics
+
+```bash
+curl http://localhost:3042/health
+curl http://localhost:3042/status
+```
+
+### Programmatic Agent Management
 
 ```ruby
-# Start all agents
+# Start all agents (blocks until shutdown)
 ActiveMatrix::AgentManager.instance.start_all
 
 # Start specific agent
@@ -156,7 +201,7 @@ recent = conversation_memory.recent_messages(5)
 ### Global Memory (Shared)
 ```ruby
 # Set global data
-global_memory.set('system_status', 'operational', 
+global_memory.set('system_status', 'operational',
   category: 'monitoring',
   expires_in: 5.minutes,
   public_read: true
@@ -180,7 +225,7 @@ class MonitorBot < ActiveMatrix::Bot::MultiInstanceBase
   route event_type: 'm.room.message', priority: 100 do |bot, event|
     # Custom processing
   end
-  
+
   route room_id: '!monitoring:matrix.org' do |bot, event|
     # Handle all events from monitoring room
   end
@@ -205,26 +250,40 @@ room.send_text "Hello from ActiveMatrix!"
 ```ruby
 # config/initializers/active_matrix.rb
 ActiveMatrix.configure do |config|
+  # Agent settings
   config.agent_startup_delay = 2.seconds
   config.max_agents_per_process = 10
   config.agent_health_check_interval = 30.seconds
+
+  # Memory settings
   config.conversation_history_limit = 20
   config.conversation_stale_after = 1.day
   config.memory_cleanup_interval = 1.hour
+
+  # Daemon settings
+  config.daemon_workers = 2
+  config.probe_port = 3042
+  config.probe_host = '0.0.0.0'
+  config.shutdown_timeout = 30
 end
 ```
 
 ## Testing
 
 ```ruby
-# spec/bots/captain_bot_spec.rb
-RSpec.describe CaptainBot do
-  let(:agent) { create(:matrix_agent, bot_class: 'CaptainBot') }
-  let(:bot) { described_class.new(agent) }
-  
-  it 'responds to status command' do
-    expect(room).to receive(:send_notice).with(/operational/)
-    bot.status
+# test/bots/captain_bot_test.rb
+class CaptainBotTest < ActiveSupport::TestCase
+  def setup
+    @agent = ActiveMatrix::Agent.create!(
+      name: 'test_captain',
+      homeserver: 'https://matrix.org',
+      username: 'test_bot',
+      bot_class: 'CaptainBot'
+    )
+  end
+
+  test 'responds to status command' do
+    # Your test logic here
   end
 end
 ```
@@ -233,16 +292,25 @@ end
 
 ActiveMatrix implements a sophisticated multi-agent architecture:
 
-- **AgentManager**: Manages lifecycle of all bots (start/stop/restart)
-- **AgentRegistry**: Thread-safe registry of running bot instances  
-- **EventRouter**: Routes Matrix events to appropriate bots
-- **ClientPool**: Manages shared client connections efficiently
+- **AgentManager**: Manages lifecycle of all bots using async fibers (start/stop/restart)
+- **AgentRegistry**: Fiber-safe registry of running bot instances
+- **EventRouter**: Routes Matrix events to appropriate bots via async queues
+- **ClientPool**: Manages shared client connections with async semaphores
 - **Memory System**: Hierarchical storage with caching
 - **State Machines**: Track agent states (offline/connecting/online/busy/error)
 
+### Models
+
+All models are namespaced under `ActiveMatrix::`:
+
+- `ActiveMatrix::Agent` - Bot agent records with state machine
+- `ActiveMatrix::AgentStore` - Per-agent key-value storage
+- `ActiveMatrix::ChatSession` - Conversation context per user/room
+- `ActiveMatrix::KnowledgeBase` - Global shared storage
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/agent_smith
+Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/activematrix
 
 ## License
 

data/app/jobs/active_matrix/application_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  class ApplicationJob < ActiveJob::Base
+    # Automatically retry jobs that encountered a deadlock
+    # retry_on ActiveRecord::Deadlocked
+
+    # Most jobs are safe to ignore if the underlying records are no longer available
+    # discard_on ActiveJob::DeserializationError
+  end
+end

data/app/models/active_matrix/agent/jobs/memory_reaper.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  class Agent < ApplicationRecord
+    module Jobs
+      # Background job responsible for harvesting dead agent memories from the system.
+      #
+      # This job systematically harvests dead memory entries to prevent database bloat
+      # and maintain optimal performance. It operates as a scheduled reaper process
+      # that runs automatically when agent memories reach their expiration time.
+      #
+      # The job performs the following operations:
+      # 1. Identifies dead agent memory records based on their expires_at timestamp
+      # 2. Harvests dead entries from both database and cache layers
+      # 3. Logs harvesting statistics for monitoring and debugging purposes
+      # 4. Handles harvesting failures gracefully without affecting system stability
+      #
+      # Usage:
+      #   # Schedule immediate harvesting
+      #   ActiveMatrix::Agent::Jobs::MemoryReaper.perform_later
+      #
+      #   # Schedule harvesting for specific time
+      #   ActiveMatrix::Agent::Jobs::MemoryReaper.set(wait_until: 1.hour.from_now).perform_later
+      #
+      class MemoryReaper < ActiveMatrix::ApplicationJob
+        queue_as :maintenance
+
+        # Performs the memory reaping operation with comprehensive error handling
+        def perform
+          ActiveMatrix.logger.info 'Starting agent memory reaping operation'
+
+          reaping_stats = {
+            agent_memories_reaped: 0,
+            cache_entries_cleared: 0,
+            errors_encountered: 0
+          }
+
+          begin
+            # Harvest dead agent memories
+            reaping_stats[:agent_memories_reaped] = harvest_dead_agent_memories
+
+            # Clear associated cache entries
+            reaping_stats[:cache_entries_cleared] = clear_expired_cache_entries
+
+            ActiveMatrix.logger.info "Memory reaping completed successfully: #{reaping_stats}"
+          rescue StandardError => e
+            reaping_stats[:errors_encountered] += 1
+            ActiveMatrix.logger.error "Memory reaping failed: #{e.message}"
+            ActiveMatrix.logger.error e.backtrace.join("\n")
+
+            # Re-raise to ensure job is marked as failed for retry
+            raise e
+          end
+
+          reaping_stats
+        end
+
+        private
+
+        # Harvests dead agent memory records from the database
+        # Returns the number of records harvested
+        def harvest_dead_agent_memories
+          return 0 unless defined?(ActiveMatrix::AgentStore)
+
+          dead_memories = ActiveMatrix::AgentStore.expired
+          count = dead_memories.count
+
+          if count.positive?
+            ActiveMatrix.logger.debug "Harvesting #{count} dead agent memory records"
+            dead_memories.destroy_all
+          end
+
+          count
+        end
+
+        # Clears expired memory entries from the Rails cache
+        # Returns the number of cache entries cleared
+        def clear_expired_cache_entries
+          # NOTE: Rails.cache doesn't provide a direct way to clear expired entries
+          # This is a placeholder for cache-specific cleanup logic if needed
+          # Most cache stores handle expiration automatically
+          0
+        end
+      end
+    end
+  end
+end

data/app/models/active_matrix/agent.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'bcrypt'
+
+# <rails-lens:schema:begin>
+# table = "active_matrix_agents"
+# database_dialect = "PostgreSQL"
+#
+# columns = [
+#   { name = "id", type = "integer", pk = true, null = false },
+#   { name = "name", type = "string", null = false },
+#   { name = "homeserver", type = "string", null = false },
+#   { name = "username", type = "string", null = false },
+#   { name = "bot_class", type = "string", null = false },
+#   { name = "state", type = "string", null = false, default = "offline" },
+#   { name = "access_token", type = "string" },
+#   { name = "encrypted_password", type = "string" },
+#   { name = "settings", type = "json" },
+#   { name = "last_sync_token", type = "string" },
+#   { name = "last_active_at", type = "datetime" },
+#   { name = "messages_handled", type = "integer", null = false, default = "0" },
+#   { name = "created_at", type = "datetime", null = false },
+#   { name = "updated_at", type = "datetime", null = false }
+# ]
+#
+# indexes = [
+#   { name = "index_active_matrix_agents_on_homeserver", columns = ["homeserver"] },
+#   { name = "index_active_matrix_agents_on_name", columns = ["name"], unique = true },
+#   { name = "index_active_matrix_agents_on_state", columns = ["state"] }
+# ]
+#
+# [callbacks]
+# before_save = [{ method = "encrypt_password", if = ["password_changed?"] }]
+# around_validation = [{ method = "machine" }]
+#
+# notes = ["agent_stores:INVERSE_OF", "chat_sessions:INVERSE_OF", "agent_stores:N_PLUS_ONE", "chat_sessions:N_PLUS_ONE", "access_token:NOT_NULL", "encrypted_password:NOT_NULL", "settings:NOT_NULL", "name:LIMIT", "homeserver:LIMIT", "username:LIMIT", "bot_class:LIMIT", "state:LIMIT", "access_token:LIMIT", "encrypted_password:LIMIT", "last_sync_token:LIMIT", "username:INDEX", "access_token:INDEX", "last_sync_token:INDEX"]
+# <rails-lens:schema:end>
+module ActiveMatrix
+  class Agent < ApplicationRecord
+    self.table_name = 'active_matrix_agents'
+
+    # Associations
+    has_many :agent_stores, class_name: 'ActiveMatrix::AgentStore', dependent: :destroy
+    has_many :chat_sessions, class_name: 'ActiveMatrix::ChatSession', dependent: :destroy
+
+    # Validations
+    validates :name, presence: true, uniqueness: true
+    validates :homeserver, presence: true
+    validates :username, presence: true
+    validates :bot_class, presence: true
+    validate :valid_bot_class?
+
+    # Scopes
+    scope :active, -> { where.not(state: %i[offline error]) }
+    scope :online, -> { where(state: %i[online_idle online_busy]) }
+    scope :offline, -> { where(state: :offline) }
+
+    # Encrypts password before saving
+    before_save :encrypt_password, if: :password_changed?
+
+    # State machine for agent lifecycle
+    state_machine :state, initial: :offline do
+      state :offline
+      state :connecting
+      state :online_idle
+      state :online_busy
+      state :error
+      state :paused
+
+      event :connect do
+        transition %i[offline error paused] => :connecting
+      end
+
+      event :connection_established do
+        transition connecting: :online_idle
+      end
+
+      after_transition to: :online_idle do |agent|
+        agent.update_column(:last_active_at, Time.current)
+      end
+
+      event :start_processing do
+        transition online_idle: :online_busy
+      end
+
+      event :finish_processing do
+        transition online_busy: :online_idle
+      end
+
+      event :disconnect do
+        transition %i[connecting online_idle online_busy] => :offline
+      end
+
+      event :encounter_error do
+        transition any => :error
+      end
+
+      event :pause do
+        transition %i[online_idle online_busy] => :paused
+      end
+
+      event :resume do
+        transition paused: :connecting
+      end
+    end
+
+    # Instance methods
+    def bot_instance
+      @bot_instance ||= bot_class.constantize.new(client) if running?
+    end
+
+    def client
+      @client ||= if access_token.present?
+                    ActiveMatrix::Client.new(homeserver, access_token: access_token)
+                  else
+                    ActiveMatrix::Client.new(homeserver)
+                  end
+    end
+
+    def running?
+      %i[online_idle online_busy].include?(state.to_sym)
+    end
+
+    def memory
+      @memory ||= ActiveMatrix::Memory::AgentMemory.new(self)
+    end
+
+    def increment_messages_handled!
+      update!(messages_handled: messages_handled + 1)
+    end
+
+    def update_activity!
+      update(last_active_at: Time.current)
+    end
+
+    # Password handling
+    attr_accessor :password
+
+    def authenticate(password)
+      return false if encrypted_password.blank?
+
+      BCrypt::Password.new(encrypted_password) == password
+    end
+
+    private
+
+    def password_changed?
+      password.present?
+    end
+
+    def encrypt_password
+      self.encrypted_password = BCrypt::Password.create(password) if password.present?
+    end
+
+    def valid_bot_class?
+      return false if bot_class.blank?
+
+      begin
+        klass = bot_class.constantize
+        errors.add(:bot_class, 'must inherit from ActiveMatrix::Bot::Base') unless klass < ActiveMatrix::Bot::Base
+      rescue NameError
+        errors.add(:bot_class, 'must be a valid class name')
+      end
+    end
+  end
+end

data/app/models/active_matrix/agent_store.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# <rails-lens:schema:begin>
+# table = "active_matrix_agent_stores"
+# database_dialect = "PostgreSQL"
+#
+# columns = [
+#   { name = "id", type = "integer", pk = true, null = false },
+#   { name = "agent_id", type = "integer", null = false },
+#   { name = "key", type = "string", null = false },
+#   { name = "value", type = "json" },
+#   { name = "expires_at", type = "datetime" },
+#   { name = "created_at", type = "datetime", null = false },
+#   { name = "updated_at", type = "datetime", null = false }
+# ]
+#
+# indexes = [
+#   { name = "index_active_matrix_agent_stores_on_agent_id", columns = ["agent_id"] },
+#   { name = "index_active_matrix_agent_stores_on_agent_id_and_key", columns = ["agent_id", "key"], unique = true },
+#   { name = "index_active_matrix_agent_stores_on_expires_at", columns = ["expires_at"] }
+# ]
+#
+# foreign_keys = [
+#   { column = "agent_id", references_table = "active_matrix_agents", references_column = "id", name = "fk_rails_59b3dc556f" }
+# ]
+#
+# [callbacks]
+# after_commit = [{ method = "schedule_cleanup", if = ["expires_at?"] }]
+#
+# notes = ["agent:INVERSE_OF", "value:NOT_NULL", "key:LIMIT"]
+# <rails-lens:schema:end>
+module ActiveMatrix
+  class AgentStore < ApplicationRecord
+    self.table_name = 'active_matrix_agent_stores'
+
+    belongs_to :agent, class_name: 'ActiveMatrix::Agent'
+
+    validates :key, presence: true, uniqueness: { scope: :agent_id }
+
+    scope :active, -> { where('expires_at IS NULL OR expires_at > ?', Time.current) }
+    scope :expired, -> { where(expires_at: ..Time.current) }
+
+    # Automatically clean up expired memories
+    after_commit :schedule_cleanup, if: :expires_at?
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    def ttl=(seconds)
+      self.expires_at = seconds.present? ? Time.current + seconds : nil
+    end
+
+    def ttl
+      return nil if expires_at.blank?
+
+      remaining = expires_at - Time.current
+      [remaining, 0].max
+    end
+
+    # Cache integration
+    def cache_key
+      "agent_memory/#{agent_id}/#{key}"
+    end
+
+    def write_to_cache
+      Rails.cache.write(cache_key, value, expires_in: ttl)
+    end
+
+    def self.cleanup_expired!
+      expired.destroy_all
+    end
+
+    private
+
+    def schedule_cleanup
+      ActiveMatrix::Agent::Jobs::MemoryReaper.set(wait_until: expires_at).perform_later if defined?(ActiveMatrix::Agent::Jobs::MemoryReaper)
+    end
+  end
+end

data/app/models/active_matrix/application_record.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# <rails-lens:schema:begin>
+# connection = "primary"
+# database_dialect = "SQLite"
+# database_version = "3.50.4"
+#
+# # This is an abstract class that establishes a database connection
+# # but does not have an associated table.
+# <rails-lens:schema:end>
+module ActiveMatrix
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end