longcache 0.1.0__py3-none-any.whl

longcache/integrations/langchain.py

@@ -0,0 +1,316 @@
+"""
+LangChain integration for LongCache.
+
+Provides CachedLLM and CachedChain wrappers that add semantic caching
+to any LangChain LLM or LCEL chain with zero code changes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import Any, Optional, Union
+
+from longcache import LongCache, CacheConfig
+
+
+class CachedLLM:
+    """
+    Wraps any LangChain LLM/ChatModel with semantic caching.
+
+    Drop-in replacement that preserves the full LLM interface.
+    Cache is checked before the LLM is called, and new responses
+    are cached automatically.
+
+    Usage:
+        from langchain_openai import ChatOpenAI
+        from longcache.integrations.langchain import CachedLLM
+
+        llm = CachedLLM(ChatOpenAI(model="gpt-4o"), cache=LongCache())
+        response = llm.invoke("What is the refund policy?")  # same API
+        # Second call with similar query returns cached response instantly
+        response2 = llm.invoke("How do I get a refund?")  # cache HIT
+    """
+
+    def __init__(
+        self,
+        llm: Any,
+        cache: Optional[LongCache] = None,
+        config: Optional[CacheConfig] = None,
+        namespace: str = "langchain",
+    ):
+        """
+        Initialize CachedLLM.
+
+        Args:
+            llm: Any LangChain BaseLLM or BaseChatModel instance.
+            cache: Existing LongCache instance. Creates a new one if not provided.
+            config: CacheConfig for the new cache (ignored if cache is provided).
+            namespace: Default namespace for cache entries.
+        """
+        self.llm = llm
+        self.cache = cache or LongCache(config or CacheConfig(namespace=namespace))
+        self._namespace = namespace
+
+    def _extract_query(self, input: Any) -> str:
+        """
+        Extract a query string from various LangChain input formats.
+
+        Supports:
+            - str: used directly
+            - list of BaseMessage: extracts last HumanMessage content
+            - dict with 'query', 'question', 'input', or 'messages' key
+
+        Args:
+            input: LangChain input in any supported format.
+
+        Returns:
+            Extracted query string.
+        """
+        if isinstance(input, str):
+            return input
+
+        if isinstance(input, list):
+            # Try to extract from message list
+            for msg in reversed(input):
+                if hasattr(msg, "content") and hasattr(msg, "type"):
+                    if msg.type == "human":
+                        return msg.content
+                # Fallback: use last message with content
+                if hasattr(msg, "content"):
+                    return msg.content
+            # Last resort: stringify
+            return str(input[-1]) if input else ""
+
+        if isinstance(input, dict):
+            for key in ("query", "question", "input", "messages", "prompt"):
+                if key in input:
+                    value = input[key]
+                    if isinstance(value, str):
+                        return value
+                    if isinstance(value, list):
+                        return self._extract_query(value)
+                    return str(value)
+
+        return str(input)
+
+    def invoke(self, input: Any, *args, **kwargs) -> Any:
+        """
+        Invoke the LLM with caching.
+
+        Checks the cache first. On a HIT, returns the cached response.
+        On a MISS, calls the LLM and caches the result.
+
+        Args:
+            input: The LLM input (string, messages list, or dict).
+            *args: Additional positional arguments passed to the LLM.
+            **kwargs: Additional keyword arguments passed to the LLM.
+
+        Returns:
+            The LLM response (from cache or fresh invocation).
+        """
+        query_key = self._extract_query(input)
+        cached = self.cache.get(query_key, namespace=self._namespace)
+        if cached is not None:
+            return cached
+
+        result = self.llm.invoke(input, *args, **kwargs)
+        self.cache.set(query_key, result, namespace=self._namespace)
+        return result
+
+    async def ainvoke(self, input: Any, *args, **kwargs) -> Any:
+        """
+        Async invoke the LLM with caching.
+
+        Same as invoke() but uses the async LLM interface.
+
+        Args:
+            input: The LLM input.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The LLM response (from cache or fresh invocation).
+        """
+        query_key = self._extract_query(input)
+        cached = await self.cache.aget(query_key, namespace=self._namespace)
+        if cached is not None:
+            return cached
+
+        result = await self.llm.ainvoke(input, *args, **kwargs)
+        await self.cache.aset(query_key, result, namespace=self._namespace)
+        return result
+
+    def stream(self, input: Any, *args, **kwargs):
+        """
+        Stream the LLM response with caching.
+
+        On a cache HIT, replays the cached response token-by-token.
+        On a MISS, streams from the LLM, collects the response, and caches it.
+
+        Args:
+            input: The LLM input.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Yields:
+            Response chunks (from cache replay or live LLM stream).
+        """
+        query_key = self._extract_query(input)
+        cached = self.cache.get(query_key, namespace=self._namespace)
+
+        if cached is not None:
+            # Replay cached response preserving original whitespace
+            cached_str = str(cached)
+            tokens = re.findall(r"\S+\s*", cached_str)
+            for token in tokens:
+                yield token
+            return
+
+        # Stream from LLM and collect
+        collected_chunks = []
+        for chunk in self.llm.stream(input, *args, **kwargs):
+            collected_chunks.append(chunk)
+            yield chunk
+
+        # Cache the assembled response
+        self.cache.set(query_key, collected_chunks, namespace=self._namespace)
+
+    async def astream(self, input: Any, *args, **kwargs):
+        """
+        Async stream the LLM response with caching.
+
+        Args:
+            input: The LLM input.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Yields:
+            Response chunks.
+        """
+        query_key = self._extract_query(input)
+        cached = await self.cache.aget(query_key, namespace=self._namespace)
+
+        if cached is not None:
+            cached_str = str(cached)
+            tokens = re.findall(r"\S+\s*", cached_str)
+            for token in tokens:
+                yield token
+            return
+
+        collected_chunks = []
+        async for chunk in self.llm.astream(input, *args, **kwargs):
+            collected_chunks.append(chunk)
+            yield chunk
+
+        await self.cache.aset(query_key, collected_chunks, namespace=self._namespace)
+
+    def __getattr__(self, name: str) -> Any:
+        """Proxy all other attributes to the underlying LLM."""
+        return getattr(self.llm, name)
+
+    def __repr__(self) -> str:
+        return f"CachedLLM(llm={self.llm!r}, cache={self.cache!r})"
+
+
+class CachedChain:
+    """
+    Wraps any LCEL Runnable chain with semantic caching.
+
+    Cache key is the final user query string extracted from the chain input.
+    Works with any LCEL chain: prompt | llm | parser, RetrievalQA, etc.
+
+    Usage:
+        from langchain_openai import ChatOpenAI
+        from longcache.integrations.langchain import CachedChain
+
+        chain = prompt | ChatOpenAI() | StrOutputParser()
+        cached_chain = CachedChain(chain, cache=LongCache())
+        result = cached_chain.invoke({"question": "What is RAG?"})
+    """
+
+    def __init__(
+        self,
+        chain: Any,
+        cache: Optional[LongCache] = None,
+        config: Optional[CacheConfig] = None,
+        query_key: str = "question",
+        namespace: str = "langchain_chain",
+    ):
+        """
+        Initialize CachedChain.
+
+        Args:
+            chain: Any LCEL Runnable chain.
+            cache: Existing LongCache instance. Creates a new one if not provided.
+            config: CacheConfig for the new cache (ignored if cache is provided).
+            query_key: Key to extract from input dict as the cache query.
+            namespace: Default namespace for cache entries.
+        """
+        self.chain = chain
+        self.cache = cache or LongCache(config or CacheConfig(namespace=namespace))
+        self.query_key = query_key
+        self._namespace = namespace
+
+    def _extract_query(self, input: Any) -> str:
+        """
+        Extract the query string from chain input.
+
+        Args:
+            input: Chain input (dict or string).
+
+        Returns:
+            The extracted query string.
+        """
+        if isinstance(input, dict):
+            return input.get(self.query_key, str(input))
+        return str(input)
+
+    def invoke(self, input: Any, *args, **kwargs) -> Any:
+        """
+        Invoke the chain with caching.
+
+        Args:
+            input: Chain input (typically a dict with the query key).
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The chain output (from cache or fresh invocation).
+        """
+        query = self._extract_query(input)
+        cached = self.cache.get(query, namespace=self._namespace)
+        if cached is not None:
+            return cached
+
+        result = self.chain.invoke(input, *args, **kwargs)
+        self.cache.set(query, result, namespace=self._namespace)
+        return result
+
+    async def ainvoke(self, input: Any, *args, **kwargs) -> Any:
+        """
+        Async invoke the chain with caching.
+
+        Args:
+            input: Chain input.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The chain output (from cache or fresh invocation).
+        """
+        query = self._extract_query(input)
+        cached = await self.cache.aget(query, namespace=self._namespace)
+        if cached is not None:
+            return cached
+
+        result = await self.chain.ainvoke(input, *args, **kwargs)
+        await self.cache.aset(query, result, namespace=self._namespace)
+        return result
+
+    def __getattr__(self, name: str) -> Any:
+        """Proxy all other attributes to the underlying chain."""
+        return getattr(self.chain, name)
+
+    def __repr__(self) -> str:
+        return f"CachedChain(chain={self.chain!r}, cache={self.cache!r})"

longcache/integrations/langgraph.py

@@ -0,0 +1,150 @@
+"""
+LangGraph integration for LongCache.
+
+Provides CachedState wrapper for semantic caching of agent/graph states.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional
+
+from longcache import LongCache, CacheConfig
+
+
+class CachedState:
+    """
+    Wraps LangGraph state evaluation with semantic caching.
+
+    Can be used as a node in a LangGraph graph to check the semantic cache
+    before executing expensive LLM nodes.
+
+    Usage:
+        from longcache.integrations.langgraph import CachedState
+        from longcache import LongCache
+
+        cache = LongCache()
+
+        def cache_node(state: dict):
+            # Check cache based on the latest message/input
+            return CachedState.check(state, cache, query_key="messages")
+    """
+
+    @staticmethod
+    def check(
+        state: dict,
+        cache: LongCache,
+        query_key: str = "messages",
+        namespace: str = "langgraph",
+    ) -> dict:
+        """
+        Check the cache for a given state.
+
+        Args:
+            state: The LangGraph state dictionary.
+            cache: LongCache instance.
+            query_key: The key in the state to use as the cache query.
+                If it's a list of messages, the last human message is used.
+            namespace: The cache namespace.
+
+        Returns:
+            A dictionary with cache results. If a hit is found, it can be
+            merged back into the state to skip LLM execution.
+        """
+        query_input = state.get(query_key)
+
+        # Extract string query
+        query = ""
+        if isinstance(query_input, str):
+            query = query_input
+        elif isinstance(query_input, list):
+            for msg in reversed(query_input):
+                if hasattr(msg, "content") and getattr(msg, "type", "") == "human":
+                    query = msg.content
+                    break
+                elif hasattr(msg, "content"):
+                    query = msg.content
+            if not query and query_input:
+                query = str(query_input[-1])
+        elif isinstance(query_input, dict):
+            query = query_input.get("query", str(query_input))
+        else:
+            query = str(query_input)
+
+        if not query:
+            return {"__cache_hit": False}
+
+        cached = cache.get(query, namespace=namespace)
+        if cached is not None:
+            return {"__cache_hit": True, "cached_response": cached}
+
+        return {"__cache_hit": False, "cached_query": query}
+
+    @staticmethod
+    async def acheck(
+        state: dict,
+        cache: LongCache,
+        query_key: str = "messages",
+        namespace: str = "langgraph",
+    ) -> dict:
+        """Async version of check()."""
+        query_input = state.get(query_key)
+
+        # Extract string query
+        query = ""
+        if isinstance(query_input, str):
+            query = query_input
+        elif isinstance(query_input, list):
+            for msg in reversed(query_input):
+                if hasattr(msg, "content") and getattr(msg, "type", "") == "human":
+                    query = msg.content
+                    break
+                elif hasattr(msg, "content"):
+                    query = msg.content
+            if not query and query_input:
+                query = str(query_input[-1])
+        elif isinstance(query_input, dict):
+            query = query_input.get("query", str(query_input))
+        else:
+            query = str(query_input)
+
+        if not query:
+            return {"__cache_hit": False}
+
+        cached = await cache.aget(query, namespace=namespace)
+        if cached is not None:
+            return {"__cache_hit": True, "cached_response": cached}
+
+        return {"__cache_hit": False, "cached_query": query}
+
+    @staticmethod
+    def save(
+        state: dict,
+        response: Any,
+        cache: LongCache,
+        namespace: str = "langgraph",
+    ) -> None:
+        """
+        Save a new response to the cache.
+
+        Args:
+            state: The state dictionary (must contain 'cached_query' from check).
+            response: The response to cache.
+            cache: LongCache instance.
+            namespace: The cache namespace.
+        """
+        query = state.get("cached_query")
+        if query:
+            cache.set(query, response, namespace=namespace)
+
+    @staticmethod
+    async def asave(
+        state: dict,
+        response: Any,
+        cache: LongCache,
+        namespace: str = "langgraph",
+    ) -> None:
+        """Async version of save()."""
+        query = state.get("cached_query")
+        if query:
+            await cache.aset(query, response, namespace=namespace)

