kbs 0.1.0 → 0.2.1

data/docs/guides/writing-rules.md

@@ -7,13 +7,15 @@ Master the art of authoring production rules. This guide covers best practices,
 Every rule consists of three parts:
 
 ```ruby
-KBS::Rule.new("rule_name", priority: 0) do |r|
-  # 1. CONDITIONS - Pattern matching
-  r.conditions = [...]
-
-  # 2. ACTION - What to do when conditions match
-  r.action = lambda do |facts, bindings|
-    # Execute logic
+KBS.knowledge_base do
+  rule "rule_name", priority: 0 do
+    # 1. CONDITIONS - Pattern matching
+    on :fact_type, attr: value
+
+    # 2. ACTION - What to do when conditions match
+    perform do |facts, bindings|
+      # Execute logic
+    end
   end
 end
 ```
@@ -45,9 +47,19 @@ Choose descriptive, actionable names:
 Control execution order when multiple rules match:
 
 ```ruby
-KBS::Rule.new("critical_safety_check", priority: 100)  # Fires first
-KBS::Rule.new("normal_processing", priority: 50)
-KBS::Rule.new("cleanup_task", priority: 10)            # Fires last
+KBS.knowledge_base do
+  rule "critical_safety_check", priority: 100 do  # Fires first
+    # ...
+  end
+
+  rule "normal_processing", priority: 50 do
+    # ...
+  end
+
+  rule "cleanup_task", priority: 10 do            # Fires last
+    # ...
+  end
+end
 ```
 
 **Priority Guidelines:**
@@ -61,13 +73,19 @@ KBS::Rule.new("cleanup_task", priority: 10)            # Fires last
 Patterns that must match for the rule to fire. Order matters for performance.
 
 ```ruby
-r.conditions = [
-  # Most selective first (fewest matches)
-  KBS::Condition.new(:critical_alert, { severity: "critical" }),
+KBS.knowledge_base do
+  rule "example" do
+    # Most selective first (fewest matches)
+    on :critical_alert, severity: "critical"
 
-  # Less selective last (more matches)
-  KBS::Condition.new(:sensor, { id: :sensor_id? })
-]
+    # Less selective last (more matches)
+    on :sensor, id: :sensor_id?
+
+    perform do |facts, bindings|
+      # Action
+    end
+  end
+end
 ```
 
 ### 4. Action
