kbs 0.2.1 → 0.3.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 +68 -1
  3. data/README.md +52 -25
  4. data/lib/kbs/agenda.rb +208 -0
  5. data/lib/kbs/alpha_memory.rb +55 -7
  6. data/lib/kbs/alpha_network.rb +83 -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 +39 -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 +104 -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 +75 -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 +27 -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 +60 -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
@@ -5,6 +5,7 @@ require 'time'
5
5
 
6
6
  module KBS
7
7
  module Blackboard
8
+ # A priority message queue between knowledge sources, kept in SQLite.
8
9
  class MessageQueue
9
10
  def initialize(db)
10
11
  @db = db
@@ -40,49 +41,50 @@ module KBS
40
41
 
41
42
  @db.execute(
42
43
  "INSERT INTO blackboard_messages (sender, topic, content, priority) VALUES (?, ?, ?, ?)",
43
- [sender, topic, content_json, priority]
44
+ [sender.to_s, topic.to_s, content_json, priority]
44
45
  )
45
46
  end
46
47
 
47
48
  def consume(topic, consumer)
48
- result = @db.get_first_row(
49
- "SELECT * FROM blackboard_messages WHERE topic = ? AND consumed = 0 ORDER BY priority DESC, posted_at ASC LIMIT 1",
50
- [topic]
51
- )
49
+ result = nil
52
50
 
53
- if result
54
- @db.execute(
55
- "UPDATE blackboard_messages SET consumed = 1, consumed_by = ?, consumed_at = CURRENT_TIMESTAMP WHERE id = ?",
56
- [consumer, result['id']]
51
+ loop do
52
+ result = @db.get_first_row(
53
+ "SELECT * FROM blackboard_messages WHERE topic = ? AND consumed = 0 ORDER BY priority DESC, posted_at ASC LIMIT 1",
54
+ [topic.to_s]
57
55
  )
56
+ break unless result
58
57
 
59
- {
60
- id: result['id'],
61
- sender: result['sender'],
62
- topic: result['topic'],
63
- content: JSON.parse(result['content'], symbolize_names: true),
64
- priority: result['priority'],
65
- posted_at: Time.parse(result['posted_at'])
66
- }
58
+ # Claim the message only if no other consumer took it since the SELECT
59
+ @db.execute(
60
+ "UPDATE blackboard_messages SET consumed = 1, consumed_by = ?, consumed_at = CURRENT_TIMESTAMP WHERE id = ? AND consumed = 0",
61
+ [consumer.to_s, result['id']]
62
+ )
63
+ break if @db.changes == 1
67
64
  end
65
+
66
+ result && message_from(result)
67
+ end
68
+
69
+ # A row of blackboard_messages as the Hash handed to consumers.
70
+ def message_from(row)
71
+ {
72
+ id: row['id'],
73
+ sender: row['sender'],
74
+ topic: row['topic'],
75
+ content: parse_content(row['content']),
76
+ priority: row['priority'],
77
+ posted_at: Time.parse("#{row['posted_at']} UTC").localtime
78
+ }
68
79
  end
69
80
 
70
81
  def peek(topic, limit: 10)
71
82
  results = @db.execute(
72
83
  "SELECT * FROM blackboard_messages WHERE topic = ? AND consumed = 0 ORDER BY priority DESC, posted_at ASC LIMIT ?",
73
- [topic, limit]
84
+ [topic.to_s, limit]
74
85
  )
75
86
 
76
- results.map do |row|
77
- {
78
- id: row['id'],
79
- sender: row['sender'],
80
- topic: row['topic'],
81
- content: JSON.parse(row['content'], symbolize_names: true),
82
- priority: row['priority'],
83
- posted_at: Time.parse(row['posted_at'])
84
- }
85
- end
87
+ results.map { |row| message_from(row) }
86
88
  end
87
89
 
88
90
  def stats
@@ -91,6 +93,15 @@ module KBS
91
93
  unconsumed_messages: @db.get_first_value("SELECT COUNT(*) FROM blackboard_messages WHERE consumed = 0")
92
94
  }
