kbs 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +87 -1
  3. data/README.md +66 -25
  4. data/lib/kbs/agenda.rb +301 -0
  5. data/lib/kbs/alpha_memory.rb +80 -9
  6. data/lib/kbs/alpha_network.rb +95 -0
  7. data/lib/kbs/beta_memory.rb +54 -19
  8. data/lib/kbs/blackboard/audit_log.rb +26 -25
  9. data/lib/kbs/blackboard/engine.rb +49 -40
  10. data/lib/kbs/blackboard/fact.rb +17 -21
  11. data/lib/kbs/blackboard/memory.rb +116 -40
  12. data/lib/kbs/blackboard/message_queue.rb +39 -28
  13. data/lib/kbs/blackboard/persistence/hybrid_store.rb +20 -9
  14. data/lib/kbs/blackboard/persistence/redis_store.rb +59 -51
  15. data/lib/kbs/blackboard/persistence/sqlite_store.rb +29 -32
  16. data/lib/kbs/blackboard/persistence/store.rb +11 -1
  17. data/lib/kbs/blackboard/redis_message_queue.rb +16 -7
  18. data/lib/kbs/condition.rb +42 -2
  19. data/lib/kbs/decompiler.rb +300 -124
  20. data/lib/kbs/dsl/condition_helpers.rb +8 -6
  21. data/lib/kbs/dsl/knowledge_base.rb +73 -93
  22. data/lib/kbs/dsl/pattern_evaluator.rb +38 -15
  23. data/lib/kbs/dsl/rule_builder.rb +118 -40
  24. data/lib/kbs/dsl/variable.rb +51 -6
  25. data/lib/kbs/dsl.rb +10 -3
  26. data/lib/kbs/engine.rb +395 -77
  27. data/lib/kbs/errors.rb +38 -0
  28. data/lib/kbs/exists_node.rb +12 -0
  29. data/lib/kbs/fact.rb +5 -19
  30. data/lib/kbs/fact_registry.rb +51 -0
  31. data/lib/kbs/introspection.rb +93 -0
  32. data/lib/kbs/join_indexing.rb +106 -0
  33. data/lib/kbs/join_node.rb +93 -57
  34. data/lib/kbs/join_test_builder.rb +80 -0
  35. data/lib/kbs/join_tests.rb +66 -0
  36. data/lib/kbs/memory_index.rb +104 -0
  37. data/lib/kbs/negation_node.rb +6 -82
  38. data/lib/kbs/network_node.rb +31 -0
  39. data/lib/kbs/pattern_matching.rb +52 -0
  40. data/lib/kbs/production_node.rb +50 -6
  41. data/lib/kbs/quantifier_node.rb +140 -0
  42. data/lib/kbs/rule.rb +26 -13
  43. data/lib/kbs/rule_source.rb +74 -0
  44. data/lib/kbs/rule_step.rb +27 -0
  45. data/lib/kbs/token.rb +76 -10
  46. data/lib/kbs/tracer.rb +80 -0
  47. data/lib/kbs/truth_maintenance.rb +82 -0
  48. data/lib/kbs/version.rb +1 -1
  49. data/lib/kbs/working_memory.rb +25 -3
  50. data/lib/kbs.rb +17 -4
  51. metadata +22 -129
  52. data/.envrc +0 -3
  53. data/.github/workflows/deploy-github-pages.yml +0 -52
  54. data/COMMITS.md +0 -196
  55. data/Rakefile +0 -8
  56. data/docs/advanced/custom-persistence.md +0 -775
  57. data/docs/advanced/debugging.md +0 -726
  58. data/docs/advanced/index.md +0 -8
  59. data/docs/advanced/performance.md +0 -865
  60. data/docs/advanced/testing.md +0 -827
  61. data/docs/api/blackboard.md +0 -1157
  62. data/docs/api/engine.md +0 -1047
  63. data/docs/api/facts.md +0 -1212
  64. data/docs/api/index.md +0 -12
  65. data/docs/api/rules.md +0 -1104
  66. data/docs/architecture/blackboard.md +0 -544
  67. data/docs/architecture/index.md +0 -277
  68. data/docs/architecture/network-structure.md +0 -343
  69. data/docs/architecture/rete-algorithm.md +0 -737
  70. data/docs/assets/css/custom.css +0 -83
  71. data/docs/assets/images/blackboard-architecture.svg +0 -136
  72. data/docs/assets/images/compiled-network.svg +0 -101
  73. data/docs/assets/images/fact-assertion-flow.svg +0 -117
  74. data/docs/assets/images/fact-rule-relationship.svg +0 -65
  75. data/docs/assets/images/fact-structure.svg +0 -42
  76. data/docs/assets/images/inference-cycle.svg +0 -47
  77. data/docs/assets/images/kb-components.svg +0 -43
  78. data/docs/assets/images/kbs.jpg +0 -0
  79. data/docs/assets/images/pattern-matching-trace.svg +0 -136
  80. data/docs/assets/images/rete-network-layers.svg +0 -96
  81. data/docs/assets/images/rule-structure.svg +0 -44
  82. data/docs/assets/images/system-layers.svg +0 -69
  83. data/docs/assets/images/trading-signal-network.svg +0 -139
  84. data/docs/assets/js/mathjax.js +0 -17
  85. data/docs/examples/index.md +0 -223
  86. data/docs/guides/blackboard-memory.md +0 -589
  87. data/docs/guides/dsl.md +0 -1321
  88. data/docs/guides/facts.md +0 -652
  89. data/docs/guides/getting-started.md +0 -385
  90. data/docs/guides/index.md +0 -23
  91. data/docs/guides/negation.md +0 -529
  92. data/docs/guides/pattern-matching.md +0 -561
  93. data/docs/guides/persistence.md +0 -451
  94. data/docs/guides/variable-binding.md +0 -491
  95. data/docs/guides/writing-rules.md +0 -914
  96. data/docs/index.md +0 -155
  97. data/docs/installation.md +0 -156
  98. data/docs/quick-start.md +0 -221
  99. data/docs/what-is-a-fact.md +0 -694
  100. data/docs/what-is-a-knowledge-base.md +0 -350
  101. data/docs/what-is-a-rule.md +0 -833
  102. data/examples/.gitignore +0 -1
  103. data/examples/README.md +0 -531
  104. data/examples/advanced_example.rb +0 -270
  105. data/examples/advanced_example_dsl.rb +0 -224
  106. data/examples/ai_enhanced_kbs.rb +0 -523
  107. data/examples/ai_enhanced_kbs_dsl.rb +0 -538
  108. data/examples/blackboard_demo.rb +0 -50
  109. data/examples/blackboard_demo_dsl.rb +0 -50
  110. data/examples/car_diagnostic.rb +0 -64
  111. data/examples/car_diagnostic_dsl.rb +0 -54
  112. data/examples/concurrent_inference_demo.rb +0 -362
  113. data/examples/concurrent_inference_demo_dsl.rb +0 -362
  114. data/examples/csv_trading_system.rb +0 -559
  115. data/examples/csv_trading_system_dsl.rb +0 -525
  116. data/examples/iot_demo_using_dsl.rb +0 -83
  117. data/examples/portfolio_rebalancing_system.rb +0 -651
  118. data/examples/portfolio_rebalancing_system_dsl.rb +0 -613
  119. data/examples/redis_trading_demo.rb +0 -177
  120. data/examples/redis_trading_demo_dsl.rb +0 -177
  121. data/examples/rule_source_demo.rb +0 -123
  122. data/examples/run_all.rb +0 -50
  123. data/examples/run_all_dsl.rb +0 -49
  124. data/examples/sample_stock_data.csv +0 -46
  125. data/examples/stock_trading_advanced.rb +0 -469
  126. data/examples/stock_trading_advanced_dsl.rb +0 -404
  127. data/examples/temp_dsl.txt +0 -9392
  128. data/examples/timestamped_trading.rb +0 -286
  129. data/examples/timestamped_trading_dsl.rb +0 -258
  130. data/examples/trading_demo.rb +0 -334
  131. data/examples/trading_demo_dsl.rb +0 -322
  132. data/examples/working_demo.rb +0 -176
  133. data/examples/working_demo_dsl.rb +0 -160
  134. data/mkdocs.yml +0 -181
