openai-sqlite-cache 0.0.1__py3-none-any.whl

cached_openai/__init__.py

@@ -0,0 +1,175 @@
+"""Drop-in OpenAI Python SDK with a persistent local SQLite cache.
+
+Use ``import cached_openai as openai`` and keep the rest of an existing OpenAI
+SDK integration unchanged.
+"""
+
+from __future__ import annotations
+
+import sys
+import types as _stdlib_types
+from pathlib import Path
+from typing import Any, Optional
+
+import openai as _openai
+from openai import *  # noqa: F403
+
+from . import _client as _cached_client
+from ._cache import SQLiteCache
+from ._http import CachingSyncClient, wrap_sync_client
+from ._module_alias import install_module_alias
+from ._settings import _UNSET, configure_settings, get_settings
+from ._version import PACKAGE_VERSION
+
+OpenAI = _cached_client.OpenAI
+AsyncOpenAI = _cached_client.AsyncOpenAI
+Client = _cached_client.Client
+AsyncClient = _cached_client.AsyncClient
+AzureOpenAI = _cached_client.AzureOpenAI
+AsyncAzureOpenAI = _cached_client.AsyncAzureOpenAI
+CachedOpenAI = _cached_client.CachedOpenAI
+AsyncCachedOpenAI = _cached_client.AsyncCachedOpenAI
+
+__version__ = PACKAGE_VERSION
+openai_version = _openai.__version__
+
+_MODULE_CONFIG_NAMES = {
+    "api_key",
+    "organization",
+    "project",
+    "webhook_secret",
+    "base_url",
+    "timeout",
+    "max_retries",
+    "default_headers",
+    "default_query",
+    "http_client",
+    "api_type",
+    "api_version",
+    "azure_endpoint",
+    "azure_ad_token",
+    "azure_ad_token_provider",
+}
+
+_MODULE_RESOURCE_NAMES = {
+    "audio",
+    "batches",
+    "beta",
+    "chat",
+    "completions",
+    "containers",
+    "conversations",
+    "embeddings",
+    "evals",
+    "files",
+    "fine_tuning",
+    "images",
+    "models",
+    "moderations",
+    "realtime",
+    "responses",
+    "skills",
+    "uploads",
+    "vector_stores",
+    "videos",
+    "webhooks",
+}
+
+
+def _reset_upstream_module_client() -> None:
+    reset = getattr(_openai, "_reset_client", None)
+    if reset is not None:
+        reset()
+
+
+def _prepare_module_client() -> None:
+    settings = get_settings()
+    if not settings.enabled:
+        return
+    current = getattr(_openai, "http_client", None)
+    if current is None:
+        current = _openai.DefaultHttpxClient()
+    wrapped = wrap_sync_client(current, settings)
+    if wrapped is not getattr(_openai, "http_client", None):
+        _openai.http_client = wrapped
+        _reset_upstream_module_client()
+
+
+def configure_cache(
+    *,
+    path: Any = _UNSET,
+    ttl_seconds: Any = _UNSET,
+    enabled: Any = _UNSET,
+) -> dict:
+    """Configure defaults used by new clients and the module-level client."""
+
+    settings = configure_settings(path=path, ttl_seconds=ttl_seconds, enabled=enabled)
+    current = getattr(_openai, "http_client", None)
+    if isinstance(current, CachingSyncClient):
+        _openai.http_client = current._cached_openai_inner
+    _reset_upstream_module_client()
+    return {
+        "path": str(settings.path.expanduser().resolve()),
+        "ttl_seconds": settings.ttl_seconds,
+        "enabled": settings.enabled,
+    }
+
+
+def clear_cache(path: Optional[Any] = None) -> int:
+    """Delete all cached response rows and return the number removed."""
+
+    cache_path = get_settings().path if path is None else Path(path).expanduser()
+    return SQLiteCache(cache_path).clear()
+
+
+def cache_info(path: Optional[Any] = None) -> dict:
+    """Return cache path, row count, stored bytes, and cumulative hit count."""
+
+    cache_path = get_settings().path if path is None else Path(path).expanduser()
+    return SQLiteCache(cache_path).stats()
+
+
+def __getattr__(name: str) -> Any:
+    if name in _MODULE_RESOURCE_NAMES:
+        _prepare_module_client()
+    return getattr(_openai, name)
+
+
+def __dir__() -> list:
+    return sorted(set(globals()) | set(dir(_openai)))
+
+
+class _CachedOpenAIModule(_stdlib_types.ModuleType):
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name in _MODULE_CONFIG_NAMES:
+            if name == "http_client" and isinstance(value, CachingSyncClient):
+                value = value._cached_openai_inner
+            setattr(_openai, name, value)
+            _reset_upstream_module_client()
+            return
+        super().__setattr__(name, value)
+
+
+sys.modules[__name__].__class__ = _CachedOpenAIModule
+
+# Preserve class identity for imports such as
+# ``from cached_openai.types.chat import ChatCompletion``.
+types = install_module_alias(__name__ + ".types", "openai.types")
+
+__all__ = sorted(
+    set(getattr(_openai, "__all__", []))
+    | {
+        "AsyncAzureOpenAI",
+        "AsyncCachedOpenAI",
+        "AsyncClient",
+        "AsyncOpenAI",
+        "AzureOpenAI",
+        "CachedOpenAI",
+        "Client",
+        "OpenAI",
+        "cache_info",
+        "clear_cache",
+        "configure_cache",
+        "openai_version",
+    }
+)

