kbs 0.1.0 → 0.2.0

data/docs/api/blackboard.md

@@ -1154,4 +1154,4 @@ archive_old_audit(memory, Date.today - 30)
 - [Facts API](facts.md) - Persistent fact objects
 - [Custom Persistence](../advanced/custom-persistence.md) - Implementing custom stores
 - [Blackboard Guide](../guides/blackboard-memory.md) - Blackboard pattern overview
-- [Multi-Agent Example](../examples/multi-agent.md) - Multi-agent coordination
+- [Blackboard Examples](../examples/index.md#advanced-features) - Multi-agent coordination and blackboard systems

data/docs/api/engine.md

@@ -25,7 +25,7 @@ Creates a new in-memory RETE engine.
 
 **Returns**: `KBS::Engine` instance
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 require 'kbs'
 
@@ -33,6 +33,19 @@ engine = KBS::Engine.new
 # Engine ready with empty working memory
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+require 'kbs'
+
+kb = KBS.knowledge_base do
+  # Engine automatically created
+  # Define rules and facts here
+end
+
+# Access engine if needed
+engine = kb.engine
+```
+
 **Internal State Initialized**:
 - `@working_memory` - WorkingMemory instance
 - `@rules` - Array of registered rules
@@ -79,7 +92,7 @@ engine.add_rule(rule)
 kb = KBS.knowledge_base do
   rule "high_temperature", priority: 10 do
     on :temperature, location: "server_room", value: greater_than(80)
-    perform do |bindings|
+    perform do |facts, bindings|
       puts "Alert: #{bindings[:location?]} is #{bindings[:value?]}°F"
     end
   end
@@ -112,7 +125,7 @@ Adds a fact to working memory and activates matching alpha memories.
 - Propagates through join nodes
 - May create new tokens in beta memories
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 fact = engine.add_fact(:temperature, location: "server_room", value: 85)
 # => #<KBS::Fact:0x00... @type=:temperature @attributes={...}>
@@ -122,6 +135,14 @@ marker = engine.add_fact(:system_ready)
 # => #<KBS::Fact:0x00... @type=:system_ready @attributes={}>
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+kb = KBS.knowledge_base do
+  fact :temperature, location: "server_room", value: 85
+  fact :system_ready
+end
+```
+
 **Thread Safety**: Not thread-safe. Wrap in mutex if adding facts from multiple threads.
 
 **Performance**: O(A × P) where A is number of alpha memories, P is pattern matching cost
@@ -181,7 +202,7 @@ Executes all activated rules by firing production nodes.
 - Rule actions may add/remove facts
 - Rule actions may modify external state
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 engine.add_fact(:temperature, value: 85)
 engine.add_fact(:sensor, status: "active")
@@ -192,6 +213,21 @@ engine.run  # Execute all matching rules
 # Rules fire based on priority (highest first within each production)
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+kb = KBS.knowledge_base do
+  rule "my_rule" do
+    on :temperature, value: greater_than(80)
+    perform { puts "High temperature!" }
+  end
+
+  fact :temperature, value: 85
+  fact :sensor, status: "active"
+
+  run  # Execute all matching rules
+end
+```
+
 **Execution Order**:
 - Production nodes fire in arbitrary order (dictionary order by rule name)
 - Within a production node, tokens fire in insertion order
@@ -392,6 +428,24 @@ engine = KBS::Blackboard::Engine.new(db_path: 'knowledge_base.db')
 # Facts persisted to knowledge_base.db
 ```
 
+**Using DSL with Blackboard (Recommended)**:
+```ruby
+engine = KBS::Blackboard::Engine.new(db_path: 'knowledge_base.db')
+
+kb = KBS.knowledge_base(engine: engine) do
+  rule "persistent_rule" do
+    on :temperature, value: greater_than(80)
+    perform { puts "High temp alert!" }
+  end
+
+  fact :temperature, value: 85
+  run
+end
+
+# Facts persist across restarts
+kb.close
+```
+
 **Example - Redis Persistence**:
 ```ruby
 require 'kbs/blackboard/persistence/redis_store'
@@ -434,7 +488,7 @@ Adds a persistent fact to the blackboard.
 - Activates alpha memories
 - Notifies observers
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 fact = engine.add_fact(:temperature, location: "server_room", value: 85)
 puts fact.uuid  # => "550e8400-e29b-41d4-a716-446655440000"
@@ -445,6 +499,21 @@ reloaded_facts = engine2.blackboard.get_facts_by_type(:temperature)
 puts reloaded_facts.first[:value]  # => 85
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+# Session 1
+engine = KBS::Blackboard::Engine.new(db_path: 'knowledge_base.db')
+kb = KBS.knowledge_base(engine: engine) do
+  fact :temperature, location: "server_room", value: 85
+end
+kb.close
+
+# Session 2 - facts still available
+engine2 = KBS::Blackboard::Engine.new(db_path: 'knowledge_base.db')
+temps = engine2.blackboard.get_facts_by_type(:temperature)
+puts temps.first[:value]  # => 85
+```
+
 **Difference from KBS::Engine**: Returns `KBS::Blackboard::Fact` (has `.uuid`) instead of `KBS::Fact`.
 
 ---
@@ -639,7 +708,7 @@ engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
 kb = KBS.knowledge_base do
   rule "high_temp_alert", priority: 10 do
     on :temperature, value: greater_than(80)
-    perform do |bindings|
+    perform do |facts, bindings|
       puts "Alert! Temperature: #{bindings[:value?]}"
     end
   end
@@ -894,7 +963,7 @@ old_facts.each { |f| engine.remove_fact(f) }
 ```ruby
 rule "expire_old_facts", priority: 0 do
   on :temperature, timestamp: ->(ts) { Time.now - ts > 3600 }
-  perform do |bindings|
+  perform do |facts, bindings|
     fact = bindings[:matched_fact?]
     engine.remove_fact(fact)
   end
@@ -910,7 +979,7 @@ end
 ```ruby
 rule "risky_operation" do
   on :task, status: "pending"
-  perform do |bindings|
+  perform do |facts, bindings|
     begin
       perform_risky_operation(bindings[:task_id?])
     rescue => e

data/docs/api/facts.md

@@ -486,7 +486,7 @@ engine.remove_fact(fact)
 ```ruby
 rule "auto_expire_old_alerts" do
   on :alert, timestamp: ->(ts) { Time.now - ts > 3600 }
-  perform do |bindings|
+  perform do |facts, bindings|
     # Fact can remove itself
     alert_fact = bindings[:matched_fact?]
     alert_fact.retract
@@ -1047,7 +1047,7 @@ You can't directly compare two attributes of the same fact in one condition. Use
 # Instead: Capture variables and check in action or use join test
 rule "large_order" do
   on :order, quantity: :qty?, price: :price?
-  perform do |bindings|
+  perform do |facts, bindings|
     total = bindings[:qty?] * bindings[:price?]
     if total > 10000
       puts "Large order: $#{total}"
@@ -1111,7 +1111,7 @@ condition = KBS::Condition.new(
 # Better - Simple check first, complex check in action
 rule "complex_log_analysis" do
   on :log_entry, level: "ERROR", message: :msg?  # Simple literal filter
-  perform do |bindings|
+  perform do |facts, bindings|
     if bindings[:msg?] =~ /very.*complex.*regex.*pattern/
       # Expensive check runs only on ERROR logs
     end

data/docs/api/rules.md

@@ -38,7 +38,7 @@ Creates a new rule.
 
 **Returns**: `KBS::Rule` instance
 
-**Example - Direct Construction**:
+**Example - Low-level API (Direct Construction)**:
 ```ruby
 # Minimal rule
 rule = KBS::Rule.new(:high_temperature)
@@ -54,7 +54,7 @@ rule = KBS::Rule.new(
 )
 ```
 
-**Example - Block Configuration**:
+**Example - Low-level API (Block Configuration)**:
 ```ruby
 rule = KBS::Rule.new(:high_temperature) do |r|
   r.conditions << KBS::Condition.new(:temperature, value: ->(v) { v > 80 })
@@ -62,12 +62,12 @@ rule = KBS::Rule.new(:high_temperature) do |r|
 end
 ```
 
-**Example - Using DSL** (recommended):
+**Using DSL (Recommended)**:
 ```ruby
 kb = KBS.knowledge_base do
   rule "high_temperature", priority: 10 do
     on :temperature, value: greater_than(80)
-    perform do |bindings|
+    perform do |facts, bindings|
       puts "High temperature: #{bindings[:value?]}"
     end
   end
@@ -89,23 +89,35 @@ kb.rules.each { |r| engine.add_rule(r) }
 
 **Description**: Unique rule identifier
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 rule = KBS::Rule.new(:high_temperature, priority: 10)
 puts rule.name  # => :high_temperature
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+kb = KBS.knowledge_base do
+  rule "high_temperature", priority: 10 do
+    on :temperature, value: greater_than(80)
+    perform { puts "Alert!" }
+  end
+end
+
+puts kb.rules.first.name  # => "high_temperature"
+```
+
 **Best Practice**: Use descriptive names that indicate the rule's purpose:
 ```ruby
 # Good
-:high_temperature_alert
-:low_inventory_reorder
-:fraud_detection_high_risk
+"high_temperature_alert"
+"low_inventory_reorder"
+"fraud_detection_high_risk"
 
 # Less clear
-:rule1
-:temp_rule
-:check
+"rule1"
+"temp_rule"
+"check"
 ```
 
 ---
@@ -122,12 +134,22 @@ puts rule.name  # => :high_temperature
 
 **Range**: Any integer (commonly 0-100)
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 rule = KBS::Rule.new(:critical_alert, priority: 100)
 puts rule.priority  # => 100
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+kb = KBS.knowledge_base do
+  rule "critical_alert", priority: 100 do
+    on :alert, level: "critical"
+    perform { puts "CRITICAL ALERT!" }
+  end
+end
+```
+
 **Priority Semantics**:
 - **KBS::Engine**: Priority is stored but NOT used for execution order (rules fire in arbitrary order)
 - **KBS::Blackboard::Engine**: Higher priority rules fire first within production nodes
@@ -155,7 +177,7 @@ priority: -10
 kb = KBS.knowledge_base do
   rule "log_temperature", priority: 0 do
     on :temperature, value: :temp?
-    perform { |b| puts "Logged: #{b[:temp?]}" }
+    perform { |facts, b| puts "Logged: #{b[:temp?]}" }
   end
 
   rule "critical_alert", priority: 100 do
@@ -190,7 +212,7 @@ engine.run
 
 **Description**: Array of conditions that must all match for rule to fire
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 rule = KBS::Rule.new(:temperature_alert)
 rule.conditions << KBS::Condition.new(:temperature, value: ->(v) { v > 80 })
@@ -199,7 +221,22 @@ rule.conditions << KBS::Condition.new(:sensor, status: "active")
 puts rule.conditions.size  # => 2
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+kb = KBS.knowledge_base do
+  rule "temperature_alert" do
+    on :temperature, value: greater_than(80)
+    on :sensor, status: "active"
+    perform { puts "Alert!" }
+  end
+end
+
+puts kb.rules.first.conditions.size  # => 2
+```
+
 **Condition Order Matters** (for performance):
+
+**Low-level API**:
 ```ruby
 # Good - Most selective condition first
 rule.conditions = [
@@ -214,6 +251,23 @@ rule.conditions = [
 ]
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+# Good - Most selective condition first
+rule "sensor_alert" do
+  on :sensor, id: 42                    # Filters to 1 fact
+  on :temperature, value: :temp?        # Then match temperature
+  perform { |facts, b| puts b[:temp?] }
+end
+
+# Less optimal - Less selective first
+rule "sensor_alert" do
+  on :temperature, value: :temp?        # Matches many facts
+  on :sensor, id: 42                    # Could have filtered first
+  perform { |facts, b| puts b[:temp?] }
+end
+```
+
 See [Performance Guide](../advanced/performance.md) for condition ordering strategies.
 
 ---
@@ -232,7 +286,7 @@ See [Performance Guide](../advanced/performance.md) for condition ordering strat
 - `facts` (Array<KBS::Fact>) - Array of matched facts (parallel to conditions array)
 - `bindings` (Hash, optional) - Variable bindings extracted from facts
 
-**Example - Facts Parameter**:
+**Example - Low-level API (Facts Parameter)**:
 ```ruby
 rule.action = ->(facts) do
   temp_fact = facts[0]  # First condition's matched fact
@@ -242,7 +296,7 @@ rule.action = ->(facts) do
 end
 ```
 
-**Example - Bindings Parameter**:
+**Example - Low-level API (Bindings Parameter)**:
 ```ruby
 # Rule with variable bindings
 rule = KBS::Rule.new(:temperature_alert) do |r|
@@ -254,11 +308,11 @@ rule = KBS::Rule.new(:temperature_alert) do |r|
 end
 ```
 
-**Example - DSL Preferred**:
+**Using DSL (Recommended)**:
 ```ruby
 rule "temperature_alert" do
   on :temperature, value: :temp?, location: :loc?
-  perform do |bindings|
+  perform do |facts, bindings|
     # Cleaner - DSL automatically provides bindings
     puts "#{bindings[:loc?]}: #{bindings[:temp?]}°F"
   end
@@ -289,7 +343,7 @@ Executes the rule's action with matched facts.
 - Executes action lambda
 - Action may modify external state, add/remove facts, etc.
 
-**Example**:
+**Example - Low-level API**:
 ```ruby
 rule = KBS::Rule.new(:log_temperature) do |r|
   r.conditions << KBS::Condition.new(:temperature, value: :temp?)
@@ -303,6 +357,22 @@ rule.fire([fact])
 # Output: Temperature: 85
 ```
 
+**Using DSL (Recommended)**:
+```ruby
+kb = KBS.knowledge_base do
+  rule "log_temperature" do
+    on :temperature, value: :temp?
+    perform do |facts, bindings|
+      puts "Temperature: #{bindings[:temp?]}"
+    end
+  end
+
+  fact :temperature, value: 85
+  run  # Fires the rule automatically
+end
+# Output: Temperature: 85
+```
+
 **Note**: Typically called by the RETE engine, not user code. Users call `engine.run` which fires all activated rules.
 
 ---
@@ -316,7 +386,7 @@ rule.fire([fact])
 kb = KBS.knowledge_base do
   rule "my_rule", priority: 10 do
     on :temperature, value: :temp?
-    perform { |b| puts b[:temp?] }
+    perform { |facts, b| puts b[:temp?] }
   end
 end
 
@@ -386,7 +456,7 @@ Rules can fire multiple times:
 ```ruby
 rule "log_temperature" do
   on :temperature, value: :temp?
-  perform { |b| puts "Temperature: #{b[:temp?]}" }
+  perform { |facts, b| puts "Temperature: #{b[:temp?]}" }
 end
 
 engine.add_fact(:temperature, value: 85)
@@ -413,7 +483,7 @@ Match single fact type:
 ```ruby
 rule "log_all_temperatures" do
   on :temperature, value: :temp?
-  perform do |bindings|
+  perform do |facts, bindings|
     puts "Temperature: #{bindings[:temp?]}"
   end
 end
@@ -429,7 +499,7 @@ Match multiple related facts:
 rule "sensor_temperature_alert" do
   on :sensor, id: :sensor_id?, status: "active"
   on :temperature, sensor_id: :sensor_id?, value: greater_than(80)
-  perform do |bindings|
+  perform do |facts, bindings|
     puts "Sensor #{bindings[:sensor_id?]} reports high temperature"
   end
 end
@@ -467,7 +537,7 @@ Rules can implement state transitions:
 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|
     # Transition order to processing
     order = find_order(bindings[:order_id?])
     order.update(status: "processing", worker_id: bindings[:worker_id?])
@@ -488,7 +558,7 @@ Low-priority rules that clean up old facts:
 ```ruby
 rule "expire_old_temperatures", priority: 0 do
   on :temperature, timestamp: less_than(Time.now - 3600)
-  perform do |bindings|
+  perform do |facts, bindings|
     fact = bindings[:matched_fact?]
     fact.retract  # Remove old temperature reading
   end
@@ -527,7 +597,7 @@ Higher priority rule overrides lower priority:
 ```ruby
 rule "high_risk_order", priority: 100 do
   on :order, id: :order_id?, total: greater_than(10000)
-  perform do |bindings|
+  perform do |facts, bindings|
     puts "HIGH RISK: Order #{bindings[:order_id?]} requires manual review"
     # This fires first due to priority
   end
@@ -535,7 +605,7 @@ end
 
 rule "auto_approve_order", priority: 10 do
   on :order, id: :order_id?, status: "pending"
-  perform do |bindings|
+  perform do |facts, bindings|
     puts "Auto-approving order #{bindings[:order_id?]}"
     # This fires later (if at all)
   end
@@ -552,7 +622,7 @@ Rule that adds facts triggering other rules:
 rule "calculate_fibonacci" do
   on :fib_request, n: :n?
   negated :fib_result, n: :n?  # Not already calculated
-  perform do |bindings|
+  perform do |facts, bindings|
     n = bindings[:n?]
 
     if n <= 1
@@ -572,7 +642,7 @@ rule "combine_fibonacci" do
   on :fib_result, n: :n_minus_1?, value: :val1?
   on :fib_result, n: :n_minus_2?, value: :val2?
   # ... (complex join test: ?n_minus_1 == ?n - 1, etc.)
-  perform do |bindings|
+  perform do |facts, bindings|
     result = bindings[:val1?] + bindings[:val2?]
     engine.add_fact(:fib_result, n: bindings[:n?], value: result)
   end
@@ -633,7 +703,7 @@ end
 
 rule "log_temperature", priority: 0 do
   on :temperature, value: :temp?
-  perform { |b| log(b[:temp?]) }
+  perform { |facts, b| log(b[:temp?]) }
 end
 ```
 
@@ -647,7 +717,7 @@ Critical safety rules should have high priority to fire before less important ru
 # Good - Idempotent (safe to run multiple times)
 rule "alert_high_temp" do
   on :temperature, value: greater_than(80)
-  perform do |bindings|
+  perform do |facts, bindings|
     # Check if alert already sent
     unless alert_sent?(bindings[:temp?])
       send_alert(bindings[:temp?])
@@ -659,7 +729,7 @@ end
 # Bad - Not idempotent (sends duplicate alerts)
 rule "alert_high_temp" do
   on :temperature, value: greater_than(80)
-  perform do |bindings|
+  perform do |facts, bindings|
     send_alert(bindings[:temp?])  # Sends every time rule fires
   end
 end
@@ -696,7 +766,7 @@ end
 rule "order_inventory_check" do
   on :order, product_id: :pid?, quantity: :qty?
   on :inventory, product_id: :pid?, available: :available?
-  perform do |bindings|
+  perform do |facts, bindings|
     if bindings[:available?] < bindings[:qty?]
       puts "Insufficient inventory for product #{bindings[:pid?]}"
     end
@@ -707,7 +777,7 @@ end
 rule "order_inventory_check" do
   on :order, product_id: :pid1?, quantity: :qty?
   on :inventory, product_id: :pid2?, available: :available?
-  perform do |bindings|
+  perform do |facts, bindings|
     # No guarantee pid1 == pid2!
     if bindings[:pid1?] == bindings[:pid2?]  # Manual check in action (inefficient)
       ...
@@ -733,7 +803,7 @@ rule "portfolio_rebalancing", priority: 50 do
 
   on :portfolio, id: :portfolio_id?, status: "active"
   on :drift_calculation, portfolio_id: :portfolio_id?, drift: greater_than(0.05)
-  perform do |bindings|
+  perform do |facts, bindings|
     # Implementation...
   end
 end
@@ -806,7 +876,7 @@ end
 # Good - Cleanup rule prevents unbounded growth
 rule "expire_old_facts", priority: 0 do
   on :temperature, timestamp: less_than(Time.now - 3600)
-  perform do |bindings|
+  perform do |facts, bindings|
     fact = bindings[:matched_fact?]
     fact.retract
   end
@@ -867,7 +937,7 @@ action: ->(facts, bindings) do
 end
 
 # 3. DSL style (cleanest)
-perform do |bindings|
+perform do |facts, bindings|
   puts bindings[:temp?]
 end
 ```
@@ -962,18 +1032,18 @@ Keep actions fast:
 
 ```ruby
 # Good - Fast action
-perform do |bindings|
+perform do |facts, bindings|
   puts "Temperature: #{bindings[:temp?]}"
 end
 
 # Bad - Slow action blocks engine
-perform do |bindings|
+perform do |facts, bindings|
   sleep 5  # Blocks engine for 5 seconds!
   send_email_alert(bindings[:temp?])  # Network I/O
 end
 
 # Better - Offload slow work
-perform do |bindings|
+perform do |facts, bindings|
   # Post message for async worker
   engine.post_message("alert_system", "email_queue", bindings)
 end