kbs 0.1.0 → 0.2.1

data/docs/guides/dsl.md

@@ -32,7 +32,7 @@ kb = KBS.knowledge_base do
 
     on :temperature, value: greater_than(80), location: :loc?
 
-    perform do |bindings|
+    perform do |facts, bindings|
       puts "High temperature at #{bindings[:loc?]}"
     end
   end
@@ -314,7 +314,7 @@ rule "rule_name" do
   on :another_type, field: predicate
 
   # Action
-  perform do |bindings|
+  perform do |facts, bindings|
     # Code to execute
   end
 end
@@ -367,7 +367,7 @@ end
 rule "log_reading" do
   priority 1  # Low priority
   on :temperature, value: :temp?
-  perform { |b| log(b[:temp?]) }
+  perform { |facts, b| log(b[:temp?]) }
 end
 ```
 
@@ -436,7 +436,7 @@ Capture attribute values in variables (symbols starting with `?`):
 on :temperature, value: :temp?, location: :loc?
 
 # In action:
-perform do |bindings|
+perform do |facts, bindings|
   puts "Temperature: #{bindings[:temp?]}"
   puts "Location: #{bindings[:loc?]}"
 end
@@ -648,7 +648,7 @@ Variables allow you to:
 
 ### Variable Syntax
 
-Variables are symbols starting with `?`:
+Variables are symbols ending with `?`:
 
 ```ruby
 :temp?      # Variable named "temp"
@@ -664,7 +664,7 @@ Variables are symbols starting with `?`:
 rule "temperature_report" do
   on :temperature, value: :temp?, location: :loc?, timestamp: :time?
 
-  perform do |bindings|
+  perform do |facts, bindings|
     puts "Temperature at #{bindings[:loc?]}: #{bindings[:temp?]}°F"
     puts "Recorded: #{bindings[:time?]}"
   end
@@ -682,7 +682,7 @@ rule "check_inventory" do
   on :order, product_id: :pid?, quantity: :qty?
   on :inventory, product_id: :pid?, available: :avail?
 
-  perform do |bindings|
+  perform do |facts, bindings|
     if bindings[:avail?] < bindings[:qty?]
       puts "Insufficient inventory for product #{bindings[:pid?]}"
     end
@@ -705,7 +705,7 @@ rule "sensor_temperature_correlation" do
   on :temperature, sensor_id: :sensor_id?, value: :temp?
   on :reading, sensor_id: :sensor_id?, timestamp: :time?
 
-  perform do |bindings|
+  perform do |facts, bindings|
     # All three facts share the same sensor_id
     puts "Sensor #{bindings[:sensor_id?]} at #{bindings[:loc?]}"
     puts "Reading: #{bindings[:temp?]}°F at #{bindings[:time?]}"
@@ -777,7 +777,7 @@ rule "no_matching_inventory" do
   on :order, product_id: :pid?
   without :inventory, product_id: :pid?
 
-  perform do |bindings|
+  perform do |facts, bindings|
     puts "No inventory for product #{bindings[:pid?]}"
   end
 end
@@ -810,7 +810,7 @@ end
 rule "sensor_timeout" do
   on :sensor, id: :sensor_id?, expected: true
   without :reading, sensor_id: :sensor_id?
-  perform { |b| puts "Sensor #{b[:sensor_id?]} timeout" }
+  perform { |facts, b| puts "Sensor #{b[:sensor_id?]} timeout" }
 end
 ```
 
@@ -827,7 +827,7 @@ All of these are **aliases**:
 - **`perform(&block)`** - Primary action keyword
 - **`action(&block)`** - Alias
 - **`execute(&block)`** - Alias
-- **`then(&block)`** - Alias
+- **`then(&block)`** - Alias  - TODO: isn't "then" a ruby keyword?
 
 ---
 
@@ -839,7 +839,7 @@ Actions receive a `bindings` hash containing all variable bindings:
 rule "example" do
   on :temperature, value: :temp?, location: :loc?
 
-  perform do |bindings|
+  perform do |facts, bindings|
     temp = bindings[:temp?]
     location = bindings[:loc?]
     puts "Temperature at #{location}: #{temp}°F"
@@ -855,7 +855,7 @@ Actions can:
 
 1. **Read bindings**:
 ```ruby
