kbs 0.0.1 → 0.2.0

data/examples/working_demo_dsl.rb

@@ -0,0 +1,160 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/kbs'
+include KBS::DSL::ConditionHelpers
+
+# Define the knowledge base with rules
+kb = KBS.knowledge_base do
+  # Rule 1: Simple stock momentum
+  rule "momentum_buy" do
+    on :stock, symbol: "AAPL"
+
+    perform do |facts, bindings|
+      stock = facts.find { |f| f.type == :stock }
+      puts "🚀 MOMENTUM SIGNAL: #{stock[:symbol]}"
+      puts "   Price: $#{stock[:price]}"
+      puts "   Volume: #{stock[:volume].to_s.reverse.scan(/\d{1,3}/).join(',').reverse}"
+      puts "   Recommendation: BUY"
+    end
+  end
+
+  # Rule 2: High volume alert
+  rule "high_volume" do
+    on :stock do
+      volume greater_than(1000000)
+    end
+
+    perform do |facts, bindings|
+      stock = facts.find { |f| f.type == :stock }
+      puts "📊 HIGH VOLUME ALERT: #{stock[:symbol]}"
+      puts "   Volume: #{stock[:volume].to_s.reverse.scan(/\d{1,3}/).join(',').reverse}"
+      puts "   Above 1M shares traded"
+    end
+  end
+
+  # Rule 3: Price movement
+  rule "price_movement" do
+    on :stock do
+      price_change satisfies { |p| p && p.abs > 2 }
+    end
+
+    perform do |facts, bindings|
+      stock = facts.find { |f| f.type == :stock }
+      direction = stock[:price_change] > 0 ? "UP" : "DOWN"
+      puts "📈 SIGNIFICANT MOVE: #{stock[:symbol]} #{direction}"
+      puts "   Change: #{stock[:price_change] > 0 ? '+' : ''}#{stock[:price_change]}%"
+    end
+  end
+
+  # Rule 4: RSI signals
+  rule "rsi_signal" do
+    on :stock do
+      rsi satisfies { |r| r && (r < 30 || r > 70) }
+    end
+
+    perform do |facts, bindings|
+      stock = facts.find { |f| f.type == :stock }
+      condition = stock[:rsi] < 30 ? "OVERSOLD" : "OVERBOUGHT"
+      action = stock[:rsi] < 30 ? "BUY" : "SELL"
+      puts "⚡ RSI SIGNAL: #{stock[:symbol]} #{condition}"
+      puts "   RSI: #{stock[:rsi].round(1)}"
+      puts "   Recommendation: #{action}"
+    end
+  end
+
+  # Rule 5: Multi-condition golden cross
+  rule "golden_cross_complete" do
+    on :stock, symbol: "AAPL"
+    on :ma_signal, type: "golden_cross"
+
+    perform do |facts, bindings|
+      stock = facts.find { |f| f.type == :stock }
+      signal = facts.find { |f| f.type == :ma_signal }
+      puts "🌟 GOLDEN CROSS CONFIRMED: #{stock[:symbol]}"
+      puts "   50-day MA crossed above 200-day MA"
+      puts "   Price: $#{stock[:price]}"
+      puts "   Recommendation: STRONG BUY"
+    end
+  end
+end
+
+def run_scenarios(kb)
+  puts "🏦 STOCK TRADING EXPERT SYSTEM"
+  puts "=" * 50
+
+  # Scenario 1: Apple momentum
+  puts "\n📊 SCENARIO 1: Apple with High Volume"
+  puts "-" * 30
+  kb.reset
+  kb.fact :stock, {
+    symbol: "AAPL",
+    price: 185.50,
+    volume: 1_500_000,
+    price_change: 3.2,
+    rsi: 68
+  }
+  kb.run
+
+  # Scenario 2: Google big move
+  puts "\n📊 SCENARIO 2: Google Big Price Move"
+  puts "-" * 30
+  kb.reset
+  kb.fact :stock, {
+    symbol: "GOOGL",
+    price: 142.80,
+    volume: 800_000,
+    price_change: -4.1,
+    rsi: 75
+  }
+  kb.run
+
+  # Scenario 3: Tesla oversold
+  puts "\n📊 SCENARIO 3: Tesla Oversold"
+  puts "-" * 30
+  kb.reset
+  kb.fact :stock, {
+    symbol: "TSLA",
+    price: 195.40,
+    volume: 2_200_000,
+    price_change: -1.8,
+    rsi: 25
+  }
+  kb.run
+
+  # Scenario 4: Apple Golden Cross
+  puts "\n📊 SCENARIO 4: Apple Golden Cross"
+  puts "-" * 30
+  kb.reset
+  kb.fact :stock, {
+    symbol: "AAPL",
+    price: 190.25,
+    volume: 1_100_000,
+    price_change: 2.1,
+    rsi: 55
+  }
+  kb.fact :ma_signal, {
+    symbol: "AAPL",
+    type: "golden_cross"
+  }
+  kb.run
+
+  # Scenario 5: Multiple signals
+  puts "\n📊 SCENARIO 5: NVIDIA Multiple Signals"
+  puts "-" * 30
+  kb.reset
+  kb.fact :stock, {
+    symbol: "NVDA",
+    price: 425.80,
+    volume: 3_500_000,
+    price_change: 8.7,
+    rsi: 78
+  }
+  kb.run
+
+  puts "\n" + "=" * 50
+  puts "DEMONSTRATION COMPLETE"
+end
+
+if __FILE__ == $0
+  run_scenarios(kb)
+end