@@ -0,0 +1,93 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KBS
4
+ # What the engine can tell about itself while it runs, as CLIPS `watch`
5
+ # and `matches` do. Included in KBS::Engine, whose tracer, agenda, rule
6
+ # paths and network it reads.
7
+ module Introspection
8
+ # Starts writing a line for each change to the watched items, or to
9
+ # every item when none is given: :facts, :activations, :rules. Lines
10
+ # go to #trace_output, $stdout by default. See KBS::Tracer.
11
+ def watch(*items)
12
+ @tracer.watch(*items)
13
+ listen_to_agenda
14
+ self
15
+ end
16
+
17
+ def unwatch(*items)
18
+ @tracer.unwatch(*items)
19
+ listen_to_agenda
20
+ self
21
+ end
22
+
23
+ # The agenda reports to the tracer only while activations are
24
+ # watched, so an unwatched engine pays nothing for it.
25
+ def listen_to_agenda
26
+ @agenda.listener = @tracer.watching?(:activations) ? @tracer : nil
27
+ end
28
+
29
+ def trace_output
30
+ @tracer.output
31
+ end
32
+
33
+ def trace_output=(output)
34
+ @tracer.output = output
35
+ end
36
+
37
+ # How far each condition of a rule has matched: the facts that fit
38
+ # the condition on its own, and the partial matches of the rule up to
39
+ # and including it. The first condition whose partial_matches is zero
40
+ # is the one that keeps the rule from firing.
41
+ #
42
+ # @return [Hash, nil] { rule:, conditions: [{ keyword:, type:,
43
+ # alpha_matches:, partial_matches: }], matches:, activations: };
44
+ # nil for an unknown rule
45
+ def matches(rule_name)
46
+ path = @rule_paths[rule_name]
47
+ return nil unless path
48
+
49
+ node = @production_nodes[rule_name]
50
+ tokens = node.tokens
51
+ {
52
+ rule: rule_name,
53
+ conditions: path.map(&:matches),
54
+ matches: tokens.size,
55
+ activations: tokens.count { |token| !node.fired?(token) }
56
+ }
57
+ end
58
+
59
+ # The work each condition of a rule has cost so far. See
60
+ # KBS::JoinIndexing::Activity. Rules that share a node report the
61
+ # same counts for it.
62
+ #
63
+ # @return [Array<Hash>, nil] one Hash per condition; nil for an
64
+ # unknown rule
65
+ def join_activity(rule_name)
66
+ @rule_paths[rule_name]&.map(&:activity)
67
+ end
68
+
69
+ def reset_join_activity
70
+ @beta_nodes.each(&:reset_activity)
71
+ end
72
+
73
+ # The size of the network and of what it holds.
74
+ def network_stats
75
+ {
76
+ rules: @rules.size,
77
+ facts: @working_memory.facts.size,
78
+ alpha_memories: @alpha_memories.size,
79
+ beta_nodes: @beta_nodes.size,
80
+ conditions: @rules.sum { |rule| rule.conditions.size },
81
+ partial_matches: @beta_nodes.sum { |node| node.successors.grep(BetaMemory).sum(&:size) },
82
+ activations: @agenda.size
83
+ }
84
+ end
85
+
86
+ # Every join, negation and exists node in the network. Rules that
87
+ # start with the same conditions share nodes, so there can be fewer
88
+ # nodes than conditions.
89
+ def beta_nodes
90
+ @beta_nodes.dup
91
+ end
92
+ end
93
+ end
@@ -0,0 +1,106 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KBS
4
+ # Lets a join or negation node find its candidates through hash indexes
5
+ # on its two memories.
6
+ #
7
+ # The node's equality tests between a token and a fact (the ones a
8
+ # shared ?variable compiles to) become the index key: the alpha memory
9
+ # is indexed on the fact fields and the beta memory on the token
10
+ # fields. Every other test is "residual" and is still evaluated for
11
+ # each candidate. A node with no such test scans its memories.
12
+ #
13
+ # The including class supplies `tests`, `alpha_memory` and
14
+ # `beta_memory` readers and includes KBS::JoinTests.
15
+ module JoinIndexing
16
+ # Counts of the work a node has done, to find the expensive
17
+ # condition of a rule:
18
+ #
19
+ # left_activations tokens that arrived from the conditions before
20
+ # right_activations facts that arrived for this condition
21
+ # comparisons candidates looked at; a hash join keeps this
22
+ # close to matches
23
+ # matches candidates that passed
24
+ Activity = Struct.new(:left_activations, :right_activations, :comparisons, :matches)
25
+
26
+ attr_reader :residual_tests
27
+
28
+ # The counts so far, as a snapshot.
29
+ def activity
30
+ Activity.new(@left_activations, @right_activations, @comparisons, @matches)
31
+ end
32
+
33
+ def reset_activity
34
+ @left_activations = @right_activations = @comparisons = @matches = 0
35
+ end
36
+
37
+ # Call when the tests or memories are set.
38
+ def build_join_indexes
39
+ reset_activity unless @matches
40
+ keyed, @residual_tests = (tests || []).partition { |test| JoinIndexing.indexable?(test) }
41
+ @right_index = @left_index = nil
42
+ return if keyed.empty? || alpha_memory.nil? || beta_memory.nil?
43
+
44
+ index_memories(keyed)
45
+ end
46
+
47
+ # Indexes both memories on the fields that the `keyed` tests compare.
48
+ def index_memories(keyed)
49
+ @fact_fields = keyed.map { |test| test[:fact_field] }
50
+ @token_specs = keyed.map { |test| [test[:token_field_index], test[:token_field]] }
51
+ @right_index = alpha_memory.index_on(@fact_fields)
52
+ @left_index = beta_memory.index_on(@token_specs)
53
+ end
54
+
55
+ def indexed?
56
+ !@right_index.nil?
57
+ end
58
+
59
+ # Facts in the alpha memory that pass the indexed tests for `token`.
60
+ def candidate_facts(token)
61
+ return alpha_memory.items unless indexed?
62
+
63
+ @right_index.lookup(MemoryIndex.token_key(token, @token_specs))
64
+ end
65
+
66
+ # Tokens in the beta memory that pass the indexed tests for `fact`.
67
+ def candidate_tokens(fact)
68
+ return beta_memory.tokens unless indexed?
69
+
70
+ @left_index.lookup(MemoryIndex.fact_key(fact, @fact_fields))
71
+ end
72
+
73
+ # Facts that join with `token`. Without residual tests the candidates
74
+ # are the matches, handed on without a copy: joining a match never
75
+ # changes the memory it came from.
76
+ def matching_facts(token)
77
+ candidates = candidate_facts(token)
78
+ matches = @residual_tests.empty? ? candidates : candidates.select { |fact| join_tests_pass?(@residual_tests, token, fact) }
79
+ @left_activations += 1
80
+ count(candidates, matches)
81
+ end
82
+
83
+ # Tokens that join with `fact`.
84
+ def matching_tokens(fact)
85
+ candidates = candidate_tokens(fact)
86
+ matches = @residual_tests.empty? ? candidates : candidates.select { |token| join_tests_pass?(@residual_tests, token, fact) }
87
+ @right_activations += 1
88
+ count(candidates, matches)
89
+ end
90
+
91
+ # Adds to the activity counts and returns the matches.
92
+ def count(candidates, matches)
93
+ @comparisons += candidates.size
94
+ @matches += matches.size
95
+ matches
96
+ end
97
+
98
+ # An equality test between a token field and a fact field.
99
+ def self.indexable?(test)
100
+ test[:operation] == :eq &&
101
+ test.key?(:token_field_index) &&
102
+ !test.key?(:expected_value) &&
103
+ !test.key?(:other_fact_field)
104
+ end
105
+ end
106
+ end
data/lib/kbs/join_node.rb CHANGED
@@ -1,9 +1,15 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module KBS
4
+ # Joins the partial matches of the conditions before it with the facts
5
+ # of one more positive condition.
4
6
  class JoinNode
