cachecore-python 0.1.0__py3-none-any.whl

cachecore/__init__.py

@@ -0,0 +1,367 @@
+"""
+CacheCore Python client — thin adapter for the CacheCore caching proxy.
+
+This library handles CacheCore-specific concerns (header injection,
+dependency encoding, invalidation) without replacing or wrapping the
+LLM SDK.  You keep using ``openai.AsyncOpenAI``, ``ChatOpenAI``, etc.
+exactly as before.
+
+Quick start::
+
+    from cachecore import CacheCoreClient, Dep
+
+    cc = CacheCoreClient(
+        gateway_url="http://localhost:8080",
+        tenant_jwt="ey...",
+    )
+
+    # Inject into any OpenAI-compatible SDK
+    import httpx
+    from openai import AsyncOpenAI
+
+    oai = AsyncOpenAI(
+        api_key="ignored",
+        base_url="http://localhost:8080/v1",
+        http_client=httpx.AsyncClient(transport=cc.transport),
+    )
+
+    # Read path — declare deps so entries can be invalidated later
+    with cc.request_context(deps=[Dep("table:products")]):
+        resp = await oai.chat.completions.create(model="gpt-4o", messages=[...])
+
+    # Write path — bypass cache, then invalidate stale deps
+    with cc.request_context(bypass=True):
+        resp = await oai.chat.completions.create(model="gpt-4o", messages=[...])
+    await cc.invalidate("table:products")
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator, Literal
+
+import httpx
+
+from cachecore._context import _RequestContext, _ctx
+from cachecore._transport import (
+    CacheCoreTransport,
+    _HDR_AGE,
+    _HDR_CACHE,
+    _HDR_SIMILARITY,
+)
+from cachecore.errors import (
+    CacheCoreAuthError,
+    CacheCoreError,
+    CacheCoreRateLimitError,
+)
+
+__all__ = [
+    "CacheCoreClient",
+    "CacheCoreTransport",
+    "CacheStatus",
+    "Dep",
+    "DepDeclaration",
+    "InvalidateResult",
+    "CacheCoreError",
+    "CacheCoreAuthError",
+    "CacheCoreRateLimitError",
+]
+
+logger = logging.getLogger("cachecore")
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Data classes
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+class DepDeclaration:
+    """
+    A dependency declaration to attach to a cached entry.
+
+    Parameters
+    ----------
+    dep_id:
+        Arbitrary string key, e.g. ``"table:products"``, ``"doc:policy-42"``.
+    hash:
+        The expected hash of this dependency at time of caching.  When the
+        dep is later invalidated with a *different* hash, all entries that
+        declared this dep_id + hash are evicted.
+
+        For simple use cases (invalidate everything with this dep_id),
+        leave as ``"v1"`` — any stable value works.  What matters is that
+        ``invalidate()`` changes the hash.
+
+    Examples
+    --------
+    ::
+
+        # Simple — just a dep ID
+        Dep("table:products")
+
+        # Explicit hash for multi-version tracking
+        Dep("table:products", hash="abc123")
+    """
+
+    __slots__ = ("dep_id", "expected_hash")
+
+    def __init__(self, dep_id: str, hash: str = "v1") -> None:
+        self.dep_id = dep_id
+        self.expected_hash = hash
+
+    def __repr__(self) -> str:
+        if self.expected_hash == "v1":
+            return f"Dep({self.dep_id!r})"
+        return f"Dep({self.dep_id!r}, hash={self.expected_hash!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, DepDeclaration):
+            return NotImplemented
+        return self.dep_id == other.dep_id and self.expected_hash == other.expected_hash
+
+    def __hash__(self) -> int:
+        return hash((self.dep_id, self.expected_hash))
+
+
+# Convenience alias — the name users will actually type
+Dep = DepDeclaration
+
+
+@dataclass(frozen=True, slots=True)
+class CacheStatus:
+    """
+    Parsed from ``X-Cache``, ``X-Cache-Similarity``, ``X-Cache-Age``
+    response headers.
+    """
+
+    status: Literal["HIT_L1", "HIT_L1_STALE", "HIT_L2", "MISS", "BYPASS", "UNKNOWN"]
+    similarity: float  # 0.0 – 1.0
+    age_seconds: int  # 0 for MISS / BYPASS
+
+    @classmethod
+    def from_headers(cls, headers: httpx.Headers) -> CacheStatus:
+        raw_status = headers.get(_HDR_CACHE, "UNKNOWN")
+        status: Literal[
+            "HIT_L1", "HIT_L1_STALE", "HIT_L2", "MISS", "BYPASS", "UNKNOWN"
+        ]
+        if raw_status in ("HIT_L1", "HIT_L1_STALE", "HIT_L2", "MISS", "BYPASS"):
+            status = raw_status  # type: ignore[assignment]
+        else:
+            status = "UNKNOWN"
+
+        try:
+            similarity = float(headers.get(_HDR_SIMILARITY, "0.0"))
+        except ValueError:
+            similarity = 0.0
+
+        try:
+            age = int(headers.get(_HDR_AGE, "0"))
+        except ValueError:
+            age = 0
+
+        return cls(status=status, similarity=similarity, age_seconds=age)
+
+
+@dataclass(frozen=True, slots=True)
+class InvalidateResult:
+    """Result of a single invalidation call."""
+
+    dep_id: str
+    ok: bool
+    error: str | None = None
+
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Client
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+class CacheCoreClient:
+    """
+    Connection-level object.  Constructed once per tenant.
+
+    Provides:
+
+    - An httpx async transport to inject into any OpenAI / Anthropic SDK.
+    - A context manager for per-request dep declarations and bypass.
+    - Invalidation helpers.
+
+    The client is **not** a replacement for the LLM SDK.  It handles
+    CacheCore-specific concerns only.
+
+    Parameters
+    ----------
+    gateway_url:
+        CacheCore proxy base URL, e.g. ``"http://localhost:8080"``.
+        No trailing slash.
+    tenant_jwt:
+        HS256/RS256 JWT for this tenant.
+    timeout:
+        HTTP timeout in seconds for management calls (invalidate).
+    debug:
+        If True, log cache status for every proxied request.
+    """
+
+    __slots__ = ("_gateway_url", "_jwt", "_timeout", "_debug", "_transport", "_http")
+
+    def __init__(
+        self,
+        gateway_url: str,
+        tenant_jwt: str,
+        *,
+        timeout: float = 30.0,
+        debug: bool = False,
+    ) -> None:
+        self._gateway_url = gateway_url.rstrip("/")
+        self._jwt = tenant_jwt
+        self._timeout = timeout
+        self._debug = debug
+        self._transport = CacheCoreTransport(jwt=tenant_jwt, debug=debug)
+
+        # Separate httpx client for management calls (invalidate).
+        # Not routed through the CacheCore transport — these go direct.
+        self._http = httpx.AsyncClient(
+            base_url=self._gateway_url,
+            timeout=httpx.Timeout(timeout),
+        )
+
+    # ── Transport ───────────────────────────────────────────────────────
+
+    @property
+    def transport(self) -> CacheCoreTransport:
+        """
+        The httpx async transport to pass to your SDK's http_client.
+
+        Example::
+
+            http = httpx.AsyncClient(transport=client.transport)
+            oai  = AsyncOpenAI(..., http_client=http)
+        """
+        return self._transport
+
+    # ── Per-request context ─────────────────────────────────────────────
+
+    @contextmanager
+    def request_context(
+        self,
+        deps: list[DepDeclaration] | None = None,
+        bypass: bool = False,
+    ) -> Iterator[None]:
+        """
+        Set per-request cache headers for the duration of the ``with`` block.
+
+        Uses a ``ContextVar`` so concurrent asyncio Tasks never interfere.
+
+        Parameters
+        ----------
+        deps:
+            Dependency declarations to tag this cache entry with.
+            Pass ``[Dep("table:products")]`` etc.
+        bypass:
+            If True, omits ``X-CacheCore-Token`` so the gateway skips
+            caching.  Use for write operations whose LLM response should
+            not be cached.
+        """
+        token = _ctx.set(_RequestContext(deps=deps or [], bypass=bypass))
+        try:
+            yield
+        finally:
+            _ctx.reset(token)
+
+    # ── Invalidation ────────────────────────────────────────────────────
+
+    async def invalidate(
+        self,
+        dep_id: str,
+        new_hash: str | None = None,
+    ) -> InvalidateResult:
+        """
+        Invalidate all cache entries that declared the given dependency.
+
+        Parameters
+        ----------
+        dep_id:
+            The dependency key to invalidate, e.g. ``"table:products"``.
+        new_hash:
+            The new hash to store for this dep.  If None, a random UUID is
+            generated — this guarantees all existing entries are stale.
+        """
+        if new_hash is None:
+            new_hash = uuid.uuid4().hex
+
+        try:
+            resp = await self._http.post(
+                "/v1/invalidate",
+                json={"dep_id": dep_id, "new_hash": new_hash},
+            )
+            _raise_for_status(resp)
+            return InvalidateResult(dep_id=dep_id, ok=True)
+        except CacheCoreError as exc:
+            return InvalidateResult(dep_id=dep_id, ok=False, error=str(exc))
+        except httpx.HTTPError as exc:
+            return InvalidateResult(dep_id=dep_id, ok=False, error=str(exc))
+
+    async def invalidate_many(
+        self,
+        dep_ids: list[str],
+        new_hash: str | None = None,
+    ) -> list[InvalidateResult]:
+        """
+        Invalidate multiple deps concurrently.
+
+        Each dep gets the same ``new_hash`` (or individual UUIDs if None).
+        """
+        tasks = [
+            self.invalidate(dep_id, new_hash=new_hash)
+            for dep_id in dep_ids
+        ]
+        return list(await asyncio.gather(*tasks))
+
+    # ── Lifecycle ───────────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP clients."""
+        await self._http.aclose()
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> CacheCoreClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    """Map gateway HTTP errors to typed exceptions."""
+    if resp.status_code < 400:
+        return
+
+    if resp.status_code in (401, 403):
+        raise CacheCoreAuthError(
+            f"CacheCore auth error {resp.status_code}: {resp.text}"
+        )
+
+    if resp.status_code == 429:
+        retry_after: float | None = None
+        raw = resp.headers.get("Retry-After")
+        if raw is not None:
+            try:
+                retry_after = float(raw)
+            except ValueError:
+                pass
+        raise CacheCoreRateLimitError(
+            f"CacheCore rate limit (429): {resp.text}",
+            retry_after=retry_after,
+        )
+
+    if resp.status_code >= 400:
+        raise CacheCoreError(
+            f"CacheCore error {resp.status_code}: {resp.text}"
+        )

