wongi-engine 0.3.9 → 0.4.0.pre.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a8fbae534e8adfb43c9611f637b0cef5d0554205cf7285fbf2b95a3add8450b
-  data.tar.gz: 51ebd685dee47ab62dcd35ce51a76c68d05945ff8ea1ee2ea35094f724e33747
+  metadata.gz: 49eb7efc3f4049b38a7035208884d2078e0e31e68d396fb647deb81add7a030c
+  data.tar.gz: 6916568d628dbfce536001472c224f0fcee9ab580d4d9f2df30f04edb77bb45d
 SHA512:
-  metadata.gz: d0bb45dbd2297b67baeb9582606879fd376aaf48275d1f52759b3dfd561ce7053dea666515c5a5d0fb1cddc7394c832680e027790a43f11e3cac379d48435ece
-  data.tar.gz: 7bd9f97dec2d971781c549a722ed110541b3dfa7859434570101fa122f9c56476cbd811029283b4aa958cf1cda25f3afcc4d01d4294dba2cc2fd33ac462cd10a
+  metadata.gz: 437466d4256f5ff96bf741e879054f2e5a7499f3876ed73cbd00b155caf6b5f06cfb60378941e36cba6dd912b8d61cbe8b4cdfec58a0b60f121841cdd63c3bd9
+  data.tar.gz: 5e8ca5469c6b20cb63928a0c4c128f3391ae74c29e09608b0a7045d6d979bc03d9d8b95f49f4282898531ee8f69e7bd9abcd8ebb8164aa4d612292e01b509be3

data/.github/workflows/test.yml

@@ -11,10 +11,10 @@ jobs:
 
     strategy:
       matrix:
