kbs 0.0.1

data/lib/kbs/blackboard/memory.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'persistence/store'
+require_relative 'persistence/sqlite_store'
+require_relative 'message_queue'
+require_relative 'audit_log'
+require_relative 'fact'
+
+module KBS
+  module Blackboard
+    # The Blackboard Memory - central workspace for facts and coordination
+    class Memory
+      attr_reader :session_id, :store, :message_queue, :audit_log
+
+      def initialize(db_path: ':memory:', store: nil)
+        @session_id = SecureRandom.uuid
+        @observers = []
+
+        # Use provided store or create default SqliteStore
+        @store = store || Persistence::SqliteStore.new(
+          db_path: db_path,
+          session_id: @session_id
+        )
+
+        # Initialize composed components based on store type
+        setup_components
+      end
+
+      private
+
+      def setup_components
+        # Detect store type and create appropriate MessageQueue and AuditLog
+        if @store.respond_to?(:hybrid?) && @store.hybrid?
+          # Hybrid store: Redis for messages, SQLite for audit
+          require_relative 'redis_message_queue'
+          @message_queue = RedisMessageQueue.new(@store.connection)
+          @audit_log = AuditLog.new(@store.db, @session_id)
+        elsif @store.respond_to?(:connection)
+          # Pure Redis store
+          require_relative 'redis_message_queue'
+          require_relative 'redis_audit_log'
+          @message_queue = RedisMessageQueue.new(@store.connection)
+          @audit_log = RedisAuditLog.new(@store.connection, @session_id)
+        elsif @store.respond_to?(:db)
+          # Pure SQLite store
+          @message_queue = MessageQueue.new(@store.db)
+          @audit_log = AuditLog.new(@store.db, @session_id)
+        else
+          raise ArgumentError, "Store must respond to either :connection (Redis) or :db (SQLite)"
+        end
+      end
+
+      public
+
+      # Fact Management
+      def add_fact(type, attributes = {})
+        uuid = SecureRandom.uuid
+
+        @store.transaction do
+          @store.add_fact(uuid, type, attributes)
+          @audit_log.log_fact_change(uuid, type, attributes, 'ADD')
+        end
+
+        fact = Fact.new(uuid, type, attributes, self)
+        notify_observers(:add, fact)
+        fact
+      end
+
+      def remove_fact(fact)
+        uuid = fact.is_a?(Fact) ? fact.uuid : fact
+
+        @store.transaction do
+          result = @store.remove_fact(uuid)
+
+          if result
+            @audit_log.log_fact_change(uuid, result[:type], result[:attributes], 'REMOVE')
+
+            fact_obj = Fact.new(uuid, result[:type], result[:attributes], self)
+            notify_observers(:remove, fact_obj)
+          end
+        end
+      end
+
+      def update_fact(fact, new_attributes)
+        uuid = fact.is_a?(Fact) ? fact.uuid : fact
+
+        @store.transaction do
+          fact_type = @store.update_fact(uuid, new_attributes)
+
+          if fact_type
+            @audit_log.log_fact_change(uuid, fact_type, new_attributes, 'UPDATE')
+          end
+        end
+      end
+
+      def get_facts(type = nil, pattern = {})
+        fact_data = @store.get_facts(type, pattern)
+
+        fact_data.map do |data|
+          Fact.new(data[:uuid], data[:type], data[:attributes], self)
+        end
+      end
+
+      # Alias for compatibility with WorkingMemory interface
+      def facts
+        get_facts
+      end
+
+      def query_facts(sql_conditions = nil, params = [])
+        fact_data = @store.query_facts(sql_conditions, params)
+
+        fact_data.map do |data|
+          Fact.new(data[:uuid], data[:type], data[:attributes], self)
+        end
+      end
+
+      # Message Queue delegation
+      def post_message(sender, topic, content, priority: 0)
+        @message_queue.post(sender, topic, content, priority: priority)
+      end
+
+      def consume_message(topic, consumer)
+        @store.transaction do
+          @message_queue.consume(topic, consumer)
+        end
+      end
+
+      def peek_messages(topic, limit: 10)
+        @message_queue.peek(topic, limit: limit)
+      end
+
+      # Knowledge Source registry
+      def register_knowledge_source(name, description: nil, topics: [])
+        @store.register_knowledge_source(name, description: description, topics: topics)
+      end
+
+      # Audit Log delegation
+      def log_rule_firing(rule_name, fact_uuids, bindings = {})
+        @audit_log.log_rule_firing(rule_name, fact_uuids, bindings)
+      end
+
+      def get_history(fact_uuid = nil, limit: 100)
+        @audit_log.fact_history(fact_uuid, limit: limit)
+      end
+
+      def get_rule_firings(rule_name = nil, limit: 100)
+        @audit_log.rule_firings(rule_name, limit: limit)
+      end
+
+      # Observer pattern
+      def add_observer(observer)
+        @observers << observer
+      end
+
+      def notify_observers(action, fact)
+        @observers.each { |obs| obs.update(action, fact) }
+      end
+
+      # Session management
+      def clear_session
+        @store.clear_session(@session_id)
+      end
+
+      def transaction(&block)
+        @store.transaction(&block)
+      end
+
+      # Statistics
+      def stats
+        store_stats = @store.stats
+        message_stats = @message_queue.stats
+        audit_stats = @audit_log.stats
+
+        store_stats.merge(message_stats).merge(audit_stats)
+      end
+
+      # Maintenance
+      def vacuum
+        @store.vacuum
+      end
+
+      def close
+        @store.close
+      end
+
+      # For backward compatibility with ReteEngine
+      alias_method :db, :store
+    end
+  end
+end

