kbs 0.1.0 → 0.2.1

data/docs/index.md

@@ -29,32 +29,30 @@ KBS (Knowledge-Based Systems) is a powerful Ruby gem that brings production rule
 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 = [
+kb = KBS.knowledge_base do
+  # Define a rule using the DSL
+  rule "buy_signal" do
     # Stock price is below threshold
-    Condition.new(:stock, { symbol: :symbol?, price: :price? }),
-    Condition.new(:threshold, { symbol: :symbol?, buy_below: :threshold? }),
+    on :stock, symbol: :symbol?, price: :price?
+    on :threshold, symbol: :symbol?, buy_below: :threshold?
 
     # No pending order exists (negation)
-    Condition.new(:order, { symbol: :symbol? }, negated: true)
-  ]
+    without :order, symbol: :symbol?
 
-  r.action = lambda do |facts, bindings|
-    if bindings[:price?] < bindings[:threshold?]
-      puts "BUY #{bindings[:symbol?]} at #{bindings[:price?]}"
+    perform do |facts, bindings|
+      if bindings[:price?] < bindings[:threshold?]
+        puts "BUY #{bindings[:symbol?]} at #{bindings[:price?]}"
+      end
     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)
+  # Add facts to working memory
+  fact :stock, symbol: "AAPL", price: 145.50
+  fact :threshold, symbol: "AAPL", buy_below: 150.0
 
-# Fire matching rules
-engine.run  # => BUY AAPL at 145.5
+  # Fire matching rules
+  run  # => BUY AAPL at 145.5
+end
 ```
 
 ## Why RETE?

data/docs/quick-start.md

@@ -6,66 +6,53 @@ Get up and running with KBS in 5 minutes.
 
 Let's build a simple temperature monitoring system that alerts when readings are abnormal.
 
-### Step 1: Create the Engine
+### Step 1: Create a Knowledge Base and Define Rules
 
 ```ruby
 require 'kbs'
 
-# Create a RETE engine
-engine = KBS::Engine.new
-```
-
-### Step 2: Define Rules
+kb = KBS.knowledge_base do
+  # Rule 1: Alert on high temperature
+  rule "high_temperature_alert" do
+    on :sensor, id: :id?, temp: :temp?
 
-```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"
+    perform do |facts, bindings|
+      if bindings[:temp?] > 75
+        puts "⚠️  HIGH TEMP Alert: Sensor #{bindings[:id?]} at #{bindings[:temp?]}°F"
+      end
     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" })
-  ]
+  # Rule 2: Alert when cooling system is offline AND temp is high
+  rule "critical_condition", priority: 10 do
+    on :sensor, id: :id?, temp: :temp?
+    on :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!"
+    perform do |facts, bindings|
+      if bindings[:temp?] > 75
+        puts "🚨 CRITICAL: Sensor #{bindings[:id?]} at #{bindings[:temp?]}°F with cooling OFFLINE!"
+      end
     end
   end
 end
-
-engine.add_rule(critical_rule)
 ```
 
-### Step 3: Add Facts
+### Step 2: 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)
+kb.fact :sensor, id: "room_101", temp: 72
+kb.fact :sensor, id: "server_rack", temp: 82
+kb.fact :sensor, id: "storage", temp: 65
 
 # Add cooling system status
-engine.add_fact(:cooling, id: "server_rack", status: "offline")
+kb.fact :cooling, id: "server_rack", status: "offline"
 ```
 
