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
docs(context): fix unrunnable ContextGraph docstring example (#921)
pravit-amp5c2901ae2700
diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.pyindex 28b431ef..ad6ecf3f 100644--- a/semantica/context/context_graph.py+++ b/semantica/context/context_graph.py@@ -72,9 +72,9 @@ Example Usage:... node_embeddings=True)>>>>>> # Basic graph operations- >>> graph.add_node("Python", type="language", properties={"popularity": "high"})- >>> graph.add_node("Programming", type="concept")- >>> graph.add_edge("Python", "Programming", type="related_to")+ >>> graph.add_node("Python", "language", popularity="high")+ >>> graph.add_node("Programming", "concept")+ >>> graph.add_edge("Python", "Programming", "related_to")>>> centrality = graph.get_node_centrality("Python")>>> similar = graph.find_similar_nodes("Python", similarity_type="content")>>> analysis = graph.analyze_graph_with_kg()@@ -88,7 +88,7 @@ Example Usage:... confidence=0.95,... entities=["customer_123", "property_456"]... )- >>> precedents = graph.find_precedents("loan_approval", limit=5)+ >>> precedents = graph.find_precedents(decision_id, limit=5)>>> influence = graph.analyze_decision_influence(decision_id)>>> insights = graph.get_decision_insights()>>> causality = graph.trace_decision_causality(decision_id)diff --git a/tests/context/test_context_graph_docstring_example.py b/tests/context/test_context_graph_docstring_example.pynew file mode 100644index 00000000..8dcd4039--- /dev/null+++ b/tests/context/test_context_graph_docstring_example.py@@ -0,0 +1,142 @@+#!/usr/bin/env python3+"""Regression tests for the ContextGraph module docstring example.++The "Example Usage" block in ``semantica/context/context_graph.py`` previously+called ``add_node``/``add_edge`` with keyword arguments those methods do not+accept (``type=`` and ``properties=``), so the documented example raised+``TypeError`` -- and the near-miss variants silently nested the properties dict+instead of failing.++These tests keep the documented example executable and pin the two behaviours+that made the original mistake easy to miss.+"""++import doctest+import re+from typing import Dict, List++import pytest++import semantica.context.context_graph as context_graph_module+from semantica.context.context_graph import ContextGraph++# The example block runs to the next top-level section header (a line starting+# in column 0, e.g. "Production Use Cases:") or the end of the docstring.+# Terminating on the next header rather than on a blank line keeps the capture+# intact when the example gains blank lines or extra paragraphs.+_EXAMPLE_BLOCK_RE = re.compile(r"^Example Usage:\n(.*?)(?=^\S|\Z)", re.DOTALL | re.MULTILINE)++# ``type=`` as its own keyword, but not the legitimate ``node_type=``/``edge_type=``.+_BARE_TYPE_KWARG_RE = re.compile(r"(?<![\w])type\s*=")+++def _example_block() -> str:+ """Return the 'Example Usage' block from the module docstring."""+ doc = context_graph_module.__doc__ or ""+ match = _EXAMPLE_BLOCK_RE.search(doc)+ assert match, "module docstring no longer contains an 'Example Usage:' block"+ block = match.group(1).strip()+ assert block, "the 'Example Usage:' block in the module docstring is empty"+ return block+++def _example_statements() -> List[str]:+ """Return the documented ``>>>`` statements, continuation lines included."""+ statements = [example.source for example in doctest.DocTestParser().get_examples(_example_block())]+ assert statements, "the 'Example Usage:' block no longer contains any '>>>' statements"+ return statements+++def _statements_calling(method: str) -> List[str]:+ """Return the documented statements that call ``graph.<method>(``."""+ return [stmt for stmt in _example_statements() if "graph.{}(".format(method) in stmt]+++def _run_example() -> Dict[str, object]:+ """Execute the documented example verbatim and return its namespace."""+ source = "".join(_example_statements())+ namespace: Dict[str, object] = {}+ exec(compile(source, "<context_graph module docstring>", "exec"), namespace)+ return namespace+++class TestDocstringExampleIsRunnable:+ """The documented example must execute exactly as written."""++ def test_documented_calls_execute(self):+ # Run the docstring text itself so this test cannot drift from the docs.+ ns = _run_example()+ graph = ns["graph"]++ assert "Python" in graph.nodes+ assert "Programming" in graph.nodes+ assert graph.nodes["Python"].node_type == "language"+ assert graph.nodes["Programming"].node_type == "concept"++ neighbors = graph.get_neighbors("Python", hops=1)+ assert any(n["id"] == "Programming" for n in neighbors)++ # record_decision must return a non-empty string ID.+ assert isinstance(ns["decision_id"], str) and ns["decision_id"]+ # find_precedents must be called with that ID and return a list.+ assert isinstance(ns["precedents"], list)++ def test_node_properties_are_stored_flat(self):+ """``popularity`` must land as a top-level property, not nested.++ Passing the previously documented ``properties={...}`` does not raise --+ it stores a dict *inside* the properties dict, which is why the original+ docs bug could reach a user's graph unnoticed.+ """+ graph = ContextGraph(advanced_analytics=False)+ graph.add_node("Python", "language", popularity="high")++ assert graph.nodes["Python"].properties == {"popularity": "high"}+ assert graph.find_node("Python")["metadata"]["popularity"] == "high"+ assert "properties" not in graph.nodes["Python"].properties++ def test_edge_type_is_positional_not_a_property(self):+ """``related_to`` must be the edge type, not a stray metadata key."""+ graph = ContextGraph(advanced_analytics=False)+ graph.add_node("Python", "language")+ graph.add_node("Programming", "concept")+ graph.add_edge("Python", "Programming", "related_to")++ edge = graph.edges[0]+ assert edge.edge_type == "related_to"+ assert "type" not in edge.metadata+++class TestDocstringExampleDoesNotRegress:+ """Guard the docstring text itself, not just equivalent code."""++ def test_add_node_example_supplies_node_type_positionally(self):+ calls = _statements_calling("add_node")+ assert calls, "the 'Example Usage:' block no longer calls graph.add_node()"+ for call in calls:+ assert not _BARE_TYPE_KWARG_RE.search(call), (+ f"add_node example passes type= as a keyword: {call!r}. "+ "node_type is positional-required; type= falls through to "+ "**properties and the call raises TypeError."+ )+ assert "properties=" not in call, (+ f"add_node example passes properties=: {call!r}. "+ "add_node has no properties parameter; extra properties are "+ "passed as **kwargs."+ )++ def test_add_edge_example_supplies_edge_type_positionally(self):+ calls = _statements_calling("add_edge")+ assert calls, "the 'Example Usage:' block no longer calls graph.add_edge()"+ for call in calls:+ assert not _BARE_TYPE_KWARG_RE.search(call), (+ f"add_edge example passes type= as a keyword: {call!r}. "+ "The parameter is edge_type; type= is silently absorbed into "+ "**properties and pollutes edge metadata."+ )++ def test_broken_form_still_raises(self):+ """Pin the signature contract the example has to respect."""+ graph = ContextGraph(advanced_analytics=False)+ with pytest.raises(TypeError, match="node_type"):+ graph.add_node("Python", type="language", properties={"popularity": "high"})