cacheverifier 0.6.0__tar.gz → 0.7.0__tar.gz

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.7.0
+
+`entries_to_refresh()` lists the cache entries your feedback reported stale,
+or wrong more often than right, and `resolve_entry(key)` marks one refreshed
+(`GET /v1/monitor/entries-to-refresh`, every plan). `feedback()` (on both
+`CacheVerifier` and `LocalVerifier`) takes `cache_entry_id`, your own key for
+the entry, which the list hands back so you can refresh or drop it directly.
+
 ## 0.6.0
 
 New `LocalVerifier` (`pip install "cacheverifier[local]"`, Managed plans):

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cacheverifier
-Version: 0.6.0
+Version: 0.7.0
 Summary: Python client for the CacheVerifier semantic-cache verification API, hosted or scored locally
 Project-URL: Homepage, https://www.cacheverifier.com
 Project-URL: Documentation, https://www.cacheverifier.com/docs
@@ -185,6 +185,19 @@ set_llm_cache(
 )
 ```
 
+## Entries to refresh
+
+Send your cache's own key with feedback, and the service tells you which
+entries to fix: ones reported stale, or wrong more often than right.
+
+```python
+cv.feedback(query, cached_answer, was_correct=False, stale=True, cache_entry_id="faq:shipping")
+
+for e in cv.entries_to_refresh():
+    my_cache.delete(e["cache_entry_id"])   # or regenerate the answer
+    cv.resolve_entry(e["key"])
+```
+
 ## Fine-tuning
 
 Once you have ~20+ feedback rows (the service found fine-tuning is often a net negative
@@ -306,6 +319,7 @@ verdict
 | `get_finetune_job(id)` / `list_finetune_jobs()` | `GET /v1/finetune/jobs[/id]` |
 | `activate_model_version(id)` | `POST /v1/finetune/model-versions/{id}/activate` |
 | `drift_status()` | `GET /v1/monitor/drift-status` |
+| `entries_to_refresh()` / `resolve_entry(key)` | `GET /v1/monitor/entries-to-refresh` / `POST .../{key}/resolve` |
 | `gray_zone_threshold()` | `GET /v1/monitor/gray-zone-threshold` |
 | `usage()` / `savings()` | `GET /v1/usage/status` / `/savings` |
 | `LocalVerifier.verify(...)` / `verify_batch(...)` | local; decisions to `POST /v1/verify/decisions` |

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/README.md

@@ -146,6 +146,19 @@ set_llm_cache(
 )
 ```
 
+## Entries to refresh
+
+Send your cache's own key with feedback, and the service tells you which
+entries to fix: ones reported stale, or wrong more often than right.
+
+```python
+cv.feedback(query, cached_answer, was_correct=False, stale=True, cache_entry_id="faq:shipping")
+
+for e in cv.entries_to_refresh():
+    my_cache.delete(e["cache_entry_id"])   # or regenerate the answer
+    cv.resolve_entry(e["key"])
+```
+
 ## Fine-tuning
 
 Once you have ~20+ feedback rows (the service found fine-tuning is often a net negative
@@ -267,6 +280,7 @@ verdict
 | `get_finetune_job(id)` / `list_finetune_jobs()` | `GET /v1/finetune/jobs[/id]` |
 | `activate_model_version(id)` | `POST /v1/finetune/model-versions/{id}/activate` |
 | `drift_status()` | `GET /v1/monitor/drift-status` |
+| `entries_to_refresh()` / `resolve_entry(key)` | `GET /v1/monitor/entries-to-refresh` / `POST .../{key}/resolve` |
 | `gray_zone_threshold()` | `GET /v1/monitor/gray-zone-threshold` |
 | `usage()` / `savings()` | `GET /v1/usage/status` / `/savings` |
 | `LocalVerifier.verify(...)` / `verify_batch(...)` | local; decisions to `POST /v1/verify/decisions` |

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/cacheverifier/__init__.py

@@ -19,7 +19,7 @@ Research behind it: https://github.com/imxinchengyou/CacheVerifier
 from cacheverifier.client import CacheVerifier, CacheVerifierError, ShadowVerdict, VerifyResult
 from cacheverifier.local import LocalVerifier, ModelCheckFailed
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 __all__ = [
     "CacheVerifier",
     "CacheVerifierError",

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/cacheverifier/client.py

@@ -312,6 +312,7 @@ class CacheVerifier:
         similarity_score: float | None = None,
         cached_query: str | None = None,
         verification_id: int | None = None,
+        cache_entry_id: str | None = None,
         stale: bool = False,
         idempotency_key: str | None = None,
     ) -> int:
@@ -328,6 +329,8 @@ class CacheVerifier:
         - `cached_query`: the cached entry's own original query, if you have it.
         - `verification_id`: from the `VerifyResult` this feedback is about
           (always for an `audit` result) -- it ties the label to that verdict.
+        - `cache_entry_id`: your own key for the cache entry the answer came
+          from; `entries_to_refresh()` hands it back.
         - `stale`: set instead of a bare `was_correct=False` when the answer
           is wrong ONLY because a fact changed (price, date, ...), not a
           semantic mismatch. Stale rows are excluded from training and drift.
@@ -340,7 +343,12 @@ class CacheVerifier:
             "stale": stale,
         }
         payload.update(
-            _drop_none(similarity_score=similarity_score, cached_query=cached_query, verification_id=verification_id)
+            _drop_none(
+                similarity_score=similarity_score,
+                cached_query=cached_query,
+                verification_id=verification_id,
+                cache_entry_id=cache_entry_id,
+            )
         )
         headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
         return int(self._post("/v1/feedback", json=payload, headers=headers)["id"])
