DeepCausality

Dynamic causality for advanced systems.

A causal-reasoning library for engineering systems where time, context, and rules evolve. Built around three primitives: the causal monad, the causaloid, and the context.

What can you build with DeepCausality

Pearl Rung-3: surgically intervene on a value mid-chain.

use deep_causality_core::{Intervenable, PropagatingEffect};

// Natural chain: nicotine → tar → cancer.
let before = PropagatingEffect::pure(0.8_f64)
    .bind(|nic, _, _| PropagatingEffect::pure(nicotine_to_tar(
        nic.into_value().unwrap_or_default())))
    .bind(|tar, _, _| PropagatingEffect::pure(tar_to_cancer(
        tar.into_value().unwrap_or_default())));

// Counterfactual: same start, but intervene on tar mid-chain.
let after = PropagatingEffect::pure(0.8_f64)
    .bind(|nic, _, _| PropagatingEffect::pure(nicotine_to_tar(
        nic.into_value().unwrap_or_default())))
    .intervene(0.1)
    .bind(|tar, _, _| PropagatingEffect::pure(tar_to_cancer(
        tar.into_value().unwrap_or_default())));

// Compare before.value vs after.value: that is the Pearl Rung-3 effect.

What DeepCausality can do for you

Static, dynamic, adaptive, and emergent causality

Model causal structure that is fixed at design time, evolves over the lifetime of a system, adapts to feedback, or arises from interaction. The same primitives carry across all four modalities, so the choice is a modeling decision.

Multi-shaped causality

Express a single rule as a Causaloid, a flat collection of Causaloids, or a hypergraph of nested Causaloids. The shape follows the problem: an isolated guard, a battery of independent checks, or a deeply composed causal structure with subgraphs and shared subexpressions.

Causal discovery via CDL

The Causal Discovery Language is a typestate-driven DSL that walks raw observational data through configuration, loading, feature selection, discovery, and analysis. Each stage is enforced by the type system.

Causal State Machines (CSM)

Wire Causaloids to actions and let the framework drive the transitions. The CSM pattern is the right fit for sensor monitoring, alerting, and control loops where a state change has to follow a causal verdict.

Static and dynamic context

Causaloids run inside a Context: a hypergraph of the data, time, and space they depend on. A static context is defined up front; a dynamic context grows, shrinks, or rewires at runtime as new information arrives.

Multimodal reasoning

A single graph can reason deterministically, probabilistically, counterfactually, or in any combination. The PropagatingEffect type carries the modality through the graph.

Markovian and non-Markovian modeling

PropagatingEffect carries the immediate signal; PropagatingProcess carries the trajectory of effects over time. Together they let a model reason about systems whose next state depends on the current state, on full history, or on anything in between.

First-class uncertainty

Uncertain<T> wraps a value whose distribution is known but whose exact value is not. MaybeUncertain<T> goes further and represents probabilistic presence: a value that may or may not be there. Both compose with the rest of the framework without breaking type safety.

Uniform mathematical composition

Tensors, multivectors, manifolds, and sparse matrices expose the same Functor/Monad/CoMonad surface through HAFT and the algebraic trait hierarchy.

Programmable safety with the Effect Ethos

The Effect Ethos is a programmable policy layer that verifies operational rules over the effects a graph produces. It lets safety-critical and regulated systems encode "what is allowed to happen" alongside "what does happen," checked deterministically at runtime.