93
95
  end
96
+
97
+ private
98
+
99
+ # A String posted as content is stored as is, so it may not be JSON.
100
+ def parse_content(content)
101
+ JSON.parse(content, symbolize_names: true)
102
+ rescue JSON::ParserError
103
+ content
104
+ end
94
105
  end
95
106
  end
96
107
  end
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require 'securerandom'
3
4
  require_relative 'store'
4
5
  require_relative 'redis_store'
5
6
  require_relative 'sqlite_store'
@@ -14,6 +15,9 @@ module KBS
14
15
  # - Durable audit trail via SQLite
15
16
  # - Best of both worlds for production systems
16
17
  class HybridStore < Store
18
+ # The SQLite tables the audit log writes to.
19
+ AUDIT_TABLES = %w[fact_history rules_fired].freeze
20
+
17
21
  attr_reader :redis_store, :sqlite_store, :session_id
18
22
 
19
23
  def initialize(
@@ -22,7 +26,8 @@ module KBS
22
26
  db_path: 'audit.db',
23
27
  session_id: nil
24
28
  )
25
- @session_id = session_id
29
+ super()
30
+ @session_id = session_id || SecureRandom.uuid
26
31
 
27
32
  # Redis for hot data (facts, messages)
28
33
  @redis_store = RedisStore.new(
@@ -71,15 +76,15 @@ module KBS
71
76
  @redis_store.clear_session(session_id)
72
77
  end
73
78
 
74
- # Stats combined from both stores
79
+ # The Redis store's stats, plus :audit_records from SQLite.
75
80
  def stats
76
- redis_stats = @redis_store.stats
77
- sqlite_stats = @sqlite_store.stats
81
+ @redis_store.stats.merge(audit_records: audit_record_count)
82
+ end
78
83
 
79
- # Prefer Redis for fact counts (authoritative)
80
- redis_stats.merge(
81
- audit_records: sqlite_stats[:total_facts] # SQLite tracks audit records
82
- )
84
+ # Rows the audit log has written to SQLite: fact changes plus rule
85
+ # firings. Zero before a Memory has created the audit tables.
86
+ def audit_record_count
87
+ AUDIT_TABLES.sum { |table| row_count(table) }
83
88
  end
84
89
 
85
90
  def vacuum
@@ -87,7 +92,7 @@ module KBS
87
92
  @sqlite_store.vacuum
88
93
  end
89
94
 
90
- def transaction(&block)
95
+ def transaction(&)
91
96
  # Redis and SQLite transactions are separate
92
97
  # Execute block in context of both
93
98
  yield
@@ -112,6 +117,12 @@ module KBS
112
117
  def hybrid?
113
118
  true
114
119
  end
120
+
121
+ # The number of rows in a SQLite table, or 0 when it does not exist.
122
+ def row_count(table)
123
+ exists = db.get_first_value("SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name = ?", [table])
124
+ exists.zero? ? 0 : db.get_first_value("SELECT COUNT(*) FROM #{table}")
125
+ end
115
126
  end
116
127
  end
117
128
  end
@@ -1,6 +1,12 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'redis'
3
+ # redis is optional. Load it when present so callers can still use Redis
4
+ # after requiring kbs; #connect raises LoadError when a store needs it.
5
+ begin
6
+ require 'redis'
7
+ rescue LoadError
8
+ nil
9
+ end
4
10
  require 'json'
5
11
  require 'securerandom'
6
12
  require_relative 'store'
@@ -8,12 +14,14 @@ require_relative 'store'
8
14
  module KBS
9
15
  module Blackboard
10
16
  module Persistence
17
+ # Keeps blackboard facts in Redis.
11
18
  class RedisStore < Store
12
19
  attr_reader :redis, :session_id
13
20
 
14
21
  def initialize(url: 'redis://localhost:6379/0', session_id: nil, redis: nil)
22
+ super()
15
23
  @session_id = session_id || SecureRandom.uuid
16
- @redis = redis || Redis.new(url: url)
24
+ @redis = redis || connect(url)
17
25
  @transaction_depth = 0
18
26
  end
19
27
 
@@ -85,10 +93,10 @@ module KBS
85
93
  def get_facts(type = nil, pattern = {})
86
94
  # Get UUIDs from appropriate index
87
95
  uuids = if type
88
- @redis.sinter('facts:active', "facts:type:#{type}")
89
- else
90
- @redis.smembers('facts:active')
91
- end
96
+ @redis.sinter('facts:active', "facts:type:#{type}")
97
+ else
98
+ @redis.smembers('facts:active')
99
+ end
92
100
 
93
101
  # Fetch and filter facts
94
102
  facts = []
@@ -98,25 +106,22 @@ module KBS
98
106
 
99
107
  attributes = JSON.parse(fact_data['attributes'], symbolize_names: true)
100
108
 
101
- if matches_pattern?(attributes, pattern)
102
- facts << {
103
- uuid: fact_data['uuid'],
104
- type: fact_data['type'].to_sym,
105
- attributes: attributes
106
- }
107
- end
109
+ next unless matches_pattern?(attributes, pattern)
110
+ facts << {
111
+ uuid: fact_data['uuid'],
112
+ type: fact_data['type'].to_sym,
113
+ attributes: attributes
114
+ }
108
115
  end
109
116
 
110
117
  facts
111
118
  end
112
119
 
113
- def query_facts(conditions = nil, params = [])
114
- # Redis doesn't support SQL queries
115
- # For complex queries, use get_facts with pattern matching
116
- # or implement custom Redis Lua scripts
117
- get_facts
120
+ def query_facts(_conditions = nil, _params = [])
121
+ raise NotImplementedError, "#{self.class} does not support SQL queries"
118
122
  end
119
123
 
124
+ # A nil description is left out of the hash: Redis cannot store nil.
120
125
  def register_knowledge_source(name, description: nil, topics: [])
121
126
  topics_json = JSON.generate(topics)
122
127
 
@@ -126,7 +131,7 @@ module KBS
126
131
  'topics' => topics_json,
127
132
  'active' => '1',
128
133
  'registered_at' => Time.now.to_f
129
- })
134
+ }.compact)
130
135
 
