kbs 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aef07173eec74d0aa657562330a8fda502d390e14e181fddcd2cfb948d158057
-  data.tar.gz: da2018b9fb70043a9b12c57d50ea71dcaa60e54f1ba1129f3411b4c603e7a860
+  metadata.gz: a911e3e7948e5e31bf7cd4f8a4ddb0c8e28964dc29d727391588119626c79160
+  data.tar.gz: 678fd624d18377b944f8a747ed14105f0ee4786b49919d9492952ec91d3b9914
 SHA512:
-  metadata.gz: 18c9bb6a21154803ea89139d8cbb1f7d86583cff83f8f827c63ec29b9dea859569ee18fe7e1d13211b78b9217658331ca128561a0b49ff580b20aef8ff00f215
-  data.tar.gz: 7e93213dfc62adf43740c4ac7bc35d4e9abf71445aa02cca59ed112624030a95465c2ec0729deeb3baa4f34b8cc0781dd6c51eea86270b643b51a5bed4da16e8
+  metadata.gz: 2bf7222f147a9279c25b66a182b0e9ca9f198207a1b8e1ac96b477d2e6ebc4c45f8552501f0e6d62d516c3800f4e8824674fd1990c2865e54efa9d1cc40543c1
+  data.tar.gz: c26c98beba1576d766b8017b92eb31943c9a5640d0cc7a2ac16145dcbc596a858109892419844922bb4d36d4e09221c84ed220e2756e299636813d2a2c1d3690

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-02-26
+
+### Added
+- **Rule Source Introspection**: New `rule_source` and `print_rule_source` methods on `KnowledgeBase` to retrieve and display the DSL source code for any rule by name
+- **Rule Decompiler**: `KBS::Decompiler` can reconstruct source for dynamically-created rules from Proc and Lambda objects
+- **Working Memory Reset**: `KnowledgeBase#reset` now clears working memory while preserving the compiled rule network, enabling reuse with different initial facts
+- **Rule Source Introspection Demo**: New `examples/rule_source_introspection_demo.rb` showcasing both file-based and dynamic rule source retrieval
+
+### Changed
+- **README rewritten to use DSL API**: Removed references to `KBS::ReteEngine` and `KBS::Rule`; all examples now use the DSL-based `KnowledgeBase` API
+- **Dependencies bumped**: minitest updated to ~> 5.26
+
+### Removed
+- Deleted obsolete `expert-systems` example
+- Deleted `DOCUMENTATION_STATUS.md`
+
+### Fixed
+- Updated `perform` method signatures in API documentation
+
 ## [0.1.0] - 2025-10-09
 
 ### Added

data/README.md

@@ -71,30 +71,25 @@ gem install kbs
 ```ruby
 require 'kbs'
 
-# Create inference engine
-engine = KBS::ReteEngine.new
-
-# Define a rule
-rule = KBS::Rule.new(
-  "high_temperature_alert",
-  conditions: [
-    KBS::Condition.new(:sensor, { type: "temperature" }),
-    KBS::Condition.new(:reading, { value: ->(v) { v > 100 } })
-  ],
-  action: lambda do |facts, bindings|
-    reading = facts.find { |f| f.type == :reading }
-    puts "🚨 HIGH TEMPERATURE: #{reading[:value]}°C"
-  end
-)
+# Create knowledge base with DSL
+kb = KBS.knowledge_base do
+  rule "high_temperature_alert" do
+    on :sensor, type: "temperature"
+    on :reading, value: greater_than(100)
 
-engine.add_rule(rule)
+    perform do |facts, bindings|
+      reading = facts.find { |f| f.type == :reading }
+      puts "🚨 HIGH TEMPERATURE: #{reading[:value]}°C"
+    end
+  end
 
-# Add facts
-engine.add_fact(:sensor, { type: "temperature", location: "reactor" })
-engine.add_fact(:reading, { value: 105, unit: "celsius" })
+  # Add facts
+  fact :sensor, type: "temperature", location: "reactor"
+  fact :reading, value: 105, unit: "celsius"
 
-# Run inference
-engine.run
+  # Run inference
+  run
+end
 # => 🚨 HIGH TEMPERATURE: 105°C
 ```
 
