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
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a911e3e7948e5e31bf7cd4f8a4ddb0c8e28964dc29d727391588119626c79160
4
- data.tar.gz: 678fd624d18377b944f8a747ed14105f0ee4786b49919d9492952ec91d3b9914
3
+ metadata.gz: 481d313c3b2209c082586165c521c611ef365a76c00aadbd00c29fa5713380d8
4
+ data.tar.gz: 818ee36d1b51568683a3953905417a4e098d1cebfd69c8a0f97b764557c31efe
5
5
  SHA512:
6
- metadata.gz: 2bf7222f147a9279c25b66a182b0e9ca9f198207a1b8e1ac96b477d2e6ebc4c45f8552501f0e6d62d516c3800f4e8824674fd1990c2865e54efa9d1cc40543c1
7
- data.tar.gz: c26c98beba1576d766b8017b92eb31943c9a5640d0cc7a2ac16145dcbc596a858109892419844922bb4d36d4e09221c84ed220e2756e299636813d2a2c1d3690
6
+ metadata.gz: '0386b6fedbc7c781e5ac99b805899b655091bc3b043bde464fb6717451f015879a2047b1807f7d5bb13bb88b7400fd8040ebc844a7e787305fa808f83daad58a'
7
+ data.tar.gz: b88d4baba525d8aec2ccd086de8817ef612c32a243b08a71a95b920fcd1bc900d1cdf39edb1572818d96c5b48a4d9362d28a892cfd31ea23e0deb21f56578b29
data/CHANGELOG.md CHANGED
@@ -1,12 +1,98 @@
1
1
  ## [Unreleased]
2
2
 
