activematrix 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 143ff7d837b5e8c2da0cc48dac7ec9494b625ec4d1f6dfd3d736648c1cf37951
-  data.tar.gz: 9d4d7c69c17c9d07e36b628a69de1e2d759249ea9310e3158f56323982757979
+  metadata.gz: b1f24e67640b140aef30d970e2ca17366a860914fa34dedb4f6879b84259fb43
+  data.tar.gz: ab62b7257d5bbb8c29738005ffd2443e96f5837a7a07f0b7263a1c9942bad6ff
 SHA512:
-  metadata.gz: 3376d53d35686a0eb5a40a7a8102a1dcd8c5c226a4bb606cf1c8d05f5f568396bd49465b5ca40c7e52dff5fa7569e0e6c39d6cae3b077ce9656bb59f699267db
-  data.tar.gz: c9a3120e5ea6edde56923990609e6ea156c8df500f8cd6955ec98811c622715872bcc3e76bfd740772be491956a5c4b45980d2c9ac8de87bf2f16e301bcad8f9
+  metadata.gz: 01c30a4813a0ba61fc39ce2dd920dce535ca0de65154f48e635598268ad9480857376363b63441203c7e0d6abe62af7b2580ea74dff8b5853a3a5afc4712381c
+  data.tar.gz: 96f2c51f3f6b70df680ca90a8f120abe15675f341c706e99286e728d910c9db8fd4c84a53880cfe178cc794d0472ab3bfca856e2a8caa6c1d3112767dd63b1d4

data/README.md

@@ -1,82 +1,249 @@
 # ActiveMatrix
 