data/lib/kbs/blackboard/engine.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require_relative '../rete_engine'
+require_relative '../engine'
 require_relative 'memory'
 
 module KBS
   module Blackboard
-    # RETE engine integrated with Blackboard memory
-    class Engine < ReteEngine
+    # KBS engine integrated with Blackboard memory
+    class Engine < KBS::Engine
       attr_reader :blackboard
 
       def initialize(db_path: ':memory:', store: nil)

data/lib/kbs/blackboard/fact.rb

@@ -39,7 +39,7 @@ module KBS
 
           if value.is_a?(Proc)
             return false unless @attributes[key] && value.call(@attributes[key])
-          elsif value.is_a?(Symbol) && value.to_s.start_with?('?')
+          elsif value.is_a?(Symbol) && value.to_s.end_with?('?')
             next
           else
             return false unless @attributes[key] == value

data/lib/kbs/condition.rb

@@ -16,7 +16,7 @@ module KBS
     def extract_variables(pattern)
       vars = {}
       pattern.each do |key, value|
-        if value.is_a?(Symbol) && value.to_s.start_with?('?')
+        if value.is_a?(Symbol) && value.to_s.end_with?('?')
           vars[value] = key
         end
       end

data/lib/kbs/decompiler.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module KBS
+  # Reconstruct Ruby source from YARV bytecode.
+  #
+  # YARV bytecode is a stack machine.  We simulate the stack,
+  # translating instructions back into Ruby expressions.
+  #
+  # Usage:
+  #   KBS::Decompiler.new(some_proc).decompile       # => "proc { |x| x + 1 }"
+  #   KBS::Decompiler.new(some_lambda).decompile      # => "->(x) { x + 1 }"
+  #   KBS::Decompiler.new(some_proc).decompile_block   # => "{ |x| x + 1 }"
+  #
+  class Decompiler
+    def initialize(proc_obj)
+      @iseq  = RubyVM::InstructionSequence.of(proc_obj)
+      @arr   = @iseq.to_a
+      @locals = @arr[10]          # [:a, :b, ...]
+      @params = @arr[11]          # {lead_num: 2, ...}
+      @body   = @arr[13]          # [1, :EVENT, [:instruction, ...], ...]
+      @children = []
+      @iseq.each_child { |c| @children << c }
+      @child_index = 0
+      @lambda = proc_obj.lambda?
+    end
+
+    def decompile
+      expr = decompile_body(@body)
+      params = build_params
+      if @lambda
+        "->(#{params}) { #{expr} }"
+      else
+        "proc { |#{params}| #{expr} }"
+      end
+    end
+
+    # Returns just the block literal: { |params| body }
+    # Useful when the surrounding keyword (perform, satisfies, etc.)
+    # is supplied by the caller.
+    def decompile_block
+      expr = decompile_body(@body)
+      params = build_params
+      if params.empty?
+        "{ #{expr} }"
+      else
+        "{ |#{params}| #{expr} }"
+      end
+    end
+
+    private
+
+    def build_params
+      count = @params[:lead_num] || 0
+      @locals.first(count).join(", ")
+    end
+
+    def decompile_body(body)
+      stack = []
+      statements = []
+      instructions = body.select { |i| i.is_a?(Array) }
+
+      instructions.each do |inst|
+        op = inst[0]
+        case op
+        when :getlocal_WC_0
+          idx = inst[1]
+          name = slot_to_name(idx)
+          stack.push(name.to_s)
+
+        when :setlocal_WC_0
+          idx = inst[1]
+          name = slot_to_name(idx)
+          val = stack.pop
+          statements << "#{name} = #{val}"
+
+        when :putobject
+          stack.push(inst[1].inspect)
+
+        when :putobject_INT2FIX_0_
+          stack.push("0")
+
+        when :putobject_INT2FIX_1_
+          stack.push("1")
+
+        when :putself
+          stack.push("self")
+
+        when :putnil
+          stack.push("nil")
+
+        when :putchilledstring, :putstring
+          stack.push(inst[1].inspect)
+
+        when :opt_plus, :opt_minus, :opt_mult, :opt_div, :opt_mod,
+             :opt_eq, :opt_neq, :opt_lt, :opt_le, :opt_gt, :opt_ge,
+             :opt_ltlt
+          op_sym = inst[1][:mid]
+          b = stack.pop
+          a = stack.pop
+          stack.push("#{a} #{op_sym} #{b}")
+
+        when :opt_send_without_block
+          calldata = inst[1]
+          method   = calldata[:mid]
+          argc     = calldata[:orig_argc]
+          args = stack.pop(argc)
+          receiver = stack.pop
+          call_str = format_call(receiver, method, args)
+          stack.push(call_str)
+
+        when :send
+          calldata = inst[1]
+          method   = calldata[:mid]
+          argc     = calldata[:orig_argc]
+          args     = stack.pop(argc)
+          receiver = stack.pop
+
+          child_iseq = @children[@child_index]
+          @child_index += 1
+          child_src = decompile_child(child_iseq)
+
+          base = format_call(receiver, method, args)
+          stack.push("#{base} { #{child_src} }")
+
+        when :newarray
+          count = inst[1]
+          items = stack.pop(count)
+          stack.push("[#{items.join(', ')}]")
+
+        when :newhash
+          count = inst[1]
+          pairs = stack.pop(count)
+          entries = pairs.each_slice(2).map { |k, v| "#{k} => #{v}" }
+          stack.push("{ #{entries.join(', ')} }")
+
+        when :branchunless
+          condition = stack.pop
+          remaining = instructions[instructions.index(inst) + 1..]
+          true_val = extract_value(remaining, 0)
+          false_val = extract_value(remaining, 1)
+          if true_val && false_val
+            stack.push("#{condition} ? #{true_val} : #{false_val}")
+            break
+          end
+
+        when :leave
+          # ignore
+
+        when :pop
+          val = stack.pop
+          statements << val if val
+
+        else
+          stack.push("/* #{op} */")
+        end
+      end
+
+      all = statements + [stack.last].compact
+      all.join("; ")
+    end
+
+    def format_call(receiver, method, args)
+      prefix = (receiver == "self") ? "" : "#{receiver}."
+      if args.empty?
+        "#{prefix}#{method}"
+      else
+        "#{prefix}#{method}(#{args.join(', ')})"
+      end
+    end
+
+    def decompile_child(child_iseq)
+      child_arr = child_iseq.to_a
+      child_locals = child_arr[10]
+      child_params = child_arr[11]
+      child_body   = child_arr[13]
+      count = child_params[:lead_num] || 0
+      param_names = child_locals.first(count).join(", ")
+
+      saved = [@locals, @params, @body]
+      @locals, @params, @body = child_locals, child_params, child_body
+      expr = decompile_body(child_body)
+      @locals, @params, @body = saved
+
+      if count > 0
+        "|#{param_names}| #{expr}"
+      else
+        expr
+      end
+    end
+
+    def extract_value(instructions, index)
+      values = instructions.select { |i|
+        i.is_a?(Array) && (i[0] == :putchilledstring || i[0] == :putstring || i[0] == :putobject)
+      }
+      val = values[index]
+      val[1].inspect if val
+    end
+
+    def slot_to_name(slot_idx)
+      name_idx = @locals.size + 2 - slot_idx
+      @locals[name_idx] || "?local_#{slot_idx}"
+    end
+  end
+end