5
- attr_accessor :alpha_memory, :beta_memory, :successors, :tests
6
- attr_reader :left_linked, :right_linked
7
+ include NetworkNode
8
+ include JoinTests
9
+ include JoinIndexing
10
+
11
+ attr_accessor :successors
12
+ attr_reader :alpha_memory, :beta_memory, :tests, :left_linked, :right_linked
7
13
 
8
14
  def initialize(alpha_memory, beta_memory, tests = [])
9
15
  @alpha_memory = alpha_memory
@@ -12,18 +18,36 @@ module KBS
12
18
  @tests = tests
13
19
  @left_linked = true
14
20
  @right_linked = true
21
+ @tokens_by_fact = {}
15
22
 
16
23
  alpha_memory.successors << self if alpha_memory
17
24
  beta_memory.successors << self if beta_memory
25
+ build_join_indexes
26
+ end
27
+
28
+ def tests=(tests)
29
+ @tests = tests
30
+ build_join_indexes
31
+ end
32
+
33
+ def alpha_memory=(memory)
34
+ @alpha_memory = memory
35
+ build_join_indexes
36
+ end
37
+
38
+ def beta_memory=(memory)
39
+ @beta_memory = memory
40
+ build_join_indexes
18
41
  end
19
42
 
20
43
  def left_unlink!
