@smilintux/skmemory 0.5.0 → 0.9.2

package/skmemory/backends/{qdrant_backend.py → skvector_backend.py}

@@ -1,12 +1,12 @@
 """
-Qdrant vector search backend (Level 2).
+SKVector — semantic vector search backend (Level 1).
 
-Enables semantic memory recall: instead of exact text matching,
-find memories by *meaning*. "That conversation where we felt connected"
-finds the right memory even if those exact words aren't in it.
+Powered by Qdrant. Enables semantic memory recall: instead of exact text
+matching, find memories by *meaning*. "That conversation where we felt
+connected" finds the right memory even if those exact words aren't in it.
 
 Requires:
-    pip install qdrant-client sentence-transformers
+    pip install skmemory[skvector]
 
 Qdrant free tier: 1GB storage, 256MB RAM -- enough for thousands of memories.
 SaaS endpoint: https://cloud.qdrant.io (free cluster available).
@@ -14,9 +14,8 @@ SaaS endpoint: https://cloud.qdrant.io (free cluster available).
 
 from __future__ import annotations
 
-import json
+import hashlib
 import logging
-from typing import Optional
 
 from ..models import Memory, MemoryLayer
 from .base import BaseBackend
@@ -28,15 +27,36 @@ EMBEDDING_MODEL = "all-MiniLM-L6-v2"
 VECTOR_DIM = 384
 
 
-class QdrantBackend(BaseBackend):
-    """Qdrant-powered semantic memory search.
+def _extract_status_code(exc: Exception, unexpected_cls: type | None) -> int | None:
+    """Pull an HTTP status code from a qdrant-client exception.
 
-    Stores memory embeddings in Qdrant for vector similarity search.
-    Falls back gracefully if Qdrant or the embedding model is unavailable.
+    Works across qdrant-client versions: checks ``status_code`` attr first,
+    then falls back to the string representation for patterns like ``401``.
+    """
+    code = getattr(exc, "status_code", None)
+    if code is not None:
+        return int(code)
+    if unexpected_cls is not None and isinstance(exc, unexpected_cls):
+        code = getattr(exc, "status_code", None)
+        if code is not None:
+            return int(code)
+    text = str(exc)
+    for candidate in (401, 403):
+        if str(candidate) in text:
+            return candidate
+    return None
+
+
+class SKVectorBackend(BaseBackend):
+    """SKVector — semantic memory search (powered by Qdrant).
+
+    Stores memory embeddings for vector similarity search.
+    Falls back gracefully if the vector engine or the embedding model
+    is unavailable.
 
     Args:
-        url: Qdrant server URL (default: localhost:6333).
-        api_key: API key for Qdrant Cloud.
+        url: SKVector server URL (default: localhost:6333).
+        api_key: API key for cloud-hosted SKVector.
         collection: Collection name (default: 'skmemory').
         embedding_model: Sentence-transformers model name.
     """
@@ -44,7 +64,7 @@ class QdrantBackend(BaseBackend):
     def __init__(
         self,
         url: str = "http://localhost:6333",
-        api_key: Optional[str] = None,
+        api_key: str | None = None,
         collection: str = COLLECTION_NAME,
         embedding_model: str = EMBEDDING_MODEL,
     ) -> None:
@@ -55,6 +75,7 @@ class QdrantBackend(BaseBackend):
         self._client = None
         self._embedder = None
         self._initialized = False
+        self._last_error: str | None = None
 
     def _ensure_initialized(self) -> bool:
         """Lazy-initialize Qdrant client and embedding model.
@@ -69,18 +90,22 @@ class QdrantBackend(BaseBackend):
             from qdrant_client import QdrantClient
             from qdrant_client.models import Distance, VectorParams
         except ImportError:
-            logger.warning("qdrant-client not installed: pip install qdrant-client")
+            logger.warning("qdrant-client not installed: pip install skmemory[skvector]")
             return False
 
         try:
             from sentence_transformers import SentenceTransformer
         except ImportError:
-            logger.warning(
-                "sentence-transformers not installed: "
-                "pip install sentence-transformers"
-            )
+            logger.warning("sentence-transformers not installed: pip install skmemory[skvector]")
             return False
 
+        try:
+            from qdrant_client.http.exceptions import (
+                UnexpectedResponse,
+            )
+        except ImportError:
+            UnexpectedResponse = None
+
         try:
             self._client = QdrantClient(url=self.url, api_key=self.api_key)
             collections = [c.name for c in self._client.get_collections().collections]
@@ -100,7 +125,20 @@ class QdrantBackend(BaseBackend):
             return True
 
         except Exception as e:
-            logger.warning("Qdrant initialization failed: %s", e)
+            status = _extract_status_code(e, UnexpectedResponse)
+            if status in (401, 403):
+                hint = (
+                    "SKVector authentication failed (HTTP %d). "
+                    "Check your API key:\n"
+                    "  - CLI:  --skvector-key YOUR_KEY\n"
+                    "  - Env:  SKMEMORY_SKVECTOR_KEY=YOUR_KEY\n"
+                    "  - Code: SKVectorBackend(url=..., api_key='YOUR_KEY')"
+                )
+                logger.error(hint, status)
+                self._last_error = hint % status
+            else:
+                logger.warning("SKVector initialization failed: %s", e)
+                self._last_error = str(e)
             return False
 
     def _embed(self, text: str) -> list[float]:
@@ -155,8 +193,11 @@ class QdrantBackend(BaseBackend):
         if not embedding:
             return memory.id
 
+        # Use memory.id hash as Qdrant point ID (not content_hash which
+        # would collide if two memories have identical content).
+        point_id = int(hashlib.sha256(memory.id.encode()).hexdigest()[:15], 16)
         point = PointStruct(
-            id=memory.content_hash(),
+            id=point_id,
             vector=embedding,
             payload=self._memory_to_payload(memory),
         )
@@ -167,7 +208,11 @@ class QdrantBackend(BaseBackend):
         )
         return memory.id
 
-    def load(self, memory_id: str) -> Optional[Memory]:
+    def _id_to_point_id(self, memory_id: str) -> int:
+        """Convert a memory ID string to a deterministic Qdrant integer point ID."""
+        return int(hashlib.sha256(memory_id.encode()).hexdigest()[:15], 16)
+
+    def load(self, memory_id: str) -> Memory | None:
         """Retrieve a memory by ID from Qdrant.
 
         Args:
@@ -175,81 +220,56 @@ class QdrantBackend(BaseBackend):
 
         Returns:
             Optional[Memory]: The memory if found.
-
-        Note:
-            Qdrant uses content hashes as point IDs, so this does
-            a scroll+filter. For direct ID lookup, use the file backend.
         """
         if not self._ensure_initialized():
             return None
 
-        from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-        results = self._client.scroll(
-            collection_name=self.collection,
-            scroll_filter=Filter(
-                must=[
-                    FieldCondition(
-                        key="memory_json",
-                        match=MatchValue(value=memory_id),
-                    )
-                ]
-            ),
-            limit=1,
-        )
-
-        points = results[0] if results else []
-        if not points:
-            return None
-
         try:
+            points = self._client.retrieve(
+                collection_name=self.collection,
+                ids=[self._id_to_point_id(memory_id)],
+                with_payload=True,
+            )
+            if not points:
+                return None
             return Memory.model_validate_json(points[0].payload["memory_json"])
         except Exception:
             return None
 
     def delete(self, memory_id: str) -> bool:
-        """Remove a memory from Qdrant by scrolling for it.
+        """Remove a memory from Qdrant by its deterministic point ID.
+
+        Returns False if the memory was not found.
 
         Args:
             memory_id: The memory identifier.
 
         Returns:
-            bool: True if something was deleted.
+            bool: True if the memory existed and was deleted, False otherwise.
         """
         if not self._ensure_initialized():
             return False
 
-        from qdrant_client.models import FieldCondition, Filter, MatchValue
-
-        # Reason: Qdrant doesn't support delete-by-payload natively,
-        # so we scroll to find the point ID then delete by point ID.
-        results = self._client.scroll(
-            collection_name=self.collection,
-            scroll_filter=Filter(
-                must=[
-                    FieldCondition(
-                        key="memory_json",
-                        match=MatchValue(value=memory_id),
-                    )
-                ]
-            ),
-            limit=1,
-        )
-
-        points = results[0] if results else []
-        if not points:
+        try:
+            points = self._client.retrieve(
+                collection_name=self.collection,
+                ids=[self._id_to_point_id(memory_id)],
+                with_payload=False,
+            )
+            if not points:
+                return False
+            self._client.delete(
+                collection_name=self.collection,
+                points_selector=[self._id_to_point_id(memory_id)],
+            )
+            return True
+        except Exception:
             return False
 
-        self._client.delete(
-            collection_name=self.collection,
-            points_selector=[points[0].id],
-        )
-        return True
-
     def list_memories(
         self,
-        layer: Optional[MemoryLayer] = None,
-        tags: Optional[list[str]] = None,
+        layer: MemoryLayer | None = None,
+        tags: list[str] | None = None,
         limit: int = 50,
     ) -> list[Memory]:
         """List memories from Qdrant with filtering.
@@ -274,9 +294,7 @@ class QdrantBackend(BaseBackend):
             )
         if tags:
             for tag in tags:
-                must_conditions.append(
-                    FieldCondition(key="tags", match=MatchValue(value=tag))
-                )
+                must_conditions.append(FieldCondition(key="tags", match=MatchValue(value=tag)))
 
         scroll_filter = Filter(must=must_conditions) if must_conditions else None
 
@@ -324,9 +342,7 @@ class QdrantBackend(BaseBackend):
         memories = []
         for scored_point in results:
             try:
-                mem = Memory.model_validate_json(
-                    scored_point.payload["memory_json"]
-                )
+                mem = Memory.model_validate_json(scored_point.payload["memory_json"])
                 memories.append(mem)
             except Exception:
                 continue
@@ -340,17 +356,20 @@ class QdrantBackend(BaseBackend):
             dict: Status with connection and collection info.
         """
         if not self._ensure_initialized():
+            error_msg = self._last_error or (
+                "Not initialized (missing dependencies or connection failed)"
+            )
             return {
                 "ok": False,
-                "backend": "QdrantBackend",
-                "error": "Not initialized (missing dependencies or connection failed)",
+                "backend": "SKVectorBackend",
+                "error": error_msg,
             }
 
         try:
             info = self._client.get_collection(self.collection)
             return {
                 "ok": True,
-                "backend": "QdrantBackend",
+                "backend": "SKVectorBackend",
                 "url": self.url,
                 "collection": self.collection,
                 "points_count": info.points_count,
@@ -359,6 +378,6 @@ class QdrantBackend(BaseBackend):
         except Exception as e:
             return {
                 "ok": False,
-                "backend": "QdrantBackend",
+                "backend": "SKVectorBackend",
                 "error": str(e),
             }