data/lib/kbs/blackboard/message_queue.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module KBS
+  module Blackboard
+    class MessageQueue
+      def initialize(db)
+        @db = db
+        setup_table
+      end
+
+      def setup_table
+        @db.execute_batch <<-SQL
+          CREATE TABLE IF NOT EXISTS blackboard_messages (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            sender TEXT NOT NULL,
+            topic TEXT NOT NULL,
+            content TEXT NOT NULL,
+            priority INTEGER DEFAULT 0,
+            posted_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+            consumed BOOLEAN DEFAULT 0,
+            consumed_by TEXT,
+            consumed_at TIMESTAMP
+          );
+        SQL
+
+        @db.execute <<-SQL
+          CREATE INDEX IF NOT EXISTS idx_messages_topic ON blackboard_messages(topic);
+        SQL
+
+        @db.execute <<-SQL
+          CREATE INDEX IF NOT EXISTS idx_messages_consumed ON blackboard_messages(consumed);
+        SQL
+      end
+
+      def post(sender, topic, content, priority: 0)
+        content_json = content.is_a?(String) ? content : JSON.generate(content)
+
+        @db.execute(
+          "INSERT INTO blackboard_messages (sender, topic, content, priority) VALUES (?, ?, ?, ?)",
+          [sender, topic, content_json, priority]
+        )
+      end
+
+      def consume(topic, consumer)
+        result = @db.get_first_row(
+          "SELECT * FROM blackboard_messages WHERE topic = ? AND consumed = 0 ORDER BY priority DESC, posted_at ASC LIMIT 1",
+          [topic]
+        )
+
+        if result
+          @db.execute(
+            "UPDATE blackboard_messages SET consumed = 1, consumed_by = ?, consumed_at = CURRENT_TIMESTAMP WHERE id = ?",
+            [consumer, result['id']]
+          )
+
+          {
+            id: result['id'],
+            sender: result['sender'],
+            topic: result['topic'],
+            content: JSON.parse(result['content'], symbolize_names: true),
+            priority: result['priority'],
+            posted_at: Time.parse(result['posted_at'])
+          }
+        end
+      end
+
+      def peek(topic, limit: 10)
+        results = @db.execute(
+          "SELECT * FROM blackboard_messages WHERE topic = ? AND consumed = 0 ORDER BY priority DESC, posted_at ASC LIMIT ?",
+          [topic, limit]
+        )
+
+        results.map do |row|
+          {
+            id: row['id'],
+            sender: row['sender'],
+            topic: row['topic'],
+            content: JSON.parse(row['content'], symbolize_names: true),
+            priority: row['priority'],
+            posted_at: Time.parse(row['posted_at'])
+          }
+        end
+      end
+
+      def stats
+        {
+          total_messages: @db.get_first_value("SELECT COUNT(*) FROM blackboard_messages"),
+          unconsumed_messages: @db.get_first_value("SELECT COUNT(*) FROM blackboard_messages WHERE consumed = 0")
+        }
+      end
+    end
+  end
+end