21
44
  @left_linked = false
22
45
  end
23
46
 
47
+ # The beta memory relinks when it gains its first token, and then
48
+ # propagates that token itself, so there is nothing to replay here.
24
49
  def left_relink!
25
50
  @left_linked = true
26
- @beta_memory.tokens.each { |token| left_activate(token) } if @beta_memory
27
51
  end
28
52
 
29
53
  def right_unlink!
@@ -39,78 +63,90 @@ module KBS
39
63
  # Left activation: a new token from beta memory needs to be joined with facts from alpha memory
40
64
  return unless @left_linked && @right_linked
41
65
 
42
- @alpha_memory.items.each do |fact|
43
- if perform_join_tests(token, fact)
44
- new_token = Token.new(token, fact, self)
45
- token.children << new_token if token
46
- @successors.each { |s| s.activate(new_token) }
47
- end
48
- end
66
+ matching_facts(token).each { |fact| emit(token, fact) }
49
67
  end
50
68
 
51
69
  def right_activate(fact)
52
70
  return unless @left_linked && @right_linked
53
71
 
54
- parent_tokens = @beta_memory ? @beta_memory.tokens : [Token.new(nil, nil, nil)]
55
-
56
- parent_tokens.each do |token|
57
- if perform_join_tests(token, fact)
58
- new_token = Token.new(token, fact, self)
59
- token.children << new_token if token
60
- @successors.each { |s| s.activate(new_token) }
61
- end
62
- end
72
+ parent_tokens = @beta_memory ? matching_tokens(fact) : [Token.new(nil, nil, nil)]
73
+ parent_tokens.each { |token| emit(token, fact) }
63
74
  end
