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
@@ -14,43 +14,65 @@ module KBS
14
14
  attr_reader :session_id, :store, :message_queue, :audit_log
15
15
 
16
16
  def initialize(db_path: ':memory:', store: nil)
17
- @session_id = SecureRandom.uuid
17
+ self.class.check_store(store) if store
18
+ @session_id = store&.session_id || SecureRandom.uuid
18
19
  @observers = []
20
+ @added_in_transaction = nil
21
+ @store = store || Persistence::SqliteStore.new(db_path: db_path, session_id: @session_id)
22
+ @message_queue, @audit_log = build_components
23
+ end
19
24
 
20
- # Use provided store or create default SqliteStore
21
- @store = store || Persistence::SqliteStore.new(
22
- db_path: db_path,
23
- session_id: @session_id
24
- )
25
+ # Raises ArgumentError unless the memory can build its message queue
26
+ # and audit log on `store`.
27
+ def self.check_store(store)
28
+ return if store.respond_to?(:connection) || store.respond_to?(:db)
25
29
 
26
- # Initialize composed components based on store type
27
- setup_components
30
+ raise ArgumentError, "Store must respond to either :connection (Redis) or :db (SQLite)"
28
31
  end
29
32
 
30
33
  private
31
34
 
32
- def setup_components
33
- # Detect store type and create appropriate MessageQueue and AuditLog
35
+ # The message queue and audit log that go with the store. A store is
36
+ # told apart by what it offers: a hybrid store keeps messages in
37
+ # Redis and the audit log in SQLite, a store with a connection is
38
+ # Redis, and one with a db is SQLite.
39
+ def build_components
34
40
  if @store.respond_to?(:hybrid?) && @store.hybrid?
35
- # Hybrid store: Redis for messages, SQLite for audit
36
- require_relative 'redis_message_queue'
37
- @message_queue = RedisMessageQueue.new(@store.connection)
38
- @audit_log = AuditLog.new(@store.db, @session_id)
41
+ hybrid_components
39
42
  elsif @store.respond_to?(:connection)
40
- # Pure Redis store
41
- require_relative 'redis_message_queue'
42
- require_relative 'redis_audit_log'
43
- @message_queue = RedisMessageQueue.new(@store.connection)
44
- @audit_log = RedisAuditLog.new(@store.connection, @session_id)
45
- elsif @store.respond_to?(:db)
46
- # Pure SQLite store
47
- @message_queue = MessageQueue.new(@store.db)
48
- @audit_log = AuditLog.new(@store.db, @session_id)
43
+ redis_components
49
44
  else
50
- raise ArgumentError, "Store must respond to either :connection (Redis) or :db (SQLite)"
45
+ sqlite_components
51
46
  end
52
47
  end
53
48
 
49
+ def hybrid_components
50
+ require_relative 'redis_message_queue'
51
+ [RedisMessageQueue.new(@store.connection), AuditLog.new(@store.db, @session_id)]
52
+ end
53
+
54
+ def redis_components
55
+ require_relative 'redis_message_queue'
56
+ require_relative 'redis_audit_log'
57
+ connection = @store.connection
58
+ [RedisMessageQueue.new(connection), RedisAuditLog.new(connection, @session_id)]
59
+ end
60
+
61
+ def sqlite_components
62
+ database = @store.db
63
+ [MessageQueue.new(database), AuditLog.new(database, @session_id)]
64
+ end
65
+
66
+ # A fact's uuid, given the fact or the uuid itself.
67
+ def uuid_of(fact)
68
+ fact.is_a?(Fact) ? fact.uuid : fact
69
+ end
70
+
71
+ # The Fact for a row the store returned.
72
+ def fact_from(data)
73
+ Fact.new(*data.values_at(:uuid, :type, :attributes), self)
74
+ end
75
+
54
76
  public
55
77
 
56
78
  # Fact Management
@@ -63,27 +85,31 @@ module KBS
63
85
  end
64
86
 
65
87
  fact = Fact.new(uuid, type, attributes, self)
88
+ @added_in_transaction[uuid] = fact if @added_in_transaction
66
89
  notify_observers(:add, fact)
67
90
  fact
68
91
  end
69
92
 
93
+ # @return [KBS::Blackboard::Fact, nil] the removed fact, or nil when
94
+ # it was not active
70
95
  def remove_fact(fact)
71
- uuid = fact.is_a?(Fact) ? fact.uuid : fact
96
+ uuid = uuid_of(fact)
72
97
 
73
98
  @store.transaction do
74
99
  result = @store.remove_fact(uuid)
100
+ next unless result
75
101
 
