activematrix 0.0.5 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fd68a9263d0fb04aaa3f2d0d3160b26b995e783ebc12fa0cf9d67c0084e3d5b
-  data.tar.gz: b282050de6c58f9c470a19f1f17c44f1d6cba0e60b0ee0907e9dd1f82d1395e7
+  metadata.gz: 9bf1ad81648f055b2fdb10da688c66ac7267456cea155b0d76bb41864ae6bab5
+  data.tar.gz: 282f29e6c278cc4ee5b721039e1ec36c2a48b03ba115e02e9beb017b45211706
 SHA512:
-  metadata.gz: 6f90166bf9f0e25db87953d2a79bfec7ddf04542ff975ddf15602f00fbcad5b0f909be3652b85c97ee771e3aab8aca79bb2e01226d35a59c79ba1ae338f2a722
-  data.tar.gz: 969d6efbe9f3a65294b983410c3737939dca5cb281fa52f55baaa8de317151126e9cc245b1a693398819053bad8e40c7391157f00a55f3835b98d178cd4fa0e7
+  metadata.gz: '08aedb897355151e41f5db2b169d58d0b2842b0c5b7c51a596708ab8ce60be886cb99550f7bb7dfdbf1e71fae918014489d4c48d4271077b930765f6513e28b6'
+  data.tar.gz: b6a3e216fecc58cf8416bc84980c7e5c17edff2b971a2707ee9f82740c69518b60a77880440522765f4befc8a1fc2fc7bb81df39e8fc120c7ddc4451c4368908

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,131 @@
+# frozen_string_literal: true
+
+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(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,51 @@
+# frozen_string_literal: true
+
+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,7 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/active_matrix/chat_session.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  class ChatSession < ApplicationRecord
+    self.table_name = 'active_matrix_chat_sessions'
+
+    belongs_to :agent, class_name: 'ActiveMatrix::Agent'
+
+    validates :user_id, presence: true
+    validates :room_id, presence: true
+    validates :user_id, uniqueness: { scope: %i[agent_id room_id] }
+
+    # Configuration
+    MAX_HISTORY_SIZE = 20
+
+    # Scopes
+    scope :recent, -> { order(last_message_at: :desc) }
+    scope :active, -> { where('last_message_at > ?', 1.hour.ago) }
+    scope :stale, -> { where(last_message_at: ...1.day.ago) }
+
+    # Add a message to the history
+    def add_message(message_data)
+      messages = message_history['messages'] || []
+
+      # Add new message
+      messages << {
+        'event_id' => message_data[:event_id],
+        'sender' => message_data[:sender],
+        'content' => message_data[:content],
+        'timestamp' => message_data[:timestamp] || Time.current.to_i
+      }
+
+      # Keep only recent messages
+      messages = messages.last(MAX_HISTORY_SIZE)
+
+      # Update record
+      self.message_history = { 'messages' => messages }
+      self.last_message_at = Time.current
+      self.message_count = messages.size
+      save!
+
+      # Update cache
+      write_to_cache
+    end
+
+    # Get recent messages
+    def recent_messages(limit = 10)
+      messages = message_history['messages'] || []
+      messages.last(limit)
+    end
+
+    # Clear old messages but keep context
+    def prune_history!
+      messages = message_history['messages'] || []
+      self.message_history = { 'messages' => messages.last(5) }
+      save!
+    end
+
+    # Cache integration
+    def cache_key
+      "conversation/#{agent_id}/#{user_id}/#{room_id}"
+    end
+
+    def write_to_cache
+      Rails.cache.write(cache_key, {
+                          context: context,
+                          recent_messages: recent_messages,
+                          last_message_at: last_message_at
+                        }, expires_in: 1.hour)
+    end
+
+    def self.cleanup_stale!
+      stale.destroy_all
+    end
+  end
+end

data/app/models/active_matrix/knowledge_base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  class KnowledgeBase < ApplicationRecord
+    self.table_name = 'active_matrix_knowledge_bases'
+
+    validates :key, presence: true, uniqueness: true
+
+    scope :active, -> { where('expires_at IS NULL OR expires_at > ?', Time.current) }
+    scope :expired, -> { where(expires_at: ..Time.current) }
+    scope :by_category, ->(category) { where(category: category) }
+    scope :readable, -> { where(public_read: true) }
+    scope :writable, -> { where(public_write: true) }
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    def readable_by?(agent)
+      public_read || (agent.is_a?(ActiveMatrix::Agent) && agent.admin?)
+    end
+
+    def writable_by?(agent)
+      public_write || (agent.is_a?(ActiveMatrix::Agent) && agent.admin?)
+    end
+
+    # Cache integration
+    def cache_key
+      "global/#{key}"
+    end
+
+    def write_to_cache
+      return unless active?
+
+      ttl = expires_at.present? ? expires_at - Time.current : nil
+      Rails.cache.write(cache_key, value, expires_in: ttl)
+    end
+
+    def self.get(key)
+      # Try cache first
+      cached = Rails.cache.read("global/#{key}")
+      return cached if cached.present?
+
+      # Fallback to database
+      memory = find_by(key: key)
+      return unless memory&.active?
+
+      memory.write_to_cache
+      memory.value
+    end
+
+    def self.set(key, value, category: nil, expires_in: nil, public_read: true, public_write: false)
+      memory = find_or_initialize_by(key: key)
+      memory.value = value
+      memory.category = category
+      memory.expires_at = expires_in.present? ? Time.current + expires_in : nil
+      memory.public_read = public_read
+      memory.public_write = public_write
+      memory.save!
+      memory.write_to_cache
+      memory
+    end
+
+    def self.cleanup_expired!
+      expired.destroy_all
+    end
+
+    private
+
+    def active?
+      !expired?
+    end
+  end
+end

data/lib/active_matrix/engine.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'rails/engine'
+
+module ActiveMatrix
+  class Engine < Rails::Engine
+    engine_name 'activematrix'
+
+    initializer 'activematrix.configure_logger' do
+      # Configure logger
+      ActiveMatrix.logger = Rails.logger
+    end
+  end
+end

data/lib/active_matrix/protocols/cs/message_relationships.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+module ActiveMatrix
+  module Protocols
+    module CS
+      # Handles message relationships (replies, edits, reactions, threads)
+      # @see https://spec.matrix.org/latest/client-server-api/#relationships
+      module MessageRelationships
+        # Send a message as a reply to another event
+        #
+        # @param room_id [String] The room ID
+        # @param event_id [String] The event ID to reply to
+        # @param content [Hash,String] The message content
+        # @param msgtype [String] The message type (defaults to 'm.text')
+        # @param params [Hash] Additional parameters for send_message_event
+        # @return [Response] The response from the server
+        #
+        # @example Reply to a message
+        #   api.reply_to(room_id, event_id, "I agree!")
+        #
+        # @example Reply with custom msgtype
+        #   api.reply_to(room_id, event_id, { url: "mxc://..." }, msgtype: 'm.image')
+        def reply_to(room_id, event_id, content, msgtype: 'm.text', **params)
+          content = { body: content } if content.is_a?(String)
+          content[:msgtype] ||= msgtype
+
+          # Add the reply relationship
+          content[:'m.relates_to'] = {
+            'm.in_reply_to' => {
+              event_id: event_id
+            }
+          }
+
+          send_message_event(room_id, 'm.room.message', content, **params)
+        end
+
+        # Send a threaded message
+        #
+        # @param room_id [String] The room ID
+        # @param thread_root_id [String] The root event ID of the thread
+        # @param content [Hash,String] The message content
+        # @param msgtype [String] The message type (defaults to 'm.text')
+        # @param latest_event_id [String,nil] The latest event in the thread (for fallback)
+        # @param include_fallback [Boolean] Include reply fallback for older clients
+        # @param params [Hash] Additional parameters for send_message_event
+        # @return [Response] The response from the server
+        #
+        # @example Send a threaded message
+        #   api.send_threaded_message(room_id, root_event_id, "This is a thread reply")
+        #
+        # @example Send a threaded message with fallback
+        #   api.send_threaded_message(room_id, root_id, "Reply", latest_event_id: last_id, include_fallback: true)
+        def send_threaded_message(room_id, thread_root_id, content, msgtype: 'm.text', 
+                                  latest_event_id: nil, include_fallback: false, **params)
+          content = { body: content } if content.is_a?(String)
+          content[:msgtype] ||= msgtype
+
+          # Build the thread relationship
+          relates_to = {
+            rel_type: 'm.thread',
+            event_id: thread_root_id
+          }
+
+          # Add fallback for older clients if requested
+          if include_fallback && latest_event_id
+            relates_to[:'m.in_reply_to'] = {
+              event_id: latest_event_id
+            }
+            relates_to[:is_falling_back] = true
+          end
+
+          content[:'m.relates_to'] = relates_to
+          send_message_event(room_id, 'm.room.message', content, **params)
+        end
+
+        # Edit an existing message
+        #
+        # @param room_id [String] The room ID
+        # @param event_id [String] The event ID to edit
+        # @param new_content [Hash,String] The new message content
+        # @param msgtype [String] The message type (defaults to 'm.text')
+        # @param params [Hash] Additional parameters for send_message_event
+        # @return [Response] The response from the server
+        #
+        # @example Edit a text message
+        #   api.edit_message(room_id, event_id, "Updated message content")
+        #
+        # @example Edit with formatted content
+        #   api.edit_message(room_id, event_id, {
+        #     body: "Updated *formatted* message",
+        #     format: "org.matrix.custom.html",
+        #     formatted_body: "Updated <em>formatted</em> message"
+        #   })
+        def edit_message(room_id, event_id, new_content, msgtype: 'm.text', **params)
+          new_content = { body: new_content } if new_content.is_a?(String)
+          new_content[:msgtype] ||= msgtype
+
+          # Build the edit event content
+          content = {
+            body: "* #{new_content[:body]}", # Fallback with asterisk prefix
+            msgtype: msgtype,
+            'm.new_content' => new_content,
+            'm.relates_to' => {
+              rel_type: 'm.replace',
+              event_id: event_id
+            }
+          }
+
+          # Copy format fields to top level if present
+          if new_content[:format]
+            content[:format] = new_content[:format]
+            content[:formatted_body] = "* #{new_content[:formatted_body]}"
+          end
+
+          send_message_event(room_id, 'm.room.message', content, **params)
+        end
+
+        # Send a reaction to an event
+        #
+        # @param room_id [String] The room ID
+        # @param event_id [String] The event ID to react to
+        # @param key [String] The reaction key (usually an emoji)
+        # @param params [Hash] Additional parameters for send_message_event
+        # @return [Response] The response from the server
+        #
+        # @example React with an emoji
+        #   api.send_reaction(room_id, event_id, "👍")
+        #
+        # @example React with custom text
+        #   api.send_reaction(room_id, event_id, "agree")
+        def send_reaction(room_id, event_id, key, **params)
+          content = {
+            'm.relates_to' => {
+              rel_type: 'm.annotation',
+              event_id: event_id,
+              key: key
+            }
+          }
+
+          send_message_event(room_id, 'm.reaction', content, **params)
+        end
+
+        # Remove a reaction from an event
+        #
+        # @param room_id [String] The room ID
+        # @param reaction_event_id [String] The reaction event ID to redact
+        # @param reason [String,nil] Optional reason for removing the reaction
+        # @param params [Hash] Additional parameters for redact_event
+        # @return [Response] The response from the server
+        #
+        # @example Remove a reaction
+        #   api.remove_reaction(room_id, reaction_event_id)
+        def remove_reaction(room_id, reaction_event_id, reason: nil, **params)
+          redact_event(room_id, reaction_event_id, reason: reason, **params)
+        end
+
+        # Send a reference to another event
+        #
+        # @param room_id [String] The room ID
+        # @param event_id [String] The event ID to reference
+        # @param content [Hash,String] The message content
+        # @param msgtype [String] The message type (defaults to 'm.text')
+        # @param params [Hash] Additional parameters for send_message_event
+        # @return [Response] The response from the server
+        #
+        # @example Send a message referencing another event
+        #   api.send_reference(room_id, event_id, "See the above message")
+        def send_reference(room_id, event_id, content, msgtype: 'm.text', **params)
+          content = { body: content } if content.is_a?(String)
+          content[:msgtype] ||= msgtype
+
+          content[:'m.relates_to'] = {
+            rel_type: 'm.reference',
+            event_id: event_id
+          }
+
+          send_message_event(room_id, 'm.room.message', content, **params)
+        end
+
+        # Get related events for a given event
+        #
+        # @param room_id [String] The room ID
+        # @param event_id [String] The event ID to get relations for
+        # @param rel_type [String,nil] Filter by specific relationship type
+        # @param event_type [String,nil] Filter by specific event type
+        # @param from [String,nil] Pagination token
+        # @param to [String,nil] Pagination token
+        # @param limit [Integer] Maximum number of events to return
+        # @param direction [String] Direction of pagination ('b' for backwards, 'f' for forwards)
+        # @param params [Hash] Additional query parameters
+        # @return [Response] The related events
+        #
+        # @example Get all relations
+        #   api.get_relations(room_id, event_id)
+        #
+        # @example Get only reactions
+        #   api.get_relations(room_id, event_id, rel_type: 'm.annotation', event_type: 'm.reaction')
+        #
+        # @example Get thread replies
+        #   api.get_relations(room_id, event_id, rel_type: 'm.thread')
+        def get_relations(room_id, event_id, rel_type: nil, event_type: nil, 
+                          from: nil, to: nil, limit: nil, direction: 'b', **params)
+          query = {
+            from: from,
+            to: to,
+            limit: limit,
+            dir: direction
+          }.merge(params).compact
+
+          # Build the appropriate endpoint based on filters
+          endpoint = "/rooms/#{room_id}/relations/#{event_id}"
+          endpoint += "/#{rel_type}" if rel_type
+          endpoint += "/#{event_type}" if rel_type && event_type
+
+          request(:get, client_api_latest, endpoint, query: query)
+        end
+
+        # Get aggregated relations for multiple events
+        #
+        # @param room_id [String] The room ID
+        # @param event_ids [Array<String>] The event IDs to get relations for
+        # @param rel_type [String,nil] Filter by specific relationship type
+        # @param event_type [String,nil] Filter by specific event type
+        # @param params [Hash] Additional body parameters
+        # @return [Response] The aggregated relations
+        #
+        # @example Get aggregated reactions for multiple events
+        #   api.get_aggregated_relations(room_id, event_ids, rel_type: 'm.annotation')
+        def get_aggregated_relations(room_id, event_ids, rel_type: nil, event_type: nil, **params)
+          body = {
+            event_ids: event_ids,
+            rel_type: rel_type,
+            event_type: event_type
+          }.merge(params).compact
+
+          request(:post, client_api_latest, "/rooms/#{room_id}/aggregations", body: body)
+        end
+
+        # Get the edit history of an event
+        #
+        # @param room_id [String] The room ID
+        # @param event_id [String] The event ID to get edit history for
+        # @param params [Hash] Additional query parameters
+        # @return [Response] The edit history
+        #
+        # @example Get edit history
+        #   api.get_edit_history(room_id, event_id)
+        def get_edit_history(room_id, event_id, **params)
+          get_relations(room_id, event_id, rel_type: 'm.replace', event_type: 'm.room.message', **params)
+        end
+
+        # Get all reactions for an event
+        #
+        # @param room_id [String] The room ID
+        # @param event_id [String] The event ID to get reactions for
+        # @param params [Hash] Additional query parameters
+        # @return [Response] The reactions
+        #
+        # @example Get all reactions
+        #   api.get_reactions(room_id, event_id)
+        def get_reactions(room_id, event_id, **params)
+          get_relations(room_id, event_id, rel_type: 'm.annotation', event_type: 'm.reaction', **params)
+        end
+
+        # Get thread messages for a root event
+        #
+        # @param room_id [String] The room ID
+        # @param thread_root_id [String] The thread root event ID
+        # @param params [Hash] Additional query parameters
+        # @return [Response] The thread messages
+        #
+        # @example Get thread messages
+        #   api.get_thread_messages(room_id, thread_root_id)
+        def get_thread_messages(room_id, thread_root_id, **params)
+          get_relations(room_id, thread_root_id, rel_type: 'm.thread', **params)
+        end
+
+        # Check if an event has been edited
+        #
+        # @param event [Hash] The event to check
+        # @return [Boolean] True if the event has been edited
+        def event_edited?(event)
+          event.dig(:unsigned, :'m.relations', :'m.replace').present?
+        end
+
+        # Get the latest edit content for an event
+        #
+        # @param event [Hash] The event to get latest content for
+        # @return [Hash,nil] The latest content or nil if not edited
+        def get_latest_edit_content(event)
+          edit_event = event.dig(:unsigned, :'m.relations', :'m.replace')
+          return nil unless edit_event
+
+          # Return the m.new_content if available, otherwise the content
+          edit_event.dig(:content, :'m.new_content') || edit_event[:content]
+        end
+
+        # Check if an event is part of a thread
+        #
+        # @param event [Hash] The event to check
+        # @return [Boolean] True if the event is part of a thread
+        def in_thread?(event)
+          rel_type = event.dig(:content, :'m.relates_to', :rel_type)
+          rel_type == 'm.thread'
+        end
+
+        # Get the thread root ID for an event
+        #
+        # @param event [Hash] The event to get thread root for
+        # @return [String,nil] The thread root event ID or nil if not in a thread
+        def get_thread_root_id(event)
+          return nil unless in_thread?(event)
+          event.dig(:content, :'m.relates_to', :event_id)
+        end
+      end
+    end
+  end
+end

data/lib/active_matrix/railtie.rb

@@ -4,9 +4,17 @@ require 'rails/railtie'
 
 module ActiveMatrix
   class Railtie < Rails::Railtie
+    Rails.logger.debug 'ActiveMatrix::Railtie: Loading...'
+
     initializer 'activematrix.configure_rails_initialization' do
+      Rails.logger.debug 'ActiveMatrix::Railtie: Initializer running'
       # Configure Rails.logger as the default logger
       ActiveMatrix.logger = Rails.logger
+      Rails.logger.debug 'ActiveMatrix::Railtie: Logger configured'
+
+      # Debug autoload paths
+      Rails.logger.debug { "ActiveMatrix::Railtie: Autoload paths = #{Rails.application.config.autoload_paths}" }
+      Rails.logger.debug { "ActiveMatrix::Railtie: Eager load paths = #{Rails.application.config.eager_load_paths}" }
     end
   end
 end

data/lib/active_matrix/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveMatrix
-  VERSION = '0.0.5'
+  VERSION = '0.0.7'
 end

data/lib/active_matrix.rb

@@ -5,12 +5,9 @@ require_relative 'active_matrix/version'
 
 require 'json'
 require 'zeitwerk'
-require 'active_support'
-require 'active_support/core_ext/integer/time'
-require 'active_support/core_ext/time/calculations'
-require 'active_support/core_ext/time/zones'
-require 'active_support/core_ext/hash/keys'
-require 'active_support/core_ext/object/blank'
+require 'active_record'
+require 'active_job'
+require 'state_machines-activerecord'
 
 module ActiveMatrix
   # Configuration
@@ -82,7 +79,7 @@ module ActiveMatrix
   # Ignore directories and files that shouldn't be autoloaded
   Loader.ignore("#{__dir__}/generators")
   Loader.ignore("#{__dir__}/activematrix.rb")
-  
+
   # Ignore files that don't follow Zeitwerk naming conventions
   Loader.ignore("#{__dir__}/active_matrix/errors.rb")
   Loader.ignore("#{__dir__}/active_matrix/events.rb")
@@ -107,6 +104,6 @@ module ActiveMatrix
   require_relative 'active_matrix/events'
   require_relative 'active_matrix/uri_module'
 
-  # Load Railtie for Rails integration
-  require 'active_matrix/railtie' if defined?(Rails::Railtie)
+  # Load Engine for Rails integration
+  require 'active_matrix/engine'
 end

data/lib/generators/active_matrix/install/install_generator.rb

@@ -23,13 +23,6 @@ module ActiveMatrix
         template 'active_matrix.rb', 'config/initializers/active_matrix.rb'
       end
 
-      def create_models
-        template 'matrix_agent.rb', 'app/models/matrix_agent.rb'
-        template 'agent_memory.rb', 'app/models/agent_memory.rb'
-        template 'conversation_context.rb', 'app/models/conversation_context.rb'
-        template 'global_memory.rb', 'app/models/global_memory.rb'
-      end
-
       def display_post_install
         readme 'README' if behavior == :invoke
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activematrix
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.7
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -10,6 +10,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: maxitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
@@ -122,6 +136,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: syslog
   requirement: !ruby/object:Gem::Requirement
@@ -178,6 +206,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -238,16 +280,16 @@ dependencies:
   name: state_machines-activerecord
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<="
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: 0.100.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - "<="
       - !ruby/object:Gem::Version
-        version: 0.40.0
+        version: 0.100.0
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -262,8 +304,15 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.6'
-description: A Ruby on Rails gem that provides seamless integration with the Matrix
-  protocol, enabling Rails applications to connect and communicate with Matrix servers.
+description: "ActiveMatrix is a comprehensive Rails-native Matrix SDK that enables
+  developers to build sophisticated multi-agent bot systems \nand real-time communication
+  features. This gem provides deep Rails integration with ActiveRecord models, state
+  machines for \nbot lifecycle management, multi-tiered memory systems, intelligent
+  event routing, connection pooling, and built-in \ninter-agent communication. Perfect
+  for building chatbots, automation systems, monitoring agents, and collaborative
+  AI \nsystems within Rails applications. Features include command handling, room
+  management, media support, end-to-end encryption \ncapabilities, and extensive protocol
+  support (CS, AS, IS, SS).\n"
 email:
 - terminale@gmail.com
 - ace@haxalot.com
@@ -277,6 +326,13 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/jobs/active_matrix/application_job.rb
+- app/models/active_matrix/agent.rb
+- app/models/active_matrix/agent/jobs/memory_reaper.rb
+- app/models/active_matrix/agent_store.rb
+- app/models/active_matrix/application_record.rb
+- app/models/active_matrix/chat_session.rb
+- app/models/active_matrix/knowledge_base.rb
 - lib/active_matrix.rb
 - lib/active_matrix/account_data_cache.rb
 - lib/active_matrix/agent_manager.rb
@@ -288,6 +344,7 @@ files:
 - lib/active_matrix/cacheable.rb
 - lib/active_matrix/client.rb
 - lib/active_matrix/client_pool.rb
+- lib/active_matrix/engine.rb
 - lib/active_matrix/errors.rb
 - lib/active_matrix/event_router.rb
 - lib/active_matrix/events.rb
@@ -301,6 +358,7 @@ files:
 - lib/active_matrix/mxid.rb
 - lib/active_matrix/protocols/as.rb
 - lib/active_matrix/protocols/cs.rb
+- lib/active_matrix/protocols/cs/message_relationships.rb
 - lib/active_matrix/protocols/is.rb
 - lib/active_matrix/protocols/msc.rb
 - lib/active_matrix/protocols/ss.rb
@@ -319,19 +377,24 @@ files:
 - lib/generators/active_matrix/install/install_generator.rb
 - lib/generators/active_matrix/install/templates/README
 - lib/generators/active_matrix/install/templates/active_matrix.rb
-- lib/generators/active_matrix/install/templates/agent_memory.rb
-- lib/generators/active_matrix/install/templates/conversation_context.rb
 - lib/generators/active_matrix/install/templates/create_agent_memories.rb
 - lib/generators/active_matrix/install/templates/create_conversation_contexts.rb
 - lib/generators/active_matrix/install/templates/create_global_memories.rb
 - lib/generators/active_matrix/install/templates/create_matrix_agents.rb
-- lib/generators/active_matrix/install/templates/global_memory.rb
-- lib/generators/active_matrix/install/templates/matrix_agent.rb
 homepage: https://github.com/seuros/activematrix
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/seuros/activematrix
+  source_code_uri: https://github.com/seuros/activematrix
+  changelog_uri: https://github.com/seuros/activematrix/blob/master/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/activematrix
+  bug_tracker_uri: https://github.com/seuros/activematrix/issues
+  wiki_uri: https://github.com/seuros/activematrix/wiki
+  tags: matrix, matrix-protocol, matrix-sdk, matrix-api, matrix-client, rails, rails-engine,
+    activerecord, activejob, rails-integration, bot, chatbot, multi-agent, agent-system,
+    bot-framework, real-time, messaging, communication, chat, state-machine
 rdoc_options: []
 require_paths:
 - lib
@@ -348,5 +411,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.7
 specification_version: 4
-summary: Rails gem for connecting to Matrix protocol
+summary: Rails-native Matrix SDK for building multi-agent bot systems and real-time
+  communication
 test_files: []

data/lib/generators/active_matrix/install/templates/agent_memory.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-class AgentMemory < ApplicationRecord
-  belongs_to :matrix_agent
-
-  validates :key, presence: true, uniqueness: { scope: :matrix_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 unless expires_at.present?
-
-    remaining = expires_at - Time.current
-    [remaining, 0].max
-  end
-
-  # Cache integration
-  def cache_key
-    "agent_memory/#{matrix_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
-    AgentMemoryCleanupJob.set(wait_until: expires_at).perform_later if defined?(AgentMemoryCleanupJob)
-  end
-end

data/lib/generators/active_matrix/install/templates/conversation_context.rb

@@ -1,72 +0,0 @@
-# frozen_string_literal: true
-
-class ConversationContext < ApplicationRecord
-  belongs_to :matrix_agent
-
-  validates :user_id, presence: true
-  validates :room_id, presence: true
-  validates :user_id, uniqueness: { scope: %i[matrix_agent_id room_id] }
-
-  # Configuration
-  MAX_HISTORY_SIZE = 20
-
-  # Scopes
-  scope :recent, -> { order(last_message_at: :desc) }
-  scope :active, -> { where('last_message_at > ?', 1.hour.ago) }
-  scope :stale, -> { where('last_message_at < ?', 1.day.ago) }
-
-  # Add a message to the history
-  def add_message(message_data)
-    messages = message_history['messages'] || []
-
-    # Add new message
-    messages << {
-      'event_id' => message_data[:event_id],
-      'sender' => message_data[:sender],
-      'content' => message_data[:content],
-      'timestamp' => message_data[:timestamp] || Time.current.to_i
-    }
-
-    # Keep only recent messages
-    messages = messages.last(MAX_HISTORY_SIZE)
-
-    # Update record
-    self.message_history = { 'messages' => messages }
-    self.last_message_at = Time.current
-    self.message_count = messages.size
-    save!
-
-    # Update cache
-    write_to_cache
-  end
-
-  # Get recent messages
-  def recent_messages(limit = 10)
-    messages = message_history['messages'] || []
-    messages.last(limit)
-  end
-
-  # Clear old messages but keep context
-  def prune_history!
-    messages = message_history['messages'] || []
-    self.message_history = { 'messages' => messages.last(5) }
-    save!
-  end
-
-  # Cache integration
-  def cache_key
-    "conversation/#{matrix_agent_id}/#{user_id}/#{room_id}"
-  end
-
-  def write_to_cache
-    Rails.cache.write(cache_key, {
-                        context: context,
-                        recent_messages: recent_messages,
-                        last_message_at: last_message_at
-                      }, expires_in: 1.hour)
-  end
-
-  def self.cleanup_stale!
-    stale.destroy_all
-  end
-end

data/lib/generators/active_matrix/install/templates/global_memory.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-class GlobalMemory < ApplicationRecord
-  validates :key, presence: true, uniqueness: true
-
-  scope :active, -> { where('expires_at IS NULL OR expires_at > ?', Time.current) }
-  scope :expired, -> { where('expires_at <= ?', Time.current) }
-  scope :by_category, ->(category) { where(category: category) }
-  scope :readable, -> { where(public_read: true) }
-  scope :writable, -> { where(public_write: true) }
-
-  def expired?
-    expires_at.present? && expires_at <= Time.current
-  end
-
-  def readable_by?(agent)
-    public_read || (agent.is_a?(MatrixAgent) && agent.admin?)
-  end
-
-  def writable_by?(agent)
-    public_write || (agent.is_a?(MatrixAgent) && agent.admin?)
-  end
-
-  # Cache integration
-  def cache_key
-    "global/#{key}"
-  end
-
-  def write_to_cache
-    return unless active?
-
-    ttl = expires_at.present? ? expires_at - Time.current : nil
-    Rails.cache.write(cache_key, value, expires_in: ttl)
-  end
-
-  def self.get(key)
-    # Try cache first
-    cached = Rails.cache.read("global/#{key}")
-    return cached if cached.present?
-
-    # Fallback to database
-    memory = find_by(key: key)
-    return unless memory&.active?
-
-    memory.write_to_cache
-    memory.value
-  end
-
-  def self.set(key, value, category: nil, expires_in: nil, public_read: true, public_write: false)
-    memory = find_or_initialize_by(key: key)
-    memory.value = value
-    memory.category = category
-    memory.expires_at = expires_in.present? ? Time.current + expires_in : nil
-    memory.public_read = public_read
-    memory.public_write = public_write
-    memory.save!
-    memory.write_to_cache
-    memory
-  end
-
-  def self.cleanup_expired!
-    expired.destroy_all
-  end
-
-  private
-
-  def active?
-    !expired?
-  end
-end

data/lib/generators/active_matrix/install/templates/matrix_agent.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-class MatrixAgent < ApplicationRecord
-  # Associations
-  has_many :agent_memories, dependent: :destroy
-  has_many :conversation_contexts, 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(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!
-    increment!(:messages_handled)
-  end
-
-  def update_activity!
-    update(last_active_at: Time.current)
-  end
-
-  # Password handling
-  attr_accessor :password
-
-  def authenticate(password)
-    return false unless encrypted_password.present?
-
-    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