@@ -348,7 +356,8 @@ class CacheVerifier:
     def feedback_batch(self, items: Iterable[dict[str, Any]]) -> list[int]:
         """Bulk-upload feedback rows (max 500). Each item is a dict with
         `query`, `candidate_answer`, `was_correct`, and optionally
-        `similarity_score` / `stale`. Returns the created row ids.
+        `similarity_score` / `cached_query` / `cache_entry_id` / `stale`.
+        Returns the created row ids.
         `POST /v1/feedback/batch`.
         """
         data = self._post("/v1/feedback/batch", json={"items": list(items)})
@@ -412,6 +421,21 @@ class CacheVerifier:
         """
         return self._get("/v1/monitor/gray-zone-threshold")
 
+    def entries_to_refresh(self) -> list[dict[str, Any]]:
+        """Cache entries your feedback reported stale, or wrong more often
+        than right -- refresh or drop them, then `resolve_entry(e["key"])`.
+        Each has `key`, `cache_entry_id` (if you sent one), `reason`
+        (`"stale"` / `"often_wrong"`), the answer, report counts and sample
+        queries. `GET /v1/monitor/entries-to-refresh`.
+        """
+        return list(self._get("/v1/monitor/entries-to-refresh")["entries"])
+
+    def resolve_entry(self, key: str) -> dict[str, Any]:
+        """Mark an entry refreshed: earlier feedback stops counting toward it.
+        `POST /v1/monitor/entries-to-refresh/{key}/resolve`.
+        """
+        return self._post(f"/v1/monitor/entries-to-refresh/{key}/resolve")
+
     def usage(self) -> dict[str, Any]:
         """`GET /v1/usage/status`."""
         return self._get("/v1/usage/status")

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/cacheverifier/local.py

@@ -475,6 +475,7 @@ class LocalVerifier:
         result: VerifyResult | None = None,
         similarity_score: float | None = None,
         cached_query: str | None = None,
+        cache_entry_id: str | None = None,
         stale: bool = False,
         idempotency_key: str | None = None,
     ) -> int:
@@ -488,6 +489,7 @@ class LocalVerifier:
             similarity_score=similarity_score,
             cached_query=cached_query,
             verification_id=verification_id,
+            cache_entry_id=cache_entry_id,
             stale=stale,
             idempotency_key=idempotency_key,
         )

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cacheverifier"
-version = "0.6.0"
+version = "0.7.0"
 description = "Python client for the CacheVerifier semantic-cache verification API, hosted or scored locally"
 readme = "README.md"
 requires-python = ">=3.9"

{cacheverifier-0.6.0 → cacheverifier-0.7.0}/tests/test_client.py

@@ -133,6 +133,7 @@ def test_feedback_returns_id_and_forwards_idempotency_key():
 def test_feedback_omits_optional_fields_when_unset():
     def handler(request: httpx.Request) -> httpx.Response:
         assert "similarity_score" not in json.loads(request.content)
+        assert "cache_entry_id" not in json.loads(request.content)
         assert request.headers.get("Idempotency-Key") is None
         return httpx.Response(200, json={"id": 1})
 
@@ -140,6 +141,29 @@ def test_feedback_omits_optional_fields_when_unset():
         assert cv.feedback("q", "a", was_correct=True) == 1
 
 
+def test_entries_to_refresh_round_trip():
+    seen = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append((request.method, request.url.path, request.content))
+        if request.url.path == "/v1/feedback":
+            return httpx.Response(200, json={"id": 7})
+        if request.method == "GET":
+            return httpx.Response(200, json={"entries": [{"key": "k" * 32, "cache_entry_id": "faq:shipping", "reason": "stale"}]})
+        return httpx.Response(200, json={"key": "k" * 32, "resolved_at": "2026-10-31T00:00:00Z"})
+
+    with make_client(handler) as cv:
+        cv.feedback("q", "a", was_correct=False, stale=True, cache_entry_id="faq:shipping")
+        [entry] = cv.entries_to_refresh()
+        assert entry["cache_entry_id"] == "faq:shipping"
+        assert cv.resolve_entry(entry["key"])["key"] == entry["key"]
+    assert json.loads(seen[0][2])["cache_entry_id"] == "faq:shipping"
+    assert [s[:2] for s in seen[1:]] == [
+        ("GET", "/v1/monitor/entries-to-refresh"),
+        ("POST", f"/v1/monitor/entries-to-refresh/{'k' * 32}/resolve"),
+    ]
+
+
 def test_finetune_passes_query_params():
     def handler(request: httpx.Request) -> httpx.Response:
         assert request.url.path == "/v1/finetune/jobs"