activematrix 0.0.7 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bf1ad81648f055b2fdb10da688c66ac7267456cea155b0d76bb41864ae6bab5
-  data.tar.gz: 282f29e6c278cc4ee5b721039e1ec36c2a48b03ba115e02e9beb017b45211706
+  metadata.gz: 763fcbfe5b98eb8dcddb9e512f782ce3c8ff994f2581e0b5a18767a52e109515
+  data.tar.gz: cf71a8ec3f33ea722e6c3b0217e05585d2c70b07816875f602ad1bf74f054cc8
 SHA512:
-  metadata.gz: '08aedb897355151e41f5db2b169d58d0b2842b0c5b7c51a596708ab8ce60be886cb99550f7bb7dfdbf1e71fae918014489d4c48d4271077b930765f6513e28b6'
-  data.tar.gz: b6a3e216fecc58cf8416bc84980c7e5c17edff2b971a2707ee9f82740c69518b60a77880440522765f4befc8a1fc2fc7bb81df39e8fc120c7ddc4451c4368908
+  metadata.gz: e6e3925d13d2708cd4b6e7e1280a3c1bfc275ad8accb353f37b7f9ea73e4886e7d69622c52bd984d307f592cdbd93482707892f5a7e64deed369296ef3b91be2
+  data.tar.gz: c61243b17caafb3a3752b1381526ebba8995b0b6033bbc1e84584b4785cc4dcc5acb59bc5a5352ee725380721fc50fbe15ab4b1bfd69f2f2e764a61c627d9d89

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/models/active_matrix/agent.rb

@@ -1,5 +1,40 @@
 # 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'
@@ -41,7 +76,7 @@ module ActiveMatrix
       end
 
       after_transition to: :online_idle do |agent|
-        agent.update(last_active_at: Time.current)
+        agent.update_column(:last_active_at, Time.current)
       end
 
       event :start_processing do

data/app/models/active_matrix/agent_store.rb

@@ -1,5 +1,34 @@
 # 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'

data/app/models/active_matrix/application_record.rb

@@ -1,5 +1,13 @@
 # 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

data/app/models/active_matrix/chat_session.rb

@@ -1,5 +1,34 @@
 # frozen_string_literal: true
 
+# <rails-lens:schema:begin>
+# table = "active_matrix_chat_sessions"
+# database_dialect = "PostgreSQL"
+#
+# columns = [
+#   { name = "id", type = "integer", pk = true, null = false },
+#   { name = "agent_id", type = "integer", null = false },
+#   { name = "user_id", type = "string", null = false },
+#   { name = "room_id", type = "string", null = false },
+#   { name = "context", type = "json" },
+#   { name = "message_history", type = "json" },
+#   { name = "last_message_at", type = "datetime" },
+#   { name = "message_count", 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_chat_sessions_on_agent_id", columns = ["agent_id"] },
+#   { name = "index_active_matrix_chat_sessions_on_last_message_at", columns = ["last_message_at"] },
+#   { name = "index_chat_sessions_on_agent_user_room", columns = ["agent_id", "user_id", "room_id"], unique = true }
+# ]
+#
+# foreign_keys = [
+#   { column = "agent_id", references_table = "active_matrix_agents", references_column = "id", name = "fk_rails_53457da357" }
+# ]
+#
+# notes = ["agent:INVERSE_OF", "context:NOT_NULL", "message_history:NOT_NULL", "user_id:LIMIT", "room_id:LIMIT"]
+# <rails-lens:schema:end>
 module ActiveMatrix
   class ChatSession < ApplicationRecord
     self.table_name = 'active_matrix_chat_sessions'

data/app/models/active_matrix/knowledge_base.rb

@@ -1,5 +1,31 @@
 # frozen_string_literal: true
 
+# <rails-lens:schema:begin>
+# table = "active_matrix_knowledge_bases"
+# database_dialect = "PostgreSQL"
+#
+# columns = [
+#   { name = "id", type = "integer", pk = true, null = false },
+#   { name = "key", type = "string", null = false },
+#   { name = "value", type = "json" },
+#   { name = "category", type = "string" },
+#   { name = "expires_at", type = "datetime" },
+#   { name = "public_read", type = "boolean", null = false, default = "true" },
+#   { name = "public_write", type = "boolean", null = false, default = "false" },
+#   { name = "created_at", type = "datetime", null = false },
+#   { name = "updated_at", type = "datetime", null = false }
+# ]
+#
+# indexes = [
+#   { name = "index_active_matrix_knowledge_bases_on_category", columns = ["category"] },
+#   { name = "index_active_matrix_knowledge_bases_on_expires_at", columns = ["expires_at"] },
+#   { name = "index_active_matrix_knowledge_bases_on_key", columns = ["key"], unique = true },
+#   { name = "index_active_matrix_knowledge_bases_on_public_read", columns = ["public_read"] },
+#   { name = "index_active_matrix_knowledge_bases_on_public_write", columns = ["public_write"] }
+# ]
+#
+# notes = ["value:NOT_NULL", "category:NOT_NULL", "key:LIMIT", "category:LIMIT"]
+# <rails-lens:schema:end>
 module ActiveMatrix
   class KnowledgeBase < ApplicationRecord
     self.table_name = 'active_matrix_knowledge_bases'

data/exe/activematrix

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'active_matrix/cli'
+
+ActiveMatrix::CLI.start(ARGV)