Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
fix(context): support direction="both" in get_causal_chain (#1958)
John Costacfba14bf18cd
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 stepdiff --git a/docs/guides/mcp-server.md b/docs/guides/mcp-server.mdindex 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.mdindex 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.pyindex 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 depthReturns:diff --git a/semantica/context/causal_analyzer.py b/semantica/context/causal_analyzer.pyindex 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 usinggraph 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 directionif direction == "upstream":diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.pyindex 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 traversalvisited = set()queue = deque([(decision_id, 0)])diff --git a/semantica/context/decision_methods.py b/semantica/context/decision_methods.pyindex 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 instancedecision_id: Decision ID to analyze- direction: "upstream" or "downstream"+ direction: "upstream", "downstream" or "both"max_depth: Maximum traversal depthReturns:diff --git a/semantica/mcp_server/__init__.py b/semantica/mcp_server/__init__.pyindex 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.mdindex 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.pyindex 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.pyindex 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) == 1assert 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.pyindex 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"] == 1assert 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.pyindex 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 datetimediff --git a/tests/test_mcp_server_causal_chain.py b/tests/test_mcp_server_causal_chain.pyindex 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: