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(export): keep backend endpoint names in LPG relationship export (#2058)
Tymur0747f53d7e57
diff --git a/semantica/export/endpoint_names.py b/semantica/export/endpoint_names.pyindex 95c0b17b..e6274ff2 100644--- a/semantica/export/endpoint_names.py+++ b/semantica/export/endpoint_names.py@@ -49,6 +49,15 @@ ENDPOINT_ALIASES: Dict[str, Tuple[str, ...]] = {}+def is_unset_id(value: Any) -> bool:+ """Whether an id value counts as missing: ``None`` or ``""`` (#2018).++ A reader then tries the next accepted name. Anything else, ``0`` included,+ is a real id.+ """+ return value is None or value == ""++def has_endpoints(sample: Dict[str, Any]) -> bool:"""Whether a record carries both ends of a relationship, under any name."""return any(k in sample for k in SOURCE_ENDPOINT_NAMES) and any(@@ -60,8 +69,11 @@ def canonical_endpoints(records: Any) -> Any:"""Return ``records`` with relationship endpoints under their canonical keys.Records that already carry ``source_id``/``target_id`` are returned- untouched, as are non-dict records. The original list is returned when- nothing needed adding, so callers that pass a canonical graph pay nothing.+ untouched, as are non-dict records. An unset canonical value (see+ ``is_unset_id``) takes the first set alias, so ``source_id=""`` next to+ ``start_node_id="alice"`` becomes ``source_id="alice"``. The original list+ is returned when nothing needed adding, so callers that pass a canonical+ graph pay nothing."""if not isinstance(records, list):return records@@ -75,10 +87,10 @@ def canonical_endpoints(records: Any) -> Any:resolved: Dict[str, Any] = {}for canonical, aliases in ENDPOINT_ALIASES.items():- if record.get(canonical) is not None:+ if not is_unset_id(record.get(canonical)):continuefor alias in aliases:- if record.get(alias) is not None:+ if not is_unset_id(record.get(alias)):resolved[canonical] = record[alias]breakdiff --git a/semantica/export/lpg_exporter.py b/semantica/export/lpg_exporter.pyindex 06ac4554..3ec9ac19 100644--- a/semantica/export/lpg_exporter.py+++ b/semantica/export/lpg_exporter.py@@ -27,6 +27,7 @@ from ..utils.exceptions import ProcessingError, ValidationErrorfrom ..utils.helpers import _require_mapping, ensure_directory, normalize_graph_payloadfrom ..utils.logging import get_loggerfrom ..utils.progress_tracker import get_progress_tracker+from .endpoint_names import SOURCE_ENDPOINT_NAMES, TARGET_ENDPOINT_NAMES, is_unset_idclass LPGExporter:@@ -233,7 +234,14 @@ class LPGExporter:lines = []for idx, node in enumerate(nodes):- node_id = node.get("id") or node.get("entity_id", f"node_{idx}")+ node_id = next(+ (+ node[key]+ for key in ("id", "entity_id")+ if not is_unset_id(node.get(key))+ ),+ f"node_{idx}",+ )node_type = node.get("type") or node.get("entity_type", "Entity")label = node.get("label") or node.get("name") or node.get("text", "")@@ -285,11 +293,25 @@ class LPGExporter:lines = []for idx, edge in enumerate(edges):- source_id = edge.get("source") or edge.get("source_id")- target_id = edge.get("target") or edge.get("target_id")+ source_id = next(+ (+ edge[key]+ for key in SOURCE_ENDPOINT_NAMES+ if not is_unset_id(edge.get(key))+ ),+ None,+ )+ target_id = next(+ (+ edge[key]+ for key in TARGET_ENDPOINT_NAMES+ if not is_unset_id(edge.get(key))+ ),+ None,+ )rel_type = edge.get("type") or edge.get("relationship_type", "RELATED_TO")- if not source_id or not target_id:+ if source_id is None or target_id is None:continue# Escape special characters@@ -301,10 +323,8 @@ class LPGExporter:properties = {}for key, value in edge.items():if key not in [- "source",- "source_id",- "target",- "target_id",+ *SOURCE_ENDPOINT_NAMES,+ *TARGET_ENDPOINT_NAMES,"type","relationship_type",]:diff --git a/tests/export/test_endpoint_names_empty_values.py b/tests/export/test_endpoint_names_empty_values.pynew file mode 100644index 00000000..01049a21--- /dev/null+++ b/tests/export/test_endpoint_names_empty_values.py@@ -0,0 +1,105 @@+"""``None`` and ``""`` endpoint values count as unset in ``endpoint_names`` (#2018).++An empty ``source_id`` next to a backend name such as ``start_node_id`` used to+stay empty, so ``export_knowledge_graph`` wrote blank endpoints to JSON, a+``None`` subject and object to Turtle, and raised for Parquet.+"""++import json++import pytest++from semantica.export.endpoint_names import canonical_endpoints, is_unset_id+from semantica.export.methods import export_knowledge_graph++BACKEND_EDGE = {+ "id": "r1",+ "source_id": "",+ "target_id": "",+ "start_node_id": "alice",+ "end_node_id": "acme",+ "type": "WORKS_AT",+}+++def _graph():+ return {+ "entities": [+ {"id": "alice", "type": "Person", "text": "Alice"},+ {"id": "acme", "type": "Org", "text": "Acme"},+ ],+ "relationships": [dict(BACKEND_EDGE)],+ }+++ "value, unset",+ [(None, True), ("", True), (0, False), ("0", False), ("alice", False)],+)+def test_is_unset_id(value, unset):+ assert is_unset_id(value) is unset++[email protected]("empty", [None, ""])+def test_unset_canonical_endpoint_takes_the_backend_name(empty):+ edge = {**BACKEND_EDGE, "source_id": empty, "target_id": empty}++ [out] = canonical_endpoints([edge])++ assert (out["source_id"], out["target_id"]) == ("alice", "acme")+++def test_empty_alias_defers_to_the_next_alias():+ edge = {"source": "", "start_node_id": "alice", "target": "", "end_id": "acme"}++ [out] = canonical_endpoints([edge])++ assert (out["source_id"], out["target_id"]) == ("alice", "acme")+++ "edge",+ [+ {"source_id": 0, "start_node_id": "x", "target_id": "acme"},+ {"source_id": "", "target_id": ""},+ ],+)+def test_records_without_a_set_alias_are_returned_as_given(edge):+ records = [edge]++ assert canonical_endpoints(records) is records+++def test_json_export_writes_the_backend_endpoints(tmp_path):+ target = tmp_path / "kg.json"++ export_knowledge_graph(_graph(), str(target), format="json")++ [rel] = json.loads(target.read_text(encoding="utf-8"))["relationships"]+ assert (rel["source_id"], rel["target_id"]) == ("alice", "acme")+++def test_turtle_export_links_the_two_entities(tmp_path):+ pytest.importorskip("rdflib", reason="the RDF writer needs rdflib")+ target = tmp_path / "kg.ttl"++ export_knowledge_graph(_graph(), str(target))++ body = target.read_text(encoding="utf-8")+ assert "ns#None" not in body+ assert (+ "ns#alice> <https://semantica.dev/ns#WORKS_AT> <https://semantica.dev/ns#acme>"+ in body+ )+++def test_parquet_export_keeps_the_relationship(tmp_path):+ pytest.importorskip("pyarrow", reason="the parquet writer needs pyarrow")+ import pyarrow.parquet as pq++ export_knowledge_graph(_graph(), str(tmp_path / "kg.parquet"))++ table = pq.read_table(tmp_path / "kg_relationships.parquet")+ assert table.select(["source_id", "target_id"]).to_pylist() == [+ {"source_id": "alice", "target_id": "acme"}+ ]diff --git a/tests/export/test_lpg_exporter_endpoint_names.py b/tests/export/test_lpg_exporter_endpoint_names.pynew file mode 100644index 00000000..05e097ad--- /dev/null+++ b/tests/export/test_lpg_exporter_endpoint_names.py@@ -0,0 +1,131 @@+"""LPG exports must retain relationships whose endpoints use backend names."""++from copy import deepcopy++import pytest++from semantica.export import LPGExporter+++def _export(tmp_path, records, vocabulary=("entities", "relationships")):+ path = tmp_path / "graph.cypher"+ graph = {+ vocabulary[0]: [{"id": "alice"}, {"id": "acme"}],+ vocabulary[1]: records,+ }+ LPGExporter(include_indexes=False).export(graph, path)+ return path.read_text(encoding="utf-8")+++ "vocabulary", [("entities", "relationships"), ("nodes", "edges")]+)+ "source_key, target_key",+ [+ ("source_id", "target_id"),+ ("source", "target"),+ ("start_node_id", "end_node_id"),+ ("start_id", "end_id"),+ ],+)+def test_export_retains_relationship_for_each_endpoint_spelling(+ tmp_path, vocabulary, source_key, target_key+):+ record = {+ "id": "r1",+ source_key: "alice",+ target_key: "acme",+ "type": "WORKS_AT",+ "weight": 0.5,+ }+ original = deepcopy(record)++ text = _export(tmp_path, [record], vocabulary)++ assert text.count("CREATE (a)-[") == 1+ assert (+ "MATCH (a {id: 'alice'}), (b {id: 'acme'}) "+ "CREATE (a)-[r:WORKS_AT {id: 'r1', weight: 0.5}]->(b);"+ ) in text+ assert record == original+++def test_export_retains_mixed_endpoint_spellings(tmp_path):+ text = _export(+ tmp_path,+ [+ {"source": "alice", "target_id": "acme", "type": "FIRST"},+ {"start_node_id": "acme", "end_id": "alice", "type": "SECOND"},+ ],+ )++ assert text.count("CREATE (a)-[") == 2+ assert "CREATE (a)-[r:FIRST]->(b);" in text+ assert "CREATE (a)-[r:SECOND]->(b);" in text++[email protected]("source, target", [(0, 1), (1, 0)])+def test_export_retains_zero_endpoint_ids(tmp_path, source, target):+ path = tmp_path / "numeric.cypher"+ LPGExporter(include_indexes=False).export(+ {+ "nodes": [{"id": source}, {"id": target}],+ "edges": [{"start_node_id": source, "end_node_id": target}],+ },+ path,+ )++ text = path.read_text(encoding="utf-8")+ assert (+ f"MATCH (a {{id: '{source}'}}), (b {{id: '{target}'}}) "+ "CREATE (a)-[r:RELATED_TO]->(b);"+ ) in text+ # A node with id 0 keeps its id instead of a generated node_<n> placeholder.+ assert "node_" not in text++[email protected]("empty", [None, ""])+def test_empty_earlier_names_fall_back_to_backend_names(tmp_path, empty):+ text = _export(+ tmp_path,+ [+ {+ "source_id": empty,+ "source": empty,+ "target_id": empty,+ "target": empty,+ "start_node_id": "alice",+ "end_node_id": "acme",+ }+ ],+ )++ assert "MATCH (a {id: 'alice'}), (b {id: 'acme'})" in text+++def test_canonical_endpoints_take_precedence(tmp_path):+ text = _export(+ tmp_path,+ [+ {+ "source_id": "alice",+ "target_id": "acme",+ "source": "ignored",+ "target": "ignored",+ "start_node_id": "ignored",+ "end_node_id": "ignored",+ }+ ],+ )++ assert "MATCH (a {id: 'alice'}), (b {id: 'acme'})" in text+ assert "ignored" not in text+++ "record",+ [{}, {"start_node_id": "alice"}, {"end_node_id": "acme"}],+)+def test_missing_endpoints_still_skip_the_relationship(tmp_path, record):+ assert "CREATE (a)-[" not in _export(tmp_path, [record])