64
75
 
76
+ # A token left the beta memory: remove the tokens this node built
77
+ # from it. They are among the token's children, so nothing is searched.
65
78
  def left_deactivate(token)
66
- token.children.each do |child|
67
- @successors.each { |s| s.deactivate(child) if s.respond_to?(:deactivate) }
79
+ token.children.select { |child| child.node.equal?(self) }.each do |child|
80
+ token.remove_child(child)
81
+ forget(child)
82
+ deactivate_successors(child)
68
83
  end
69
- token.children.clear
70
84
  end
71
85
 
86
+ # A fact left the alpha memory: remove the tokens this node built
87
+ # from it. The node keeps them by fact, so the beta memory is not
88
+ # scanned.
72
89
  def right_deactivate(fact)
73
- tokens_to_remove = []
74
-
75
- if @beta_memory
76
- @beta_memory.tokens.each do |token|
77
- token.children.select { |child| child.fact == fact }.each do |child|
78
- tokens_to_remove << child
79
- @successors.each { |s| s.deactivate(child) if s.respond_to?(:deactivate) }
80
- end
81
- end
90
+ tokens_for(@tokens_by_fact.delete(fact)).each do |child|
91
+ child.parent&.remove_child(child)
92
+ deactivate_successors(child)
82
93
  end
94
+ end
83
95
 
84
- tokens_to_remove.each { |token| token.parent.children.delete(token) if token.parent }
96
+ # The tokens this node has built from `fact`.
97
+ def tokens_built_from(fact)
98
+ tokens_for(@tokens_by_fact[fact])
99
+ end
100
+
101
+ # Forgets the tokens this node has built, without telling the successors.
102
+ def reset
103
+ @tokens_by_fact.clear
85
104
  end
86
105
 
87
106
  private
88
107
 
89
- def perform_join_tests(token, fact)
90
- @tests.all? do |test|
91
- fact_value = fact.attributes[test[:fact_field]]
92
-
93
- # If test has expected_value, compare against that constant
94
- if test.key?(:expected_value)
95
- if test[:operation] == :eq
96
- fact_value == test[:expected_value]
97
- elsif test[:operation] == :ne
98
- fact_value != test[:expected_value]
99
- else
100
- true
101
- end
102
- else
103
- # Otherwise compare with token value
104
- token_value = token.facts[test[:token_field_index]]&.attributes&.[](test[:token_field])
105
-
106
- if test[:operation] == :eq
107
- token_value == fact_value
108
- elsif test[:operation] == :ne
109
- token_value != fact_value
110
- else
111
- true
112
- end
113
- end
108
+ # Passes the match of `token` and `fact` on to the successors.
109
+ def emit(token, fact)
110
+ new_token = Token.new(token, fact, self)
111
+ token.add_child(new_token)
112
+ remember(new_token)
113
+ activate_successors(new_token)
114
+ end
115
+
116
+ # @tokens_by_fact maps a fact to the tokens built from it: the token
117
+ # itself while there is one, which is the common case, and a Set once
118
+ # there are more.
119
+ def remember(token)
120
+ fact = token.fact
121
+ entry = @tokens_by_fact[fact]
122
+ case entry
123
+ when nil then @tokens_by_fact[fact] = token
124
+ when Set then entry << token
125
+ else @tokens_by_fact[fact] = Set.new.compare_by_identity << entry << token
126
+ end
127
+ end
128
+
129
+ def forget(token)
130
+ fact = token.fact
131
+ entry = @tokens_by_fact[fact]
132
+ if entry.equal?(token)
133
+ @tokens_by_fact.delete(fact)
134
+ elsif entry.is_a?(Set)
135
+ forget_one_of(entry, token, fact)
136
+ end
137
+ end
138
+
139
+ # Takes `token` out of the Set of tokens built from `fact`, and drops
140
+ # the Set when it was the last.
141
+ def forget_one_of(tokens, token, fact)
142
+ @tokens_by_fact.delete(fact) if tokens.delete(token).empty?
143
+ end
144
+
145
+ def tokens_for(entry)
146
+ case entry
147
+ when nil then []
148
+ when Set then entry.to_a
149
+ else [entry]
114
150
  end
115
151
  end
116
152
  end
