kbs 0.0.1 → 0.1.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 (86) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/deploy-github-pages.yml +52 -0
  3. data/CHANGELOG.md +68 -2
  4. data/README.md +235 -334
  5. data/docs/DOCUMENTATION_STATUS.md +158 -0
  6. data/docs/advanced/custom-persistence.md +775 -0
  7. data/docs/advanced/debugging.md +726 -0
  8. data/docs/advanced/index.md +8 -0
  9. data/docs/advanced/performance.md +832 -0
  10. data/docs/advanced/testing.md +691 -0
  11. data/docs/api/blackboard.md +1157 -0
  12. data/docs/api/engine.md +978 -0
  13. data/docs/api/facts.md +1212 -0
  14. data/docs/api/index.md +12 -0
  15. data/docs/api/rules.md +1034 -0
  16. data/docs/architecture/blackboard.md +553 -0
  17. data/docs/architecture/index.md +277 -0
  18. data/docs/architecture/network-structure.md +343 -0
  19. data/docs/architecture/rete-algorithm.md +737 -0
  20. data/docs/assets/css/custom.css +83 -0
  21. data/docs/assets/images/blackboard-architecture.svg +136 -0
  22. data/docs/assets/images/compiled-network.svg +101 -0
  23. data/docs/assets/images/fact-assertion-flow.svg +117 -0
  24. data/docs/assets/images/kbs.jpg +0 -0
  25. data/docs/assets/images/pattern-matching-trace.svg +136 -0
  26. data/docs/assets/images/rete-network-layers.svg +96 -0
  27. data/docs/assets/images/system-layers.svg +69 -0
  28. data/docs/assets/images/trading-signal-network.svg +139 -0
  29. data/docs/assets/js/mathjax.js +17 -0
  30. data/docs/examples/expert-systems.md +1031 -0
  31. data/docs/examples/index.md +9 -0
  32. data/docs/examples/multi-agent.md +1335 -0
  33. data/docs/examples/stock-trading.md +488 -0
  34. data/docs/guides/blackboard-memory.md +558 -0
  35. data/docs/guides/dsl.md +1321 -0
  36. data/docs/guides/facts.md +652 -0
  37. data/docs/guides/getting-started.md +383 -0
  38. data/docs/guides/index.md +23 -0
  39. data/docs/guides/negation.md +529 -0
  40. data/docs/guides/pattern-matching.md +561 -0
  41. data/docs/guides/persistence.md +451 -0
  42. data/docs/guides/variable-binding.md +491 -0
  43. data/docs/guides/writing-rules.md +755 -0
  44. data/docs/index.md +157 -0
  45. data/docs/installation.md +156 -0
  46. data/docs/quick-start.md +228 -0
  47. data/examples/README.md +2 -2
  48. data/examples/advanced_example.rb +2 -2
  49. data/examples/advanced_example_dsl.rb +224 -0
  50. data/examples/ai_enhanced_kbs.rb +1 -1
  51. data/examples/ai_enhanced_kbs_dsl.rb +538 -0
  52. data/examples/blackboard_demo_dsl.rb +50 -0
  53. data/examples/car_diagnostic.rb +1 -1
  54. data/examples/car_diagnostic_dsl.rb +54 -0
  55. data/examples/concurrent_inference_demo.rb +5 -5
  56. data/examples/concurrent_inference_demo_dsl.rb +363 -0
  57. data/examples/csv_trading_system.rb +1 -1
  58. data/examples/csv_trading_system_dsl.rb +525 -0
  59. data/examples/knowledge_base.db +0 -0
  60. data/examples/portfolio_rebalancing_system.rb +2 -2
  61. data/examples/portfolio_rebalancing_system_dsl.rb +613 -0
  62. data/examples/redis_trading_demo_dsl.rb +177 -0
  63. data/examples/run_all.rb +50 -0
  64. data/examples/run_all_dsl.rb +49 -0
  65. data/examples/stock_trading_advanced.rb +1 -1
  66. data/examples/stock_trading_advanced_dsl.rb +404 -0
  67. data/examples/temp.txt +7693 -0
  68. data/examples/temp_dsl.txt +8447 -0
  69. data/examples/timestamped_trading.rb +1 -1
  70. data/examples/timestamped_trading_dsl.rb +258 -0
  71. data/examples/trading_demo.rb +1 -1
  72. data/examples/trading_demo_dsl.rb +322 -0
  73. data/examples/working_demo.rb +1 -1
  74. data/examples/working_demo_dsl.rb +160 -0
  75. data/lib/kbs/blackboard/engine.rb +3 -3
  76. data/lib/kbs/blackboard/fact.rb +1 -1
  77. data/lib/kbs/condition.rb +1 -1
  78. data/lib/kbs/dsl/knowledge_base.rb +1 -1
  79. data/lib/kbs/dsl/variable.rb +1 -1
  80. data/lib/kbs/{rete_engine.rb → engine.rb} +1 -1
  81. data/lib/kbs/fact.rb +1 -1
  82. data/lib/kbs/version.rb +1 -1
  83. data/lib/kbs.rb +2 -2
  84. data/mkdocs.yml +181 -0
  85. metadata +66 -6
  86. data/examples/stock_trading_system.rb.bak +0 -563