@@ -102,7 +97,6 @@ engine.run
 
 ```ruby
 require 'kbs'
-require 'kbs/dsl'
 
 kb = KBS.knowledge_base do
   rule "momentum_breakout" do
@@ -130,18 +124,29 @@ kb.run
 ```ruby
 require 'kbs/blackboard'
 
-# Create persistent blackboard
-engine = KBS::Blackboard::Engine.new(
-  store: KBS::Blackboard::Persistence::SQLiteStore.new(db_path: 'knowledge.db')
-)
+# Create persistent blackboard with DSL
+engine = KBS::Blackboard::Engine.new(db_path: 'knowledge.db')
+
+kb = KBS.knowledge_base(engine: engine) do
+  rule "temperature_monitor" do
+    on :sensor, type: "temperature", value: greater_than(25)
+
+    perform do |facts|
+      sensor = facts.first
+      puts "⚠️  High temperature at #{sensor[:location]}: #{sensor[:value]}°C"
+    end
+  end
 
-# Add persistent facts
-sensor = engine.add_fact(:sensor, { type: "temperature", location: "room1" })
-puts "Fact UUID: #{sensor.uuid}"
+  # Add persistent facts
+  fact :sensor, type: "temperature", location: "room1", value: 22
+  fact :sensor, type: "temperature", location: "room2", value: 28
+
+  run
+end
 
 # Query facts
 sensors = engine.blackboard.get_facts(:sensor)
-sensors.each { |s| puts "#{s[:type]} at #{s[:location]}" }
+sensors.each { |s| puts "#{s[:type]} at #{s[:location]}: #{s[:value]}°C" }
 
 # View audit history
 history = engine.blackboard.get_history(limit: 10)
@@ -155,51 +160,74 @@ end
 ```ruby
 require 'kbs/blackboard'
 
-# High-frequency trading with Redis
-engine = KBS::Blackboard::Engine.new(
-  store: KBS::Blackboard::Persistence::RedisStore.new(
-    url: 'redis://localhost:6379/0'
-  )
-)
+# High-frequency trading with Redis and DSL
+store = KBS::Blackboard::Persistence::RedisStore.new(url: 'redis://localhost:6379/0')
+engine = KBS::Blackboard::Engine.new(store: store)
+
+kb = KBS.knowledge_base(engine: engine) do
+  rule "price_alert" do
+    on :market_price, volume: greater_than(500_000)
+
+    perform do |facts|
+      price = facts.first
+      puts "📊 High volume: #{price[:symbol]} - #{price[:volume]} shares"
+      # Post message for other components
+      engine.post_message("PriceAlert", "high_volume",
+        { symbol: price[:symbol], volume: price[:volume] },
+        priority: 10
+      )
+    end
+  end
 
-# Fast in-memory fact storage
-engine.add_fact(:market_price, { symbol: "AAPL", price: 150.25, volume: 1_000_000 })
+  # Fast in-memory fact storage
+  fact :market_price, symbol: "AAPL", price: 150.25, volume: 1_000_000
 
-# Message queue for real-time coordination
-engine.post_message("MarketDataFeed", "prices",
-  { symbol: "AAPL", bid: 150.24, ask: 150.26 },
-  priority: 10
-)
+  run
+end
 
-message = engine.consume_message("prices", "TradingStrategy")
-puts "Received: #{message[:content]}"
+# Consume messages
+message = engine.consume_message("high_volume", "TradingStrategy")
+puts "Received: #{message[:content]}" if message
 ```
 
 ### AI-Enhanced Reasoning
 
 ```ruby
 require 'kbs'
-require 'kbs/examples/ai_enhanced_kbs'
+require 'ruby_llm'
 
 # Requires Ollama with a model installed
 # export OLLAMA_MODEL=gpt-oss:latest
 
-system = AIEnhancedKBS::AIKnowledgeSystem.new
+kb = KBS.knowledge_base do
+  rule "ai_sentiment_analysis" do
+    on :news_data, symbol: satisfies { |s| s && s.length > 0 }
+
+    perform do |facts|
+      news = facts.first
+      # AI-powered sentiment analysis
+      client = RubyLLM::Chat.new(provider: :ollama, model: 'gpt-oss:latest')
+      response = client.ask("Analyze sentiment: #{news[:headline]}")
+
+      puts "🤖 AI SENTIMENT ANALYSIS: #{news[:symbol]}"
+      puts "   Headline: #{news[:headline]}"
+      puts "   AI Analysis: #{response.content}"
+    end
+  end
 
-# Add news for AI sentiment analysis
-system.engine.add_fact(:news_data, {
-  symbol: "AAPL",
-  headline: "Apple Reports Record Q4 Earnings, Beats Expectations by 15%",
-  content: "Apple Inc. announced exceptional results..."
-})
+  # Add news for AI sentiment analysis
+  fact :news_data,
+    symbol: "AAPL",
+    headline: "Apple Reports Record Q4 Earnings, Beats Expectations by 15%",
+    content: "Apple Inc. announced exceptional results..."
 
-system.engine.run
+  run
+end
 
 # Output:
 # 🤖 AI SENTIMENT ANALYSIS: AAPL
-#    AI Sentiment: positive (92%)
-#    Key Themes: strong earnings growth, share buyback program
-#    Market Impact: bullish
+#    Headline: Apple Reports Record Q4 Earnings, Beats Expectations by 15%
+#    AI Analysis: positive (92%) - strong earnings growth, bullish outlook
 ```
 
 ## 📚 Examples

