openai-sqlite-cache 0.0.1__tar.gz

openai_sqlite_cache-0.0.1/LICENSE

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

openai_sqlite_cache-0.0.1/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: openai_sqlite_cache
+Version: 0.0.1
+Summary: An unofficial drop-in OpenAI Python SDK with a local SQLite response cache
+Author: openai_sqlite_cache contributors
+License-Expression: MIT
+Keywords: openai,cache,sqlite,llm,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai<3,>=1.66.2
+Dynamic: license-file
+
+# openai_sqlite_cache
+
+`openai_sqlite_cache` 是非官方的 OpenAI Python SDK 透明 SQLite 缓存层。同一个 API、同一个模型、完全相同的输入再次调用时，会直接返回本机缓存的响应，不再请求上游。
+
+PyPI 分发名是 `openai_sqlite_cache`（规范化名称为 `openai-sqlite-cache`）；为满足只替换 import 的用法，Python 导入名仍然是 `cached_openai`。
+
+## 安装
+
+在当前仓库中安装：
+
+```bash
+pip install ./openai_sqlite_cache
+```
+
+发布到你有权限的 Python 包索引后，安装形式为：
+
+```bash
+pip install openai_sqlite_cache
+```
+
+> 注意：本项目与公共 PyPI 上的 `cached-openai` 分发项目都提供 `cached_openai` 导入包，二者不能安全地安装在同一个 Python 环境中。请只安装其中一个。
+
+## 用法
+
+现有代码只需替换 import，并保留 `openai` 这个本地别名：
+
+```python
+# 原来：import openai
+import cached_openai as openai
+
+client = openai.OpenAI()
+response = client.responses.create(
+    model="gpt-5",
+    input="Explain SQLite in one sentence.",
+)
+print(response.output_text)
+```
+
+也可以直接使用包名：
+
+```python
+import cached_openai
+
+client = cached_openai.OpenAI()
+completion = client.chat.completions.create(
+    model="gpt-4.1-mini",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+以下官方 SDK 用法均保持不变：
+
+- `OpenAI`、`AsyncOpenAI`、`AzureOpenAI` 和 `AsyncAzureOpenAI`；
+- 模块级调用，如 `openai.chat.completions.create(...)`；
+- `with_options()`、`with_raw_response`、`with_streaming_response`；
+- 自定义 `base_url` 和自定义同步/异步 `http_client`；
+- 官方 SDK 的响应模型和异常类型。
+
+流式响应会在第一次被完整消费时写入缓存；如果流被提前关闭，则不会缓存不完整内容。Realtime/WebSocket 不经过普通 HTTP 请求，因此不会缓存。
+
+## 缓存规则
+
+缓存键使用 SHA-256 计算，包含：
+
+- HTTP 方法和规范化后的完整 API URL；
+- 请求体（JSON 会按键排序，multipart 会忽略随机 boundary 并对文件内容取 hash）；
+- 模型名；
+- organization、project、beta 等会影响语义的请求头；
+- API 凭据的不可逆作用域 hash，防止不同 API key 之间共享响应。
+
+请求原文和 API key 都不会写入数据库。数据库只保存 hash、成功响应体、必要响应头和命中统计。默认永久保留，只缓存 2xx 响应。
+
+为避免有副作用的操作被错误去重，目前只缓存这些推理/生成端点：Responses、Chat Completions、Completions、Embeddings、Moderations、Images、Audio 和 Videos。Files、Uploads、Batches、Fine-tuning、Vector Stores 等管理类 API 会原样请求上游。
+
+## 配置
+
+默认数据库位置：
+
+- macOS：`~/Library/Caches/openai-sqlite-cache/cache.sqlite3`
+- Linux：`$XDG_CACHE_HOME/openai-sqlite-cache/cache.sqlite3`，未设置时使用 `~/.cache/...`
+- Windows：`%LOCALAPPDATA%/openai-sqlite-cache/cache.sqlite3`
+
+环境变量：
+
+```bash
+export CACHED_OPENAI_CACHE_PATH=/path/to/cache.sqlite3
+export CACHED_OPENAI_TTL_SECONDS=86400
+export CACHED_OPENAI_DISABLE=0
+```
+
+也可以在创建客户端前配置：
+
+```python
+import cached_openai as openai
+
+openai.configure_cache(
+    path="./.cache/openai.sqlite3",
+    ttl_seconds=24 * 60 * 60,
+)
+client = openai.OpenAI()
+```
+
+单个客户端可以覆盖全局配置：
+
+```python
+client = openai.OpenAI(
+    cache_path="./project-cache.sqlite3",
+    cache_ttl=3600,
+    cache_enabled=True,
+)
+```
+
+维护接口：
+
+```python
+print(openai.cache_info())
+removed = openai.clear_cache()
+```
+
+缓存文件可能包含模型响应中的敏感内容，应像其他本地应用数据一样保护。包会尽量把目录和数据库权限分别设为 `0700` 和 `0600`。
+
+## 开发与测试
+
+```bash
+cd openai_sqlite_cache
+python -m unittest discover -s tests -v
+python -m pip wheel --no-deps . -w dist
+```

openai_sqlite_cache-0.0.1/README.md

@@ -0,0 +1,128 @@
+# openai_sqlite_cache
+
+`openai_sqlite_cache` 是非官方的 OpenAI Python SDK 透明 SQLite 缓存层。同一个 API、同一个模型、完全相同的输入再次调用时，会直接返回本机缓存的响应，不再请求上游。
+
+PyPI 分发名是 `openai_sqlite_cache`（规范化名称为 `openai-sqlite-cache`）；为满足只替换 import 的用法，Python 导入名仍然是 `cached_openai`。
+
+## 安装
+
+在当前仓库中安装：
+
+```bash
+pip install ./openai_sqlite_cache
+```
+
+发布到你有权限的 Python 包索引后，安装形式为：
+
+```bash
+pip install openai_sqlite_cache
+```
+
+> 注意：本项目与公共 PyPI 上的 `cached-openai` 分发项目都提供 `cached_openai` 导入包，二者不能安全地安装在同一个 Python 环境中。请只安装其中一个。
+
+## 用法
+
+现有代码只需替换 import，并保留 `openai` 这个本地别名：
+
+```python
+# 原来：import openai
+import cached_openai as openai
+
+client = openai.OpenAI()
+response = client.responses.create(
+    model="gpt-5",
+    input="Explain SQLite in one sentence.",
+)
+print(response.output_text)
+```
+
+也可以直接使用包名：
+
+```python
+import cached_openai
+
+client = cached_openai.OpenAI()
+completion = client.chat.completions.create(
+    model="gpt-4.1-mini",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+以下官方 SDK 用法均保持不变：
+
+- `OpenAI`、`AsyncOpenAI`、`AzureOpenAI` 和 `AsyncAzureOpenAI`；
+- 模块级调用，如 `openai.chat.completions.create(...)`；
+- `with_options()`、`with_raw_response`、`with_streaming_response`；
+- 自定义 `base_url` 和自定义同步/异步 `http_client`；
+- 官方 SDK 的响应模型和异常类型。
+
+流式响应会在第一次被完整消费时写入缓存；如果流被提前关闭，则不会缓存不完整内容。Realtime/WebSocket 不经过普通 HTTP 请求，因此不会缓存。
+
+## 缓存规则
+
+缓存键使用 SHA-256 计算，包含：
+
+- HTTP 方法和规范化后的完整 API URL；
+- 请求体（JSON 会按键排序，multipart 会忽略随机 boundary 并对文件内容取 hash）；
+- 模型名；
+- organization、project、beta 等会影响语义的请求头；
+- API 凭据的不可逆作用域 hash，防止不同 API key 之间共享响应。
+
+请求原文和 API key 都不会写入数据库。数据库只保存 hash、成功响应体、必要响应头和命中统计。默认永久保留，只缓存 2xx 响应。
+
+为避免有副作用的操作被错误去重，目前只缓存这些推理/生成端点：Responses、Chat Completions、Completions、Embeddings、Moderations、Images、Audio 和 Videos。Files、Uploads、Batches、Fine-tuning、Vector Stores 等管理类 API 会原样请求上游。
+
+## 配置
+
+默认数据库位置：
+
+- macOS：`~/Library/Caches/openai-sqlite-cache/cache.sqlite3`
+- Linux：`$XDG_CACHE_HOME/openai-sqlite-cache/cache.sqlite3`，未设置时使用 `~/.cache/...`
+- Windows：`%LOCALAPPDATA%/openai-sqlite-cache/cache.sqlite3`
+
+环境变量：
+
+```bash
+export CACHED_OPENAI_CACHE_PATH=/path/to/cache.sqlite3
+export CACHED_OPENAI_TTL_SECONDS=86400
+export CACHED_OPENAI_DISABLE=0
+```
+
+也可以在创建客户端前配置：
+
+```python
+import cached_openai as openai
+
+openai.configure_cache(
+    path="./.cache/openai.sqlite3",
+    ttl_seconds=24 * 60 * 60,
+)
+client = openai.OpenAI()
+```
+
+单个客户端可以覆盖全局配置：
+
+```python
+client = openai.OpenAI(
+    cache_path="./project-cache.sqlite3",
+    cache_ttl=3600,
+    cache_enabled=True,
+)
+```
+
+维护接口：
+
+```python
+print(openai.cache_info())
+removed = openai.clear_cache()
+```
+
+缓存文件可能包含模型响应中的敏感内容，应像其他本地应用数据一样保护。包会尽量把目录和数据库权限分别设为 `0700` 和 `0600`。
+
+## 开发与测试
+
+```bash
+cd openai_sqlite_cache
+python -m unittest discover -s tests -v
+python -m pip wheel --no-deps . -w dist
+```

openai_sqlite_cache-0.0.1/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openai_sqlite_cache"
+version = "0.0.1"
+description = "An unofficial drop-in OpenAI Python SDK with a local SQLite response cache"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "openai_sqlite_cache contributors" },
+]
+keywords = ["openai", "cache", "sqlite", "llm", "api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "openai>=1.66.2,<3",
+]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+cached_openai = ["py.typed"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

openai_sqlite_cache-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openai_sqlite_cache-0.0.1/src/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",
+    }
+)

openai_sqlite_cache-0.0.1/src/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]),
+        }