-A Rails gem for integrating Matrix protocol communication into Ruby on Rails applications. This gem is a fork of the [matrix-sdk](https://github.com/ananace/ruby-matrix-sdk) gem, enhanced with Rails-specific features and tight integration with ActiveRecord and the Rails framework.
+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.
 
-## About
+## Features
 
-ActiveMatrix provides a seamless way to add Matrix protocol support to your Rails applications, allowing you to build chat features, real-time messaging, and collaborative tools using the decentralized Matrix network.
+- **Multi-Agent Architecture**: Run multiple bots concurrently with lifecycle management
+- **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
+- **Generators**: Rails generators for quick bot creation
+- **Inter-Agent Communication**: Built-in messaging between bots
 
-## Example usage
+## Installation
 
-For more fully-featured examples, check the [examples](examples/) folder.
+Add this line to your application's Gemfile:
 
 ```ruby
-# Raw API usage
-require 'matrix_sdk'
+gem 'activematrix', '~> 0.0.3'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+$ rails generate active_matrix:install
+$ rails db:migrate
+```
+
+## Multi-Agent System Usage
+
+### Creating Your First Bot
 
-api = MatrixSdk::Api.new 'https://matrix.org'
+```bash
+$ rails generate active_matrix:bot captain
+```
 
-api.login user: 'example', password: 'notarealpass'
-api.whoami?
-# => {:user_id=>"@example:matrix.org"}
+This creates a bot class in `app/bots/captain_bot.rb`:
 
-# It's possible to call arbitrary APIs as well
-api.request :get, :federation_v1, '/version'
-# => {:server=>{:version=>"0.28.1", :name=>"Synapse"}}
+```ruby
+class CaptainBot < ActiveMatrix::Bot::MultiInstanceBase
+  set :accept_invites, true
+  set :command_prefix, '!'
+  
+  command :status,
+          desc: 'Get system status',
+          args: '[component]' do |component = nil|
+    if component
+      # Check specific component
+      status = memory.get("status_#{component}") || 'unknown'
+      room.send_notice("#{component}: #{status}")
+    else
+      # Overall status
+      room.send_notice("All systems operational!")
+    end
+  end
+  
+  command :deploy,
+          desc: 'Deploy to production',
+          args: 'target' do |target|
+    # Use conversation memory to track deployments
+    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]
+    when 'status_report'
+      memory.set("status_#{data[:component]}", data[:status])
+      logger.info "Received status update from #{from.agent_name}"
+    end
+  end
+end
 ```
 
+### Setting Up Agents
+
 ```ruby
-# Client wrapper with login
-require 'matrix_sdk'
-
-client = MatrixSdk::Client.new 'https://example.com'
-client.login 'username', 'notarealpass' #, no_sync: true
-
-client.rooms.count
-# => 5
-hq = client.find_room '#matrix:matrix.org'
-# => #<MatrixSdk::Room:00005592a1161528 @id="!cURbafjkfsMDVwdRDQ:matrix.org" @name="Matrix HQ" @topic="The Official Matrix HQ - please come chat here! | To support Matrix.org development: https://patreon.com/matrixdotorg | Try http://riot.im/app for a glossy web client | Looking for homeserver hosting? Check out https://upcloud.com/matrix!" @canonical_alias="#matrix:matrix.org" @aliases=["#matrix:jda.mn"] @join_rule=:public @guest_access=:can_join @event_history_limit=10>
-hq.guest_access?
-# => true
-hq.send_text "This is an example message - don't actually do this ;)"
-# => {:event_id=>"$123457890abcdef:matrix.org"}
+# Create agent records in Rails console or seeds
+captain = MatrixAgent.create!(
+  name: 'captain',
+  homeserver: 'https://matrix.org',
+  username: 'captain_bot',
+  password: 'secure_password',
+  bot_class: 'CaptainBot',
+  settings: {
+    rooms_to_join: ['!warroom:matrix.org'],
+    command_prefix: '!'
+  }
+)
+
+lieutenant = MatrixAgent.create!(
+  name: 'lieutenant', 
+  homeserver: 'https://matrix.org',
+  username: 'lieutenant_bot',
+  password: 'secure_password',
+  bot_class: 'LieutenantBot'
+)
 ```
 
+### Managing Agents
+
 ```ruby
-# Client wrapper with token
-require 'matrix_sdk'
+# Start all agents
+ActiveMatrix::AgentManager.instance.start_all
+
+# Start specific agent
+ActiveMatrix::AgentManager.instance.start_agent(captain)
 
-client = MatrixSdk::Client.new 'https://example.com'
-client.api.access_token = 'thisisnotarealtoken'
+# Check status
+ActiveMatrix::AgentManager.instance.status
+# => { running: 2, agents: [...], monitor_active: true }
 
-# Doesn't automatically trigger a sync when setting the token directly
-client.rooms.count
-# => 0
+# Stop agent
+ActiveMatrix::AgentManager.instance.stop_agent(captain)
 
-client.sync
-client.rooms.count
-# => 5
+# Restart agent
+ActiveMatrix::AgentManager.instance.restart_agent(captain)
 ```
 
+## Memory System
+
+### Agent Memory (Private)
+```ruby
+# In your bot
+memory.set('last_deployment', Time.current)
+memory.get('last_deployment')
+memory.increment('deployment_count')
+memory.remember('config') { load_config_from_api }
+```
+
+### Conversation Memory (Per User/Room)
 ```ruby
-#!/bin/env ruby
-# Bot DSL
-require 'matrix_sdk/bot'
-
-command :plug do
-  room.send_text <<~PLUG
-    The Ruby SDK is a fine method for writing applications communicating over the Matrix protocol.
-    It can easily be integrated with Rails, and it supports most client/bot use-cases.
-  PLUG
+# Automatically available in commands
+conversation_memory[:last_command] = 'deploy'
+context = conversation_context # Hash of conversation data
+
+# Track message history
+conversation_memory.add_message(event)
+recent = conversation_memory.recent_messages(5)
+```
+
+### Global Memory (Shared)
+```ruby
+# Set global data
+global_memory.set('system_status', 'operational', 
+  category: 'monitoring',
+  expires_in: 5.minutes,
+  public_read: true
+)
+
+# Broadcast to all agents
+global_memory.broadcast('alert', {
+  level: 'warning',
+  message: 'High CPU usage detected'
+})
+
+# Share between specific agents
+global_memory.share('secret_key', 'value', ['captain', 'lieutenant'])
+```
+
+## Event Routing
+
+```ruby
+class MonitorBot < ActiveMatrix::Bot::MultiInstanceBase
+  # Route specific events to this bot
+  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
 end
 ```
 
-## Contributing
+## Basic Client Usage
+
+For simple, single-bot applications:
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/ananace/ruby-matrix-sdk
+```ruby
+# Traditional client usage still works
+client = ActiveMatrix::Client.new 'https://matrix.org'
+client.login 'username', 'password'
 
+room = client.find_room '#matrix:matrix.org'
+room.send_text "Hello from ActiveMatrix!"
+```
 
-## License
+## Configuration
+
+```ruby
+# config/initializers/active_matrix.rb
+ActiveMatrix.configure do |config|
+  config.agent_startup_delay = 2.seconds
+  config.max_agents_per_process = 10
+  config.agent_health_check_interval = 30.seconds
+  config.conversation_history_limit = 20
+  config.conversation_stale_after = 1.day
+  config.memory_cleanup_interval = 1.hour
+end
+```
+
+## Testing
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+```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
+  end
+end
+```
+
+## Architecture
+
+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
+- **Memory System**: Hierarchical storage with caching
+- **State Machines**: Track agent states (offline/connecting/online/busy/error)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/seuros/agent_smith
+
+## License
 
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/active_matrix/agent_manager.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module ActiveMatrix
+  # Manages the lifecycle of Matrix bot agents
+  class AgentManager
+    include Singleton
+    include ActiveMatrix::Logging
+
+    attr_reader :registry, :config
+
+    def initialize
+      @registry = AgentRegistry.instance
+      @config = ActiveMatrix.config
+      @shutdown = false
+      @monitor_thread = nil
+
+      setup_signal_handlers
+    end
+
+    # Start all agents marked as active in the database
+    def start_all
+      return if @shutdown
+
+      logger.info 'Starting all active agents...'
+
+      agents = defined?(MatrixAgent) ? MatrixAgent.where.not(state: :offline) : []
+      agents.each_with_index do |agent, index|
+        sleep(config.agent_startup_delay || 2) if index.positive?
+        start_agent(agent)
+      end
+
+      start_monitor_thread
+      logger.info "Started #{@registry.count} agents"
+    end
+
+    # Start a specific agent
+    def start_agent(agent)
+      return if @shutdown
+
+      if @registry.running?(agent)
+        logger.warn "Agent #{agent.name} is already running"
+        return false
+      end
+
+      logger.info "Starting agent: #{agent.name}"
+
+      begin
+        # Update state
+        agent.connect!
+
+        # Create bot instance in a new thread
+        thread = Thread.new do
+          Thread.current.name = "agent-#{agent.name}"
+
+          begin
+            # Create client and bot instance
+            client = create_client_for_agent(agent)
+            bot_class = agent.bot_class.constantize
+            bot_instance = bot_class.new(client)
+
+            # Register the agent
+            @registry.register(agent, bot_instance)
+
+            # Authenticate if needed
+            if agent.access_token.present?
+              client.access_token = agent.access_token
+            else
+              client.login(agent.username, agent.password)
+              agent.update(access_token: client.access_token)
+            end
+
+            # Restore sync token if available
+            client.sync_token = agent.last_sync_token if agent.last_sync_token.present?
+
+            # Mark as online
+            agent.connection_established!
+
+            # Start the sync loop
+            client.start_listener_thread
+            client.instance_variable_get(:@sync_thread).join
+          rescue StandardError => e
+            logger.error "Error in agent #{agent.name}: #{e.message}"
+            logger.error e.backtrace.join("\n")
+            agent.encounter_error!
+            raise
+          ensure
+            @registry.unregister(agent)
+            agent.disconnect! if agent.may_disconnect?
+          end
+        end
+
+        thread.abort_on_exception = true
+        true
+      rescue StandardError => e
+        logger.error "Failed to start agent #{agent.name}: #{e.message}"
+        agent.encounter_error!
+        false
+      end
+    end
+
+    # Stop a specific agent
+    def stop_agent(agent)
+      entry = @registry.get(agent.id)
+      return false unless entry
+
+      logger.info "Stopping agent: #{agent.name}"
+
+      begin
+        # Stop the client sync
+        client = entry[:instance].client
+        client.stop_listener_thread if client.listening?
+
+        # Save sync token
+        agent.update(last_sync_token: client.sync_token) if client.sync_token.present?
+
+        # Kill the thread if still alive
+        thread = entry[:thread]
+        if thread&.alive?
+          thread.kill
+          thread.join(5) # Wait up to 5 seconds
+        end
+
+        # Update state
+        agent.disconnect! if agent.may_disconnect?
+
+        true
+      rescue StandardError => e
+        logger.error "Error stopping agent #{agent.name}: #{e.message}"
+        false
+      end
+    end
+
+    # Stop all running agents
+    def stop_all
+      logger.info 'Stopping all agents...'
+      @shutdown = true
+
+      # Stop monitor thread
+      @monitor_thread&.kill
+
+      # Stop all agents
+      @registry.all_records.each do |agent|
+        stop_agent(agent)
+      end
+
+      logger.info 'All agents stopped'
+    end
+
+    # Restart an agent
+    def restart_agent(agent)
+      stop_agent(agent)
+      sleep(1) # Brief pause
+      start_agent(agent)
+    end
+
+    # Pause an agent (keep it registered but stop processing)
+    def pause_agent(agent)
+      return false unless agent.may_pause?
+
+      entry = @registry.get(agent.id)
+      return false unless entry
+
+      logger.info "Pausing agent: #{agent.name}"
+
+      client = entry[:instance].client
+      client.stop_listener_thread if client.listening?
+      agent.pause!
+
+      true
+    end
+
+    # Resume a paused agent
+    def resume_agent(agent)
+      return false unless agent.paused?
+
+      entry = @registry.get(agent.id)
+      return false unless entry
+
+      logger.info "Resuming agent: #{agent.name}"
+
+      agent.resume!
+      client = entry[:instance].client
+      client.start_listener_thread
+      agent.connection_established!
+
+      true
+    end
+
+    # Get status of all agents
+    def status
+      {
+        running: @registry.count,
+        agents: @registry.health_status,
+        monitor_active: @monitor_thread&.alive? || false,
+        shutdown: @shutdown
+      }
+    end
+
+    private
+
+    def create_client_for_agent(agent)
+      # Use shared client pool if available
+      if defined?(ClientPool)
+        ClientPool.instance.get_client(agent.homeserver)
+      else
+        ActiveMatrix::Client.new(agent.homeserver,
+                                 client_cache: :some,
+                                 sync_filter_limit: 20)
+      end
+    end
+
+    def start_monitor_thread
+      return if @monitor_thread&.alive?
+
+      @monitor_thread = Thread.new do
+        Thread.current.name = 'agent-monitor'
+
+        loop do
+          break if @shutdown
+
+          begin
+            check_agent_health
+            cleanup_stale_data
+          rescue StandardError => e
+            logger.error "Monitor thread error: #{e.message}"
+          end
+
+          sleep(config.agent_health_check_interval || 30)
+        end
+      end
+    end
+
+    def check_agent_health
+      @registry.all.each do |entry|
+        agent = entry[:record]
+        thread = entry[:thread]
+
+        # Check if thread is alive
+        unless thread&.alive?
+          logger.warn "Agent #{agent.name} thread died, restarting..."
+          @registry.unregister(agent)
+          agent.encounter_error!
+          start_agent(agent) unless @shutdown
+          next
+        end
+
+        # Check last activity
+        if agent.last_active_at && agent.last_active_at < 5.minutes.ago
+          logger.warn "Agent #{agent.name} seems inactive"
+          # Could implement additional health checks here
+        end
+      end
+    end
+
+    def cleanup_stale_data
+      # Clean up old conversation contexts
+      ConversationContext.cleanup_stale! if defined?(ConversationContext)
+
+      # Clean up expired memories
+      AgentMemory.cleanup_expired! if defined?(AgentMemory)
+      GlobalMemory.cleanup_expired! if defined?(GlobalMemory)
+    end
+
+    def setup_signal_handlers
+      %w[INT TERM].each do |signal|
+        Signal.trap(signal) do
+          Thread.new { stop_all }.join
+          exit
+        end
+      end
+    end
+  end
+end