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

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. 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:

• 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.

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 and supports both downstream and upstream traversal.

To retrieve a downstream causal chain:

# 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:

# 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 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, 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 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.

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 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 demonstrates adding and traversing causal relationships using all supported types, providing working examples of both canonical forms and aliases in practical scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}