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
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require 'securerandom'
3
4
  require 'sqlite3'
4
5
  require 'json'
5
6
  require_relative 'store'
@@ -7,18 +8,20 @@ require_relative 'store'
7
8
  module KBS
8
9
  module Blackboard
9
10
  module Persistence
11
+ # Keeps blackboard facts in a SQLite database.
10
12
  class SqliteStore < Store
11
13
  attr_reader :db, :db_path, :session_id
12
14
 
13
15
  def initialize(db_path: ':memory:', session_id: nil)
16
+ super()
14
17
  @db_path = db_path
15
- @session_id = session_id
18
+ @session_id = session_id || SecureRandom.uuid
16
19
  @transaction_depth = 0
20
+ @db = SQLite3::Database.new(@db_path)
17
21
  setup_database
18
22
  end
19
23
 
20
24
  def setup_database
21
- @db = SQLite3::Database.new(@db_path)
22
25
  @db.results_as_hash = true
23
26
  create_tables
24
27
  create_indexes
@@ -90,17 +93,16 @@ module KBS
90
93
  [uuid]
91
94
  )
92
95
 
93
- if result
94
- @db.execute(
95
- "UPDATE facts SET retracted = 1, retracted_at = CURRENT_TIMESTAMP WHERE uuid = ?",
96
- [uuid]
97
- )
96
+ return unless result
97
+ @db.execute(
98
+ "UPDATE facts SET retracted = 1, retracted_at = CURRENT_TIMESTAMP WHERE uuid = ?",
99
+ [uuid]
100
+ )
98
101
 
99
- {
100
- type: result['fact_type'].to_sym,
101
- attributes: JSON.parse(result['attributes'], symbolize_names: true)
102
- }
103
- end
102
+ {
103
+ type: result['fact_type'].to_sym,
104
+ attributes: JSON.parse(result['attributes'], symbolize_names: true)
105
+ }
104
106
  end
105
107
 
106
108
  def update_fact(uuid, attributes)
@@ -120,13 +122,12 @@ module KBS
120
122
  [uuid]
121
123
  )
122
124
 
123
- if result
124
- {
125
- uuid: result['uuid'],
126
- type: result['fact_type'].to_sym,
127
- attributes: JSON.parse(result['attributes'], symbolize_names: true)
128
- }
129
- end
125
+ return unless result
126
+ {
127
+ uuid: result['uuid'],
128
+ type: result['fact_type'].to_sym,
129
+ attributes: JSON.parse(result['attributes'], symbolize_names: true)
130
+ }
130
131
  end
131
132
 
132
133
  def get_facts(type = nil, pattern = {})
@@ -143,13 +144,12 @@ module KBS
143
144
  results.map do |row|
144
145
  attributes = JSON.parse(row['attributes'], symbolize_names: true)
145
146
 
146
- if matches_pattern?(attributes, pattern)
147
- {
148
- uuid: row['uuid'],
149
- type: row['fact_type'].to_sym,
150
- attributes: attributes
151
- }
152
- end
147
+ next unless matches_pattern?(attributes, pattern)
148
+ {
149
+ uuid: row['uuid'],
150
+ type: row['fact_type'].to_sym,
151
+ attributes: attributes
152
+ }
153
153
  end.compact
154
154
  end
155
155
 
@@ -196,7 +196,7 @@ module KBS
196
196
  }
197
197
  end
198
198
 
199
- def transaction(&block)
199
+ def transaction(&)
200
200
  @transaction_depth += 1
201
201
  result = nil
202
202
  begin
@@ -229,11 +229,8 @@ module KBS
229
229
 
230
230
  def matches_pattern?(attributes, pattern)
231
231
  pattern.all? do |key, value|
232
- if value.is_a?(Proc)
233
- attributes[key] && value.call(attributes[key])
234
- else
235
- attributes[key] == value
236
- end
232
+ actual = attributes[key]
233
+ value.is_a?(Proc) ? actual && value.call(actual) : actual == value
237
234
  end
238
235
  end
239
236
  end
@@ -5,6 +5,16 @@ module KBS
5
5
  module Persistence
6
6
  # Abstract interface for fact persistence
7
7
  class Store
8
+ # The session the store files new facts under. nil by default: a
9
+ # Memory given a store without one makes its own.
10
+ def session_id
11
+ nil
12
+ end
13
+
14
+ def register_knowledge_source(name, description: nil, topics: [])
15
+ raise NotImplementedError, "#{self.class} must implement #register_knowledge_source"
16
+ end
17
+
8
18
  def add_fact(uuid, type, attributes)
9
19
  raise NotImplementedError, "#{self.class} must implement #add_fact"
10
20
  end
@@ -45,7 +55,7 @@ module KBS
45
55
  # Optional operation - no-op by default
46
56
  end
47
57
 
48
- def transaction(&block)
58
+ def transaction(&)
49
59
  # Default: just execute the block
50
60
  yield if block_given?
51
61
  end
@@ -39,11 +39,12 @@ module KBS
39
39
  end
40
40
 
41
41
  def consume(topic, consumer)
42
- # Get highest priority (lowest score) unconsumed message
43
- messages = @redis.zrange("messages:#{topic}", 0, 0)
44
- return nil if messages.empty?
42
+ # Atomically pop the highest priority (lowest score) message, so no
43
+ # other consumer can receive it too
44
+ popped = @redis.zpopmin("messages:#{topic}")
45
+ return nil unless popped
45
46
 
46
- message_id = messages.first
47
+ message_id = popped.first
47
48
  message_data = @redis.hgetall("message:#{message_id}")
48
49
 
49
50
  return nil if message_data.empty? || message_data['consumed'] == '1'
@@ -53,14 +54,13 @@ module KBS
53
54
  pipeline.hset("message:#{message_id}", 'consumed', '1')
54
55
  pipeline.hset("message:#{message_id}", 'consumed_by', consumer)
55
56
  pipeline.hset("message:#{message_id}", 'consumed_at', Time.now.to_f)
56
- pipeline.zrem("messages:#{topic}", message_id)
57
57
  end
58
58
 
59
59
  {
60
60
  id: message_data['id'].to_i,
61
61
  sender: message_data['sender'],
62
62
  topic: message_data['topic'],
63
- content: JSON.parse(message_data['content'], symbolize_names: true),
63
+ content: parse_content(message_data['content']),
64
64
  priority: message_data['priority'].to_i,
65
65
  posted_at: Time.at(message_data['posted_at'].to_f)
66
66
  }
@@ -79,7 +79,7 @@ module KBS
79
79
  id: message_data['id'].to_i,
80
80
  sender: message_data['sender'],
81
81
  topic: message_data['topic'],
82
- content: JSON.parse(message_data['content'], symbolize_names: true),
82
+ content: parse_content(message_data['content']),
83
83
  priority: message_data['priority'].to_i,
84
84
  posted_at: Time.at(message_data['posted_at'].to_f)
85
85
  }
@@ -106,6 +106,15 @@ module KBS
106
106
  unconsumed_messages: total_unconsumed
107
107
  }
108
108
  end
109
+
110
+ private
111
+
112
+ # A String posted as content is stored as is, so it may not be JSON.
113
+ def parse_content(content)
114
+ JSON.parse(content, symbolize_names: true)
115
+ rescue JSON::ParserError
116
+ content
117
+ end
109
118
  end
110
119
  end
111
120
  end
data/lib/kbs/condition.rb CHANGED
@@ -1,16 +1,56 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module KBS
4
+ # One condition of a rule: a fact type and a pattern its attributes must
5
+ # fit, optionally negated, existential or logical.
4
6
  class Condition
5
- attr_reader :type, :pattern, :variable_bindings, :negated
7
+ attr_reader :type, :pattern, :variable_bindings, :negated, :exists, :logical
8
+
9
+ # What #summary puts before a negated or exists condition.
10
+ SUMMARY_PREFIXES = { "without" => "NOT ", "exists" => "EXISTS " }.freeze
11
+
12
+ # @param negated [Boolean] match when no fact fits the pattern
13
+ # @param exists [Boolean] match once when at least one fact fits the
14
+ # pattern, instead of once for each fact
15
+ # @param logical [Boolean] facts the rule asserts depend on this
16
+ # condition staying matched; logical conditions come first in a rule
17
+ def initialize(type, pattern = {}, negated: false, exists: false, logical: false)
18
+ raise ArgumentError, "a condition cannot be both negated and exists" if negated && exists
6
19
 
7
- def initialize(type, pattern = {}, negated: false)
8
20
  @type = type
9
21
  @pattern = pattern
10
22
  @negated = negated
23
+ @exists = exists
24
+ @logical = logical
11
25
  @variable_bindings = extract_variables(pattern)
12
26
  end
13
27
 
28
+ # One line for listings: the type and pattern, marked NOT or EXISTS.
29
+ def summary
30
+ prefix = SUMMARY_PREFIXES[keyword] || ""
31
+ "#{prefix}#{@type}(#{RuleSource.pattern_source(@pattern)})"
32
+ end
33
+
34
+ # The value each of this condition's variables takes from `fact`.
35
+ def bindings_from(fact)
36
+ attributes = fact.attributes
37
+ @variable_bindings.transform_values { |field| attributes[field] }
38
+ end
39
+
40
+ # Whether the condition adds a fact to the rule's match. Negated and
41
+ # exists conditions test for facts but contribute none.
42
+ def binds_fact?
43
+ !@negated && !@exists
44
+ end
45
+
46
+ # The DSL keyword that writes this condition.
47
+ def keyword
48
+ return "without" if @negated
49
+ return "exists" if @exists
50
+
51
+ "on"
52
+ end
53
+
14
54
  private
15
55
 
16
56
  def extract_variables(pattern)