kbs 0.0.1 → 0.1.0

data/docs/index.md

@@ -0,0 +1,157 @@
+![KBS - Knowledge-Based System](assets/images/kbs.jpg)
+
+# KBS - Knowledge-Based Systems for Ruby
+
+**A Ruby implementation of the RETE algorithm for building intelligent, rule-based systems with persistent memory.**
+
+[![Gem Version](https://badge.fury.io/rb/kbs.svg)](https://badge.fury.io/rb/kbs)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-ruby.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## What is KBS?
+
+KBS (Knowledge-Based Systems) is a powerful Ruby gem that brings production rule systems to your applications. At its core is the **RETE algorithm**, a highly optimized pattern-matching engine originally developed for expert systems and now used in modern applications ranging from trading systems to IoT automation.
+
+### Key Features
+
+- **🚀 RETE Algorithm**: State-of-the-art pattern matching with unlinking optimization
+- **💾 Persistent Blackboard Memory**: SQLite, Redis, or hybrid storage for facts and audit trails
+- **🎯 Declarative DSL**: Write rules in natural, readable Ruby syntax
+- **🔄 Incremental Matching**: Process only changes, not entire fact sets
+- **🚫 Negation Support**: Express "absence of pattern" conditions naturally
+- **📊 Multi-Agent Systems**: Build collaborative systems with message passing
+- **🔍 Full Auditability**: Complete history of fact changes and rule firings
+- **⚡ High Performance**: Handle millions of facts with sub-millisecond updates
+
+## Quick Example
+
+```ruby
+require 'kbs'
+
+# Create a rule-based trading system
+engine = KBS::Engine.new
+
+# Define a rule using the DSL
+engine.add_rule(Rule.new("buy_signal") do |r|
+  r.conditions = [
+    # Stock price is below threshold
+    Condition.new(:stock, { symbol: :symbol?, price: :price? }),
+    Condition.new(:threshold, { symbol: :symbol?, buy_below: :threshold? }),
+
+    # No pending order exists (negation)
+    Condition.new(:order, { symbol: :symbol? }, negated: true)
+  ]
+
+  r.action = lambda do |facts, bindings|
+    if bindings[:price?] < bindings[:threshold?]
+      puts "BUY #{bindings[:symbol?]} at #{bindings[:price?]}"
+    end
+  end
+end)
+
+# Add facts to working memory
+engine.add_fact(:stock, symbol: "AAPL", price: 145.50)
+engine.add_fact(:threshold, symbol: "AAPL", buy_below: 150.0)
+
+# Fire matching rules
+engine.run  # => BUY AAPL at 145.5
+```
+
+## Why RETE?
+
+Traditional rule engines re-evaluate all rules against all facts on every change—extremely inefficient. RETE solves this through:
+
+1. **Network Compilation**: Rules are compiled into a discrimination network that shares common patterns
+2. **State Preservation**: Partial matches are cached between cycles
+3. **Incremental Updates**: Only changed facts propagate through the network
+4. **Unlinking Optimization (RETE)**: Empty nodes automatically disconnect to skip unnecessary work
+
+Result: **Near-constant time** per fact change, regardless of rule set size.
+
+## Use Cases
+
+### 💹 Algorithmic Trading
+Real-time market analysis, signal detection, and automated order execution with complex multi-condition rules.
+
+### 🏭 Industrial Automation
+IoT sensor monitoring, predictive maintenance, and automated control systems with temporal reasoning.
+
+### 🏥 Expert Systems
+Medical diagnosis, troubleshooting assistants, and decision support systems with knowledge representation.
+
+### 🤖 Multi-Agent Systems
+Collaborative agents with shared blackboard memory for distributed problem-solving.
+
+### 📧 Business Rules Engines
+Policy enforcement, workflow automation, and compliance checking with auditable decision trails.
+
+## Architecture
+
+KBS consists of several integrated components:
+
+- **RETE Engine**: Core pattern matching and rule execution
+- **Working Memory**: Transient in-memory fact storage
+- **Blackboard System**: Persistent memory with SQLite/Redis backends
+- **DSL**: Natural language rule definition syntax
+- **Message Queue**: Priority-based inter-agent communication
+- **Audit Log**: Complete history for compliance and debugging
+
+See [Architecture Overview](architecture/index.md) for details.
+
+## Getting Started
+
+1. **[Installation](installation.md)** - Add KBS to your project
+2. **[Quick Start](quick-start.md)** - Build your first rule-based system in 5 minutes
+3. **[RETE Algorithm](architecture/rete-algorithm.md)** - Deep dive into how it works
+4. **[Writing Rules](guides/writing-rules.md)** - Master the DSL and pattern matching
+5. **[Examples](examples/index.md)** - Learn from real-world applications
+
+## Performance
+
+KBS is built for production workloads:
+
+- **Fact Addition**: O(N) where N = activated nodes (typically << total nodes)
+- **Rule Firing**: O(M) where M = matched tokens
+- **Memory Efficient**: Network sharing reduces redundant storage
+- **Scalable**: Tested with millions of facts, thousands of rules
+
+Benchmarks on M2 Max:
+- Add 100,000 facts: ~500ms
+- Match complex 5-condition rule: <1ms per fact
+- Redis backend: 100x faster than SQLite for high-frequency updates
+
+## Project Status
+
+KBS is **actively maintained**:
+
+- ✅ Core RETE implementation complete
+- ✅ Persistent blackboard with multiple backends
+- ✅ Full DSL support with negation
+- ✅ Comprehensive test coverage
+- ✅ Real-world usage in trading systems
+- 🚧 Additional examples and guides in progress
+
+## Community & Support
+
+- **GitHub**: [madbomber/kbs](https://github.com/madbomber/kbs)
+- **RubyGems**: [kbs](https://rubygems.org/gems/kbs)
+- **Issues**: [Report bugs or request features](https://github.com/madbomber/kbs/issues)
+- **Discussions**: [Ask questions](https://github.com/madbomber/kbs/discussions)
+
+## License
+
+KBS is released under the [MIT License](https://opensource.org/licenses/MIT).
+
+Copyright © 2024 Dewayne VanHoozer
+
+## Acknowledgments
+
+The RETE algorithm was invented by Charles Forgy in 1979. This implementation draws inspiration from:
+
+- Forgy, C. (1982). "Rete: A Fast Algorithm for the Many Pattern/Many Object Pattern Match Problem"
+- Doorenbos, R. (1995). "Production Matching for Large Learning Systems" (RETE/UL)
+- Modern production rule systems: Drools, Jess, CLIPS
+
+---
+
+**Ready to build intelligent systems?** Start with the [Quick Start Guide](quick-start.md)!

data/docs/installation.md

@@ -0,0 +1,156 @@
+# Installation
+
+## Requirements
+
+- **Ruby**: 2.7 or higher
+- **SQLite3**: For persistent blackboard memory (optional)
+- **Redis**: For high-performance persistence (optional)
+
+## Installing the Gem
+
+### From RubyGems
+
+```bash
+gem install kbs
+```
+
+### Using Bundler
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'kbs'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### From Source
+
+```bash
+git clone https://github.com/madbomber/kbs.git
+cd kbs
+bundle install
+rake install
+```
+
+## Optional Dependencies
+
+### SQLite3 (Default Blackboard Backend)
+
+```bash
+gem install sqlite3
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem 'sqlite3'
+```
+
+### Redis (High-Performance Backend)
+
+Install Redis server:
+
+```bash
+# macOS
+brew install redis
+brew services start redis
+
+# Ubuntu/Debian
+sudo apt-get install redis-server
+sudo systemctl start redis
+
+# Docker
+docker run -d -p 6379:6379 redis:latest
+```
+
+Install Ruby Redis gem:
+
+```bash
+gem install redis
+```
+
+Or in your `Gemfile`:
+
+```ruby
+gem 'redis'
+```
+
+## Verification
+
+Verify the installation:
+
+```ruby
+require 'kbs'
+
+puts "KBS version: #{KBS::VERSION}"
+# => KBS version: 0.1.0
+
+# Test basic functionality
+engine = KBS::Engine.new
+engine.add_fact(:test, value: 42)
+puts "✓ KBS is working!"
+```
+
+## Development Setup
+
+For contributing or running tests:
+
+```bash
+git clone https://github.com/madbomber/kbs.git
+cd kbs
+bundle install
+
+# Run tests
+bundle exec rake test
+
+# Run examples
+bundle exec ruby examples/working_demo.rb
+```
+
+## Troubleshooting
+
+### SQLite3 Installation Issues
+
+On macOS with M1/M2:
+
+```bash
+gem install sqlite3 -- --with-sqlite3-include=/opt/homebrew/opt/sqlite/include \
+  --with-sqlite3-lib=/opt/homebrew/opt/sqlite/lib
+```
+
+On Ubuntu/Debian:
+
+```bash
+sudo apt-get install libsqlite3-dev
+gem install sqlite3
+```
+
+### Redis Connection Issues
+
+Check Redis is running:
+
+```bash
+redis-cli ping
+# => PONG
+```
+
+Test connection from Ruby:
+
+```ruby
+require 'redis'
+redis = Redis.new(url: 'redis://localhost:6379/0')
+redis.ping
+# => "PONG"
+```
+
+## Next Steps
+
+- **[Quick Start Guide](quick-start.md)** - Build your first rule-based system
+- **[RETE Algorithm](architecture/rete-algorithm.md)** - Understand the engine
+- **[Writing Rules](guides/writing-rules.md)** - Master the DSL
+- **[Examples](examples/index.md)** - See real-world applications

data/docs/quick-start.md

@@ -0,0 +1,228 @@
+# Quick Start Guide
+
+Get up and running with KBS in 5 minutes.
+
+## Your First Rule-Based System
+
+Let's build a simple temperature monitoring system that alerts when readings are abnormal.
+
+### Step 1: Create the Engine
+
+```ruby
+require 'kbs'
+
+# Create a RETE engine
+engine = KBS::Engine.new
+```
+
+### Step 2: Define Rules
+
+```ruby
+# Rule 1: Alert on high temperature
+high_temp_rule = KBS::Rule.new("high_temperature_alert") do |r|
+  r.conditions = [
+    KBS::Condition.new(:sensor, { id: :id?, temp: :temp? })
+  ]
+
+  r.action = lambda do |facts, bindings|
+    if bindings[:temp?] > 75
+      puts "⚠️  HIGH TEMP Alert: Sensor #{bindings[:id?]} at #{bindings[:temp?]}°F"
+    end
+  end
+end
+
+engine.add_rule(high_temp_rule)
+
+# Rule 2: Alert when cooling system is offline AND temp is high
+critical_rule = KBS::Rule.new("critical_condition", priority: 10) do |r|
+  r.conditions = [
+    KBS::Condition.new(:sensor, { id: :id?, temp: :temp? }),
+    KBS::Condition.new(:cooling, { id: :id?, status: "offline" })
+  ]
+
+  r.action = lambda do |facts, bindings|
+    if bindings[:temp?] > 75
+      puts "🚨 CRITICAL: Sensor #{bindings[:id?]} at #{bindings[:temp?]}°F with cooling OFFLINE!"
+    end
+  end
+end
+
+engine.add_rule(critical_rule)
+```
+
+### Step 3: Add Facts
+
+```ruby
+# Add sensor readings
+engine.add_fact(:sensor, id: "room_101", temp: 72)
+engine.add_fact(:sensor, id: "server_rack", temp: 82)
+engine.add_fact(:sensor, id: "storage", temp: 65)
+
+# Add cooling system status
+engine.add_fact(:cooling, id: "server_rack", status: "offline")
+```
+
+### Step 4: Run Rules
+
+```ruby
+engine.run
+# Output:
+# => ⚠️  HIGH TEMP Alert: Sensor server_rack at 82°F
+# => 🚨 CRITICAL: Sensor server_rack at 82°F with cooling OFFLINE!
+```
+
+## Understanding What Happened
+
+1. **Engine Creation**: `Engine.new` builds an empty RETE network
+2. **Rule Addition**: Rules are compiled into the discrimination network
+3. **Fact Assertion**: Facts propagate through the network, creating partial matches
+4. **Rule Firing**: `engine.run()` executes actions for all complete matches
+
+The critical rule fires because:
+- Sensor "server_rack" temp (82°F) > 75
+- Cooling system for "server_rack" is offline
+- Both conditions are joined on the same `:id?` variable
+
+## Using Negation
+
+Rules can match on the **absence** of facts:
+
+```ruby
+# Alert when sensor has NO recent reading
+stale_sensor_rule = KBS::Rule.new("stale_sensor") do |r|
+  r.conditions = [
+    KBS::Condition.new(:sensor_registered, { id: :id? }),
+    # No recent reading exists (negation!)
+    KBS::Condition.new(:sensor, { id: :id? }, negated: true)
+  ]
+
+  r.action = lambda do |facts, bindings|
+    puts "⚠️  No reading from sensor #{bindings[:id?]}"
+  end
+end
+
+engine.add_rule(stale_sensor_rule)
+
+# Register sensors
+engine.add_fact(:sensor_registered, id: "room_101")
+engine.add_fact(:sensor_registered, id: "room_102")
+
+# Only add reading for room_101
+engine.add_fact(:sensor, id: "room_101", temp: 70)
+
+engine.run
+# => ⚠️  No reading from sensor room_102
+```
+
+## Persistent Blackboard Memory
+
+For production systems, use persistent storage:
+
+```ruby
+require 'kbs/blackboard'
+
+# SQLite backend (default)
+engine = KBS::Blackboard::Engine.new(db_path: 'monitoring.db')
+
+# Facts survive restarts
+engine.add_fact(:sensor, id: "room_101", temp: 72)
+
+# Query historical data
+memory = engine.working_memory
+audit = memory.audit_log.recent_changes(limit: 10)
+```
+
+## Next Steps
+
+### Learn the Fundamentals
+
+- **[Writing Rules](guides/writing-rules.md)** - Master rule syntax and patterns
+- **[Pattern Matching](guides/pattern-matching.md)** - Understand how facts match conditions
+- **[Variable Binding](guides/variable-binding.md)** - Use variables to join conditions
+- **[Negation](guides/negation.md)** - Express "absence" conditions
+
+### Explore Examples
+
+- **[Stock Trading](examples/stock-trading.md)** - Build a trading signal system
+- **[Expert Systems](examples/expert-systems.md)** - Diagnostic and decision support
+- **[Multi-Agent Systems](examples/multi-agent.md)** - Collaborative problem-solving
+
+### Advanced Topics
+
+- **[Blackboard Memory](guides/blackboard-memory.md)** - Persistent storage and audit trails
+- **[Performance Tuning](advanced/performance.md)** - Optimize for production workloads
+- **[Debugging](advanced/debugging.md)** - Trace rule execution and network state
+
+### Understand the Engine
+
+- **[RETE Algorithm](architecture/rete-algorithm.md)** - Deep dive into pattern matching
+- **[Network Structure](architecture/network-structure.md)** - How rules are compiled
+- **[API Reference](api/index.md)** - Complete class documentation
+
+## Common Patterns
+
+### Time-Based Rules
+
+```ruby
+rule = KBS::Rule.new("recent_spike") do |r|
+  r.conditions = [
+    KBS::Condition.new(:reading, {
+      sensor: :id?,
+      temp: :temp?,
+      timestamp: ->(ts) { Time.now - ts < 300 }  # Within 5 minutes
+    })
+  ]
+
+  r.action = lambda do |facts, bindings|
+    puts "Recent spike: #{bindings[:temp?]}°F"
+  end
+end
+```
+
+### Threshold Comparison
+
+```ruby
+rule = KBS::Rule.new("above_threshold") do |r|
+  r.conditions = [
+    KBS::Condition.new(:reading, { sensor: :id?, value: :val? }),
+    KBS::Condition.new(:threshold, { sensor: :id?, max: :max? })
+  ]
+
+  r.action = lambda do |facts, bindings|
+    if bindings[:val?] > bindings[:max?]
+      puts "Threshold exceeded!"
+    end
+  end
+end
+```
+
+### State Machine
+
+```ruby
+# Transition from "init" to "ready"
+transition_rule = KBS::Rule.new("init_to_ready") do |r|
+  r.conditions = [
+    KBS::Condition.new(:state, { current: "init" }),
+    KBS::Condition.new(:sensor, { initialized: true }),
+    # No "ready" state exists yet
+    KBS::Condition.new(:state, { current: "ready" }, negated: true)
+  ]
+
+  r.action = lambda do |facts|
+    # Remove old state
+    engine.remove_fact(facts[0])
+    # Add new state
+    engine.add_fact(:state, current: "ready")
+  end
+end
+```
+
+## Tips
+
+1. **Use descriptive rule names**: Makes debugging easier
+2. **Set priorities**: Higher priority rules fire first
+3. **Call `run()` explicitly**: Rules don't fire automatically
+4. **Leverage negation**: Express "when X is absent" naturally
+5. **Profile performance**: Use `advanced/debugging.md` techniques
+
+Ready to dive deeper? Check out the [Writing Rules Guide](guides/writing-rules.md)!

data/examples/README.md

@@ -1,6 +1,6 @@
 # KBS Examples
 
-This directory contains comprehensive examples demonstrating the capabilities of the KBS (Knowledge-Based System) gem. Each example showcases different features and use cases of the RETE II inference engine and blackboard architecture.
+This directory contains comprehensive examples demonstrating the capabilities of the KBS (Knowledge-Based System) gem. Each example showcases different features and use cases of the RETE inference engine and blackboard architecture.
 
 ## Table of Contents
 
@@ -421,7 +421,7 @@ export OLLAMA_MODEL=gpt-oss:latest
 ## Summary of Capabilities
 
 ### Core KBS Features
-- ✅ RETE II inference engine
+- ✅ RETE inference engine
 - ✅ Forward-chaining reasoning
 - ✅ Pattern matching
 - ✅ Negated conditions

data/examples/advanced_example.rb

@@ -4,7 +4,7 @@ require_relative '../lib/kbs'
 
 class StockTradingExpertSystem
   def initialize
-    @engine = KBS::ReteEngine.new
+    @engine = KBS::Engine.new
     setup_rules
   end
   
@@ -137,7 +137,7 @@ end
 
 class NetworkDiagnosticSystem
   def initialize
-    @engine = KBS::ReteEngine.new
+    @engine = KBS::Engine.new
     setup_network_rules
   end