76
- if result
77
- @audit_log.log_fact_change(uuid, result[:type], result[:attributes], 'REMOVE')
102
+ @audit_log.log_fact_change(uuid, result[:type], result[:attributes], 'REMOVE')
78
103
 
79
- fact_obj = Fact.new(uuid, result[:type], result[:attributes], self)
80
- notify_observers(:remove, fact_obj)
81
- end
104
+ fact_obj = Fact.new(uuid, result[:type], result[:attributes], self)
105
+ @added_in_transaction&.delete(uuid)
106
+ notify_observers(:remove, fact_obj)
107
+ fact_obj
82
108
  end
83
109
  end
84
110
 
85
111
  def update_fact(fact, new_attributes)
86
- uuid = fact.is_a?(Fact) ? fact.uuid : fact
112
+ uuid = uuid_of(fact)
87
113
 
88
114
  @store.transaction do
89
115
  fact_type = @store.update_fact(uuid, new_attributes)
@@ -94,12 +120,41 @@ module KBS
94
120
  end
95
121
  end
96
122
 
123
+ # The fact with this uuid as the store holds it now, or nil.
124
+ #
125
+ # @param fact [KBS::Blackboard::Fact, String] a fact or its uuid
126
+ def find_fact(fact)
127
+ uuid = uuid_of(fact)
128
+ data = @store.get_fact(uuid)
129
+ data && Fact.new(uuid, data[:type], data[:attributes], self)
130
+ end
131
+
132
+ # Merges `changes` into a fact's attributes and tells the observers
133
+ # it was removed and added again, so an engine matches the new
134
+ # values. The uuid is kept.
135
+ #
136
+ # @return [KBS::Blackboard::Fact, nil] the fact with its new
137
+ # attributes, or nil when it is not in the store
138
+ def modify_fact(fact, changes)
139
+ current = find_fact(fact)
140
+ return nil unless current
141
+
142
+ # A Fact passed in still has its attributes as they were given;
143
+ # the store's copy has been through JSON, which turns Symbol
144
+ # values into Strings.
145
+ attributes = (fact.is_a?(Fact) ? fact : current).attributes.merge(changes)
146
+ update_fact(current, attributes)
147
+
148
+ notify_observers(:remove, current)
149
+ modified = Fact.new(current.uuid, current.type, attributes, self)
150
+ notify_observers(:add, modified)
151
+ modified
152
+ end
153
+
97
154
  def get_facts(type = nil, pattern = {})
98
155
  fact_data = @store.get_facts(type, pattern)
99
156
 
100
- fact_data.map do |data|
101
- Fact.new(data[:uuid], data[:type], data[:attributes], self)
102
- end
157
+ fact_data.map { |data| fact_from(data) }
103
158
  end
104
159
 
105
160
  # Alias for compatibility with WorkingMemory interface
@@ -110,9 +165,7 @@ module KBS
110
165
  def query_facts(sql_conditions = nil, params = [])
111
166
  fact_data = @store.query_facts(sql_conditions, params)
112
167
 
113
- fact_data.map do |data|
114
- Fact.new(data[:uuid], data[:type], data[:attributes], self)
115
- end
168
+ fact_data.map { |data| fact_from(data) }
116
169
  end
117
170
 
118
171
  # Message Queue delegation
@@ -162,8 +215,31 @@ module KBS
162
215
  @store.clear_session(@session_id)
163
216
  end
164
217
 
165
- def transaction(&block)
166
- @store.transaction(&block)
218
+ # Runs the block in a store transaction. When the block raises, the
219
+ # facts it added that the store rolled back are removed from the
220
+ # observers (an engine) as well. A store that cannot roll back, such
221
+ # as Redis, keeps them, and so do the observers. Facts the block
222
+ # removed or modified are not restored in the observers.
223
+ def transaction(&)
224
+ return @store.transaction(&) if @added_in_transaction
225
+
226
+ @added_in_transaction = {}
227
+ begin
228
+ @store.transaction(&)
229
+ rescue StandardError
230
+ withdraw_rolled_back(@added_in_transaction.values)
231
+ raise
232
+ ensure
233
+ @added_in_transaction = nil
234
+ end
235
+ end
236
+
237
+ # Tells the observers each fact the store no longer holds was
238
+ # removed, newest first.
239
+ def withdraw_rolled_back(facts)
240
+ facts.reverse_each do |fact|
241
+ notify_observers(:remove, fact) unless @store.get_fact(fact.uuid)
242
+ end
167
243
  end
168
244
 
169
245
  # Statistics
@@ -185,7 +261,7 @@ module KBS
185
261
  end
186
262
 
187
263
  # For backward compatibility with ReteEngine
188
- alias_method :db, :store
264
+ alias db store
189
265
  end
190
266
  end
191
267
  end
@@ -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