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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +87 -1
- data/README.md +66 -25
- data/lib/kbs/agenda.rb +301 -0
- data/lib/kbs/alpha_memory.rb +80 -9
- data/lib/kbs/alpha_network.rb +95 -0
- data/lib/kbs/beta_memory.rb +54 -19
- data/lib/kbs/blackboard/audit_log.rb +26 -25
- data/lib/kbs/blackboard/engine.rb +49 -40
- data/lib/kbs/blackboard/fact.rb +17 -21
- data/lib/kbs/blackboard/memory.rb +116 -40
- data/lib/kbs/blackboard/message_queue.rb +39 -28
- data/lib/kbs/blackboard/persistence/hybrid_store.rb +20 -9
- data/lib/kbs/blackboard/persistence/redis_store.rb +59 -51
- data/lib/kbs/blackboard/persistence/sqlite_store.rb +29 -32
- data/lib/kbs/blackboard/persistence/store.rb +11 -1
- data/lib/kbs/blackboard/redis_message_queue.rb +16 -7
- data/lib/kbs/condition.rb +42 -2
- data/lib/kbs/decompiler.rb +300 -124
- data/lib/kbs/dsl/condition_helpers.rb +8 -6
- data/lib/kbs/dsl/knowledge_base.rb +73 -93
- data/lib/kbs/dsl/pattern_evaluator.rb +38 -15
- data/lib/kbs/dsl/rule_builder.rb +118 -40
- data/lib/kbs/dsl/variable.rb +51 -6
- data/lib/kbs/dsl.rb +10 -3
- data/lib/kbs/engine.rb +395 -77
- data/lib/kbs/errors.rb +38 -0
- data/lib/kbs/exists_node.rb +12 -0
- data/lib/kbs/fact.rb +5 -19
- data/lib/kbs/fact_registry.rb +51 -0
- data/lib/kbs/introspection.rb +93 -0
- data/lib/kbs/join_indexing.rb +106 -0
- data/lib/kbs/join_node.rb +93 -57
- data/lib/kbs/join_test_builder.rb +80 -0
- data/lib/kbs/join_tests.rb +66 -0
- data/lib/kbs/memory_index.rb +104 -0
- data/lib/kbs/negation_node.rb +6 -82
- data/lib/kbs/network_node.rb +31 -0
- data/lib/kbs/pattern_matching.rb +52 -0
- data/lib/kbs/production_node.rb +50 -6
- data/lib/kbs/quantifier_node.rb +140 -0
- data/lib/kbs/rule.rb +26 -13
- data/lib/kbs/rule_source.rb +74 -0
- data/lib/kbs/rule_step.rb +27 -0
- data/lib/kbs/token.rb +76 -10
- data/lib/kbs/tracer.rb +80 -0
- data/lib/kbs/truth_maintenance.rb +82 -0
- data/lib/kbs/version.rb +1 -1
- data/lib/kbs/working_memory.rb +25 -3
- data/lib/kbs.rb +17 -4
- metadata +22 -129
- data/.envrc +0 -3
- data/.github/workflows/deploy-github-pages.yml +0 -52
- data/COMMITS.md +0 -196
- data/Rakefile +0 -8
- data/docs/advanced/custom-persistence.md +0 -775
- data/docs/advanced/debugging.md +0 -726
- data/docs/advanced/index.md +0 -8
- data/docs/advanced/performance.md +0 -865
- data/docs/advanced/testing.md +0 -827
- data/docs/api/blackboard.md +0 -1157
- data/docs/api/engine.md +0 -1047
- data/docs/api/facts.md +0 -1212
- data/docs/api/index.md +0 -12
- data/docs/api/rules.md +0 -1104
- data/docs/architecture/blackboard.md +0 -544
- data/docs/architecture/index.md +0 -277
- data/docs/architecture/network-structure.md +0 -343
- data/docs/architecture/rete-algorithm.md +0 -737
- data/docs/assets/css/custom.css +0 -83
- data/docs/assets/images/blackboard-architecture.svg +0 -136
- data/docs/assets/images/compiled-network.svg +0 -101
- data/docs/assets/images/fact-assertion-flow.svg +0 -117
- data/docs/assets/images/fact-rule-relationship.svg +0 -65
- data/docs/assets/images/fact-structure.svg +0 -42
- data/docs/assets/images/inference-cycle.svg +0 -47
- data/docs/assets/images/kb-components.svg +0 -43
- data/docs/assets/images/kbs.jpg +0 -0
- data/docs/assets/images/pattern-matching-trace.svg +0 -136
- data/docs/assets/images/rete-network-layers.svg +0 -96
- data/docs/assets/images/rule-structure.svg +0 -44
- data/docs/assets/images/system-layers.svg +0 -69
- data/docs/assets/images/trading-signal-network.svg +0 -139
- data/docs/assets/js/mathjax.js +0 -17
- data/docs/examples/index.md +0 -223
- data/docs/guides/blackboard-memory.md +0 -589
- data/docs/guides/dsl.md +0 -1321
- data/docs/guides/facts.md +0 -652
- data/docs/guides/getting-started.md +0 -385
- data/docs/guides/index.md +0 -23
- data/docs/guides/negation.md +0 -529
- data/docs/guides/pattern-matching.md +0 -561
- data/docs/guides/persistence.md +0 -451
- data/docs/guides/variable-binding.md +0 -491
- data/docs/guides/writing-rules.md +0 -914
- data/docs/index.md +0 -155
- data/docs/installation.md +0 -156
- data/docs/quick-start.md +0 -221
- data/docs/what-is-a-fact.md +0 -694
- data/docs/what-is-a-knowledge-base.md +0 -350
- data/docs/what-is-a-rule.md +0 -833
- data/examples/.gitignore +0 -1
- data/examples/README.md +0 -531
- data/examples/advanced_example.rb +0 -270
- data/examples/advanced_example_dsl.rb +0 -224
- data/examples/ai_enhanced_kbs.rb +0 -523
- data/examples/ai_enhanced_kbs_dsl.rb +0 -538
- data/examples/blackboard_demo.rb +0 -50
- data/examples/blackboard_demo_dsl.rb +0 -50
- data/examples/car_diagnostic.rb +0 -64
- data/examples/car_diagnostic_dsl.rb +0 -54
- data/examples/concurrent_inference_demo.rb +0 -362
- data/examples/concurrent_inference_demo_dsl.rb +0 -362
- data/examples/csv_trading_system.rb +0 -559
- data/examples/csv_trading_system_dsl.rb +0 -525
- data/examples/iot_demo_using_dsl.rb +0 -83
- data/examples/portfolio_rebalancing_system.rb +0 -651
- data/examples/portfolio_rebalancing_system_dsl.rb +0 -613
- data/examples/redis_trading_demo.rb +0 -177
- data/examples/redis_trading_demo_dsl.rb +0 -177
- data/examples/rule_source_demo.rb +0 -123
- data/examples/run_all.rb +0 -50
- data/examples/run_all_dsl.rb +0 -49
- data/examples/sample_stock_data.csv +0 -46
- data/examples/stock_trading_advanced.rb +0 -469
- data/examples/stock_trading_advanced_dsl.rb +0 -404
- data/examples/temp_dsl.txt +0 -9392
- data/examples/timestamped_trading.rb +0 -286
- data/examples/timestamped_trading_dsl.rb +0 -258
- data/examples/trading_demo.rb +0 -334
- data/examples/trading_demo_dsl.rb +0 -322
- data/examples/working_demo.rb +0 -176
- data/examples/working_demo_dsl.rb +0 -160
- data/mkdocs.yml +0 -181
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 481d313c3b2209c082586165c521c611ef365a76c00aadbd00c29fa5713380d8
|
|
4
|
+
data.tar.gz: 818ee36d1b51568683a3953905417a4e098d1cebfd69c8a0f97b764557c31efe
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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/
|
|
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
|
-
[](https://www.ruby-lang.org/)
|
|
8
8
|
[](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**:
|
|
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`, `
|
|
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
|
|
42
|
-
- **
|
|
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**:
|
|
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
|
|
200
|
-
#
|
|
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(
|
|
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
|
-
|
|
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
|
-
|
|
374
|
+
Run a single test file (`test/test_*.rb`):
|
|
343
375
|
|
|
344
376
|
```bash
|
|
345
|
-
ruby test/
|
|
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
|
-
|
|
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::
|
|
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::
|
|
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
|
-
- `
|
|
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
|
-
- `
|
|
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 >=
|
|
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
|