data/docs/DOCUMENTATION_STATUS.md ADDED
@@ -0,0 +1,158 @@
1
+ # KBS Documentation Status
2
+
3
+ This document tracks the comprehensive documentation effort for the KBS gem.
4
+
5
+ ## ✅ Completed Documents
6
+
7
+ ### Core Pages
8
+ - [x] `index.md` - Main landing page with features, quick example, use cases
9
+ - [x] `installation.md` - Installation guide with all backends
10
+ - [x] `quick-start.md` - 5-minute getting started guide
11
+
12
+ ### Architecture
13
+ - [x] `architecture/index.md` - Architecture overview with system layers
14
+ - [x] `architecture/rete-algorithm.md` - **COMPREHENSIVE** deep dive into RETE (650+ lines)
15
+ - [x] `architecture/blackboard.md` - **COMPREHENSIVE** blackboard pattern implementation
16
+
17
+ ### SVG Graphics Created
18
+ - [x] `assets/images/rete-network-layers.svg` - 3-layer RETE architecture
19
+ - [x] `assets/images/fact-assertion-flow.svg` - Step-by-step fact propagation
20
+ - [x] `assets/images/pattern-matching-trace.svg` - Complete negation example
21
+ - [x] `assets/images/blackboard-architecture.svg` - Multi-agent blackboard system
22
+
23
+ ### Supporting Files
24
+ - [x] `assets/css/custom.css` - Dark theme styling for SVGs and code
25
+ - [x] `assets/js/mathjax.js` - Mathematical notation support
26
+
27
+ ## 📋 Remaining Documents
28
+
29
+ ### Architecture
30
+ - [ ] `architecture/network-structure.md` - Network compilation details, node types, optimization
31
+
32
+ ### Guides (10 files)
33
+ - [ ] `guides/index.md` - Guides landing page
34
+ - [ ] `guides/getting-started.md` - Expanded tutorial
35
+ - [ ] `guides/writing-rules.md` - Rule authoring best practices
36
+ - [ ] `guides/dsl.md` - Complete DSL reference with all aliases
37
+ - [ ] `guides/facts.md` - Fact lifecycle, queries, updates
38
+ - [ ] `guides/pattern-matching.md` - Pattern syntax, predicates, operators
39
+ - [ ] `guides/variable-binding.md` - Variables, join tests, extraction
40
+ - [ ] `guides/negation.md` - Negation semantics, use cases, pitfalls
41
+ - [ ] `guides/blackboard-memory.md` - Persistence guide
42
+ - [ ] `guides/persistence.md` - Backend comparison, configuration
43
+
44
+ ### Examples (3 files)
45
+ - [ ] `examples/index.md` - Examples landing page
46
+ - [ ] `examples/stock-trading.md` - Trading system walkthrough
47
+ - [ ] `examples/expert-systems.md` - Diagnostic expert system
48
+ - [ ] `examples/multi-agent.md` - Collaborative agents
49
+
50
+ ### Advanced (4 files)
51
+ - [ ] `advanced/index.md` - Advanced topics landing page
52
+ - [ ] `advanced/performance.md` - Profiling, optimization, benchmarks
53
+ - [ ] `advanced/custom-persistence.md` - Building custom stores
54
+ - [ ] `advanced/debugging.md` - Network inspection, tracing
55
+ - [ ] `advanced/testing.md` - Testing strategies for rules
56
+
57
+ ### API Reference (5 files)
58
+ - [ ] `api/index.md` - API overview
59
+ - [ ] `api/rete-engine.md` - Engine class reference
60
+ - [ ] `api/facts.md` - Fact and Condition classes
61
+ - [ ] `api/rules.md` - Rule class reference
62
+ - [ ] `api/blackboard.md` - Blackboard::* classes
63
+
64
+ ## 📊 Documentation Metrics
65
+
66
+ - **Total Pages Planned**: 35
67
+ - **Pages Completed**: 9 (26%)
68
+ - **SVG Graphics Created**: 4
69
+ - **Total Lines Written**: ~4,500+
70
+ - **Estimated Remaining**: ~6,000 lines
71
+
72
+ ## 🎯 Documentation Priorities
73
+
74
+ ### High Priority (Core Learning Path)
75
+ 1. `guides/writing-rules.md` - Essential for users
76
+ 2. `guides/dsl.md` - Complete reference
77
+ 3. `examples/stock-trading.md` - Real-world application
78
+ 4. `architecture/network-structure.md` - Complete architecture coverage
79
+
80
+ ### Medium Priority (Advanced Users)
81
+ 5. `advanced/performance.md` - Production optimization
82
+ 6. `guides/pattern-matching.md` - Deep pattern knowledge
83
+ 7. `examples/multi-agent.md` - Advanced architecture
84
+ 8. `advanced/debugging.md` - Troubleshooting
85
+
86
+ ### Lower Priority (Reference)
87
+ 9. API documentation files - Generated from code
88
+ 10. Remaining guides - Nice-to-have expansions
89
+
90
+ ## 🎨 SVG Graphics Roadmap
91
+
92
+ ### Completed
93
+ - ✅ RETE network layers diagram
94
+ - ✅ Fact assertion flow diagram
95
+ - ✅ Pattern matching trace (negation)
96
+ - ✅ Blackboard architecture diagram
97
+
98
+ ### Planned
99
+ - [ ] Network compilation process (for `network-structure.md`)
100
+ - [ ] Variable binding flow (for `guides/variable-binding.md`)
101
+ - [ ] Token tree structure (for `advanced/debugging.md`)
102
+ - [ ] Performance comparison chart (for `advanced/performance.md`)
103
+ - [ ] Multi-agent message flow (for `examples/multi-agent.md`)
104
+
105
+ ## 📝 Content Guidelines
106
+
107
+ ### Every Document Should Include:
108
+ 1. **Clear introduction** - What this document covers
109
+ 2. **Code examples** - Real, runnable Ruby code
110
+ 3. **Visual aids** - SVG diagrams where helpful
111
+ 4. **Cross-references** - Links to related docs
112
+ 5. **Implementation references** - Line numbers for source code
113
+ 6. **Best practices** - Dos and don'ts
114
+ 7. **Next steps** - Where to go from here
115
+
116
+ ### SVG Requirements:
117
+ - Dark theme with transparent background
118
+ - Consistent color palette:
119
+ - Purple `#bb86fc` - Core components/control
120
+ - Teal `#03dac6` - Data/storage
121
+ - Pink `#cf6679` - Agents/actions
122
+ - Gold `#ffd700` - Important/production
123
+ - Monospace fonts for code
124
+ - Clear arrows and flow indicators
125
+ - Legends where needed
126
+
127
+ ## 🚀 Next Session Tasks
128
+
129
+ Based on build warnings, create in this order:
130
+
131
+ 1. **Stub all missing files** (eliminate build warnings)
132
+ 2. **Complete guides/** (highest user value)
133
+ 3. **Complete examples/** (practical learning)
134
+ 4. **Complete advanced/** (production users)
135
+ 5. **Complete api/** (reference documentation)
136
+
137
+ ## 📚 Documentation Style
138
+
139
+ - **Tone**: Technical but accessible
140
+ - **Code**: Always include complete, runnable examples
141
+ - **Length**: Comprehensive where needed (RETE doc is 650+ lines and that's perfect)
142
+ - **Format**: Markdown with code blocks, SVGs, tables
143
+ - **Audience**: Ruby developers new to rule-based systems
144
+
145
+ ## ✨ Quality Standards
146
+
147
+ - ✅ Every code example must be syntactically correct
148
+ - ✅ Every link must point to existing files
149
+ - ✅ Every SVG must have alt text/caption
150
+ - ✅ Every technical term explained on first use
151
+ - ✅ Implementation file references with line numbers
152
+ - ✅ No orphan pages (all linked from somewhere)
153
+
154
+ ---
155
+
156
+ **Last Updated**: {{ date }}
157
+ **Documentation Lead**: Claude Code
158
+ **Status**: In Progress (26% complete)