Merge pull request #283 from marvin-hansen/main

feat(deep_causality): Implemented Adaptive Reasoning

Author: marvin-hansen

deep_causality/src/traits/causable_graph/graph_reasoning/mod.rs

@@ -47,6 +47,20 @@ where
     /// the output effect of a parent node becomes the input effect for its child node.
     /// The traversal continues as long as no `CausalityError` is returned.
     ///
+    /// ## Adaptive Reasoning
+    ///
+    /// If a `Causaloid` returns a `PropagatingEffect::RelayTo(target_index, inner_effect)`,
+    /// the BFS traversal dynamically jumps to  `target_index`, and `inner_effect` becomes
+    /// the new input for the relayed path. This enables *adaptive reasoning* conditional to the deciding
+    /// causaloid. To illustrate adaptive reasoning, an example clinical patent risk model may operate
+    /// very differently for patients with normal blood pressure compared to high blood pressure patients.
+    /// Therefore, two highly specialized models are defined and a dedicated dispatch causaloid.
+    /// The dispatch causaloid analyses blood pressure and then, conditional on its finding, dispatches
+    /// further reasoning to the matching model i.e. a dedicated sub-graph. Ensure that all possible
+    /// values of  target_index exists in the graph before implementing adaptive reasoning.
+    /// For more details, see section 5.10.3 Adaptive Reasoning in The EPP reference paper:
+    /// https://github.com/deepcausality-rs/papers/blob/main/effect_propagation_process/epp.pdf
+    ///
     /// # Arguments
     ///
     /// * `start_index` - The index of the node to start the traversal from.
@@ -57,7 +71,7 @@ where
     /// * `Ok(PropagatingEffect)`: The final `PropagatingEffect` from the last successfully evaluated node
     ///   in the main traversal path. `Deterministic(false)` now propagates and does not implicitly halt propagation.
     ///   Only a `Causaloid` returning a `CausalityError` will abort the traversal.
