Merge pull request #295 from marvin-hansen/main

feat(deep_causality): Implemented Effect Ethos for Deontic Reasoning and Action-Guarding

Author: marvin-hansen

Cargo.lock

@@ -15,7 +15,7 @@ bazel_dep(name = "rules_rust", version = "0.63.0")
 ###############################################################################
 RUST_EDITION = "2024"
 
-RUST_VERSION = "1.88.0"
+RUST_VERSION = "1.89.0"
 
 rust = use_extension("@rules_rust//rust:extensions.bzl", "rust")
 rust.toolchain(

MODULE.bazel

@@ -18,7 +18,7 @@ echo "smoking: Simple causal model without  Context"
 echo "--------------------------------"
 echo ""
 
-select opt in  cate csm dbn granger starter scm rcm quit;
+select opt in  cate csm dbn ethos granger starter scm rcm quit;
 do
   case $opt in
 
@@ -40,6 +40,12 @@ do
       break
       ;;
 
+    ethos)
+      echo "Selected example: ethos (CSM with Effect Ethos)"
+      command cargo run --release --bin example_effect_ethos
+      break
+      ;;
+
     starter)
       echo "Selected example: Starter (Starter)"
       command cargo run --release --bin example-starter

MODULE.bazel.lock

@@ -17,3 +17,9 @@ impl fmt::Display for ActionError {
         write!(f, "ActionError: {}", self.0)
     }
 }
+
+impl From<String> for ActionError {
+    fn from(s: String) -> Self {
+        ActionError(s)
+    }
+}

build/scripts/example.sh

@@ -0,0 +1,56 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use crate::{ActionError, CausalityError, DeonticError};
+use std::error::Error;
+use std::fmt::{Display, Formatter};
+
+#[derive(Debug)]
+pub enum CsmError {
+    Action(ActionError),
+    Causal(CausalityError),
+    Deontic(DeonticError),
+    Forbidden(String),
+}
+
+impl Error for CsmError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            CsmError::Action(e) => Some(e),
+            CsmError::Deontic(e) => Some(e),
+            CsmError::Causal(e) => Some(e),
+            CsmError::Forbidden(_) => None,
+        }
+    }
+}
+
+impl Display for CsmError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            CsmError::Action(e) => write!(f, "CSM Action Error: {e}"),
+            CsmError::Deontic(e) => write!(f, "CSM Deontic Error: {e}"),
+            CsmError::Causal(e) => write!(f, "CSM Causal Error: {e}"),
+            CsmError::Forbidden(s) => write!(f, "{s}"),
+        }
+    }
+}
+
+impl From<ActionError> for CsmError {
+    fn from(err: ActionError) -> Self {
+        CsmError::Action(err)
+    }
+}
+
+impl From<DeonticError> for CsmError {
+    fn from(err: DeonticError) -> Self {
+        CsmError::Deontic(err)
+    }
+}
+
+impl From<CausalityError> for CsmError {
+    fn from(err: CausalityError) -> Self {
+        CsmError::Causal(err)
+    }
+}

deep_causality/src/errors/action_error.rs

@@ -0,0 +1,138 @@
+/*
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) "2025" . The DeepCausality Authors and Contributors. All Rights Reserved.
+ */
+
+use crate::TeloidID;
+use std::error::Error;
+use std::fmt;
+use ultragraph::GraphError;
+
+/// Errors related to the Deontic Inference process within the Effect Ethos.
+#[derive(Debug, Clone, PartialEq)]
+pub enum DeonticError {
+    /// Failed to add a new teloid to the graph.
+    FailedToAddTeloid,
+
+    /// Failed to add edge to the graph.
+    FailedToAddEdge(usize, usize),
+
+    /// An operation was attempted on a graph that was not frozen.
+    /// Deontic inference requires a static, immutable graph.
+    GraphNotFrozen,
+
+    /// An mutation operation was attempted on a graph that was frozen.
+    /// Mutation requires an unfrozen graph
+    GraphIsFrozen,
+
+    /// The TeloidGraph is invalid because it contains a cycle, which would
+    /// lead to infinite loops in reasoning.
+    GraphIsCyclic,
+
+    /// A TeloidID exists in the graph or tag index but not in the TeloidStore,
+    /// indicating a critical state inconsistency.
+    TeloidNotFound { id: TeloidID },
+
+    /// The final set of active norms was empty or otherwise unable to produce
+    /// a conclusive verdict.
+    InconclusiveVerdict,
+
+    /// No applicable norms were found for a given action.
+    NoRelevantNormsFound,
+
+    /// The CausalState is missing a context, which is required for deontic evaluation.
+    MissingContext,
+
+    /// Wraps a lower-level error from the ultragraph crate.
+    GraphError(GraphError),
+}
+
+impl Error for DeonticError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            DeonticError::GraphError(e) => Some(e),
+            _ => None,
+        }
+    }
+}
+
+impl fmt::Display for DeonticError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            DeonticError::GraphNotFrozen => {
+                write!(
+                    f,
+                    "Deontic inference failed: The TeloidGraph must be frozen before evaluation."
+                )
+            }
+            DeonticError::GraphIsFrozen => {
+                write!(
+                    f,
+                    "Deontic inference failed: The TeloidGraph is frozen and cannot be modified."
+                )
+            }
+
+            DeonticError::GraphIsCyclic => {
+                write!(
+                    f,
+                    "Deontic inference failed: The TeloidGraph contains a cycle and is invalid."
+                )
+            }
+            DeonticError::TeloidNotFound { id } => {
+                write!(
+                    f,
+                    "Deontic inference failed: Teloid with ID {} not found in store.",
+                    id
+                )
+            }
+            DeonticError::InconclusiveVerdict => {
+                write!(
+                    f,
+                    "Deontic inference failed: The final set of active norms was inconclusive."
+                )
+            }
+            DeonticError::MissingContext => {
+                write!(
+                    f,
+                    "Deontic inference failed: The CausalState is missing a context."
+                )
+            }
+            DeonticError::GraphError(e) => {
+                write!(
+                    f,
+                    "A graph operation failed during deontic inference: {}",
+                    e
+                )
+            }
+            DeonticError::FailedToAddTeloid => {
+                write!(f, "Failed to add a new teloid to the graph.")
+            }
+            DeonticError::FailedToAddEdge(source, target) => {
+                write!(
+                    f,
+                    "Edge from {source} to {target} could not be created; a node may not exist or the edge already exists."
+                )
+            }
+            DeonticError::NoRelevantNormsFound => {
+                write!(
+                    f,
+                    "No relevant norms found, so the action cannot be decided. Please check if you have added the correct tags."
+                )
+            }
+        }
+    }
+}
+
+impl From<GraphError> for DeonticError {
+    fn from(err: GraphError) -> Self {
+        match err {
+            GraphError::GraphIsFrozen => DeonticError::GraphIsFrozen,
+            GraphError::GraphNotFrozen => DeonticError::GraphNotFrozen,
+            GraphError::GraphContainsCycle => DeonticError::GraphIsCyclic,
+            GraphError::EdgeCreationError { source, target } => {
+                DeonticError::FailedToAddEdge(source, target)
+            }
+            _ => DeonticError::GraphError(err),
+        }
+    }
+}