data/lib/kbs/dsl/knowledge_base.rb

@@ -6,12 +6,14 @@ module KBS
       attr_reader :engine, :rules
 
       def initialize
-        @engine = ReteEngine.new
+        @engine = Engine.new
         @rules = {}
         @rule_builders = {}
+        @rule_source_locations = {}
       end
 
       def rule(name, &block)
+        @rule_source_locations[name] = block.source_location if block
         builder = RuleBuilder.new(name)
         builder.instance_eval(&block) if block_given?
         @rule_builders[name] = builder
@@ -42,7 +44,7 @@ module KBS
       end
 
       def reset
-        @engine.working_memory.facts.clear
+        @engine.reset
       end
 
       def facts
@@ -65,6 +67,30 @@ module KBS
         puts "-" * 40
       end
 
+      def rule_source(name)
+        # Try file-based source first
+        if (location = @rule_source_locations[name])
+          file, line = location
+          if file && File.exist?(file)
+            source = extract_rule_source(file, line)
+            return source if source
+          end
+        end
+
+        # Fall back to reconstruction from internal state
+        reconstruct_rule_source(name)
+      end
+
+      def print_rule_source(name)
+        source = rule_source(name)
+        unless source
+          puts "No source available for rule '#{name}'"
+          return
+        end
+
+        puts source
+      end
+
       def print_rules
         puts "Knowledge Base Rules:"
         puts "-" * 40
