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

Semantica enforces exactly three relationship types for causal links—CAUSED, INFLUENCED, and PRECEDENT_FOR—which are centrally defined in 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 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—operate on a schema-compliant graph without invalid edge labels.

The schema definition in 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.

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:

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

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

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