Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(context): support direction="both" in get_causal_chain (#1958)

John Costacfba14bf18cd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4bd565e6..b4d8f2bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- A per-call `model=` is recorded when it is a string that names a model — its `strip()` is not empty — and it is recorded as given. Every other value falls back to the constructor's model, the way a call that passes no model at all does: absent, `None`, a value that is not a string, an empty string and a whitespace-only string all name no model and are never recorded as one. A value that is not a string is dropped before it reaches the metadata, so it can no longer make the storage layer fail to serialize the entry and lose the write altogether
- No other recorded field changes: the token counts, the cost, the latency, the activity times and the previews are what they were
- New tests in `tests/provenance/test_llms_provenance_tracking.py` cover the override, the fallback for every value that names no model, the structured and typed paths and a direct call to the recorder, on every wrapper; one test writes through a real `ProvenanceManager` over sqlite to prove the entry is stored
+- **`get_causal_chain` rejected `direction="both"`, which the MCP tool schema advertises** (fixes #1815) by @costajohnt
+ - `ContextGraph.get_causal_chain` and `CausalChainAnalyzer.get_causal_chain` now accept `"both"` and return the upstream chain followed by the downstream one, each walked up to `max_depth`. Causes come farthest first and effects nearest first on both backends, each decision is listed once (the nearest copy within each direction; a decision reachable both ways is listed as upstream) and carries `metadata["causal_direction"]`. The MCP `get_causal_chain` tool (and the legacy `semantica.mcp_server` one, whose schema now lists `"both"`) no longer errors for this value.
- **`semantica pipeline validate` reported a partly malformed file valid, and `--json` had no structured result** (fixes #2026) by @ALDRIN121
- `PipelineBuilder.build_pipeline()` keeps a step only when both `name` and `type` are truthy, so a half-written step was dropped before the validator saw it and the file was reported valid. `_load_pipeline_file()` now checks every entry while the index is still known and rejects the file, naming the offending one (`steps[1] ('broken') is missing a non-empty 'type'`). A step that is not a mapping used to reach `dict()` inside `deserialize_pipeline()` and surface as `dictionary update sequence element #0 has length 1; 2 is required`; it is now reported as `steps[0] is not a mapping (got str)`. `pipeline run` loads through the same helper, so it no longer executes a pipeline that is silently missing a step
diff --git a/docs/guides/mcp-server.md b/docs/guides/mcp-server.md
index db22256a..c6b227c1 100644
--- a/docs/guides/mcp-server.md
+++ b/docs/guides/mcp-server.md
@@ -142,7 +142,7 @@ Once connected, the LLM can call any of these tools during a conversation. The a
**Live graph queries and edits.** `query_graph` reads the graph without exporting it: fetch one node, walk its neighbours up to five hops, or keyword-search nodes. `update_node` merges properties onto an existing node (for example marking a task node `done`), and `delete_node` archives a node it no longer tracks. When `SEMANTICA_KG_PATH` is set, `update_node` and `delete_node` write their changes back to that file so they survive a restart.
-**Decision intelligence.** `record_decision` writes a decision as a provenance node with confidence score, reasoning, and decision maker identity. `query_decisions` retrieves past decisions by query or category. `find_precedents` finds the most similar past decisions by semantic similarity. `get_causal_chain` traces decision causality upstream or downstream.
+**Decision intelligence.** `record_decision` writes a decision as a provenance node with confidence score, reasoning, and decision maker identity. `query_decisions` retrieves past decisions by query or category. `find_precedents` finds the most similar past decisions by semantic similarity. `get_causal_chain` traces decision causality upstream, downstream or both.
**Reasoning.** `run_reasoning` applies forward-chaining IF/THEN rules over a set of facts and returns derived conclusions.
diff --git a/docs/reference/mcp_server.md b/docs/reference/mcp_server.md
index 954aff70..4cb9d73a 100644
--- a/docs/reference/mcp_server.md
+++ b/docs/reference/mcp_server.md
@@ -306,7 +306,7 @@ Find past decisions similar to a given scenario using hybrid similarity search.
<Accordion title="get_causal_chain" icon="diagram-project">
-Trace the causal chain upstream or downstream from a decision.
+Trace the causal chain upstream, downstream or both from a decision.
**Input:**
@@ -314,7 +314,7 @@ Trace the causal chain upstream or downstream from a decision.
{ "decision_id": "dec_a1b2c3", "direction": "downstream", "max_depth": 5 }
```
-`direction` accepts `"upstream"` or `"downstream"` (default: `"downstream"`).
+`direction` accepts `"upstream"`, `"downstream"` or `"both"` (default: `"downstream"`). With `"both"`, the result lists the causes (farthest first) and then the effects (nearest first); each decision appears once and carries `metadata.causal_direction`.
`max_depth` defaults to `5`, maximum `20`.
</Accordion>
diff --git a/semantica/context/agent_context.py b/semantica/context/agent_context.py
index 941ef5e2..d714b833 100644
--- a/semantica/context/agent_context.py
+++ b/semantica/context/agent_context.py
@@ -2032,7 +2032,7 @@ class AgentContext:
Args:
decision_id: Decision ID to analyze
- direction: "upstream" (causes) or "downstream" (effects)
+ direction: "upstream" (causes), "downstream" (effects) or "both"
max_depth: Maximum traversal depth
Returns:
diff --git a/semantica/context/causal_analyzer.py b/semantica/context/causal_analyzer.py
index b7f2edf6..9d396e11 100644
--- a/semantica/context/causal_analyzer.py
+++ b/semantica/context/causal_analyzer.py
@@ -5,7 +5,7 @@ Analyzes decision causality, influence chains, and precedent relationships using
graph traversal and advanced analytics.
Key Features:
- - Causal chain tracing (upstream/downstream)
+ - Causal chain tracing (upstream, downstream or both)
- Decision influence analysis and scoring
- Precedent relationship mapping
- Multi-directional causality analysis
@@ -100,9 +100,14 @@ class CausalChainAnalyzer:
Args:
decision_id: Starting decision ID
- direction: "upstream" (what caused this) or "downstream" (what this caused)
- max_depth: Maximum traversal depth
-
+ direction: "upstream" (what caused this), "downstream" (what this caused)
+ or "both" (the upstream chain followed by the downstream one, each
+ decision listed once and tagged with metadata["causal_direction"]).
+ With "both", causes come farthest first and effects nearest first,
+ matching ContextGraph. A plain "upstream" query against a graph
+ store returns nearest first; ContextGraph returns it farthest first.
+ max_depth: Maximum traversal depth, per direction
+
Returns:
List of decisions in causal chain
"""
@@ -117,8 +122,29 @@ class CausalChainAnalyzer:
if not (1 <= max_depth <= 100):
raise ValueError("max_depth must be between 1 and 20")
+ if direction == "both":
+ # Each query returns nearest first, so within a side the first
+ # copy is the nearest; a decision reachable both ways is kept as
+ # upstream.
+ chain, seen = [], set()
+ for side in ("upstream", "downstream"):
+ for d in self.get_causal_chain(decision_id, side, max_depth):
+ if d.decision_id not in seen:
+ seen.add(d.decision_id)
+ d.metadata["causal_direction"] = side
+ chain.append(d)
+ # Causes farthest first, then effects nearest first, as
+ # ContextGraph.get_causal_chain orders them.
+ n_up = sum(d.metadata["causal_direction"] == "upstream" for d in chain)
+ chain[:n_up] = sorted(
+ chain[:n_up],
+ key=lambda d: d.metadata.get("causal_distance", 0),
+ reverse=True,
+ )
+ return chain
+
if direction not in ["upstream", "downstream"]:
- raise ValueError("Direction must be 'upstream' or 'downstream'")
+ raise ValueError("Direction must be 'upstream', 'downstream' or 'both'")
# Define relationship direction based on traversal direction
if direction == "upstream":
diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.py
index 935a4187..4ea567c5 100644
--- a/semantica/context/context_graph.py
+++ b/semantica/context/context_graph.py
@@ -4013,17 +4013,29 @@ class ContextGraph:
Args:
decision_id: Starting decision ID
- direction: "upstream" or "downstream"
- max_depth: Maximum traversal depth
-
+ direction: "upstream", "downstream" or "both" (the upstream
+ chain followed by the downstream one, each decision listed
+ once and tagged with metadata["causal_direction"])
+ max_depth: Maximum traversal depth, per direction
+
Returns:
List of decisions in causal chain
"""
from .decision_models import Decision
-
+
+ if direction == "both":
+ chain, seen = [], set()
+ for side in ("upstream", "downstream"):
+ for d in self.get_causal_chain(decision_id, side, max_depth):
+ if d.decision_id not in seen:
+ seen.add(d.decision_id)
+ d.metadata["causal_direction"] = side
+ chain.append(d)
+ return chain
+
if direction not in ["upstream", "downstream"]:
- raise ValueError("Direction must be 'upstream' or 'downstream'")
-
+ raise ValueError("Direction must be 'upstream', 'downstream' or 'both'")
+
# BFS traversal
visited = set()
queue = deque([(decision_id, 0)])
diff --git a/semantica/context/decision_methods.py b/semantica/context/decision_methods.py
index e76872dc..07c64327 100644
--- a/semantica/context/decision_methods.py
+++ b/semantica/context/decision_methods.py
@@ -134,7 +134,7 @@ def get_causal_chain(
Args:
graph_store: Graph database instance
decision_id: Decision ID to analyze
- direction: "upstream" or "downstream"
+ direction: "upstream", "downstream" or "both"
max_depth: Maximum traversal depth
Returns:
diff --git a/semantica/mcp_server/__init__.py b/semantica/mcp_server/__init__.py
index 4a360a30..09a91fd2 100644
--- a/semantica/mcp_server/__init__.py
+++ b/semantica/mcp_server/__init__.py
@@ -782,12 +782,12 @@ TOOLS = [
},
{
"name": "get_causal_chain",
- "description": "Trace the causal chain upstream or downstream from a decision.",
+ "description": "Trace the causal chain upstream, downstream or both from a decision.",
"inputSchema": {
"type": "object",
"properties": {
"decision_id": {"type": "string", "description": "Decision ID to trace"},
- "direction": {"type": "string", "enum": ["upstream", "downstream"], "description": "Trace direction"},
+ "direction": {"type": "string", "enum": ["upstream", "downstream", "both"], "description": "Trace direction"},
"max_depth": {"type": "integer", "description": "Max chain depth (default 5)"},
},
"required": ["decision_id"],
diff --git a/semantica_mcp/mcp/README.md b/semantica_mcp/mcp/README.md
index bc78c692..967f97e0 100644
--- a/semantica_mcp/mcp/README.md
+++ b/semantica_mcp/mcp/README.md
@@ -48,7 +48,7 @@ python -m mcp [--debug]
| `record_decision` | Record a decision with context, confidence, causal links |
| `query_decisions` | Query decisions by natural language or structured filters |
| `find_precedents` | Find past decisions similar to a scenario (hybrid similarity) |
-| `get_causal_chain` | Trace upstream/downstream causal chain from a decision |
+| `get_causal_chain` | Trace the upstream, downstream or both causal chains from a decision |
| `analyze_decision_impact` | Analyse downstream influence of a decision |
| `link_decisions` | Create a causal relationship (CAUSED, INFLUENCED, PRECEDENT_FOR) between two decisions |
diff --git a/semantica_mcp/mcp/tools/decisions.py b/semantica_mcp/mcp/tools/decisions.py
index 83dc3778..219f9933 100644
--- a/semantica_mcp/mcp/tools/decisions.py
+++ b/semantica_mcp/mcp/tools/decisions.py
@@ -171,7 +171,7 @@ def handle_find_precedents(args: dict) -> dict:
def handle_get_causal_chain(args: dict) -> dict:
- """Trace the upstream or downstream causal chain from a decision."""
+ """Trace the upstream, downstream or both causal chains from a decision."""
if not isinstance(args, dict):
return {"error": "args must be a dictionary", "chain": []}
decision_id = str(args.get("decision_id") or "").strip()
@@ -392,7 +392,7 @@ DECISION_TOOLS = [
},
{
"name": "get_causal_chain",
- "description": "Trace the causal chain upstream or downstream from a recorded decision.",
+ "description": "Trace the causal chain upstream, downstream or both from a recorded decision.",
"inputSchema": GET_CAUSAL_CHAIN,
"_handler": handle_get_causal_chain,
},
diff --git a/tests/context/test_causal_analyzer.py b/tests/context/test_causal_analyzer.py
index 8d1f3403..9d4856e9 100644
--- a/tests/context/test_causal_analyzer.py
+++ b/tests/context/test_causal_analyzer.py
@@ -129,9 +129,52 @@ class TestCausalChainAnalyzer:
assert len(chain) == 1
assert chain[0].decision_id == "decision_002"
+ def test_get_causal_chain_both_merges_both_queries(self, causal_analyzer, mock_graph_store):
+ """direction="both" runs the upstream and downstream queries and merges them (#1815)."""
+
+ def record(decision_id, distance):
+ return {
+ "decision_id": decision_id,
+ "category": "credit_approval",
+ "scenario": decision_id,
+ "reasoning": "",
+ "outcome": "approved",
+ "confidence": 0.9,
+ "timestamp": datetime.now().isoformat(),
+ "decision_maker": "ai_agent_001",
+ "distance": distance,
+ }
+
+ # Query results come nearest first, as RETURN DISTINCT end, length(path)
+ # ... ORDER BY distance gives them; a decision reached by two paths of
+ # different length comes back twice.
+ mock_graph_store.execute_query.side_effect = [
+ [
+ record("decision_001", 1),
+ record("decision_000", 2),
+ record("decision_000", 3), # same cause by a longer path
+ ], # upstream
+ [record("decision_003", 1), record("decision_001", 2)], # downstream, with a cycle
+ ]
+
+ chain = causal_analyzer.get_causal_chain("decision_002", "both", 5)
+
+ # Causes farthest first (as ContextGraph orders them), then effects;
+ # every decision once; within a side the nearest copy is kept, and a
+ # decision reachable both ways is listed as upstream.
+ assert [d.decision_id for d in chain] == ["decision_000", "decision_001", "decision_003"]
+ assert [d.metadata["causal_distance"] for d in chain] == [2, 1, 1]
+ assert [d.metadata["causal_direction"] for d in chain] == [
+ "upstream", "upstream", "downstream"
+ ]
+ queries = [call.args[0] for call in mock_graph_store.execute_query.call_args_list]
+ assert len(queries) == 2
+ assert "<-[:CAUSED" in queries[0]
+ assert "]->" in queries[1]
+
def test_get_causal_chain_invalid_direction(self, causal_analyzer):
"""Test causal chain retrieval with invalid direction."""
- with pytest.raises(ValueError, match="Direction must be 'upstream' or 'downstream'"):
+ with pytest.raises(ValueError, match="Direction must be 'upstream', 'downstream' or 'both'"):
causal_analyzer.get_causal_chain("decision_001", "invalid", 5)
def test_get_causal_chain_invalid_max_depth(self, causal_analyzer):
diff --git a/tests/context/test_context_graph_decisions.py b/tests/context/test_context_graph_decisions.py
index 6cf110f9..e3537f3c 100644
--- a/tests/context/test_context_graph_decisions.py
+++ b/tests/context/test_context_graph_decisions.py
@@ -233,10 +233,70 @@ class TestContextGraphDecisions:
assert chain[1].decision_id == "decision_003"
assert chain[0].metadata["causal_distance"] == 1
assert chain[1].metadata["causal_distance"] == 2
-
+
+ def test_get_causal_chain_both(self, context_graph):
+ """direction="both" returns the upstream chain, then the downstream one (#1815)."""
+ # decision_001 -> decision_002 -> decision_003 -> decision_004
+ for i in range(1, 5):
+ context_graph.add_decision(
+ Decision(
+ decision_id=f"decision_{i:03d}",
+ category="test",
+ scenario=f"scenario {i}",
+ reasoning=f"reasoning {i}",
+ outcome="approved",
+ confidence=0.8,
+ timestamp=datetime.now() - timedelta(hours=i),
+ decision_maker="test_agent",
+ )
+ )
+ for i in range(1, 4):
+ context_graph.add_causal_relationship(
+ f"decision_{i:03d}", f"decision_{i + 1:03d}", "CAUSED"
+ )
+
+ chain = context_graph.get_causal_chain("decision_002", direction="both", max_depth=5)
+
+ assert [d.decision_id for d in chain] == ["decision_001", "decision_003", "decision_004"]
+ assert [d.metadata["causal_distance"] for d in chain] == [1, 1, 2]
+ assert [d.metadata["causal_direction"] for d in chain] == [
+ "upstream", "downstream", "downstream"
+ ]
+
+ # max_depth applies to each direction.
+ chain = context_graph.get_causal_chain("decision_002", direction="both", max_depth=1)
+ assert [d.decision_id for d in chain] == ["decision_001", "decision_003"]
+
+ def test_get_causal_chain_both_lists_a_decision_once(self, context_graph):
+ """A decision reachable both ways (a cycle) appears once, as upstream."""
+ # decision_001 -> decision_002 -> decision_003 -> decision_001
+ for i in (1, 2, 3):
+ context_graph.add_decision(
+ Decision(
+ decision_id=f"decision_{i:03d}",
+ category="test",
+ scenario=f"scenario {i}",
+ reasoning=f"reasoning {i}",
+ outcome="approved",
+ confidence=0.8,
+ timestamp=datetime.now(),
+ decision_maker="test_agent",
+ )
+ )
+ context_graph.add_causal_relationship("decision_001", "decision_002", "CAUSED")
+ context_graph.add_causal_relationship("decision_002", "decision_003", "CAUSED")
+ context_graph.add_causal_relationship("decision_003", "decision_001", "INFLUENCED")
+
+ chain = context_graph.get_causal_chain("decision_001", direction="both", max_depth=5)
+
+ # Upstream distances (2, 1), not the downstream ones (1, 2).
+ assert [d.decision_id for d in chain] == ["decision_002", "decision_003"]
+ assert [d.metadata["causal_distance"] for d in chain] == [2, 1]
+ assert {d.metadata["causal_direction"] for d in chain} == {"upstream"}
+
def test_get_causal_chain_invalid_direction(self, context_graph):
"""Test getting causal chain with invalid direction."""
- with pytest.raises(ValueError, match="Direction must be 'upstream' or 'downstream'"):
+ with pytest.raises(ValueError, match="Direction must be 'upstream', 'downstream' or 'both'"):
context_graph.get_causal_chain("decision_001", "invalid", 5)
def test_get_causal_chain_max_depth(self, context_graph):
diff --git a/tests/test_mcp_decisions_causal_chain.py b/tests/test_mcp_decisions_causal_chain.py
index 8b63c3b2..2c96c1cb 100644
--- a/tests/test_mcp_decisions_causal_chain.py
+++ b/tests/test_mcp_decisions_causal_chain.py
@@ -312,6 +312,15 @@ class TestCausalChainSerializationWithRealGraph(unittest.TestCase):
{"Require BAA from vendors": 1, "Host on AWS": 2},
)
+ def test_both_directions_round_trip_through_tools_call(self):
+ # The schema advertises "both"; the engine used to reject it (#1815).
+ payload = self._tools_call({"decision_id": self.ids[1], "direction": "both"})
+ self.assertNotIn("error", payload)
+ self.assertEqual(
+ [(d["scenario"], d["metadata"]["causal_direction"]) for d in payload["chain"]],
+ [("Adopt HIPAA program", "upstream"), ("Host on AWS", "downstream")],
+ )
+
def test_non_json_metadata_is_stringified(self):
from datetime import datetime
diff --git a/tests/test_mcp_server_causal_chain.py b/tests/test_mcp_server_causal_chain.py
index 2186fa66..422b6438 100644
--- a/tests/test_mcp_server_causal_chain.py
+++ b/tests/test_mcp_server_causal_chain.py
@@ -80,6 +80,14 @@ class TestGetCausalChainTool(unittest.TestCase):
{"Require BAA from vendors": 1, "Host on AWS": 2},
)
+ def test_both_directions(self):
+ # The legacy schema lists "both" too (#1815).
+ chain = self._call(decision_id=self.ids[1], direction="both")
+ self.assertEqual(
+ [(d["scenario"], d["metadata"]["causal_direction"]) for d in chain],
+ [("Adopt HIPAA program", "upstream"), ("Host on AWS", "downstream")],
+ )
+
def test_entries_are_plain_decision_dicts(self):
chain = self._call(decision_id=self.ids[2], direction="upstream")
for entry in chain: