cacheverifier 0.5.0__tar.gz → 0.7.0__tar.gz

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

@@ -1,5 +1,33 @@
 # 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):
+scores gray-zone hits on your own machines with the model CacheVerifier
+fine-tuned for you, deciding exactly as the hosted `/v1/verify` would. It
+downloads the live model, checks it against reference verdicts from the
+service before using it, switches to newer models as they go live, and, while
+auditing is on, uploads each decision without the texts so audits and risk
+monitoring keep working. Falls back to the hosted API until a model is ready.
+
+`CacheVerifier.verify()` takes `similarity_score`, `cached_query` and
+`runner_up_similarity_score` (all optional), which a fine-tuned model's joint
+rules use; before this the client couldn't send them. `feedback()` takes
+`cached_query` and `verification_id`. `VerifyResult` gains `decision_rule`,
+`audit` and `verification_id`, which the API already returned.
+
+The offline Health Check now truncates long inputs exactly as the service
+does since its verifier-core 0.7.0: a long query next to a short answer keeps
+the room the answer doesn't need, instead of being cut to half the budget.
+
 ## 0.5.0
 
 New LangChain integration: `cacheverifier.integrations.langchain.VerifiedCache`

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: cacheverifier
-Version: 0.5.0
-Summary: Python client for the hosted CacheVerifier semantic-cache verification API
+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
 Project-URL: Source, https://github.com/imxinchengyou/cacheverifier-python
@@ -31,6 +31,10 @@ Requires-Dist: sentence-transformers<4,>=3.0; extra == 'healthcheck'
 Requires-Dist: torch>=2.2; extra == 'healthcheck'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Provides-Extra: local
+Requires-Dist: numpy<2,>=1.26; extra == 'local'
+Requires-Dist: sentence-transformers<4,>=3.0; extra == 'local'
+Requires-Dist: torch>=2.2; extra == 'local'
 Description-Content-Type: text/markdown
 
 # cacheverifier
@@ -60,6 +64,8 @@ pip install cacheverifier
 pip install "cacheverifier[gptcache]"
 # with the offline Health Check (adds torch + sentence-transformers):
 pip install "cacheverifier[healthcheck]"
+# to score with your fine-tuned model on your own machines (same deps):
+pip install "cacheverifier[local]"
 ```
 
 Requires Python 3.9+. The only runtime dependency is `httpx` — the extras above
@@ -179,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
@@ -198,6 +217,40 @@ if job.get("result_model_version"):
 `cv.dry_run([...])` reports the same baseline-vs-tuned AUC on examples you pass directly,
 without writing anything or deploying a model.
 
+## Local scoring (Managed plans)
+
+`LocalVerifier` runs the model CacheVerifier fine-tuned for you on your own
+machines: no network round trip on your request path, and your query and
+answer texts stay with you. Fine-tuning, drift monitoring, audits and
+certification keep running on the service.
+
+```python
+from cacheverifier import LocalVerifier
+
+cv = LocalVerifier(api_key="cv_...")       # downloads your live model in the background
+r = cv.verify(query, cached_answer, similarity_score=0.87, cached_query=cached_question)
+if r.approved:
+    ...                                    # serve from cache
+else:
+    answer = call_llm(query)
+    if r.audit:                            # a randomized audit: report whether the cached answer was right
+        cv.feedback(query, cached_answer, was_correct=same_answer(answer, cached_answer), result=r)
+```
+
+- It decides exactly as the hosted `/v1/verify` would with that model: every download
+  carries reference verdicts from the service, and a model that doesn't reproduce them
+  locally is not used.
+- When a newer model goes live (after a fine-tune or a scheduled recalibration), it is
+  downloaded, checked, and switched to without a restart.
+- While auditing is on, each decision is uploaded as scores, verdicts and a keyed hash of
+  the pair, never the texts, so audits and `/v1/monitor/risk` work as with the hosted API.
+- Until a model is ready, calls go to the hosted API (`fallback="hosted"`, the default)
+  or are rejected (`fallback="reject"`). Pass `wait=True` to block until the first
+  download finishes (a model is ~330MB).
+- The audit draw happens in this client. The risk bound assumes it is independent of
+  whether the answer is right, which the client guarantees unless it is modified.
+- Not supported yet: the online ACI threshold (local scoring uses the model's fixed one).
+
 ## Local Health Check (offline)
 
 `cv.dry_run()` still uploads your examples to the API. If that's a blocker — a
@@ -259,15 +312,18 @@ verdict
 
 | method | endpoint |
 |---|---|
-| `verify(query, candidate_answer)` | `POST /v1/verify` |
+| `verify(query, candidate_answer, similarity_score=..., cached_query=...)` | `POST /v1/verify` |
 | `verify_batch(pairs)` | `POST /v1/verify/batch` |
 | `feedback(...)` / `feedback_batch(items)` | `POST /v1/feedback` / `/batch` |
 | `finetune(...)` / `dry_run(examples, ...)` | `POST /v1/finetune/jobs` / `/dry-run` |
 | `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` |
+| `LocalVerifier.refresh()` | `GET /v1/models/active` + `/v1/models/{id}/files/{name}` |
 
 Non-2xx responses raise `CacheVerifierError` (`.status_code`, `.detail`).
 

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

@@ -25,6 +25,8 @@ pip install cacheverifier
 pip install "cacheverifier[gptcache]"
 # with the offline Health Check (adds torch + sentence-transformers):
 pip install "cacheverifier[healthcheck]"
+# to score with your fine-tuned model on your own machines (same deps):
+pip install "cacheverifier[local]"
 ```
 
 Requires Python 3.9+. The only runtime dependency is `httpx` — the extras above