cachecore/_context.py

@@ -0,0 +1,42 @@
+"""
+Internal context-variable plumbing for per-request cache headers.
+
+ContextVar is safe in asyncio: each Task gets its own snapshot,
+so concurrent LLM calls from different Tasks never interfere.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cachecore import DepDeclaration
+
+
+@dataclass(slots=True)
+class _RequestContext:
+    deps: list[DepDeclaration] = field(default_factory=list)
+    bypass: bool = False
+
+
+_ctx: ContextVar[_RequestContext | None] = ContextVar(
+    "cachecore_request_ctx", default=None
+)
+
+
+def _encode_deps(deps: list[DepDeclaration]) -> str:
+    """
+    Encode a list of DepDeclaration into the X-CacheCore-Deps header value.
+
+    Format: base64url (no padding) of JSON array:
+        [{"dep_id": "...", "expected_hash": "..."}]
+
+    This is the canonical encoding the gateway expects (manifest.rs:37-51).
+    """
+    payload = [{"dep_id": d.dep_id, "expected_hash": d.expected_hash} for d in deps]
+    raw = json.dumps(payload, separators=(",", ":")).encode()
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

cachecore/_transport.py

@@ -0,0 +1,99 @@
+"""
+CacheCore httpx async transport.
+
+Sits between the LLM SDK and the network.  On every outgoing request it:
+  1. Injects  X-CacheCore-Token  (unless bypass is active).
+  2. Injects  X-CacheCore-Deps   (base64url-JSON, if deps declared).
+  3. Captures X-Cache / X-Cache-Similarity / X-Cache-Age from the response.
+
+Why a transport and not default_headers?
+The OpenAI Python SDK constructs each httpx.Request internally and its
+header-merging logic can drop or overwrite client-level default_headers.
+Injecting at the transport layer — after Request construction, before the
+TCP write — is the only guaranteed injection point.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import httpx
+
+from cachecore._context import _ctx, _encode_deps
+
+if TYPE_CHECKING:
+    from cachecore import CacheStatus
+
+logger = logging.getLogger("cachecore")
+
+# ── Header constants ────────────────────────────────────────────────────
+# These MUST match proxy.rs exactly.  Bug 1 in the design doc: both test
+# agents used "X-Cache-Deps" — the gateway reads "X-CacheCore-Deps".
+# Baking the correct names here makes the bug impossible by construction.
+_HDR_TOKEN = "X-CacheCore-Token"
+_HDR_DEPS = "X-CacheCore-Deps"
+_HDR_CACHE = "X-Cache"
+_HDR_SIMILARITY = "X-Cache-Similarity"
+_HDR_AGE = "X-Cache-Age"
+
+
+class CacheCoreTransport(httpx.AsyncBaseTransport):
+    """
+    Drop-in httpx async transport that handles all CacheCore header plumbing.
+
+    Usage::
+
+        transport = CacheCoreTransport(jwt="ey...")
+        http = httpx.AsyncClient(transport=transport)
+        oai  = AsyncOpenAI(base_url="http://localhost:8080/v1",
+                           api_key="dummy", http_client=http)
+    """
+
+    __slots__ = ("_jwt", "_wrapped", "_debug")
+
+    def __init__(
+        self,
+        jwt: str,
+        *,
+        wrapped: httpx.AsyncBaseTransport | None = None,
+        debug: bool = False,
+    ) -> None:
+        self._jwt = jwt
+        self._wrapped = wrapped or httpx.AsyncHTTPTransport()
+        self._debug = debug
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        ctx = _ctx.get()
+
+        # ── Inject token (unless bypass) ────────────────────────────────
+        # Bypass = omit the token entirely.  The gateway treats a missing
+        # token as bypass mode (proxy.rs:55-68).  This fixes Bug 3: the
+        # old agents sent "X-Cache-Bypass: true" which is a no-op.
+        bypass = ctx is not None and ctx.bypass
+        if not bypass:
+            request.headers[_HDR_TOKEN] = self._jwt
+
+        # ── Inject deps ─────────────────────────────────────────────────
+        # This fixes Bug 1 (wrong header name) and Bug 2 (wrong encoding)
+        # by construction: correct header, correct base64url-JSON format.
+        if ctx and ctx.deps:
+            request.headers[_HDR_DEPS] = _encode_deps(ctx.deps)
+
+        # ── Forward ─────────────────────────────────────────────────────
+        response = await self._wrapped.handle_async_request(request)
+
+        # ── Debug logging ───────────────────────────────────────────────
+        if self._debug:
+            cache = response.headers.get(_HDR_CACHE, "?")
+            sim = response.headers.get(_HDR_SIMILARITY, "?")
+            age = response.headers.get(_HDR_AGE, "?")
+            logger.debug(
+                "CacheCore  %s  sim=%s  age=%ss  %s %s",
+                cache, sim, age, request.method, request.url,
+            )
+
+        return response
+
+    async def aclose(self) -> None:
+        await self._wrapped.aclose()

