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(explorer): resolve router isolation, rdf_parser param shadow, and missing utils package
KaifAhmad1ebd2be3d9d05
diff --git a/semantica/explorer/utils/__init__.py b/semantica/explorer/utils/__init__.pynew file mode 100644index 00000000..8f9b9f56--- /dev/null+++ b/semantica/explorer/utils/__init__.py@@ -0,0 +1 @@+"""Utility helpers for the Semantica Knowledge Explorer."""diff --git a/semantica/explorer/utils/rdf_parser.py b/semantica/explorer/utils/rdf_parser.pyindex e6be89ec..9ab45ea8 100644--- a/semantica/explorer/utils/rdf_parser.py+++ b/semantica/explorer/utils/rdf_parser.py@@ -43,24 +43,29 @@ def _get_all_labels(graph: rdflib.Graph, subject: rdflib.URIRef, predicate: rdfl""" Returns a list of all string values for a predicate, stripping lang tags."""return list({str(lbl) for lbl in graph.objects(subject, predicate)})-def parse_skos_file(file_bytes: bytes, format: str = "turtle") -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:+def parse_skos_file(file_bytes: bytes, rdf_format: str = "turtle") -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:"""Parses RDF data and extracts SKOS concepts and relationships.-+Args:file_bytes: The raw bytes of the uploaded file.- format: The rdflib parse format (e.g., "turtle", "xml").-+ rdf_format: The rdflib parse format (e.g., "turtle" for .ttl, "xml" for .rdf).+Returns:A tuple of (nodes_list, edges_list) formatted for ContextGraph ingestion.++ Note:+ Edges are only emitted when both endpoints exist in the parsed file.+ Relationships pointing to external URIs not declared as skos:Concept or+ skos:ConceptScheme (e.g. cross-vocabulary broader links) are silently dropped."""-+g = rdflib.Graph()-+try:- g.parse(data=file_bytes, format=format)+ g.parse(data=file_bytes, format=rdf_format)except Exception as e:- raise ValueError(f"Failed to parse RDF file as {format}. Ensure the file is valid. Details: {str(e)}")+ raise ValueError(f"Failed to parse RDF file as {rdf_format}. Ensure the file is valid. Details: {str(e)}") from enodes_dict: Dict[str, Dict[str, Any]] = {}edges: List[Dict[str, Any]] = []diff --git a/semantica/server.py b/semantica/server.pyindex 828be61c..44ac7176 100644--- a/semantica/server.py+++ b/semantica/server.py@@ -66,9 +66,8 @@ try:export_import,graph,temporal,- vocabulary,)-+app.include_router(analytics.router)app.include_router(annotations.router)app.include_router(decisions.router)@@ -76,8 +75,7 @@ try:app.include_router(export_import.router)app.include_router(graph.router)app.include_router(temporal.router)- app.include_router(vocabulary.router)-+logging.info("Explorer API routes successfully mounted.")except ImportError as exc:@@ -87,6 +85,14 @@ except ImportError as exc:f"Details: {exc}")+# Vocabulary router — mounted separately; available once PR #421 lands+try:+ from .explorer.routes import vocabulary+ app.include_router(vocabulary.router)+ logging.info("Vocabulary API routes successfully mounted.")+except ImportError:+ logging.debug("Vocabulary router not yet available (pending implementation).")+def main():"""Server entry point."""uvicorn.run(app, host="0.0.0.0", port=8000)diff --git a/tests/explorer/test_rdf_parser.py b/tests/explorer/test_rdf_parser.pynew file mode 100644index 00000000..5483b02e--- /dev/null+++ b/tests/explorer/test_rdf_parser.py@@ -0,0 +1,424 @@+"""+Tests for semantica/explorer/utils/rdf_parser.py++Covers:+- parse_skos_file() with Turtle and RDF/XML formats+- ConceptScheme and Concept node extraction+- Label priority resolution (en > en-* > untagged > fallback)+- altLabel collection+- Structural edge extraction (broader/narrower/inScheme/related/topConceptOf/hasTopConcept)+- Edge filtering: edges with unknown endpoints are dropped+- Invalid bytes raises ValueError+- Empty graph returns empty lists+- _get_best_label and _get_all_labels helpers+"""++import pytest+import rdflib+from rdflib.namespace import RDF, SKOS++from semantica.explorer.utils.rdf_parser import (+ _get_all_labels,+ _get_best_label,+ parse_skos_file,+)++# ---------------------------------------------------------------------------+# Sample TTL fixtures+# ---------------------------------------------------------------------------++MINIMAL_TTL = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .++ex:Animals a skos:ConceptScheme ;+ skos:prefLabel "Animals"@en .++ex:Mammal a skos:Concept ;+ skos:prefLabel "Mammal"@en ;+ skos:inScheme ex:Animals .++ex:Dog a skos:Concept ;+ skos:prefLabel "Dog"@en ;+ skos:broader ex:Mammal ;+ skos:inScheme ex:Animals .+"""++MULTILINGUAL_TTL = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .++ex:C1 a skos:Concept ;+ skos:prefLabel "French Only"@fr ;+ skos:prefLabel "English Label"@en ;+ skos:prefLabel "British English"@en-GB ;+ skos:altLabel "Alias One"@en ;+ skos:altLabel "Alias Two"@en .+"""++UNTAGGED_TTL = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .++ex:C2 a skos:Concept ;+ skos:prefLabel "No Language Tag" ;+ skos:altLabel "alt1" ;+ skos:altLabel "alt2" .+"""++FALLBACK_TTL = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .++ex:C3 a skos:Concept ;+ skos:prefLabel "Nur Deutsch"@de .+"""++ALL_EDGE_TYPES_TTL = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .++ex:S1 a skos:ConceptScheme ;+ skos:prefLabel "Scheme One" .++ex:A a skos:Concept ;+ skos:prefLabel "A" ;+ skos:inScheme ex:S1 ;+ skos:topConceptOf ex:S1 .++ex:B a skos:Concept ;+ skos:prefLabel "B" ;+ skos:broader ex:A ;+ skos:inScheme ex:S1 .++ex:C a skos:Concept ;+ skos:prefLabel "C" ;+ skos:related ex:B ;+ skos:inScheme ex:S1 .++ex:S1 skos:hasTopConcept ex:A .+"""++# An edge pointing to an external URI not declared as a Concept/ConceptScheme+ORPHAN_EDGE_TTL = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .++ex:Known a skos:Concept ;+ skos:prefLabel "Known" ;+ skos:broader ex:ExternalConcept .+"""++MINIMAL_RDF_XML = b"""<?xml version="1.0"?>+<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"+ xmlns:skos="http://www.w3.org/2004/02/skos/core#"+ xmlns:ex="http://example.org/">++ <skos:ConceptScheme rdf:about="http://example.org/SchemeX">+ <skos:prefLabel xml:lang="en">Scheme X</skos:prefLabel>+ </skos:ConceptScheme>++ <skos:Concept rdf:about="http://example.org/ConceptY">+ <skos:prefLabel xml:lang="en">Concept Y</skos:prefLabel>+ <skos:inScheme rdf:resource="http://example.org/SchemeX"/>+ </skos:Concept>++</rdf:RDF>+"""+++# ---------------------------------------------------------------------------+# Helper: get node by URI+# ---------------------------------------------------------------------------++def _node(nodes, uri):+ return next((n for n in nodes if n["id"] == uri), None)++def _edges_of_type(edges, edge_type):+ return [e for e in edges if e["type"] == edge_type]+++# ---------------------------------------------------------------------------+# parse_skos_file — basic extraction+# ---------------------------------------------------------------------------++class TestParseSkosFileBasic:+ def test_returns_tuple_of_two_lists(self):+ nodes, edges = parse_skos_file(MINIMAL_TTL)+ assert isinstance(nodes, list)+ assert isinstance(edges, list)++ def test_extracts_concept_scheme(self):+ nodes, _ = parse_skos_file(MINIMAL_TTL)+ scheme = _node(nodes, "http://example.org/Animals")+ assert scheme is not None+ assert scheme["type"] == "skos:ConceptScheme"+ assert scheme["properties"]["content"] == "Animals"++ def test_extracts_concepts(self):+ nodes, _ = parse_skos_file(MINIMAL_TTL)+ uris = {n["id"] for n in nodes}+ assert "http://example.org/Mammal" in uris+ assert "http://example.org/Dog" in uris++ def test_concept_type_tag(self):+ nodes, _ = parse_skos_file(MINIMAL_TTL)+ mammal = _node(nodes, "http://example.org/Mammal")+ assert mammal["type"] == "skos:Concept"++ def test_node_has_required_keys(self):+ nodes, _ = parse_skos_file(MINIMAL_TTL)+ for n in nodes:+ assert "id" in n+ assert "type" in n+ assert "properties" in n+ assert "content" in n["properties"]+ assert "alt_labels" in n["properties"]+ assert "description" in n["properties"]++ def test_edge_has_required_keys(self):+ _, edges = parse_skos_file(MINIMAL_TTL)+ for e in edges:+ assert "source_id" in e+ assert "target_id" in e+ assert "type" in e+ assert "weight" in e+ assert "properties" in e++ def test_edge_weight_default(self):+ _, edges = parse_skos_file(MINIMAL_TTL)+ assert all(e["weight"] == 1.0 for e in edges)+++# ---------------------------------------------------------------------------+# parse_skos_file — label priority+# ---------------------------------------------------------------------------++class TestLabelPriority:+ def test_en_preferred_over_fr(self):+ nodes, _ = parse_skos_file(MULTILINGUAL_TTL)+ c1 = _node(nodes, "http://example.org/C1")+ assert c1 is not None+ assert c1["properties"]["content"] == "English Label"++ def test_untagged_used_when_no_en(self):+ nodes, _ = parse_skos_file(UNTAGGED_TTL)+ c2 = _node(nodes, "http://example.org/C2")+ assert c2 is not None+ assert c2["properties"]["content"] == "No Language Tag"++ def test_fallback_to_any_language(self):+ nodes, _ = parse_skos_file(FALLBACK_TTL)+ c3 = _node(nodes, "http://example.org/C3")+ assert c3 is not None+ assert c3["properties"]["content"] == "Nur Deutsch"++ def test_uri_fragment_used_when_no_pref_label(self):+ ttl = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .+ex:NoLabel a skos:Concept .+"""+ nodes, _ = parse_skos_file(ttl)+ n = _node(nodes, "http://example.org/NoLabel")+ assert n is not None+ assert n["properties"]["content"] == "NoLabel"+++# ---------------------------------------------------------------------------+# parse_skos_file — altLabels+# ---------------------------------------------------------------------------++class TestAltLabels:+ def test_alt_labels_collected(self):+ nodes, _ = parse_skos_file(MULTILINGUAL_TTL)+ c1 = _node(nodes, "http://example.org/C1")+ assert set(c1["properties"]["alt_labels"]) == {"Alias One", "Alias Two"}++ def test_alt_labels_empty_when_none(self):+ nodes, _ = parse_skos_file(MINIMAL_TTL)+ mammal = _node(nodes, "http://example.org/Mammal")+ assert mammal["properties"]["alt_labels"] == []++ def test_alt_labels_deduped(self):+ ttl = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .+ex:C a skos:Concept ;+ skos:prefLabel "C" ;+ skos:altLabel "same"@en ;+ skos:altLabel "same"@en .+"""+ nodes, _ = parse_skos_file(ttl)+ c = _node(nodes, "http://example.org/C")+ assert c["properties"]["alt_labels"].count("same") == 1+++# ---------------------------------------------------------------------------+# parse_skos_file — edge types+# ---------------------------------------------------------------------------++class TestEdgeTypes:+ def setup_method(self):+ self.nodes, self.edges = parse_skos_file(ALL_EDGE_TYPES_TTL)++ def test_in_scheme_edges(self):+ in_scheme = _edges_of_type(self.edges, "skos:inScheme")+ assert len(in_scheme) >= 2 # A, B, C all inScheme S1++ def test_broader_edge(self):+ broader = _edges_of_type(self.edges, "skos:broader")+ assert any(+ e["source_id"] == "http://example.org/B" and+ e["target_id"] == "http://example.org/A"+ for e in broader+ )++ def test_related_edge(self):+ related = _edges_of_type(self.edges, "skos:related")+ assert any(+ e["source_id"] == "http://example.org/C" and+ e["target_id"] == "http://example.org/B"+ for e in related+ )++ def test_top_concept_of_edge(self):+ top_concept_of = _edges_of_type(self.edges, "skos:topConceptOf")+ assert any(+ e["source_id"] == "http://example.org/A" and+ e["target_id"] == "http://example.org/S1"+ for e in top_concept_of+ )++ def test_has_top_concept_edge(self):+ has_top = _edges_of_type(self.edges, "skos:hasTopConcept")+ assert any(+ e["source_id"] == "http://example.org/S1" and+ e["target_id"] == "http://example.org/A"+ for e in has_top+ )+++# ---------------------------------------------------------------------------+# parse_skos_file — edge filtering (orphan edges dropped)+# ---------------------------------------------------------------------------++class TestOrphanEdgeFiltering:+ def test_edge_to_external_uri_is_dropped(self):+ nodes, edges = parse_skos_file(ORPHAN_EDGE_TTL)+ # ex:ExternalConcept is not declared as a Concept/ConceptScheme+ # so the broader edge should be dropped+ assert len(edges) == 0++ def test_known_node_is_still_extracted(self):+ nodes, _ = parse_skos_file(ORPHAN_EDGE_TTL)+ assert _node(nodes, "http://example.org/Known") is not None+++# ---------------------------------------------------------------------------+# parse_skos_file — empty and error cases+# ---------------------------------------------------------------------------++class TestEmptyAndErrors:+ def test_empty_graph_returns_empty_lists(self):+ empty_ttl = b"@prefix skos: <http://www.w3.org/2004/02/skos/core#> .\n"+ nodes, edges = parse_skos_file(empty_ttl)+ assert nodes == []+ assert edges == []++ def test_invalid_bytes_raises_value_error(self):+ with pytest.raises(ValueError, match="Failed to parse RDF file"):+ parse_skos_file(b"this is not valid turtle !!!!", rdf_format="turtle")++ def test_invalid_xml_raises_value_error(self):+ with pytest.raises(ValueError, match="Failed to parse RDF file"):+ parse_skos_file(b"<not-valid-xml>", rdf_format="xml")+++# ---------------------------------------------------------------------------+# parse_skos_file — RDF/XML format+# ---------------------------------------------------------------------------++class TestRdfXmlFormat:+ def test_parses_rdf_xml(self):+ nodes, edges = parse_skos_file(MINIMAL_RDF_XML, rdf_format="xml")+ uris = {n["id"] for n in nodes}+ assert "http://example.org/SchemeX" in uris+ assert "http://example.org/ConceptY" in uris++ def test_rdf_xml_scheme_type(self):+ nodes, _ = parse_skos_file(MINIMAL_RDF_XML, rdf_format="xml")+ scheme = _node(nodes, "http://example.org/SchemeX")+ assert scheme["type"] == "skos:ConceptScheme"+ assert scheme["properties"]["content"] == "Scheme X"++ def test_rdf_xml_in_scheme_edge(self):+ _, edges = parse_skos_file(MINIMAL_RDF_XML, rdf_format="xml")+ in_scheme = _edges_of_type(edges, "skos:inScheme")+ assert any(+ e["source_id"] == "http://example.org/ConceptY" and+ e["target_id"] == "http://example.org/SchemeX"+ for e in in_scheme+ )+++# ---------------------------------------------------------------------------+# _get_best_label helper+# ---------------------------------------------------------------------------++class TestGetBestLabel:+ def _make_graph(self, triples_ttl: bytes) -> rdflib.Graph:+ g = rdflib.Graph()+ g.parse(data=triples_ttl, format="turtle")+ return g++ def test_returns_en_when_available(self):+ ttl = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .+ex:X skos:prefLabel "English"@en ;+ skos:prefLabel "Deutsch"@de .+"""+ g = self._make_graph(ttl)+ result = _get_best_label(g, rdflib.URIRef("http://example.org/X"), SKOS.prefLabel)+ assert result == "English"++ def test_returns_empty_string_when_no_labels(self):+ g = rdflib.Graph()+ result = _get_best_label(g, rdflib.URIRef("http://example.org/X"), SKOS.prefLabel)+ assert result == ""++ def test_en_variant_beats_untagged(self):+ ttl = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .+ex:X skos:prefLabel "No Tag" ;+ skos:prefLabel "British"@en-GB .+"""+ g = self._make_graph(ttl)+ result = _get_best_label(g, rdflib.URIRef("http://example.org/X"), SKOS.prefLabel)+ assert result == "British"+++# ---------------------------------------------------------------------------+# _get_all_labels helper+# ---------------------------------------------------------------------------++class TestGetAllLabels:+ def test_returns_all_values(self):+ ttl = b"""+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .+@prefix ex: <http://example.org/> .+ex:X skos:altLabel "A"@en ;+ skos:altLabel "B"@fr ;+ skos:altLabel "C" .+"""+ g = rdflib.Graph()+ g.parse(data=ttl, format="turtle")+ result = _get_all_labels(g, rdflib.URIRef("http://example.org/X"), SKOS.altLabel)+ assert set(result) == {"A", "B", "C"}++ def test_returns_empty_list_when_no_labels(self):+ g = rdflib.Graph()+ result = _get_all_labels(g, rdflib.URIRef("http://example.org/X"), SKOS.altLabel)+ assert result == []