# Causal Relationship Types in Semantica's ContextGraph: A Complete Guide

> Explore Semantica's ContextGraph causal relationship types: CAUSED, INFLUENCED, and PRECEDENT_FOR. Understand how they track decision dependencies for clear insights.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-08

---

**Semantica's `ContextGraph` supports three canonical causal relationship types—`CAUSED`, `INFLUENCED`, and `PRECEDENT_FOR`—along with present-tense aliases that automatically normalize to these canonical forms when recording dependencies between decisions.**

The `ContextGraph` class in the semantica-agi/semantica repository provides a structured way to map how decisions relate to one another through causal links. Understanding the available causal relationship types is essential for building accurate decision dependency chains and performing root-cause analysis on complex decision trees.

## Canonical Causal Relationship Types

The core vocabulary for causality is defined in the private constant `_CAUSAL_EDGE_TYPES` located at lines 532-36 of [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py). This enumeration establishes three distinct semantic levels for connecting decision nodes:

- **CAUSED**: Indicates that a decision *directly* caused another decision. This represents the strongest form of causal dependency.

- **INFLUENCED**: Denotes that a decision *influenced* another decision, representing a weaker, indirect effect or partial contribution.

- **PRECEDENT_FOR**: Specifies that a decision serves as a precedent for another decision, establishing a legal or logical foundation without implying direct causation.

## Present-Tense Aliases and Normalization

To keep the API user-friendly, the module accepts present-tense aliases that are automatically normalized to canonical forms. These mappings are defined in `_CAUSAL_EDGE_ALIASES` at lines 438-50 of [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py):

- `CAUSES` → `CAUSED`

- `INFLUENCES` → `INFLUENCED`

- `PRECEDES` → `PRECEDENT_FOR`

When you call `ContextGraph.add_causal_relationship(...)`, the system transparently converts these aliases to their canonical equivalents before storing the edge.

## Implementing Causal Relationships in Code

The following examples demonstrate how to initialize a graph, add decision nodes, and record causal relationships using both canonical types and their aliases.

```python
from semantica.context import ContextGraph

# Initialise a context graph

g = ContextGraph()

# Add decisions (nodes)

g.add_node("d_root", "decision")
g.add_node("d_child", "decision")
g.add_node("d_grandchild", "decision")

# Record causal relationships using canonical types

g.add_causal_relationship("d_root", "d_child", "CAUSED")
g.add_causal_relationship("d_child", "d_grandchild", "CAUSED")

# Or use the present‑tense aliases (they are auto‑normalized)

g.add_causal_relationship("d_root", "d_child", "CAUSES")         # → CAUSED

g.add_causal_relationship("d_child", "d_grandchild", "INFLUENCES")  # → INFLUENCED

```

## Traversing Causal Chains

Once relationships are established, you can traverse the graph using `get_causal_chain()` to analyze dependencies in both directions. This method is implemented in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) and supports both downstream and upstream traversal.

To retrieve a downstream causal chain:

```python

# Retrieve a downstream causal chain

chain = g.get_causal_chain("d_root", direction="downstream", max_depth=5)
print(chain)   # ['d_child', 'd_grandchild']

```

To trace backwards for root-cause analysis:

```python

# Retrieve an upstream causal chain (reverse direction)

up_chain = g.get_causal_chain("d_grandchild", direction="upstream")
print(up_chain)   # ['d_child', 'd_root']

```

The `CausalChainAnalyzer` class in [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py) provides additional analytical capabilities using the same causal vocabularies.

## Summary

- **Three canonical types** define causality in Semantica: `CAUSED` (direct), `INFLUENCED` (indirect), and `PRECEDENT_FOR` (foundational).

- **Alias normalization** allows natural present-tense inputs (`CAUSES`, `INFLUENCES`, `PRECEDES`) that convert automatically to canonical forms.

- **Source definitions** reside in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py), specifically in `_CAUSAL_EDGE_TYPES` (lines 532-36) and `_CAUSAL_EDGE_ALIASES` (lines 438-50).

- **API methods** like `add_causal_relationship()` and `get_causal_chain()` enable both recording and traversing decision dependencies.

## Frequently Asked Questions

### What are the three causal relationship types in Semantica's ContextGraph?

Semantica defines three canonical causal relationship types in the `_CAUSAL_EDGE_TYPES` constant: **`CAUSED`** for direct causation, **`INFLUENCED`** for indirect effects, and **`PRECEDENT_FOR`** for foundational relationships. These are implemented in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) at lines 532-36.

### Can I use present-tense verbs instead of past-tense when adding causal relationships?

Yes. The API accepts present-tense aliases including `CAUSES`, `INFLUENCES`, and `PRECEDES`. These are automatically normalized to their canonical forms (`CAUSED`, `INFLUENCED`, `PRECEDENT_FOR`) via the `_CAUSAL_EDGE_ALIASES` mapping at lines 438-50 of [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py).

### How do I traverse causal chains to perform root-cause analysis?

Use the `get_causal_chain()` method with `direction="upstream"` to trace dependencies backwards from a decision to its origins, or `direction="downstream"` to see all consequences. The `CausalChainAnalyzer` in [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py) provides additional analysis tools for working with these relationships.

### Where are the causal relationship types tested in the codebase?

The test suite in [`tests/030_realworld_comprehensive.py`](https://github.com/semantica-agi/semantica/blob/main/tests/030_realworld_comprehensive.py) demonstrates adding and traversing causal relationships using all supported types, providing working examples of both canonical forms and aliases in practical scenarios.