data/docs/advanced/performance.md

@@ -20,25 +20,19 @@ KBS performance depends on:
 require 'benchmark'
 require 'kbs'
 
-engine = KBS::Engine.new
-
-# Add rules
-rule = KBS::Rule.new("simple_rule") do |r|
-  r.conditions = [
-    KBS::Condition.new(:fact, { value: :v? })
-  ]
-
-  r.action = lambda do |facts, bindings|
-    # Simple action
+kb = KBS.knowledge_base do
+  rule "simple_rule" do
+    on :fact, value: :v?
+    perform do |facts, bindings|
+      # Simple action
+    end
   end
 end
 
-engine.add_rule(rule)
-
 # Benchmark fact addition
 time = Benchmark.measure do
   10_000.times do |i|
-    engine.add_fact(:fact, { value: i })
+    kb.fact :fact, value: i
   end
 end
 
@@ -47,7 +41,7 @@ puts "#{(10_000 / time.real).round(2)} facts/second"
 
 # Benchmark engine run
 time = Benchmark.measure do
-  engine.run
+  kb.run
 end
 
 puts "Ran engine in #{time.real} seconds"
@@ -67,24 +61,39 @@ class KBSBenchmark
   def setup_engine
     case @engine_type
     when :memory
-      KBS::Engine.new
+      # Return a new knowledge base context
+      @kb_context = :memory
     when :blackboard_sqlite
-      KBS::Blackboard::Engine.new(db_path: ':memory:')
+      @kb_context = :blackboard_sqlite
+      @db_path = ':memory:'
     when :blackboard_redis
       require 'kbs/blackboard/persistence/redis_store'