longcache/integrations/llamaindex.py

@@ -0,0 +1,103 @@
+"""
+LlamaIndex integration for LongCache.
+
+Provides CachedQueryEngine that wraps any LlamaIndex query engine
+with semantic caching.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from longcache import LongCache, CacheConfig
+
+
+class CachedQueryEngine:
+    """
+    Wraps a LlamaIndex query engine with semantic caching.
+
+    Intercepts queries before they reach the LlamaIndex retrieval
+    and generation pipeline. On cache HIT, returns the cached
+    response instantly.
+
+    Requires the 'llamaindex' extra: uv pip install longcache[llamaindex]
+
+    Usage:
+        from llama_index.core import VectorStoreIndex
+        from longcache.integrations.llamaindex import CachedQueryEngine
+
+        index = VectorStoreIndex.from_documents(documents)
+        engine = index.as_query_engine()
+
+        cached_engine = CachedQueryEngine(engine, cache=LongCache())
+        response = cached_engine.query("What is RAG?")
+    """
+
+    def __init__(
+        self,
+        query_engine: Any,
+        cache: Optional[LongCache] = None,
+        config: Optional[CacheConfig] = None,
+        namespace: str = "llamaindex",
+    ):
+        """
+        Initialize CachedQueryEngine.
+
+        Args:
+            query_engine: A LlamaIndex query engine instance.
+            cache: Existing LongCache instance. Creates a new one if not provided.
+            config: CacheConfig for the new cache (ignored if cache is provided).
+            namespace: Default namespace for cache entries.
+        """
+        self.query_engine = query_engine
+        self.cache = cache or LongCache(config or CacheConfig(namespace=namespace))
+        self._namespace = namespace
+
+    def query(self, query_str: str, **kwargs) -> Any:
+        """
+        Query the engine with caching.
+
+        Checks the cache first using semantic similarity. On a HIT,
+        returns the cached response. On a MISS, runs the full query
+        pipeline and caches the result.
+
+        Args:
+            query_str: The query string.
+            **kwargs: Additional keyword arguments passed to the query engine.
+
+        Returns:
+            The query response (from cache or fresh invocation).
+        """
+        cached = self.cache.get(query_str, namespace=self._namespace)
+        if cached is not None:
+            return cached
+
+        result = self.query_engine.query(query_str, **kwargs)
+        self.cache.set(query_str, result, namespace=self._namespace)
+        return result
+
+    async def aquery(self, query_str: str, **kwargs) -> Any:
+        """
+        Async query the engine with caching.
+
+        Args:
+            query_str: The query string.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The query response (from cache or fresh invocation).
+        """
+        cached = self.cache.get(query_str, namespace=self._namespace)
+        if cached is not None:
+            return cached
+
+        result = await self.query_engine.aquery(query_str, **kwargs)
+        self.cache.set(query_str, result, namespace=self._namespace)
+        return result
+
+    def __getattr__(self, name: str) -> Any:
+        """Proxy all other attributes to the underlying query engine."""
+        return getattr(self.query_engine, name)
+
+    def __repr__(self) -> str:
+        return f"CachedQueryEngine(engine={self.query_engine!r}, cache={self.cache!r})"