-perform do |bindings|
+perform do |facts, bindings|
   value = bindings[:temp?]
 end
 ```
@@ -874,7 +874,7 @@ end
 
 3. **Call external methods**:
 ```ruby
-perform do |bindings|
+perform do |facts, bindings|
   send_email_alert(bindings[:temp?])
   log_to_database(bindings)
   trigger_alarm if bindings[:level?] == "critical"
@@ -883,7 +883,7 @@ end
 
 4. **Add/remove facts**:
 ```ruby
-perform do |bindings|
+perform do |facts, bindings|
   # Add derived fact
   fact :alert, level: "high", source: bindings[:sensor_id?]
 
@@ -901,7 +901,7 @@ end
 # Simple logging
 rule "log_temperature" do
   on :temperature, value: :temp?
-  perform { |b| puts "Temperature: #{b[:temp?]}" }
+  perform { |facts, b| puts "Temperature: #{b[:temp?]}" }
 end
 
 # State machine transition
@@ -909,7 +909,7 @@ rule "pending_to_processing" do
   on :order, id: :order_id?, status: "pending"
   on :worker, status: "available", id: :worker_id?
 
-  perform do |bindings|
+  perform do |facts, bindings|
     # Update order status
     order = query(:order, id: bindings[:order_id?]).first
     retract order
@@ -1079,7 +1079,7 @@ end
 kb = KBS.knowledge_base do
   rule "example" do
     on :temperature, value: :temp?
-    perform { |b| puts b[:temp?] }
+    perform { |facts, b| puts b[:temp?] }
   end
 end
 
@@ -1112,7 +1112,7 @@ kb = KBS.knowledge_base do
     on :temperature, sensor_id: :sensor_id?, value: greater_than(80)
     without :alert, sensor_id: :sensor_id?  # No existing alert
 
-    perform do |bindings|
+    perform do |facts, bindings|
       puts "⚠️  HIGH TEMPERATURE ALERT"
       puts "Sensor: #{bindings[:sensor_id?]}"
       puts "Temperature: #{bindings[:value?]}°F"
@@ -1132,7 +1132,7 @@ kb = KBS.knowledge_base do
     on :temperature, sensor_id: :sensor_id?, value: less_than(75)
     on :alert, sensor_id: :sensor_id?
 
-    perform do |bindings|
+    perform do |facts, bindings|
       puts "✓ Temperature normal for sensor #{bindings[:sensor_id?]}"
 
       # Remove alert
@@ -1167,7 +1167,7 @@ kb = KBS.knowledge_base do
     on :order, id: :order_id?, status: "new", product_id: :pid?, quantity: :qty?
     on :inventory, product_id: :pid?, quantity: :available?
 
-    perform do |bindings|
+    perform do |facts, bindings|
       if bindings[:available?] >= bindings[:qty?]
         order = query(:order, id: bindings[:order_id?]).first
         retract order
@@ -1191,7 +1191,7 @@ kb = KBS.knowledge_base do
                product_id: :pid?, quantity: :qty?
     on :inventory, product_id: :pid?, quantity: :available?
 
-    perform do |bindings|
+    perform do |facts, bindings|
       # Deduct inventory
       inventory = query(:inventory, product_id: bindings[:pid?]).first
       retract inventory
@@ -1296,13 +1296,13 @@ on :order, status: ->(s) { ["pending", "processing"].include?(s) }
 # Good - Simple, focused action
 rule "log_temperature" do
   on :temperature, value: :temp?
-  perform { |b| logger.info("Temperature: #{b[:temp?]}") }
+  perform { |facts, b| logger.info("Temperature: #{b[:temp?]}") }
 end
 
 # Avoid - Complex logic in action
 rule "complex_action" do
   on :temperature, value: :temp?
-  perform do |b|
+  perform do |facts, b|
     # 100 lines of complex logic...
     # Better to extract to methods
   end

data/docs/guides/getting-started.md

@@ -28,35 +28,35 @@ gem install kbs
 
 Let's create a simple rule that fires when temperature exceeds a threshold.
 
-### Step 1: Create the Engine
+### Step 1: Create a Knowledge Base
 
 ```ruby
 require 'kbs'
 
