memory-reuse 0.1.0__py3-none-any.whl

memory_reuse/__init__.py

@@ -0,0 +1,44 @@
+"""memory-reuse — execution cache layer for AI agents.
+
+Reduces LLM and tool call costs by caching results with exact-match hashing,
+TTL support, multi-scope isolation (global / user / session), and first-class
+LangGraph integration.
+
+Quick start::
+
+    from memory_reuse import MemoryCache, CacheConfig
+
+    cache = MemoryCache()                 # in-memory backend, 1-hour TTL
+    cache.set_context(user_id="alice")
+
+    # LangGraph decorator
+    from memory_reuse.integrations import cached_tool
+
+    @cached_tool(cache, scope="user", ttl=300)
+    async def search(query: str) -> list[str]:
+        ...
+"""
+
+from memory_reuse.config import CacheConfig
+from memory_reuse.core import MemoryCache
+from memory_reuse.exceptions import (
+    AgentMemoryError,
+    BackendConnectionError,
+    BackendNotAvailableError,
+    InvalidTTLError,
+    ScopeViolationError,
+)
+from memory_reuse.stats import CacheStats
+
+__all__ = [
+    "MemoryCache",
+    "CacheConfig",
+    "CacheStats",
+    "AgentMemoryError",
+    "BackendConnectionError",
+    "BackendNotAvailableError",
+    "ScopeViolationError",
+    "InvalidTTLError",
+]
+
+__version__ = "0.1.0"

memory_reuse/_utils.py

@@ -0,0 +1,125 @@
+"""Internal utilities for key building, hashing, and serialisation.
+
+These are implementation details — do not import from outside this package.
+"""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import json
+import re
+from typing import Any
+
+# Characters allowed in cache key segments (alphanumeric, dash, underscore, dot)
+_SAFE_KEY_RE = re.compile(r"[^a-zA-Z0-9_\-.]")
+
+
+def sanitize_key(key: str) -> str:
+    """Replace unsafe characters in a key segment with underscores.
+
+    Args:
+        key: Raw key segment string.
+
+    Returns:
+        A string where any character not matching ``[a-zA-Z0-9_\\-.]`` is
+        replaced with ``_``.
+
+    Example::
+
+        >>> sanitize_key("user@example.com")
+        'user_example.com'
+    """
+    return _SAFE_KEY_RE.sub("_", key)
+
+
+def build_cache_key(prefix: str, scope: str, scope_id: str | None, *parts: Any) -> str:
+    """Build a namespaced, deterministic cache key.
+
+    The resulting key follows the pattern::
+
+        <prefix>:<scope>:<scope_id>:<hash_of_parts>
+
+    When ``scope`` is ``"global"`` the ``scope_id`` segment is omitted.
+
+    Args:
+        prefix: Top-level namespace (e.g. ``"agentmem"``).
+        scope: One of ``"global"``, ``"user"``, or ``"session"``.
+        scope_id: Identifier for the scope (user ID or session ID).
+            Must be provided for non-global scopes.
+        *parts: Arbitrary values that together identify the cached item.
+            They are JSON-serialised and hashed.
+
+    Returns:
+        A colon-separated cache key string.
+
+    Raises:
+        ValueError: If a non-global scope is used without a ``scope_id``.
+    """
+    if scope != "global" and not scope_id:
+        raise ValueError(f"scope_id is required for scope='{scope}'")
+
+    parts_hash = hash_value(list(parts))
+    safe_prefix = sanitize_key(prefix)
+    safe_scope = sanitize_key(scope)
+
+    if scope == "global":
+        return f"{safe_prefix}:{safe_scope}:{parts_hash}"
+
+    safe_scope_id = sanitize_key(scope_id)  # type: ignore[arg-type]
+    return f"{safe_prefix}:{safe_scope}:{safe_scope_id}:{parts_hash}"
+
+
+def hash_value(value: Any) -> str:
+    """Produce a 32-character SHA-256 hex digest of a JSON-serialised value.
+
+    Keys in mappings are sorted to ensure deterministic output regardless of
+    insertion order.
+
+    Args:
+        value: Any JSON-serialisable value.
+
+    Returns:
+        The first 32 hex characters of the SHA-256 digest.
+
+    Raises:
+        TypeError: If ``value`` cannot be JSON-serialised.
+    """
+    serialised = json.dumps(value, sort_keys=True, ensure_ascii=False, default=str)
+    digest = hashlib.sha256(serialised.encode("utf-8")).hexdigest()
+    return digest[:32]
+
+
+def serialize_value(value: Any) -> bytes:
+    """Serialise and gzip-compress a value for storage in the backend.
+
+    Args:
+        value: Any JSON-serialisable value.
+
+    Returns:
+        gzip-compressed JSON bytes.
+
+    Raises:
+        TypeError: If ``value`` cannot be JSON-serialised.
+    """
+    raw = json.dumps(value, sort_keys=True, ensure_ascii=False, default=str).encode("utf-8")
+    return gzip.compress(raw, compresslevel=6)
+
+
+def deserialize_value(data: bytes) -> Any:
+    """Decompress and deserialise bytes produced by :func:`serialize_value`.
+
+    Args:
+        data: gzip-compressed JSON bytes.
+
+    Returns:
+        The original Python object.
+
+    Raises:
+        ValueError: If the data cannot be decompressed or parsed.
+    """
+    try:
+        raw = gzip.decompress(data)
+        return json.loads(raw.decode("utf-8"))
+    except Exception as exc:
+        raise ValueError(f"Failed to deserialise cached value: {exc}") from exc

