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(vector-store): rank Euclidean results by distance in Qdrant and Pinecone (#2116)
Tymurba38aa270b56
diff --git a/semantica/vector_store/pinecone_store.py b/semantica/vector_store/pinecone_store.pyindex 43bd3616..0119d369 100644--- a/semantica/vector_store/pinecone_store.py+++ b/semantica/vector_store/pinecone_store.py@@ -81,7 +81,7 @@ class PineconeClient:# Map metric namesmetric_map = {"cosine": "cosine",- "euclidean": "euclidean_distance",+ "euclidean": "euclidean","dot": "dotproduct",}pinecone_metric = metric_map.get(metric.lower(), "cosine")@@ -129,13 +129,30 @@ class PineconeClient:except Exception as e:raise ProcessingError(f"Failed to get index: {str(e)}")+ def get_index_metric(self, index_name: str) -> Optional[str]:+ """Read the metric from the control-plane index description."""+ try:+ description = self.client.describe_index(index_name)+ metric = (+ description.get("metric")+ if isinstance(description, dict)+ else description.metric+ )+ return metric if isinstance(metric, str) else None+ except Exception as e:+ self.logger.warning(+ f"Could not determine index metric for '{index_name}': {e}"+ )+ return None+class PineconeIndex:"""Pinecone index wrapper."""- def __init__(self, index: Any):+ def __init__(self, index: Any, metric: Optional[str] = None):"""Initialize Pinecone index wrapper."""self.index = index+ self.metric = metricself.logger = get_logger("pinecone_index")def upsert_vectors(@@ -191,19 +208,16 @@ class PineconeIndex:results = []for match in response.matches:+ score = float(match.score)+ if self.metric == "euclidean":+ similarity = 1.0 / (1.0 + max(0.0, score))+ else:+ # Preserve the existing normalization for cosine and dotproduct.+ similarity = (score / (1.0 + abs(score)) + 1.0) / 2.0results.append({"id": match.id,- # Pinecone's native score is already "higher is better" but its- # range depends on the configured metric (bounded for cosine,- # unbounded for dotproduct). Squash with x/(1+|x|) instead of- # clamping distance-to-zero, since the latter collapses every- # score >= 1.0 to an identical 1.0 and destroys ranking order- # for dotproduct/unnormalized-vector indexes.- "score": (- float(match.score) / (1.0 + abs(float(match.score))) + 1.0- )- / 2.0,+ "score": similarity,"metadata": match.metadata or {},"vector": None,"distance": None,@@ -441,7 +455,9 @@ class PineconeStore:# Get the indexpinecone_index = self.client.get_index(index_name)- self.index = PineconeIndex(pinecone_index)+ self.index = PineconeIndex(+ pinecone_index, metric=self.client.get_index_metric(index_name)+ )self.search_engine = PineconeSearch(self.index)self.dimension = dimension@@ -469,7 +485,9 @@ class PineconeStore:try:pinecone_index = self.client.get_index(index_name)- self.index = PineconeIndex(pinecone_index)+ self.index = PineconeIndex(+ pinecone_index, metric=self.client.get_index_metric(index_name)+ )self.search_engine = PineconeSearch(self.index)if self.dimension is None:try:diff --git a/semantica/vector_store/qdrant_store.py b/semantica/vector_store/qdrant_store.pyindex 6e6b85b6..faa193f5 100644--- a/semantica/vector_store/qdrant_store.py+++ b/semantica/vector_store/qdrant_store.py@@ -126,6 +126,7 @@ class QdrantCollection:"""Initialize Qdrant collection wrapper."""self.client = clientself.collection_name = collection_name+ self._vectors_config = Noneself.logger = get_logger("qdrant_collection")def upsert_points(self, points: List[PointStruct], **options) -> Dict[str, Any]:@@ -153,6 +154,17 @@ class QdrantCollection:raise ProcessingError("Qdrant not available")try:+ if self._vectors_config is None:+ try:+ info = self.client.get_collection(self.collection_name)+ self._vectors_config = info.config.params.vectors+ except Exception as e:+ self.logger.warning(f"Could not determine collection distance: {e}")+ vector_config = self._vectors_config+ if isinstance(vector_config, dict):+ vector_config = vector_config.get(options.get("using"))+ distance = getattr(vector_config, "distance", None)+# qdrant-client >=1.10.0: query_points() supersedes the removed search().# It returns a QueryResponse whose .points attribute is a list of# ScoredPoint objects (id, score, payload, …).@@ -168,17 +180,16 @@ class QdrantCollection:results = []for point in response.points:+ score = float(point.score)+ if distance in ("Euclid", "Manhattan"):+ similarity = 1.0 / (1.0 + max(0.0, score))+ else:+ # Preserve the existing normalization for Cosine and unbounded Dot.+ similarity = (score / (1.0 + abs(score)) + 1.0) / 2.0results.append({"id": point.id,- # See pinecone_store.py PineconeIndex.search_vectors for why- # this uses x/(1+|x|) rather than clamping distance-to-zero:- # Qdrant's Dot distance metric is unbounded, and the old- # clamped formula collapsed every score >= 1.0 to 1.0.- "score": (- float(point.score) / (1.0 + abs(float(point.score))) + 1.0- )- / 2.0,+ "score": similarity,"metadata": point.payload or {},"vector": None,"distance": None,diff --git a/tests/vector_store/test_pinecone_score_direction.py b/tests/vector_store/test_pinecone_score_direction.pynew file mode 100644index 00000000..985b9687--- /dev/null+++ b/tests/vector_store/test_pinecone_score_direction.py@@ -0,0 +1,82 @@+"""Metric-aware Pinecone scores using the existing fake-client pattern."""++from types import SimpleNamespace+from unittest.mock import MagicMock++import numpy as np+import pytest++from semantica.vector_store.pinecone_store import (+ PineconeClient,+ PineconeIndex,+ PineconeStore,+)++[email protected](autouse=True)+def pinecone_available(monkeypatch):+ monkeypatch.setattr(+ "semantica.vector_store.pinecone_store.PINECONE_AVAILABLE", True+ )++[email protected]("create", [False, True])[email protected]("description_type", [dict, SimpleNamespace])+ "metric,native_metric,raw_scores,expected",+ [+ ("euclidean", "euclidean", [0.0, 1.0, 3.0], [1.0, 0.5, 0.25]),+ ("cosine", "cosine", [1.0, 0.0, -1.0], [0.75, 0.5, 0.25]),+ ("dot", "dotproduct", [50.0, 2.0, -1.0], [101 / 102, 5 / 6, 0.25]),+ ],+)+def test_scores_follow_created_or_attached_metric(+ create, description_type, metric, native_metric, raw_scores, expected+):+ client = MagicMock()+ index = client.Index.return_value+ client.describe_index.return_value = description_type(metric=native_metric)+ index.query.return_value = SimpleNamespace(+ matches=[+ SimpleNamespace(id=str(i), score=score, metadata={})+ for i, score in enumerate(raw_scores)+ ]+ )+ store = PineconeStore(api_key="test-key", dimension=2)+ store.client = PineconeClient(client)+ if create:+ store.create_index("vectors", dimension=2, metric=metric)+ else:+ store.get_index("vectors")++ results = store.search_vectors(np.array([1.0, 0.0]), k=3)+ scores = [result["score"] for result in results]+ assert [result["id"] for result in results] == ["0", "1", "2"]+ assert scores == pytest.approx(expected)+ assert scores == sorted(scores, reverse=True)+ if create:+ assert client.create_index.call_args.kwargs["metric"] == native_metric+++def test_unavailable_metric_keeps_existing_scores():+ client = MagicMock()+ client.describe_index.side_effect = RuntimeError("description unavailable")+ index = client.Index.return_value+ index.query.return_value = SimpleNamespace(+ matches=[SimpleNamespace(id="a", score=2.0, metadata={})]+ )+ store = PineconeStore(api_key="test-key", dimension=2)+ store.client = PineconeClient(client)+ store.get_index("vectors")++ results = store.search_vectors(np.array([1.0, 0.0]))+ assert results[0]["score"] == pytest.approx(5 / 6)+++def test_direct_index_without_metric_keeps_existing_scores():+ index = MagicMock()+ index.query.return_value = SimpleNamespace(+ matches=[SimpleNamespace(id="a", score=2.0, metadata={})]+ )+ results = PineconeIndex(index).search_vectors([1.0, 0.0])+ assert results[0]["score"] == pytest.approx(5 / 6)diff --git a/tests/vector_store/test_qdrant_score_direction.py b/tests/vector_store/test_qdrant_score_direction.pynew file mode 100644index 00000000..ac0669bd--- /dev/null+++ b/tests/vector_store/test_qdrant_score_direction.py@@ -0,0 +1,93 @@+"""Metric-aware Qdrant scores against the real local backend."""++from types import SimpleNamespace+from unittest.mock import MagicMock++import numpy as np+import pytest++from semantica.vector_store.qdrant_store import QdrantCollection, QdrantStore++qdrant = pytest.importorskip("qdrant_client")+models = pytest.importorskip("qdrant_client.models")++[email protected]("reopen", [False, True])+ "metric,vectors,expected",+ [+ ("Euclidean", [[1.0, 0.0], [2.0, 0.0], [4.0, 0.0]], [1.0, 0.5, 0.25]),+ ("Cosine", [[1.0, 0.0], [0.0, 1.0], [-1.0, 0.0]], [0.75, 0.5, 0.25]),+ ("Dot", [[50.0, 0.0], [2.0, 0.0], [-1.0, 0.0]], [101 / 102, 5 / 6, 0.25]),+ ],+)+def test_scores_follow_created_or_reopened_metric(+ tmp_path, metric, vectors, expected, reopen+):+ path = str(tmp_path / "qdrant")+ store = QdrantStore()+ store.client = qdrant.QdrantClient(path=path)+ try:+ store.create_collection("vectors", vector_size=2, distance=metric)+ store.insert_vectors(vectors, ids=[1, 2, 3])+ if reopen:+ store.client.close()+ store = QdrantStore()+ store.client = qdrant.QdrantClient(path=path)+ store.get_collection("vectors")++ results = store.search_vectors(np.array([1.0, 0.0]), limit=10)+ assert [result["id"] for result in results] == [1, 2, 3]+ scores = [result["score"] for result in results]+ assert scores == pytest.approx(expected)+ assert scores == sorted(scores, reverse=True)+ finally:+ store.client.close()+++ "distance", [models.Distance.EUCLID, models.Distance.MANHATTAN]+)[email protected]("named", [False, True])+def test_direct_wrapper_reads_external_collection_metric(distance, named):+ client = qdrant.QdrantClient(":memory:")+ try:+ config = models.VectorParams(size=2, distance=distance)+ if named:+ config = {+ "distance": config,+ "dot": models.VectorParams(size=2, distance=models.Distance.DOT),+ }+ client.create_collection("external", vectors_config=config)+ points = []+ for i, dot in enumerate([50.0, 2.0, -1.0], start=1):+ vector = [float(i - 1), 0.0]+ if named:+ vector = {"distance": vector, "dot": [dot, 0.0]}+ points.append(models.PointStruct(id=i, vector=vector))+ client.upsert("external", points=points)+ collection = QdrantCollection(client, "external")+ options = {"using": "distance"} if named else {}+ results = collection.search_points(np.array([0.0, 0.0]), limit=3, **options)+ scores = [result["score"] for result in results]+ assert [result["id"] for result in results] == [1, 2, 3]+ assert scores == pytest.approx([1.0, 0.5, 1 / 3])+ assert scores == sorted(scores, reverse=True)+ if named:+ results = collection.search_points(np.array([1.0, 0.0]), using="dot")+ assert [result["id"] for result in results] == [1, 2, 3]+ assert [result["score"] for result in results] == pytest.approx(+ [101 / 102, 5 / 6, 0.25]+ )+ finally:+ client.close()+++def test_unavailable_collection_metric_keeps_existing_scores():+ client = MagicMock()+ client.get_collection.side_effect = RuntimeError("description unavailable")+ client.query_points.return_value = SimpleNamespace(+ points=[SimpleNamespace(id=1, score=2.0, payload={})]+ )+ results = QdrantCollection(client, "vectors").search_points(np.array([1.0, 0.0]))+ assert results[0]["score"] == pytest.approx(5 / 6)