-# Create the inference engine
-engine = KBS::Engine.new
+# Create a knowledge base with DSL
+kb = KBS.knowledge_base do
+  # Rules will be defined here
+end
 ```
 
-The engine manages rules, facts, and executes the pattern matching algorithm.
+The knowledge base manages rules, facts, and executes the pattern matching algorithm.
 
 ### Step 2: Define a Rule
 
 ```ruby
-# Define a rule for high temperature alerts
-high_temp_rule = KBS::Rule.new("high_temperature_alert") do |r|
-  r.conditions = [
-    KBS::Condition.new(:sensor, { id: :sensor_id?, temp: :temp? }),
-    KBS::Condition.new(:threshold, { id: :sensor_id?, max: :max? })
-  ]
-
-  r.action = lambda do |facts, bindings|
-    if bindings[:temp?] > bindings[:max?]
-      puts "🚨 ALERT: Sensor #{bindings[:sensor_id?]} at #{bindings[:temp?]}°C"
+kb = KBS.knowledge_base do
+  # Define a rule for high temperature alerts
+  rule "high_temperature_alert" do
+    on :sensor, id: :sensor_id?, temp: :temp?
+    on :threshold, id: :sensor_id?, max: :max?
+
+    perform do |facts, bindings|
+      if bindings[:temp?] > bindings[:max?]
+        puts "🚨 ALERT: Sensor #{bindings[:sensor_id?]} at #{bindings[:temp?]}°C"
+      end
     end
   end
 end
-
-engine.add_rule(high_temp_rule)
 ```
 
 **What this rule does:**
@@ -67,24 +67,32 @@ engine.add_rule(high_temp_rule)
 
 **Variable binding** (`:sensor_id?`) ensures we only compare sensors with their own thresholds.
 
-### Step 3: Add Facts
+### Step 3: Add Facts and Run
 
 ```ruby
-# Add sensor reading
-engine.add_fact(:sensor, id: "bedroom", temp: 28)
-
-# Add threshold
-engine.add_fact(:threshold, id: "bedroom", max: 25)
-```
-
-Facts are observations about the world. The engine automatically matches them against rule conditions.
+kb = KBS.knowledge_base do
+  rule "high_temperature_alert" do
+    on :sensor, id: :sensor_id?, temp: :temp?
+    on :threshold, id: :sensor_id?, max: :max?
+
+    perform do |facts, bindings|
+      if bindings[:temp?] > bindings[:max?]
+        puts "🚨 ALERT: Sensor #{bindings[:sensor_id?]} at #{bindings[:temp?]}°C"
+      end
+    end
+  end
 
-### Step 4: Run the Engine
+  # Add facts
+  fact :sensor, id: "bedroom", temp: 28
+  fact :threshold, id: "bedroom", max: 25
 
-```ruby
-engine.run
+  # Run inference
+  run
+end
 ```
 
+Facts are observations about the world. The knowledge base automatically matches them against rule conditions.
+
 **Output:**
 ```
 🚨 ALERT: Sensor bedroom at 28°C
