kbs 0.0.1

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

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require 'sqlite3'
+require 'json'
+require_relative 'store'
+
+module KBS
+  module Blackboard
+    module Persistence
+      class SqliteStore < Store
+        attr_reader :db, :db_path, :session_id
+
+        def initialize(db_path: ':memory:', session_id: nil)
+          @db_path = db_path
+          @session_id = session_id
+          @transaction_depth = 0
+          setup_database
+        end
+
+        def setup_database
+          @db = SQLite3::Database.new(@db_path)
+          @db.results_as_hash = true
+          create_tables
+          create_indexes
+          setup_triggers
+        end
+
+        def create_tables
+          @db.execute_batch <<-SQL
+            CREATE TABLE IF NOT EXISTS facts (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              uuid TEXT UNIQUE NOT NULL,
+              fact_type TEXT NOT NULL,
+              attributes TEXT NOT NULL,
+              fact_timestamp TIMESTAMP,
+              market_timestamp TIMESTAMP,
+              created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+              updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+              session_id TEXT,
+              retracted BOOLEAN DEFAULT 0,
+              retracted_at TIMESTAMP,
+              data_source TEXT,
+              market_session TEXT
+            );
+
+            CREATE TABLE IF NOT EXISTS knowledge_sources (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              name TEXT UNIQUE NOT NULL,
+              description TEXT,
+              topics TEXT,
+              active BOOLEAN DEFAULT 1,
+              registered_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+          SQL
+        end
+
+        def create_indexes
+          @db.execute_batch <<-SQL
+            CREATE INDEX IF NOT EXISTS idx_facts_type ON facts(fact_type);
+            CREATE INDEX IF NOT EXISTS idx_facts_session ON facts(session_id);
+            CREATE INDEX IF NOT EXISTS idx_facts_retracted ON facts(retracted);
+            CREATE INDEX IF NOT EXISTS idx_facts_timestamp ON facts(fact_timestamp);
+            CREATE INDEX IF NOT EXISTS idx_facts_market_timestamp ON facts(market_timestamp);
+            CREATE INDEX IF NOT EXISTS idx_facts_market_session ON facts(market_session);
+          SQL
+        end
+
+        def setup_triggers
+          @db.execute_batch <<-SQL
+            CREATE TRIGGER IF NOT EXISTS update_fact_timestamp
+            AFTER UPDATE ON facts
+            BEGIN
+              UPDATE facts SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+            END;
+          SQL
+        end
+
+        def add_fact(uuid, type, attributes)
+          attributes_json = JSON.generate(attributes)
+
+          @db.execute(
+            "INSERT INTO facts (uuid, fact_type, attributes, session_id) VALUES (?, ?, ?, ?)",
+            [uuid, type.to_s, attributes_json, @session_id]
+          )
+        end
+
+        def remove_fact(uuid)
+          result = @db.get_first_row(
+            "SELECT fact_type, attributes FROM facts WHERE uuid = ? AND retracted = 0",
+            [uuid]
+          )
+
+          if result
+            @db.execute(
+              "UPDATE facts SET retracted = 1, retracted_at = CURRENT_TIMESTAMP WHERE uuid = ?",
+              [uuid]
+            )
+
+            {
+              type: result['fact_type'].to_sym,
+              attributes: JSON.parse(result['attributes'], symbolize_names: true)
+            }
+          end
+        end
+
+        def update_fact(uuid, attributes)
+          attributes_json = JSON.generate(attributes)
+
+          @db.execute(
+            "UPDATE facts SET attributes = ? WHERE uuid = ? AND retracted = 0",
+            [attributes_json, uuid]
+          )
+
+          get_fact_type(uuid)
+        end
+
+        def get_fact(uuid)
+          result = @db.get_first_row(
+            "SELECT * FROM facts WHERE uuid = ? AND retracted = 0",
+            [uuid]
+          )
+
+          if result
+            {
+              uuid: result['uuid'],
+              type: result['fact_type'].to_sym,
+              attributes: JSON.parse(result['attributes'], symbolize_names: true)
+            }
+          end
+        end
+
+        def get_facts(type = nil, pattern = {})
+          query = "SELECT * FROM facts WHERE retracted = 0"
+          params = []
+
+          if type
+            query += " AND fact_type = ?"
+            params << type.to_s
+          end
+
+          results = @db.execute(query, params)
+
+          results.map do |row|
+            attributes = JSON.parse(row['attributes'], symbolize_names: true)
+
+            if matches_pattern?(attributes, pattern)
+              {
+                uuid: row['uuid'],
+                type: row['fact_type'].to_sym,
+                attributes: attributes
+              }
+            end
+          end.compact
+        end
+
+        def query_facts(sql_conditions = nil, params = [])
+          query = "SELECT * FROM facts WHERE retracted = 0"
+          query += " AND #{sql_conditions}" if sql_conditions
+
+          results = @db.execute(query, params)
+
+          results.map do |row|
+            {
+              uuid: row['uuid'],
+              type: row['fact_type'].to_sym,
+              attributes: JSON.parse(row['attributes'], symbolize_names: true)
+            }
+          end
+        end
+
+        def register_knowledge_source(name, description: nil, topics: [])
+          topics_json = JSON.generate(topics)
+
+          @db.execute(
+            "INSERT OR REPLACE INTO knowledge_sources (name, description, topics) VALUES (?, ?, ?)",
+            [name, description, topics_json]
+          )
+        end
+
+        def clear_session(session_id)
+          @db.execute(
+            "UPDATE facts SET retracted = 1, retracted_at = CURRENT_TIMESTAMP WHERE session_id = ?",
+            [session_id]
+          )
+        end
+
+        def vacuum
+          @db.execute("VACUUM")
+        end
+
+        def stats
+          {
+            total_facts: @db.get_first_value("SELECT COUNT(*) FROM facts"),
+            active_facts: @db.get_first_value("SELECT COUNT(*) FROM facts WHERE retracted = 0"),
+            knowledge_sources: @db.get_first_value("SELECT COUNT(*) FROM knowledge_sources WHERE active = 1")
+          }
+        end
+
+        def transaction(&block)
+          @transaction_depth += 1
+          result = nil
+          begin
+            if @transaction_depth == 1
+              @db.transaction do
+                result = yield
+              end
+            else
+              result = yield
+            end
+          ensure
+            @transaction_depth -= 1
+          end
+          result
+        end
+
+        def close
+          @db.close if @db
+        end
+
+        private
+
+        def get_fact_type(uuid)
+          result = @db.get_first_row(
+            "SELECT fact_type FROM facts WHERE uuid = ?",
+            [uuid]
+          )
+          result ? result['fact_type'].to_sym : nil
+        end
+
+        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

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module KBS
+  module Blackboard
+    module Persistence
+      # Abstract interface for fact persistence
+      class Store
+        def add_fact(uuid, type, attributes)
+          raise NotImplementedError, "#{self.class} must implement #add_fact"
+        end
+
+        def remove_fact(uuid)
+          raise NotImplementedError, "#{self.class} must implement #remove_fact"
+        end
+
+        def update_fact(uuid, attributes)
+          raise NotImplementedError, "#{self.class} must implement #update_fact"
+        end
+
+        def get_fact(uuid)
+          raise NotImplementedError, "#{self.class} must implement #get_fact"
+        end
+
+        def get_facts(type = nil, pattern = {})
+          raise NotImplementedError, "#{self.class} must implement #get_facts"
+        end
+
+        def query_facts(conditions = nil, params = [])
+          raise NotImplementedError, "#{self.class} must implement #query_facts"
+        end
+
+        def clear_session(session_id)
+          raise NotImplementedError, "#{self.class} must implement #clear_session"
+        end
+
+        def stats
+          raise NotImplementedError, "#{self.class} must implement #stats"
+        end
+
+        def close
+          raise NotImplementedError, "#{self.class} must implement #close"
+        end
+
+        def vacuum
+          # Optional operation - no-op by default
+        end
+
+        def transaction(&block)
+          # Default: just execute the block
+          yield if block_given?
+        end
+      end
+    end
+  end
+end

data/lib/kbs/blackboard/redis_audit_log.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module KBS
+  module Blackboard
+    # Redis-based audit log using lists for history
+    class RedisAuditLog
+      def initialize(redis, session_id)
+        @redis = redis
+        @session_id = session_id
+      end
+
+      def log_fact_change(fact_uuid, fact_type, attributes, action)
+        attributes_json = attributes.is_a?(String) ? attributes : JSON.generate(attributes)
+        timestamp = Time.now.to_f
+
+        entry = {
+          'fact_uuid' => fact_uuid,
+          'fact_type' => fact_type.to_s,
+          'attributes' => attributes_json,
+          'action' => action,
+          'timestamp' => timestamp,
+          'session_id' => @session_id
+        }
+
+        entry_json = JSON.generate(entry)
+
+        # Add to global history (as list - newest first)
+        @redis.lpush('fact_history:all', entry_json)
+
+        # Add to fact-specific history
+        @redis.lpush("fact_history:#{fact_uuid}", entry_json)
+
+        # Optionally limit history size (e.g., keep last 10000 entries)
+        @redis.ltrim('fact_history:all', 0, 9999)
+        @redis.ltrim("fact_history:#{fact_uuid}", 0, 999)
+      end
+
+      def log_rule_firing(rule_name, fact_uuids, bindings = {})
+        timestamp = Time.now.to_f
+
+        entry = {
+          'rule_name' => rule_name,
+          'fact_uuids' => JSON.generate(fact_uuids),
+          'bindings' => JSON.generate(bindings),
+          'fired_at' => timestamp,
+          'session_id' => @session_id
+        }
+
+        entry_json = JSON.generate(entry)
+
+        # Add to global rules fired list
+        @redis.lpush('rules_fired:all', entry_json)
+
+        # Add to rule-specific history
+        @redis.lpush("rules_fired:#{rule_name}", entry_json)
+
+        # Limit size
+        @redis.ltrim('rules_fired:all', 0, 9999)
+        @redis.ltrim("rules_fired:#{rule_name}", 0, 999)
+      end
+
+      def fact_history(fact_uuid = nil, limit: 100)
+        key = fact_uuid ? "fact_history:#{fact_uuid}" : 'fact_history:all'
+        entries_json = @redis.lrange(key, 0, limit - 1)
+
+        entries_json.map do |entry_json|
+          entry = JSON.parse(entry_json, symbolize_names: true)
+          {
+            fact_uuid: entry[:fact_uuid],
+            fact_type: entry[:fact_type].to_sym,
+            attributes: JSON.parse(entry[:attributes], symbolize_names: true),
+            action: entry[:action],
+            timestamp: Time.at(entry[:timestamp]),
+            session_id: entry[:session_id]
+          }
+        end
+      end
+
+      def rule_firings(rule_name = nil, limit: 100)
+        key = rule_name ? "rules_fired:#{rule_name}" : 'rules_fired:all'
+        entries_json = @redis.lrange(key, 0, limit - 1)
+
+        entries_json.map do |entry_json|
+          entry = JSON.parse(entry_json, symbolize_names: true)
+          {
+            rule_name: entry[:rule_name],
+            fact_uuids: JSON.parse(entry[:fact_uuids]),
+            bindings: JSON.parse(entry[:bindings], symbolize_names: true),
+            fired_at: Time.at(entry[:fired_at]),
+            session_id: entry[:session_id]
+          }
+        end
+      end
+
+      def stats
+        rules_fired_count = @redis.llen('rules_fired:all')
+
+        {
+          rules_fired: rules_fired_count
+        }
+      end
+    end
+  end
+end

data/lib/kbs/blackboard/redis_message_queue.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module KBS
+  module Blackboard
+    # Redis-based message queue using sorted sets for priority ordering
+    class RedisMessageQueue
+      def initialize(redis)
+        @redis = redis
+        @message_id_counter = "message_id_counter"
+      end
+
+      def post(sender, topic, content, priority: 0)
+        message_id = @redis.incr(@message_id_counter)
+        content_json = content.is_a?(String) ? content : JSON.generate(content)
+        timestamp = Time.now.to_f
+
+        message_data = {
+          'id' => message_id,
+          'sender' => sender,
+          'topic' => topic,
+          'content' => content_json,
+          'priority' => priority,
+          'posted_at' => timestamp,
+          'consumed' => '0'
+        }
+
+        # Store message data
+        @redis.hset("message:#{message_id}", message_data)
+
+        # Add to topic queue with score = -priority (for DESC ordering) + timestamp (for ASC within priority)
+        # Score: higher priority = lower score (negative), then by timestamp
+        score = (-priority * 1_000_000) + timestamp
+        @redis.zadd("messages:#{topic}", score, message_id)
+
+        message_id
+      end
+
+      def consume(topic, consumer)
+        # Get highest priority (lowest score) unconsumed message
+        messages = @redis.zrange("messages:#{topic}", 0, 0)
+        return nil if messages.empty?
+
+        message_id = messages.first
+        message_data = @redis.hgetall("message:#{message_id}")
+
+        return nil if message_data.empty? || message_data['consumed'] == '1'
+
+        # Mark as consumed
+        @redis.multi do |pipeline|
+          pipeline.hset("message:#{message_id}", 'consumed', '1')
+          pipeline.hset("message:#{message_id}", 'consumed_by', consumer)
+          pipeline.hset("message:#{message_id}", 'consumed_at', Time.now.to_f)
+          pipeline.zrem("messages:#{topic}", message_id)
+        end
+
+        {
+          id: message_data['id'].to_i,
+          sender: message_data['sender'],
+          topic: message_data['topic'],
+          content: JSON.parse(message_data['content'], symbolize_names: true),
+          priority: message_data['priority'].to_i,
+          posted_at: Time.at(message_data['posted_at'].to_f)
+        }
+      end
+
+      def peek(topic, limit: 10)
+        # Get top N messages without consuming
+        message_ids = @redis.zrange("messages:#{topic}", 0, limit - 1)
+        messages = []
+
+        message_ids.each do |message_id|
+          message_data = @redis.hgetall("message:#{message_id}")
+          next if message_data.empty? || message_data['consumed'] == '1'
+
+          messages << {
+            id: message_data['id'].to_i,
+            sender: message_data['sender'],
+            topic: message_data['topic'],
+            content: JSON.parse(message_data['content'], symbolize_names: true),
+            priority: message_data['priority'].to_i,
+            posted_at: Time.at(message_data['posted_at'].to_f)
+          }
+        end
+
+        messages
+      end
+
+      def stats
+        # Count all unconsumed messages across all topics
+        topics = @redis.keys('messages:*')
+        total_unconsumed = 0
+
+        topics.each do |topic_key|
+          total_unconsumed += @redis.zcard(topic_key)
+        end
+
+        # Count all messages (including consumed)
+        all_message_keys = @redis.keys('message:*')
+        total_messages = all_message_keys.size
+
+        {
+          total_messages: total_messages,
+          unconsumed_messages: total_unconsumed
+        }
+      end
+    end
+  end
+end

data/lib/kbs/blackboard.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative '../kbs'
+
+# Blackboard pattern components
+require_relative 'blackboard/fact'
+require_relative 'blackboard/message_queue'
+require_relative 'blackboard/audit_log'
+require_relative 'blackboard/redis_message_queue'
+require_relative 'blackboard/redis_audit_log'
+require_relative 'blackboard/persistence/store'
+require_relative 'blackboard/persistence/sqlite_store'
+require_relative 'blackboard/persistence/redis_store'
+require_relative 'blackboard/persistence/hybrid_store'
+require_relative 'blackboard/memory'
+require_relative 'blackboard/engine'
+
+# Backward compatibility aliases (deprecated - will be removed in v1.0)
+module KBS
+  BlackboardMemory = Blackboard::Memory
+  BlackboardEngine = Blackboard::Engine
+  PersistedFact = Blackboard::Fact
+end

data/lib/kbs/condition.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module KBS
+  class Condition
+    attr_reader :type, :pattern, :variable_bindings, :negated
+
+    def initialize(type, pattern = {}, negated: false)
+      @type = type
+      @pattern = pattern
+      @negated = negated
+      @variable_bindings = extract_variables(pattern)
+    end
+
+    private
+
+    def extract_variables(pattern)
+      vars = {}
+      pattern.each do |key, value|
+        if value.is_a?(Symbol) && value.to_s.start_with?('?')
+          vars[value] = key
+        end
+      end
+      vars
+    end
+  end
+end

data/lib/kbs/dsl/condition_helpers.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module KBS
+  module DSL
+    module ConditionHelpers
+      def less_than(value)
+        ->(v) { v < value }
+      end
+
+      def greater_than(value)
+        ->(v) { v > value }
+      end
+
+      def equals(value)
+        value
+      end
+
+      def not_equal(value)
+        ->(v) { v != value }
+      end
+
+      def one_of(*values)
+        ->(v) { values.include?(v) }
+      end
+
+      def range(min_or_range, max = nil)
+        if min_or_range.is_a?(Range)
+          ->(v) { min_or_range.include?(v) }
+        else
+          ->(v) { v >= min_or_range && v <= max }
+        end
+      end
+
+      def between(min, max)
+        range(min, max)
+      end
+
+      def any(*values)
+        if values.empty?
+          # Match anything
+          ->(v) { true }
+        else
+          # Match one of the values
+          one_of(*values)
+        end
+      end
+
+      def matches(pattern)
+        ->(v) { v.match?(pattern) }
+      end
+
+      def satisfies(&block)
+        block
+      end
+    end
+  end
+end

data/lib/kbs/dsl/knowledge_base.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module KBS
+  module DSL
+    class KnowledgeBase
+      attr_reader :engine, :rules
+
+      def initialize
+        @engine = ReteEngine.new
+        @rules = {}
+        @rule_builders = {}
+      end
+
+      def rule(name, &block)
+        builder = RuleBuilder.new(name)
+        builder.instance_eval(&block) if block_given?
+        @rule_builders[name] = builder
+        rule = builder.build
+        @rules[name] = rule
+        @engine.add_rule(rule)
+        builder
+      end
+
+      def defrule(name, &block)
+        rule(name, &block)
+      end
+
+      def fact(type, attributes = {})
+        @engine.add_fact(type, attributes)
+      end
+
+      def assert(type, attributes = {})
+        fact(type, attributes)
+      end
+
+      def retract(fact)
+        @engine.remove_fact(fact)
+      end
+
+      def run
+        @engine.run
+      end
+
+      def reset
+        @engine.working_memory.facts.clear
+      end
+
+      def facts
+        @engine.working_memory.facts
+      end
+
+      def query(type, pattern = {})
+        @engine.working_memory.facts.select do |fact|
+          next false unless fact.type == type
+          pattern.all? { |key, value| fact.attributes[key] == value }
+        end
+      end
+
+      def print_facts
+        puts "Working Memory Contents:"
+        puts "-" * 40
+        facts.each_with_index do |fact, i|
+          puts "#{i + 1}. #{fact}"
+        end
+        puts "-" * 40
+      end
+
+      def print_rules
+        puts "Knowledge Base Rules:"
+        puts "-" * 40
+        @rule_builders.each do |name, builder|
+          puts "Rule: #{name}"
+          puts "  Description: #{builder.description}" if builder.description
+          puts "  Priority: #{builder.priority}"
+          puts "  Conditions: #{builder.conditions.size}"
+          builder.conditions.each_with_index do |cond, i|
+            negated = cond.negated ? "NOT " : ""
+            puts "    #{i + 1}. #{negated}#{cond.type}(#{cond.pattern})"
+          end
+          puts ""
+        end
+        puts "-" * 40
+      end
+    end
+  end
+end