@@ -81,6 +107,79 @@ module KBS
         end
         puts "-" * 40
       end
+
+      private
+
+      def reconstruct_rule_source(name)
+        builder = @rule_builders[name]
+        return nil unless builder
+
+        lines = []
+        lines << "rule #{name.inspect} do"
+        lines << "  desc #{builder.description.inspect}" if builder.description
+        lines << "  priority #{builder.priority}" if builder.priority != 0
+
+        builder.conditions.each do |cond|
+          keyword = cond.negated ? "without" : "on"
+          pattern_str = reconstruct_pattern(cond.pattern)
+          if pattern_str.empty?
+            lines << "  #{keyword} #{cond.type.inspect}"
+          else
+            lines << "  #{keyword} #{cond.type.inspect}, #{pattern_str}"
+          end
+        end
+
+        if builder.action_block
+          block_str = decompile_proc_block(builder.action_block)
+          lines << "  perform #{block_str}"
+        end
+
+        lines << "end"
+        lines.join("\n")
+      end
+
+      def reconstruct_pattern(pattern)
+        return "" if pattern.empty?
+
+        pattern.map do |key, value|
+          val_str = if value.is_a?(Proc)
+                      Decompiler.new(value).decompile
+                    else
+                      value.inspect
+                    end
+          "#{key}: #{val_str}"
+        end.join(", ")
+      end
+
+      def decompile_proc_block(proc_obj)
+        Decompiler.new(proc_obj).decompile_block
+      rescue => e
+        "{ <decompilation failed: #{e.message}> }"
+      end
+
+      def extract_rule_source(file, start_line)
+        lines = File.readlines(file)
+        start_idx = start_line - 1
+        return nil if start_idx < 0 || start_idx >= lines.length
+
+        # source_location points to the block's `do` line, which is
+        # normally the same line as the `rule` call.  Walk back up to
+        # 2 lines in case they are on separate lines.
+        rule_idx = start_idx.downto([start_idx - 2, 0].max).find do |i|
+          lines[i].match?(/\b(?:rule|defrule)\b/)
+        end || start_idx
+
+        base_indent = lines[rule_idx][/^\s*/].length
+        end_pattern = /^\s{#{base_indent}}end\b/
+
+        result = []
+        (rule_idx...lines.length).each do |i|
+          result << lines[i]
+          break if i > rule_idx && lines[i].match?(end_pattern)
+        end
+
+        result.join.chomp
+      end
     end
   end
 end

data/lib/kbs/dsl/variable.rb

@@ -7,7 +7,7 @@ module KBS
 
       def initialize(name)
         name_str = name.to_s
-        @name = name_str.start_with?('?') ? name_str.to_sym : "?#{name_str}".to_sym
+        @name = name_str.end_with?('?') ? name_str.to_sym : "#{name_str}?".to_sym
       end
 
       def to_sym

data/lib/kbs/dsl.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require_relative '../kbs'
+unless defined?(KBS::Engine)
+  require_relative '../kbs'
+end
 
 # DSL components
 require_relative 'dsl/variable'

data/lib/kbs/{rete_engine.rb → engine.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module KBS
-  class ReteEngine
+  class Engine
     attr_reader :working_memory, :rules, :alpha_memories, :production_nodes
 
     def initialize
@@ -53,6 +53,47 @@ module KBS
       end
     end
 
+    # Clear all transient RETE state while preserving the compiled rule network.
+    #
+    # The RETE network has four levels of transient state:
+    #   1. WorkingMemory — holds all asserted facts
+    #   2. AlphaMemory   — holds facts matching each pattern
+    #   3. BetaMemory    — holds tokens from condition joins
+    #   4. ProductionNode — holds tokens ready to fire
+    #
+    # Simply clearing working memory facts doesn't cascade reliably
+    # through intermediate beta memories. Stale tokens in beta memories
+    # cause false matches when new facts are asserted on the next cycle.
+    #
+    # This method clears all four levels directly while preserving the
+    # root beta memory's dummy token (needed for first-condition joins).
+    def reset
+      # 1. Clear working memory directly (bypass observer — we clear everything)
+      @working_memory.facts.clear
+
+      # 2. Clear alpha memories and their downstream beta memories
+      @alpha_memories.each_value do |alpha_mem|
+        alpha_mem.items.clear
+
+        # Each alpha memory successor is a JoinNode or NegationNode.
+        # Their successors are intermediate BetaMemory nodes.
+        # The root beta memory is never a join node successor, so
+        # its dummy token is preserved.
+        alpha_mem.successors.each do |join_node|
+          next unless join_node.respond_to?(:successors)
+          join_node.successors.each do |beta_or_prod|
+            beta_or_prod.tokens.clear if beta_or_prod.respond_to?(:tokens)
+          end
+        end
+      end
+
+      # 3. Clear production node tokens
+      @production_nodes.each_value { |node| node.tokens.clear }
+
+      # 4. Clear stale child references from the root dummy token
+      @root_beta_memory.tokens.each { |t| t.children.clear }
+    end
+
     private
 
     def build_network_for_rule(rule)

data/lib/kbs/fact.rb

@@ -26,7 +26,7 @@ module KBS
 
         if value.is_a?(Proc)
           return false unless @attributes[key] && value.call(@attributes[key])
-        elsif value.is_a?(Symbol) && value.to_s.start_with?('?')
+        elsif value.is_a?(Symbol) && value.to_s.end_with?('?')
           next
         else
           return false unless @attributes[key] == value

data/lib/kbs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KBS
-  VERSION = "0.0.1"
+  VERSION = "0.2.0"
 end

data/lib/kbs.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "kbs/version"
+require_relative 'kbs/version'
 
-# Core RETE II classes
-require_relative "kbs/fact"
-require_relative "kbs/working_memory"
-require_relative "kbs/token"
-require_relative "kbs/alpha_memory"
-require_relative "kbs/beta_memory"
-require_relative "kbs/join_node"
-require_relative "kbs/negation_node"
-require_relative "kbs/production_node"
-require_relative "kbs/condition"
-require_relative "kbs/rule"
-require_relative "kbs/rete_engine"
+# Core RETE classes
+require_relative 'kbs/fact'
+require_relative 'kbs/working_memory'
+require_relative 'kbs/token'
+require_relative 'kbs/alpha_memory'
+require_relative 'kbs/beta_memory'
+require_relative 'kbs/join_node'
+require_relative 'kbs/negation_node'
+require_relative 'kbs/production_node'
+require_relative 'kbs/condition'
+require_relative 'kbs/rule'
+require_relative 'kbs/engine'
+require_relative 'kbs/decompiler'
+require_relative 'kbs/dsl'
 
 module KBS
   class Error < StandardError; end