@@ -0,0 +1,80 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KBS
4
+ # Compiles a rule's conditions into the join tests for each condition.
5
+ #
6
+ # A ?variable that an earlier positive condition bound becomes an
7
+ # equality test against that condition's fact, so the same variable in
8
+ # two conditions joins them. A variable used twice in one condition
9
+ # compares the two attributes of the same fact. Variables that first
10
+ # appear in a negated or exists condition are local to it: such a
11
+ # condition adds no fact to the match, so it binds nothing for later
12
+ # conditions.
13
+ class JoinTestBuilder
14
+ def initialize(conditions)
15
+ @conditions = conditions
16
+ end
17
+
18
+ # @return [Array<Array<Hash>>] the tests for each condition, in order
19
+ def tests
20
+ bound = {}
21
+
22
+ @conditions.each_with_index.map do |condition, index|
23
+ local = {}
24
+ tests = type_tests(condition, index) + variable_tests(condition, bound, local)
25
+ remember_bindings(bound, local, index) if condition.binds_fact?
26
+ tests
27
+ end
28
+ end
29
+
30
+ def self.variable?(value)
31
+ value.is_a?(Symbol) && value.to_s.end_with?('?')
32
+ end
33
+
34
+ private
35
+
36
+ # Records where each variable of a condition is first bound: the
37
+ # condition's index and the field.
38
+ def remember_bindings(bound, local, index)
39
+ local.each { |variable, field| bound[variable] ||= [index, field] }
40
+ end
41
+
42
+ # Condition#type is merged over a user attribute named :type in the
43
+ # alpha pattern, so a constant or Proc on that attribute is tested here.
44
+ def type_tests(condition, index)
45
+ user_type = condition.pattern[:type]
46
+ return [] if user_type.nil? || user_type == condition.type || self.class.variable?(user_type)
47
+
48
+ [{
49
+ token_field_index: index,
50
+ token_field: :type,
51
+ fact_field: :type,
52
+ operation: :eq,
53
+ expected_value: user_type
54
+ }]
55
+ end
56
+
57
+ # Records in `local` the first field each variable appears on in this
58
+ # condition.
59
+ def variable_tests(condition, bound, local)
60
+ condition.pattern.filter_map do |field, value|
61
+ next unless self.class.variable?(value)
62
+
63
+ first_field = local[value]
64
+ next { fact_field: field, other_fact_field: first_field, operation: :eq } if first_field
65
+
66
+ local[value] = field
67
+ token_test(bound[value], field)
68
+ end
69
+ end
70
+
71
+ # The test of `field` against the earlier condition that bound the
72
+ # variable, or nil when none did.
73
+ def token_test(binding, field)
74
+ return unless binding
75
+
76
+ index, token_field = binding
77
+ { token_field_index: index, token_field: token_field, fact_field: field, operation: :eq }
78
+ end
79
+ end
80
+ end
@@ -0,0 +1,66 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KBS
4
+ # Evaluates the tests a join or negation node applies to a token and a
5
+ # fact. A test is a Hash in one of three forms:
6
+ #
7
+ # { fact_field:, expected_value:, operation: }
8
+ # compares a fact attribute with a constant, or calls a Proc with it
9
+ #
10
+ # { fact_field:, other_fact_field:, operation: }
11
+ # compares two attributes of the same fact
12
+ #
13
+ # { token_field_index:, token_field:, fact_field:, operation: }
14
+ # compares a fact attribute with an attribute of the fact that an
15
+ # earlier condition matched; token_field_index is that condition's
16
+ # position in the rule
17
+ #
18
+ # The including class supplies the tests through a `tests` reader.
19
+ module JoinTests
20
+ def perform_join_tests(token, fact)
21
+ join_tests_pass?(tests, token, fact)
22
+ end
23
+
24
+ def join_tests_pass?(tests, token, fact)
25
+ tests.all? { |test| join_test_passes?(test, token, fact) }
26
+ end
27
+
28
+ def join_test_passes?(test, token, fact)
29
+ expected = test[:expected_value]
30
+ return predicate_passes?(expected, fact.attributes[test[:fact_field]]) if expected.is_a?(Proc)
31
+
32
+ compare_join_values(test[:operation], *join_operands(test, token, fact))
33
+ end
34
+
35
+ # An operation with no entry here passes.
36
+ COMPARISONS = { eq: :==, ne: :!= }.freeze
37
+
38
+ def compare_join_values(operation, left, right)
39
+ comparison = COMPARISONS[operation]
40
+ comparison ? left.public_send(comparison, right) : true
41
+ end
42
+
43
+ private
44
+
45
+ # A Proc given as the expected value is called with the fact's value,
46
+ # and fails without one.
47
+ def predicate_passes?(predicate, value)
48
+ value && predicate.call(value)
49
+ end
50
+
51
+ # The two values a test compares: the fact's field against a constant,
52
+ # against another field of the same fact, or against a field of a fact
53
+ # matched earlier (in which case the earlier value comes first).
54
+ def join_operands(test, token, fact)
55
+ attributes = fact.attributes
56
+ fact_value = attributes[test[:fact_field]]
57
+ if test.key?(:expected_value)
58
+ [fact_value, test[:expected_value]]
59
+ elsif test.key?(:other_fact_field)
60
+ [fact_value, attributes[test[:other_fact_field]]]
61
+ else
62
+ [token.fact_at(test[:token_field_index])&.attributes&.[](test[:token_field]), fact_value]
63
+ end
64
+ end
65
+ end
66
+ end
@@ -0,0 +1,104 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KBS
4
+ # A hash index over the items of an alpha or beta memory. Items that
5
+ # share a key sit in one bucket, so a join looks up only the facts or
6
+ # tokens that can pass its equality tests instead of scanning the memory.
7
+ #
8
+ # The key is computed once, when the item is added, and remembered:
9
+ # removing an item finds its bucket even if its attributes changed since.
10
+ #
11
+ # A join on an id usually files one item per key, so a bucket holds a
12
+ # lone item itself and becomes a Set only for the second. Sets compare
13
+ # with eql?, as the index's own key table does, so a blackboard fact
14
+ # read again from its store is the same item. Adding and removing an
15
+ # item do not depend on the size of the bucket.
16
+ class MemoryIndex
17
+ EMPTY = Set.new.freeze
18
+
19
+ # @yield [item] returns the key to file the item under
20
+ def initialize(&key_for)
21
+ @key_for = key_for
22
+ @buckets = {}
23
+ @keys = {}
24
+ end
25
+
26
+ def add(item)
27
+ key = @key_for.call(item)
28
+ @keys[item] = key
29
+ bucket = @buckets[key]
30
+ case bucket
31
+ when nil then @buckets[key] = item
32
+ when Set then bucket << item
33
+ else @buckets[key] = Set[bucket, item] unless bucket.eql?(item)
34
+ end
35
+ end
36
+
37
+ def remove(item)
38
+ return unless @keys.key?(item)
39
+
40
+ key = @keys.delete(item)
41
+ bucket = @buckets[key]
42
+ if bucket.is_a?(Set)
43
+ bucket.delete(item)
44
+ return unless bucket.empty?
45
+ end
46
+ @buckets.delete(key)
47
+ end
48
+
49
+ # @return [Enumerable] the items filed under `key`, in the order they
50
+ # were added; do not modify it
51
+ def lookup(key)
52
+ bucket = @buckets[key]
53
+ case bucket
54
+ when nil then EMPTY
55
+ when Set then bucket
56
+ else [bucket]
57
+ end
58
+ end
59
+
60
+ def clear
61
+ @buckets.clear
62
+ @keys.clear
63
+ end
64
+
65
+ def size
66
+ @keys.size
67
+ end
68
+
69
+ # The index key for a fact: its value for the field, or its values for
70
+ # several fields. A single field is the common case and needs no Array.
71
+ def self.fact_key(fact, fields)
72
+ attributes = fact.attributes
73
+ return normalize(attributes[fields.first]) if fields.size == 1
74
+
75
+ fields.map { |field| normalize(attributes[field]) }
76
+ end
77
+
78
+ # The index key for a token, built like #fact_key: for each [condition
79
+ # index, field] pair, that attribute of the fact the condition matched.
80
+ def self.token_key(token, specs)
81
+ return token_value(token, *specs.first) if specs.size == 1
82
+
83
+ specs.map { |index, field| token_value(token, index, field) }
84
+ end
85
+
86
+ # The normalized attribute `field` of the fact the condition at
87
+ # `index` matched; nil when that condition matched no fact.
88
+ def self.token_value(token, index, field)
89
+ normalize(token.fact_at(index)&.attributes&.[](field))
90
+ end
91
+
92
+ # Join tests compare with ==, and a Hash key with eql?. They differ
93
+ # for numbers: 1 == 1.0, but 1 and 1.0 are different keys. Whole
94
+ # numbers are filed as Integers and Rationals as Floats, so values
95
+ # that are == land in the same bucket.
96
+ def self.normalize(value)
97
+ return value if value.is_a?(Integer) || !value.is_a?(Numeric) || !value.real?
98
+ return value unless value.finite?
99
+ return value.to_i if value == value.to_i
100
+
101
+ value.is_a?(Rational) ? value.to_f : value
102
+ end
103
+ end
104
+ end