@@ -97,10 +105,10 @@ The rule fired because the bedroom temperature (28°C) exceeds its threshold (25
 Variable binding connects facts across conditions. Here's how it works:
 
 ```ruby
-r.conditions = [
-  KBS::Condition.new(:sensor, { id: :sensor_id?, temp: :temp? }),
-  KBS::Condition.new(:threshold, { id: :sensor_id?, max: :max? })
-]
+rule "example" do
+  on :sensor, id: :sensor_id?, temp: :temp?
+  on :threshold, id: :sensor_id?, max: :max?
+end
 ```
 
 **Binding Process:**
@@ -119,19 +127,19 @@ Without variable binding, the rule would incorrectly match bedroom sensors with
 Let's prevent the same alert from firing repeatedly:
 
 ```ruby
-smart_alert_rule = KBS::Rule.new("smart_temperature_alert") do |r|
-  r.conditions = [
-    KBS::Condition.new(:sensor, { id: :sensor_id?, temp: :temp? }),
-    KBS::Condition.new(:threshold, { id: :sensor_id?, max: :max? }),
+kb = KBS.knowledge_base do
+  rule "smart_temperature_alert" do
+    on :sensor, id: :sensor_id?, temp: :temp?
+    on :threshold, id: :sensor_id?, max: :max?
     # Only fire if no alert already exists for this sensor
-    KBS::Condition.new(:alert, { sensor_id: :sensor_id? }, negated: true)
-  ]
-
-  r.action = lambda do |facts, bindings|
-    if bindings[:temp?] > bindings[:max?]
-      puts "🚨 ALERT: Sensor #{bindings[:sensor_id?]} at #{bindings[:temp?]}°C"
-      # Record that we sent this alert
-      engine.add_fact(:alert, sensor_id: bindings[:sensor_id?])
+    without :alert, sensor_id: :sensor_id?
+
+    perform do |facts, bindings|
+      if bindings[:temp?] > bindings[:max?]
+        puts "🚨 ALERT: Sensor #{bindings[:sensor_id?]} at #{bindings[:temp?]}°C"
+        # Record that we sent this alert
+        fact :alert, sensor_id: bindings[:sensor_id?]
+      end
     end
   end
 end
@@ -187,25 +195,24 @@ Learn more: [Blackboard Memory Guide](blackboard-memory.md)
 When multiple rules match, control firing order with priorities:
 
 ```ruby
-critical_rule = KBS::Rule.new("critical_alert", priority: 100) do |r|
-  r.conditions = [
-    KBS::Condition.new(:sensor, { temp: :temp? })
-  ]
-
-  r.action = lambda do |facts, bindings|
-    if bindings[:temp?] > 50
-      puts "🔥 CRITICAL: Immediate shutdown required!"
-      exit(1)
+kb = KBS.knowledge_base do
+  rule "critical_alert", priority: 100 do
+    on :sensor, temp: :temp?
+
+    perform do |facts, bindings|
+      if bindings[:temp?] > 50
+        puts "🔥 CRITICAL: Immediate shutdown required!"
+        exit(1)
+      end
     end
   end
-end
 
-normal_rule = KBS::Rule.new("normal_alert", priority: 10) do |r|
-  # ... (less urgent alerts)
+  rule "normal_alert", priority: 10 do
+    on :sensor, temp: :temp?
+    # ... (less urgent alerts)
+    perform { |facts| puts "Normal alert" }
+  end
 end
-
-engine.add_rule(critical_rule)
-engine.add_rule(normal_rule)
 ```
 
 **Priority:** Higher numbers fire first. Default is `0`.
@@ -224,74 +231,69 @@ require 'kbs'
 class TemperatureMonitor
   def initialize
     @engine = KBS::Blackboard::Engine.new(db_path: 'sensors.db')
-    setup_rules
+    @kb = setup_rules
   end
 
   def setup_rules
-    # Rule 1: Send alert when temp exceeds threshold
-    alert_rule = KBS::Rule.new("temperature_alert", priority: 50) do |r|
-      r.conditions = [
-        KBS::Condition.new(:sensor, { id: :id?, temp: :temp? }),
-        KBS::Condition.new(:threshold, { id: :id?, max: :max? }),
-        KBS::Condition.new(:alert, { sensor_id: :id? }, negated: true)
-      ]
-
-      r.action = lambda do |facts, bindings|
-        if bindings[:temp?] > bindings[:max?]
-          send_alert(bindings[:id?], bindings[:temp?], bindings[:max?])
-          @engine.add_fact(:alert, sensor_id: bindings[:id?])
+    engine = @engine
+    monitor = self
+
+    KBS.knowledge_base(engine: engine) do
+      # Rule 1: Send alert when temp exceeds threshold
+      rule "temperature_alert", priority: 50 do
+        on :sensor, id: :id?, temp: :temp?
+        on :threshold, id: :id?, max: :max?
+        without :alert, sensor_id: :id?
+
+        perform do |facts, bindings|
+          if bindings[:temp?] > bindings[:max?]
+            monitor.send_alert(bindings[:id?], bindings[:temp?], bindings[:max?])
+            fact :alert, sensor_id: bindings[:id?]
+          end
         end
       end
-    end
 
-    # Rule 2: Clear alert when temp drops below threshold
-    clear_rule = KBS::Rule.new("clear_alert", priority: 40) do |r|
-      r.conditions = [
-        KBS::Condition.new(:sensor, { id: :id?, temp: :temp? }),
-        KBS::Condition.new(:threshold, { id: :id?, max: :max? }),
-        KBS::Condition.new(:alert, { sensor_id: :id? })
-      ]
-
-      r.action = lambda do |facts, bindings|
-        if bindings[:temp?] <= bindings[:max?]
-          clear_alert(bindings[:id?])
-          # Remove the alert fact
-          alert_fact = facts.find { |f| f.type == :alert && f[:sensor_id] == bindings[:id?] }
-          @engine.remove_fact(alert_fact) if alert_fact
+      # Rule 2: Clear alert when temp drops below threshold
+      rule "clear_alert", priority: 40 do
+        on :sensor, id: :id?, temp: :temp?
+        on :threshold, id: :id?, max: :max?
+        on :alert, sensor_id: :id?
+
+        perform do |facts, bindings|
+          if bindings[:temp?] <= bindings[:max?]
+            monitor.clear_alert(bindings[:id?])
+            # Find and retract the alert fact
+            alert_fact = query(:alert, sensor_id: bindings[:id?]).first
+            retract alert_fact if alert_fact
+          end
         end
       end
-    end
 
-    # Rule 3: Emergency shutdown for extreme temps
-    emergency_rule = KBS::Rule.new("emergency_shutdown", priority: 100) do |r|
-      r.conditions = [
-        KBS::Condition.new(:sensor, { temp: :temp? })
-      ]
+      # Rule 3: Emergency shutdown for extreme temps
+      rule "emergency_shutdown", priority: 100 do
+        on :sensor, temp: :temp?
 
-      r.action = lambda do |facts, bindings|
-        if bindings[:temp?] > 60
-          emergency_shutdown(bindings[:temp?])
+        perform do |facts, bindings|
+          if bindings[:temp?] > 60
+            monitor.emergency_shutdown(bindings[:temp?])
+          end
         end
       end
     end
-
-    @engine.add_rule(alert_rule)
-    @engine.add_rule(clear_rule)
-    @engine.add_rule(emergency_rule)
   end
 
   def add_sensor(id, max_temp)
-    @engine.add_fact(:threshold, id: id, max: max_temp)
+    @kb.fact :threshold, id: id, max: max_temp
   end
 
   def update_reading(id, temp)
-    # Remove old reading
-    old = @engine.facts.find { |f| f.type == :sensor && f[:id] == id }
-    @engine.remove_fact(old) if old
+    # Find and remove old reading
+    old = @kb.query(:sensor, id: id).first
+    @kb.retract old if old
 
     # Add new reading
-    @engine.add_fact(:sensor, id: id, temp: temp)
-    @engine.run
+    @kb.fact :sensor, id: id, temp: temp
+    @kb.run
   end
 
   def send_alert(sensor_id, temp, threshold)
@@ -375,7 +377,7 @@ Now that you understand the basics, explore:
 - **[Writing Rules](writing-rules.md)** - Advanced rule patterns and techniques
 - **[Pattern Matching](pattern-matching.md)** - Deep dive into condition syntax
 - **[Blackboard Memory](blackboard-memory.md)** - Multi-agent collaboration
-- **[Stock Trading Example](../examples/stock-trading.md)** - Real-world application
+- **[Stock Trading Examples](../examples/index.md#stock-trading-systems)** - Real-world applications
 - **[API Reference](../api/engine.md)** - Complete method documentation
 
 ---