patternmem-rag 0.1.1__py3-none-any.whl

patternmem/__init__.py

@@ -0,0 +1,40 @@
+"""
+patternmem
+~~~~~~~~~~
+Framework-agnostic RAG middleware that makes any pipeline self-improving
+via persistent cross-query failure-pattern memory.
+
+One-line integration::
+
+    answer = await PatternMemMiddleware(pipeline=my_rag_pipeline).ainvoke(query)
+
+Public API
+----------
+The following names are the stable, versioned public surface of this package.
+Anything not listed here is considered internal and may change without notice.
+"""
+
+from __future__ import annotations
+
+from patternmem.backend import MemoryBackend
+from patternmem.middleware import PatternMemMiddleware
+from patternmem.types import (
+    FailurePattern,
+    FailureSignal,
+    FailureType,
+    LLMResolverError,
+)
+
+__all__ = [
+    "PatternMemMiddleware",
+    # data contracts
+    "FailureSignal",
+    "FailureType",
+    "FailurePattern",
+    # errors
+    "LLMResolverError",
+    # ABC (for community backend implementors)
+    "MemoryBackend",
+]
+
+__version__ = "0.1.0"

patternmem/_utils.py

@@ -0,0 +1,25 @@
+"""
+patternmem._utils
+~~~~~~~~~~~~~~~~~~
+Internal utility helpers shared across backends.
+
+All functions here are *pure* (no I/O, no async, no side-effects).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Return cosine similarity in [−1, 1] between two L2-normalised vectors.
+
+    Returns 0.0 if either vector has zero norm (avoids division-by-zero).
+    """
+    va = np.array(a, dtype=np.float32)
+    vb = np.array(b, dtype=np.float32)
+    norm_a = float(np.linalg.norm(va))
+    norm_b = float(np.linalg.norm(vb))
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return float(np.dot(va, vb) / (norm_a * norm_b))

patternmem/augmenter.py