-        ruby-version: ["3.1", "3.0", "2.7", "2.6", "jruby-head"]
+        ruby-version: ["3.1", "3.0", "2.7", "jruby-head"]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Ruby ${{ matrix.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:

data/.gitignore

@@ -19,3 +19,5 @@ test/version_tmp
 tmp
 .ruby-version
 .idea
+.hugo_build.lock
+themes

data/README.md

@@ -3,26 +3,26 @@
 [![Gem](https://img.shields.io/gem/v/wongi-engine.svg)](https://rubygems.org/gems/wongi-engine/)
 [![Build Status](https://github.com/ulfurinn/wongi-engine/actions/workflows/test.yml/badge.svg)](https://github.com/ulfurinn/wongi-engine/actions/workflows/test.yml)
 
+This is a pure-Ruby forward-chaining rule engine based on the classic [Rete algorithm](http://en.wikipedia.org/wiki/Rete_algorithm).
+
 Ruby >= 2.7 and JRuby are supported. Rubinius should work but isn't actively supported.
 
-## [Documentation](http://ulfurinn.github.io/wongi-engine/)
+## Documentation
+
+There is no API documentation, as most of the library's interfaces are for internal use only and would not be safe to use directly.
+
+Instead, follow the [tutorial](https://ulfurinn.github.io/wongi-engine/) and stick to the constructs described in it.
 
-This library contains a rule engine written in Ruby. It's based on the [Rete algorithm](http://en.wikipedia.org/wiki/Rete_algorithm) and uses a DSL to express rules in a readable way.
+## Upgrading
 
-**Word of caution**: this is complex and fragile machinery, and there may be subtle bugs that are only revealed with nontrivial usage. Be conservative with upgrades, test your rules extensively, and please report any behaviour that is not consistent with your expectations.
+Until there is a 1.0 release, all minor versions should be treated as potentially breaking.
 
-[Feature annoucements](https://github.com/ulfurinn/wongi-engine/issues?q=is%3Aopen+is%3Aissue+label%3Aannoucement)
+Always test your rules extensively. There's always a chance of you finding a bug in the engine that is only triggered by a very specific rule configuration.
+
+[Feature annoucements](https://github.com/ulfurinn/wongi-engine/issues?q=is%3Aissue+label%3Aannoucement)
 
 [Open discussions](https://github.com/ulfurinn/wongi-engine/issues?q=is%3Aopen+is%3Aissue+label%3Adiscussion)
 
 ## Acknowledgements
 
 The Rete implementation in this library largely follows the outline presented in [\[Doorenbos, 1995\]](http://reports-archive.adm.cs.cmu.edu/anon/1995/CMU-CS-95-113.pdf).
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request

data/lib/wongi-engine/alpha_index.rb

@@ -0,0 +1,58 @@
+module Wongi::Engine
+  class AlphaIndex
+    attr_reader :pattern, :index
+    private :pattern
+    private :index
+
+    def initialize(pattern)
+      @pattern = pattern
+      @index = Hash.new { |h, k| h[k] = [] }
+    end
+
+    def add(wme)
+      collection_for_wme(wme).push(wme)
+    end
+
+    def remove(wme)
+      collection = collection_for_wme(wme)
+      collection.delete(wme)
+      if collection.empty?
+        # release some memory
+        index.delete(hashed_key(wme))
+      end
+    end
+
+    def collection_for_wme(wme)
+      index[hashed_key(wme)]
+    end
+
+    def collections_for_template(template)
+      return nil unless template_matches_pattern?(template)
+
+      # here we know that all fields on which we're indexing are concrete in the template
+      collection_for_wme(template)
+    end
+
+    private def template_matches_pattern?(template)
+      template_element_matches_pattern?(:subject, template.subject) &&
+      template_element_matches_pattern?(:predicate, template.predicate) &&
+      template_element_matches_pattern?(:object, template.object)
+    end
+
+    private def template_element_matches_pattern?(member, template_element)
+      if Template.concrete?(template_element)
+        pattern.include?(member)
+      else
+        !pattern.include?(member)
+      end
+    end
+
+    private def key(wme)
+      pattern.map { wme.public_send(_1) }
+    end
+
+    private def hashed_key(wme)
+      key(wme).map(&:hash)
+    end
+  end
+end

data/lib/wongi-engine/alpha_memory.rb

@@ -2,16 +2,14 @@ module Wongi::Engine
   class AlphaMemory
     attr_reader :betas, :template, :rete
 
-    def initialize(template, rete = nil)
+    def initialize(template, rete)
       @template = template
       @rete = rete
       @betas = []
-      @wmes = []
       @frozen = false
     end
 
     def activate(wme)
-      wme.overlay.add_wme(wme, self)
       # TODO: it used to activate before adding to the list. mandated by the original thesis. investigate. it appears to create duplicate tokens - needs a remedy in collecting nodes
       betas.each do |beta|
         beta.alpha_activate wme
@@ -19,18 +17,12 @@ module Wongi::Engine
     end
 
     def deactivate(wme)
-      wme.overlay.remove_wme(wme, self)
+      # p deactivate: {wme:}
       betas.each do |beta|
         beta.alpha_deactivate wme
       end
     end
 
-    def snapshot!(alpha)
-      alpha.wmes.map(&:dup).each do |wme|
-        activate wme
-      end
-    end
-
     def inspect
       "<Alpha #{__id__} template=#{template}>"
     end
@@ -38,19 +30,5 @@ module Wongi::Engine
     def to_s
       inspect
     end
-
-    def size
-      wmes.count
-    end
-
-    def wmes
-      Enumerator.new do |y|
-        rete.overlays.each do |overlay|
-          overlay.raw_wmes(self).dup.each do |wme|
-            y << wme
-          end
-        end
-      end
-    end
   end
 end

data/lib/wongi-engine/beta/aggregate_node.rb

@@ -27,41 +27,43 @@ module Wongi::Engine
 
     def alpha_activate(wme)
       # we need to re-run all WMEs through the aggregator, so the new incoming one doesn't matter
-      parent.tokens.each do |token|
-        evaluate(wme, token)
+      tokens.each do |token|
+        evaluate(wme: wme, token: token)
       end
     end
 
     def alpha_deactivate(wme)
       # we need to re-run all WMEs through the aggregator, so the new incoming one doesn't matter
-      parent.tokens.each do |token|
-        evaluate(wme, token)
+      tokens.each do |token|
+        evaluate(wme: wme, token: token)
       end
     end
 
     def beta_activate(token)
-      evaluate(nil, token)
+      return if tokens.find { |t| t.duplicate? token }
+
+      overlay.add_token(token)
+      evaluate(wme: nil, token: token)
     end
 
     def beta_deactivate(token)
-      children.each do |child|
-        child.tokens.each do |t|
-          child.beta_deactivate t if t.parent == token
-        end
-      end
+      overlay.remove_token(token)
+      beta_deactivate_children(token: token)
     end
 
     def refresh_child(child)
-      parent.tokens.each do |token|
-        evaluate(nil, token, child)
+      tokens.each do |token|
+        evaluate(wme: nil, token: token, child: child)
       end
     end
 
-    def evaluate(wme, token, child = nil)
+    def evaluate(wme:, token:, child: nil)
       # clean up previous decisions
-      beta_deactivate(token)
+      # # TODO: optimise: only clean up if the value changed
+      beta_deactivate_children(token: token)
 
-      candidates = alpha.wmes.select { |asserted_wme| matches?(token, asserted_wme) }
+      template = specialize(alpha.template, tests, token)
+      candidates = select_wmes(template) { |asserted_wme| matches?(token, asserted_wme) }
 
       return if candidates.empty?
 

data/lib/wongi-engine/beta/assignment_node.rb

@@ -7,12 +7,17 @@ module Wongi::Engine
     end
 
     def beta_activate(token, _wme = nil, _assignments = {})
+      return if tokens.find { |t| t.duplicate? token }
+
+      overlay.add_token(token)
       children.each do |child|
-        child.beta_activate Token.new(child, token, nil, { @variable => @body.respond_to?(:call) ? @body.call(token) : @body })
+        value = @body.respond_to?(:call) ? @body.call(token) : @body
+        child.beta_activate Token.new(child, token, nil, { @variable => value })
       end
     end
 
     def beta_deactivate(token)
+      overlay.remove_token(token)
       children.each do |child|
         child.tokens.each do |t|
           if t.parent == token
@@ -24,7 +29,7 @@ module Wongi::Engine
     end
 
     def refresh_child(child)
-      parent.tokens.each do |token|
+      tokens.each do |token|
         child.beta_activate Token.new(child, token, nil, { @variable => @body.respond_to?(:call) ? @body.call(token) : @body })
       end
     end

data/lib/wongi-engine/beta/beta_node.rb

@@ -1,26 +1,5 @@
 module Wongi::Engine
   class BetaNode
-    module TokenContainer
-      def tokens
-        Enumerator.new do |y|
-          rete.overlays.each do |overlay|
-            overlay.raw_tokens(self).dup.each do |token|
-              y << token unless token.deleted?
-            end
-            overlay.raw_tokens(self).reject!(&:deleted?)
-          end
-        end
-      end
-
-      def empty?
-        tokens.first.nil?
-      end
-
-      def size
-        tokens.count
-      end
-    end
-
     include CoreExt
 
     attr_writer :rete
@@ -58,6 +37,7 @@ module Wongi::Engine
     abstract :beta_activate
     abstract :beta_deactivate
     abstract :beta_reactivate
+    abstract :refresh_child
 
     def assignment_node(variable, body)
       node = AssignmentNode.new self, variable, body
@@ -69,8 +49,41 @@ module Wongi::Engine
       parent.refresh_child self
     end
 
-    def refresh_child(_node)
-      raise "#{self.class} must implement refresh_child"
+    def beta_deactivate_children(token: nil, wme: nil, children: self.children)
+      children.each do |child|
+        child.tokens.select { (token.nil? || _1.parent == token) && (wme.nil? || _1.wme == wme) }.each do |child_token|
+          child.beta_deactivate(child_token)
+        end
+      end
+    end
+
+    private def select_wmes(template)
+      rete.current_overlay.select(template)
+    end
+
+    private def specialize(template, tests, token)
+      tests.each_with_object(template.dup) do |test, template|
+        var = test.variable
+        if token.has_var?(var)
+          template.public_send("#{test.field}=", token[var])
+        end
+      end
+    end
+
+    def tokens
+      overlay.node_tokens(self)
+    end
+
+    def overlay
+      rete.current_overlay
+    end
+
+    def empty?
+      tokens.first.nil?
+    end
+
+    def size
+      tokens.count
     end
 
     private

data/lib/wongi-engine/beta/filter_node.rb

@@ -10,22 +10,20 @@ module Wongi
       end
 
       def beta_activate(token)
+        return if tokens.find { |t| t.duplicate? token }
+
         return unless test.passes?(token)
 
+        overlay.add_token(token)
+
         children.each do |child|
           child.beta_activate Token.new(child, token, nil, {})
         end
       end
 
       def beta_deactivate(token)
-        children.each do |child|
-          child.tokens.each do |t|
-            if t.parent == token
-              child.beta_deactivate t
-              # token.destroy
-            end
-          end
-        end
+        overlay.remove_token(token)
+        beta_deactivate_children(token: token)
       end
 
       def equivalent?(test)
@@ -33,12 +31,9 @@ module Wongi
       end
 
       def refresh_child(child)
-        tmp = children
-        self.children = [child]
-        parent.tokens.each do |token|
-          beta_activate token
+        tokens.select { test.passes?(_1) }.each do |token|
+          child.beta_activate Token.new(child, token, nil, {})
         end
-        self.children = tmp
       end
     end
   end

data/lib/wongi-engine/beta/join_node.rb

@@ -1,19 +1,5 @@
 module Wongi
   module Engine
-    TokenAssignment = Struct.new(:wme, :field) do
-      def call(_token = nil)
-        wme.send field
-      end
-
-      def inspect
-        "#{field} of #{wme}"
-      end
-
-      def to_s
-        inspect
-      end
-    end
-
     class BetaTest
       attr_reader :field, :variable
 
@@ -57,8 +43,10 @@ module Wongi
       end
 
       def alpha_activate(wme)
+        # p alpha_activate: {class: self.class, object_id:, wme:}
         assignments = collect_assignments(wme)
-        parent.tokens.each do |token|
+
+        tokens.each do |token|
           next unless matches?(token, wme)
 
           children.each do |beta|
@@ -68,15 +56,17 @@ module Wongi
       end
 
       def alpha_deactivate(wme)
-        children.each do |child|
-          child.tokens.each do |token|
-            child.beta_deactivate token if token.wme == wme
-          end
-        end
+        beta_deactivate_children(wme: wme)
       end
 
       def beta_activate(token)
-        alpha.wmes.each do |wme|
+        # p beta_activate: {class: self.class, object_id:, token:}
+        return if tokens.find { |t| t.duplicate? token }
+
+        overlay.add_token(token)
+
+        template = specialize(alpha.template, tests, token)
+        select_wmes(template).each do |wme|
           next unless matches?(token, wme)
 
           assignments = collect_assignments(wme)
@@ -87,17 +77,15 @@ module Wongi
       end
 
       def beta_deactivate(token)
-        children.each do |child|
-          child.tokens.each do |t|
-            child.beta_deactivate t if t.parent == token
-          end
-        end
+        # p beta_deactivate: {class: self.class, object_id:, token:}
+        overlay.remove_token(token)
+        beta_deactivate_children(token: token)
       end
 
       def refresh_child(child)
-        alpha.wmes.each do |wme|
+        select_wmes(alpha.template).each do |wme|
           assignments = collect_assignments(wme)
-          parent.tokens.each do |token|
+          tokens.each do |token|
             child.beta_activate Token.new(child, token, wme, assignments) if matches?(token, wme)
           end
         end
@@ -106,7 +94,7 @@ module Wongi
       protected
 
       def matches?(token, wme)
-        @tests.each do |test|
+        tests.each do |test|
           return false unless test.matches?(token, wme)
         end
         true

data/lib/wongi-engine/beta/ncc_node.rb

@@ -1,52 +1,40 @@
 module Wongi
   module Engine
     class NccNode < BetaNode
-      include TokenContainer
-
       attr_accessor :partner
 
       def beta_activate(token)
-        return if tokens.find { |t| t.parent == token }
+        # p beta_activate: {class: self.class, object_id:, token:}
+        return if tokens.find { |t| t.duplicate? token }
 
-        t = Token.new self, token, nil, {}
-        t.overlay.add_token(t, self)
+        overlay.add_token(token)
         partner.tokens.each do |ncc_token|
-          next unless ncc_token.ancestors.find { |a| a.equal? token }
-
-          t.ncc_results << ncc_token
-          ncc_token.owner = t
+          if partner.owner_for(ncc_token) == token
+            overlay.add_ncc_token(token, ncc_token)
+          end
         end
-        return unless t.ncc_results.empty?
+        return if overlay.ncc_tokens_for(token).any?
 
         children.each do |child|
-          child.beta_activate Token.new(child, t, nil, {})
+          child.beta_activate Token.new(child, token, nil, {})
         end
       end
 
       def beta_deactivate(token)
-        t = tokens.find { |tok| tok.parent == token }
-        return unless t
-
-        t.overlay.remove_token(t, self)
-        t.deleted!
-        partner.tokens.select { |ncc| ncc.owner == t }.each do |ncc_token|
-          ncc_token.owner = nil
-          t.ncc_results.delete(ncc_token)
-        end
-        children.each do |beta|
-          beta.tokens.select { |child_token| child_token.parent == t }.each do |child_token|
-            beta.beta_deactivate(child_token)
-          end
-        end
+        # p beta_deactivate: {class: self.class, object_id:, token:}
+        overlay.remove_token(token)
+        beta_deactivate_children(token: token)
       end
 
       def ncc_activate(token)
+        # p ncc_activate: {class: self.class, object_id:, token:}
         children.each do |child|
           child.beta_activate Token.new(child, token, nil, {})
         end
       end
 
       def ncc_deactivate(token)
+        # p ncc_deactivate: {class: self.class, object_id:, token:}
         children.each do |beta|
           beta.tokens.select { |t| t.parent == token }.each do |t|
             beta.beta_deactivate t
@@ -56,7 +44,7 @@ module Wongi
 
       def refresh_child(child)
         tokens.each do |token|
-          child.beta_activate Token.new(child, token, nil, {}) if token.ncc_results.empty?
+          child.beta_activate Token.new(child, token, nil, {}) if overlay.ncc_tokens_for(token).empty?
         end
       end
     end

data/lib/wongi-engine/beta/ncc_partner.rb

@@ -1,39 +1,39 @@
 module Wongi
   module Engine
     class NccPartner < BetaNode
-      include TokenContainer
-
       attr_accessor :ncc, :divergent
 
       def beta_activate(token)
-        t = Token.new self, token, nil, {}
-        owner = owner_for(t)
-        t.overlay.add_token(t, self)
+        # p beta_activate: {class: self.class, object_id:, token:}
+        return if tokens.find { |t| t.duplicate? token }
+
+        overlay.add_token(token)
+
+        owner = owner_for(token)
         return unless owner
 
-        owner.ncc_results << t
-        t.owner = owner
+        overlay.add_ncc_token(owner, token)
         owner.node.ncc_deactivate owner
       end
 
-      def beta_deactivate(t)
-        token = tokens.find { |tok| tok.parent == t }
-        return unless token
+      def beta_deactivate(token)
+        # p beta_deactivate: {class: self.class, object_id:, token:}
 
-        token.overlay.remove_token(token, self)
+        # fetch the owner before deleting the token
+        owner = overlay.ncc_owner(token)
 
-        owner = token.owner
+        overlay.remove_token(token)
         return unless owner
 
-        owner.ncc_results.delete token
-        ncc.ncc_activate owner if owner.ncc_results.empty?
+        ncc.ncc_activate owner if overlay.ncc_tokens_for(owner).empty?
       end
 
-      private
-
       def owner_for(token)
-        divergent_token = token.ancestors.find { |t| t.node == divergent }
-        ncc.tokens.find { |t| t.ancestors.include? divergent_token }
+        # find a token in the NCC node that has the same lineage as this token:
+        # - the NCC token will be a direct descendant of the divergent, therefore
+        # - one of this token's ancestors will be a duplicate of that token
+        # TODO: this should be more resilient, but child token creation does not allow for much else at the moment
+        ncc.tokens.find { |t| token.ancestors.any? { |ancestor| ancestor.duplicate?(t) } }
       end
     end
   end