# Supported Relationship Types for Causal Links in Semantica: A Complete Guide

> Explore Semantica's supported relationship types for causal links: CAUSED, INFLUENCED, and PRECEDENT_FOR. Understand how these ensure valid graph mutations.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: api-reference
- Published: 2026-09-09

---

**Semantica enforces exactly three relationship types for causal links—`CAUSED`, `INFLUENCED`, and `PRECEDENT_FOR`—which are centrally defined in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) and validated at runtime to prevent invalid graph mutations.**

The `semantica-agi/semantica` repository provides a structured knowledge graph for decision intelligence, where **supported relationship types for causal links** constrain how entities connect within the causal model. These edge types are not merely conventions; they are hard-coded constants that the graph engine uses to maintain semantic integrity during traversal and analysis operations.

## The Three Supported Causal Relationship Types

Semantica distinguishes between three levels of causal connection, each mapped to a specific string constant used when creating edges between nodes:

- **`CAUSED`** — Indicates a direct causal relationship where the source decision is the strict cause of the target decision.
- **`INFLUENCED`** — Represents an indirect connection where the source decision affected the target without being a deterministic cause.
- **`PRECEDENT_FOR`** — Denotes temporal and contextual precedence, where the source decision occurred earlier and established the conditions for the target decision.

These three values constitute the complete enumerated set of valid causal links. No other relationship strings are accepted by the graph API.

## Source Code Implementation and Validation Logic

The canonical definition resides in **[`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py)** within the private constant `_CAUSAL_EDGE_TYPES`. According to the source code at line 536, this constant enumerates the permitted values, and the `add_causal_relationship()` method validates incoming relationship parameters against this set.

Attempting to insert a causal link with an undefined relationship type immediately raises a **`ValueError`**. This validation ensures that downstream analytics—such as those performed by `CausalChainAnalyzer` in [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py)—operate on a schema-compliant graph without invalid edge labels.

The schema definition in **[`semantica/context/graph_schema.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/graph_schema.py)** further documents these labels as part of the overall Neo4j graph structure, ensuring persistence layers respect the same constraints as the in-memory implementation.

## Working with Causal Links in Python

To create causal connections, instantiate a `ContextGraph` and invoke `add_causal_relationship()` with the source node ID, target node ID, and one of the three supported type strings.

```python
from semantica.context import ContextGraph

# Initialize the knowledge graph

g = ContextGraph()

# Add causal relationships using the supported types

g.add_causal_relationship("decision_a", "decision_b", "CAUSED")
g.add_causal_relationship("decision_b", "decision_c", "INFLUENCED")
g.add_causal_relationship("decision_c", "decision_d", "PRECEDENT_FOR")

```

The following example demonstrates the validation failure triggered by unsupported relationship strings:

```python

# Raises ValueError: "RELATED_TO" is not in _CAUSAL_EDGE_TYPES

g.add_causal_relationship("decision_x", "decision_y", "RELATED_TO")

```

## Traversing Causal Chains

Once established, these relationship types enable directional queries through `get_causal_chain()`. This method respects the edge type semantics when traversing the graph, allowing you to trace downstream effects or upstream causes based on the specific causal connection.

```python

# Query downstream causal chain from decision_a

chain = g.get_causal_relationship("decision_a", direction="downstream", max_depth=5)
print(chain)  # Output: ['decision_b', 'decision_c', 'decision_d']

```

The traversal logic differentiates between the three edge types, ensuring that `INFLUENCED` relationships are weighted differently than `CAUSED` relationships during dependency analysis.

## Summary

- **Three strict types**: `CAUSED`, `INFLUENCED`, and `PRECEDENT_FOR` are the only valid causal relationship strings.
- **Centralized definition**: The `_CAUSAL_EDGE_TYPES` constant in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) serves as the single source of truth.
- **Runtime validation**: Invalid relationship types passed to `add_causal_relationship()` raise `ValueError` immediately.
- **Schema enforcement**: [`semantica/context/graph_schema.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/graph_schema.py) and [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py) rely on these types for consistent graph traversal and persistence.

## Frequently Asked Questions

### What are the exact string values for causal relationship types in Semantica?

Semantica recognizes exactly three case-sensitive strings: **`CAUSED`**, **`INFLUENCED`**, and **`PRECEDENT_FOR`**. These values are stored as constants in `_CAUSAL_EDGE_TYPES` and must be passed exactly as shown when calling `add_causal_relationship()`.

### What happens if I try to use an unsupported relationship type?

The `add_causal_relationship()` method validates the input against `_CAUSAL_EDGE_TYPES` and raises a **`ValueError`** if the string does not match one of the three supported types. This prevents corruption of the causal graph and ensures compatibility with the `CausalChainAnalyzer` traversal algorithms.

### Where is the validation for causal edge types implemented?

Validation logic is implemented in **[`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py)** at line 536, where the `_CAUSAL_EDGE_TYPES` constant is defined and checked. The same type constraints are reflected in **[`semantica/context/graph_schema.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/graph_schema.py)**, which governs how these edges are persisted in Neo4j-backed deployments.

### How do I query downstream effects using these relationship types?

Use the `get_causal_chain()` method on a `ContextGraph` instance, specifying `direction="downstream"` and an optional `max_depth` parameter. This method traverses all three causal edge types (`CAUSED`, `INFLUENCED`, `PRECEDENT_FOR`) to reconstruct the dependency chain originating from a specific decision node.