kbs 0.1.0 → 0.2.0

data/docs/examples/index.md

@@ -1,9 +1,223 @@
 # Examples
 
-Real-world applications of KBS.
+Real-world applications demonstrating KBS capabilities. Each example is available in both low-level API and DSL versions.
 
-- **[Stock Trading](stock-trading.md)** - Algorithmic trading system
-- **[Expert Systems](expert-systems.md)** - Diagnostic and decision support
-- **[Multi-Agent Systems](multi-agent.md)** - Collaborative problem-solving
+## Getting Started
 
-See also: [Quick Start Guide](../quick-start.md)
+### Working Demo
+**Files:** [`working_demo.rb`](https://github.com/madbomber/kbs/blob/main/examples/working_demo.rb) | [`working_demo_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/working_demo_dsl.rb)
+
+Simple trading system demonstrating the basics of KBS with momentum signals, volume alerts, and price movement detection. Perfect starting point for learning KBS fundamentals.
+
+**Features:**
+
+- Basic rule definition and pattern matching
+- Stock momentum detection
+- High volume alerts
+- Price change notifications
+
+### Advanced Example
+**Files:** [`advanced_example.rb`](https://github.com/madbomber/kbs/blob/main/examples/advanced_example.rb) | [`advanced_example_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/advanced_example_dsl.rb)
+
+More complex patterns including multi-condition rules, variable bindings, and negation patterns. Shows advanced RETE features and rule chaining.
+
+**Features:**
+
+- Multi-condition pattern matching
+- Variable binding and join tests
+- Negation (NOT conditions)
+- Rule priorities
+
+## Stock Trading Systems
+
+### Basic Trading Demo
+**Files:** [`trading_demo.rb`](https://github.com/madbomber/kbs/blob/main/examples/trading_demo.rb) | [`trading_demo_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/trading_demo_dsl.rb)
+
+Foundational trading signals including momentum detection and volume analysis.
+
+**Features:**
+
+- Buy/sell signal generation
+- Volume-based alerts
+- Price momentum tracking
+
+### Advanced Stock Trading
+**Files:** [`stock_trading_advanced.rb`](https://github.com/madbomber/kbs/blob/main/examples/stock_trading_advanced.rb) | [`stock_trading_advanced_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/stock_trading_advanced_dsl.rb)
+
+Sophisticated trading system with technical indicators, portfolio management, and risk controls.
+
+**Features:**
+
+- Golden cross detection (MA crossover)
+- Momentum breakout signals
+- RSI indicators
+- Volume ratio analysis
+- Risk management rules
+
+### CSV Trading System
+**Files:** [`csv_trading_system.rb`](https://github.com/madbomber/kbs/blob/main/examples/csv_trading_system.rb) | [`csv_trading_system_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/csv_trading_system_dsl.rb)
+
+Complete trading system that processes historical stock data from CSV files, calculates technical indicators, and generates trading signals.
+
+**Features:**
+
+- CSV data ingestion
+- Moving average calculations
+- Technical indicator generation
+- Backtesting support
+- Portfolio tracking
+
+### Portfolio Rebalancing System
+**Files:** [`portfolio_rebalancing_system.rb`](https://github.com/madbomber/kbs/blob/main/examples/portfolio_rebalancing_system.rb) | [`portfolio_rebalancing_system_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/portfolio_rebalancing_system_dsl.rb)
+
+Sector-based portfolio management with automatic rebalancing, drift detection, and underperformer replacement.
+
+**Features:**
+
+- Target allocation management
+- Sector drift detection
+- Automatic rebalancing rules
+- Underperformer identification
+- Position replacement logic
+
+### Timestamped Trading
+**Files:** [`timestamped_trading.rb`](https://github.com/madbomber/kbs/blob/main/examples/timestamped_trading.rb) | [`timestamped_trading_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/timestamped_trading_dsl.rb)
+
+Time-aware trading system demonstrating temporal reasoning and time-based rule activation.
+
+**Features:**
+
+- Time-based rule conditions
+- Stale data detection
+- Market hours awareness
+- Temporal pattern matching
+
+### Redis High-Frequency Trading
+**Files:** [`redis_trading_demo.rb`](https://github.com/madbomber/kbs/blob/main/examples/redis_trading_demo.rb) | [`redis_trading_demo_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/redis_trading_demo_dsl.rb)
+
+High-performance trading system using Redis for fast in-memory fact storage, ideal for low-latency trading applications.
+
+**Features:**
+
+- Redis-backed persistence
+- High-frequency market data processing
+- Fast fact lookup and updates
+- Distributed knowledge base support
+
+## Expert Systems
+
+### Car Diagnostic System
+**Files:** [`car_diagnostic.rb`](https://github.com/madbomber/kbs/blob/main/examples/car_diagnostic.rb) | [`car_diagnostic_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/car_diagnostic_dsl.rb)
+
+Expert system for diagnosing car problems based on symptoms. Demonstrates classic expert system pattern with IF-THEN diagnostic rules.
+
+**Features:**
+
+- Symptom-based diagnosis
+- Multiple diagnostic rules
+- Recommendation generation
+- Negation for ruling out conditions
+
+### IoT Monitoring System
+**File:** [`iot_demo_using_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/iot_demo_using_dsl.rb)
+
+IoT sensor monitoring system with temperature alerts, inventory management, and customer VIP upgrades. Shows real-world DSL usage patterns.
+
+**Features:**
+
+- Sensor monitoring
+- Temperature threshold alerts
+- Inventory tracking
+- Multi-domain rules (IoT, inventory, CRM)
+
+## AI-Enhanced Systems
+
+### AI-Enhanced Knowledge Base
+**Files:** [`ai_enhanced_kbs.rb`](https://github.com/madbomber/kbs/blob/main/examples/ai_enhanced_kbs.rb) | [`ai_enhanced_kbs_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/ai_enhanced_kbs_dsl.rb)
+
+Integration with Large Language Models (LLMs) for AI-powered sentiment analysis, market insights, and intelligent trading decisions.
+
+**Features:**
+
+- LLM integration via `ruby_llm` gem
+- News sentiment analysis
+- AI-powered market insights
+- MCP agent support
+- Hybrid AI + rule-based reasoning
+
+**Requirements:**
+
+- Ollama running locally (or compatible LLM provider)
+- `ruby_llm` and `ruby_llm-mcp` gems
+
+## Advanced Features
+
+### Blackboard Memory System
+**Files:** [`blackboard_demo.rb`](https://github.com/madbomber/kbs/blob/main/examples/blackboard_demo.rb) | [`blackboard_demo_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/blackboard_demo_dsl.rb)
+
+Demonstrates persistent blackboard architecture with SQLite storage, message queues, audit logs, and fact history tracking.
+
+**Features:**
++
+- SQLite-backed persistence
+- UUID-based fact tracking
+- Message queue (priority-based)
+- Complete audit trail
+- Fact update history
+- Database statistics
+
+### Concurrent Inference Patterns
+**Files:** [`concurrent_inference_demo.rb`](https://github.com/madbomber/kbs/blob/main/examples/concurrent_inference_demo.rb) | [`concurrent_inference_demo_dsl.rb`](https://github.com/madbomber/kbs/blob/main/examples/concurrent_inference_demo_dsl.rb)
+
+Advanced patterns for multi-threaded knowledge bases including reactive engines, background inference, and event-driven architectures.
+
+**Features:**
+
+- Auto-inference mode (reactive)
+- Background thread inference
+- Event-driven processing
+- Thread-safe fact addition
+- Continuous reasoning loops
+
+## Running Examples
+
+### Run Individual Examples
+
+Each example is executable from the command line:
+
+```bash
+# Run a specific example
+ruby examples/working_demo.rb
+
+# Run DSL version
+ruby examples/working_demo_dsl.rb
+
+# Run AI-enhanced example (requires Ollama)
+OLLAMA_MODEL=gpt-oss:latest ruby examples/ai_enhanced_kbs.rb
+```
+
+### Run All Examples
+
+Run all examples at once:
+
+```bash
+# Run all low-level API examples
+ruby examples/run_all.rb
+
+# Run all DSL examples
+ruby examples/run_all_dsl.rb
+```
+
+## Example Organization
+
+- **Low-level API examples** (`*.rb`) - Direct use of `KBS::Engine`, `KBS::Rule`, `KBS::Condition`
+- **DSL examples** (`*_dsl.rb`) - Using `KBS.knowledge_base` and declarative syntax
+- Both versions demonstrate the same functionality with different APIs
+
+## Further Reading
+
+- **[Quick Start Guide](../quick-start.md)** - Step-by-step tutorial
+- **[DSL Reference](../guides/dsl.md)** - Complete DSL syntax guide
+- **[Writing Rules](../guides/writing-rules.md)** - Best practices for rule design
+- **[Blackboard Memory](../guides/blackboard-memory.md)** - Persistence guide
+- **[API Reference](../api/index.md)** - Complete API documentation

data/docs/guides/blackboard-memory.md

@@ -24,27 +24,34 @@ require 'kbs'
 # With SQLite (default)
 engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
 
-# Facts persist across restarts
-engine.add_fact(:sensor, { id: "bedroom", temp: 28 })
-engine.close
+kb = KBS.knowledge_base(engine: engine) do
+  # Facts persist across restarts
+  fact :sensor, id: "bedroom", temp: 28
+end
+
+kb.close
 
 # Next run
 engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
-puts engine.facts.size  # => 1
+kb = KBS.knowledge_base(engine: engine)
+puts kb.engine.facts.size  # => 1
 ```
 
 ### Blackboard vs Regular Engine
 
 ```ruby
 # Regular engine (transient)
-regular = KBS::Engine.new
-regular.add_fact(:foo, { bar: 1 })
+kb_regular = KBS.knowledge_base do
+  fact :foo, bar: 1
+end
 # Lost on exit
 
 # Blackboard engine (persistent)
-blackboard = KBS::Blackboard::Engine.new(db_path: 'kb.db')
-blackboard.add_fact(:foo, { bar: 1 })
-blackboard.close
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+kb_blackboard = KBS.knowledge_base(engine: engine) do
+  fact :foo, bar: 1
+end
+kb_blackboard.close
 # Persisted to database
 ```
 
@@ -53,14 +60,16 @@ blackboard.close
 ### Fact Lifecycle
 
 ```ruby
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+
 # Create fact
-fact = engine.add_fact(:sensor, { id: "bedroom", temp: 28 })
+fact = engine.add_fact(:sensor, id: "bedroom", temp: 28)
 
 # Fact has UUID
 puts fact.id  # => "550e8400-e29b-41d4-a716-446655440000"
 
 # Update fact
-engine.update_fact(fact.id, { temp: 30 })
+engine.update_fact(fact.id, temp: 30)
 
 # Query fact history
 history = engine.fact_history(fact.id)
@@ -77,7 +86,8 @@ engine.delete_fact(fact.id)
 Blackboard facts support the same interface as regular facts:
 
 ```ruby
-fact = engine.add_fact(:stock, { symbol: "AAPL", price: 150 })
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+fact = engine.add_fact(:stock, symbol: "AAPL", price: 150)
 
 # Access
 fact.type           # => :stock
@@ -97,6 +107,8 @@ The blackboard includes a priority-based message queue for agent communication:
 ### Sending Messages
 
 ```ruby
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+
 # Add message to queue
 engine.send_message(:alerts, "High temperature detected", priority: 10)
 engine.send_message(:alerts, "Critical failure", priority: 100)  # Higher priority
@@ -139,11 +151,13 @@ Blackboard automatically logs all changes:
 ### Fact Audit Log
 
 ```ruby
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+
 # Add fact
-fact = engine.add_fact(:order, { id: 1, status: "pending" })
+fact = engine.add_fact(:order, id: 1, status: "pending")
 
 # Update fact
-engine.update_fact(fact.id, { status: "processing" })
+engine.update_fact(fact.id, status: "processing")
 
 # Delete fact
 engine.delete_fact(fact.id)
@@ -173,9 +187,15 @@ engine = KBS::Blackboard::Engine.new(
   audit_rules: true
 )
 
-# Add and run rules
-engine.add_rule(my_rule)
-engine.run
+kb = KBS.knowledge_base(engine: engine) do
+  rule "my_rule" do
+    on :trigger, {}
+    perform { }
+  end
+
+  fact :trigger, {}
+  run
+end
 
 # Query rule firings
 firings = engine.rule_firings(rule_name: "my_rule")
@@ -202,12 +222,12 @@ class Agent
     @engine.facts.select { |f| relevant?(f) }
   end
 
-  def decide
+  def decide(observations)
     # Apply agent's expertise
     # Return action or nil
   end
 
-  def act
+  def act(action)
     # Write facts to blackboard
     # Send messages to other agents
   end
@@ -277,7 +297,7 @@ class ExecutionAgent < Agent
         execute_order(order)
 
         # Update fact
-        @engine.update_fact(order.id, { executed: true })
+        @engine.update_fact(order.id, executed: true)
 
         # Notify
         @engine.send_message(:notifications, "Order executed", priority: 10)
@@ -306,19 +326,21 @@ end
 Blackboard supports ACID transactions (SQLite backend):
 
 ```ruby
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+
 # Transaction succeeds
 engine.transaction do
-  engine.add_fact(:account, { id: 1, balance: 1000 })
-  engine.add_fact(:account, { id: 2, balance: 500 })
+  engine.add_fact(:account, id: 1, balance: 1000)
+  engine.add_fact(:account, id: 2, balance: 500)
 end
 # Both facts committed
 
 # Transaction fails
 begin
   engine.transaction do
-    engine.add_fact(:account, { id: 3, balance: 100 })
+    engine.add_fact(:account, id: 3, balance: 100)
     raise "Error!"
-    engine.add_fact(:account, { id: 4, balance: 200 })  # Never reached
+    engine.add_fact(:account, id: 4, balance: 200)  # Never reached
   end
 rescue => e
   puts "Transaction rolled back"
@@ -344,10 +366,11 @@ class FactObserver
   end
 end
 
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
 observer = FactObserver.new
 engine.memory.add_observer(observer)
 
-engine.add_fact(:sensor, { temp: 28 })
+engine.add_fact(:sensor, temp: 28)
 # Output: Fact added: sensor - {:temp=>28}
 ```
 
@@ -402,11 +425,11 @@ engine = KBS::Blackboard::Engine.new(store: store)
 ```ruby
 # Good: Store fact UUID
 order_id = engine.add_fact(:order, { ... }).id
-engine.add_fact(:payment, { order_id: order_id })
+engine.add_fact(:payment, order_id: order_id)
 
 # Bad: Use attribute as reference
-engine.add_fact(:order, { id: 1 })
-engine.add_fact(:payment, { order_id: 1 })  # Fragile
+engine.add_fact(:order, id: 1)
+engine.add_fact(:payment, order_id: 1)  # Fragile
 ```
 
 ### 2. Namespace Facts by Agent
@@ -438,17 +461,19 @@ end
 
 ```ruby
 # Remove stale data
-KBS::Rule.new("cleanup_old_facts", priority: 1) do |r|
-  r.conditions = [
-    KBS::Condition.new(:market_data, {
-      timestamp: :time?
-    }, predicate: lambda { |f|
-      (Time.now - f[:timestamp]) > 3600  # 1 hour old
-    })
-  ]
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
 
-  r.action = lambda do |facts, bindings|
-    engine.remove_fact(facts[0])
+kb = KBS.knowledge_base(engine: engine) do
+  rule "cleanup_old_facts", priority: 1 do
+    on :market_data,
+      timestamp: :time?,
+      predicate: lambda { |f|
+        (Time.now - f[:timestamp]) > 3600  # 1 hour old
+      }
+
+    perform do |facts, bindings|
+      engine.remove_fact(facts[0])
+    end
   end
 end
 ```
@@ -456,15 +481,17 @@ end
 ### 5. Use Transactions for Multi-Fact Updates
 
 ```ruby
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+
 # Good: Atomic updates
 engine.transaction do
-  engine.update_fact(account1_id, { balance: new_balance1 })
-  engine.update_fact(account2_id, { balance: new_balance2 })
+  engine.update_fact(account1_id, balance: new_balance1)
+  engine.update_fact(account2_id, balance: new_balance2)
 end
 
 # Bad: Separate updates (not atomic)
-engine.update_fact(account1_id, { balance: new_balance1 })
-engine.update_fact(account2_id, { balance: new_balance2 })
+engine.update_fact(account1_id, balance: new_balance1)
+engine.update_fact(account2_id, balance: new_balance2)
 ```
 
 ## Common Patterns
@@ -472,16 +499,18 @@ engine.update_fact(account2_id, { balance: new_balance2 })
 ### Leader Election
 
 ```ruby
-# Agent attempts to become leader
-KBS::Rule.new("become_leader") do |r|
-  r.conditions = [
-    KBS::Condition.new(:agent, { name: :name? }),
-    KBS::Condition.new(:leader, {}, negated: true)
-  ]
-
-  r.action = lambda do |facts, bindings|
-    engine.add_fact(:leader, { name: bindings[:name?] })
-    puts "#{bindings[:name?]} is now leader"
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+
+kb = KBS.knowledge_base(engine: engine) do
+  # Agent attempts to become leader
+  rule "become_leader" do
+    on :agent, name: :name?
+    without :leader, {}
+
+    perform do |facts, bindings|
+      fact :leader, name: bindings[:name?]
+      puts "#{bindings[:name?]} is now leader"
+    end
   end
 end
 ```
@@ -490,7 +519,7 @@ end
 
 ```ruby
 # Acquire lock
-def acquire_lock(resource_id)
+def acquire_lock(engine, resource_id, agent_id)
   engine.transaction do
     lock = engine.facts.find { |f|
       f.type == :lock && f[:resource_id] == resource_id
@@ -499,7 +528,7 @@ def acquire_lock(resource_id)
     if lock.nil?
       engine.add_fact(:lock, {
         resource_id: resource_id,
-        owner: @agent_id,
+        owner: agent_id,
         acquired_at: Time.now
       })
       true
@@ -510,11 +539,11 @@ def acquire_lock(resource_id)
 end
 
 # Release lock
-def release_lock(resource_id)
+def release_lock(engine, resource_id, agent_id)
   lock = engine.facts.find { |f|
     f.type == :lock &&
     f[:resource_id] == resource_id &&
-    f[:owner] == @agent_id
+    f[:owner] == agent_id
   }
 
   engine.remove_fact(lock) if lock
@@ -524,6 +553,8 @@ end
 ### Event Sourcing
 
 ```ruby
+engine = KBS::Blackboard::Engine.new(db_path: 'kb.db')
+
 # Store events as facts
 engine.add_fact(:event, {
   type: "order_created",
@@ -533,7 +564,7 @@ engine.add_fact(:event, {
 })
 
 # Reconstruct state from events
-def rebuild_order(order_id)
+def rebuild_order(engine, order_id)
   events = engine.facts
     .select { |f| f.type == :event && f[:aggregate_id] == order_id }
     .sort_by { |f| f[:timestamp] }
@@ -550,7 +581,7 @@ end
 
 - **[Persistence](persistence.md)** - Storage backend options
 - **[Architecture](../architecture/blackboard.md)** - Blackboard implementation details
-- **[Multi-Agent Example](../examples/multi-agent.md)** - Complete multi-agent system
+- **[Blackboard Examples](../examples/index.md#advanced-features)** - Complete multi-agent and blackboard systems
 - **[API Reference](../api/blackboard.md)** - Complete blackboard API
 
 ---