@@ -0,0 +1,155 @@
+"""
+patternmem.augmenter
+~~~~~~~~~~~~~~~~~~~~~
+Augmenter — builds the ``augmented_input`` dict from retrieved ``FailurePattern``
+objects and injects it into the pipeline call for Phase 1 of the 3-phase loop.
+
+Invariants enforced here
+------------------------
+- **Invariant 2**: Never mutates the user's prompt template.  All influence
+  flows through ``augmented_input``.
+- **Invariant 4**: Retrieval-type hints → ``augmented_input["retrieval_hint"]``
+  only.  Generation-type constraints → ``augmented_input["generation_constraint"]``
+  only.  No hint ever appears in the wrong key.
+
+Framework detection
+-------------------
+Duck-typing only — no ``isinstance`` against framework types, no framework imports.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from patternmem.types import (
+    FailurePattern,
+    is_generation_failure,
+    is_retrieval_failure,
+)
+
+
+class Augmenter:
+    """Builds ``augmented_input`` dicts from failure patterns.
+
+    Parameters
+    ----------
+    pipeline:
+        The wrapped pipeline object.  Used for framework-specific augmentation
+        (duck-typing only).
+    rewrite_feedback:
+        If ``True``, add a ``rewrite_constraint`` key to ``augmented_input``
+        when retrieval hints are present.  Never touches the prompt template.
+    allow_param_override:
+        If ``True``, add ``llm_call_kwargs`` (e.g. ``temperature=0.1``) to
+        ``augmented_input`` for grounding-sensitive failure types.
+    """
+
+    def __init__(
+        self,
+        pipeline: Any,
+        rewrite_feedback: bool = False,
+        allow_param_override: bool = False,
+    ) -> None:
+        self._pipeline = pipeline
+        self._rewrite_feedback = rewrite_feedback
+        self._allow_param_override = allow_param_override
+
+    # ------------------------------------------------------------------
+    # Framework detection helpers (duck-typing, no imports)
+    # ------------------------------------------------------------------
+
+    def _is_langchain(self) -> bool:
+        """Heuristic: pipeline has a ``retriever`` attribute with ``search_kwargs``."""
+        try:
+            return hasattr(self._pipeline, "retriever") and hasattr(
+                self._pipeline.retriever, "search_kwargs"
+            )
+        except Exception:  # noqa: BLE001
+            return False
+
+    def _is_llamaindex(self) -> bool:
+        """Heuristic: pipeline responds to ``as_query_engine()`` call."""
+        try:
+            return callable(getattr(self._pipeline, "as_query_engine", None))
+        except Exception:  # noqa: BLE001
+            return False
+
+    # ------------------------------------------------------------------
+    # Public method
+    # ------------------------------------------------------------------
+
+    def build(self, patterns: list[FailurePattern]) -> dict[str, Any]:
+        """Build the ``augmented_input`` dict from the given patterns.
+
+        Parameters
+        ----------
+        patterns:
+            Matched patterns from ``backend.lookup_patterns()``.  May contain
+            both retrieval-type and generation-type failures (compound case).
+
+        Returns
+        -------
+        dict[str, Any]
+            Keys set only as needed:
+            - ``"retrieval_hint"`` — present only if retrieval-type patterns exist
+            - ``"generation_constraint"`` — present only if generation-type patterns exist
+            - ``"rewrite_constraint"`` — present only if ``rewrite_feedback=True``
+              and a retrieval hint was produced
+            - ``"llm_call_kwargs"`` — present only if ``allow_param_override=True``
+              and a generation-type constraint was produced
+            - ``"langchain_retriever_hint"`` — present only for LangChain pipelines
+            - ``"llamaindex_query_bundle"`` — present only for LlamaIndex pipelines
+
+        Notes (Invariant 4)
+        -------------------
+        Retrieval-type ``FailureType``s → ``"retrieval_hint"`` only.
+        Generation-type ``FailureType``s → ``"generation_constraint"`` only.
+        This is enforced by ``is_retrieval_failure`` / ``is_generation_failure``
+        defined in ``patternmem.types``.
+        """
+        retrieval_hints: list[str] = []
+        generation_constraints: list[str] = []
+
+        for p in patterns:
+            if is_retrieval_failure(p.failure_type):
+                retrieval_hints.append(p.hint_text)
+            elif is_generation_failure(p.failure_type):
+                generation_constraints.append(p.hint_text)
+            # UNKNOWN failure type → no augmentation
+
+        augmented: dict[str, Any] = {}
+
+        # --- Retrieval lane ---
+        if retrieval_hints:
+            combined_hint = "; ".join(retrieval_hints)
+            augmented["retrieval_hint"] = combined_hint
+
+            # Framework-specific injection
+            if self._is_langchain():
+                try:
+                    self._pipeline.retriever.search_kwargs["hint"] = combined_hint
+                    augmented["langchain_retriever_hint"] = combined_hint
+                except Exception:  # noqa: BLE001
+                    pass
+            elif self._is_llamaindex():
+                augmented["llamaindex_query_bundle"] = {
+                    "custom_embedding_strs": [combined_hint]
+                }
+
+            # Rewrite feedback lane (only if explicitly enabled)
+            if self._rewrite_feedback:
+                # Invariant 2: never patch the prompt object — append via context key only
+                augmented["rewrite_constraint"] = (
+                    f"Constraint (auto): {combined_hint}"
+                )
+
+        # --- Generation lane ---
+        if generation_constraints:
+            combined_constraint = "; ".join(generation_constraints)
+            augmented["generation_constraint"] = combined_constraint
+
+            # Optional temperature override for grounding-sensitive queries
+            if self._allow_param_override:
+                augmented["llm_call_kwargs"] = {"temperature": 0.1}
+
+        return augmented

patternmem/backend.py

@@ -0,0 +1,138 @@
+"""
+patternmem.backend
+~~~~~~~~~~~~~~~~~~
+Abstract base class for all PatternMem memory backends.
+
+Every storage backend (JSON, SQLite, NetworkX, Neo4j) must subclass
+``MemoryBackend`` and implement every abstract method.  The contract test suite
+in ``tests/contract/test_backend_contract.py`` asserts identical behaviour
+across all implementations, making them provably interchangeable.
+
+Design rules
+------------
+- All methods are ``async`` — implementations may use any I/O strategy
+  (asyncio-native, ``asyncio.to_thread``, etc.) as long as they do not block
+  the event loop for more than ~10 ms.
+- The ABC deliberately does *not* import any storage driver — backends stay
+  in ``patternmem/backends/`` and import drivers themselves.
+- ``update_pattern`` and ``delete_pattern`` are required by the decay loop
+  (Invariant 6) but are *not* exported from ``patternmem.__init__``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from patternmem.types import FailurePattern
+
+
+class MemoryBackend(ABC):
+    """Abstract base class that every storage backend must implement.
+
+    The public surface (``write_pattern``, ``lookup_patterns``, ``get_stats``)
+    is exported from ``patternmem.__init__``.  The lifecycle methods
+    (``update_pattern``, ``delete_pattern``) are required internally for the
+    decay/eviction loop but are not part of the user-facing API.
+    """
+
+    # ------------------------------------------------------------------
+    # Public API — exported via patternmem.__init__
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def write_pattern(self, pattern: FailurePattern) -> None:
+        """Persist a new ``FailurePattern`` to the backend.
+
+        Parameters
+        ----------
+        pattern:
+            The failure pattern to store.  The ``id`` field is already set by
+            ``FailurePattern``'s ``__post_init__``.
+
+        Notes
+        -----
+        Implementations must be idempotent on ``pattern.id``: writing the same
+        ``id`` twice should update the existing record, not create a duplicate.
+        """
+
+    @abstractmethod
+    async def lookup_patterns(
+        self,
+        query_embedding: list[float],
+        top_k: int = 3,
+    ) -> list[FailurePattern]:
+        """Return the top-*k* patterns whose embeddings are similar to *query_embedding*.
+
+        Parameters
+        ----------
+        query_embedding:
+            Dense query vector produced by the MiniLM encoder.
+        top_k:
+            Maximum number of patterns to return.  Implementations must apply
+            the similarity threshold (0.82 by default, configurable via the
+            middleware's ``similarity_threshold`` parameter) before ranking.
+
+        Returns
+        -------
+        list[FailurePattern]
+            Ordered by descending similarity score.  Empty list if no patterns
+            exceed the similarity threshold.
+        """
+
+    @abstractmethod
+    async def get_stats(self) -> dict[str, Any]:
+        """Return backend health and bookkeeping statistics.
+
+        The returned dict must contain at minimum:
+
+        .. code-block:: python
+
+            {"count": int}          # total patterns stored
+
+        Implementations may include additional keys (e.g. ``"path"``,
+        ``"uri"``, ``"evictions"``).
+        """
+
+    # ------------------------------------------------------------------
+    # Lifecycle API — required by decay/eviction loop (Invariant 6)
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    async def update_pattern(self, pattern_id: str, decay_weight: float) -> None:
+        """Update the ``decay_weight`` of an existing pattern.
+
+        Parameters
+        ----------
+        pattern_id:
+            UUID string of the pattern to update.
+        decay_weight:
+            New decay weight value.  Must be stored verbatim; no clamping is
+            performed here — callers (``BackgroundReflector``) own that logic.
+
+        Raises
+        ------
+        KeyError
+            If *pattern_id* does not exist in the backend.
+        """
+
+    @abstractmethod
+    async def delete_pattern(self, pattern_id: str) -> None:
+        """Permanently evict a pattern from the backend.
+
+        Parameters
+        ----------
+        pattern_id:
+            UUID string of the pattern to delete.
+
+        Raises
+        ------
+        KeyError
+            If *pattern_id* does not exist in the backend.
+
+        Notes
+        -----
+        This is called by the decay loop when ``decay_weight < 0.1``.
+        Implementations should ensure the deletion is durable (e.g. flushed
+        to disk for file-based backends) before returning.
+        """

