kbs 0.1.0 → 0.2.1

data/examples/timestamped_trading_dsl.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require_relative '../lib/kbs/dsl'
+require_relative '../lib/kbs'
 require 'time'
 
 class TimestampedTradingSystem

data/examples/trading_demo_dsl.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require_relative '../lib/kbs/dsl'
+require_relative '../lib/kbs'
 include KBS::DSL::ConditionHelpers
 
 class TradingDemo

data/examples/working_demo_dsl.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require_relative '../lib/kbs/dsl'
+require_relative '../lib/kbs'
 include KBS::DSL::ConditionHelpers
 
 # Define the knowledge base with rules

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

@@ -9,9 +9,11 @@ module KBS
         @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.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/engine.rb

@@ -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/version.rb

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

data/lib/kbs.rb

@@ -1,19 +1,21 @@
 # frozen_string_literal: true
 
-require_relative "kbs/version"
+require_relative 'kbs/version'
 
 # 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/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

data/mkdocs.yml

@@ -143,39 +143,39 @@ extra:
 
 # Navigation
 nav:
-  - Home: index.md
+  - Home:
+      - index.md
+      - What is aKnowledge Base?: what-is-a-knowledge-base.md
+      - What is a Fact?: what-is-a-fact.md
+      - What is a Rule?: what-is-a-rule.md
   - Installation: installation.md
   - Quick Start: quick-start.md
   - Architecture:
-    - architecture/index.md
-    - RETE Algorithm: architecture/rete-algorithm.md
-    - Blackboard System: architecture/blackboard.md
-    - Network Structure: architecture/network-structure.md
+      - architecture/index.md
+      - RETE Algorithm: architecture/rete-algorithm.md
+      - Blackboard System: architecture/blackboard.md
+      - Network Structure: architecture/network-structure.md
   - Guides:
-    - guides/index.md
-    - Getting Started: guides/getting-started.md
-    - Writing Rules: guides/writing-rules.md
-    - DSL Reference: guides/dsl.md
-    - Working with Facts: guides/facts.md
-    - Pattern Matching: guides/pattern-matching.md
-    - Variable Binding: guides/variable-binding.md
-    - Negation: guides/negation.md
-    - Blackboard Memory: guides/blackboard-memory.md
-    - Persistence Options: guides/persistence.md
-  - Examples:
-    - examples/index.md
-    - Stock Trading: examples/stock-trading.md
-    - Expert Systems: examples/expert-systems.md
-    - Multi-Agent Systems: examples/multi-agent.md
+      - guides/index.md
+      - Getting Started: guides/getting-started.md
+      - Writing Rules: guides/writing-rules.md
+      - DSL Reference: guides/dsl.md
+      - Working with Facts: guides/facts.md
+      - Pattern Matching: guides/pattern-matching.md
+      - Variable Binding: guides/variable-binding.md
+      - Negation: guides/negation.md
+      - Blackboard Memory: guides/blackboard-memory.md
+      - Persistence Options: guides/persistence.md
+  - Examples: examples/index.md
   - Advanced:
-    - advanced/index.md
-    - Performance Tuning: advanced/performance.md
-    - Custom Persistence: advanced/custom-persistence.md
-    - Debugging: advanced/debugging.md
-    - Testing Rules: advanced/testing.md
+      - advanced/index.md
+      - Performance Tuning: advanced/performance.md
+      - Custom Persistence: advanced/custom-persistence.md
+      - Debugging: advanced/debugging.md
+      - Testing Rules: advanced/testing.md
   - API Reference:
-    - api/index.md
-    - ReteEngine: api/engine.md
-    - Facts: api/facts.md
-    - Rules: api/rules.md
-    - Blackboard: api/blackboard.md
+      - api/index.md
+      - ReteEngine: api/engine.md
+      - Facts: api/facts.md
+      - Rules: api/rules.md
+      - Blackboard: api/blackboard.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kbs
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -13,14 +13,14 @@ dependencies:
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '1.6'
 - !ruby/object:Gem::Dependency
@@ -90,7 +90,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/DOCUMENTATION_STATUS.md
 - docs/advanced/custom-persistence.md
 - docs/advanced/debugging.md
 - docs/advanced/index.md
@@ -109,16 +108,18 @@ files:
 - docs/assets/images/blackboard-architecture.svg
 - docs/assets/images/compiled-network.svg
 - docs/assets/images/fact-assertion-flow.svg
+- docs/assets/images/fact-rule-relationship.svg
+- docs/assets/images/fact-structure.svg
+- docs/assets/images/inference-cycle.svg
+- docs/assets/images/kb-components.svg
 - docs/assets/images/kbs.jpg
 - docs/assets/images/pattern-matching-trace.svg
 - docs/assets/images/rete-network-layers.svg
+- docs/assets/images/rule-structure.svg
 - docs/assets/images/system-layers.svg
 - docs/assets/images/trading-signal-network.svg
 - docs/assets/js/mathjax.js
-- docs/examples/expert-systems.md
 - docs/examples/index.md
-- docs/examples/multi-agent.md
-- docs/examples/stock-trading.md
 - docs/guides/blackboard-memory.md
 - docs/guides/dsl.md
 - docs/guides/facts.md
@@ -132,6 +133,10 @@ files:
 - docs/index.md
 - docs/installation.md
 - docs/quick-start.md
+- docs/what-is-a-fact.md
+- docs/what-is-a-knowledge-base.md
+- docs/what-is-a-rule.md
+- examples/.gitignore
 - examples/README.md
 - examples/advanced_example.rb
 - examples/advanced_example_dsl.rb
@@ -146,17 +151,16 @@ files:
 - examples/csv_trading_system.rb
 - examples/csv_trading_system_dsl.rb
 - examples/iot_demo_using_dsl.rb
-- examples/knowledge_base.db
 - examples/portfolio_rebalancing_system.rb
 - examples/portfolio_rebalancing_system_dsl.rb
 - examples/redis_trading_demo.rb
 - examples/redis_trading_demo_dsl.rb
+- examples/rule_source_demo.rb
 - examples/run_all.rb
 - examples/run_all_dsl.rb
 - examples/sample_stock_data.csv
 - examples/stock_trading_advanced.rb
 - examples/stock_trading_advanced_dsl.rb
-- examples/temp.txt
 - examples/temp_dsl.txt
 - examples/timestamped_trading.rb
 - examples/timestamped_trading_dsl.rb
@@ -180,6 +184,7 @@ files:
 - lib/kbs/blackboard/redis_audit_log.rb
 - lib/kbs/blackboard/redis_message_queue.rb
 - lib/kbs/condition.rb
+- lib/kbs/decompiler.rb
 - lib/kbs/dsl.rb
 - lib/kbs/dsl/condition_helpers.rb
 - lib/kbs/dsl/knowledge_base.rb
@@ -217,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Knowledge-Based System with RETE inference, Blackboard architecture, and
   AI integration