memory_reuse/backends/__init__.py

@@ -0,0 +1,21 @@
+"""Cache backend implementations for memory-reuse.
+
+Available backends:
+
+* :class:`~memory_reuse.backends.memory.InMemoryBackend` — zero-dependency,
+  in-process storage with LRU eviction and TTL support.
+* :class:`~memory_reuse.backends.redis.RedisBackend` — Redis-backed storage
+  (requires ``pip install memory-reuse[redis]``).
+"""
+
+from memory_reuse.backends.base import AbstractBackend
+from memory_reuse.backends.memory import InMemoryBackend
+
+__all__ = ["AbstractBackend", "InMemoryBackend"]
+
+try:
+    from memory_reuse.backends.redis import RedisBackend  # noqa: F401
+
+    __all__.append("RedisBackend")
+except ImportError:
+    pass

memory_reuse/backends/base.py

@@ -0,0 +1,76 @@
+"""Abstract base class for cache backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class AbstractBackend(ABC):
+    """Interface that all cache backends must implement.
+
+    Every method is a coroutine so that network-bound backends (e.g. Redis)
+    can be awaited without blocking the event loop, while the in-memory
+    backend simply returns immediately.
+
+    Implementors should document their own connection-lifecycle behaviour
+    (lazy vs eager connection, reconnect logic, etc.).
+    """
+
+    @abstractmethod
+    async def get(self, key: str) -> bytes | None:
+        """Retrieve the raw bytes stored under ``key``.
+
+        Args:
+            key: The cache key to look up.
+
+        Returns:
+            The stored bytes, or ``None`` if the key does not exist or has
+            expired.
+        """
+
+    @abstractmethod
+    async def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+        """Store ``value`` under ``key``.
+
+        Args:
+            key: The cache key.
+            value: Raw bytes to store (typically gzip-compressed JSON).
+            ttl: Time-to-live in seconds. ``None`` means the entry never
+                expires. A backend may ignore this if it does not support TTL.
+        """
+
+    @abstractmethod
+    async def delete(self, key: str) -> None:
+        """Remove the entry for ``key`` if it exists.
+
+        Args:
+            key: The cache key to remove. A no-op if the key does not exist.
+        """
+
+    @abstractmethod
+    async def exists(self, key: str) -> bool:
+        """Check whether a non-expired entry exists for ``key``.
+
+        Args:
+            key: The cache key to check.
+
+        Returns:
+            ``True`` if the key exists and has not expired, ``False``
+            otherwise.
+        """
+
+    @abstractmethod
+    async def flush(self) -> None:
+        """Delete all entries managed by this backend instance.
+
+        Use with caution in production — this removes every cached value.
+        """
+
+    @abstractmethod
+    async def ping(self) -> bool:
+        """Check backend connectivity.
+
+        Returns:
+            ``True`` if the backend is reachable and functioning, ``False``
+            otherwise. Should not raise.
+        """

memory_reuse/backends/memory.py

@@ -0,0 +1,170 @@
+"""In-memory cache backend with TTL support and LRU eviction."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+
+from memory_reuse.backends.base import AbstractBackend
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_MAX_ENTRIES = 10_000
+
+
+@dataclass
+class _Entry:
+    """Internal storage wrapper for a cached value with optional expiry."""
+
+    value: bytes
+    expires_at: float | None  # Unix timestamp, or None for no expiry
+
+
+class InMemoryBackend(AbstractBackend):
+    """Fully in-memory cache backend — no external dependencies required.
+
+    Features:
+
+    * **TTL** — entries are lazily expired on access.
+    * **LRU eviction** — when ``max_entries`` is reached the least-recently-used
+      entry is dropped to make room for the new one.
+    * **Thread-safe** — an :class:`asyncio.Lock` serialises all mutations.
+
+    Args:
+        max_entries: Maximum number of entries to hold before LRU eviction
+            kicks in. Defaults to 10 000.
+
+    Example::
+
+        backend = InMemoryBackend(max_entries=500)
+        await backend.set("key", b"value", ttl=60)
+        data = await backend.get("key")
+    """
+
+    def __init__(self, max_entries: int = _DEFAULT_MAX_ENTRIES) -> None:
+        if max_entries <= 0:
+            raise ValueError(f"max_entries must be positive, got {max_entries}")
+        self._max_entries = max_entries
+        # OrderedDict used as an ordered map: most-recently-used at the end
+        self._store: OrderedDict[str, _Entry] = OrderedDict()
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------
+    # AbstractBackend implementation
+    # ------------------------------------------------------------------
+
+    async def get(self, key: str) -> bytes | None:
+        """Return stored bytes for ``key``, or ``None`` on miss/expiry.
+
+        Args:
+            key: Cache key to look up.
+
+        Returns:
+            Stored bytes or ``None``.
+        """
+        async with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return None
+            if self._is_expired(entry):
+                del self._store[key]
+                logger.debug("InMemoryBackend: key expired, removed from store")
+                return None
+            # Move to end (most recently used)
+            self._store.move_to_end(key)
+            return entry.value
+
+    async def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+        """Store ``value`` under ``key`` with an optional TTL.
+
+        If the store is at capacity, the LRU entry is evicted first.
+
+        Args:
+            key: Cache key.
+            value: Bytes to store.
+            ttl: Time-to-live in seconds. ``None`` means no expiry.
+        """
+        expires_at: float | None = None
+        if ttl is not None:
+            expires_at = time.monotonic() + ttl
+
+        async with self._lock:
+            if key in self._store:
+                # Update in place and move to end
+                self._store[key] = _Entry(value=value, expires_at=expires_at)
+                self._store.move_to_end(key)
+            else:
+                if len(self._store) >= self._max_entries:
+                    evicted_key, _ = self._store.popitem(last=False)
+                    logger.debug("InMemoryBackend: LRU eviction triggered")
+                self._store[key] = _Entry(value=value, expires_at=expires_at)
+
+    async def delete(self, key: str) -> None:
+        """Remove the entry for ``key``.
+
+        Args:
+            key: Cache key to remove. No-op if the key does not exist.
+        """
+        async with self._lock:
+            self._store.pop(key, None)
+
+    async def exists(self, key: str) -> bool:
+        """Return ``True`` if ``key`` exists and has not expired.
+
+        Args:
+            key: Cache key to check.
+
+        Returns:
+            Boolean existence flag.
+        """
+        async with self._lock:
+            entry = self._store.get(key)
+            if entry is None:
+                return False
+            if self._is_expired(entry):
+                del self._store[key]
+                return False
+            return True
+
+    async def flush(self) -> None:
+        """Remove all entries from the store."""
+        async with self._lock:
+            self._store.clear()
+        logger.debug("InMemoryBackend: store flushed")
+
+    async def ping(self) -> bool:
+        """Always returns ``True`` — the in-memory backend is always available.
+
+        Returns:
+            ``True``
+        """
+        return True
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _is_expired(self, entry: _Entry) -> bool:
+        """Check whether an entry has passed its TTL.
+
+        Args:
+            entry: The :class:`_Entry` to inspect.
+
+        Returns:
+            ``True`` if the entry has an expiry time that is in the past.
+        """
+        if entry.expires_at is None:
+            return False
+        return time.monotonic() >= entry.expires_at
+
+    @property
+    def size(self) -> int:
+        """Current number of entries in the store (including not-yet-evicted expired ones).
+
+        Returns:
+            Integer entry count.
+        """
+        return len(self._store)