patternmem/backends/__init__.py

@@ -0,0 +1 @@
+"""patternmem.backends — internal package."""

patternmem/backends/chroma_backend.py

@@ -0,0 +1,215 @@
+"""
+patternmem.backends.chroma_backend
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ChromaDB backend for PatternMem.
+
+Uses ChromaDB's native vector index for similarity search — no brute-force
+numpy cosine loop is needed.  This makes it the best choice for large
+pattern memories (> 10 000 patterns) when you don't need Neo4j's graph model.
+
+Storage layout
+--------------
+A single ChromaDB collection named ``"patternmem_patterns"`` (configurable).
+Pattern metadata (failure_type, root_cause, hint_text, score, created_at,
+decay_weight) is stored in Chroma's document metadata dict.
+The query embedding is stored as the collection document embedding.
+
+Similarity
+----------
+ChromaDB runs its own HNSW index for approximate nearest-neighbour search.
+PatternMem's ``similarity_threshold`` is applied as a post-filter on the
+returned cosine distances (Chroma returns distances not similarities, so
+we convert: similarity = 1 − distance).
+
+Requirements
+------------
+    pip install patternmem-rag[chroma]
+    # or
+    pip install chromadb>=0.4
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any
+
+from patternmem.backend import MemoryBackend
+from patternmem.types import FailurePattern, FailureType
+
+try:
+    import chromadb
+
+    _CHROMA_AVAILABLE = True
+except ImportError:
+    _CHROMA_AVAILABLE = False
+
+
+def _pattern_to_chroma(p: FailurePattern) -> dict[str, Any]:
+    """Flatten FailurePattern into a Chroma metadata dict (scalar values only)."""
+    return {
+        "failure_type": p.failure_type.name,
+        "root_cause": p.root_cause,
+        "hint_text": p.hint_text,
+        "score": p.score,
+        "created_at": p.created_at.isoformat(),
+        "decay_weight": p.decay_weight,
+    }
+
+
+def _chroma_to_pattern(
+    pattern_id: str,
+    meta: dict[str, Any],
+    embedding: list[float],
+) -> FailurePattern:
+    return FailurePattern(
+        id=pattern_id,
+        query_embedding=embedding,
+        failure_type=FailureType[meta["failure_type"]],
+        root_cause=meta["root_cause"],
+        hint_text=meta["hint_text"],
+        score=float(meta["score"]),
+        created_at=datetime.fromisoformat(meta["created_at"]).replace(
+            tzinfo=timezone.utc
+        ),
+        decay_weight=float(meta["decay_weight"]),
+    )
+
+
+class ChromaBackend(MemoryBackend):
+    """ChromaDB-backed vector store for PatternMem failure patterns.
+
+    Uses ChromaDB's native HNSW index for fast approximate nearest-neighbour
+    search.  Recommended for pattern stores > 10 000 entries or when you
+    already run a Chroma server.
+
+    Parameters
+    ----------
+    collection_name:
+        Name of the Chroma collection to use.  Created if it does not exist.
+    persist_directory:
+        Path for the persistent Chroma client.  ``None`` uses an ephemeral
+        (in-memory) client — useful for tests and notebooks.
+    host / port:
+        If provided, connects to a running Chroma HTTP server instead of a
+        local file-backed client.  ``host`` takes precedence over
+        ``persist_directory``.
+    similarity_threshold:
+        Minimum cosine similarity (0–1) for a pattern to be returned.
+        Chroma returns L2 or cosine distances; PatternMem converts and filters.
+    """
+
+    def __init__(
+        self,
+        collection_name: str = "patternmem_patterns",
+        persist_directory: str | None = None,
+        host: str | None = None,
+        port: int = 8000,
+        similarity_threshold: float = 0.82,
+    ) -> None:
+        if not _CHROMA_AVAILABLE:
+            raise ImportError(
+                "ChromaBackend requires 'chromadb'. "
+                "Install it with: pip install patternmem-rag[chroma]"
+            )
+        self._threshold = similarity_threshold
+        self._collection_name = collection_name
+
+        if host is not None:
+            # Connect to a running Chroma HTTP server
+            self._client = chromadb.HttpClient(host=host, port=port)
+        elif persist_directory is not None:
+            # File-backed persistent client
+            self._client = chromadb.PersistentClient(path=persist_directory)
+        else:
+            # Ephemeral in-memory client (tests / notebooks)
+            self._client = chromadb.EphemeralClient()
+
+        # Get-or-create the collection with cosine similarity space
+        self._collection = self._client.get_or_create_collection(
+            name=collection_name,
+            metadata={"hnsw:space": "cosine"},
+        )
+        self._lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------
+    # MemoryBackend implementation
+    # ------------------------------------------------------------------
+
+    async def write_pattern(self, pattern: FailurePattern) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._write_sync, pattern)
+
+    def _write_sync(self, pattern: FailurePattern) -> None:
+        """Upsert pattern into the Chroma collection (idempotent on pattern.id)."""
+        self._collection.upsert(
+            ids=[pattern.id],
+            embeddings=[pattern.query_embedding],
+            metadatas=[_pattern_to_chroma(pattern)],
+            documents=[pattern.root_cause or " "],  # Chroma requires non-empty docs
+        )
+
+    async def lookup_patterns(
+        self,
+        query_embedding: list[float],
+        top_k: int = 3,
+    ) -> list[FailurePattern]:
+        # Fetch more candidates than top_k so the threshold filter has room to work
+        n_results = min(top_k * 4, max(1, self._collection.count()))
+        if n_results == 0:
+            return []
+
+        results = await asyncio.to_thread(
+            self._collection.query,
+            query_embeddings=[query_embedding],
+            n_results=n_results,
+            include=["embeddings", "metadatas", "distances"],
+        )
+
+        ids: list[str] = results["ids"][0]
+        metadatas: list[dict[str, Any]] = results["metadatas"][0]
+        distances: list[float] = results["distances"][0]
+        embeddings: list[list[float]] = results["embeddings"][0]
+
+        # Chroma cosine space returns distances in [0, 2]; convert to similarity
+        # similarity = 1 − (distance / 2)  (for cosine distance in [0, 2])
+        # OR  similarity = 1 − distance     (for normalized cosine in [0, 1])
+        # ChromaDB cosine distance = 1 − cosine_similarity → similarity = 1 − dist
+        patterns: list[FailurePattern] = []
+        for pid, meta, dist, emb in zip(ids, metadatas, distances, embeddings):
+            similarity = 1.0 - float(dist)
+            if similarity >= self._threshold:
+                patterns.append(_chroma_to_pattern(pid, meta, list(emb)))
+
+        # Already sorted by distance (ascending) = similarity descending
+        return patterns[:top_k]
+
+    async def get_stats(self) -> dict[str, Any]:
+        count = await asyncio.to_thread(self._collection.count)
+        return {
+            "count": count,
+            "collection": self._collection_name,
+            "backend": "chroma",
+        }
+
+    async def update_pattern(self, pattern_id: str, decay_weight: float) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._update_sync, pattern_id, decay_weight)
+
+    def _update_sync(self, pattern_id: str, decay_weight: float) -> None:
+        result = self._collection.get(ids=[pattern_id], include=["metadatas"])
+        if not result["ids"]:
+            raise KeyError(f"Pattern {pattern_id!r} not found in Chroma backend")
+        meta = result["metadatas"][0]
+        meta["decay_weight"] = decay_weight
+        self._collection.update(ids=[pattern_id], metadatas=[meta])
+
+    async def delete_pattern(self, pattern_id: str) -> None:
+        async with self._lock:
+            await asyncio.to_thread(self._delete_sync, pattern_id)
+
+    def _delete_sync(self, pattern_id: str) -> None:
+        result = self._collection.get(ids=[pattern_id])
+        if not result["ids"]:
+            raise KeyError(f"Pattern {pattern_id!r} not found in Chroma backend")
+        self._collection.delete(ids=[pattern_id])