patternmem-rag 0.1.1__tar.gz

patternmem_rag-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PatternMem Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

patternmem_rag-0.1.1/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: patternmem-rag
+Version: 0.1.1
+Summary: Framework-agnostic RAG middleware that makes any pipeline self-improving via persistent failure-pattern memory.
+Author-email: Nitesh Kumar <nk-gujjar@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nk-gujjar/patternmem-rag
+Project-URL: Repository, https://github.com/nk-gujjar/patternmem-rag
+Project-URL: Issues, https://github.com/nk-gujjar/patternmem-rag/issues
+Keywords: rag,llm,memory,retrieval-augmented-generation,self-improving
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sentence-transformers>=2.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: aiosqlite>=0.19
+Provides-Extra: ragas
+Requires-Dist: ragas>=0.1; extra == "ragas"
+Provides-Extra: deepeval
+Requires-Dist: deepeval>=0.20; extra == "deepeval"
+Provides-Extra: neo4j
+Requires-Dist: neo4j>=5.0; extra == "neo4j"
+Provides-Extra: langfuse
+Requires-Dist: langfuse>=2.0; extra == "langfuse"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1; extra == "langchain"
+Provides-Extra: networkx
+Requires-Dist: networkx>=3.0; extra == "networkx"
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.4; extra == "chroma"
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.7; extra == "faiss"
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == "celery"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: hypothesis>=6.80; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: networkx>=3.0; extra == "dev"
+Requires-Dist: types-aiofiles; extra == "dev"
+Provides-Extra: all
+Requires-Dist: patternmem-rag[chroma,deepeval,faiss,langchain,langfuse,neo4j,networkx,ragas]; extra == "all"
+Dynamic: license-file
+
+# PatternMem RAG
+
+[![CI](https://github.com/nk-gujjar/patternmem-rag/actions/workflows/ci.yml/badge.svg)](https://github.com/nk-gujjar/patternmem-rag/actions)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/patternmem-rag/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://pypi.org/project/patternmem-rag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Framework-agnostic Python middleware that wraps *any* existing RAG pipeline and makes it self-improving** — via persistent failure-pattern memory across queries.
+
+```python
+# Before
+answer = my_rag_pipeline(query)
+
+# After — one line
+answer = await PatternMemMiddleware(pipeline=my_rag_pipeline).ainvoke(query)
+```
+
+---
+
+## Why PatternMem?
+
+Self-RAG, CRAG, and DSPy all reflect *within a single query*. PatternMem is the missing layer: it makes failure signals **persistent across the entire query history** — so the second time a pipeline fails on a similar question, it already knows what went wrong and pre-empts the failure.
+
+PatternMem **does not reimplement** evaluation, LLM calling, or graph storage. It sits between your pipeline and the eval/storage libraries you already have.
+
+---
+
+## Quickstart
+
+```bash
+pip install patternmem-rag
+```
+
+```python
+import asyncio
+from patternmem import PatternMemMiddleware
+
+async def my_rag_pipeline(query, **kwargs):
+    # your existing pipeline here
+    return {"answer": "...", "chunks": [...]}
+
+async def main():
+    async with PatternMemMiddleware(
+        pipeline=my_rag_pipeline,
+        backend="json",    # local file, zero credentials
+        eval="auto",       # tries RAGAS → DeepEval → no-op
+    ) as mw:
+        answer = await mw.ainvoke("What is the capital of France?")
+        print(answer)
+
+asyncio.run(main())
+```
+
+## Zero-credential mode (no API keys needed)
+
+```python
+answer = await PatternMemMiddleware(
+    pipeline=my_pipeline,
+    backend="json",
+    eval="none",
+    observability=None,
+).ainvoke(query)
+```
+
+Run the included demo:
+```bash
+python examples/zero_credential_demo.py
+```
+
+---
+
+## How it works
+
+```
+Query ──► [Phase 1: ~50ms]
+           Embed query (MiniLM, local)
+           Lookup patterns (cosine similarity ≥ 0.82)
+           on HIT  → Augmenter injects retrieval_hint / generation_constraint
+           Pipeline called → Answer returned to caller immediately
+
+           [Phase 2: async background]
+           EvalRouter: RAGAS / DeepEval / none → FailureSignal
+
+           [Phase 3: async background]
+           BackgroundReflector: LLM extracts FailurePattern → Backend write
+           Decay/eviction loop (patterns below weight 0.1 are pruned)
+```
+
+The caller **never waits** for Phases 2 or 3.
+
+---
+
+## Optional extras
+
+| Extra | What it adds |
+|---|---|
+| `pip install patternmem-rag[ragas]` | RAGAS evaluation adapter |
+| `pip install patternmem-rag[deepeval]` | DeepEval evaluation adapter |
+| `pip install patternmem-rag[neo4j]` | Neo4j / AuraDB backend |
+| `pip install patternmem-rag[langfuse]` | Langfuse observability |
+| `pip install patternmem-rag[networkx]` | NetworkX in-memory backend |
+| `pip install patternmem-rag[chroma]` | ChromaDB vector backend |
+| `pip install patternmem-rag[faiss]` | FAISS local vector index backend |
+
+---
+
+## Configuration reference
+
+```python
+PatternMemMiddleware(
+    pipeline,                          # any callable (sync or async)
+    llm=None,                          # explicit LLM; auto-resolved if omitted
+    backend="json",                    # "json" | "sqlite" | "networkx" | MemoryBackend
+    eval="auto",                       # "ragas" | "deepeval" | "auto" | "none"
+    observability=None,                # "langfuse" | "otel" | None
+    similarity_threshold=0.82,         # cosine similarity floor for pattern lookup
+    allow_param_override=False,        # allow temperature/CoT overrides
+    rewrite_feedback=False,            # inject hints into query rewriter
+)
+```
+
+---
+
+## Backend choice guide
+
+| Backend | Best for | Persistence | Dependencies |
+|---|---|---|---|
+| `"json"` | Zero-config, development | File | None |
+| `"sqlite"` | Single-process production | File (WAL) | `aiosqlite` (core) |
+| `"networkx"` | Notebooks, graph experiments | Optional file | `networkx` |
+| `"chroma"` | Large stores, existing Chroma setup | File / HTTP server | `chromadb` |
+| `"faiss"` | High-speed local search, no server | File (index + sidecar) | `faiss-cpu` |
+| `"neo4j"` | Multi-process, AuraDB, scale | Native graph | `neo4j` driver |
+
+---
+
+## Custom backend
+
+Implement `MemoryBackend` and pass an instance directly:
+
+```python
+from patternmem import MemoryBackend, PatternMemMiddleware
+
+class MyRedisBackend(MemoryBackend):
+    async def write_pattern(self, pattern): ...
+    async def lookup_patterns(self, embedding, top_k=3): ...
+    async def get_stats(self): ...
+    async def update_pattern(self, id, decay_weight): ...
+    async def delete_pattern(self, id): ...
+
+mw = PatternMemMiddleware(pipeline=my_pipeline, backend=MyRedisBackend())
+```
+
+---
+
+## FAQ
+
+**Q: Does PatternMem replace RAGAS or DeepEval?**
+No. It wraps them. It uses their scores as signals, stores the resulting patterns, and pre-empts future failures.
+
+**Q: Does it change my prompts?**
+Never. All augmentation flows through `augmented_input` kwargs — PatternMem never touches your prompt template.
+
+**Q: What if evaluation isn't installed?**
+`eval="none"` is a first-class mode. The middleware still runs the full 3-phase loop; Phase 2 returns an UNKNOWN signal and Phase 3 stores it with no external calls.
+
+**Q: What's the LLM used for?**
+Only Phase 3 (root cause extraction and hint generation from a `FailureSignal`). It borrows your pipeline's LLM — it never creates one.
+
+**Q: What's out of scope?**
+Celery integration (documented stub), Redis/Postgres backends (open ABC for community), any dashboard (use Langfuse's native UI).
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue first to discuss what you'd like to change.
+
+- All backends must pass the contract test suite in `tests/contract/test_backend_contract.py`.
+- Keep public API surface stable — anything not in `patternmem.__init__.__all__` is internal.
+
+---
+
+## License
+
+MIT

patternmem_rag-0.1.1/README.md

@@ -0,0 +1,186 @@
+# PatternMem RAG
+
+[![CI](https://github.com/nk-gujjar/patternmem-rag/actions/workflows/ci.yml/badge.svg)](https://github.com/nk-gujjar/patternmem-rag/actions)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/patternmem-rag/)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://pypi.org/project/patternmem-rag/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Framework-agnostic Python middleware that wraps *any* existing RAG pipeline and makes it self-improving** — via persistent failure-pattern memory across queries.
+
+```python
+# Before
+answer = my_rag_pipeline(query)
+
+# After — one line
+answer = await PatternMemMiddleware(pipeline=my_rag_pipeline).ainvoke(query)
+```
+
+---
+
+## Why PatternMem?
+
+Self-RAG, CRAG, and DSPy all reflect *within a single query*. PatternMem is the missing layer: it makes failure signals **persistent across the entire query history** — so the second time a pipeline fails on a similar question, it already knows what went wrong and pre-empts the failure.
+
+PatternMem **does not reimplement** evaluation, LLM calling, or graph storage. It sits between your pipeline and the eval/storage libraries you already have.
+
+---
+
+## Quickstart
+
+```bash
+pip install patternmem-rag
+```
+
+```python
+import asyncio
+from patternmem import PatternMemMiddleware
+
+async def my_rag_pipeline(query, **kwargs):
+    # your existing pipeline here
+    return {"answer": "...", "chunks": [...]}
+
+async def main():
+    async with PatternMemMiddleware(
+        pipeline=my_rag_pipeline,
+        backend="json",    # local file, zero credentials
+        eval="auto",       # tries RAGAS → DeepEval → no-op
+    ) as mw:
+        answer = await mw.ainvoke("What is the capital of France?")
+        print(answer)
+
+asyncio.run(main())
+```
+
+## Zero-credential mode (no API keys needed)
+
+```python
+answer = await PatternMemMiddleware(
+    pipeline=my_pipeline,
+    backend="json",
+    eval="none",
+    observability=None,
+).ainvoke(query)
+```
+
+Run the included demo:
+```bash
+python examples/zero_credential_demo.py
+```
+
+---
+
+## How it works
+
+```
+Query ──► [Phase 1: ~50ms]
+           Embed query (MiniLM, local)
+           Lookup patterns (cosine similarity ≥ 0.82)
+           on HIT  → Augmenter injects retrieval_hint / generation_constraint
+           Pipeline called → Answer returned to caller immediately
+
+           [Phase 2: async background]
+           EvalRouter: RAGAS / DeepEval / none → FailureSignal
+
+           [Phase 3: async background]
+           BackgroundReflector: LLM extracts FailurePattern → Backend write
+           Decay/eviction loop (patterns below weight 0.1 are pruned)
+```
+
+The caller **never waits** for Phases 2 or 3.
+
+---
+
+## Optional extras
+
+| Extra | What it adds |
+|---|---|
+| `pip install patternmem-rag[ragas]` | RAGAS evaluation adapter |
+| `pip install patternmem-rag[deepeval]` | DeepEval evaluation adapter |
+| `pip install patternmem-rag[neo4j]` | Neo4j / AuraDB backend |
+| `pip install patternmem-rag[langfuse]` | Langfuse observability |
+| `pip install patternmem-rag[networkx]` | NetworkX in-memory backend |
+| `pip install patternmem-rag[chroma]` | ChromaDB vector backend |
+| `pip install patternmem-rag[faiss]` | FAISS local vector index backend |
+
+---
+
+## Configuration reference
+
+```python
+PatternMemMiddleware(
+    pipeline,                          # any callable (sync or async)
+    llm=None,                          # explicit LLM; auto-resolved if omitted
+    backend="json",                    # "json" | "sqlite" | "networkx" | MemoryBackend
+    eval="auto",                       # "ragas" | "deepeval" | "auto" | "none"
+    observability=None,                # "langfuse" | "otel" | None
+    similarity_threshold=0.82,         # cosine similarity floor for pattern lookup
+    allow_param_override=False,        # allow temperature/CoT overrides
+    rewrite_feedback=False,            # inject hints into query rewriter
+)
+```
+
+---
+
+## Backend choice guide
+
+| Backend | Best for | Persistence | Dependencies |
+|---|---|---|---|
+| `"json"` | Zero-config, development | File | None |
+| `"sqlite"` | Single-process production | File (WAL) | `aiosqlite` (core) |
+| `"networkx"` | Notebooks, graph experiments | Optional file | `networkx` |
+| `"chroma"` | Large stores, existing Chroma setup | File / HTTP server | `chromadb` |
+| `"faiss"` | High-speed local search, no server | File (index + sidecar) | `faiss-cpu` |
+| `"neo4j"` | Multi-process, AuraDB, scale | Native graph | `neo4j` driver |
+
+---
+
+## Custom backend
+
+Implement `MemoryBackend` and pass an instance directly:
+
+```python
+from patternmem import MemoryBackend, PatternMemMiddleware
+
+class MyRedisBackend(MemoryBackend):
+    async def write_pattern(self, pattern): ...
+    async def lookup_patterns(self, embedding, top_k=3): ...
+    async def get_stats(self): ...
+    async def update_pattern(self, id, decay_weight): ...
+    async def delete_pattern(self, id): ...
+
+mw = PatternMemMiddleware(pipeline=my_pipeline, backend=MyRedisBackend())
+```
+
+---
+
+## FAQ
+
+**Q: Does PatternMem replace RAGAS or DeepEval?**
+No. It wraps them. It uses their scores as signals, stores the resulting patterns, and pre-empts future failures.
+
+**Q: Does it change my prompts?**
+Never. All augmentation flows through `augmented_input` kwargs — PatternMem never touches your prompt template.
+
+**Q: What if evaluation isn't installed?**
+`eval="none"` is a first-class mode. The middleware still runs the full 3-phase loop; Phase 2 returns an UNKNOWN signal and Phase 3 stores it with no external calls.
+
+**Q: What's the LLM used for?**
+Only Phase 3 (root cause extraction and hint generation from a `FailureSignal`). It borrows your pipeline's LLM — it never creates one.
+
+**Q: What's out of scope?**
+Celery integration (documented stub), Redis/Postgres backends (open ABC for community), any dashboard (use Langfuse's native UI).
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue first to discuss what you'd like to change.
+
+- All backends must pass the contract test suite in `tests/contract/test_backend_contract.py`.
+- Keep public API surface stable — anything not in `patternmem.__init__.__all__` is internal.
+
+---
+
+## License
+
+MIT

patternmem_rag-0.1.1/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_rag-0.1.1/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_rag-0.1.1/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