131
136
  @redis.sadd('knowledge_sources:active', name)
132
137
  end
@@ -141,27 +146,15 @@ module KBS
141
146
  @redis.del("facts:session:#{session_id}")
142
147
  end
143
148
 
144
- def vacuum
145
- # Remove retracted facts from Redis to free memory
146
- all_uuids = @redis.smembers('facts:all')
149
+ # How long a retracted fact is kept before vacuum removes it.
150
+ RETENTION_SECONDS = 30 * 24 * 60 * 60
147
151
 
148
- all_uuids.each do |uuid|
152
+ # Removes retracted facts older than RETENTION_SECONDS from Redis
153
+ # to free memory.
154
+ def vacuum
155
+ @redis.smembers('facts:all').each do |uuid|
149
156
  fact_data = @redis.hgetall("fact:#{uuid}")
150
- if fact_data['retracted'] == '1'
151
- # Calculate if fact is old enough to remove (e.g., > 30 days)
152
- retracted_at = fact_data['retracted_at'].to_f
153
- if Time.now.to_f - retracted_at > (30 * 24 * 60 * 60)
154
- type = fact_data['type']
155
- session_id = fact_data['session_id']
156
-
157
- @redis.multi do |pipeline|
158
- pipeline.del("fact:#{uuid}")
159
- pipeline.srem('facts:all', uuid)
160
- pipeline.srem("facts:type:#{type}", uuid)
161
- pipeline.srem("facts:session:#{session_id}", uuid) if session_id
162
- end
163
- end
164
- end
157
+ purge_fact(uuid, fact_data) if expired?(fact_data)
165
158
  end
166
159
  end
167
160
 
@@ -177,16 +170,12 @@ module KBS
177
170
  }