deep_causality/src/errors/csm_error.rs

@@ -11,6 +11,8 @@ mod causal_graph_index_error;
 mod causality_error;
 mod causality_graph_error;
 mod context_index_error;
+mod csm_error;
+mod deontic_error;
 mod index_error;
 mod model_build_error;
 mod model_generation_error;
@@ -25,6 +27,8 @@ pub use causal_graph_index_error::*;
 pub use causality_error::*;
 pub use causality_graph_error::*;
 pub use context_index_error::*;
+pub use csm_error::*;
+pub use deontic_error::*;
 pub use index_error::*;
 pub use model_build_error::*;
 pub use model_generation_error::*;

deep_causality/src/errors/deontic_error.rs

@@ -81,18 +81,24 @@ pub use crate::traits::observable::ObservableReasoning;
 // Scalar Traits
 pub use crate::traits::scalar::scalar_projector::ScalarProjector;
 pub use crate::traits::scalar::scalar_value::ScalarValue;
+// Teloid Traits
+pub use crate::traits::telos::deontic_explainable::DeonticExplainable;
+pub use crate::traits::telos::deontic_inferable::DeonticInferable;
+pub use crate::traits::telos::teloid_storable::TeloidStorable;
+pub use crate::traits::telos::teloidable::Teloidable;
 // Transferable Trait
 pub use crate::traits::transferable::Transferable;
 //
 // Types
 //
 // Alias types
 pub use crate::types::alias_types::alias_base::*;
+pub use crate::types::alias_types::alias_csm::*;
 pub use crate::types::alias_types::alias_function::*;
 pub use crate::types::alias_types::alias_lock::*;
 pub use crate::types::alias_types::alias_primitives::*;
 pub use crate::types::alias_types::alias_uniform::*;
-pub use crate::types::alias_types::*;
+// pub use crate::types::alias_types::*;
 // Causal types
 pub use crate::types::causal_types::causal_type::CausaloidType;
 pub use crate::types::causal_types::causaloid::Causaloid;
@@ -136,7 +142,7 @@ pub use crate::types::context_node_types::time::time_kind::TimeKind;
 pub use crate::types::context_types::relation_kind::*;
 pub use crate::types::context_types::time_scale::TimeScale;
 // CSM types
-pub use crate::types::csm_types::CSM;
+pub use crate::types::csm_types::csm::CSM;
 pub use crate::types::csm_types::csm_action::CausalAction;
 pub use crate::types::csm_types::csm_state::CausalState;
 // Generative types
@@ -154,6 +160,18 @@ pub use crate::types::reasoning_types::propagating_effect::PropagatingEffect;
 //Symbolic types
 pub use crate::types::symbolic_types::symbolic_representation::SymbolicRepresentation;
 pub use crate::types::symbolic_types::symbolic_result::SymbolicResult;
+//
+// Teloid types
+pub use crate::types::telos_types::action_parameter_value::ActionParameterValue;
+pub use crate::types::telos_types::effect_ethos::EffectEthos;
+pub use crate::types::telos_types::proposed_action::ProposedAction;
+pub use crate::types::telos_types::tag_index::TagIndex;
+pub use crate::types::telos_types::teloid::{Teloid, TeloidMetaData};
+pub use crate::types::telos_types::teloid_graph::*;
+pub use crate::types::telos_types::teloid_modal::TeloidModal;
+pub use crate::types::telos_types::teloid_relation::TeloidRelation;
+pub use crate::types::telos_types::teloid_store::TeloidStore;
+pub use crate::types::telos_types::teloid_verdict::Verdict;
 // Utils
 //
 pub use crate::utils::time_utils::*;

deep_causality/src/errors/mod.rs

@@ -59,7 +59,7 @@ where
     /// 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
+    /// <https://github.com/deepcausality-rs/papers/blob/main/effect_propagation_process/epp.pdf>
     ///
     /// # Arguments
     ///
@@ -170,7 +170,7 @@ where
     /// 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
+    /// <https://github.com/deepcausality-rs/papers/blob/main/effect_propagation_process/epp.pdf>
     ///
     /// # Arguments
     ///