@@ -144,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
@@ -163,6 +178,40 @@ if job.get("result_model_version"):
 `cv.dry_run([...])` reports the same baseline-vs-tuned AUC on examples you pass directly,
 without writing anything or deploying a model.
 
+## Local scoring (Managed plans)
+
+`LocalVerifier` runs the model CacheVerifier fine-tuned for you on your own
+machines: no network round trip on your request path, and your query and
+answer texts stay with you. Fine-tuning, drift monitoring, audits and
+certification keep running on the service.
+
+```python
+from cacheverifier import LocalVerifier
+
+cv = LocalVerifier(api_key="cv_...")       # downloads your live model in the background
+r = cv.verify(query, cached_answer, similarity_score=0.87, cached_query=cached_question)
+if r.approved:
+    ...                                    # serve from cache
+else:
+    answer = call_llm(query)
+    if r.audit:                            # a randomized audit: report whether the cached answer was right
+        cv.feedback(query, cached_answer, was_correct=same_answer(answer, cached_answer), result=r)
+```
+
+- It decides exactly as the hosted `/v1/verify` would with that model: every download
+  carries reference verdicts from the service, and a model that doesn't reproduce them
+  locally is not used.
+- When a newer model goes live (after a fine-tune or a scheduled recalibration), it is
+  downloaded, checked, and switched to without a restart.
+- While auditing is on, each decision is uploaded as scores, verdicts and a keyed hash of
+  the pair, never the texts, so audits and `/v1/monitor/risk` work as with the hosted API.
+- Until a model is ready, calls go to the hosted API (`fallback="hosted"`, the default)
+  or are rejected (`fallback="reject"`). Pass `wait=True` to block until the first
+  download finishes (a model is ~330MB).
+- The audit draw happens in this client. The risk bound assumes it is independent of
+  whether the answer is right, which the client guarantees unless it is modified.
+- Not supported yet: the online ACI threshold (local scoring uses the model's fixed one).
+
 ## Local Health Check (offline)
 
 `cv.dry_run()` still uploads your examples to the API. If that's a blocker — a
@@ -224,15 +273,18 @@ verdict
 
 | method | endpoint |
 |---|---|
-| `verify(query, candidate_answer)` | `POST /v1/verify` |
+| `verify(query, candidate_answer, similarity_score=..., cached_query=...)` | `POST /v1/verify` |
 | `verify_batch(pairs)` | `POST /v1/verify/batch` |
 | `feedback(...)` / `feedback_batch(items)` | `POST /v1/feedback` / `/batch` |
 | `finetune(...)` / `dry_run(examples, ...)` | `POST /v1/finetune/jobs` / `/dry-run` |
 | `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` |
+| `LocalVerifier.refresh()` | `GET /v1/models/active` + `/v1/models/{id}/files/{name}` |
 
 Non-2xx responses raise `CacheVerifierError` (`.status_code`, `.detail`).
 

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

@@ -17,6 +17,15 @@ Research behind it: https://github.com/imxinchengyou/CacheVerifier
 """
 
 from cacheverifier.client import CacheVerifier, CacheVerifierError, ShadowVerdict, VerifyResult
+from cacheverifier.local import LocalVerifier, ModelCheckFailed
 
-__version__ = "0.5.0"
-__all__ = ["CacheVerifier", "CacheVerifierError", "ShadowVerdict", "VerifyResult", "__version__"]
+__version__ = "0.7.0"
+__all__ = [
+    "CacheVerifier",
+    "CacheVerifierError",
+    "LocalVerifier",
+    "ModelCheckFailed",
+    "ShadowVerdict",
+    "VerifyResult",
+    "__version__",
+]

{cacheverifier-0.5.0 → cacheverifier-0.7.0}/cacheverifier/_healthcheck/_finetune.py

@@ -25,6 +25,7 @@ from sentence_transformers import CrossEncoder, InputExample
 from torch.utils.data import DataLoader
 
 from cacheverifier._healthcheck._base_models import DEFAULT_BASE_MODEL
+from cacheverifier._inference import MAX_SEQUENCE_LENGTH, smart_truncate_pair
 
 # The four third-party imports above are from the `healthcheck` extra. This module is
 # only ever imported from inside `cacheverifier._healthcheck.cli.run()`,
@@ -36,13 +37,11 @@ NLI_LABEL_ORDER = ("contradiction", "entailment", "neutral")
 """`cross-encoder/nli-*` models' class order, used when the loaded model
 doesn't expose an `id2label` naming them."""
 
-MAX_SEQUENCE_LENGTH = 128
-"""Token cap applied identically at train and score time. Matches the
-hosted service; BERT-style attention memory is O(n^2) in sequence length,
-and this keeps a CPU run well-behaved."""
-
-_CONTENT_TOKEN_BUDGET = MAX_SEQUENCE_LENGTH - 3  # [CLS] + 2x [SEP]
-_MIN_QUERY_TOKENS = 32
+# Token cap and truncation shared with local scoring, so a Health Check
+# trains with exactly what the service and `LocalVerifier` score with. Before
+# 0.6.0 this module kept its own copy of the truncation, which had fallen
+# behind the service's 0.7.0 change (a long query next to a short answer
+# was cut to half the budget).
 
 TRAIN_BATCH_SIZE = 4
 TRAIN_EPOCHS = 3
@@ -102,34 +101,6 @@ class HealthCheckResult:
         return self.auc_tuned - self.auc_baseline
 
 
-def _head_tail_truncate(ids: list[int], budget: int, head_ratio: float = 0.6) -> list[int]:
-    if len(ids) <= budget:
-        return ids
-    head_n = int(budget * head_ratio)
-    tail_n = budget - head_n
-    return ids[:head_n] + (ids[-tail_n:] if tail_n > 0 else [])
-
-
-def smart_truncate_pair(query: str, candidate_answer: str, tokenizer: Any) -> tuple[str, str]:
-    """Tokenizer-aware head+tail truncation, applied identically at train
-    and score time (a model trained on one truncation policy and scored
-    with another sees a different token window than it was optimized
-    against). A no-op whenever the pair already fits."""
-    query_ids = tokenizer.encode(query, add_special_tokens=False)
-    answer_ids = tokenizer.encode(candidate_answer, add_special_tokens=False)
-    if len(query_ids) + len(answer_ids) <= _CONTENT_TOKEN_BUDGET:
-        return query, candidate_answer
-
-    query_budget = min(len(query_ids), max(_MIN_QUERY_TOKENS, _CONTENT_TOKEN_BUDGET // 2))
-    answer_budget = _CONTENT_TOKEN_BUDGET - query_budget
-    query_ids = _head_tail_truncate(query_ids, query_budget)
-    answer_ids = _head_tail_truncate(answer_ids, answer_budget)
-    return (
-        tokenizer.decode(query_ids, skip_special_tokens=True),
-        tokenizer.decode(answer_ids, skip_special_tokens=True),
-    )
-
-
 def roc_auc(scores: np.ndarray, labels: np.ndarray) -> float:
     """Rank-based AUC, no sklearn dependency. NaN if either class is absent."""
     order = np.argsort(scores)

cacheverifier-0.7.0/cacheverifier/_inference.py

@@ -0,0 +1,162 @@
+"""The scoring and decision steps the hosted service applies to one
+(query, candidate_answer) pair, for running a downloaded model locally.
+
+A port of the hosted service's inference path: input composition with the
+`cached_query` diff, tokenizer-aware truncation, and the threshold / joint
+decision rules. Training, certification and monitoring stay on the service.
+Pure Python (the tokenizer is passed in), so it imports without the `local`
+extra.
+
+Kept in step with the service by two checks: the service's own test suite
+compares these functions with its implementation, and every model download
+carries reference verdicts that `LocalVerifier` reproduces before it decides
+anything (see `cacheverifier.local`).
+"""
+
+from __future__ import annotations
+
+import difflib
+import math
+from dataclasses import dataclass
+from typing import Any
+
+MAX_SEQUENCE_LENGTH = 128
+"""Token cap applied at train and score time, as on the service."""
+
+CONTENT_TOKEN_BUDGET = MAX_SEQUENCE_LENGTH - 3  # [CLS] + 2x [SEP]
+MIN_QUERY_TOKENS = 32
+QUERY_DIFF_MAX_WORDS = 12
+
+
+def query_diff_summary(current_query: str, cached_query: str) -> str:
+    """Word-level diff of the cache entry's own query against the request's,
+    e.g. `removed: pause | added: cancel`."""
+    old, new = cached_query.split(), current_query.split()
+    sm = difflib.SequenceMatcher(a=old, b=new, autojunk=False)
+    removed: list[str] = []
+    added: list[str] = []
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag in ("replace", "delete"):
+            removed.extend(old[i1:i2])
+        if tag in ("replace", "insert"):
+            added.extend(new[j1:j2])
+    parts = []
+    if removed:
+        parts.append("removed: " + " ".join(removed[:QUERY_DIFF_MAX_WORDS]))
+    if added:
+        parts.append("added: " + " ".join(added[:QUERY_DIFF_MAX_WORDS]))
+    return " | ".join(parts) if parts else "no change"
+
+
+def compose_query_input(current_query: str, cached_query: str | None) -> str:
+    if not cached_query:
+        return current_query
+    return f"{current_query} [qdiff] {query_diff_summary(current_query, cached_query)}"
+
+
+def _head_tail_truncate(ids: list[int], budget: int, head_ratio: float = 0.6) -> list[int]:
+    if len(ids) <= budget:
+        return ids
+    head_n = int(budget * head_ratio)
+    tail_n = budget - head_n
+    return ids[:head_n] + (ids[-tail_n:] if tail_n > 0 else [])
+
+
+def smart_truncate_pair(query: str, candidate_answer: str, tokenizer: Any) -> tuple[str, str]:
+    """Tokenizer-aware head+tail truncation, a no-op whenever the pair fits.
+    The answer gets at most half the budget while the query wants more; the
+    query gets whatever the answer doesn't need."""
+    query_ids = tokenizer.encode(query, add_special_tokens=False)
+    answer_ids = tokenizer.encode(candidate_answer, add_special_tokens=False)
+    if len(query_ids) + len(answer_ids) <= CONTENT_TOKEN_BUDGET:
+        return query, candidate_answer
+    half = CONTENT_TOKEN_BUDGET // 2
+    query_budget = min(len(query_ids), max(MIN_QUERY_TOKENS, half, CONTENT_TOKEN_BUDGET - len(answer_ids)))
+    answer_budget = CONTENT_TOKEN_BUDGET - query_budget
+    query_ids = _head_tail_truncate(query_ids, query_budget)
+    answer_ids = _head_tail_truncate(answer_ids, answer_budget)
+    return (
+        tokenizer.decode(query_ids, skip_special_tokens=True),
+        tokenizer.decode(answer_ids, skip_special_tokens=True),
+    )
+
+
+def _sigmoid(x: float) -> float:
+    if x >= 0.0:
+        return 1.0 / (1.0 + math.exp(-x))
+    e = math.exp(x)
+    return e / (1.0 + e)
+
+
+@dataclass(frozen=True)
+class JointRule:
+    """A fitted joint decision rule, as the service stores it: approve iff
+    the verifier score reaches `verifier_floor` (when set) and the fused
+    probability over the standardized similarity, verifier score (and, with
+    `uses_gap`, the gap to the runner-up match) reaches `threshold`."""
+
+    coef_similarity: float
+    coef_verifier: float
+    intercept: float
+    similarity_mean: float
+    similarity_std: float
+    verifier_mean: float
+    verifier_std: float
+    threshold: float
+    coef_gap: float = 0.0
+    gap_mean: float = 0.0
+    gap_std: float = 1.0
+    uses_gap: bool = False
+    verifier_floor: float | None = None
+
+    def approves(
+        self, verifier_score: float, similarity_score: float, runner_up_similarity_score: float | None = None
+    ) -> bool:
+        if self.verifier_floor is not None and verifier_score < self.verifier_floor:
+            return False
+        z_sim = (similarity_score - self.similarity_mean) / self.similarity_std
+        z_ver = (verifier_score - self.verifier_mean) / self.verifier_std
+        logit = self.coef_similarity * z_sim + self.coef_verifier * z_ver + self.intercept
+        if self.uses_gap:
+            if runner_up_similarity_score is None:
+                raise ValueError("this joint rule uses the similarity gap; runner_up_similarity_score is required")
+            z_gap = ((similarity_score - runner_up_similarity_score) - self.gap_mean) / self.gap_std
+            logit += self.coef_gap * z_gap
+        return _sigmoid(logit) >= self.threshold
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> JointRule:
+        floor = d.get("verifier_floor")
+        return cls(
+            coef_similarity=float(d["coef_similarity"]),
+            coef_verifier=float(d["coef_verifier"]),
+            intercept=float(d["intercept"]),
+            similarity_mean=float(d["similarity_mean"]),
+            similarity_std=float(d["similarity_std"]),
+            verifier_mean=float(d["verifier_mean"]),
+            verifier_std=float(d["verifier_std"]),
+            threshold=float(d["threshold"]),
+            coef_gap=float(d.get("coef_gap", 0.0)),
+            gap_mean=float(d.get("gap_mean", 0.0)),
+            gap_std=float(d.get("gap_std", 1.0)),
+            uses_gap=bool(d.get("uses_gap", False)),
+            verifier_floor=float(floor) if floor is not None else None,
+        )
+
+
+def decide(
+    score: float,
+    threshold: float,
+    joint_rule: JointRule | None,
+    joint_rule_gap: JointRule | None,
+    similarity_score: float | None,
+    runner_up_similarity_score: float | None,
+) -> tuple[bool, str]:
+    """(approved, decision_rule), with the service's precedence: the gap
+    rule when both similarity scores are given, then the 2-feature rule
+    when the similarity is, else the plain threshold."""
+    if joint_rule_gap is not None and similarity_score is not None and runner_up_similarity_score is not None:
+        return joint_rule_gap.approves(score, similarity_score, runner_up_similarity_score), "joint_gap"
+    if joint_rule is not None and similarity_score is not None:
+        return joint_rule.approves(score, similarity_score), "joint"
+    return score >= threshold, "threshold"

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

@@ -105,6 +105,14 @@ class VerifyResult:
     - `shadow`: on a cold-start call, what the shared stock model would have
       decided (a `ShadowVerdict`); None otherwise, and on servers that don't
       send it.
+    - `decision_rule`: `"threshold"`, `"joint"` / `"joint_gap"` (a fitted rule
+      that also used your similarity scores), `"aci"`, or `"cold_start"`.
+    - `audit`: this approval was drawn for a randomized audit, so `approved`
+      is False: call your LLM, serve its answer, and report whether the
+      cached answer matched with `feedback(..., verification_id=...)`.
+    - `verification_id`: set while auditing is on; pass it to `feedback()`.
+      From `LocalVerifier` it is None until the decision has been uploaded:
+      pass the result itself as `feedback(..., result=r)` instead.
     """
 
     approved: bool
@@ -115,6 +123,11 @@ class VerifyResult:
     degraded: bool = False
     notice: str | None = None
     shadow: ShadowVerdict | None = None
+    decision_rule: str | None = None
+    audit: bool = False
+    verification_id: int | None = None
+    local_decision: str | None = None
+    """`LocalVerifier` only: its handle for this decision until upload."""
 
     @classmethod
     def _from_json(cls, d: dict[str, Any]) -> VerifyResult:
@@ -127,6 +140,9 @@ class VerifyResult:
             latency_ms=float(d["latency_ms"]),
             notice=d.get("notice"),
             shadow=ShadowVerdict._from_json(shadow) if shadow else None,
+            decision_rule=d.get("decision_rule"),
+            audit=bool(d.get("audit", False)),
+            verification_id=d.get("verification_id"),
         )
 
 
@@ -194,15 +210,36 @@ class CacheVerifier:
 
     # -- core: verify ----------------------------------------------------
 
-    def verify(self, query: str, candidate_answer: str) -> VerifyResult:
+    def verify(
+        self,
+        query: str,
+        candidate_answer: str,
+        *,
+        similarity_score: float | None = None,
+        cached_query: str | None = None,
+        runner_up_similarity_score: float | None = None,
+    ) -> VerifyResult:
         """Approve or reject one gray-zone cache hit. `POST /v1/verify`.
 
+        The optional arguments are what your cache lookup already knows:
+        the hit's similarity score, the cached entry's own original query,
+        and the second-best match's similarity. A fine-tuned model uses them
+        when it learned a rule from them; they never hurt otherwise.
+
         On a timeout / connection error / 5xx / rate-limited 429 this returns a synthetic
         `VerifyResult` (`degraded=True`, `approved` per `fail_open`) instead of
         raising -- the verifier being unreachable should degrade to a normal
         cache miss, not an exception on your request path.
         """
-        data = self._verify_call("/v1/verify", {"query": query, "candidate_answer": candidate_answer})
+        payload = {"query": query, "candidate_answer": candidate_answer}
+        payload.update(
+            _drop_none(
+                similarity_score=similarity_score,
+                cached_query=cached_query,
+                runner_up_similarity_score=runner_up_similarity_score,
+            )
+        )
+        data = self._verify_call("/v1/verify", payload)
         if data is None:
             return self._degraded_result()
         return VerifyResult._from_json(data)
@@ -273,6 +310,9 @@ class CacheVerifier:
         was_correct: bool,
         *,
         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:
@@ -286,6 +326,11 @@ class CacheVerifier:
         - `similarity_score`: your cache backend's own score for this
           candidate, if you still have it. Only used by
           `gray_zone_threshold()`; safe to omit.
+        - `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.
@@ -297,15 +342,22 @@ class CacheVerifier:
             "was_correct": was_correct,
             "stale": stale,
         }
-        if similarity_score is not None:
-            payload["similarity_score"] = similarity_score
+        payload.update(
+            _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"])
 
     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)})
@@ -369,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")