cachecore/errors.py

@@ -0,0 +1,24 @@
+"""CacheCore client exceptions."""
+
+from __future__ import annotations
+
+
+class CacheCoreError(Exception):
+    """Base exception for all CacheCore client errors."""
+
+
+class CacheCoreAuthError(CacheCoreError):
+    """Raised on 401/403 from the gateway or admin endpoints."""
+
+
+class CacheCoreRateLimitError(CacheCoreError):
+    """
+    Raised on 429 Too Many Requests from the gateway.
+
+    Attributes:
+        retry_after:  Value of Retry-After header if present (seconds), else None.
+    """
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after

cachecore_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: cachecore-python
+Version: 0.1.0
+Summary: Python client for CacheCore — semantic cache gateway for LLM agent workloads
+Project-URL: Homepage, https://cachecore.it
+Project-URL: Repository, https://github.com/cachecore/cachecore-python
+Author: Fabrizio
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cache,llm,openai,proxy,semantic-cache
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Description-Content-Type: text/markdown
+
+# cachecore
+
+Python client for [CacheCore](https://cachecore.it) — the LLM API caching proxy that reduces cost and latency for AI agent workloads.
+
+CacheCore sits transparently between your application and LLM providers (OpenAI, Anthropic via OpenAI-compat, etc.) and caches responses at two levels: L1 exact-match and L2 semantic similarity. This client handles the CacheCore-specific plumbing — header injection, dependency encoding, invalidation — without replacing your LLM SDK.
+
+## Install
+
+```bash
+pip install cachecore-python
+```
+
+```python
+import cachecore  # the import name is 'cachecore'
+```
+
+## Quick start
+
+### Rung 1 — zero code changes: swap `base_url`
+
+Point your existing SDK at CacheCore and get L1 exact-match caching immediately.
+No `import cachecore` required.
+
+```python
+from openai import AsyncOpenAI
+
+oai = AsyncOpenAI(
+    api_key="your-openai-key",
+    base_url="https://gateway.cachecore.it/v1",  # ← only change
+)
+
+# Identical requests are now served from cache.
+resp = await oai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "What is 2+2?"}],
+)
+```
+
+### Rung 2 — tenant isolation (3 lines)
+
+Add `CacheCoreClient` to unlock tenant-scoped namespaces, L2 semantic caching, and per-tenant
+metrics. Three extra lines wired into the SDK's `http_client`.
+
+```python
+from cachecore import CacheCoreClient
+import httpx
+from openai import AsyncOpenAI
+
+cc = CacheCoreClient(
+    gateway_url="https://gateway.cachecore.it",
+    tenant_jwt="ey...",  # your tenant JWT from the CacheCore dashboard
+)
+
+oai = AsyncOpenAI(
+    api_key="ignored",  # gateway injects its own upstream key
+    base_url="https://gateway.cachecore.it/v1",
+    http_client=httpx.AsyncClient(transport=cc.transport),
+)
+
+# Requests now carry your tenant identity.
+# Semantically similar prompts hit L2 cache.
+resp = await oai.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Explain photosynthesis"}],
+)
+```
+
+### Rung 3 — dep invalidation
+
+Declare which data a cached response depends on. When that data changes, invalidate the dep
+and all stale entries are evicted automatically.
+
+```python
+from cachecore import CacheCoreClient, Dep
+import httpx
+from openai import AsyncOpenAI
+
+cc = CacheCoreClient(
+    gateway_url="https://gateway.cachecore.it",
+    tenant_jwt="ey...",
+)
+
+oai = AsyncOpenAI(
+    api_key="ignored",
+    base_url="https://gateway.cachecore.it/v1",
+    http_client=httpx.AsyncClient(transport=cc.transport),
+)
+
+# Read path — declare what data this response depends on
+with cc.request_context(deps=[Dep("table:products"), Dep("table:orders")]):
+    resp = await oai.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "List all products under $50"}],
+    )
+
+# Write path — bypass cache for the LLM call, then invalidate
+with cc.request_context(bypass=True):
+    resp = await oai.chat.completions.create(
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Confirm order created."}],
+    )
+await cc.invalidate("table:products")
+
+# Invalidate multiple deps at once
+await cc.invalidate_many(["table:orders", "table:products"])
+```
+
+## Works with LangChain / LangGraph
+
+The transport works with any SDK that accepts an `httpx.AsyncClient`:
+
+```python
+from langchain_openai import ChatOpenAI
+import httpx
+from cachecore import CacheCoreClient, Dep
+
+cc = CacheCoreClient(gateway_url="https://gateway.cachecore.it", tenant_jwt="ey...")
+
+llm = ChatOpenAI(
+    model="gpt-4o",
+    api_key="ignored",
+    base_url="https://gateway.cachecore.it/v1",
+    http_async_client=httpx.AsyncClient(transport=cc.transport),
+)
+
+# Use request_context() around any ainvoke / astream call
+with cc.request_context(deps=[Dep("doc:policy-42")]):
+    result = await llm.ainvoke("Summarise the compliance policy")
+```
+
+## API reference
+
+### `CacheCoreClient`
+
+```python
+CacheCoreClient(
+    gateway_url: str,       # "https://gateway.cachecore.it"
+    tenant_jwt: str,        # tenant HS256/RS256 JWT
+    timeout: float = 30.0,  # for invalidation calls
+    debug: bool = False,    # log cache status per request
+)
+```
+
+| Property / Method | Description |
+|---|---|
+| `.transport` | `httpx.AsyncBaseTransport` — pass to `httpx.AsyncClient(transport=...)` |
+| `.request_context(deps, bypass)` | Context manager — sets per-request deps / bypass |
+| `await .invalidate(dep_id)` | Evict all entries tagged with this dep |
+| `await .invalidate_many(dep_ids)` | Invalidate multiple deps concurrently |
+| `await .aclose()` | Close HTTP clients. Also works as `async with CacheCoreClient(...):` |
+
+### `Dep` / `DepDeclaration`
+
+```python
+Dep("table:products")                  # simple — hash defaults to "v1"
+Dep("table:products", hash="abc123")   # explicit hash for versioned deps
+```
+
+### `CacheStatus`
+
+Parsed from response headers after a proxied request:
+
+```python
+from cachecore import CacheStatus
+
+status = CacheStatus.from_headers(response.headers)
+# status.status      → "HIT_L1" | "HIT_L1_STALE" | "HIT_L2" | "MISS" | "BYPASS" | "UNKNOWN"
+# status.similarity  → float 0.0–1.0  (non-zero on L2 hits)
+# status.age_seconds → int
+```
+
+### Exceptions
+
+| Exception | When |
+|---|---|
+| `CacheCoreError` | Base class for all CacheCore errors |
+| `CacheCoreAuthError` | 401 / 403 from the gateway |
+| `CacheCoreRateLimitError` | 429 — check `.retry_after` attribute (seconds, or `None`) |
+
+## How it works
+
+The client injects headers at the httpx transport layer — below the LLM SDK, above the network. Your SDK continues to work exactly as before:
+
+```
+Your code  →  openai SDK  →  httpx  →  [CacheCoreTransport]  →  CacheCore proxy  →  OpenAI API
+                                              ↑
+                                  injects X-CacheCore-Token
+                                  injects X-CacheCore-Deps
+```
+
+## Requirements
+
+- Python 3.10+
+- `httpx >= 0.25.0`
+
+## Links
+
+- Website: [cachecore.it](https://cachecore.it)
+- Source: [github.com/cachecore/cachecore-python](https://github.com/cachecore/cachecore-python)
+
+## License
+
+MIT — see [LICENSE](LICENSE)

cachecore_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+cachecore/__init__.py,sha256=mMEIWjAxEAPty9j-VbY7rWZsWmM1DhUW8YuwRcVdJ0A,11915
+cachecore/_context.py,sha256=JB5kbnJFViX6MEOTjFvW-VNeRhLi-uisf2i8ufrxVsM,1205
+cachecore/_transport.py,sha256=vfCLEtH3W-A0eW0rh17KFIu28hUwEVoQwV5hoVyC1bk,4049
+cachecore/errors.py,sha256=Jy4JXmINWgG7ItgPb7o4pI5tW2O8N5xmSFe47P8XdoU,646
+cachecore/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cachecore_python-0.1.0.dist-info/METADATA,sha256=6O5qCrZEirdoOZ7T5XKz8NmEIEqKpi7Q6bvGCrhRnpA,7230
+cachecore_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cachecore_python-0.1.0.dist-info/licenses/LICENSE,sha256=lQU0_mqn8xkIyItjElpsMJyRpESqDBaJlCpy1fmYzW0,1065
+cachecore_python-0.1.0.dist-info/RECORD,,

cachecore_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cachecore_python-0.1.0.dist-info/licenses/LICENSE

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