rust_rule_engine/rete/
propagation.rs

1//! Incremental Propagation Engine (P3 Feature - Advanced)
2//!
3//! This module implements incremental updates similar to Drools:
4//! - Only propagate changed facts through the network
5//! - Track affected rules and activations
6//! - Efficient re-evaluation after updates
7
8use std::collections::{HashMap, HashSet};
9use std::sync::Arc;
10use super::working_memory::{WorkingMemory, FactHandle};
11use super::network::{ReteUlNode, TypedReteUlRule};
12use super::facts::{TypedFacts, FactValue};
13use super::agenda::{AdvancedAgenda, Activation};
14use super::template::TemplateRegistry;
15use super::globals::GlobalsRegistry;
16use super::deffacts::DeffactsRegistry;
17use crate::errors::{Result, RuleEngineError};
18
19/// Track which rules are affected by which fact types
20#[derive(Debug)]
21pub struct RuleDependencyGraph {
22    /// Map: fact_type -> set of rule indices that depend on it
23    fact_type_to_rules: HashMap<String, HashSet<usize>>,
24    /// Map: rule index -> set of fact types it depends on
25    rule_to_fact_types: HashMap<usize, HashSet<String>>,
26}
27
28impl RuleDependencyGraph {
29    /// Create new dependency graph
30    pub fn new() -> Self {
31        Self {
32            fact_type_to_rules: HashMap::new(),
33            rule_to_fact_types: HashMap::new(),
34        }
35    }
36
37    /// Add dependency: rule depends on fact type
38    pub fn add_dependency(&mut self, rule_idx: usize, fact_type: String) {
39        self.fact_type_to_rules
40            .entry(fact_type.clone())
41            .or_insert_with(HashSet::new)
42            .insert(rule_idx);
43
44        self.rule_to_fact_types
45            .entry(rule_idx)
46            .or_insert_with(HashSet::new)
47            .insert(fact_type);
48    }
49
50    /// Get rules affected by a fact type change
51    pub fn get_affected_rules(&self, fact_type: &str) -> HashSet<usize> {
52        self.fact_type_to_rules
53            .get(fact_type)
54            .cloned()
55            .unwrap_or_else(HashSet::new)
56    }
57
58    /// Get fact types that a rule depends on
59    pub fn get_rule_dependencies(&self, rule_idx: usize) -> HashSet<String> {
60        self.rule_to_fact_types
61            .get(&rule_idx)
62            .cloned()
63            .unwrap_or_else(HashSet::new)
64    }
65}
66
67impl Default for RuleDependencyGraph {
68    fn default() -> Self {
69        Self::new()
70    }
71}
72
73/// Type alias for custom test functions in RETE engine
74/// Functions take a slice of FactValues and return a FactValue (typically Boolean)
75pub type ReteCustomFunction = Arc<dyn Fn(&[FactValue], &TypedFacts) -> Result<FactValue> + Send + Sync>;
76
77/// Incremental Propagation Engine
78/// Only re-evaluates rules affected by changed facts
79pub struct IncrementalEngine {
80    /// Working memory
81    working_memory: WorkingMemory,
82    /// Rules
83    rules: Vec<TypedReteUlRule>,
84    /// Dependency graph
85    dependencies: RuleDependencyGraph,
86    /// Advanced agenda
87    agenda: AdvancedAgenda,
88    /// Track which facts each rule last matched
89    rule_matched_facts: HashMap<usize, HashSet<FactHandle>>,
90    /// Template registry for type-safe facts
91    templates: TemplateRegistry,
92    /// Global variables registry
93    globals: GlobalsRegistry,
94    /// Deffacts registry for initial facts
95    deffacts: DeffactsRegistry,
96    /// Custom functions for Test CE support
97    custom_functions: HashMap<String, ReteCustomFunction>,
98}
99
100impl IncrementalEngine {
101    /// Create new incremental engine
102    pub fn new() -> Self {
103        Self {
104            working_memory: WorkingMemory::new(),
105            rules: Vec::new(),
106            dependencies: RuleDependencyGraph::new(),
107            agenda: AdvancedAgenda::new(),
108            rule_matched_facts: HashMap::new(),
109            custom_functions: HashMap::new(),
110            templates: TemplateRegistry::new(),
111            globals: GlobalsRegistry::new(),
112            deffacts: DeffactsRegistry::new(),
113        }
114    }
115
116    /// Add rule and register its dependencies
117    pub fn add_rule(&mut self, rule: TypedReteUlRule, depends_on: Vec<String>) {
118        let rule_idx = self.rules.len();
119
120        // Register dependencies
121        for fact_type in depends_on {
122            self.dependencies.add_dependency(rule_idx, fact_type);
123        }
124
125        self.rules.push(rule);
126    }
127
128    /// Insert fact into working memory
129    pub fn insert(&mut self, fact_type: String, data: TypedFacts) -> FactHandle {
130        let handle = self.working_memory.insert(fact_type.clone(), data);
131
132        // Trigger incremental propagation for this fact type
133        self.propagate_changes_for_type(&fact_type);
134
135        handle
136    }
137
138    /// Update fact in working memory
139    pub fn update(&mut self, handle: FactHandle, data: TypedFacts) -> Result<()> {
140        // Get fact type before update
141        let fact_type = self.working_memory
142            .get(&handle)
143            .map(|f| f.fact_type.clone())
144            .ok_or_else(|| RuleEngineError::FieldNotFound {
145                field: format!("FactHandle {} not found", handle),
146            })?;
147
148        self.working_memory.update(handle, data).map_err(|e| RuleEngineError::EvaluationError {
149            message: e,
150        })?;
151
152        // Trigger incremental propagation for this fact type
153        self.propagate_changes_for_type(&fact_type);
154
155        Ok(())
156    }
157
158    /// Retract fact from working memory
159    pub fn retract(&mut self, handle: FactHandle) -> Result<()> {
160        // Get fact type before retract
161        let fact_type = self.working_memory
162            .get(&handle)
163            .map(|f| f.fact_type.clone())
164            .ok_or_else(|| RuleEngineError::FieldNotFound {
165                field: format!("FactHandle {} not found", handle),
166            })?;
167
168        self.working_memory.retract(handle).map_err(|e| RuleEngineError::EvaluationError {
169            message: e,
170        })?;
171
172        // Trigger incremental propagation for this fact type
173        self.propagate_changes_for_type(&fact_type);
174
175        Ok(())
176    }
177
178    /// Propagate changes for a specific fact type (incremental!)
179    fn propagate_changes_for_type(&mut self, fact_type: &str) {
180        // Get affected rules
181        let affected_rules = self.dependencies.get_affected_rules(fact_type);
182
183        if affected_rules.is_empty() {
184            return; // No rules depend on this fact type
185        }
186
187        // Flatten working memory to TypedFacts for evaluation
188        let facts = self.working_memory.to_typed_facts();
189
190        // Re-evaluate only affected rules
191        for &rule_idx in &affected_rules {
192            let rule = &self.rules[rule_idx];
193
194            // Evaluate rule condition
195            let matches = super::network::evaluate_rete_ul_node_typed(&rule.node, &facts);
196
197            if matches {
198                // Create activation
199                let activation = Activation::new(rule.name.clone(), rule.priority)
200                    .with_no_loop(rule.no_loop);
201
202                self.agenda.add_activation(activation);
203            }
204        }
205    }
206
207    /// Fire all pending activations
208    pub fn fire_all(&mut self) -> Vec<String> {
209        let mut fired_rules = Vec::new();
210
211        while let Some(activation) = self.agenda.get_next_activation() {
212            // Find rule
213            if let Some((idx, rule)) = self.rules
214                .iter_mut()
215                .enumerate()
216                .find(|(_, r)| r.name == activation.rule_name)
217            {
218                // Execute action
219                let mut facts = self.working_memory.to_typed_facts();
220                (rule.action)(&mut facts);
221
222                // Track fired rule
223                fired_rules.push(activation.rule_name.clone());
224                self.agenda.mark_rule_fired(&activation);
225
226                // TODO: Update working memory with changed facts
227                // This is complex and would require tracking what changed
228            }
229        }
230
231        fired_rules
232    }
233
234    /// Get working memory
235    pub fn working_memory(&self) -> &WorkingMemory {
236        &self.working_memory
237    }
238
239    /// Get mutable working memory
240    pub fn working_memory_mut(&mut self) -> &mut WorkingMemory {
241        &mut self.working_memory
242    }
243
244    /// Get agenda
245    pub fn agenda(&self) -> &AdvancedAgenda {
246        &self.agenda
247    }
248
249    /// Get mutable agenda
250    pub fn agenda_mut(&mut self) -> &mut AdvancedAgenda {
251        &mut self.agenda
252    }
253
254    /// Set conflict resolution strategy
255    ///
256    /// Controls how conflicting rules in the agenda are ordered.
257    /// Available strategies: Salience (default), LEX, MEA, Depth, Breadth, Simplicity, Complexity, Random
258    pub fn set_conflict_resolution_strategy(
259        &mut self,
260        strategy: super::agenda::ConflictResolutionStrategy,
261    ) {
262        self.agenda.set_strategy(strategy);
263    }
264
265    /// Get current conflict resolution strategy
266    pub fn conflict_resolution_strategy(&self) -> super::agenda::ConflictResolutionStrategy {
267        self.agenda.strategy()
268    }
269
270    /// Get statistics
271    pub fn stats(&self) -> IncrementalEngineStats {
272        IncrementalEngineStats {
273            rules: self.rules.len(),
274            working_memory: self.working_memory.stats(),
275            agenda: self.agenda.stats(),
276            dependencies: self.dependencies.fact_type_to_rules.len(),
277        }
278    }
279
280    /// Clear fired flags and reset agenda
281    pub fn reset(&mut self) {
282        self.agenda.reset_fired_flags();
283    }
284
285    /// Get template registry
286    pub fn templates(&self) -> &TemplateRegistry {
287        &self.templates
288    }
289
290    /// Get mutable template registry
291    pub fn templates_mut(&mut self) -> &mut TemplateRegistry {
292        &mut self.templates
293    }
294
295    /// Register a custom function for Test CE support
296    ///
297    /// # Example
298    /// ```
299    /// use rust_rule_engine::rete::{IncrementalEngine, FactValue};
300    ///
301    /// let mut engine = IncrementalEngine::new();
302    /// engine.register_function(
303    ///     "is_valid_email",
304    ///     |args, _facts| {
305    ///         if let Some(FactValue::String(email)) = args.first() {
306    ///             Ok(FactValue::Boolean(email.contains('@')))
307    ///         } else {
308    ///             Ok(FactValue::Boolean(false))
309    ///         }
310    ///     }
311    /// );
312    /// ```
313    pub fn register_function<F>(&mut self, name: &str, func: F)
314    where
315        F: Fn(&[FactValue], &TypedFacts) -> Result<FactValue> + Send + Sync + 'static,
316    {
317        self.custom_functions.insert(name.to_string(), Arc::new(func));
318    }
319
320    /// Get a custom function by name (for Test CE evaluation)
321    pub fn get_function(&self, name: &str) -> Option<&ReteCustomFunction> {
322        self.custom_functions.get(name)
323    }
324
325    /// Get global variables registry
326    pub fn globals(&self) -> &GlobalsRegistry {
327        &self.globals
328    }
329
330    /// Get mutable global variables registry
331    pub fn globals_mut(&mut self) -> &mut GlobalsRegistry {
332        &mut self.globals
333    }
334
335    /// Get deffacts registry
336    pub fn deffacts(&self) -> &DeffactsRegistry {
337        &self.deffacts
338    }
339
340    /// Get mutable deffacts registry
341    pub fn deffacts_mut(&mut self) -> &mut DeffactsRegistry {
342        &mut self.deffacts
343    }
344
345    /// Load all registered deffacts into working memory
346    /// Returns handles of all inserted facts
347    pub fn load_deffacts(&mut self) -> Vec<FactHandle> {
348        let mut handles = Vec::new();
349
350        // Get all facts from all registered deffacts
351        let all_facts = self.deffacts.get_all_facts();
352
353        for (_deffacts_name, fact_instance) in all_facts {
354            // Check if template exists for this fact type
355            let handle = if self.templates.get(&fact_instance.fact_type).is_some() {
356                // Use template validation
357                match self.insert_with_template(&fact_instance.fact_type, fact_instance.data) {
358                    Ok(h) => h,
359                    Err(_) => continue, // Skip invalid facts
360                }
361            } else {
362                // Insert without template validation
363                self.insert(fact_instance.fact_type, fact_instance.data)
364            };
365
366            handles.push(handle);
367        }
368
369        handles
370    }
371
372    /// Load a specific deffacts set by name
373    /// Returns handles of inserted facts or error if deffacts not found
374    pub fn load_deffacts_by_name(&mut self, name: &str) -> crate::errors::Result<Vec<FactHandle>> {
375        // Clone the facts to avoid borrow checker issues
376        let facts_to_insert = {
377            let deffacts = self.deffacts.get(name).ok_or_else(|| {
378                crate::errors::RuleEngineError::EvaluationError {
379                    message: format!("Deffacts '{}' not found", name),
380                }
381            })?;
382            deffacts.facts.clone()
383        };
384
385        let mut handles = Vec::new();
386
387        for fact_instance in facts_to_insert {
388            // Check if template exists for this fact type
389            let handle = if self.templates.get(&fact_instance.fact_type).is_some() {
390                // Use template validation
391                self.insert_with_template(&fact_instance.fact_type, fact_instance.data)?
392            } else {
393                // Insert without template validation
394                self.insert(fact_instance.fact_type, fact_instance.data)
395            };
396
397            handles.push(handle);
398        }
399
400        Ok(handles)
401    }
402
403    /// Reset engine and reload all deffacts (similar to CLIPS reset)
404    /// Clears working memory and agenda, then loads all deffacts
405    pub fn reset_with_deffacts(&mut self) -> Vec<FactHandle> {
406        // Clear working memory and agenda
407        self.working_memory = WorkingMemory::new();
408        self.agenda.clear();
409        self.rule_matched_facts.clear();
410
411        // Reload all deffacts
412        self.load_deffacts()
413    }
414
415    /// Insert a typed fact with template validation
416    pub fn insert_with_template(
417        &mut self,
418        template_name: &str,
419        data: TypedFacts,
420    ) -> crate::errors::Result<FactHandle> {
421        // Validate against template
422        self.templates.validate(template_name, &data)?;
423
424        // Insert into working memory
425        Ok(self.insert(template_name.to_string(), data))
426    }
427}
428
429impl Default for IncrementalEngine {
430    fn default() -> Self {
431        Self::new()
432    }
433}
434
435/// Engine statistics
436#[derive(Debug)]
437pub struct IncrementalEngineStats {
438    pub rules: usize,
439    pub working_memory: super::working_memory::WorkingMemoryStats,
440    pub agenda: super::agenda::AgendaStats,
441    pub dependencies: usize,
442}
443
444impl std::fmt::Display for IncrementalEngineStats {
445    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
446        write!(
447            f,
448            "Engine Stats: {} rules, {} fact types tracked\nWM: {}\nAgenda: {}",
449            self.rules,
450            self.dependencies,
451            self.working_memory,
452            self.agenda
453        )
454    }
455}
456
457#[cfg(test)]
458mod tests {
459    use super::*;
460    use crate::rete::network::ReteUlNode;
461    use crate::rete::alpha::AlphaNode;
462
463    #[test]
464    fn test_dependency_graph() {
465        let mut graph = RuleDependencyGraph::new();
466
467        graph.add_dependency(0, "Person".to_string());
468        graph.add_dependency(1, "Person".to_string());
469        graph.add_dependency(1, "Order".to_string());
470
471        let affected = graph.get_affected_rules("Person");
472        assert_eq!(affected.len(), 2);
473        assert!(affected.contains(&0));
474        assert!(affected.contains(&1));
475
476        let deps = graph.get_rule_dependencies(1);
477        assert_eq!(deps.len(), 2);
478        assert!(deps.contains("Person"));
479        assert!(deps.contains("Order"));
480    }
481
482    #[test]
483    fn test_incremental_propagation() {
484        let mut engine = IncrementalEngine::new();
485
486        // Add rule that depends on "Person" type
487        let node = ReteUlNode::UlAlpha(AlphaNode {
488            field: "Person.age".to_string(),
489            operator: ">".to_string(),
490            value: "18".to_string(),
491        });
492
493        let rule = TypedReteUlRule {
494            name: "IsAdult".to_string(),
495            node,
496            priority: 0,
497            no_loop: true,
498            action: Box::new(|_| {}),
499        };
500
501        engine.add_rule(rule, vec!["Person".to_string()]);
502
503        // Insert Person fact
504        let mut person = TypedFacts::new();
505        person.set("age", 25i64);
506        let handle = engine.insert("Person".to_string(), person);
507
508        // Check that rule was activated
509        let stats = engine.stats();
510        assert!(stats.agenda.total_activations > 0);
511
512        // Update person
513        let mut updated = TypedFacts::new();
514        updated.set("age", 15i64); // Now under 18
515        engine.update(handle, updated).unwrap();
516
517        // Rule should be re-evaluated (incrementally)
518    }
519}
rust_rule_engine/rete/propagation.rs

rust_rule_engine/rete/
propagation.rs