cached_openai/_cache.py

@@ -0,0 +1,145 @@
+"""A small, process-safe SQLite store for HTTP response payloads."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import time
+from contextlib import closing
+from dataclasses import dataclass
+from pathlib import Path
+from threading import RLock
+from typing import List, Optional, Sequence, Tuple
+
+HeaderList = List[Tuple[str, str]]
+
+
+@dataclass(frozen=True)
+class CachedResponse:
+    status_code: int
+    headers: HeaderList
+    body: bytes
+
+
+class SQLiteCache:
+    """Persistent cache whose rows contain responses, never request bodies."""
+
+    def __init__(self, path: Path):
+        self.path = path.expanduser().resolve()
+        self._lock = RLock()
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(str(self.path), timeout=10.0)
+        connection.execute("PRAGMA busy_timeout = 10000")
+        return connection
+
+    def _initialize(self) -> None:
+        self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        with self._lock, closing(self._connect()) as connection, connection:
+            connection.execute("PRAGMA journal_mode = WAL")
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS responses (
+                    cache_key TEXT PRIMARY KEY,
+                    status_code INTEGER NOT NULL,
+                    headers_json TEXT NOT NULL,
+                    body BLOB NOT NULL,
+                    created_at REAL NOT NULL,
+                    last_accessed_at REAL NOT NULL,
+                    hit_count INTEGER NOT NULL DEFAULT 0
+                )
+                """
+            )
+        try:
+            os.chmod(self.path, 0o600)
+        except OSError:
+            pass
+
+    def get(
+        self, cache_key: str, ttl_seconds: Optional[float]
+    ) -> Optional[CachedResponse]:
+        now = time.time()
+        with self._lock, closing(self._connect()) as connection, connection:
+            row = connection.execute(
+                """
+                SELECT status_code, headers_json, body, created_at
+                FROM responses
+                WHERE cache_key = ?
+                """,
+                (cache_key,),
+            ).fetchone()
+            if row is None:
+                return None
+            if ttl_seconds is not None and now - float(row[3]) >= ttl_seconds:
+                connection.execute(
+                    "DELETE FROM responses WHERE cache_key = ?", (cache_key,)
+                )
+                return None
+            connection.execute(
+                """
+                UPDATE responses
+                SET last_accessed_at = ?, hit_count = hit_count + 1
+                WHERE cache_key = ?
+                """,
+                (now, cache_key),
+            )
+        raw_headers = json.loads(str(row[1]))
+        headers = [(str(name), str(value)) for name, value in raw_headers]
+        return CachedResponse(
+            status_code=int(row[0]), headers=headers, body=bytes(row[2])
+        )
+
+    def put(
+        self,
+        cache_key: str,
+        status_code: int,
+        headers: Sequence[Tuple[str, str]],
+        body: bytes,
+    ) -> None:
+        now = time.time()
+        headers_json = json.dumps(
+            list(headers), ensure_ascii=False, separators=(",", ":")
+        )
+        with self._lock, closing(self._connect()) as connection, connection:
+            connection.execute(
+                """
+                INSERT INTO responses (
+                    cache_key, status_code, headers_json, body,
+                    created_at, last_accessed_at, hit_count
+                ) VALUES (?, ?, ?, ?, ?, ?, 0)
+                ON CONFLICT(cache_key) DO UPDATE SET
+                    status_code = excluded.status_code,
+                    headers_json = excluded.headers_json,
+                    body = excluded.body,
+                    created_at = excluded.created_at,
+                    last_accessed_at = excluded.last_accessed_at,
+                    hit_count = 0
+                """,
+                (cache_key, status_code, headers_json, sqlite3.Binary(body), now, now),
+            )
+
+    def clear(self) -> int:
+        with self._lock, closing(self._connect()) as connection, connection:
+            count = int(
+                connection.execute("SELECT COUNT(*) FROM responses").fetchone()[0]
+            )
+            connection.execute("DELETE FROM responses")
+            return count
+
+    def stats(self) -> dict:
+        with self._lock, closing(self._connect()) as connection, connection:
+            row = connection.execute(
+                """
+                SELECT COUNT(*), COALESCE(SUM(LENGTH(body)), 0),
+                       COALESCE(SUM(hit_count), 0)
+                FROM responses
+                """
+            ).fetchone()
+        return {
+            "path": str(self.path),
+            "entries": int(row[0]),
+            "response_bytes": int(row[1]),
+            "hits": int(row[2]),
+        }