-      store = KBS::Blackboard::Persistence::RedisStore.new(
+      @kb_context = :blackboard_redis
+      @store = KBS::Blackboard::Persistence::RedisStore.new(
         url: 'redis://localhost:6379/15'  # Test database
       )
-      KBS::Blackboard::Engine.new(store: store)
     end
   end
 
   def benchmark_fact_addition(count: 10_000)
-    engine = setup_engine
+    setup_engine
+
+    kb = case @kb_context
+    when :memory
+      KBS.knowledge_base do
+        # Add facts in benchmark block
+      end
+    when :blackboard_sqlite
+      engine = KBS::Blackboard::Engine.new(db_path: @db_path)
+      KBS.knowledge_base(engine: engine)
+    when :blackboard_redis
+      engine = KBS::Blackboard::Engine.new(store: @store)
+      KBS.knowledge_base(engine: engine)
+    end
 
     time = Benchmark.measure do
       count.times do |i|
-        engine.add_fact(:fact, { id: i, value: rand(1000) })
+        kb.fact :fact, id: i, value: rand(1000)
       end
     end
 
@@ -96,30 +105,57 @@ class KBSBenchmark
   end
 
   def benchmark_simple_rules(fact_count: 1000, rule_count: 10)
-    engine = setup_engine
+    setup_engine
 
-    # Add rules
-    rule_count.times do |i|
-      rule = KBS::Rule.new("rule_#{i}") do |r|
-        r.conditions = [
-          KBS::Condition.new(:fact, { value: :v? })
-        ]
+    kb = case @kb_context
+    when :memory
+      KBS.knowledge_base do
+        # Add rules
+        rule_count.times do |i|
+          rule "rule_#{i}" do
+            on :fact, value: :v?
+            perform do |facts, bindings|
+              # Minimal action
+            end
+          end
+        end
 
-        r.action = lambda do |facts, bindings|
-          # Minimal action
+        # Add facts
+        fact_count.times do |i|
+          fact :fact, value: i
+        end
+      end
+    when :blackboard_sqlite
+      engine = KBS::Blackboard::Engine.new(db_path: @db_path)
+      kb = KBS.knowledge_base(engine: engine) do
+        rule_count.times do |i|
+          rule "rule_#{i}" do
+            on :fact, value: :v?
+            perform { }
+          end
+        end
+        fact_count.times do |i|
+          fact :fact, value: i
+        end
+      end
+    when :blackboard_redis
+      engine = KBS::Blackboard::Engine.new(store: @store)
+      kb = KBS.knowledge_base(engine: engine) do
+        rule_count.times do |i|
+          rule "rule_#{i}" do
+            on :fact, value: :v?
+            perform { }
+          end
+        end
+        fact_count.times do |i|
+          fact :fact, value: i
         end
       end
-      engine.add_rule(rule)
-    end
-
-    # Add facts
-    fact_count.times do |i|
-      engine.add_fact(:fact, { value: i })
     end
 
     # Benchmark engine run
     time = Benchmark.measure do
-      engine.run
+      kb.run
     end
 
     @results[:simple_rules] = {
@@ -130,33 +166,33 @@ class KBSBenchmark
   end
 
   def benchmark_complex_joins(fact_count: 500)
-    engine = setup_engine
-
-    # Rule with 3-way join
-    rule = KBS::Rule.new("complex_join") do |r|
-      r.conditions = [
-        KBS::Condition.new(:a, { id: :id?, value: :v? }),
-        KBS::Condition.new(:b, { a_id: :id?, score: :s? }),
-        KBS::Condition.new(:c, { b_score: :s? })
-      ]
-
-      r.action = lambda do |facts, bindings|
-        # Action
-      end
-    end
+    setup_engine
 
-    engine.add_rule(rule)
+    kb = case @kb_context
+    when :memory
+      KBS.knowledge_base do
+        # Rule with 3-way join
+        rule "complex_join" do
+          on :a, id: :id?, value: :v?
+          on :b, a_id: :id?, score: :s?
+          on :c, b_score: :s?
+          perform do |facts, bindings|
+            # Action
+          end
+        end
 
-    # Add facts
-    fact_count.times do |i|
-      engine.add_fact(:a, { id: i, value: rand(100) })
-      engine.add_fact(:b, { a_id: i, score: rand(100) })
-      engine.add_fact(:c, { b_score: i })
+        # Add facts
+        fact_count.times do |i|
+          fact :a, id: i, value: rand(100)
+          fact :b, a_id: i, score: rand(100)
+          fact :c, b_score: i
+        end
+      end
     end
 
     # Benchmark
     time = Benchmark.measure do
-      engine.run
+      kb.run
     end
 
     @results[:complex_joins] = {
@@ -166,31 +202,28 @@ class KBSBenchmark
   end
 
   def benchmark_negation(fact_count: 1000)
-    engine = setup_engine
-
-    # Rule with negation
-    rule = KBS::Rule.new("negation_rule") do |r|
-      r.conditions = [
-        KBS::Condition.new(:positive, { id: :id? }),
-        KBS::Condition.new(:negative, { id: :id? }, negated: true)
-      ]
-
-      r.action = lambda do |facts, bindings|
-        # Action
+    setup_engine
+
+    kb = KBS.knowledge_base do
+      # Rule with negation
+      rule "negation_rule" do
+        on :positive, id: :id?
+        without :negative, id: :id?
+        perform do |facts, bindings|
+          # Action
+        end
       end
-    end
 
-    engine.add_rule(rule)
-
-    # Add facts (50% will match)
-    fact_count.times do |i|
-      engine.add_fact(:positive, { id: i })
-      engine.add_fact(:negative, { id: i }) if i.even?
+      # Add facts (50% will match)
+      fact_count.times do |i|
+        fact :positive, id: i
+        fact :negative, id: i if i.even?
+      end
     end
 
     # Benchmark
     time = Benchmark.measure do
-      engine.run
+      kb.run
     end
 
     @results[:negation] = {