-### Step 4: Run Rules
+### Step 3: Run Rules
 
 ```ruby
-engine.run
+kb.run
 # Output:
 # => ⚠️  HIGH TEMP Alert: Sensor server_rack at 82°F
 # => 🚨 CRITICAL: Sensor server_rack at 82°F with cooling OFFLINE!
@@ -73,10 +60,10 @@ engine.run
 
 ## 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
+1. **Knowledge Base Creation**: `KBS.knowledge_base do...end` creates the RETE network and defines rules
+2. **Rule Definition**: Rules are compiled into the discrimination network using the DSL
+3. **Fact Assertion**: `kb.fact` adds facts that propagate through the network, creating partial matches
+4. **Rule Firing**: `kb.run` executes actions for all complete matches
 
 The critical rule fires because:
 - Sensor "server_rack" temp (82°F) > 75
@@ -88,30 +75,28 @@ The critical rule fires because:
 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? }),
+kb = KBS.knowledge_base do
+  # Alert when sensor has NO recent reading
+  rule "stale_sensor" do
+    on :sensor_registered, id: :id?
     # No recent reading exists (negation!)
-    KBS::Condition.new(:sensor, { id: :id? }, negated: true)
-  ]
+    without :sensor, id: :id?
 
-  r.action = lambda do |facts, bindings|
-    puts "⚠️  No reading from sensor #{bindings[:id?]}"
+    perform do |facts, bindings|
+      puts "⚠️  No reading from sensor #{bindings[:id?]}"
+    end
   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")
+  # Register sensors
+  fact :sensor_registered, id: "room_101"
+  fact :sensor_registered, id: "room_102"
 
-# Only add reading for room_101
-engine.add_fact(:sensor, id: "room_101", temp: 70)
+  # Only add reading for room_101
+  fact :sensor, id: "room_101", temp: 70
 
-engine.run
-# => ⚠️  No reading from sensor room_102
+  run
+  # => ⚠️  No reading from sensor room_102
+end
 ```
 
 ## Persistent Blackboard Memory
@@ -124,12 +109,22 @@ 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)
+kb = KBS.knowledge_base(engine: engine) do
+  rule "temperature_monitor" do
+    on :sensor, temp: greater_than(75)
+    perform do |facts|
+      puts "High temp alert!"
+    end
+  end
+
+  # Facts survive restarts
+  fact :sensor, id: "room_101", temp: 72
+
+  run
+end
 
 # Query historical data
-memory = engine.working_memory
-audit = memory.audit_log.recent_changes(limit: 10)
+audit = engine.blackboard.get_history(limit: 10)
 ```
 
 ## Next Steps
@@ -143,9 +138,9 @@ audit = memory.audit_log.recent_changes(limit: 10)
 
 ### 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
+- **[Stock Trading Examples](examples/index.md#stock-trading-systems)** - Build a trading signal system
+- **[Expert System Examples](examples/index.md#expert-systems)** - Diagnostic and decision support
+- **[Blackboard & Multi-Agent Examples](examples/index.md#advanced-features)** - Collaborative problem-solving
 
 ### Advanced Topics
 
@@ -164,17 +159,16 @@ audit = memory.audit_log.recent_changes(limit: 10)
 ### 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"
+kb = KBS.knowledge_base do
+  rule "recent_spike" do
+    on :reading,
+       sensor: :id?,
+       temp: :temp?,
+       timestamp: ->(ts) { Time.now - ts < 300 }  # Within 5 minutes
+
+    perform do |facts, bindings|
+      puts "Recent spike: #{bindings[:temp?]}°F"
+    end
   end
 end
 ```
@@ -182,15 +176,15 @@ 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!"
+kb = KBS.knowledge_base do
+  rule "above_threshold" do
+    on :reading, sensor: :id?, value: :val?
+    on :threshold, sensor: :id?, max: :max?
+
+    perform do |facts, bindings|
+      if bindings[:val?] > bindings[:max?]
+        puts "Threshold exceeded!"
+      end
     end
   end
 end
@@ -199,20 +193,19 @@ 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 }),
+kb = KBS.knowledge_base do
+  # Transition from "init" to "ready"
+  rule "init_to_ready" do
+    on :state, current: "init"
+    on :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")
+    without :state, current: "ready"
+
+    perform do |facts|
+      # Note: For state transitions, you'd typically use engine methods
+      # This is a simplified example
+      puts "Transitioning to ready state"
+    end
   end
 end
 ```