-    /// * `Err(CausalityError)` if the graph is not frozen, a node is missing, or an evaluation fails.
+    /// * `Err(CausalityError)` if the graph is not frozen, a node is missing, a RelayTo target cannot be found or an evaluation fails.
     fn evaluate_subgraph_from_cause(
         &self,
         start_index: usize,
@@ -100,13 +114,41 @@ where
             // This ensures the function returns the effect of the last node on the path.
             last_propagated_effect = result_effect.clone();
 
-            // Only a CausalityError returned from cause.evaluate() will abort the traversal.
-            let children = self.get_graph().outbound_edges(current_index)?;
-            for child_index in children {
-                if !visited[child_index] {
-                    visited[child_index] = true;
-                    // Pass the result_effect of the current node to its children.
-                    queue.push_back((child_index, result_effect.clone()));
+            match result_effect {
+                // Adaptive reasoning:
+                // The Causaloid itself determines the next step in the reasoning process
+                // conditional on its reasoning outcome. Based on its own internal logic,
+                // a Causaloid then dynamically dispatches the flow of causality
+                // to another Causaloid in the graph, enabling adaptive reasoning.
+                PropagatingEffect::RelayTo(target_index, inner_effect) => {
+                    // If a RelayTo effect is returned, clear the queue and add the target_index
+                    // with the inner_effect as the new starting point for traversal.
+                    queue.clear();
+
+                    // Validate target_index before proceeding
+                    if !self.contains_causaloid(target_index) {
+                        return Err(CausalityError(format!(
+                            "RelayTo target causaloid with index {target_index} not found in graph."
+                        )));
+                    }
+
+                    if !visited[target_index] {
+                        visited[target_index] = true;
+                        queue.push_back((target_index, *inner_effect));
+                    }
+                    // Update last_propagated_effect to reflect the effect of the relayed node.
+                    // This is already handled by the line above: last_propagated_effect = result_effect.clone();
+                }
+                _ => {
+                    // Only a CausalityError returned from cause.evaluate() will abort the traversal.
+                    let children = self.get_graph().outbound_edges(current_index)?;
+                    for child_index in children {
+                        if !visited[child_index] {
+                            visited[child_index] = true;
+                            // Pass the result_effect of the current node to its children.
+                            queue.push_back((child_index, result_effect.clone()));
+                        }
+                    }
                 }
             }
         }
@@ -121,6 +163,15 @@ where
     /// one causaloid becomes the input for the next causaloid in the path. If any node
     /// fails evaluation or returns a non-propagating effect that prunes the path, the reasoning stops.
     ///
+    /// If a `Causaloid` returns a `PropagatingEffect::RelayTo(target_index, inner_effect)`,
+    /// the shortest path traversal is immediately interrupted, and the `RelayTo` effect
+    /// is returned to the caller, signaling a dynamic redirection. The runtime behavior differs
+    /// from `evaluate_subgraph_from_cause` because a shortest path is assumed to be a fixed path
+    /// and thus RelayTo is not supposed to happen in the middle of the path. Therefore, the
+    /// call-site must handle the occurrence i.e. when its a known final effect.
+    /// For more details, see section 5.10.3 Adaptive Reasoning in The EPP reference paper:
+    /// https://github.com/deepcausality-rs/papers/blob/main/effect_propagation_process/epp.pdf
+    ///
     /// # Arguments
     ///
     /// * `start_index` - The index of the start cause.
@@ -130,6 +181,7 @@ where
     /// # Returns
     ///
     /// * `Ok(PropagatingEffect)`: The final `PropagatingEffect` from the last evaluated node on the path.
+    ///   If a `RelayTo` effect is encountered, that effect is returned immediately.
     /// * `Err(CausalityError)` if the path cannot be found or an evaluation fails.
     fn evaluate_shortest_path_between_causes(
         &self,
@@ -164,8 +216,14 @@ where
             // Evaluate the current cause with the effect propagated from the previous node.
             // Then, overwrite the current_effect with the result of the evaluation, which then
             // serves as the input for the next node.
-            // Only a CausalityError returned from cause.evaluate() will abort the traversal.
+            // For normal traversal, a CausalityError returned from cause.evaluate() will abort the traversal.
             current_effect = cause.evaluate(&current_effect)?;
+
+            // If a RelayTo effect is returned, stop the shortest path traversal and return it
+            // because it breaks the assumption of a fixed shortest path.
+            if let PropagatingEffect::RelayTo(_, _) = current_effect {
+                return Ok(current_effect);
+            }
         }
 
         // If the loop completes, all nodes on the path were successfully evaluated.

deep_causality/src/types/reasoning_types/propagating_effect/mod.rs

@@ -41,8 +41,9 @@ pub enum PropagatingEffect {
     Map(HashMap<IdentificationValue, Box<PropagatingEffect>>),
     /// A graph of effects, for passing complex relational data.
     Graph(Arc<EffectGraph>),
-    /// A dispatch command that directs a reasoning engine to jump to a specific
-    /// next causaloid with the specified id (`usize`) and provide it with the encapsulated effect as its new input.
+    /// A dispatch command that directs the reasoning engine to dynamically jump to a specific
+    /// causaloid within the graph. The `usize` is the target causaloid's index, and the `Box<PropagatingEffect>`
+    /// is the effect to be passed as input to that target causaloid. This enables adaptive reasoning.
     RelayTo(usize, Box<PropagatingEffect>),
 }
 

deep_causality/tests/types/causal_types/causaloid_graph/causality_graph_reasoning_adaptive_tests.rs

@@ -0,0 +1,237 @@
+#![allow(clippy::too_many_arguments)]
+
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use deep_causality::utils_test::test_utils;
+use deep_causality::*;
+
+#[test]
+fn test_evaluate_subgraph_from_cause_with_relay_to_simple() {
+    // Graph: Root (0) -> A (1) -> B (2) -> C (3)
+    // A will relay to C
+    let mut g = CausaloidGraph::new(0);
+
+    let root_causaloid = test_utils::get_test_causaloid_deterministic_true();
+    let root_index = g.add_root_causaloid(root_causaloid).unwrap();
+
+    // Causaloid A: Relays to C (index 3) with a specific effect
+    let causaloid_a_id = 10;
+    let causaloid_a_description = "Causaloid A relays to node 3 with Numerical(100.0)";
+    let causaloid_a_fn =
+        |_effect: &PropagatingEffect| -> Result<PropagatingEffect, CausalityError> {
+            Ok(PropagatingEffect::RelayTo(
+                3,
+                Box::new(PropagatingEffect::Deterministic(false)),
+            ))
+        };
+    let causaloid_a = Causaloid::new(causaloid_a_id, causaloid_a_fn, causaloid_a_description);
+    let idx_a = g.add_causaloid(causaloid_a).unwrap();
+
+    // Causaloid B: Standard causaloid, should be skipped
+    let causaloid_b = test_utils::get_test_causaloid_deterministic_input_output();
+    let idx_b = g.add_causaloid(causaloid_b).unwrap();
+
+    // Causaloid C: Standard causaloid, should be the final evaluated node
+    let causaloid_c = test_utils::get_test_causaloid_deterministic_input_output();
+    let idx_c = g.add_causaloid(causaloid_c).unwrap();
+
+    // Link the graph: Root -> A -> B -> C
+    g.add_edge(root_index, idx_a).unwrap();
+    g.add_edge(idx_a, idx_b).unwrap();
+    g.add_edge(idx_b, idx_c).unwrap();
+
+    g.freeze();
+
+    let initial_effect = PropagatingEffect::Deterministic(true);
+    let res = g.evaluate_subgraph_from_cause(root_index, &initial_effect);
+
+    dbg!(&res);
+    assert!(res.is_ok());
+    // Expected: Root (true) -> A (Relay to C with Deterministic(false))
+    // C (input  Deterministic(false)) -> Deterministic(true) (C just inverts the input)
+    assert_eq!(res.unwrap(), PropagatingEffect::Deterministic(true));
+}
+
+#[test]
+fn test_evaluate_subgraph_from_cause_with_relay_to_visited_node() {
+    // Graph: Root (0) -> A (1) -> B (2)
+    // B will relay back to Root (0)
+    let mut g = CausaloidGraph::new(0);
+
+    let root_causaloid = test_utils::get_test_causaloid_deterministic_true();
+    let root_index = g.add_root_causaloid(root_causaloid).unwrap();
+
+    let causaloid_a = test_utils::get_test_causaloid_deterministic_input_output();
+    let idx_a = g.add_causaloid(causaloid_a).unwrap();
+
+    // Causaloid B: Relays back to Root (index 0)
+    let causaloid_b_id = 11;
+    let causaloid_b_description = "Causaloid B relays to node 0 with Numerical(50.0)";
+    let causaloid_b_fn =
+        |_effect: &PropagatingEffect| -> Result<PropagatingEffect, CausalityError> {
+            Ok(PropagatingEffect::RelayTo(
+                0,
+                Box::new(PropagatingEffect::Numerical(50.0)),
+            ))
+        };
+    let causaloid_b = Causaloid::new(causaloid_b_id, causaloid_b_fn, causaloid_b_description);
+    let idx_b = g.add_causaloid(causaloid_b).unwrap();
+
+    // Link the graph: Root -> A -> B
+    g.add_edge(root_index, idx_a).unwrap();
+    g.add_edge(idx_a, idx_b).unwrap();
+
+    g.freeze();
+
+    let initial_effect = PropagatingEffect::Deterministic(true);
+    let res = g.evaluate_subgraph_from_cause(root_index, &initial_effect);
+
+    assert!(res.is_ok());
+    // Expected: Root (true) -> A (false) -> B (Relay to Root with Numerical(50.0))
+    // The traversal should jump back to Root, but since Root is already visited, it won't be re-added.
+    // The last propagated effect will be the RelayTo effect from B.
+    assert_eq!(
+        res.unwrap(),
+        PropagatingEffect::RelayTo(0, Box::new(PropagatingEffect::Numerical(50.0)))
+    );
+}
+
+#[test]
+fn test_evaluate_shortest_path_between_causes_with_relay_interrupt() {
+    // Graph: Root (0) -> A (1) -> B (2) -> C (3)
+    // A will relay, interrupting the shortest path from Root to C
+    let mut g = CausaloidGraph::new(0);
+
+    let root_causaloid = test_utils::get_test_causaloid_deterministic_true();
+    let root_index = g.add_root_causaloid(root_causaloid).unwrap();
+
+    // Causaloid A: Relays to C (index 3) with a specific effect
+    let causaloid_a_id = 12;
+    let causaloid_a_description = "Causaloid A relays to node 3 with Numerical(200.0)";
+    let causaloid_a_fn =
+        |_effect: &PropagatingEffect| -> Result<PropagatingEffect, CausalityError> {
+            Ok(PropagatingEffect::RelayTo(
+                3,
+                Box::new(PropagatingEffect::Numerical(200.0)),
+            ))
+        };
+    let causaloid_a = Causaloid::new(causaloid_a_id, causaloid_a_fn, causaloid_a_description);
+    let idx_a = g.add_causaloid(causaloid_a).unwrap();
+
+    // Causaloid B: Standard causaloid, should not be reached
+    let causaloid_b = test_utils::get_test_causaloid_deterministic_input_output();
+    let idx_b = g.add_causaloid(causaloid_b).unwrap();
+
+    // Causaloid C: Standard causaloid
+    let causaloid_c = test_utils::get_test_causaloid_deterministic_input_output();
+    let idx_c = g.add_causaloid(causaloid_c).unwrap();
+
+    // Link the graph: Root -> A -> B -> C
+    g.add_edge(root_index, idx_a).unwrap();
+    g.add_edge(idx_a, idx_b).unwrap();
+    g.add_edge(idx_b, idx_c).unwrap();
+
+    g.freeze();
+
+    let initial_effect = PropagatingEffect::Deterministic(true);
+    // Attempt to find shortest path from Root (0) to C (3)
+    let res = g.evaluate_shortest_path_between_causes(root_index, idx_c, &initial_effect);
+
+    assert!(res.is_ok());
+    // Expected: The RelayTo effect from A should interrupt the path and be returned.
+    assert_eq!(
+        res.unwrap(),
+        PropagatingEffect::RelayTo(3, Box::new(PropagatingEffect::Numerical(200.0)))
+    );
+}
+
+#[test]
+fn test_evaluate_shortest_path_between_causes_with_relay_at_end() {
+    // Graph: Root (0) -> A (1) -> B (2)
+    // B will relay, as the last node on the shortest path
+    let mut g = CausaloidGraph::new(0);
+
+    let root_causaloid = test_utils::get_test_causaloid_deterministic_true();
+    let root_index = g.add_root_causaloid(root_causaloid).unwrap();
+
+    let causaloid_a = test_utils::get_test_causaloid_deterministic_input_output();
+    let idx_a = g.add_causaloid(causaloid_a).unwrap();
+
+    // Causaloid B: Relays to Root (index 0)
+    let causaloid_b_id = 13;
+    let causaloid_b_description = "Causaloid B relays to node 0 with Numerical(50.0)";
+    let causaloid_b_fn =
+        |_effect: &PropagatingEffect| -> Result<PropagatingEffect, CausalityError> {
+            Ok(PropagatingEffect::RelayTo(
+                0,
+                Box::new(PropagatingEffect::Numerical(50.0)),
+            ))
+        };
+    let causaloid_b = Causaloid::new(causaloid_b_id, causaloid_b_fn, causaloid_b_description);
+    let idx_b = g.add_causaloid(causaloid_b).unwrap();
+
+    // Link the graph: Root -> A -> B
+    g.add_edge(root_index, idx_a).unwrap();
+    g.add_edge(idx_a, idx_b).unwrap();
+
+    g.freeze();
+
+    let initial_effect = PropagatingEffect::Deterministic(true);
+    // Attempt to find shortest path from Root (0) to B (2)
+    let res = g.evaluate_shortest_path_between_causes(root_index, idx_b, &initial_effect);
+
+    assert!(res.is_ok());
+    // Expected: The RelayTo effect from B should be returned.
+    assert_eq!(
+        res.unwrap(),
+        PropagatingEffect::RelayTo(0, Box::new(PropagatingEffect::Numerical(50.0)))
+    );
+}
+
+#[test]
+fn test_evaluate_subgraph_from_cause_relay_to_non_existent_node() {
+    // Graph: Root (0) -> A (1)
+    // A will relay to a non-existent node (e.g., index 99)
+    let mut g = CausaloidGraph::new(0);
+
+    let root_causaloid = test_utils::get_test_causaloid_deterministic_true();
+    let root_index = g.add_root_causaloid(root_causaloid).unwrap();
+
+    // Causaloid A: Relays to a non-existent node (index 99)
+    let non_existent_target_index = 124;
+    let causaloid_a_id = 14;
+    let causaloid_a_description = format!(
+        "Causaloid A relays to non-existent node {}",
+        non_existent_target_index
+    );
+    let causaloid_a_fn =
+        |_effect: &PropagatingEffect| -> Result<PropagatingEffect, CausalityError> {
+            Ok(PropagatingEffect::RelayTo(
+                124, // non_existent_target_index
+                Box::new(PropagatingEffect::Numerical(1.0)),
+            ))
+        };
+
+    let causaloid_a = Causaloid::new(causaloid_a_id, causaloid_a_fn, &causaloid_a_description);
+    let idx_a = g.add_causaloid(causaloid_a).unwrap();
+
+    // Link the graph: Root -> A
+    g.add_edge(root_index, idx_a).unwrap();
+
+    g.freeze();
+
+    let initial_effect = PropagatingEffect::Deterministic(true);
+    let res = g.evaluate_subgraph_from_cause(root_index, &initial_effect);
+
+    assert!(res.is_err());
+    assert_eq!(
+        res.unwrap_err().to_string(),
+        format!(
+            "CausalityError: RelayTo target causaloid with index {} not found in graph.",
+            non_existent_target_index
+        )
+    );
+}

deep_causality/tests/types/causal_types/causaloid_graph/mod.rs

@@ -12,6 +12,8 @@ mod causality_graph_freeze_tests;
 #[cfg(test)]
 mod causality_graph_nodes_tests;
 #[cfg(test)]
+mod causality_graph_reasoning_adaptive_tests;
+#[cfg(test)]
 mod causality_graph_reasoning_all_tests;
 #[cfg(test)]
 mod causality_graph_reasoning_imbalanced_tests;