This directory contains examples demonstrating the Causal State Machine pattern. CSMs are systems where state transitions are governed not just by events, but by causal reasoning (Cause -> Effect -> New State) and potentially ethical/normative rules.
Run any example from the repository root:
cargo run -p csm_examples --example <example_name>| Example | Pattern | Description |
|---|---|---|
| csm_basic | Basic CSM | A simple monitoring system (Sensor -> Action) demonstrating the fundamental State-Causaloid-Action loop. |
| csm_context | Contextual CSM | Demonstrates sharing mutable data (BaseContext) across the causal graph using Arc<RwLock>, allowing complex state aggregations. |
| csm_effect_ethos | Ethical CSM | Integrates Deontic Logic (Obligation, Permission, Prohibition) into the state machine, allowing the system to evaluate the "moral permissibility" of an action before execution. |
The core unit of a CSM is the Causaloid. Unlike a simple state transition function, a Causaloid encapsulates:
-
Causal Function: The logic
$f(data) \to bool$ . - Description: Human-readable explanation of why this causal link exists.
- Weights: For probabilistic reasoning.
In complex systems, decisions often depend on a global context (e.g., total system power, user permissions) rather than just local inputs. The csm_context example shows how to thread this context safely through the graph.
The csm_effect_ethos example demonstrates a "Super-Ego" layer for AI agents. Even if an action is causally possible, the system checks if it is ethically permissible (e.g., "Do not delete root files").
| Example | Command |
|---|---|
| Basic CSM | cargo run -p csm_examples --example csm_example |
| Contextual CSM | cargo run -p csm_examples --example csm_context_example |
| Ethical CSM | cargo run -p csm_examples --example csm_effect_ethos_example |