memory_reuse/backends/redis.py

@@ -0,0 +1,217 @@
+"""Redis cache backend using redis.asyncio."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from typing import TYPE_CHECKING, cast
+
+from memory_reuse.backends.base import AbstractBackend
+from memory_reuse.exceptions import BackendConnectionError, BackendNotAvailableError
+
+if TYPE_CHECKING:
+    # Only imported at runtime when redis is available
+    import redis.asyncio as aioredis
+
+logger = logging.getLogger(__name__)
+
+_MAX_CONNECTIONS = 20
+
+
+class RedisBackend(AbstractBackend):
+    """Cache backend that stores data in Redis.
+
+    Requires the optional ``redis`` extra::
+
+        pip install memory-reuse[redis]
+
+    The connection is established lazily on the first operation.
+    Connection errors are converted to :exc:`BackendConnectionError` so
+    callers do not need to handle redis-specific exceptions.
+
+    Args:
+        url: Redis connection URL (e.g. ``redis://localhost:6379/0``).
+            Prefer reading this from the ``MEMORY_REUSE_REDIS_URL``
+            environment variable rather than hardcoding it.
+        max_connections: Maximum size of the underlying connection pool.
+            Defaults to 20.
+
+    Example::
+
+        import os
+        backend = RedisBackend(url=os.environ["MEMORY_REUSE_REDIS_URL"])
+        await backend.set("key", b"value", ttl=300)
+        data = await backend.get("key")
+    """
+
+    def __init__(self, url: str, max_connections: int = _MAX_CONNECTIONS) -> None:
+        self._url = url
+        self._max_connections = max_connections
+        self._client: aioredis.Redis | None = None  # type: ignore[type-arg]
+
+    # ------------------------------------------------------------------
+    # Connection management
+    # ------------------------------------------------------------------
+
+    async def _get_client(self) -> aioredis.Redis:  # type: ignore[type-arg]
+        """Return the Redis client, creating it on first call.
+
+        Returns:
+            An initialised ``redis.asyncio.Redis`` client.
+
+        Raises:
+            BackendNotAvailableError: If the ``redis`` package is not installed.
+            BackendConnectionError: If the connection attempt fails.
+        """
+        if self._client is not None:
+            return self._client
+
+        try:
+            import redis.asyncio as aioredis
+        except ImportError as exc:
+            raise BackendNotAvailableError(
+                "Redis backend requires 'redis' package. "
+                "Install it with: pip install memory-reuse[redis]"
+            ) from exc
+
+        try:
+            pool = aioredis.ConnectionPool.from_url(
+                self._url,
+                max_connections=self._max_connections,
+                decode_responses=False,
+            )
+            self._client = aioredis.Redis(connection_pool=pool)
+            # Validate connectivity
+            await self._client.ping()
+        except Exception as exc:
+            self._client = None
+            # Deliberately not logging self._url to avoid leaking credentials
+            logger.error("RedisBackend: failed to connect to Redis server")
+            raise BackendConnectionError(
+                "Could not connect to Redis. Check your connection URL and network."
+            ) from exc
+
+        return self._client
+
+    # ------------------------------------------------------------------
+    # AbstractBackend implementation
+    # ------------------------------------------------------------------
+
+    async def get(self, key: str) -> bytes | None:
+        """Retrieve raw bytes stored under ``key``.
+
+        Args:
+            key: Cache key.
+
+        Returns:
+            Stored bytes or ``None`` on miss.
+
+        Raises:
+            BackendConnectionError: On Redis connectivity failure.
+        """
+        client = await self._get_client()
+        try:
+            # The client is created with decode_responses=False, so values are
+            # always raw bytes (or None on a miss). Cast to satisfy the type
+            # checker, which infers the broader bytes | str | None union.
+            value = await client.get(key)
+            return cast("bytes | None", value)
+        except Exception as exc:
+            logger.error("RedisBackend: GET failed for key prefix '%s'", key[:8])
+            raise BackendConnectionError("Redis GET operation failed") from exc
+
+    async def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+        """Store ``value`` under ``key``.
+
+        Args:
+            key: Cache key.
+            value: Bytes to store.
+            ttl: Time-to-live in seconds. ``None`` means no expiry.
+
+        Raises:
+            BackendConnectionError: On Redis connectivity failure.
+        """
+        client = await self._get_client()
+        try:
+            if ttl is not None:
+                await client.setex(key, ttl, value)
+            else:
+                await client.set(key, value)
+        except Exception as exc:
+            logger.error("RedisBackend: SET failed for key prefix '%s'", key[:8])
+            raise BackendConnectionError("Redis SET operation failed") from exc
+
+    async def delete(self, key: str) -> None:
+        """Remove the entry for ``key``.
+
+        Args:
+            key: Cache key to remove.
+
+        Raises:
+            BackendConnectionError: On Redis connectivity failure.
+        """
+        client = await self._get_client()
+        try:
+            await client.delete(key)
+        except Exception as exc:
+            logger.error("RedisBackend: DELETE failed for key prefix '%s'", key[:8])
+            raise BackendConnectionError("Redis DELETE operation failed") from exc
+
+    async def exists(self, key: str) -> bool:
+        """Check whether ``key`` exists in Redis.
+
+        Args:
+            key: Cache key.
+
+        Returns:
+            ``True`` if the key exists (and has not expired in Redis).
+
+        Raises:
+            BackendConnectionError: On Redis connectivity failure.
+        """
+        client = await self._get_client()
+        try:
+            return bool(await client.exists(key))
+        except Exception as exc:
+            logger.error("RedisBackend: EXISTS failed for key prefix '%s'", key[:8])
+            raise BackendConnectionError("Redis EXISTS operation failed") from exc
+
+    async def flush(self) -> None:
+        """Delete all keys in the current Redis database.
+
+        Warning:
+            This calls ``FLUSHDB`` on the connected database. Use with care
+            in shared Redis environments.
+
+        Raises:
+            BackendConnectionError: On Redis connectivity failure.
+        """
+        client = await self._get_client()
+        try:
+            await client.flushdb()
+            logger.debug("RedisBackend: database flushed")
+        except Exception as exc:
+            raise BackendConnectionError("Redis FLUSHDB operation failed") from exc
+
+    async def ping(self) -> bool:
+        """Check Redis connectivity.
+
+        Returns:
+            ``True`` if Redis responds to PING, ``False`` on any error.
+        """
+        try:
+            client = await self._get_client()
+            return await client.ping()
+        except Exception:
+            return False
+
+    async def close(self) -> None:
+        """Close the connection pool gracefully.
+
+        Call this during application shutdown to release Redis connections.
+        """
+        if self._client is not None:
+            with contextlib.suppress(Exception):
+                await self._client.aclose()
+            self._client = None
+            logger.debug("RedisBackend: connection pool closed")

memory_reuse/cache/__init__.py

@@ -0,0 +1,12 @@
+"""Cache layer implementations for memory-reuse.
+
+* :class:`~memory_reuse.cache.exact.ExactCache` — hash-keyed cache for
+  LLM responses and other deterministic lookups.
+* :class:`~memory_reuse.cache.tool.ToolCache` — TTL-enforced cache for
+  tool/function call results.
+"""
+
+from memory_reuse.cache.exact import ExactCache
+from memory_reuse.cache.tool import ToolCache
+
+__all__ = ["ExactCache", "ToolCache"]