cached_openai/_client.py

@@ -0,0 +1,166 @@
+"""Drop-in cached variants of OpenAI's explicit clients."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import openai as _openai
+
+from ._http import (
+    CachingAsyncClient,
+    CachingSyncClient,
+    wrap_async_client,
+    wrap_sync_client,
+)
+from ._settings import _UNSET, CacheSettings, settings_for_client
+
+
+def _settings_from_existing(
+    existing: CacheSettings,
+    cache_path: Any,
+    cache_ttl: Any,
+    cache_enabled: Any,
+) -> CacheSettings:
+    path = (
+        existing.path
+        if cache_path is _UNSET or cache_path is None
+        else Path(cache_path).expanduser()
+    )
+    ttl = existing.ttl_seconds if cache_ttl is _UNSET else cache_ttl
+    enabled = (
+        existing.enabled
+        if cache_enabled is _UNSET or cache_enabled is None
+        else cache_enabled
+    )
+    if ttl is not None and float(ttl) < 0:
+        raise ValueError("cache_ttl must be zero or greater")
+    return CacheSettings(
+        path=path,
+        ttl_seconds=None if ttl is None else float(ttl),
+        enabled=bool(enabled),
+    )
+
+
+def _sync_kwargs(
+    kwargs: dict, cache_path: Any, cache_ttl: Any, cache_enabled: Any
+) -> dict:
+    original = kwargs.get("http_client")
+    if isinstance(original, CachingSyncClient):
+        settings = _settings_from_existing(
+            original._cached_openai_settings,
+            cache_path,
+            cache_ttl,
+            cache_enabled,
+        )
+    else:
+        settings = settings_for_client(
+            cache_path=cache_path,
+            cache_ttl=cache_ttl,
+            cache_enabled=cache_enabled,
+        )
+    if not settings.enabled:
+        if isinstance(original, CachingSyncClient):
+            kwargs["http_client"] = original._cached_openai_inner
+        return kwargs
+    if original is None:
+        original = _openai.DefaultHttpxClient()
+    kwargs["http_client"] = wrap_sync_client(original, settings)
+    return kwargs
+
+
+def _async_kwargs(
+    kwargs: dict, cache_path: Any, cache_ttl: Any, cache_enabled: Any
+) -> dict:
+    original = kwargs.get("http_client")
+    if isinstance(original, CachingAsyncClient):
+        settings = _settings_from_existing(
+            original._cached_openai_settings,
+            cache_path,
+            cache_ttl,
+            cache_enabled,
+        )
+    else:
+        settings = settings_for_client(
+            cache_path=cache_path,
+            cache_ttl=cache_ttl,
+            cache_enabled=cache_enabled,
+        )
+    if not settings.enabled:
+        if isinstance(original, CachingAsyncClient):
+            kwargs["http_client"] = original._cached_openai_inner
+        return kwargs
+    if original is None:
+        original = _openai.DefaultAsyncHttpxClient()
+    kwargs["http_client"] = wrap_async_client(original, settings)
+    return kwargs
+
+
+class OpenAI(_openai.OpenAI):
+    """The official synchronous OpenAI client with an SQLite cache."""
+
+    def __init__(
+        self,
+        *args: Any,
+        cache_path: Any = _UNSET,
+        cache_ttl: Any = _UNSET,
+        cache_enabled: Any = _UNSET,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            *args, **_sync_kwargs(kwargs, cache_path, cache_ttl, cache_enabled)
+        )
+
+
+class AsyncOpenAI(_openai.AsyncOpenAI):
+    """The official asynchronous OpenAI client with an SQLite cache."""
+
+    def __init__(
+        self,
+        *args: Any,
+        cache_path: Any = _UNSET,
+        cache_ttl: Any = _UNSET,
+        cache_enabled: Any = _UNSET,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            *args, **_async_kwargs(kwargs, cache_path, cache_ttl, cache_enabled)
+        )
+
+
+class AzureOpenAI(_openai.AzureOpenAI):
+    """The official synchronous Azure OpenAI client with an SQLite cache."""
+
+    def __init__(
+        self,
+        *args: Any,
+        cache_path: Any = _UNSET,
+        cache_ttl: Any = _UNSET,
+        cache_enabled: Any = _UNSET,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            *args, **_sync_kwargs(kwargs, cache_path, cache_ttl, cache_enabled)
+        )
+
+
+class AsyncAzureOpenAI(_openai.AsyncAzureOpenAI):
+    """The official asynchronous Azure OpenAI client with an SQLite cache."""
+
+    def __init__(
+        self,
+        *args: Any,
+        cache_path: Any = _UNSET,
+        cache_ttl: Any = _UNSET,
+        cache_enabled: Any = _UNSET,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            *args, **_async_kwargs(kwargs, cache_path, cache_ttl, cache_enabled)
+        )
+
+
+Client = OpenAI
+AsyncClient = AsyncOpenAI
+CachedOpenAI = OpenAI
+AsyncCachedOpenAI = AsyncOpenAI

cached_openai/_fingerprint.py

@@ -0,0 +1,186 @@
+"""Stable, privacy-conscious request fingerprints for cacheable OpenAI APIs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from email.parser import BytesParser
+from email.policy import default as email_policy
+from typing import Any, Dict, List, Mapping, Optional, Tuple
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+_CACHEABLE_SUFFIXES = (
+    "/responses",
+    "/responses/compact",
+    "/chat/completions",
+    "/completions",
+    "/embeddings",
+    "/moderations",
+    "/images/generations",
+    "/images/edits",
+    "/images/variations",
+    "/audio/speech",
+    "/audio/transcriptions",
+    "/audio/translations",
+    "/videos",
+)
+
+_CREDENTIAL_HEADERS = {
+    "authorization",
+    "api-key",
+    "cookie",
+    "x-api-key",
+}
+
+_IGNORED_HEADERS = {
+    "accept-encoding",
+    "connection",
+    "content-length",
+    "host",
+    "idempotency-key",
+    "traceparent",
+    "tracestate",
+    "transfer-encoding",
+    "user-agent",
+}
+
+
+def _canonical_json(value: Any) -> bytes:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    ).encode("utf-8")
+
+
+def _normalized_url(url: str) -> str:
+    parts = urlsplit(url)
+    hostname = (parts.hostname or "").lower()
+    port = parts.port
+    default_port = (parts.scheme.lower() == "https" and port == 443) or (
+        parts.scheme.lower() == "http" and port == 80
+    )
+    authority = hostname if port is None or default_port else f"{hostname}:{port}"
+    query = urlencode(
+        sorted(parse_qsl(parts.query, keep_blank_values=True)), doseq=True
+    )
+    return urlunsplit((parts.scheme.lower(), authority, parts.path, query, ""))
+
+
+def _is_cacheable_path(path: str) -> bool:
+    normalized = path.rstrip("/").lower()
+    return any(normalized.endswith(suffix) for suffix in _CACHEABLE_SUFFIXES)
+
+
+def _header_items(headers: Any) -> List[Tuple[str, str]]:
+    if hasattr(headers, "multi_items"):
+        return [(str(name), str(value)) for name, value in headers.multi_items()]
+    if hasattr(headers, "items"):
+        return [(str(name), str(value)) for name, value in headers.items()]
+    return [(str(name), str(value)) for name, value in headers]
+
+
+def _multipart_value(content_type: str, body: bytes) -> Tuple[Any, Optional[str]]:
+    message = BytesParser(policy=email_policy).parsebytes(
+        b"Content-Type: "
+        + content_type.encode("latin-1")
+        + b"\r\nMIME-Version: 1.0\r\n\r\n"
+        + body
+    )
+    parts: List[Dict[str, Any]] = []
+    model: Optional[str] = None
+    for part in message.iter_parts():
+        name = part.get_param("name", header="content-disposition") or ""
+        filename = part.get_filename()
+        payload = part.get_payload(decode=True) or b""
+        item: Dict[str, Any] = {
+            "name": name,
+            "filename": filename,
+            "content_type": part.get_content_type(),
+            "sha256": hashlib.sha256(payload).hexdigest(),
+        }
+        if filename is None:
+            charset = part.get_content_charset() or "utf-8"
+            try:
+                value = payload.decode(charset)
+            except (LookupError, UnicodeDecodeError):
+                value = payload.decode("utf-8", errors="replace")
+            item["value"] = value
+            if name == "model":
+                model = value
+        parts.append(item)
+    return {"kind": "multipart", "parts": parts}, model
+
+
+def request_fingerprint(
+    method: str, url: str, headers: Any, body: bytes
+) -> Optional[str]:
+    """Return a versioned SHA-256 key, or ``None`` for non-inference APIs."""
+
+    if method.upper() != "POST" or not _is_cacheable_path(urlsplit(url).path):
+        return None
+
+    items = _header_items(headers)
+    lowered: Dict[str, List[str]] = {}
+    for name, value in items:
+        lowered.setdefault(name.lower(), []).append(value)
+    content_type = (lowered.get("content-type") or [""])[0]
+    media_type = content_type.split(";", 1)[0].strip().lower()
+
+    model: Optional[str] = None
+    body_value: Any
+    if media_type == "application/json" or (
+        not media_type and body.lstrip().startswith((b"{", b"["))
+    ):
+        try:
+            body_value = json.loads(body.decode("utf-8"))
+            if isinstance(body_value, Mapping) and body_value.get("model") is not None:
+                model = str(body_value["model"])
+            body_value = {"kind": "json", "value": body_value}
+        except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+            body_value = {"kind": "bytes", "sha256": hashlib.sha256(body).hexdigest()}
+    elif media_type == "multipart/form-data":
+        try:
+            body_value, model = _multipart_value(content_type, body)
+        except Exception:
+            body_value = {"kind": "bytes", "sha256": hashlib.sha256(body).hexdigest()}
+    elif media_type == "application/x-www-form-urlencoded":
+        fields = sorted(parse_qsl(body.decode("utf-8"), keep_blank_values=True))
+        body_value = {"kind": "form", "fields": fields}
+        for name, value in fields:
+            if name == "model":
+                model = value
+                break
+    else:
+        body_value = {"kind": "bytes", "sha256": hashlib.sha256(body).hexdigest()}
+
+    scoped_headers = {}
+    for name, values in lowered.items():
+        if (
+            name in _CREDENTIAL_HEADERS
+            or name in _IGNORED_HEADERS
+            or name == "content-type"
+            or name.startswith("x-stainless-")
+        ):
+            continue
+        scoped_headers[name] = sorted(values)
+    scoped_headers["content-type"] = [media_type]
+    credential_material = "\0".join(
+        f"{name}:{value}"
+        for name in sorted(_CREDENTIAL_HEADERS)
+        for value in lowered.get(name, [])
+    )
+    credential_scope = hashlib.sha256(credential_material.encode("utf-8")).hexdigest()
+
+    material = {
+        "version": 1,
+        "method": method.upper(),
+        "url": _normalized_url(url),
+        "model": model or "<default>",
+        "headers": scoped_headers,
+        "credential_scope": credential_scope,
+        "body": body_value,
+    }
+    return "v1:" + hashlib.sha256(_canonical_json(material)).hexdigest()