178
171
  end
179
172
 
180
- def transaction(&block)
173
+ def transaction(&)
181
174
  @transaction_depth += 1
182
175
  begin
183
- if @transaction_depth == 1
184
- # Redis MULTI/EXEC happens in individual operations
185
- # This provides a consistent interface
186
- yield
187
- else
188
- yield
189
- end
176
+ # Redis MULTI/EXEC happens in individual operations; this
177
+ # provides a consistent interface.
178
+ yield
190
179
  ensure
191
180
  @transaction_depth -= 1
192
181
  end
@@ -203,13 +192,32 @@ module KBS
203
192
 
204
193
  private
205
194
 
195
+ # Raises LoadError here, not at require time, when redis is missing.
196
+ def connect(url)
197
+ require 'redis'
198
+ Redis.new(url: url)
199
+ end
200
+
201
+ # Whether a fact's hash says it was retracted long enough ago.
202
+ def expired?(fact_data, now = Time.now.to_f)
203
+ fact_data['retracted'] == '1' && now - fact_data['retracted_at'].to_f > RETENTION_SECONDS
204
+ end
205
+
206
+ # Deletes a fact's hash and takes its uuid out of every index.
207
+ def purge_fact(uuid, fact_data)
208
+ session_id = fact_data['session_id']
209
+ @redis.multi do |pipeline|
210
+ pipeline.del("fact:#{uuid}")
211
+ pipeline.srem('facts:all', uuid)
212
+ pipeline.srem("facts:type:#{fact_data['type']}", uuid)
213
+ pipeline.srem("facts:session:#{session_id}", uuid) if session_id
214
+ end
215
+ end
216
+
206
217
  def matches_pattern?(attributes, pattern)
207
218
  pattern.all? do |key, value|
208
- if value.is_a?(Proc)
209
- attributes[key] && value.call(attributes[key])
210
- else
211
- attributes[key] == value
212
- end
219
+ actual = attributes[key]
220
+ value.is_a?(Proc) ? actual && value.call(actual) : actual == value
213
221
  end
214
222
  end
215
223
  end
@@ -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,53 @@
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
+ # @param negated [Boolean] match when no fact fits the pattern
10
+ # @param exists [Boolean] match once when at least one fact fits the
11
+ # pattern, instead of once for each fact
12
+ # @param logical [Boolean] facts the rule asserts depend on this
13
+ # condition staying matched; logical conditions come first in a rule
14
+ def initialize(type, pattern = {}, negated: false, exists: false, logical: false)
15
+ raise ArgumentError, "a condition cannot be both negated and exists" if negated && exists
6
16
 
7
- def initialize(type, pattern = {}, negated: false)
8
17
  @type = type
9
18
  @pattern = pattern
10
19
  @negated = negated
20
+ @exists = exists
21
+ @logical = logical
11
22
  @variable_bindings = extract_variables(pattern)
12
23
  end
13
24
 
25
+ # One line for listings: the type and pattern, marked NOT or EXISTS.
26
+ def summary
27
+ prefix = { "without" => "NOT ", "exists" => "EXISTS " }.fetch(keyword, "")
28
+ "#{prefix}#{@type}(#{RuleSource.pattern_source(@pattern)})"
29
+ end
30
+
31
+ # The value each of this condition's variables takes from `fact`.
32
+ def bindings_from(fact)
33
+ attributes = fact.attributes
34
+ @variable_bindings.transform_values { |field| attributes[field] }
35
+ end
36
+
37
+ # Whether the condition adds a fact to the rule's match. Negated and
38
+ # exists conditions test for facts but contribute none.
39
+ def binds_fact?
40
+ !@negated && !@exists
41
+ end
42
+
43
+ # The DSL keyword that writes this condition.
44
+ def keyword
45
+ return "without" if @negated
46
+ return "exists" if @exists
47
+
48
+ "on"
49
+ end
50
+
14
51
  private
15
52
 
16
53
  def extract_variables(pattern)