cacheverifier 0.1.0__tar.gz

cacheverifier-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q
+      - run: mypy cacheverifier
+        if: matrix.python-version != '3.9'  # mypy config targets 3.10+
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

cacheverifier-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Publishes to PyPI via Trusted Publishing (OIDC) -- no API token stored
+# anywhere. Setup, done once on pypi.org: Account -> Publishing -> "Add a
+# pending publisher" with
+#   PyPI project name: cacheverifier
+#   Owner:             imxinchengyou
+#   Repository:        cacheverifier-python
+#   Workflow name:     publish.yml
+#   Environment:       pypi
+# Then publishing a GitHub Release runs this workflow and uploads the build.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

cacheverifier-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage

cacheverifier-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+Initial release: thin `httpx`-based client for `/v1/verify`, `/v1/verify/batch`,
+`/v1/feedback`(`/batch`), fine-tune jobs + dry run, drift and gray-zone-threshold
+monitoring, and usage/savings. GPTCache `SimilarityEvaluation` adapter under
+`cacheverifier.integrations.gptcache`.

cacheverifier-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chengyou Xin
+
+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.

cacheverifier-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: cacheverifier
+Version: 0.1.0
+Summary: Python client for the hosted CacheVerifier semantic-cache verification API
+Project-URL: Homepage, https://www.cacheverifier.com
+Project-URL: Documentation, https://www.cacheverifier.com/docs
+Project-URL: Source, https://github.com/imxinchengyou/cacheverifier-python
+Project-URL: Research, https://github.com/imxinchengyou/CacheVerifier
+Author: Chengyou Xin
+License: MIT
+License-File: LICENSE
+Keywords: cache-verification,cross-encoder,gptcache,llm,llm-caching,semantic-cache,semantic-cache-verification
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: gptcache
+Requires-Dist: gptcache>=0.1.30; extra == 'gptcache'
+Description-Content-Type: text/markdown
+
+# cacheverifier
+
+[![CI](https://github.com/imxinchengyou/cacheverifier-python/actions/workflows/ci.yml/badge.svg)](https://github.com/imxinchengyou/cacheverifier-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/cacheverifier)](https://pypi.org/project/cacheverifier/)
+[![Python](https://img.shields.io/pypi/pyversions/cacheverifier)](https://pypi.org/project/cacheverifier/)
+
+Python client for **[CacheVerifier](https://www.cacheverifier.com)** — a hosted API that
+verifies semantic-cache hits. Given a query and a candidate cached answer, it approves or
+rejects serving that answer from cache, so a similarity match that is *close but wrong*
+doesn't become a silent error in your app.
+
+CacheVerifier does **not** run your cache or do similarity search. Your cache backend does
+its own lookup first; you call `verify()` only on the candidates in the similarity "gray
+zone", where a plain threshold match might be wrong.
+
+- Docs / API reference: <https://www.cacheverifier.com/docs>
+- Why similarity ≠ correctness: <https://www.cacheverifier.com/why-similarity-fails>
+- The research behind it (paper + benchmarks): <https://github.com/imxinchengyou/CacheVerifier>
+
+## Install
+
+```bash
+pip install cacheverifier
+# with the GPTCache adapter:
+pip install "cacheverifier[gptcache]"
+```
+
+Requires Python 3.9+. The only runtime dependency is `httpx`.
+
+## Quickstart
+
+Get a free API key at <https://www.cacheverifier.com> (self-serve verify and fine-tuning
+are free forever, no card).
+
+```python
+from cacheverifier import CacheVerifier
+
+cv = CacheVerifier(api_key="cv_...")
+
+query = "how do I cancel my subscription"
+candidate = "Go to Settings > Billing > Pause subscription for a month."  # from your cache
+
+result = cv.verify(query, candidate)
+if result.approved:
+    answer = candidate                       # verified hit — skip the LLM call
+else:
+    answer = call_your_llm(query)            # not trustworthy — fall through
+
+# Later, once you know if it was actually right (thumbs-down, reopened ticket, ...):
+cv.feedback(query, answer, was_correct=True, similarity_score=0.86)
+```
+
+`verify()` returns a `VerifyResult`:
+
+| field | meaning |
+|---|---|
+| `approved` | serve the cached answer (`True`) or fall through (`False`) |
+| `score` / `threshold` | `approved` is `score >= threshold` |
+| `model_version` | `"stock"`, `"v<id>"` (fine-tuned), or `"cold_start_fail_closed"` |
+| `latency_ms` | server-side inference time |
+
+## GPTCache
+
+Drop the verifier into a GPTCache pipeline as its similarity evaluator — no fork required:
+
+```python
+from gptcache import cache
+from cacheverifier.integrations.gptcache import CacheVerifierEvaluation
+
+evaluator = CacheVerifierEvaluation(api_key="cv_...")
+cache.init(similarity_evaluation=evaluator, ...)
+
+# when you learn a served hit's real outcome:
+evaluator.report_feedback(query, answer, was_correct=False, similarity_score=0.9)
+```
+
+See [`examples/gptcache_example.py`](examples/gptcache_example.py).
+
+## Fine-tuning
+
+Once you have ~20+ feedback rows (the service found fine-tuning is often a net negative
+below ~1,000 on the hardest data — see the [research](https://github.com/imxinchengyou/CacheVerifier)),
+train a verifier on your own gray-zone labels:
+
+```python
+job = cv.finetune()                       # or cv.finetune(target_risk=0.01, cost_ratio=5.0)
+job = cv.get_finetune_job(job["id"])      # poll until status == "done"
+print(job["auc_baseline"], job["auc_tuned"])
+
+# a model can finish as "held_for_review" — promote it explicitly:
+if job.get("result_model_version"):
+    cv.activate_model_version(job["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.
+
+## API surface
+
+| method | endpoint |
+|---|---|
+| `verify(query, candidate_answer)` | `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` |
+| `gray_zone_threshold()` | `GET /v1/monitor/gray-zone-threshold` |
+| `usage()` / `savings()` | `GET /v1/usage/status` / `/savings` |
+
+Non-2xx responses raise `CacheVerifierError` (`.status_code`, `.detail`).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). (The [research repository](https://github.com/imxinchengyou/CacheVerifier)
+is separately licensed; this client is not.)

cacheverifier-0.1.0/README.md

@@ -0,0 +1,117 @@
+# cacheverifier
+
+[![CI](https://github.com/imxinchengyou/cacheverifier-python/actions/workflows/ci.yml/badge.svg)](https://github.com/imxinchengyou/cacheverifier-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/cacheverifier)](https://pypi.org/project/cacheverifier/)
+[![Python](https://img.shields.io/pypi/pyversions/cacheverifier)](https://pypi.org/project/cacheverifier/)
+
+Python client for **[CacheVerifier](https://www.cacheverifier.com)** — a hosted API that
+verifies semantic-cache hits. Given a query and a candidate cached answer, it approves or
+rejects serving that answer from cache, so a similarity match that is *close but wrong*
+doesn't become a silent error in your app.
+
+CacheVerifier does **not** run your cache or do similarity search. Your cache backend does
+its own lookup first; you call `verify()` only on the candidates in the similarity "gray
+zone", where a plain threshold match might be wrong.
+
+- Docs / API reference: <https://www.cacheverifier.com/docs>
+- Why similarity ≠ correctness: <https://www.cacheverifier.com/why-similarity-fails>
+- The research behind it (paper + benchmarks): <https://github.com/imxinchengyou/CacheVerifier>
+
+## Install
+
+```bash
+pip install cacheverifier
+# with the GPTCache adapter:
+pip install "cacheverifier[gptcache]"
+```
+
+Requires Python 3.9+. The only runtime dependency is `httpx`.
+
+## Quickstart
+
+Get a free API key at <https://www.cacheverifier.com> (self-serve verify and fine-tuning
+are free forever, no card).
+
+```python
+from cacheverifier import CacheVerifier
+
+cv = CacheVerifier(api_key="cv_...")
+
+query = "how do I cancel my subscription"
+candidate = "Go to Settings > Billing > Pause subscription for a month."  # from your cache
+
+result = cv.verify(query, candidate)
+if result.approved:
+    answer = candidate                       # verified hit — skip the LLM call
+else:
+    answer = call_your_llm(query)            # not trustworthy — fall through
+
+# Later, once you know if it was actually right (thumbs-down, reopened ticket, ...):
+cv.feedback(query, answer, was_correct=True, similarity_score=0.86)
+```
+
+`verify()` returns a `VerifyResult`:
+
+| field | meaning |
+|---|---|
+| `approved` | serve the cached answer (`True`) or fall through (`False`) |
+| `score` / `threshold` | `approved` is `score >= threshold` |
+| `model_version` | `"stock"`, `"v<id>"` (fine-tuned), or `"cold_start_fail_closed"` |
+| `latency_ms` | server-side inference time |
+
+## GPTCache
+
+Drop the verifier into a GPTCache pipeline as its similarity evaluator — no fork required:
+
+```python
+from gptcache import cache
+from cacheverifier.integrations.gptcache import CacheVerifierEvaluation
+
+evaluator = CacheVerifierEvaluation(api_key="cv_...")
+cache.init(similarity_evaluation=evaluator, ...)
+
+# when you learn a served hit's real outcome:
+evaluator.report_feedback(query, answer, was_correct=False, similarity_score=0.9)
+```
+
+See [`examples/gptcache_example.py`](examples/gptcache_example.py).
+
+## Fine-tuning
+
+Once you have ~20+ feedback rows (the service found fine-tuning is often a net negative
+below ~1,000 on the hardest data — see the [research](https://github.com/imxinchengyou/CacheVerifier)),
+train a verifier on your own gray-zone labels:
+
+```python
+job = cv.finetune()                       # or cv.finetune(target_risk=0.01, cost_ratio=5.0)
+job = cv.get_finetune_job(job["id"])      # poll until status == "done"
+print(job["auc_baseline"], job["auc_tuned"])
+
+# a model can finish as "held_for_review" — promote it explicitly:
+if job.get("result_model_version"):
+    cv.activate_model_version(job["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.
+
+## API surface
+
+| method | endpoint |
+|---|---|
+| `verify(query, candidate_answer)` | `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` |
+| `gray_zone_threshold()` | `GET /v1/monitor/gray-zone-threshold` |
+| `usage()` / `savings()` | `GET /v1/usage/status` / `/savings` |
+
+Non-2xx responses raise `CacheVerifierError` (`.status_code`, `.detail`).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE). (The [research repository](https://github.com/imxinchengyou/CacheVerifier)
+is separately licensed; this client is not.)

cacheverifier-0.1.0/cacheverifier/__init__.py

@@ -0,0 +1,22 @@
+"""cacheverifier -- Python client for the hosted CacheVerifier API.
+
+CacheVerifier verifies semantic-cache hits: given a query and a candidate
+cached answer, it approves or rejects serving that answer from cache, so a
+similarity match that is close but wrong doesn't become a silent error.
+
+    from cacheverifier import CacheVerifier
+
+    cv = CacheVerifier(api_key="cv_...")
+    if cv.verify(query, candidate_answer).approved:
+        ...  # serve from cache
+    else:
+        ...  # fall through to your LLM
+
+Docs: https://www.cacheverifier.com/docs
+Research behind it: https://github.com/imxinchengyou/CacheVerifier
+"""
+
+from cacheverifier.client import CacheVerifier, CacheVerifierError, VerifyResult
+
+__version__ = "0.1.0"
+__all__ = ["CacheVerifier", "CacheVerifierError", "VerifyResult", "__version__"]

cacheverifier-0.1.0/cacheverifier/client.py

@@ -0,0 +1,278 @@
+"""Thin Python client for the hosted CacheVerifier API (https://www.cacheverifier.com).
+
+CacheVerifier does not run your semantic cache or do similarity search. Your
+cache backend does its own lookup first; you call `verify()` only on the
+candidates in the similarity "gray zone", where a plain threshold match
+might be wrong. See https://www.cacheverifier.com/docs for the full API.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://www.cacheverifier.com"
+DEFAULT_TIMEOUT = 10.0
+
+__all__ = ["CacheVerifier", "CacheVerifierError", "VerifyResult"]
+
+
+class CacheVerifierError(RuntimeError):
+    """Raised for any non-2xx response from the API.
+
+    `status_code` is the HTTP status; `detail` is the server's error message
+    (the JSON body's `detail` field when present, otherwise the raw text).
+    """
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        super().__init__(f"CacheVerifier API error {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    """One `/v1/verify` decision.
+
+    - `approved`: serve the cached answer (True) or fall through to your LLM (False).
+    - `score`: the verifier's raw score for this pair; `approved` is `score >= threshold`.
+    - `threshold`: the cutoff this call was decided against (tenant-specific once
+      you've fine-tuned; 0.0 on the shared stock model).
+    - `model_version`: `"stock"`, `"v<id>"` for a fine-tuned model, or
+      `"cold_start_fail_closed"` when no model ran (see `cold_start_mode`).
+    - `latency_ms`: server-side model inference time, not round-trip time.
+    """
+
+    approved: bool
+    score: float
+    threshold: float
+    model_version: str
+    latency_ms: float
+
+    @classmethod
+    def _from_json(cls, d: dict[str, Any]) -> VerifyResult:
+        return cls(
+            approved=bool(d["approved"]),
+            score=float(d["score"]),
+            threshold=float(d["threshold"]),
+            model_version=str(d["model_version"]),
+            latency_ms=float(d["latency_ms"]),
+        )
+
+
+class CacheVerifier:
+    """Client for the hosted CacheVerifier API.
+
+        from cacheverifier import CacheVerifier
+
+        cv = CacheVerifier(api_key="cv_...")
+        result = cv.verify("how do I cancel", "Go to Settings > Billing > Pause.")
+        if result.approved:
+            ...  # serve the cached answer
+        else:
+            ...  # fall through to your LLM
+
+    Usable as a context manager (`with CacheVerifier(...) as cv:`) to close
+    the underlying HTTP connection pool deterministically.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required -- get one at https://www.cacheverifier.com")
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"X-API-Key": api_key, "User-Agent": _user_agent()},
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> CacheVerifier:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # -- core: verify ----------------------------------------------------
+
+    def verify(self, query: str, candidate_answer: str) -> VerifyResult:
+        """Approve or reject one gray-zone cache hit. `POST /v1/verify`."""
+        data = self._post("/v1/verify", json={"query": query, "candidate_answer": candidate_answer})
+        return VerifyResult._from_json(data)
+
+    def verify_batch(self, pairs: Sequence[tuple[str, str]]) -> list[VerifyResult]:
+        """Verify many `(query, candidate_answer)` pairs in one request and
+        one batched forward pass. `POST /v1/verify/batch` (max 100 items).
+
+        Useful when your own retrieval returns several close candidates:
+        send them in rank order and take the first `approved` one.
+        """
+        items = [{"query": q, "candidate_answer": a} for q, a in pairs]
+        data = self._post("/v1/verify/batch", json={"items": items})
+        return [VerifyResult._from_json(r) for r in data["results"]]
+
+    # -- feedback ------------------------------------------------------
+
+    def feedback(
+        self,
+        query: str,
+        candidate_answer: str,
+        was_correct: bool,
+        *,
+        similarity_score: float | None = None,
+        stale: bool = False,
+        idempotency_key: str | None = None,
+    ) -> int:
+        """Record whether a served (or considered) hit was actually correct.
+        Returns the created row id. `POST /v1/feedback`.
+
+        This is the ground-truth signal fine-tuning and drift monitoring
+        learn from -- you supply it from a thumbs-down, a reopened ticket,
+        manual review, etc.
+
+        - `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.
+        - `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.
+        - `idempotency_key`: pass a stable key to make retries safe.
+        """
+        payload: dict[str, Any] = {
+            "query": query,
+            "candidate_answer": candidate_answer,
+            "was_correct": was_correct,
+            "stale": stale,
+        }
+        if similarity_score is not None:
+            payload["similarity_score"] = similarity_score
+        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.
+        `POST /v1/feedback/batch`.
+        """
+        data = self._post("/v1/feedback/batch", json={"items": list(items)})
+        return [int(i) for i in data["ids"]]
+
+    # -- fine-tuning -------------------------------------------------
+
+    def finetune(self, *, target_risk: float | None = None, cost_ratio: float | None = None) -> dict[str, Any]:
+        """Kick off fine-tuning on all feedback submitted so far. Returns the
+        job (poll `get_finetune_job(job['id'])` for completion + AUC).
+        `POST /v1/finetune/jobs`.
+
+        - `target_risk`: e.g. `0.01` to also certify a threshold at 1%
+          false-reuse risk via Conformal Risk Control.
+        - `cost_ratio`: pick the live threshold by cost (how many times more
+          a wrong reuse costs than a miss) instead of the default Youden's J.
+        """
+        return self._post("/v1/finetune/jobs", params=_drop_none(target_risk=target_risk, cost_ratio=cost_ratio))
+
+    def dry_run(
+        self,
+        examples: Sequence[dict[str, Any]],
+        *,
+        target_risk: float | None = None,
+        cost_ratio: float | None = None,
+    ) -> dict[str, Any]:
+        """Baseline-vs-fine-tuned AUC on `examples` given directly here --
+        nothing is written to your feedback history and no model is
+        deployed. Each example is a dict with `query`, `candidate_answer`,
+        `was_correct` (and optional `stale`). `POST /v1/finetune/dry-run`.
+        """
+        return self._post(
+            "/v1/finetune/dry-run",
+            json={"examples": list(examples)},
+            params=_drop_none(target_risk=target_risk, cost_ratio=cost_ratio),
+        )
+
+    def get_finetune_job(self, job_id: int) -> dict[str, Any]:
+        """`GET /v1/finetune/jobs/{id}`."""
+        return self._get(f"/v1/finetune/jobs/{job_id}")
+
+    def list_finetune_jobs(self) -> list[dict[str, Any]]:
+        """`GET /v1/finetune/jobs`."""
+        return self._get("/v1/finetune/jobs")
+
+    def activate_model_version(self, model_version_id: int) -> dict[str, Any]:
+        """Promote a model that finished as `held_for_review`.
+        `POST /v1/finetune/model-versions/{id}/activate`.
+        """
+        return self._post(f"/v1/finetune/model-versions/{model_version_id}/activate")
+
+    # -- monitoring / usage ----------------------------------------
+
+    def drift_status(self) -> dict[str, Any]:
+        """`GET /v1/monitor/drift-status` (needs an active fine-tuned model)."""
+        return self._get("/v1/monitor/drift-status")
+
+    def gray_zone_threshold(self) -> dict[str, Any]:
+        """Recommend a tau_high for YOUR cache backend, replaying feedback
+        rows that included `similarity_score`. `GET /v1/monitor/gray-zone-threshold`.
+        """
+        return self._get("/v1/monitor/gray-zone-threshold")
+
+    def usage(self) -> dict[str, Any]:
+        """`GET /v1/usage/status`."""
+        return self._get("/v1/usage/status")
+
+    def savings(self) -> dict[str, Any]:
+        """This period's estimated LLM calls and wrong hits avoided.
+        `GET /v1/usage/savings`.
+        """
+        return self._get("/v1/usage/savings")
+
+    # -- plumbing ----------------------------------------------------
+
+    def _get(self, path: str) -> Any:
+        return self._unwrap(self._client.get(path))
+
+    def _post(
+        self,
+        path: str,
+        *,
+        json: Any | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        return self._unwrap(self._client.post(path, json=json, params=params or None, headers=headers))
+
+    @staticmethod
+    def _unwrap(resp: httpx.Response) -> Any:
+        if resp.is_success:
+            return resp.json()
+        detail: str
+        try:
+            body = resp.json()
+            detail = body["detail"] if isinstance(body, dict) and "detail" in body else resp.text
+        except ValueError:
+            detail = resp.text
+        raise CacheVerifierError(resp.status_code, str(detail))
+
+
+def _drop_none(**kwargs: Any) -> dict[str, Any]:
+    return {k: v for k, v in kwargs.items() if v is not None}
+
+
+def _user_agent() -> str:
+    from cacheverifier import __version__
+
+    return f"cacheverifier-python/{__version__} httpx/{httpx.__version__}"

cacheverifier-0.1.0/cacheverifier/integrations/__init__.py

@@ -0,0 +1,7 @@
+"""Cache-backend integrations for CacheVerifier.
+
+Each integration wraps `cacheverifier.CacheVerifier` in the extension point
+a given cache library already exposes, so verification is a drop-in change
+with no upstream fork required. GPTCache is the first; the same pattern
+applies to any backend with a "should I trust this candidate" hook.
+"""

cacheverifier-0.1.0/cacheverifier/integrations/gptcache.py

@@ -0,0 +1,84 @@
+"""GPTCache integration: a `SimilarityEvaluation` that calls the hosted
+CacheVerifier `/v1/verify` endpoint instead of relying on cosine/dot-product
+similarity alone.
+
+GPTCache's `SimilarityEvaluation` interface (`evaluation()` + `range()`) is
+a zero-friction integration point: any subclass drops straight into a
+GPTCache pipeline's `similarity_evaluation=` argument, no upstream PR
+required.
+
+    from gptcache import cache
+    from cacheverifier.integrations.gptcache import CacheVerifierEvaluation
+
+    cache.init(
+        similarity_evaluation=CacheVerifierEvaluation(api_key="cv_..."),
+        ...
+    )
+
+`gptcache` is an optional dependency -- `pip install "cacheverifier[gptcache]"`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cacheverifier.client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, CacheVerifier
+
+try:
+    from gptcache.similarity_evaluation import SimilarityEvaluation as _GPTCacheBase
+except ImportError:  # keep importable without gptcache installed
+    _GPTCacheBase = object
+
+
+class CacheVerifierEvaluation(_GPTCacheBase):
+    """Drop-in replacement for GPTCache's built-in similarity evaluators.
+
+    `evaluation()` returns 1.0 (reuse) or 0.0 (don't) -- binary, because the
+    hosted verifier already makes a binary approve/reject call per gray-zone
+    hit rather than a softened similarity score. Callers who want GPTCache's
+    own threshold logic on top can wrap this rather than replace it.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._cv = CacheVerifier(api_key=api_key, base_url=base_url, timeout=timeout)
+
+    def evaluation(self, src_dict: dict[str, Any], cache_dict: dict[str, Any], **_kwargs: Any) -> float:
+        query = src_dict.get("question") or src_dict.get("query", "")
+        candidate_answer = cache_dict.get("answer", "")
+        return 1.0 if self._cv.verify(query, candidate_answer).approved else 0.0
+
+    def range(self) -> tuple[float, float]:
+        return 0.0, 1.0
+
+    def report_feedback(
+        self,
+        query: str,
+        candidate_answer: str,
+        was_correct: bool,
+        similarity_score: float | None = None,
+    ) -> None:
+        """Not part of GPTCache's interface -- call it once you know whether
+        a served hit was actually correct (a thumbs-down, a reopened
+        ticket, ...). Feeds `POST /v1/feedback`, which fine-tuning and drift
+        monitoring both consume.
+
+        `similarity_score` is optional: pass GPTCache's own vector-search
+        score for this candidate if you still have it when you learn
+        `was_correct` -- that is what lets the service later recommend a
+        tau_high for your GPTCache config (`gray_zone_threshold()`).
+        """
+        self._cv.feedback(
+            query,
+            candidate_answer,
+            was_correct,
+            similarity_score=similarity_score,
+        )
+
+    def close(self) -> None:
+        self._cv.close()

cacheverifier-0.1.0/examples/gptcache_example.py

@@ -0,0 +1,46 @@
+"""Wire CacheVerifier into a GPTCache pipeline as the similarity evaluator.
+
+    pip install "cacheverifier[gptcache]"
+    CACHEVERIFIER_API_KEY=cv_... python gptcache_example.py
+
+The only CacheVerifier-specific line is `similarity_evaluation=...`. Every
+gray-zone lookup GPTCache would otherwise decide on cosine similarity alone
+now gets one synchronous verifier call instead.
+"""
+
+import os
+
+from gptcache import cache
+from gptcache.adapter.api import get, put
+from gptcache.embedding import Onnx
+from gptcache.manager import CacheBase, VectorBase, get_data_manager
+
+from cacheverifier.integrations.gptcache import CacheVerifierEvaluation
+
+embedding = Onnx()
+data_manager = get_data_manager(
+    CacheBase("sqlite"),
+    VectorBase("faiss", dimension=embedding.dimension),
+)
+
+evaluator = CacheVerifierEvaluation(api_key=os.environ["CACHEVERIFIER_API_KEY"])
+
+cache.init(
+    embedding_func=embedding.to_embeddings,
+    data_manager=data_manager,
+    similarity_evaluation=evaluator,
+)
+
+put("how do I cancel my subscription?", "Go to Settings > Billing > Cancel subscription.")
+
+# Close-but-different intent. Cosine similarity would likely reuse the
+# cached answer; the verifier call decides whether that is actually safe.
+hit = get("how do I pause my subscription for a month?")
+print("cache returned:", hit)
+
+# When you later learn whether a served hit was right:
+evaluator.report_feedback(
+    "how do I pause my subscription for a month?",
+    hit or "",
+    was_correct=False,
+)

cacheverifier-0.1.0/examples/quickstart.py

@@ -0,0 +1,51 @@
+"""CacheVerifier quickstart -- verify one gray-zone cache hit, then report
+the outcome back. Runs against the live API.
+
+    pip install cacheverifier
+    CACHEVERIFIER_API_KEY=cv_... python quickstart.py
+
+Get a free key at https://www.cacheverifier.com (self-serve verify and
+fine-tuning are free forever).
+"""
+
+import os
+
+from cacheverifier import CacheVerifier
+
+
+def call_your_llm(query: str) -> str:
+    """Stand-in for your own LLM call. CacheVerifier doesn't do this part --
+    your cache backend already has one."""
+    return "Go to Settings > Billing > Cancel subscription."
+
+
+def main() -> None:
+    api_key = os.environ["CACHEVERIFIER_API_KEY"]
+
+    # A gray-zone example: your cache's similarity search found a candidate
+    # close enough to look like a match, but "cancel" vs "pause" is a real
+    # difference a plain similarity threshold can't tell apart.
+    query = "how do I cancel my subscription"
+    candidate = "Go to Settings > Billing > Pause subscription for a month."
+
+    with CacheVerifier(api_key=api_key) as cv:
+        result = cv.verify(query, candidate)
+        print(f"verify -> approved={result.approved} score={result.score:.3f} "
+              f"threshold={result.threshold} model={result.model_version}")
+
+        if result.approved:
+            answer = candidate
+            print("approved: serving the cached answer, no LLM call made.")
+        else:
+            answer = call_your_llm(query)
+            print(f"rejected: fell through to your LLM -> {answer!r}")
+
+        # Once you know the real outcome (thumbs-down, reopened ticket,
+        # manual review), report it. This is what fine-tuning and drift
+        # monitoring learn from.
+        row_id = cv.feedback(query, answer, was_correct=True, similarity_score=0.86)
+        print(f"feedback recorded (row {row_id})")
+
+
+if __name__ == "__main__":
+    main()

cacheverifier-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cacheverifier"
+version = "0.1.0"
+description = "Python client for the hosted CacheVerifier semantic-cache verification API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Chengyou Xin" }]
+keywords = [
+    "semantic-cache",
+    "semantic-cache-verification",
+    "llm",
+    "llm-caching",
+    "gptcache",
+    "cache-verification",
+    "cross-encoder",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://www.cacheverifier.com"
+Documentation = "https://www.cacheverifier.com/docs"
+Source = "https://github.com/imxinchengyou/cacheverifier-python"
+Research = "https://github.com/imxinchengyou/CacheVerifier"
+
+[project.optional-dependencies]
+gptcache = ["gptcache>=0.1.30"]
+dev = ["pytest>=7", "mypy>=1.5", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["cacheverifier"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py39"
+
+[tool.ruff.lint]
+# PYI034 wants `Self` as the __enter__ return type; not available on the
+# 3.9 floor without a typing_extensions dependency this client doesn't need.
+ignore = ["PYI034"]
+
+[tool.mypy]
+python_version = "3.10"
+disallow_untyped_defs = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+
+[[tool.mypy.overrides]]
+module = "gptcache.*"
+ignore_missing_imports = true

cacheverifier-0.1.0/tests/test_client.py

@@ -0,0 +1,144 @@
+"""Offline tests: every request is served by an httpx.MockTransport, so
+nothing here touches the network."""
+
+import json
+
+import httpx
+import pytest
+
+from cacheverifier import CacheVerifier, CacheVerifierError, VerifyResult
+
+
+def make_client(handler):
+    return CacheVerifier(api_key="cv_test", transport=httpx.MockTransport(handler))
+
+
+def test_verify_parses_result_and_sends_api_key():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["api_key"] = request.headers.get("X-API-Key")
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(
+            200,
+            json={
+                "approved": True,
+                "score": 3.5,
+                "latency_ms": 24.1,
+                "model_version": "stock",
+                "threshold": 0.0,
+            },
+        )
+
+    with make_client(handler) as cv:
+        result = cv.verify("how do I cancel", "Go to Settings > Billing.")
+
+    assert isinstance(result, VerifyResult)
+    assert result.approved is True
+    assert result.score == 3.5
+    assert result.threshold == 0.0
+    assert result.model_version == "stock"
+    assert seen["path"] == "/v1/verify"
+    assert seen["api_key"] == "cv_test"
+    assert seen["body"] == {"query": "how do I cancel", "candidate_answer": "Go to Settings > Billing."}
+
+
+def test_verify_batch_returns_ordered_results():
+    def handler(request: httpx.Request) -> httpx.Response:
+        items = json.loads(request.content)["items"]
+        assert request.url.path == "/v1/verify/batch"
+        return httpx.Response(
+            200,
+            json={
+                "results": [
+                    {
+                        "approved": i == 0,
+                        "score": 5.0 - i,
+                        "latency_ms": 10.0,
+                        "model_version": "v7",
+                        "threshold": 1.0,
+                    }
+                    for i, _ in enumerate(items)
+                ]
+            },
+        )
+
+    with make_client(handler) as cv:
+        results = cv.verify_batch([("q1", "a1"), ("q2", "a2")])
+
+    assert [r.approved for r in results] == [True, False]
+    assert results[0].model_version == "v7"
+
+
+def test_feedback_returns_id_and_forwards_idempotency_key():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json={"id": 42})
+
+    with make_client(handler) as cv:
+        row_id = cv.feedback(
+            "q", "a", was_correct=False, similarity_score=0.86, stale=True, idempotency_key="abc-123"
+        )
+
+    assert row_id == 42
+    assert seen["idem"] == "abc-123"
+    assert seen["body"] == {
+        "query": "q",
+        "candidate_answer": "a",
+        "was_correct": False,
+        "stale": True,
+        "similarity_score": 0.86,
+    }
+
+
+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 request.headers.get("Idempotency-Key") is None
+        return httpx.Response(200, json={"id": 1})
+
+    with make_client(handler) as cv:
+        assert cv.feedback("q", "a", was_correct=True) == 1
+
+
+def test_finetune_passes_query_params():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/finetune/jobs"
+        assert dict(request.url.params) == {"target_risk": "0.01", "cost_ratio": "5.0"}
+        return httpx.Response(200, json={"id": 3, "status": "queued"})
+
+    with make_client(handler) as cv:
+        job = cv.finetune(target_risk=0.01, cost_ratio=5.0)
+
+    assert job["status"] == "queued"
+
+
+def test_error_response_raises_with_detail():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(429, json={"detail": "free tier limit reached"})
+
+    with make_client(handler) as cv, pytest.raises(CacheVerifierError) as excinfo:
+        cv.verify("q", "a")
+
+    assert excinfo.value.status_code == 429
+    assert excinfo.value.detail == "free tier limit reached"
+
+
+def test_error_response_without_json_body_falls_back_to_text():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(502, text="Bad Gateway")
+
+    with make_client(handler) as cv, pytest.raises(CacheVerifierError) as excinfo:
+        cv.usage()
+
+    assert excinfo.value.status_code == 502
+    assert "Bad Gateway" in excinfo.value.detail
+
+
+def test_empty_api_key_rejected():
+    with pytest.raises(ValueError):
+        CacheVerifier(api_key="")

cacheverifier-0.1.0/tests/test_gptcache_integration.py

@@ -0,0 +1,55 @@
+"""The GPTCache adapter must stay importable and usable even when gptcache
+itself isn't installed (it's an optional dependency)."""
+
+import httpx
+
+from cacheverifier.integrations.gptcache import CacheVerifierEvaluation
+
+
+def _eval(handler) -> CacheVerifierEvaluation:
+    ev = CacheVerifierEvaluation(api_key="cv_test")
+    ev._cv._client = httpx.Client(  # swap in a mock transport
+        base_url="https://www.cacheverifier.com",
+        headers={"X-API-Key": "cv_test"},
+        transport=httpx.MockTransport(handler),
+    )
+    return ev
+
+
+def test_evaluation_maps_approved_to_binary_score():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/verify"
+        return httpx.Response(
+            200,
+            json={"approved": True, "score": 2.0, "latency_ms": 5.0, "model_version": "stock", "threshold": 0.0},
+        )
+
+    ev = _eval(handler)
+    assert ev.evaluation({"question": "q"}, {"answer": "a"}) == 1.0
+    assert ev.range() == (0.0, 1.0)
+
+
+def test_evaluation_rejects_to_zero():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json={"approved": False, "score": -1.0, "latency_ms": 5.0, "model_version": "stock", "threshold": 0.0},
+        )
+
+    assert _eval(handler).evaluation({"query": "q"}, {"answer": "a"}) == 0.0
+
+
+def test_report_feedback_posts_similarity_score():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        import json
+
+        seen["path"] = request.url.path
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json={"id": 9})
+
+    _eval(handler).report_feedback("q", "a", was_correct=False, similarity_score=0.9)
+    assert seen["path"] == "/v1/feedback"
+    assert seen["body"]["similarity_score"] == 0.9
+    assert seen["body"]["was_correct"] is False