longcache 0.1.0__py3-none-any.whl

longcache/__init__.py

@@ -0,0 +1,11 @@
+"""
+LongCache — Semantic similarity cache for LLM/RAG pipelines.
+
+Cut repeat query costs by 40%+ by caching semantically similar queries.
+"""
+
+from longcache.core.cache import LongCache
+from longcache.config import CacheConfig
+
+__version__ = "0.1.0"
+__all__ = ["LongCache", "CacheConfig"]

longcache/backends/__init__.py

@@ -0,0 +1,21 @@
+"""Cache storage backends."""
+
+from longcache.backends.base import AbstractCacheBackend
+from longcache.backends.sqlite import SQLiteCacheBackend
+from longcache.backends.memory import InMemoryCacheBackend
+
+__all__ = ["AbstractCacheBackend", "SQLiteCacheBackend", "InMemoryCacheBackend"]
+
+
+# Lazy import for Redis backend — only available when redis extra is installed
+def get_redis_backend():
+    """Import and return RedisCacheBackend. Raises ImportError if redis is not installed."""
+    try:
+        from longcache.backends.redis import RedisCacheBackend
+
+        return RedisCacheBackend
+    except ImportError:
+        raise ImportError(
+            "Redis backend requires the 'redis' extra. "
+            "Install with: uv pip install longcache[redis]"
+        )

longcache/backends/async_redis.py