3
+ ## [0.4.0] - Unreleased
4
+
5
+ Faster matching and rule firing. What matches and the order rules fire in are unchanged for every strategy.
6
+
7
+ ### Breaking changes
8
+ - The facts an action receives (`Token#facts`) are frozen; copy them with `dup` before changing them.
9
+ - `Token#children` for a token with a single child returns a frozen one-element Set; change children through `add_child` / `remove_child` as before.
10
+ - `Activation#sort_key` is computed when called, from the new `Activation#strategy` the agenda sets; `Activation#sort_key=` is gone.
11
+ - `MemoryIndex.fact_key` and `MemoryIndex.token_key` return the value itself for a single field, and `MemoryIndex#lookup` may return an Array.
12
+
13
+ ### Changed
14
+ - **Agenda grouped by salience, as in CLIPS.** Activations are filed by salience and, under `:definition`, by rule; within a group `:depth` takes the newest first and `:breadth` / `:definition` the oldest first. Adding and popping no longer compare sort keys, which took about 40% of CPU in an assert-and-`run` profile. Firing 3n activations from three rules runs about 3 to 3.7 times faster (see `docs/advanced/performance.md`).
15
+ - **Fewer allocations per fact and per match.** A join index keys a single field by its value instead of an Array, and a bucket holds a lone fact or token without a `Set`. Each alpha memory prepares its pattern's tests once and skips the `?variables`. `Fact#matches?` no longer builds a pair per pattern entry, joins hand on their candidates without copying them, and the alpha network builds a candidate list only when more than one applies. A token with one child keeps it without a `Set`, and the Sets that hold tokens compare by identity. Joins, negation and retraction run about 15% to 45% faster at n=2000 (25% to 70% with YJIT).
16
+
17
+ ### Added
18
+ - `benchmarks/rete_scaling.rb` measures firing (`run`) under the `:definition` and `:depth` strategies.
19
+ - Fasterer is in the development bundle, so the `asgard quality` Fasterer gate runs instead of being skipped; `.fasterer.yml` records the one speedup turned off.
20
+ - README and the performance guide recommend running with YJIT (`ruby --yjit` or `RUBY_YJIT_ENABLE=1`), which is roughly 1.5 to 2.5 times faster on these benchmarks.
21
+
22
+ ## [0.3.0] - 2026-11-20
23
+
24
+ The engine now works like CLIPS: an agenda with conflict resolution, truth maintenance, `exists`, `modify`, and joins on shared `?variables`. Matching and retraction use indexes instead of scans.
25
+
26
+ ### Breaking changes
27
+ - Requires Ruby 4.0 or later (was 3.2).
28
+ - A `?variable` used in more than one condition now joins them: the facts must share the value. It used to match every combination. A `without` condition now blocks only on facts that agree with the variables bound before it.
29
+ - `run` fires until no matches remain, so a fact asserted by one action can fire any rule in the same `run`, in priority order. `run` returns the number of rules fired. Rules that keep re-matching need `run(limit)` or `halt`.
30
+ - `priority` now sets firing order on both engines; equal priorities keep definition order (#35).
31
+ - The DSL keyword `exists` now means "at least one such fact" and matches once; it used to be an alias for `on`.
32
+ - `WorkingMemory#facts`, `AlphaMemory#items`, `BetaMemory#tokens` and `ProductionNode#tokens` return copies; change the memories through their methods (`add_item`, `remove_token`, `clear`, …). `Token#children` is a frozen Set changed through `add_child` / `remove_child`.
33
+ - `RedisStore#query_facts` and `HybridStore#query_facts` raise `NotImplementedError` instead of returning every fact (#16).
34
+ - Shared nodes mean shared tokens, so whether a rule fired is now `ProductionNode#fired?(token)`; `Token#fired?` no longer prevents a second firing. `Activation#to_s` separates facts with `; ` and shows `*` for a `without` or `exists` condition.
35
+ - The gem ships only `lib/`, `README.md`, `CHANGELOG.md` and `LICENSE.txt` (#31). The Rakefile is gone; development tasks run through [asgard](https://github.com/MadBomber/asgard) (`.loki`).
36
+
37
+ ### Added
38
+ - **Agenda** (`engine.agenda`) holding pending matches, with conflict resolution `strategy:` `:definition` (default), `:depth` or `:breadth`; `run(limit)` and `halt`.
39
+ - **Truth maintenance**: conditions in a `logical do … end` block support the facts the action asserts, which are retracted when the support goes away. `logically_supported?`, `dependencies`, `dependents`.
40
+ - **`modify(fact, changes)`** on both engines and `KnowledgeBase`: updates a fact and re-matches it, keeping its identity (and uuid / `UPDATE` audit entry on the blackboard).
41
+ - **`fact_duplication: false`**: `add_fact` returns the existing equal fact instead of adding another; `duplicate_of` finds it.
42
+ - **`exists` conditions** (`KBS::ExistsNode`).
43
+ - **`KBS::MatchInProgressError`** when a pattern predicate changes working memory during a match.
44
+ - Bare `fact`, `assert`, `retract`, `modify`, `query` and `halt` work inside a DSL `perform` block; condition keywords after the rule is built raise `KBS::RuleBuiltError`.
45
+ - Block-form conditions accept bare names and comparisons: `on(:t) { location loc; value > 80 }`.
46
+ - `KnowledgeBase#query` accepts condition helpers such as `greater_than(80)`.
47
+ - `Engine#facts`, `Engine#close`, `KnowledgeBase#close`, `KBS.knowledge_base(engine:)` (#10, #64).
48
+ - `Fact#to_s` and `Rule#to_s` print DSL source (#3).
49
+ - **Introspection, as in CLIPS**: `watch` / `unwatch` (`:facts`, `:activations`, `:rules`) with `trace_output=`; `matches(rule_name)` shows the facts and partial matches per condition; `join_activity`, `reset_join_activity`, `network_stats` and `beta_nodes` measure the network. Also on `KnowledgeBase`.
50
+ - Benchmarks: `benchmarks/rete_scaling.rb` and `benchmarks/regex_baseline.rb` (#4).
51
+
52
+ ### Performance
53
+ With 2,000 facts or rules:
54
+ - Asserting finds alpha memories by type and constant: 1 s → 6 ms.
55
+ - Rules that start with the same conditions share those join, negation and exists nodes and their partial matches: 50 such rules over 2000 orders and payments, 517 ms → 37 ms.
56
+ - Shared-variable joins use hash indexes: 970 ms → 11 ms.
57
+ - Retracting follows recorded links instead of searching: 470 ms → 4 ms; removing negation blockers: 407 ms → 8 ms. Asserting costs about 20% more for the bookkeeping.
58
+
59
+ ### Fixed
60
+ - **Matching**
61
+ - Rules fire once per match whatever order facts arrive in (#41).
62
+ - Adding a rule late no longer re-fires earlier rules (#34).
63
+ - A rule that starts with `without` fires when nothing blocks it (#11).
64
+ - Bindings are correct after a leading `without`.
65
+ - Helpers and variables work on an attribute named `type` (#65).
66
+ - Helpers fail to match, instead of raising, on values of the wrong type (#67).
67
+ - **DSL**
68
+ - Condition helpers work in the block form of `on` (#40).
69
+ - `priority:` keyword on `rule` / `defrule` (#29).
70
+ - Zero-argument lambda actions (#14).
71
+ - `print_rules` shows DSL conditions (#58).
72
+ - **Rule source and decompiler**: literals, `!=`, `&&` / `||`, ternaries and Ruby 4.1 strings print correctly; undecompilable values no longer raise (#33, #36, #43, #50, #52).
73
+ - **Blackboard**
74
+ - `remove_fact` retracts from the network and returns the fact (#42).
75
+ - A rolled-back transaction withdraws the facts it added.
76
+ - `clear_session` works with a store passed in (#51).
77
+ - `fact_duplication: false` covers facts already stored.
78
+ - Symbol rule names and message topics work on SQLite.
79
+ - `register_knowledge_source` without a description works on Redis/Hybrid stores.
80
+ - `HybridStore#stats[:audit_records]` counts audit rows.
81
+ - The `Store` base class defines `session_id` and `register_knowledge_source`.
82
+ - `require 'kbs/blackboard'` works without the redis gem.
83
+ - **Messages and audit**
84
+ - String message content round-trips (#63).
85
+ - SQLite timestamps are read as UTC (#62).
86
+ - Two consumers can no longer receive the same message (#60).
87
+ - **Docs and examples**: every doc and snippet was checked against the code and corrected; the README and example DSL rules were fixed (#59, #66).
88
+
3
89
  ## [0.2.1] - 2026-02-26
4
90
 
5
91
  ### Added
6
92
  - **Rule Source Introspection**: New `rule_source` and `print_rule_source` methods on `KnowledgeBase` to retrieve and display the DSL source code for any rule by name
7
93
  - **Rule Decompiler**: `KBS::Decompiler` can reconstruct source for dynamically-created rules from Proc and Lambda objects
8
94
  - **Working Memory Reset**: `KnowledgeBase#reset` now clears working memory while preserving the compiled rule network, enabling reuse with different initial facts
9
- - **Rule Source Introspection Demo**: New `examples/rule_source_introspection_demo.rb` showcasing both file-based and dynamic rule source retrieval
95
+ - **Rule Source Introspection Demo**: New `examples/rule_source_demo.rb` showcasing both file-based and dynamic rule source retrieval
10
96
 
11
97
  ### Changed
12
98
  - **README rewritten to use DSL API**: Removed references to `KBS::ReteEngine` and `KBS::Rule`; all examples now use the DSL-based `KnowledgeBase` API
data/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  A comprehensive Ruby implementation of a Knowledge-Based System featuring the RETE algorithm, Blackboard architecture, and AI integration for building intelligent rule-based applications.
6
6
 
7
- [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2.0-red.svg)](https://www.ruby-lang.org/)
7
+ [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%204.0-red.svg)](https://www.ruby-lang.org/)
8
8
  [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
9
9
 
10
10
  See the [full documentation website](https://madbomber.github.io/kbs/).
@@ -16,13 +16,18 @@ See the [full documentation website](https://madbomber.github.io/kbs/).
16
16
  - **Incremental Updates**: Efficient fact addition/removal without full network recomputation
17
17
  - **Negation Support**: Built-in handling of NOT conditions and absence patterns
18
18
  - **Memory Optimization**: Nodes automatically unlink when empty to reduce computation
19
- - **Pattern Sharing**: Common sub-patterns shared between rules for maximum efficiency
19
+ - **Pattern Sharing**: Rules with the same pattern share one alpha memory
20
+ - **Indexed Matching**: Alpha memories found by fact type and constant, joins on shared `?variables` hash-indexed, and retraction without scanning
21
+ - **Agenda**: Runs to quiescence, ordered by priority then a conflict resolution strategy (`:definition`, `:depth`, `:breadth`); `run(limit)` and `halt`
22
+ - **Truth Maintenance**: Facts asserted under `logical` conditions are retracted when those conditions stop matching
23
+ - **Fact Lifecycle**: `modify` re-matches a changed fact; `fact_duplication: false` rejects duplicate facts
20
24
 
21
25
  ### Declarative DSL
22
26
  - **Readable Syntax**: Write rules in natural, expressive Ruby syntax
23
- - **Condition Helpers**: `greater_than`, `less_than`, `range`, `one_of`, `matches` for intuitive pattern matching
27
+ - **Condition Helpers**: `greater_than`, `less_than`, `range`, `one_of`, `satisfies` and more (see [DSL Helpers](#dsl-helpers))
24
28
  - **Rule Metadata**: Descriptions, priorities, and documentation built-in
25
29
  - **Negative Patterns**: `without` keyword for absence testing
30
+ - **Existence Tests**: `exists` matches once when at least one fact fits
26
31
 
27
32
  ### Blackboard Architecture
28
33
  - **Multi-Agent Coordination**: Knowledge sources collaborate via shared blackboard
@@ -38,12 +43,12 @@ See the [full documentation website](https://madbomber.github.io/kbs/).
38
43
  - **Query Interface**: Powerful fact retrieval with pattern matching and SQL queries
39
44
 
40
45
  ### Concurrent Execution
41
- - **Auto-Inference Mode**: Background thread continuously runs inference as facts change
42
- - **Thread-Safe**: Concurrent fact assertion and rule firing
46
+ - **Auto-Inference Patterns**: `examples/concurrent_inference_demo.rb` subclasses `KBS::Engine` to run inference reactively or in a background thread
47
+ - **Your Own Locking**: The engine has no locks of its own; those examples guard it with a `Mutex`
43
48
  - **Real-Time Processing**: Perfect for monitoring systems and event-driven architectures
44
49
 
45
50
  ### AI Integration
46
- - **LLM Integration**: Native support for Ollama, OpenAI via RubyLLM gem
51
+ - **LLM Integration**: Call Ollama, OpenAI and others from rule actions with the RubyLLM gem (not a kbs dependency; install it yourself)
47
52
  - **Hybrid Reasoning**: Combine symbolic rules with neural AI for enhanced decision-making
48
53
  - **Sentiment Analysis**: AI-powered news and text analysis
49
54
  - **Strategy Generation**: LLMs create trading strategies based on market conditions
@@ -103,8 +108,7 @@ kb = KBS.knowledge_base do
103
108
  desc "Detect stock momentum breakouts"
104
109
  priority 10
105
110
 
106
- on :stock, volume: greater_than(1_000_000)
107
- on :stock, price_change_pct: greater_than(3)
111
+ on :stock, volume: greater_than(1_000_000), price_change_pct: greater_than(3)
108
112
  without :position, status: "open"
109
113
 
110
114
  perform do |facts, bindings|
@@ -196,8 +200,12 @@ puts "Received: #{message[:content]}" if message
196
200
  require 'kbs'
197
201
  require 'ruby_llm'
198
202
 
199
- # Requires Ollama with a model installed
200
- # export OLLAMA_MODEL=gpt-oss:latest
203
+ # Requires `gem install ruby_llm` and LM Studio's server (`lms server start`) with a model loaded
204
+ # LM Studio speaks the OpenAI API, so ruby_llm's :openai provider points at it
205
+ RubyLLM.configure do |config|
206
+ config.openai_api_base = ENV.fetch("LMS_API_BASE", "http://localhost:1234/v1")
207
+ config.openai_api_key = ENV.fetch("LMS_API_KEY", "lm-studio") # LM Studio ignores it; ruby_llm needs one set
208
+ end
201
209
 
202
210
  kb = KBS.knowledge_base do
203
211
  rule "ai_sentiment_analysis" do
@@ -206,7 +214,11 @@ kb = KBS.knowledge_base do
206
214
  perform do |facts|
207
215
  news = facts.first
208
216
  # AI-powered sentiment analysis
209
- client = RubyLLM::Chat.new(provider: :ollama, model: 'gpt-oss:latest')
217
+ client = RubyLLM::Chat.new(
218
+ provider: :openai,
219
+ model: ENV.fetch("LMS_MODEL", "openai/gpt-oss-20b"),
220
+ assume_model_exists: true # local model ids aren't in ruby_llm's registry
221
+ )
210
222
  response = client.ask("Analyze sentiment: #{news[:headline]}")
211
223
 
212
224
  puts "🤖 AI SENTIMENT ANALYSIS: #{news[:symbol]}"
@@ -232,15 +244,15 @@ end
232
244
 
233
245
  ## 📚 Examples
234
246
 
235
- The `examples/` directory contains 13 comprehensive examples demonstrating all features:
247
+ The `examples/` directory contains 13 comprehensive examples demonstrating all features. Each one except `iot_demo_using_dsl.rb` also has a DSL version (`*_dsl.rb`), and `rule_source_demo.rb` shows rule source introspection:
236
248
 
237
249
  ### Basic Examples
238
250
  - **car_diagnostic.rb** - Simple expert system for car diagnostics
239
251
  - **working_demo.rb** - Stock trading signal generator
252
+ - **trading_demo.rb** - Multiple trading strategies
240
253
 
241
254
  ### DSL Examples
242
255
  - **iot_demo_using_dsl.rb** - IoT sensor monitoring with declarative DSL
243
- - **trading_demo.rb** - Multiple trading strategies
244
256
 
245
257
  ### Advanced Trading
246
258
  - **advanced_example.rb** - Golden cross detection and technical analysis
@@ -320,6 +332,20 @@ Facts → Alpha Network → Beta Network → Production Nodes
320
332
 
321
333
  ## ⚡ Performance
322
334
 
335
+ ### Run with YJIT
336
+
337
+ Turn on YJIT, the JIT compiler built into CRuby. It makes KBS roughly 1.5 to 2.5 times faster with no code changes:
338
+
339
+ ```bash
340
+ ruby --yjit app.rb # or set RUBY_YJIT_ENABLE=1
341
+ ```
342
+
343
+ ```ruby
344
+ RubyVM::YJIT.enable # or from code, early in boot
345
+ ```
346
+
347
+ `benchmarks/rete_scaling.rb` measures the network with and without it; see [Performance Tuning](docs/advanced/performance.md#running-with-yjit).
348
+
323
349
  ### Benchmarks
324
350
  - **Rule Compilation**: ~1ms per rule for typical patterns
325
351
  - **Fact Addition**: ~0.1ms per fact (warm network)
@@ -336,46 +362,61 @@ Facts → Alpha Network → Beta Network → Production Nodes
336
362
  Run the comprehensive test suite:
337
363
 
338
364
  ```bash
339
- rake test
365
+ asgard test_check
366
+ ```
367
+
368
+ Without [asgard](https://github.com/MadBomber/asgard) installed, run the same command it does:
369
+
370
+ ```bash
371
+ bundle exec ruby -Ilib:test -e 'Dir["test/**/test_*.rb"].each { |f| require File.expand_path(f) }'
340
372
  ```
341
373
 
342
- Individual test files:
374
+ Run a single test file (`test/test_*.rb`):
343
375
 
344
376
  ```bash
345
- ruby test/kbs_test.rb
346
- ruby test/blackboard_test.rb
347
- ruby test/dsl_test.rb
377
+ bundle exec ruby test/test_rule.rb
348
378
  ```
349
379
 
350
- **Test Coverage**: 100% with 199 tests, 447 assertions, 0 failures
380
+ SimpleCov measures coverage on every run and fails the run below the minimum set in `test/test_helper.rb` (currently 35% line coverage).
381
+
382
+ The Redis store tests are skipped unless `KBS_TEST_REDIS_URL` names a disposable Redis database. See [test/README.md](test/README.md) before setting it, because those tests flush the database.
351
383
 
352
384
  ## 📖 Documentation
353
385
 
354
386
  ### Core Classes
355
387
 
356
- - **KBS::ReteEngine** - Main inference engine
388
+ - **KBS::Engine** - Main inference engine
357
389
  - **KBS::Rule** - Rule definition
358
390
  - **KBS::Condition** - Pattern matching conditions
359
391
  - **KBS::Fact** - Working memory facts
360
392
  - **KBS::Blackboard::Engine** - Blackboard coordination
361
- - **KBS::Blackboard::Persistence::SQLiteStore** - SQLite backend
393
+ - **KBS::Blackboard::Persistence::SqliteStore** - SQLite backend
362
394
  - **KBS::Blackboard::Persistence::RedisStore** - Redis backend
363
395
  - **KBS::Blackboard::Persistence::HybridStore** - Hybrid storage
364
396
 
365
397
  ### DSL Helpers
366
398
 
399
+ Use these as attribute values in the hash form of `on`, for example `on :reading, value: greater_than(100)`, and in `kb.query` patterns. The block form of `on` has its own operators; see [Block-Style Patterns](docs/guides/dsl.md#block-style-patterns).
400
+
367
401
  - `greater_than(n)` - Match values > n
368
402
  - `less_than(n)` - Match values < n
369
- - `range(min, max)` - Match values between min and max
403
+ - `equals(value)` - Match values equal to value
404
+ - `not_equal(value)` - Match values not equal to value
405
+ - `range(min, max)`, `between(min, max)` or `range(a_range)` - Match values from min to max inclusive, or values in the Range
370
406
  - `one_of(*values)` - Match any of the values
371
- - `matches(regex)` - Match regex pattern
407
+ - `any(*values)` - Same as `one_of`; with no arguments, match anything
408
+ - `satisfies { |v| ... }` - Match values for which the block returns true
409
+
410
+ For a regex in the hash form, use `satisfies { |v| regex.match?(v.to_s) }`. In that position `matches` is another name for `on`, not a helper.
411
+
412
+ See the [DSL guide](docs/guides/dsl.md#pattern-helpers) for examples.
372
413
 
373
414
  ## 🔧 Requirements
374
415
 
375
- - Ruby >= 3.2.0
416
+ - Ruby >= 4.0
376
417
  - SQLite3 (bundled with most systems)
377
418
  - Redis (optional, for Redis storage)
378
- - Ollama (optional, for AI integration)
419
+ - RubyLLM plus Ollama or LM Studio (optional, for AI integration)
379
420
 
380
421
  ## 🤝 Contributing
381
422
 
data/lib/kbs/agenda.rb ADDED
@@ -0,0 +1,301 @@
1
+ # frozen_string_literal: true
2
+
3
+ module KBS
4
+ # A rule matched by a token, waiting on the agenda to fire.
5
+ class Activation
6
+ attr_reader :node, :token, :salience, :rule_order, :timetag
7
+
8
+ # The conflict resolution strategy of the agenda the activation is on,
9
+ # which #sort_key follows. Set by the agenda; :definition until then.
10
+ attr_accessor :strategy
11
+
12
+ def initialize(node, token, rule_order:, timetag:)
13
+ @node = node
14
+ @token = token
15
+ @salience = node.rule.priority
16
+ @rule_order = rule_order
17
+ @timetag = timetag
18
+ @cancelled = false
19
+ @strategy = :definition
20
+ end
21
+
22
+ # Where the activation sorts on its agenda, lowest first. Built when
23
+ # asked for: the agenda orders activations without it.
24
+ def sort_key
25
+ key_for(@strategy)
26
+ end
27
+
28
+ def rule
29
+ @node.rule
30
+ end
31
+
32
+ def cancel!
33
+ @cancelled = true
34
+ end
35
+
36
+ def cancelled?
37
+ @cancelled
38
+ end
39
+
40
+ # The rule's name and one entry per condition, separated by "; ": the
41
+ # matched fact, or * for a negated or exists condition.
42
+ def description
43
+ "#{rule.name}: #{@token.slots.map { |fact| fact ? fact.to_s : '*' }.join('; ')}"
44
+ end
45
+
46
+ # Cancels the activation unless it already is.
47
+ #
48
+ # @return [Boolean] whether this call cancelled it
49
+ def withdraw
50
+ return false if @cancelled
51
+
52
+ @cancelled = true
53
+ end
54
+
55
+ # Where the activation sorts on an agenda that uses `strategy`:
56
+ # lowest first.
57
+ def key_for(strategy)
58
+ priority = -@salience
59
+ case strategy
60
+ when :depth then [priority, -@timetag, 0]
61
+ when :breadth then [priority, @timetag, 0]
62
+ else [priority, @rule_order, @timetag]
63
+ end
64
+ end
65
+
66
+ def to_s
67
+ "#{@salience} #{description}"
68
+ end
69
+ end
70
+
71
+ # The conflict set: every activation that has not fired yet, ordered
72
+ # by rule priority (salience) and then by the conflict resolution
73
+ # strategy.
74
+ #
75
+ # :definition rules in the order they were added, each rule's
76
+ # activations oldest first (the default)
77
+ # :depth newest activation first
78
+ # :breadth oldest activation first
79
+ #
80
+ # Activations are grouped the way CLIPS groups them: by salience, and
81
+ # under :definition also by rule. Groups are kept in firing order, and
82
+ # within a group the order follows from where an activation is put:
83
+ # :depth takes the newest first (a stack), the others the oldest first
84
+ # (a queue). Nothing is compared to add or pop an activation; only an
85
+ # add that opens a new group finds its place, by binary search on a
86
+ # number. Removing an activation marks it cancelled, and it is dropped
87
+ # when it reaches the front of its group.
88
+ class Agenda
89
+ # Activations taken oldest first.
90
+ class Fifo
91
+ def initialize
92
+ @items = []
93
+ end
94
+
95
+ def <<(activation)
96
+ @items << activation
97
+ self
98
+ end
99
+
100
+ # self when an activation is pending, after dropping the cancelled
101
+ # ones in front of it; nil otherwise.
102
+ def front
103
+ @items.shift while @items.first&.cancelled?
104
+ self unless @items.empty?
105
+ end
106
+
107
+ # The activation to take next. Call #front first.
108
+ def next
109
+ @items.first
110
+ end
111
+
112
+ def take
113
+ @items.shift
114
+ end
115
+
116
+ def each_activation(&)
117
+ @items.each(&)
118
+ end
119
+
120
+ private
121
+
122
+ attr_reader :items
123
+ end
124
+
125
+ # Activations taken newest first.
126
+ class Lifo < Fifo
127
+ def front
128
+ items.pop while items.last&.cancelled?
129
+ self unless items.empty?
130
+ end
131
+
132
+ def next
133
+ items.last
134
+ end
135
+
136
+ def take
137
+ items.pop
138
+ end
139
+ end
140
+
141
+ # Members filed under numeric keys and kept in key order: the salience
142
+ # levels of an agenda, or the rules within one level. A member is
143
+ # made by the block when its key is first used, and is a Fifo, a Lifo
144
+ # or another Groups.
145
+ class Groups
146
+ def initialize(&make)
147
+ @make = make
148
+ @members = {}
149
+ @keys = []
150
+ end
151
+
152
+ # The member for `key`, made and filed in order if it is new.
153
+ def fetch(key)
154
+ @members[key] || file(key)
155
+ end
156
+
157
+ # The first queue with an activation pending, found through the
158
+ # members in key order. Members left with nothing pending are
159
+ # dropped on the way. nil when nothing is pending.
160
+ def front
161
+ until @keys.empty?
162
+ queue = @members[@keys.first].front
163
+ return queue if queue
164
+
165
+ @members.delete(@keys.shift)
166
+ end
167
+ nil
168
+ end
169
+
170
+ def each_activation(&)
171
+ @members.each_value { |member| member.each_activation(&) }
172
+ end
173
+
174
+ private
175
+
176
+ # Activations mostly arrive for keys after the existing ones, so
177
+ # the last key is checked before searching.
178
+ def file(key)
179
+ last = @keys.last
180
+ position = last.nil? || last < key ? @keys.size : @keys.bsearch_index { |other| other >= key }
181
+ @keys.insert(position, key)
182
+ @members[key] = @make.call
183
+ end
184
+ end
185
+
186
+ STRATEGIES = %i[definition depth breadth].freeze
187
+
188
+ # For each strategy: the queue its groups use, and the key that files
189
+ # an activation into a group within its salience level (the position
190
+ # of its rule under :definition, one key for all otherwise).
191
+ LAYOUTS = {
192
+ definition: [Fifo, :rule_order.to_proc],
193
+ depth: [Lifo, proc { 0 }],
194
+ breadth: [Fifo, proc { 0 }]
195
+ }.freeze
196
+
197
+ attr_reader :strategy, :size
198
+
199
+ # An object told about each activation that is added, and each one
200
+ # removed before it fired, through activation_added(activation) and
201
+ # activation_removed(activation).
202
+ attr_accessor :listener
203
+
204
+ def initialize(strategy: :definition)
205
+ @listener = nil
206
+ validate_strategy(strategy)
207
+ @strategy = strategy
208
+ @size = 0
209
+ @timetag = 0
210
+ @levels = self.class.levels_for(strategy)
211
+ @rule_key = LAYOUTS.fetch(strategy).last
212
+ end
213
+
214
+ # Regroups the pending activations, oldest first, so each new group
215
+ # is in timetag order whatever the old strategy was.
216
+ def strategy=(strategy)
217
+ validate_strategy(strategy)
218
+ pending = to_a.sort_by(&:timetag)
219
+ @strategy = strategy
220
+ @levels = self.class.levels_for(strategy)
221
+ @rule_key = LAYOUTS.fetch(strategy).last
222
+ pending.each { |activation| push(activation) }
223
+ end
224
+
225
+ # @return [Activation] the new activation, to pass to #remove later
226
+ def add(node, token, rule_order: 0)
227
+ activation = Activation.new(node, token, rule_order: rule_order, timetag: @timetag += 1)
228
+ push(activation)
229
+ @size += 1
230
+ @listener&.activation_added(activation)
231
+ activation
232
+ end
233
+
234
+ def remove(activation)
235
+ return unless activation&.withdraw
236
+
237
+ @size -= 1
238
+ @listener&.activation_removed(activation)
239
+ end
240
+
241
+ # Removes and returns the next activation to fire, or nil when empty.
242
+ def pop
243
+ activation = @levels.front&.take
244
+ return nil unless activation
245
+
246
+ activation.cancel!
247
+ @size -= 1
248
+ activation
249
+ end
250
+
251
+ def peek
252
+ @levels.front&.next
253
+ end
254
+
255
+ def empty?
256
+ @size.zero?
257
+ end
258
+
259
+ def clear
260
+ @levels.each_activation(&:cancel!)
261
+ @levels = self.class.levels_for(@strategy)
262
+ @size = 0
263
+ end
264
+
265
+ # Pending activations in firing order.
266
+ def to_a
267
+ @levels.enum_for(:each_activation).reject(&:cancelled?).sort_by(&:sort_key)
268
+ end
269
+
270
+ def sort_key_for(activation)
271
+ activation.key_for(@strategy)
272
+ end
273
+
274
+ # Empty salience levels for `strategy`. Each level holds one group per
275
+ # rule under :definition, and a single group otherwise.
276
+ def self.levels_for(strategy)
277
+ queue = LAYOUTS.fetch(strategy).first
278
+ Groups.new { Groups.new { queue.new } }
279
+ end
280
+
281
+ # The key of the salience level an activation is filed under: its
282
+ # salience negated, so that higher salience sorts first, and
283
+ # normalized, so that 1 and 1.0 share a level.
284
+ def self.level_key(activation)
285
+ -MemoryIndex.normalize(activation.salience)
286
+ end
287
+
288
+ private
289
+
290
+ def validate_strategy(strategy)
291
+ return if STRATEGIES.include?(strategy)
292
+
293
+ raise ArgumentError, "unknown strategy #{strategy.inspect}; use one of #{STRATEGIES.inspect}"
294
+ end
295
+
296
+ def push(activation)
297
+ activation.strategy = @strategy
298
+ @levels.fetch(self.class.level_key(activation)).fetch(@rule_key.call(activation)) << activation
299
+ end
300
+ end
301
+ end