data/lib/kbs/blackboard/persistence/hybrid_store.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative 'store'
+require_relative 'redis_store'
+require_relative 'sqlite_store'
+
+module KBS
+  module Blackboard
+    module Persistence
+      # Hybrid store combining Redis (facts, messages) with SQLite (audit trail)
+      #
+      # Benefits:
+      # - Fast in-memory fact access via Redis
+      # - Durable audit trail via SQLite
+      # - Best of both worlds for production systems
+      class HybridStore < Store
+        attr_reader :redis_store, :sqlite_store, :session_id
+
+        def initialize(
+          redis_url: 'redis://localhost:6379/0',
+          redis: nil,
+          db_path: 'audit.db',
+          session_id: nil
+        )
+          @session_id = session_id
+
+          # Redis for hot data (facts, messages)
+          @redis_store = RedisStore.new(
+            url: redis_url,
+            redis: redis,
+            session_id: @session_id
+          )
+
+          # SQLite for cold data (audit trail)
+          @sqlite_store = SqliteStore.new(
+            db_path: db_path,
+            session_id: @session_id
+          )
+        end
+
+        # Fact operations delegated to Redis (fast)
+        def add_fact(uuid, type, attributes)
+          @redis_store.add_fact(uuid, type, attributes)
+        end
+
+        def remove_fact(uuid)
+          @redis_store.remove_fact(uuid)
+        end
+
+        def update_fact(uuid, attributes)
+          @redis_store.update_fact(uuid, attributes)
+        end
+
+        def get_fact(uuid)
+          @redis_store.get_fact(uuid)
+        end
+
+        def get_facts(type = nil, pattern = {})
+          @redis_store.get_facts(type, pattern)
+        end
+
+        def query_facts(conditions = nil, params = [])
+          @redis_store.query_facts(conditions, params)
+        end
+
+        def register_knowledge_source(name, description: nil, topics: [])
+          @redis_store.register_knowledge_source(name, description: description, topics: topics)
+        end
+
+        def clear_session(session_id)
+          @redis_store.clear_session(session_id)
+        end
+
+        # Stats combined from both stores
+        def stats
+          redis_stats = @redis_store.stats
+          sqlite_stats = @sqlite_store.stats
+
+          # Prefer Redis for fact counts (authoritative)
+          redis_stats.merge(
+            audit_records: sqlite_stats[:total_facts] # SQLite tracks audit records
+          )
+        end
+
+        def vacuum
+          @redis_store.vacuum
+          @sqlite_store.vacuum
+        end
+
+        def transaction(&block)
+          # Redis and SQLite transactions are separate
+          # Execute block in context of both
+          yield
+        end
+
+        def close
+          @redis_store.close
+          @sqlite_store.close
+        end
+
+        # Provide access to both connections for MessageQueue/AuditLog
+        # Memory class will detect hybrid store and use appropriate components
+        def connection
+          @redis_store.connection
+        end
+
+        def db
+          @sqlite_store.db
+        end
+
+        # Helper to check if this is a hybrid store
+        def hybrid?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/kbs/blackboard/persistence/redis_store.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'redis'
+require 'json'
+require 'securerandom'
+require_relative 'store'
+
+module KBS
+  module Blackboard
+    module Persistence
+      class RedisStore < Store
+        attr_reader :redis, :session_id
+
+        def initialize(url: 'redis://localhost:6379/0', session_id: nil, redis: nil)
+          @session_id = session_id || SecureRandom.uuid
+          @redis = redis || Redis.new(url: url)
+          @transaction_depth = 0
+        end
+
+        def add_fact(uuid, type, attributes)
+          attributes_json = JSON.generate(attributes)
+          timestamp = Time.now.to_f
+
+          @redis.multi do |pipeline|
+            pipeline.hset("fact:#{uuid}", {
+              'uuid' => uuid,
+              'type' => type.to_s,
+              'attributes' => attributes_json,
+              'session_id' => @session_id,
+              'created_at' => timestamp,
+              'updated_at' => timestamp,
+              'retracted' => '0'
+            })
+
+            # Indexes
+            pipeline.sadd('facts:active', uuid)
+            pipeline.sadd("facts:type:#{type}", uuid)
+            pipeline.sadd("facts:session:#{@session_id}", uuid) if @session_id
+            pipeline.sadd('facts:all', uuid)
+          end
+        end
+
+        def remove_fact(uuid)
+          fact_data = @redis.hgetall("fact:#{uuid}")
+          return nil if fact_data.empty? || fact_data['retracted'] == '1'
+
+          type = fact_data['type'].to_sym
+          attributes = JSON.parse(fact_data['attributes'], symbolize_names: true)
+
+          @redis.multi do |pipeline|
+            pipeline.hset("fact:#{uuid}", 'retracted', '1')
+            pipeline.hset("fact:#{uuid}", 'retracted_at', Time.now.to_f)
+            pipeline.srem('facts:active', uuid)
+            pipeline.srem("facts:type:#{type}", uuid)
+          end
+
+          { type: type, attributes: attributes }
+        end
+
+        def update_fact(uuid, attributes)
+          fact_data = @redis.hgetall("fact:#{uuid}")
+          return nil if fact_data.empty? || fact_data['retracted'] == '1'
+
+          attributes_json = JSON.generate(attributes)
+
+          @redis.multi do |pipeline|
+            pipeline.hset("fact:#{uuid}", 'attributes', attributes_json)
+            pipeline.hset("fact:#{uuid}", 'updated_at', Time.now.to_f)
+          end
+
+          fact_data['type'].to_sym
+        end
+
+        def get_fact(uuid)
+          fact_data = @redis.hgetall("fact:#{uuid}")
+          return nil if fact_data.empty? || fact_data['retracted'] == '1'
+
+          {
+            uuid: fact_data['uuid'],
+            type: fact_data['type'].to_sym,
+            attributes: JSON.parse(fact_data['attributes'], symbolize_names: true)
+          }
+        end
+
+        def get_facts(type = nil, pattern = {})
+          # Get UUIDs from appropriate index
+          uuids = if type
+            @redis.sinter('facts:active', "facts:type:#{type}")
+          else
+            @redis.smembers('facts:active')
+          end
+
+          # Fetch and filter facts
+          facts = []
+          uuids.each do |uuid|
+            fact_data = @redis.hgetall("fact:#{uuid}")
+            next if fact_data.empty? || fact_data['retracted'] == '1'
+
+            attributes = JSON.parse(fact_data['attributes'], symbolize_names: true)
+
+            if matches_pattern?(attributes, pattern)
+              facts << {
+                uuid: fact_data['uuid'],
+                type: fact_data['type'].to_sym,
+                attributes: attributes
+              }
+            end
+          end
+
+          facts
+        end
+
+        def query_facts(conditions = nil, params = [])
+          # Redis doesn't support SQL queries
+          # For complex queries, use get_facts with pattern matching
+          # or implement custom Redis Lua scripts
+          get_facts
+        end
+
+        def register_knowledge_source(name, description: nil, topics: [])
+          topics_json = JSON.generate(topics)
+
+          @redis.hset("ks:#{name}", {
+            'name' => name,
+            'description' => description,
+            'topics' => topics_json,
+            'active' => '1',
+            'registered_at' => Time.now.to_f
+          })
+
+          @redis.sadd('knowledge_sources:active', name)
+        end
+
+        def clear_session(session_id)
+          uuids = @redis.smembers("facts:session:#{session_id}")
+
+          uuids.each do |uuid|
+            remove_fact(uuid)
+          end
+
+          @redis.del("facts:session:#{session_id}")
+        end
+
+        def vacuum
+          # Remove retracted facts from Redis to free memory
+          all_uuids = @redis.smembers('facts:all')
+
+          all_uuids.each do |uuid|
+            fact_data = @redis.hgetall("fact:#{uuid}")
+            if fact_data['retracted'] == '1'
+              # Calculate if fact is old enough to remove (e.g., > 30 days)
+              retracted_at = fact_data['retracted_at'].to_f
+              if Time.now.to_f - retracted_at > (30 * 24 * 60 * 60)
+                type = fact_data['type']
+                session_id = fact_data['session_id']
+
+                @redis.multi do |pipeline|
+                  pipeline.del("fact:#{uuid}")
+                  pipeline.srem('facts:all', uuid)
+                  pipeline.srem("facts:type:#{type}", uuid)
+                  pipeline.srem("facts:session:#{session_id}", uuid) if session_id
+                end
+              end
+            end
+          end
+        end
+
+        def stats
+          active_count = @redis.scard('facts:active')
+          total_count = @redis.scard('facts:all')
+          ks_count = @redis.scard('knowledge_sources:active')
+
+          {
+            total_facts: total_count,
+            active_facts: active_count,
+            knowledge_sources: ks_count
+          }
+        end
+
+        def transaction(&block)
+          @transaction_depth += 1
+          begin
+            if @transaction_depth == 1
+              # Redis MULTI/EXEC happens in individual operations
+              # This provides a consistent interface
+              yield
+            else
+              yield
+            end
+          ensure
+            @transaction_depth -= 1
+          end
+        end
+
+        def close
+          @redis.close if @redis
+        end
+
+        # Redis-specific helper to get connection for MessageQueue/AuditLog
+        def connection
+          @redis
+        end
+
+        private
+
+        def matches_pattern?(attributes, pattern)
+          pattern.all? do |key, value|
+            if value.is_a?(Proc)
+              attributes[key] && value.call(attributes[key])
+            else
+              attributes[key] == value
+            end
+          end
+        end
+      end
+    end
+  end
+end