@@ -0,0 +1,274 @@
+"""
+Async Redis cache backend using redis.asyncio.
+
+Drop-in async replacement for RedisCacheBackend.
+Use this in async FastAPI/Starlette applications.
+
+    backend = AsyncRedisCacheBackend(redis_url="redis://localhost:6379/0")
+    entry_id = await backend.store(entry)
+    result = await backend.retrieve(entry_id)
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+import asyncio
+from typing import Optional
+
+import numpy as np
+
+from longcache.core.entry import CacheEntry
+
+
+class AsyncRedisCacheBackend:
+    """
+    Async Redis-based cache backend for distributed deployments.
+    """
+
+    KEY_PREFIX = "longcache:entry"
+    NAMESPACE_SET = "longcache:namespaces"
+    ID_COUNTER = "longcache:id_counter"
+
+    def __init__(
+        self,
+        redis_url: str = "redis://localhost:6379/0",
+        max_entries: int = 10_000,
+    ):
+        try:
+            from redis.asyncio import Redis
+        except ImportError:
+            raise ImportError(
+                "Async Redis backend requires the 'redis' extra. "
+                "Install with: uv pip install longcache[redis]"
+            )
+
+        self._redis_url = redis_url
+        self._max_entries = max_entries
+        self._lock = asyncio.Lock()
+        self._client = Redis.from_url(redis_url, decode_responses=True)
+
+    def _entry_key(self, entry_id: int) -> str:
+        return f"{self.KEY_PREFIX}:{entry_id}"
+
+    def _namespace_key(self, namespace: str) -> str:
+        return f"longcache:ns:{namespace}"
+
+    def _vector_to_str(self, vector: np.ndarray) -> str:
+        return base64.b64encode(vector.tobytes()).decode("ascii")
+
+    def _str_to_vector(self, vector_str: str) -> np.ndarray:
+        return np.frombuffer(base64.b64decode(vector_str), dtype=np.float32).copy()
+
+    async def store(self, entry: CacheEntry) -> int:
+        async with self._lock:
+            entry_id = await self._client.incr(self.ID_COUNTER)
+
+            vector_str = self._vector_to_str(entry.vector) if entry.vector is not None else ""
+            response_json = json.dumps(entry.response, default=str)
+
+            entry_data = {
+                "id": entry_id,
+                "namespace": entry.namespace,
+                "query": entry.query,
+                "vector": vector_str,
+                "response": response_json,
+                "created_at": entry.created_at,
+                "expires_at": entry.expires_at or "",
+                "hit_count": entry.hit_count,
+                "model": entry.model,
+                "system_prompt": entry.system_prompt,
+                "temperature": entry.temperature,
+                "tags": json.dumps(list(entry.tags or [])),
+            }
+
+            key = self._entry_key(entry_id)
+
+            pipe = self._client.pipeline()
+            pipe.hset(key, mapping=entry_data)
+
+            pipe.sadd(self._namespace_key(entry.namespace), entry_id)
+            pipe.sadd(self.NAMESPACE_SET, entry.namespace)
+
+            for tag in entry.tags or []:
+                pipe.sadd(f"longcache:tag:{entry.namespace}:{tag}", entry_id)
+
+            if entry.expires_at is not None:
+                ttl_seconds = max(1, int(entry.expires_at - time.time()))
+                pipe.expire(key, ttl_seconds)
+
+            await pipe.execute()
+
+        # Note: outside the lock — _enforce_max_entries() calls evict_oldest()
+        # which calls delete(), and self._lock is not reentrant.
+        await self._enforce_max_entries(entry.namespace)
+        return entry_id
+
+    async def retrieve(self, entry_id: int) -> Optional[CacheEntry]:
+        key = self._entry_key(entry_id)
+        data = await self._client.hgetall(key)
+
+        if not data:
+            return None
+
+        entry = self._data_to_entry(data)
+        if entry.is_expired():
+            await self.delete(entry_id)
+            return None
+
+        return entry
+
+    def _data_to_entry(self, data: dict) -> CacheEntry:
+        vector = None
+        if data.get("vector"):
+            vector = self._str_to_vector(data["vector"])
+
+        response = data.get("response", "")
+        if isinstance(response, str):
+            try:
+                response = json.loads(response)
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        expires_at = data.get("expires_at")
+        if expires_at == "" or expires_at is None:
+            expires_at = None
+        else:
+            expires_at = float(expires_at)
+
+        tags_raw = data.get("tags")
+        tags = []
+        if tags_raw:
+            try:
+                tags = json.loads(tags_raw)
+            except Exception:
+                pass
+
+        temp_val = data.get("temperature")
+        temperature = float(temp_val) if temp_val not in (None, "") else -1.0
+
+        return CacheEntry(
+            id=int(data["id"]),
+            namespace=data["namespace"],
+            query=data["query"],
+            vector=vector,
+            response=response,
+            created_at=float(data["created_at"]),
+            expires_at=expires_at,
+            hit_count=int(data.get("hit_count", 0)),
+            model=data.get("model", ""),
+            system_prompt=data.get("system_prompt", ""),
+            temperature=temperature,
+            tags=tags,
+        )
+
+    async def delete(self, entry_id: int) -> bool:
+        async with self._lock:
+            key = self._entry_key(entry_id)
+            namespace = await self._client.hget(key, "namespace")
+
+            pipe = self._client.pipeline()
+            pipe.delete(key)
+            if namespace:
+                pipe.srem(self._namespace_key(namespace), entry_id)
+            await pipe.execute()
+            return True
+
+    async def delete_namespace(self, namespace: str) -> int:
+        async with self._lock:
+            ns_key = self._namespace_key(namespace)
+            entry_ids = await self._client.smembers(ns_key)
+
+            if not entry_ids:
+                return 0
+
+            pipe = self._client.pipeline()
+            for entry_id in entry_ids:
+                pipe.delete(self._entry_key(int(entry_id)))
+            pipe.delete(ns_key)
+            pipe.srem(self.NAMESPACE_SET, namespace)
+            await pipe.execute()
+
+            return len(entry_ids)
+
+    async def delete_by_tag(self, tag: str, namespace: str) -> int:
+        """
+        Delete all entries in a namespace carrying the given tag.
+
+        Args:
+            tag: The tag string to match.
+            namespace: Scope the deletion to this namespace.
+
+        Returns:
+            The number of entries deleted.
+        """
+        tag_key = f"longcache:tag:{namespace}:{tag}"
+        async with self._lock:
+            entry_ids = await self._client.smembers(tag_key)
+            if not entry_ids:
+                return 0
+
+            pipe = self._client.pipeline()
+            for entry_id in entry_ids:
+                pipe.delete(self._entry_key(int(entry_id)))
+                pipe.srem(self._namespace_key(namespace), entry_id)
+            pipe.delete(tag_key)
+            await pipe.execute()
+            return len(entry_ids)
+
+    async def clear(self) -> int:
+        # Note: delete_namespace() acquires self._lock itself, so we must
+        # NOT hold the lock here too — asyncio.Lock is not reentrant and
+        # doing so would deadlock.
+        namespaces = await self._client.smembers(self.NAMESPACE_SET)
+        total = 0
+        for ns in namespaces:
+            total += await self.delete_namespace(ns)
+        return total
+
+    async def count(self, namespace: str) -> int:
+        ns_key = self._namespace_key(namespace)
+        return await self._client.scard(ns_key)
+
+    async def list_entries(self, namespace: str) -> list[CacheEntry]:
+        ns_key = self._namespace_key(namespace)
+        entry_ids = await self._client.smembers(ns_key)
+
+        entries = []
+        for entry_id in entry_ids:
+            entry = await self.retrieve(int(entry_id))
+            if entry is not None and not entry.is_expired():
+                entries.append(entry)
+
+        return entries
+
+    async def update_hit_count(self, entry_id: int) -> None:
+        key = self._entry_key(entry_id)
+        await self._client.hincrby(key, "hit_count", 1)
+
+    async def evict_oldest(self, namespace: str, count: int) -> int:
+        # Note: delete() acquires self._lock itself, so we must not hold
+        # the lock here too — asyncio.Lock is not reentrant.
+        entries = await self.list_entries(namespace)
+        entries.sort(key=lambda e: e.created_at)
+
+        evicted = 0
+        for entry in entries[:count]:
+            if await self.delete(entry.id):
+                evicted += 1
+
+        return evicted
+
+    async def get_expired(self, namespace: str) -> list[int]:
+        entries = await self.list_entries(namespace)
+        return [e.id for e in entries if e.is_expired()]
+
+    async def _enforce_max_entries(self, namespace: str) -> None:
+        count = await self.count(namespace)
+        if count > self._max_entries:
+            excess = count - self._max_entries
+            await self.evict_oldest(namespace, excess)
+
+    def __repr__(self) -> str:
+        return f"AsyncRedisCacheBackend(redis_url={self._redis_url!r})"

longcache/backends/base.py

@@ -0,0 +1,167 @@
+"""
+Abstract base class for cache backends.
+
+All backends must implement this interface to provide
+consistent storage semantics regardless of the underlying
+storage engine.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from longcache.core.entry import CacheEntry
+
+
+class AbstractCacheBackend(ABC):
+    """
+    Abstract interface for LongCache storage backends.
+
+    All methods operate on CacheEntry objects, which encapsulate
+    the query, vector, response, and metadata. Backends are
+    responsible for serialization/deserialization as needed.
+    """
+
+    @abstractmethod
+    def store(self, entry: CacheEntry) -> int:
+        """
+        Store a cache entry and return its unique ID.
+
+        Args:
+            entry: The CacheEntry to store. May not have an ID assigned yet.
+
+        Returns:
+            The unique integer ID assigned to the stored entry.
+        """
+        ...
+
+    @abstractmethod
+    def retrieve(self, entry_id: int) -> Optional[CacheEntry]:
+        """
+        Retrieve a cache entry by its ID.
+
+        Args:
+            entry_id: The unique ID of the entry to retrieve.
+
+        Returns:
+            CacheEntry if found, None otherwise.
+        """
+        ...
+
+    @abstractmethod
+    def delete(self, entry_id: int) -> bool:
+        """
+        Delete a cache entry by its ID.
+
+        Args:
+            entry_id: The unique ID of the entry to delete.
+
+        Returns:
+            True if the entry was deleted, False if not found.
+        """
+        ...
+
+    @abstractmethod
+    def delete_namespace(self, namespace: str) -> int:
+        """
+        Delete all entries in a namespace.
+
+        Args:
+            namespace: The namespace to clear.
+
+        Returns:
+            The number of entries deleted.
+        """
+        ...
+
+    @abstractmethod
+    def delete_by_tag(self, tag: str, namespace: str) -> int:
+        """
+        Delete all entries in a namespace carrying the given tag.
+
+        Args:
+            tag: The tag string to match.
+            namespace: Scope the deletion to this namespace.
+
+        Returns:
+            The number of entries deleted.
+        """
+        ...
+
+    @abstractmethod
+    def clear(self) -> int:
+        """
+        Clear all entries across all namespaces.
+
+        Returns:
+            The total number of entries deleted.
+        """
+        ...
+
+    @abstractmethod
+    def count(self, namespace: str) -> int:
+        """
+        Count entries in a namespace.
+
+        Args:
+            namespace: The namespace to count entries in.
+
+        Returns:
+            The number of entries in the namespace.
+        """
+        ...
+
+    @abstractmethod
+    def list_entries(self, namespace: str) -> list[CacheEntry]:
+        """
+        List all non-expired entries in a namespace.
+
+        Used primarily for rebuilding the FAISS index on startup.
+
+        Args:
+            namespace: The namespace to list entries from.
+
+        Returns:
+            List of CacheEntry objects with vectors populated.
+        """
+        ...
+
+    @abstractmethod
+    def update_hit_count(self, entry_id: int) -> None:
+        """
+        Increment the hit count for a cache entry.
+
+        Args:
+            entry_id: The ID of the entry to update.
+        """
+        ...
+
+    @abstractmethod
+    def evict_oldest(self, namespace: str, count: int) -> int:
+        """
+        Evict the oldest entries in a namespace.
+
+        Used for LRU-style eviction when max_entries is exceeded.
+
+        Args:
+            namespace: The namespace to evict entries from.
+            count: The number of entries to evict.
+
+        Returns:
+            The number of entries actually evicted.
+        """
+        ...
+
+    @abstractmethod
+    def get_expired(self, namespace: str) -> list[int]:
+        """
+        Get IDs of all expired entries in a namespace.
+
+        Args:
+            namespace: The namespace to check for expired entries.
+
+        Returns:
+            List of entry IDs that have expired.
+        """
+        ...