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
feat(triplet_store): add Altair Anzo triplet store backend (#814)
Mohd Kaif7fb94b652870
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 977b4178..c57a8f62 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Added+- **Altair Anzo triplet store backend** (#813) by @KaifAhmad1+ - Added `AnzoStore` (`semantica/triplet_store/anzo_store.py`), a fourth peer to `BlazegraphStore`/`RDF4JStore`/`JenaStore` speaking plain SPARQL 1.1 over HTTP — no new dependency, since Anzo has no official Python SDK but needs none+ - The one structural difference from the existing backends: Anzo addresses data by a dataset/graphmart **URI** (`dataset_uri`, required) rather than a short namespace/repository name, so the endpoint path (`<endpoint>/sparql/<store_type>/<url-encoded_dataset_uri>`) percent-encodes it; `store_type` defaults to `"graphmart"` and can be set to `"dataset"`+ - Reuses the shared `sparql_escaping.py` literal-escaping, datatype-IRI resolution, and CONSTRUCT-detection helpers rather than reimplementing them, matching `BlazegraphStore`'s CONSTRUCT/bindings `execute_sparql` contract exactly+ - Wired into `TripletStore` (`backend="anzo"`, added to `SUPPORTED_BACKENDS` and `NAMED_GRAPH_CAPABLE_BACKENDS`) and `config.py` (`TRIPLET_STORE_ANZO_ENDPOINT` env var / `anzo_endpoint` config key), and exported from `semantica.triplet_store`+ - 32 new tests in `tests/triplet_store/test_anzo_store.py` (mocked HTTP, no live Anzo instance needed), including dataset-URI percent-encoding cases that don't apply to the other backends+ - Bulk loading uses SPARQL `INSERT DATA` (the same approach `BlazegraphStore` uses) rather than Anzo's separate HTTP Client Interface, keeping the `bulk_load()` contract identical across backends+- **Comprehensive unit and security test suite for the `/api/sparql` Explorer route** (#773) by @Sameer6305- Added `tests/explorer/test_sparql_route.py` (34 tests) covering the SPARQL Explorer route (`semantica/explorer/routes/sparql.py`), which executes arbitrary SPARQL queries against an in-memory rdflib projection of the live graph and previously had zero test coverage- Verified read-only allowlist enforcement against write and mutation queries (`INSERT DATA`, `DELETE DATA`, `DELETE WHERE`, `DROP ALL`, `CLEAR ALL`, `LOAD`, `CREATE GRAPH`, `MODIFY`, comments, and multi-statement injections like `SELECT ... ; DROP ALL`), confirming rejected queries short-circuit before any graph is built or querieddiff --git a/semantica/triplet_store/__init__.py b/semantica/triplet_store/__init__.pyindex c5907094..72aba64c 100644--- a/semantica/triplet_store/__init__.py+++ b/semantica/triplet_store/__init__.py@@ -3,11 +3,11 @@ Triplet Store ModuleThis module provides comprehensive triplet store integration and managementfor RDF data storage and querying, supporting multiple triplet store backends-(Blazegraph, Jena, RDF4J) with unified interfaces.+(Blazegraph, Jena, RDF4J, Anzo) with unified interfaces.Key Features:- Unified triplet store interface- - Multi-backend support (Blazegraph, Jena, RDF4J)+ - Multi-backend support (Blazegraph, Jena, RDF4J, Anzo)- CRUD operations for RDF triplets- SPARQL query execution and optimization- Bulk data loading with progress tracking@@ -20,6 +20,7 @@ Main Classes:- BlazegraphStore: Blazegraph integration store- JenaStore: Apache Jena integration store- RDF4JStore: Eclipse RDF4J integration store+ - AnzoStore: Altair Anzo integration storeExample Usage:>>> from semantica.triplet_store import TripletStore@@ -35,6 +36,7 @@ from .triplet_store import TripletStorefrom .blazegraph_store import BlazegraphStorefrom .jena_store import JenaStorefrom .rdf4j_store import RDF4JStore+from .anzo_store import AnzoStorefrom .methods import (register_store,add_triplet,@@ -59,6 +61,7 @@ __all__ = ["BlazegraphStore","JenaStore","RDF4JStore",+ "AnzoStore","register_store","add_triplet","add_triplets",diff --git a/semantica/triplet_store/anzo_store.py b/semantica/triplet_store/anzo_store.pynew file mode 100644index 00000000..4ec4adaa--- /dev/null+++ b/semantica/triplet_store/anzo_store.py@@ -0,0 +1,503 @@+"""+Altair Anzo Store Module++This module provides Altair Anzo (formerly Cambridge Semantics Anzo, now+"Altair Graph Studio") integration for RDF storage and SPARQL querying.+Anzo speaks plain SPARQL 1.1 over HTTP, so this backend follows the same+request/response contract as BlazegraphStore and RDF4JStore — the one real+structural difference is that Anzo addresses data by a dataset/graphmart+*URI* rather than a short namespace/repository name, so that URI has to be+percent-encoded into the endpoint path.++Key Features:+ - Anzo SPARQL endpoint connection and HTTP Basic authentication+ - SPARQL query execution (SELECT/ASK/CONSTRUCT)+ - Bulk data loading via SPARQL INSERT DATA+ - Dataset/graphmart URI resolution and percent-encoding++Main Classes:+ - AnzoStore: Main Anzo integration store++Example Usage:+ >>> from semantica.triplet_store import AnzoStore+ >>> store = AnzoStore(+ ... endpoint="http://localhost:8080",+ ... dataset_uri="http://cambridgesemantics.com/Graphmart/abc123",+ ... )+ >>> result = store.execute_sparql(sparql_query)+ >>> load_result = store.bulk_load(triplets)++Author: Semantica Contributors+License: MIT+"""++import re+from typing import Any, Dict, List, Optional+from urllib.parse import quote, urlparse++import requests+from rdflib import Graph, Literal++from ..semantic_extract.triplet_extractor import Triplet+from ..utils.exceptions import ProcessingError, ValidationError+from ..utils.logging import get_logger+from ..utils.progress_tracker import get_progress_tracker+from . import sparql_escaping+++class AnzoStore:+ """+ Altair Anzo triplet store backend.++ • Anzo connection and HTTP Basic authentication+ • SPARQL query execution+ • Bulk data loading via SPARQL Update+ • Dataset/graphmart URI addressing+ • Error handling and recovery+ """++ def __init__(self, endpoint: str, **config):+ """+ Initialize Anzo store.++ Args:+ endpoint: Anzo host URL, e.g. "http://localhost:8080" (scheme ++ host + port only — the ``/sparql/<store_type>/<dataset_uri>``+ path is appended by this class).+ **config: Additional configuration:+ - dataset_uri: Full URI identifying the Anzo dataset or+ graphmart (required). Unlike Blazegraph's namespace or+ RDF4J's repository ID, this is a full URI, not a short+ name, and is percent-encoded into the endpoint path.+ - store_type: "graphmart" or "lds" (Anzo's Linked Data Set+ store type; default: "graphmart").+ - username: Username for HTTP Basic authentication.+ - password: Password for HTTP Basic authentication.+ - timeout: Request timeout in seconds (default: 30).++ Raises:+ ValidationError: if dataset_uri is not provided.+ """+ self.logger = get_logger("anzo_store")+ self.config = config+ self.progress_tracker = get_progress_tracker()+ # Ensure progress tracker is enabled+ if not self.progress_tracker.enabled:+ self.progress_tracker.enabled = True++ self.endpoint = endpoint.rstrip("/")++ dataset_uri = config.get("dataset_uri")+ if not dataset_uri:+ raise ValidationError(+ "AnzoStore requires 'dataset_uri' — the full URI of the "+ "Anzo dataset or graphmart to connect to."+ )+ self.dataset_uri = dataset_uri+ self.store_type = config.get("store_type", "graphmart")+ self.username = config.get("username")+ self.password = config.get("password")+ self.timeout = config.get("timeout", 30)++ self.connected = False+ self._connect()++ def _connect(self) -> None:+ """Connect to Anzo instance."""+ try:+ sparql_endpoint = self._get_sparql_endpoint()+ response = requests.get(+ sparql_endpoint,+ params={"query": "SELECT * WHERE { ?s ?p ?o } LIMIT 1"},+ timeout=self.timeout,+ auth=(self.username, self.password)+ if self.username and self.password+ else None,+ )++ if response.status_code == 200:+ self.connected = True+ self.logger.info(f"Connected to Anzo: {self.endpoint}")+ else:+ self.logger.warning(+ f"Anzo connection test failed: {response.status_code}"+ )+ except Exception as e:+ self.logger.warning(f"Could not connect to Anzo: {e}")++ def _get_sparql_endpoint(self) -> str:+ """+ Get SPARQL endpoint URL.++ Anzo's endpoint shape is ``<host>:<port>/sparql/<store_type>/<url-+ encoded_dataset_or_graphmart_uri>`` — the dataset/graphmart is+ identified by a full URI rather than a short name, so it must be+ percent-encoded (including "/" and ":") to remain a single path+ segment.+ """+ encoded_dataset = quote(self.dataset_uri, safe="")+ return f"{self.endpoint}/sparql/{self.store_type}/{encoded_dataset}"++ def _get_update_endpoint(self) -> str:+ """Get SPARQL Update endpoint URL (same endpoint as query, per Anzo's SPARQL 1.1 protocol)."""+ return self._get_sparql_endpoint()++ def _is_construct_query(self, query: str) -> bool:+ """+ Detect whether `query` is a SPARQL CONSTRUCT query.++ Delegates to sparql_escaping.CONSTRUCT_QUERY_RE, the single canonical+ CONSTRUCT-detection regex shared with BlazegraphStore and RDF4JStore.+ """+ return sparql_escaping.CONSTRUCT_QUERY_RE.search(query) is not None++ def execute_sparql(self, query: str, **options) -> Dict[str, Any]:+ """+ Execute SPARQL query.++ Args:+ query: SPARQL query string+ **options: Additional options:+ - result_format: Optional[Literal["bindings", "construct"]].+ If omitted, auto-detected via _is_construct_query(query).++ Returns:+ Query results. For non-CONSTRUCT queries (or when result_format+ resolves to "bindings"):+ {"success": bool, "bindings": [...], "variables": [...], "metadata": {...}}+ For CONSTRUCT queries (or result_format="construct"):+ {"success": bool, "bindings": [], "variables": [], "triples": [...],+ "metadata": {...}}+ where "triples" is a list of (subject, predicate, object, metadata)+ 4-tuples parsed from the Turtle response via rdflib.++ Raises:+ ProcessingError: if not connected, the HTTP request fails, or (for+ CONSTRUCT queries) the response body fails to parse as Turtle.+ """+ tracking_id = self.progress_tracker.start_tracking(+ module="triplet_store",+ submodule="AnzoStore",+ message="Executing SPARQL query on Anzo",+ )++ try:+ if not self.connected:+ self.progress_tracker.stop_tracking(+ tracking_id, status="failed", message="Not connected to Anzo"+ )+ raise ProcessingError("Not connected to Anzo")++ sparql_endpoint = self._get_sparql_endpoint()++ result_format = options.get("result_format")+ if result_format is None:+ result_format = "construct" if self._is_construct_query(query) else "bindings"+ elif result_format not in ("construct", "bindings"):+ raise ValidationError(f"Invalid result_format: {result_format!r}")++ if result_format == "construct":+ self.progress_tracker.update_tracking(+ tracking_id, message="Sending CONSTRUCT query to Anzo endpoint..."+ )+ response = requests.post(+ sparql_endpoint,+ data={"query": query},+ headers={+ "Content-Type": "application/x-www-form-urlencoded",+ "Accept": "text/turtle",+ },+ timeout=self.timeout,+ auth=(self.username, self.password)+ if self.username and self.password+ else None,+ )++ response.raise_for_status()++ self.progress_tracker.update_tracking(+ tracking_id, message="Parsing CONSTRUCT response as Turtle..."+ )+ graph = Graph()+ try:+ graph.parse(data=response.content, format="turtle")+ except Exception as parse_error:+ raise ProcessingError(+ f"Failed to parse CONSTRUCT response as Turtle: {parse_error}"+ ) from parse_error++ triples = []+ for s, p, o in graph:+ obj_metadata: Dict[str, Any] = {}+ if isinstance(o, Literal):+ if o.datatype is not None:+ obj_metadata["datatype"] = str(o.datatype)+ if o.language is not None:+ obj_metadata["language"] = str(o.language)+ triples.append((str(s), str(p), str(o), obj_metadata))++ result = {+ "success": True,+ "bindings": [],+ "variables": [],+ "triples": triples,+ "metadata": {+ "query": query,+ "endpoint": sparql_endpoint,+ "result_format": "construct",+ },+ }++ self.progress_tracker.stop_tracking(+ tracking_id,+ status="completed",+ message=f"CONSTRUCT query executed: {len(triples)} triples",+ )+ return result++ # Non-CONSTRUCT path.+ self.progress_tracker.update_tracking(+ tracking_id, message="Sending query to Anzo endpoint..."+ )+ response = requests.post(+ sparql_endpoint,+ data={"query": query},+ headers={+ "Content-Type": "application/x-www-form-urlencoded",+ "Accept": "application/sparql-results+json",+ },+ timeout=self.timeout,+ auth=(self.username, self.password)+ if self.username and self.password+ else None,+ )++ response.raise_for_status()++ self.progress_tracker.update_tracking(+ tracking_id, message="Parsing query results..."+ )+ result_data = response.json()++ result = {+ "success": True,+ "bindings": result_data.get("results", {}).get("bindings", []),+ "variables": result_data.get("head", {}).get("vars", []),+ "metadata": {"query": query, "endpoint": sparql_endpoint},+ }++ self.progress_tracker.stop_tracking(+ tracking_id,+ status="completed",+ message=f"Query executed: {len(result['bindings'])} results",+ )+ return result+ except ValidationError:+ self.progress_tracker.stop_tracking(+ tracking_id, status="failed", message="Validation error"+ )+ raise+ except Exception as e:+ self.logger.error(f"SPARQL query failed: {e}")+ self.progress_tracker.stop_tracking(+ tracking_id, status="failed", message=str(e)+ )+ raise ProcessingError(f"SPARQL query failed: {e}")++ def bulk_load(self, triplets: List[Triplet], **options) -> Dict[str, Any]:+ """+ Load triplets in bulk via SPARQL INSERT DATA.++ Args:+ triplets: List of triplets+ **options: Additional options:+ - graph: Named graph URI++ Returns:+ Load status+ """+ if not self.connected:+ raise ProcessingError("Not connected to Anzo")++ update_endpoint = self._get_update_endpoint()++ try:+ graph = options.get("graph", "")+ if graph:+ sparql_escaping.validate_uri(graph)++ insert_data = self._build_insert_data(triplets)+ # The GRAPH block must be nested *inside* the INSERT DATA braces+ # per the SPARQL 1.1 Update grammar (INSERT DATA { GRAPH <g> { ... } }),+ # not appended before them.+ if graph:+ query = f"INSERT DATA {{ GRAPH <{graph}> {{ {insert_data} }} }}"+ else:+ query = f"INSERT DATA {{ {insert_data} }}"++ response = requests.post(+ update_endpoint,+ data={"update": query},+ headers={"Content-Type": "application/x-www-form-urlencoded"},+ timeout=self.timeout * 2, # Longer timeout for bulk operations+ auth=(self.username, self.password)+ if self.username and self.password+ else None,+ )++ response.raise_for_status()++ return {+ "success": True,+ "triplets_loaded": len(triplets),+ "dataset_uri": self.dataset_uri,+ }+ except ValidationError:+ raise+ except Exception as e:+ self.logger.error(f"Bulk load failed: {e}")+ raise ProcessingError(f"Bulk load failed: {e}")++ def _build_insert_data(self, triplets: List[Triplet]) -> str:+ """Build SPARQL INSERT DATA clause.++ Validates subject/predicate as safe IRIs via sparql_escaping.validate_uri+ before interpolating them into the query string, so a value containing+ e.g. ``>`` cannot terminate the intended ``<...>`` token and inject+ additional SPARQL Update tokens.+ """+ lines = []+ for triplet in triplets:+ sparql_escaping.validate_uri(triplet.subject)+ sparql_escaping.validate_uri(triplet.predicate)+ lines.append(+ f"<{triplet.subject}> <{triplet.predicate}> {self._format_object_for_sparql(triplet)} ."+ )+ return " ".join(lines)++ def _format_object_for_sparql(self, triplet: Triplet) -> str:+ """Format triplet object as IRI or literal for SPARQL/N-Triples style syntax."""+ obj = triplet.object+ metadata = triplet.metadata or {}++ if self._is_uri_value(obj):+ if obj.startswith("<") and obj.endswith(">"):+ inner = obj[1:-1]+ if " " in inner or ">" in inner:+ raise ValueError(f"IRI contains invalid characters: {obj!r}")+ return obj+ return f"<{obj}>"++ escaped = sparql_escaping.escape_literal(obj)+ datatype = metadata.get("datatype") or metadata.get("literal_datatype")+ language = metadata.get("lang") or metadata.get("language")++ if datatype:+ datatype_iri = sparql_escaping.resolve_datatype_iri(datatype)+ return f"\"{escaped}\"^^{datatype_iri}"++ if language:+ if not sparql_escaping.LANG_TAG_RE.match(str(language)):+ raise ValueError(+ f"Invalid language tag {language!r}: must match RFC 5646 "+ f"(letters/digits and hyphens only, e.g. 'en', 'en-US')"+ )+ return f"\"{escaped}\"@{language}"++ return f"\"{escaped}\""++ def _is_uri_value(self, value: str) -> bool:+ """Detect if a value should be serialized as an IRI."""+ if not isinstance(value, str) or not value:+ return False+ if value.startswith("<") and value.endswith(">"):+ return True+ parsed = urlparse(value)+ if parsed.scheme not in {"http", "https", "urn"}:+ return False+ # Reject strings that only look like URIs (e.g. "http not a uri")+ return not re.search(r"\s", value)++ def add_triplet(self, triplet: Triplet, **options) -> Dict[str, Any]:+ """Add single triplet."""+ return self.bulk_load([triplet], **options)++ def add_triplets(self, triplets: List[Triplet], **options) -> Dict[str, Any]:+ """Add multiple triplets."""+ return self.bulk_load(triplets, **options)++ def get_triplets(+ self,+ subject: Optional[str] = None,+ predicate: Optional[str] = None,+ object: Optional[str] = None,+ **options,+ ) -> List[Triplet]:+ """Get triplets matching criteria."""+ # Constraints are expressed via FILTER(...) rather than appended as bare+ # equality expressions inside the group graph pattern — the latter+ # (e.g. "?s ?p ?o ?s = <...>") is not a valid SPARQL graph pattern and+ # is rejected by standards-compliant SPARQL engines. subject/predicate+ # are also validated as safe IRIs before interpolation.+ filters = []+ if subject:+ filters.append(f"?s = <{sparql_escaping.validate_uri(subject)}>")+ if predicate:+ filters.append(f"?p = <{sparql_escaping.validate_uri(predicate)}>")+ if object:+ filters.append(+ f"?o = {self._format_object_for_sparql(Triplet(subject='', predicate='', object=object))}"+ )++ filter_clause = f" FILTER({' && '.join(filters)})" if filters else ""+ query = f"SELECT ?s ?p ?o WHERE {{ ?s ?p ?o .{filter_clause} }}"++ result = self.execute_sparql(query, **options)++ triplets = []+ for binding in result["bindings"]:+ triplets.append(+ Triplet(+ subject=binding.get("s", {}).get("value", ""),+ predicate=binding.get("p", {}).get("value", ""),+ object=binding.get("o", {}).get("value", ""),+ metadata={"source": "anzo"},+ )+ )++ return triplets++ def delete_triplet(self, triplet: Triplet, **options) -> Dict[str, Any]:+ """Delete triplet."""+ if not self.connected:+ raise ProcessingError("Not connected to Anzo")++ update_endpoint = self._get_update_endpoint()++ try:+ sparql_escaping.validate_uri(triplet.subject)+ sparql_escaping.validate_uri(triplet.predicate)++ query = (+ f"DELETE DATA {{ <{triplet.subject}> <{triplet.predicate}> "+ f"{self._format_object_for_sparql(triplet)} }}"+ )++ response = requests.post(+ update_endpoint,+ data={"update": query},+ headers={"Content-Type": "application/x-www-form-urlencoded"},+ timeout=self.timeout,+ auth=(self.username, self.password)+ if self.username and self.password+ else None,+ )++ response.raise_for_status()++ return {"success": True}+ except ValidationError:+ raise+ except Exception as e:+ self.logger.error(f"Delete triplet failed: {e}")+ raise ProcessingError(f"Delete triplet failed: {e}")diff --git a/semantica/triplet_store/config.py b/semantica/triplet_store/config.pyindex ff674812..c1c0e6cc 100644--- a/semantica/triplet_store/config.py+++ b/semantica/triplet_store/config.py@@ -123,6 +123,7 @@ class TripletStoreConfig:"TRIPLET_STORE_BLAZEGRAPH_ENDPOINT": "blazegraph_endpoint","TRIPLET_STORE_JENA_ENDPOINT": "jena_endpoint","TRIPLET_STORE_RDF4J_ENDPOINT": "rdf4j_endpoint",+ "TRIPLET_STORE_ANZO_ENDPOINT": "anzo_endpoint",}for env_var, config_key in env_mappings.items():diff --git a/semantica/triplet_store/triplet_store.py b/semantica/triplet_store/triplet_store.pyindex 2fd573d5..d9dff7e1 100644--- a/semantica/triplet_store/triplet_store.py+++ b/semantica/triplet_store/triplet_store.py@@ -45,8 +45,8 @@ class TripletStore:supporting Blazegraph, Jena, and RDF4J backends."""- SUPPORTED_BACKENDS = {"blazegraph", "jena", "rdf4j"}- NAMED_GRAPH_CAPABLE_BACKENDS = {"blazegraph", "rdf4j"}+ SUPPORTED_BACKENDS = {"blazegraph", "jena", "rdf4j", "anzo"}+ NAMED_GRAPH_CAPABLE_BACKENDS = {"blazegraph", "rdf4j", "anzo"}def __init__(self,@@ -130,6 +130,19 @@ class TripletStore:self._store_backend = RDF4JStore(**backend_config)+ elif self.backend_type == "anzo":+ from .anzo_store import AnzoStore++ backend_config = self.config.copy()+ if self.endpoint:+ backend_config["endpoint"] = self.endpoint+ else:+ backend_config["endpoint"] = triplet_store_config.get(+ "anzo_endpoint", "http://localhost:8080"+ )++ self._store_backend = AnzoStore(**backend_config)+self.logger.info(f"Initialized {self.backend_type} backend")except Exception as e:diff --git a/semantica/triplet_store/triplet_store_usage.md b/semantica/triplet_store/triplet_store_usage.mdindex bbf33c85..8d704416 100644--- a/semantica/triplet_store/triplet_store_usage.md+++ b/semantica/triplet_store/triplet_store_usage.md@@ -166,6 +166,23 @@ Eclipse RDF4J support.store = TripletStore(backend="rdf4j", endpoint="http://localhost:8080/rdf4j-server")```+### Anzo+Altair Anzo (Altair Graph Studio) support. Unlike Blazegraph's namespace or+RDF4J's repository ID, Anzo addresses data by a dataset/graphmart **URI**+rather than a short name, so `dataset_uri` is required and is+percent-encoded into the endpoint path+(`<endpoint>/sparql/<store_type>/<url-encoded_dataset_uri>`).+```python+store = TripletStore(+ backend="anzo",+ endpoint="http://localhost:8080",+ dataset_uri="http://cambridgesemantics.com/Graphmart/abc123",+ store_type="graphmart", # or "lds" (Anzo's Linked Data Set store type)+ username="user",+ password="pass",+)+```+## ConfigurationConfiguration is managed via `config.yaml` or environment variables.@@ -176,4 +193,5 @@ triplet_store:blazegraph_endpoint: http://localhost:9999/blazegraphjena_endpoint: http://localhost:3030/dsrdf4j_endpoint: http://localhost:8080/rdf4j-server+ anzo_endpoint: http://localhost:8080```diff --git a/tests/triplet_store/test_anzo_store.py b/tests/triplet_store/test_anzo_store.pynew file mode 100644index 00000000..bc1c527a--- /dev/null+++ b/tests/triplet_store/test_anzo_store.py@@ -0,0 +1,590 @@+import os+import sys+import unittest+from unittest.mock import MagicMock, patch++PROJECT_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))+if PROJECT_ROOT not in sys.path:+ sys.path.insert(0, PROJECT_ROOT)++from semantica.semantic_extract.triplet_extractor import Triplet+from semantica.triplet_store.anzo_store import AnzoStore+from semantica.utils.exceptions import ProcessingError, ValidationError++DATASET_URI = "http://cambridgesemantics.com/Graphmart/abc123"+++def _make_connected_store(**overrides) -> AnzoStore:+ """Create an AnzoStore instance bypassing the real _connect() call,+ with .connected forced True (mirrors the state execute_sparql requires)."""+ kwargs = {"endpoint": "http://localhost:8080", "dataset_uri": DATASET_URI}+ kwargs.update(overrides)+ with patch.object(AnzoStore, "_connect", autospec=True):+ store = AnzoStore(**kwargs)+ store.connected = True+ return store+++CONSTRUCT_QUERY = "CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }"+++class TestAnzoStoreConstruction(unittest.TestCase):+ def test_requires_dataset_uri(self):+ with self.assertRaises(ValidationError):+ AnzoStore(endpoint="http://localhost:8080")++ def test_default_store_type_is_graphmart(self):+ store = _make_connected_store()+ self.assertEqual(store.store_type, "graphmart")++ def test_store_type_override(self):+ store = _make_connected_store(store_type="lds")+ self.assertEqual(store.store_type, "lds")+++class TestAnzoStoreEndpointEncoding(unittest.TestCase):+ def test_sparql_endpoint_url_encodes_dataset_uri(self):+ store = _make_connected_store()+ endpoint = store._get_sparql_endpoint()+ self.assertEqual(+ endpoint,+ "http://localhost:8080/sparql/graphmart/"+ "http%3A%2F%2Fcambridgesemantics.com%2FGraphmart%2Fabc123",+ )++ def test_sparql_endpoint_uses_store_type_in_path(self):+ store = _make_connected_store(store_type="lds")+ endpoint = store._get_sparql_endpoint()+ self.assertIn("/sparql/lds/", endpoint)++ def test_update_endpoint_matches_query_endpoint(self):+ store = _make_connected_store()+ self.assertEqual(store._get_update_endpoint(), store._get_sparql_endpoint())++ def test_dataset_uri_with_special_characters_is_fully_encoded(self):+ store = _make_connected_store(dataset_uri="http://ex.org/g?x=1&y=2#frag")+ endpoint = store._get_sparql_endpoint()+ # No raw reserved characters from the dataset URI should leak into the path.+ path_segment = endpoint.split("/sparql/graphmart/", 1)[1]+ for char in ("/", "?", "&", "#", ":"):+ self.assertNotIn(char, path_segment)+++class TestAnzoStoreIsConstructQuery(unittest.TestCase):+ def test_detects_uppercase(self):+ self.assertTrue(_make_connected_store()._is_construct_query(CONSTRUCT_QUERY))++ def test_detects_lowercase(self):+ self.assertTrue(+ _make_connected_store()._is_construct_query(+ "construct { ?s ?p ?o } where { ?s ?p ?o }"+ )+ )++ def test_false_for_select(self):+ self.assertFalse(+ _make_connected_store()._is_construct_query("SELECT ?s WHERE { ?s ?p ?o }")+ )++ def test_false_for_ask(self):+ self.assertFalse(_make_connected_store()._is_construct_query("ASK { ?s ?p ?o }"))++ def test_no_false_positive_on_constructor_substring(self):+ self.assertFalse(+ _make_connected_store()._is_construct_query(+ 'SELECT ?s WHERE { ?s <urn:p> "CONSTRUCTOR" }'+ )+ )++ def test_is_construct_query_detects_mixed_case_keyword(self):+ store = _make_connected_store()+ self.assertTrue(+ store._is_construct_query("Construct { ?s ?p ?o } Where { ?s ?p ?o }")+ )++ def test_is_construct_query_detects_complex_preambles(self):+ # Permanent regression tests covering edge cases discovered during+ # regex stress-testing (issue #7): multiline declarations, empty+ # prefix namespaces, and inline comments embedded in the preamble.+ store = _make_connected_store()+ cases = {+ "multiline_prefix": "PREFIX foaf:\n <http://xmlns.com/foaf/0.1/>\nCONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }",+ "empty_prefix_namespace": "PREFIX : <http://ex.org/> CONSTRUCT { ?s ?p ?o }",+ "inline_comment": "PREFIX ex: <http://ex.org/>\n# inline comment\nCONSTRUCT { ?s ?p ?o }",+ }+ for name, query in cases.items():+ with self.subTest(case=name):+ self.assertTrue(store._is_construct_query(query))+++class TestAnzoStoreExecuteSparql(unittest.TestCase):+ def test_not_connected_raises_processing_error(self):+ with patch.object(AnzoStore, "_connect", autospec=True):+ store = AnzoStore(endpoint="http://localhost:8080", dataset_uri=DATASET_URI)+ store.connected = False+ with self.assertRaises(ProcessingError):+ store.execute_sparql("SELECT ?s WHERE { ?s ?p ?o }")++ def test_select_sends_basic_auth_when_credentials_given(self):+ store = _make_connected_store(username="user", password="pass")+ mock_resp = MagicMock()+ mock_resp.json.return_value = {"head": {"vars": []}, "results": {"bindings": []}}+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ store.execute_sparql("SELECT ?s WHERE { ?s ?p ?o }")+ _, kw = mp.call_args+ self.assertEqual(kw["auth"], ("user", "pass"))++ def test_select_response_shape(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.json.return_value = {+ "head": {"vars": ["s", "p", "o"]},+ "results": {+ "bindings": [+ {+ "s": {"type": "uri", "value": "http://ex.org/s1"},+ "p": {"type": "uri", "value": "http://ex.org/p1"},+ "o": {"type": "literal", "value": "v1"},+ }+ ]+ },+ }+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ result = store.execute_sparql("SELECT ?s ?p ?o WHERE { ?s ?p ?o }")+ _, kw = mp.call_args+ self.assertNotEqual(kw["headers"].get("Accept"), "text/turtle")+ self.assertEqual(+ result,+ {+ "success": True,+ "bindings": mock_resp.json.return_value["results"]["bindings"],+ "variables": ["s", "p", "o"],+ "metadata": {+ "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o }",+ "endpoint": store._get_sparql_endpoint(),+ },+ },+ )+ self.assertNotIn("triples", result)++ def test_construct_sends_turtle_accept_header(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.content = b'@prefix ex: <http://ex.org/> .\nex:s1 ex:p1 "v" .\n'+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ store.execute_sparql(CONSTRUCT_QUERY)+ _, kw = mp.call_args+ self.assertEqual(kw["headers"]["Accept"], "text/turtle")++ def test_construct_parses_triples_from_turtle_fixture(self):+ store = _make_connected_store()+ fixture = (+ b"@prefix ex: <http://ex.org/> .\n"+ b'ex:s1 ex:p1 "value1" .\n'+ b"ex:s1 ex:p2 ex:o2 .\n"+ )+ mock_resp = MagicMock()+ mock_resp.content = fixture+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ):+ result = store.execute_sparql(CONSTRUCT_QUERY)+ self.assertTrue(result["success"])+ self.assertEqual(result["metadata"]["result_format"], "construct")+ triples = {(s, p, o) for s, p, o, _m in result["triples"]}+ self.assertIn(("http://ex.org/s1", "http://ex.org/p1", "value1"), triples)+ self.assertIn(("http://ex.org/s1", "http://ex.org/p2", "http://ex.org/o2"), triples)++ def test_result_format_construct_forces_construct_path(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.content = b'@prefix ex: <http://ex.org/> .\nex:s1 ex:p1 "v" .\n'+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ result = store.execute_sparql(+ "SELECT ?s WHERE { ?s ?p ?o }", result_format="construct"+ )+ _, kw = mp.call_args+ self.assertEqual(kw["headers"]["Accept"], "text/turtle")+ self.assertIn("triples", result)++ def test_malformed_turtle_raises_processing_error(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.content = b"this is { not [ valid turtle at all !!!"+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ):+ with self.assertRaises(ProcessingError) as ctx:+ store.execute_sparql(CONSTRUCT_QUERY)+ self.assertIsInstance(ctx.exception, ProcessingError)++ def test_invalid_result_format_raises_validation_error(self):+ store = _make_connected_store()+ with self.assertRaises(ValidationError):+ store.execute_sparql("SELECT ?s WHERE { ?s ?p ?o }", result_format="nope")++ def test_execute_sparql_construct_handles_literal_with_braces_in_valid_turtle(+ self,+ ):+ # Adversarial case implied by the brace-matching bug found in the+ # template-string layer (construct_templates._find_matching_brace):+ # confirm rdflib itself parses a *valid* Turtle literal containing+ # brace characters correctly, since this is a different parsing+ # layer (real Turtle syntax, not our {{param}} template string).+ store = _make_connected_store()+ turtle_fixture = (+ b"@prefix ex: <http://ex.org/> .\n"+ b'ex:s1 ex:p1 "text with { and } braces inside" .\n'+ )+ mock_response = MagicMock()+ mock_response.content = turtle_fixture+ mock_response.raise_for_status = MagicMock()++ with patch(+ "semantica.triplet_store.anzo_store.requests.post",+ return_value=mock_response,+ ):+ result = store.execute_sparql("CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }")++ self.assertEqual(len(result["triples"]), 1)+ subject, predicate, obj, metadata = result["triples"][0]+ self.assertEqual(subject, "http://ex.org/s1")+ self.assertEqual(predicate, "http://ex.org/p1")+ self.assertEqual(obj, "text with { and } braces inside")+ self.assertEqual(metadata, {})+++class TestAnzoStoreBulkLoadAndCrud(unittest.TestCase):+ def _t(self):+ return Triplet(+ subject="http://ex.org/s1",+ predicate="http://ex.org/p",+ object="http://ex.org/o1",+ )++ def test_bulk_load_posts_insert_data_to_update_endpoint(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ result = store.bulk_load([self._t()])+ self.assertTrue(result["success"])+ self.assertEqual(result["triplets_loaded"], 1)+ self.assertEqual(result["dataset_uri"], DATASET_URI)+ call_url = mp.call_args[0][0]+ self.assertEqual(call_url, store._get_update_endpoint())+ self.assertIn("INSERT DATA", mp.call_args[1]["data"]["update"])++ def test_bulk_load_with_graph_nests_graph_block_inside_insert_data(self):+ # SPARQL 1.1 Update requires the GRAPH block *inside* the INSERT DATA+ # braces: INSERT DATA { GRAPH <g> { ... } }, not+ # "INSERT DATA GRAPH <g> { ... }".+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ store.bulk_load([self._t()], graph="http://ex.org/g")+ update_query = mp.call_args[1]["data"]["update"]+ self.assertIn("INSERT DATA { GRAPH <http://ex.org/g> {", update_query)+ self.assertNotIn("INSERT DATA GRAPH", update_query)++ def test_bulk_load_rejects_invalid_graph_uri(self):+ store = _make_connected_store()+ with self.assertRaises(ValidationError):+ store.bulk_load([self._t()], graph="http://ex.org/g with space")++ def test_bulk_load_rejects_injected_subject(self):+ store = _make_connected_store()+ bad_triplet = Triplet(+ subject="http://ex.org/s1> } ; DROP ALL #",+ predicate="http://ex.org/p",+ object="http://ex.org/o1",+ )+ with self.assertRaises(ValidationError):+ store.bulk_load([bad_triplet])++ def test_bulk_load_not_connected_raises(self):+ with patch.object(AnzoStore, "_connect", autospec=True):+ store = AnzoStore(endpoint="http://localhost:8080", dataset_uri=DATASET_URI)+ store.connected = False+ with self.assertRaises(ProcessingError):+ store.bulk_load([self._t()])++ def test_add_triplet_delegates_to_bulk_load(self):+ store = _make_connected_store()+ with patch.object(store, "bulk_load", return_value={"success": True}) as mb:+ store.add_triplet(self._t())+ mb.assert_called_once_with([self._t()])++ def test_add_triplets_delegates_to_bulk_load(self):+ store = _make_connected_store()+ triplets = [self._t(), self._t()]+ with patch.object(store, "bulk_load", return_value={"success": True}) as mb:+ store.add_triplets(triplets)+ mb.assert_called_once_with(triplets)++ def test_delete_triplet_posts_delete_data(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ result = store.delete_triplet(self._t())+ self.assertTrue(result["success"])+ self.assertIn("DELETE DATA", mp.call_args[1]["data"]["update"])++ def test_delete_triplet_not_connected_raises(self):+ with patch.object(AnzoStore, "_connect", autospec=True):+ store = AnzoStore(endpoint="http://localhost:8080", dataset_uri=DATASET_URI)+ store.connected = False+ with self.assertRaises(ProcessingError):+ store.delete_triplet(self._t())++ def test_delete_triplet_rejects_injected_subject(self):+ store = _make_connected_store()+ bad_triplet = Triplet(+ subject="http://ex.org/s1> } ; DROP ALL #",+ predicate="http://ex.org/p",+ object="http://ex.org/o1",+ )+ with self.assertRaises(ValidationError):+ store.delete_triplet(bad_triplet)++ def test_get_triplets_builds_select_and_parses_bindings(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.json.return_value = {+ "head": {"vars": ["s", "p", "o"]},+ "results": {+ "bindings": [+ {+ "s": {"type": "uri", "value": "http://ex.org/s1"},+ "p": {"type": "uri", "value": "http://ex.org/p1"},+ "o": {"type": "literal", "value": "v1"},+ }+ ]+ },+ }+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ):+ triplets = store.get_triplets(subject="http://ex.org/s1")+ self.assertEqual(len(triplets), 1)+ self.assertEqual(triplets[0].subject, "http://ex.org/s1")+ self.assertEqual(triplets[0].metadata.get("source"), "anzo")++ def test_get_triplets_emits_valid_filter_based_query(self):+ # The WHERE clause must remain a syntactically valid graph pattern+ # (?s ?p ?o .) with constraints expressed via FILTER(...), not bare+ # equality expressions appended inside the group graph pattern.+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.json.return_value = {"head": {"vars": []}, "results": {"bindings": []}}+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ store.get_triplets(subject="http://ex.org/s1", predicate="http://ex.org/p1")+ query = mp.call_args[1]["data"]["query"]+ self.assertIn("?s ?p ?o .", query)+ self.assertIn("FILTER(", query)+ self.assertIn("?s = <http://ex.org/s1>", query)+ self.assertIn("?p = <http://ex.org/p1>", query)+ self.assertNotIn("?o } WHERE", query)++ def test_get_triplets_no_filters_omits_filter_clause(self):+ store = _make_connected_store()+ mock_resp = MagicMock()+ mock_resp.json.return_value = {"head": {"vars": []}, "results": {"bindings": []}}+ mock_resp.raise_for_status = MagicMock()+ with patch(+ "semantica.triplet_store.anzo_store.requests.post", return_value=mock_resp+ ) as mp:+ store.get_triplets()+ query = mp.call_args[1]["data"]["query"]+ self.assertNotIn("FILTER(", query)+ self.assertEqual(query, "SELECT ?s ?p ?o WHERE { ?s ?p ?o . }")++ def test_get_triplets_rejects_invalid_subject_uri(self):+ store = _make_connected_store()+ with self.assertRaises(ValidationError):+ store.get_triplets(subject="not a valid uri")+++class TestAnzoStoreObjectFormatting(unittest.TestCase):+ def test_format_object_serializes_uri_object(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:knows",+ object="urn:entity:person:2",+ )+ self.assertEqual(+ store._format_object_for_sparql(triplet), "<urn:entity:person:2>"+ )++ def test_format_object_serializes_literal_object(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:name",+ object="Jane Doe",+ )+ self.assertEqual(store._format_object_for_sparql(triplet), "\"Jane Doe\"")++ def test_format_object_serializes_typed_literal(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:age",+ object="42",+ metadata={"datatype": "xsd:integer"},+ )+ self.assertEqual(+ store._format_object_for_sparql(triplet),+ "\"42\"^^<http://www.w3.org/2001/XMLSchema#integer>",+ )++ def test_format_object_rejects_injected_lang_tag(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:label",+ object="Color",+ metadata={"lang": "en . CLEAR ALL #"},+ )+ with self.assertRaises(ValueError):+ store._format_object_for_sparql(triplet)++ def test_format_object_escapes_literal_object(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:note",+ object='line "one"\\line2',+ )+ obj = store._format_object_for_sparql(triplet)+ self.assertEqual(+ obj,+ "\"line \\\"one\\\"\\\\line2\"",+ )++ def test_format_object_serializes_language_literal(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:label",+ object="Color",+ metadata={"lang": "en"},+ )+ obj = store._format_object_for_sparql(triplet)+ self.assertEqual(obj, "\"Color\"@en")++ def test_format_object_does_not_treat_invalid_uri_like_text_as_uri(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:note",+ object="http not a uri",+ )+ obj = store._format_object_for_sparql(triplet)+ self.assertEqual(obj, "\"http not a uri\"")++ def test_format_object_expands_rdf_prefix_to_full_iri(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:value",+ object="hello",+ metadata={"datatype": "rdf:langString"},+ )+ obj = store._format_object_for_sparql(triplet)+ self.assertEqual(+ obj,+ "\"hello\"^^<http://www.w3.org/1999/02/22-rdf-syntax-ns#langString>",+ )++ def test_format_object_rejects_unknown_prefix(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:value",+ object="hello",+ metadata={"datatype": "myns:customType"},+ )+ with self.assertRaises(ValueError):+ store._format_object_for_sparql(triplet)++ def test_format_object_rejects_datatype_with_whitespace(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:age",+ object="42",+ metadata={"datatype": "http://example.org/type CLEAR ALL"},+ )+ with self.assertRaises(ValueError):+ store._format_object_for_sparql(triplet)++ def test_format_object_accepts_full_iri_datatype_no_brackets(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:age",+ object="42",+ metadata={"datatype": "http://www.w3.org/2001/XMLSchema#integer"},+ )+ obj = store._format_object_for_sparql(triplet)+ self.assertEqual(+ obj,+ "\"42\"^^<http://www.w3.org/2001/XMLSchema#integer>",+ )++ def test_format_object_accepts_bracketed_iri_datatype(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:age",+ object="42",+ metadata={"datatype": "<http://www.w3.org/2001/XMLSchema#integer>"},+ )+ obj = store._format_object_for_sparql(triplet)+ self.assertEqual(+ obj,+ "\"42\"^^<http://www.w3.org/2001/XMLSchema#integer>",+ )++ def test_format_object_accepts_hyphenated_lang_tag(self):+ store = _make_connected_store()+ triplet = Triplet(+ subject="urn:entity:person:1",+ predicate="urn:property:label",+ object="Colour",+ metadata={"lang": "en-GB"},+ )+ obj = store._format_object_for_sparql(triplet)+ self.assertEqual(obj, "\"Colour\"@en-GB")+++if __name__ == "__main__":+ unittest.main()