@@ -75,16 +93,23 @@ r.conditions = [
 Code executed when all conditions match:
 
 ```ruby
-r.action = lambda do |facts, bindings|
-  # Access matched facts
-  alert = facts[0]
-  sensor = facts[1]
+KBS.knowledge_base do
+  rule "example" do
+    on :alert, message: :msg?
+    on :sensor, id: :sensor_id?
 
-  # Access variable bindings
-  sensor_id = bindings[:sensor_id?]
+    perform do |facts, bindings|
+      # Access matched facts
+      alert = facts[0]
+      sensor = facts[1]
 
-  # Perform action
-  notify_operator(sensor_id, alert[:message])
+      # Access variable bindings
+      sensor_id = bindings[:sensor_id?]
+
+      # Perform action
+      notify_operator(sensor_id, alert[:message])
+    end
+  end
 end
 ```
 
@@ -96,17 +121,23 @@ end
 
 ```ruby
 # Bad: General condition first
-r.conditions = [
-  KBS::Condition.new(:sensor, {}),           # 1000 matches
-  KBS::Condition.new(:critical_alert, {})    # 1 match
-]
+KBS.knowledge_base do
+  rule "inefficient" do
+    on :sensor, {}           # 1000 matches
+    on :critical_alert, {}   # 1 match
+    perform { }
+  end
+end
 # Creates 1000 partial matches, wastes memory
 
 # Good: Specific condition first
-r.conditions = [
-  KBS::Condition.new(:critical_alert, {}),   # 1 match
-  KBS::Condition.new(:sensor, {})            # Joins with 1000
-]
+KBS.knowledge_base do
+  rule "efficient" do
+    on :critical_alert, {}   # 1 match
+    on :sensor, {}           # Joins with 1000
+    perform { }
+  end
+end
 # Creates 1 partial match, efficient joins
 ```
 
@@ -114,31 +145,31 @@ r.conditions = [
 
 ```ruby
 # Most selective (few facts)
-KBS::Condition.new(:emergency, { level: "critical" })
-KBS::Condition.new(:user, { role: "admin" })
+on :emergency, level: "critical"
+on :user, role: "admin"
 
 # Moderate selectivity
-KBS::Condition.new(:order, { status: "pending" })
-KBS::Condition.new(:stock, { exchange: "NYSE" })
+on :order, status: "pending"
+on :stock, exchange: "NYSE"
 
 # Least selective (many facts)
-KBS::Condition.new(:sensor, {})
-KBS::Condition.new(:log_entry, {})
+on :sensor, {}
+on :log_entry, {}
 ```
 
 ### Measuring Selectivity
 
 ```ruby
-def measure_selectivity(engine, type, pattern)
-  engine.facts.count { |f|
+def measure_selectivity(kb, type, pattern)
+  kb.engine.facts.count { |f|
     f.type == type &&
     pattern.all? { |k, v| f[k] == v }
   }
 end
 
 # Compare
-puts measure_selectivity(engine, :critical_alert, {})  # => 1
-puts measure_selectivity(engine, :sensor, {})          # => 1000
+puts measure_selectivity(kb, :critical_alert, {})  # => 1
+puts measure_selectivity(kb, :sensor, {})          # => 1000
 
 # Order: critical_alert first, sensor second
 ```
@@ -151,52 +182,58 @@ One action, one purpose:
 
 ```ruby
 # Good: Focused action
-r.action = lambda do |facts, bindings|
-  send_email_alert(bindings[:email?], bindings[:message?])
+KBS.knowledge_base do
+  rule "send_email" do
+    on :alert, email: :email?, message: :message?
+    perform do |facts, bindings|
+      send_email_alert(bindings[:email?], bindings[:message?])
+    end
+  end
 end
 
 # Bad: Multiple responsibilities
-r.action = lambda do |facts, bindings|
-  send_email_alert(bindings[:email?])
-  update_database(bindings[:id?])
-  call_external_api(bindings[:data?])
-  write_log_file(bindings[:msg?])
+KBS.knowledge_base do
+  rule "do_everything" do
+    on :trigger, email: :email?, id: :id?, data: :data?, msg: :msg?
+    perform do |facts, bindings|
+      send_email_alert(bindings[:email?])
+      update_database(bindings[:id?])
+      call_external_api(bindings[:data?])
+      write_log_file(bindings[:msg?])
+    end
+  end
 end
 ```
 
 Split complex actions into multiple rules:
 
 ```ruby
-# Rule 1: Detect condition
-KBS::Rule.new("detect_high_temp", priority: 50) do |r|
-  r.conditions = [
-    KBS::Condition.new(:sensor, { temp: :temp? }, predicate: ->(f) { f[:temp] > 30 })
-  ]
+KBS.knowledge_base do
+  # Rule 1: Detect condition
+  rule "detect_high_temp", priority: 50 do
+    on :sensor, temp: :temp?, predicate: greater_than(30)
 
-  r.action = lambda do |facts, bindings|
-    engine.add_fact(:high_temp_detected, { temp: bindings[:temp?] })
+    perform do |facts, bindings|
+      fact :high_temp_detected, temp: bindings[:temp?]
+    end
   end
-end
 
-# Rule 2: Send alert
-KBS::Rule.new("send_temp_alert", priority: 40) do |r|
-  r.conditions = [
-    KBS::Condition.new(:high_temp_detected, { temp: :temp? })
-  ]
+  # Rule 2: Send alert
+  rule "send_temp_alert", priority: 40 do
+    on :high_temp_detected, temp: :temp?
 
-  r.action = lambda do |facts, bindings|
-    send_email("High temp: #{bindings[:temp?]}")
+    perform do |facts, bindings|
+      send_email("High temp: #{bindings[:temp?]}")
+    end
   end
-end
 
-# Rule 3: Log event
-KBS::Rule.new("log_temp_event", priority: 30) do |r|
-  r.conditions = [
-    KBS::Condition.new(:high_temp_detected, { temp: :temp? })
-  ]
+  # Rule 3: Log event
+  rule "log_temp_event", priority: 30 do
+    on :high_temp_detected, temp: :temp?
 
-  r.action = lambda do |facts, bindings|
-    logger.info("Temperature spike: #{bindings[:temp?]}")
+    perform do |facts, bindings|
+      logger.info("Temperature spike: #{bindings[:temp?]}")
+    end
   end
 end
 ```
@@ -207,19 +244,31 @@ Actions should be deterministic and idempotent when possible:
 
 ```ruby
 # Good: Idempotent (safe to run multiple times)
-r.action = lambda do |facts, bindings|
-  # Remove old alert if exists
-  old = engine.facts.find { |f| f.type == :alert && f[:id] == bindings[:id?] }
-  engine.remove_fact(old) if old
+kb = KBS.knowledge_base do
+  rule "update_alert" do
+    on :trigger, id: :id?
+
+    perform do |facts, bindings|
+      # Remove old alert if exists
+      old = engine.facts.find { |f| f.type == :alert && f[:id] == bindings[:id?] }
+      engine.remove_fact(old) if old
 
-  # Add new alert
-  engine.add_fact(:alert, { id: bindings[:id?], message: "Alert!" })
+      # Add new alert
+      fact :alert, id: bindings[:id?], message: "Alert!"
+    end
+  end
 end
 
 # Bad: Non-idempotent (creates duplicates)
-r.action = lambda do |facts, bindings|
-  # Always adds, even if alert already exists
-  engine.add_fact(:alert, { id: bindings[:id?], message: "Alert!" })
+kb = KBS.knowledge_base do
+  rule "duplicate_alerts" do
+    on :trigger, id: :id?
+
+    perform do |facts, bindings|
+      # Always adds, even if alert already exists
+      fact :alert, id: bindings[:id?], message: "Alert!"
+    end
+  end
 end
 ```
 
@@ -228,17 +277,22 @@ end
 Protect against failures:
 
 ```ruby
-r.action = lambda do |facts, bindings|
-  begin
-    send_email(bindings[:email?], bindings[:message?])
-  rescue Net::SMTPError => e
-    logger.error("Failed to send email: #{e.message}")
-    # Add failure fact for retry logic
-    engine.add_fact(:email_failure, {
-      email: bindings[:email?],
-      error: e.message,
-      timestamp: Time.now
-    })
+KBS.knowledge_base do
+  rule "safe_email" do
+    on :alert, email: :email?, message: :message?
+
+    perform do |facts, bindings|
+      begin
+        send_email(bindings[:email?], bindings[:message?])
+      rescue Net::SMTPError => e
+        logger.error("Failed to send email: #{e.message}")
+        # Add failure fact for retry logic
+        fact :email_failure,
+          email: bindings[:email?],
+          error: e.message,
+          timestamp: Time.now
+      end
+    end
   end
 end
 ```
@@ -267,20 +321,22 @@ Use descriptive, consistent variable names:
 Connect facts through shared variables:
 
 ```ruby
-# Pattern: Join sensor reading with threshold
-r.conditions = [
-  KBS::Condition.new(:sensor, {
-    id: :sensor_id?,
-    temp: :current_temp?
-  }),
-
-  KBS::Condition.new(:threshold, {
-    sensor_id: :sensor_id?,  # Same variable = join constraint
-    max_temp: :max_temp?
-  })
-]
-
-# Only matches when sensor_id is same in both facts
+KBS.knowledge_base do
+  # Pattern: Join sensor reading with threshold
+  rule "check_threshold" do
+    on :sensor,
+      id: :sensor_id?,
+      temp: :current_temp?
+
+    on :threshold,
+      sensor_id: :sensor_id?,  # Same variable = join constraint
+      max_temp: :max_temp?
+
+    perform do |facts, bindings|
+      # Only matches when sensor_id is same in both facts
+    end
+  end
+end
 ```
 
 ### Computed Bindings
@@ -288,15 +344,22 @@ r.conditions = [
 Derive values in actions:
 
 ```ruby
-r.action = lambda do |facts, bindings|
-  current = bindings[:current_temp?]
-  max = bindings[:max_temp?]
+KBS.knowledge_base do
+  rule "calculate_diff" do
+    on :sensor, temp: :current_temp?
+    on :threshold, max_temp: :max_temp?
+
+    perform do |facts, bindings|
+      current = bindings[:current_temp?]
+      max = bindings[:max_temp?]
 
-  # Compute derived values
-  diff = current - max
-  percentage_over = ((current / max.to_f) - 1) * 100
+      # Compute derived values
+      diff = current - max
+      percentage_over = ((current / max.to_f) - 1) * 100
 
-  puts "#{diff}°C over threshold (#{percentage_over.round(1)}%)"
+      puts "#{diff}°C over threshold (#{percentage_over.round(1)}%)"
+    end
+  end
 end
 ```
 
@@ -307,47 +370,40 @@ end
 Model state transitions:
 
 ```ruby
-# Transition: pending → processing
-KBS::Rule.new("start_processing") do |r|
-  r.conditions = [
-    KBS::Condition.new(:order, {
+KBS.knowledge_base do
+  # Transition: pending → processing
+  rule "start_processing" do
+    on :order,
       id: :order_id?,
       status: "pending"
-    })
-  ]
 
-  r.action = lambda do |facts, bindings|
-    old_order = facts[0]
-    engine.remove_fact(old_order)
-    engine.add_fact(:order, {
-      id: bindings[:order_id?],
-      status: "processing",
-      started_at: Time.now
-    })
+    perform do |facts, bindings|
+      old_order = facts[0]
+      engine.remove_fact(old_order)
+      fact :order,
+        id: bindings[:order_id?],
+        status: "processing",
+        started_at: Time.now
+    end
   end
-end
 
-# Transition: processing → completed
-KBS::Rule.new("complete_processing") do |r|
-  r.conditions = [
-    KBS::Condition.new(:order, {
+  # Transition: processing → completed
+  rule "complete_processing" do
+    on :order,
       id: :order_id?,
       status: "processing"
-    }),
-    KBS::Condition.new(:processing_done, {
+    on :processing_done,
       order_id: :order_id?
-    })
-  ]
 
-  r.action = lambda do |facts, bindings|
-    order = facts[0]
-    engine.remove_fact(order)
-    engine.remove_fact(facts[1])  # Remove trigger
-    engine.add_fact(:order, {
-      id: bindings[:order_id?],
-      status: "completed",
-      completed_at: Time.now
-    })
+    perform do |facts, bindings|
+      order = facts[0]
+      engine.remove_fact(order)
+      engine.remove_fact(facts[1])  # Remove trigger
+      fact :order,
+        id: bindings[:order_id?],
+        status: "completed",
+        completed_at: Time.now
+    end
   end
 end
 ```
@@ -357,19 +413,19 @@ end
 Prevent duplicate actions:
 
 ```ruby
-KBS::Rule.new("send_alert_once") do |r|
-  r.conditions = [
-    KBS::Condition.new(:high_temp, { sensor_id: :id? }),
+KBS.knowledge_base do
+  rule "send_alert_once" do
+    on :high_temp, sensor_id: :id?
 
     # Guard: Only fire if alert not already sent
-    KBS::Condition.new(:alert_sent, { sensor_id: :id? }, negated: true)
-  ]
+    without :alert_sent, sensor_id: :id?
 
-  r.action = lambda do |facts, bindings|
-    send_alert(bindings[:id?])
+    perform do |facts, bindings|
+      send_alert(bindings[:id?])
 
-    # Record that we sent this alert
-    engine.add_fact(:alert_sent, { sensor_id: bindings[:id?] })
+      # Record that we sent this alert
+      fact :alert_sent, sensor_id: bindings[:id?]
+    end
   end
 end
 ```
@@ -379,18 +435,18 @@ end
 Remove stale facts:
 
 ```ruby
-KBS::Rule.new("cleanup_stale_alerts", priority: 1) do |r|
-  r.conditions = [
-    KBS::Condition.new(:alert, {
-      timestamp: :time?
-    }, predicate: lambda { |f|
-      (Time.now - f[:timestamp]) > 3600  # 1 hour old
-    })
-  ]
+KBS.knowledge_base do
+  rule "cleanup_stale_alerts", priority: 1 do
+    on :alert,
+      timestamp: :time?,
+      predicate: lambda { |f|
+        (Time.now - f[:timestamp]) > 3600  # 1 hour old
+      }
 
-  r.action = lambda do |facts, bindings|
-    engine.remove_fact(facts[0])
-    logger.info("Removed stale alert")
+    perform do |facts, bindings|
+      engine.remove_fact(facts[0])
+      logger.info("Removed stale alert")
+    end
   end
 end
 ```
@@ -400,20 +456,20 @@ end
 Compute over multiple facts:
 
 ```ruby
-KBS::Rule.new("compute_average_temp") do |r|
-  r.conditions = [
-    KBS::Condition.new(:compute_avg_requested, {})
-  ]
+KBS.knowledge_base do
+  rule "compute_average_temp" do
+    on :compute_avg_requested, {}
 
-  r.action = lambda do |facts, bindings|
-    temps = engine.facts
-      .select { |f| f.type == :sensor }
-      .map { |f| f[:temp] }
-      .compact
+    perform do |facts, bindings|
+      temps = engine.facts
+        .select { |f| f.type == :sensor }
+        .map { |f| f[:temp] }
+        .compact
 
-    avg = temps.sum / temps.size.to_f
+      avg = temps.sum / temps.size.to_f
 
-    engine.add_fact(:average_temp, { value: avg })
+      fact :average_temp, value: avg
+    end
   end
 end
 ```
@@ -423,26 +479,23 @@ end
 React to time-based conditions:
 
 ```ruby
-KBS::Rule.new("detect_delayed_response") do |r|
-  r.conditions = [
-    KBS::Condition.new(:request, {
+KBS.knowledge_base do
+  rule "detect_delayed_response" do
+    on :request,
       id: :req_id?,
       created_at: :created?
-    }),
 
-    KBS::Condition.new(:response, {
+    without :response,
       request_id: :req_id?
-    }, negated: true),
 
-    KBS::Condition.new(:request, {},
+    on :request, {},
       predicate: lambda { |f|
         (Time.now - f[:created_at]) > 300  # 5 minutes
       }
-    )
-  ]
 
-  r.action = lambda do |facts, bindings|
-    alert("Request #{bindings[:req_id?]} delayed!")
+    perform do |facts, bindings|
+      alert("Request #{bindings[:req_id?]} delayed!")
+    end
   end
 end
 ```
@@ -464,12 +517,14 @@ module Priority
 end
 
 # Use in rules
-KBS::Rule.new("emergency_shutdown", priority: Priority::CRITICAL) do |r|
-  # ...
-end
+KBS.knowledge_base do
+  rule "emergency_shutdown", priority: Priority::CRITICAL do
+    # ...
+  end
 
-KBS::Rule.new("process_order", priority: Priority::NORMAL) do |r|
-  # ...
+  rule "process_order", priority: Priority::NORMAL do
+    # ...
+  end
 end
 ```
 
@@ -479,21 +534,37 @@ Avoid priority inversions where low-priority rules block high-priority rules:
 
 ```ruby
 # Bad: Low priority rule creates fact needed by high priority rule
-KBS::Rule.new("compute_risk", priority: 10) do |r|
-  r.conditions = [...]
-  r.action = lambda { |f, b| engine.add_fact(:risk_score, { ... }) }
-end
+KBS.knowledge_base do
+  rule "compute_risk", priority: 10 do
+    on :data, value: :v?
+    perform do |facts, bindings|
+      fact :risk_score, value: calculate_risk(bindings[:v?])
+    end
+  end
 
-KBS::Rule.new("emergency_check", priority: 100) do |r|
-  r.conditions = [
-    KBS::Condition.new(:risk_score, { value: :risk? })  # Depends on low priority rule!
-  ]
-  r.action = lambda { |f, b| emergency_shutdown if b[:risk?] > 90 }
+  rule "emergency_check", priority: 100 do
+    on :risk_score, value: :risk?  # Depends on low priority rule!
+    perform do |facts, bindings|
+      emergency_shutdown if bindings[:risk?] > 90
+    end
+  end
 end
 
 # Fix: Make dependency higher priority
-KBS::Rule.new("compute_risk", priority: 110) do |r|
-  # Now runs before emergency_check
+KBS.knowledge_base do
+  rule "compute_risk", priority: 110 do  # Now runs before emergency_check
+    on :data, value: :v?
+    perform do |facts, bindings|
+      fact :risk_score, value: calculate_risk(bindings[:v?])
+    end
+  end
+
+  rule "emergency_check", priority: 100 do
+    on :risk_score, value: :risk?
+    perform do |facts, bindings|
+      emergency_shutdown if bindings[:risk?] > 90
+    end
+  end
 end
 ```
 
@@ -506,46 +577,67 @@ require 'minitest/autorun'
 require 'kbs'
 
 class TestTemperatureRules < Minitest::Test
-  def setup
-    @engine = KBS::Engine.new
+  def test_fires_when_temp_exceeds_threshold
+    alert_fired = false
 
-    @rule = KBS::Rule.new("high_temp_alert") do |r|
-      r.conditions = [
-        KBS::Condition.new(:sensor, { id: :id?, temp: :temp? }),
-        KBS::Condition.new(:threshold, { id: :id?, max: :max? })
-      ]
+    kb = KBS.knowledge_base do
+      rule "high_temp_alert" do
+        on :sensor, id: :id?, temp: :temp?
+        on :threshold, id: :id?, max: :max?
 
-      r.action = lambda do |facts, bindings|
-        @alert_fired = true if bindings[:temp?] > bindings[:max?]
+        perform do |facts, bindings|
+          alert_fired = true if bindings[:temp?] > bindings[:max?]
+        end
       end
+
+      fact :sensor, id: "bedroom", temp: 30
+      fact :threshold, id: "bedroom", max: 25
+      run
     end
 
-    @engine.add_rule(@rule)
-    @alert_fired = false
+    assert alert_fired, "Rule should fire when temp > threshold"
   end
 
-  def test_fires_when_temp_exceeds_threshold
-    @engine.add_fact(:sensor, { id: "bedroom", temp: 30 })
-    @engine.add_fact(:threshold, { id: "bedroom", max: 25 })
-    @engine.run
+  def test_does_not_fire_when_temp_below_threshold
+    alert_fired = false
 
-    assert @alert_fired, "Rule should fire when temp > threshold"
-  end
+    kb = KBS.knowledge_base do
+      rule "high_temp_alert" do
+        on :sensor, id: :id?, temp: :temp?
+        on :threshold, id: :id?, max: :max?
 
-  def test_does_not_fire_when_temp_below_threshold
-    @engine.add_fact(:sensor, { id: "bedroom", temp: 20 })
-    @engine.add_fact(:threshold, { id: "bedroom", max: 25 })
-    @engine.run
+        perform do |facts, bindings|
+          alert_fired = true if bindings[:temp?] > bindings[:max?]
+        end
+      end
 
-    refute @alert_fired, "Rule should not fire when temp <= threshold"
+      fact :sensor, id: "bedroom", temp: 20
+      fact :threshold, id: "bedroom", max: 25
+      run
+    end
+
+    refute alert_fired, "Rule should not fire when temp <= threshold"
   end
 
   def test_only_fires_for_matching_sensor
-    @engine.add_fact(:sensor, { id: "bedroom", temp: 30 })
-    @engine.add_fact(:threshold, { id: "kitchen", max: 25 })
-    @engine.run
+    alert_fired = false
+
+    kb = KBS.knowledge_base do
+      rule "high_temp_alert" do
+        on :sensor, id: :id?, temp: :temp?
+        on :threshold, id: :id?, max: :max?
+
+        perform do |facts, bindings|
+          alert_fired = true if bindings[:temp?] > bindings[:max?]
+        end
+      end
 
-    refute @alert_fired, "Rule should not fire for different sensors"
+      fact :sensor, id: "bedroom", temp: 30
+      fact :threshold, id: "kitchen", max: 25
+      run
+    end
+
+    refute alert_fired, "Rule should not fire for different sensors"
   end
 end
 ```
@@ -556,23 +648,42 @@ Test multiple rules working together:
 
 ```ruby
 def test_state_machine_workflow
-  # Add state transition rules
-  engine.add_rule(start_processing_rule)
-  engine.add_rule(complete_processing_rule)
+  kb = KBS.knowledge_base do
+    # Add state transition rules
+    rule "start_processing" do
+      on :order, id: :id?, status: "pending"
+      perform do |facts, bindings|
+        engine.remove_fact(facts[0])
+        fact :order, id: bindings[:id?], status: "processing"
+      end
+    end
 
-  # Add initial state
-  engine.add_fact(:order, { id: 1, status: "pending" })
-  engine.run
+    rule "complete_processing" do
+      on :order, id: :id?, status: "processing"
+      on :processing_done, order_id: :id?
+      perform do |facts, bindings|
+        engine.remove_fact(facts[0])
+        engine.remove_fact(facts[1])
+        fact :order, id: bindings[:id?], status: "completed"
+      end
+    end
+
+    # Add initial state
+    fact :order, id: 1, status: "pending"
+    run
+  end
 
   # Should not transition yet
-  assert_equal "pending", find_order(1)[:status]
+  order = kb.engine.facts.find { |f| f.type == :order && f[:id] == 1 }
+  assert_equal "pending", order[:status]
 
   # Trigger transition
-  engine.add_fact(:processing_done, { order_id: 1 })
-  engine.run
+  kb.fact :processing_done, order_id: 1
+  kb.run
 
-  # Should transition to processing, then completed
-  assert_equal "completed", find_order(1)[:status]
+  # Should transition to completed
+  order = kb.engine.facts.find { |f| f.type == :order && f[:id] == 1 }
+  assert_equal "completed", order[:status]
 end
 ```
 
@@ -582,16 +693,28 @@ Test rule invariants:
 
 ```ruby
 def test_no_duplicate_alerts
-  # Add facts
-  100.times do |i|
-    engine.add_fact(:high_temp, { sensor_id: i })
-  end
+  kb = KBS.knowledge_base do
+    rule "send_alert_once" do
+      on :high_temp, sensor_id: :id?
+      without :alert_sent, sensor_id: :id?
+
+      perform do |facts, bindings|
+        send_alert(bindings[:id?])
+        fact :alert_sent, sensor_id: bindings[:id?]
+      end
+    end
+
+    # Add facts
+    100.times do |i|
+      fact :high_temp, sensor_id: i
+    end
 
-  # Run engine multiple times
-  10.times { engine.run }
+    # Run engine multiple times
+    10.times { run }
+  end
 
   # Property: At most one alert per sensor
-  alert_counts = engine.facts
+  alert_counts = kb.engine.facts
     .select { |f| f.type == :alert_sent }
     .group_by { |f| f[:sensor_id] }
     .transform_values(&:count)
@@ -610,62 +733,81 @@ Negations are expensive:
 
 ```ruby
 # Expensive: 3 negations
-r.conditions = [
-  KBS::Condition.new(:foo, {}, negated: true),
-  KBS::Condition.new(:bar, {}, negated: true),
-  KBS::Condition.new(:baz, {}, negated: true)
-]
+KBS.knowledge_base do
+  rule "many_negations" do
+    without :foo, {}
+    without :bar, {}
+    without :baz, {}
+    perform { }
+  end
+end
 
 # Better: Combine into positive condition
-engine.add_fact(:conditions_met, {}) unless foo_exists? || bar_exists? || baz_exists?
+KBS.knowledge_base do
+  rule "positive_logic" do
+    on :conditions_met, {}
+    perform { }
+  end
 
-r.conditions = [
-  KBS::Condition.new(:conditions_met, {})
-]
+  # Add conditions_met fact if foo, bar, baz don't exist
+  unless engine.facts.any? { |f| [:foo, :bar, :baz].include?(f.type) }
+    fact :conditions_met, {}
+  end
+end
 ```
 
 ### Avoid Predicates for Simple Checks
 
 ```ruby
 # Expensive: Predicate disables network sharing
-KBS::Condition.new(:stock, {},
-  predicate: lambda { |f| f[:symbol] == "AAPL" }
-)
+KBS.knowledge_base do
+  rule "with_predicate" do
+    on :stock, {}, predicate: lambda { |f| f[:symbol] == "AAPL" }
+    perform { }
+  end
+end
 
 # Better: Use pattern matching
-KBS::Condition.new(:stock, { symbol: "AAPL" })
+KBS.knowledge_base do
+  rule "with_pattern" do
+    on :stock, symbol: "AAPL"
+    perform { }
+  end
+end
 ```
 
 ### Cache Computed Values
 
 ```ruby
 # Bad: Recomputes every time rule fires
-r.action = lambda do |facts, bindings|
-  avg = compute_expensive_average(engine.facts)
-  if avg > threshold
-    alert(avg)
+KBS.knowledge_base do
+  rule "check_average" do
+    on :sensor, temp: :temp?
+
+    perform do |facts, bindings|
+      avg = compute_expensive_average(engine.facts)
+      alert(avg) if avg > threshold
+    end
   end
 end
 
 # Good: Cache as fact, recompute only when needed
-KBS::Rule.new("update_average", priority: 100) do |r|
-  r.conditions = [
-    KBS::Condition.new(:sensor, { temp: :temp? })  # Triggers when sensor added
-  ]
+KBS.knowledge_base do
+  rule "update_average", priority: 100 do
+    on :sensor, temp: :temp?  # Triggers when sensor added
 
-  r.action = lambda do |facts, bindings|
-    avg = compute_expensive_average(engine.facts)
-    engine.add_fact(:cached_average, { value: avg })
+    perform do |facts, bindings|
+      avg = compute_expensive_average(engine.facts)
+      fact :cached_average, value: avg
+    end
   end
-end
 
-KBS::Rule.new("check_average", priority: 50) do |r|
-  r.conditions = [
-    KBS::Condition.new(:cached_average, { value: :avg? })
-  ]
+  rule "check_average", priority: 50 do
+    on :cached_average, value: :avg?
 
-  r.action = lambda do |facts, bindings|
-    alert(bindings[:avg?]) if bindings[:avg?] > threshold
+    perform do |facts, bindings|
+      alert(bindings[:avg?]) if bindings[:avg?] > threshold
+    end
   end
 end
 ```
@@ -676,27 +818,27 @@ end
 
 ```ruby
 # Bad: Rule fires itself indefinitely
-KBS::Rule.new("infinite_loop") do |r|
-  r.conditions = [
-    KBS::Condition.new(:sensor, { temp: :temp? })
-  ]
+KBS.knowledge_base do
+  rule "infinite_loop" do
+    on :sensor, temp: :temp?
 
-  r.action = lambda do |facts, bindings|
-    # This triggers the rule again!
-    engine.add_fact(:sensor, { temp: bindings[:temp?] + 1 })
+    perform do |facts, bindings|
+      # This triggers the rule again!
+      fact :sensor, temp: bindings[:temp?] + 1
+    end
   end
 end
 
 # Fix: Add termination condition
-KBS::Rule.new("limited_increment") do |r|
-  r.conditions = [
-    KBS::Condition.new(:sensor, { temp: :temp? }),
-    KBS::Condition.new(:increment_done, {}, negated: true)
-  ]
-
-  r.action = lambda do |facts, bindings|
-    engine.add_fact(:sensor, { temp: bindings[:temp?] + 1 })
-    engine.add_fact(:increment_done, {})
+KBS.knowledge_base do
+  rule "limited_increment" do
+    on :sensor, temp: :temp?
+    without :increment_done, {}
+
+    perform do |facts, bindings|
+      fact :sensor, temp: bindings[:temp?] + 1
+      fact :increment_done, {}
+    end
   end
 end
 ```
@@ -707,39 +849,56 @@ end
 # Bad: Closure captures wrong variable
 rules = []
 %w[sensor1 sensor2 sensor3].each do |sensor|
-  rules << KBS::Rule.new("process_#{sensor}") do |r|
-    r.conditions = [...]
-    r.action = lambda do |facts, bindings|
-      # All rules reference same 'sensor' variable (last value!)
-      puts sensor
+  # All rules reference same 'sensor' variable (last value!)
+  kb = KBS.knowledge_base do
+    rule "process_#{sensor}" do
+      on :reading, {}
+      perform { puts sensor }  # Wrong!
     end
   end
 end
 
 # Fix: Force closure with parameter
 %w[sensor1 sensor2 sensor3].each do |sensor_name|
-  rules << KBS::Rule.new("process_#{sensor_name}") do |r|
-    captured_sensor = sensor_name  # Force capture
-    r.conditions = [...]
-    r.action = lambda do |facts, bindings|
-      puts captured_sensor  # Correct value
+  captured_sensor = sensor_name  # Force capture
+
+  kb = KBS.knowledge_base do
+    rule "process_#{captured_sensor}" do
+      on :reading, {}
+      perform { puts captured_sensor }  # Correct
     end
   end
 end
 ```
 
-### 3. Forgetting to Call `engine.run`
+### 3. Forgetting to Call `run`
 
 ```ruby
 # Bad: Facts added but never matched
-engine.add_fact(:sensor, { temp: 30 })
-engine.add_fact(:threshold, { max: 25 })
-# Rules never fire!
+kb = KBS.knowledge_base do
+  rule "example" do
+    on :sensor, temp: :temp?
+    on :threshold, max: :max?
+    perform { }
+  end
+
+  fact :sensor, temp: 30
+  fact :threshold, max: 25
+  # Rules never fire!
+end
 
 # Good: Run after adding facts
-engine.add_fact(:sensor, { temp: 30 })
-engine.add_fact(:threshold, { max: 25 })
-engine.run  # Match and fire rules
+kb = KBS.knowledge_base do
+  rule "example" do
+    on :sensor, temp: :temp?
+    on :threshold, max: :max?
+    perform { }
+  end
+
+  fact :sensor, temp: 30
+  fact :threshold, max: 25
+  run  # Match and fire rules
+end
 ```
 
 ## Next Steps