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

cached_openai/_settings.py

@@ -0,0 +1,122 @@
+"""Cache settings and platform-appropriate defaults."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, replace
+from pathlib import Path
+from threading import RLock
+from typing import Optional, Union
+
+PathLike = Union[str, os.PathLike[str]]
+
+
+def default_cache_path() -> Path:
+    """Return a user-local cache path without requiring another dependency."""
+
+    configured = os.environ.get("CACHED_OPENAI_CACHE_PATH")
+    if configured:
+        return Path(configured).expanduser()
+
+    if sys.platform == "darwin":
+        root = Path.home() / "Library" / "Caches"
+    elif os.name == "nt":
+        root = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        root = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return root / "openai-sqlite-cache" / "cache.sqlite3"
+
+
+def _env_flag(name: str, default: bool) -> bool:
+    value = os.environ.get(name)
+    if value is None:
+        return default
+    return value.strip().lower() not in {"0", "false", "no", "off"}
+
+
+def _env_ttl() -> Optional[float]:
+    value = os.environ.get("CACHED_OPENAI_TTL_SECONDS", "").strip()
+    if not value:
+        return None
+    ttl = float(value)
+    if ttl < 0:
+        raise ValueError("CACHED_OPENAI_TTL_SECONDS must be zero or greater")
+    return ttl
+
+
+@dataclass(frozen=True)
+class CacheSettings:
+    path: Path
+    ttl_seconds: Optional[float] = None
+    enabled: bool = True
+
+
+_settings_lock = RLock()
+_settings: Optional[CacheSettings] = None
+
+
+def get_settings() -> CacheSettings:
+    global _settings
+    with _settings_lock:
+        if _settings is None:
+            _settings = CacheSettings(
+                path=default_cache_path(),
+                ttl_seconds=_env_ttl(),
+                enabled=not _env_flag("CACHED_OPENAI_DISABLE", False),
+            )
+        return _settings
+
+
+_UNSET = object()
+
+
+def configure_settings(
+    *,
+    path: Union[PathLike, object] = _UNSET,
+    ttl_seconds: Union[Optional[float], object] = _UNSET,
+    enabled: Union[bool, object] = _UNSET,
+) -> CacheSettings:
+    global _settings
+    with _settings_lock:
+        current = get_settings()
+        changes = {}
+        if path is not _UNSET:
+            changes["path"] = Path(path).expanduser()  # type: ignore[arg-type]
+        if ttl_seconds is not _UNSET:
+            if ttl_seconds is not None and float(ttl_seconds) < 0:  # type: ignore[arg-type]
+                raise ValueError("ttl_seconds must be zero or greater")
+            changes["ttl_seconds"] = (
+                None if ttl_seconds is None else float(ttl_seconds)  # type: ignore[arg-type]
+            )
+        if enabled is not _UNSET:
+            changes["enabled"] = bool(enabled)
+        _settings = replace(current, **changes)
+        return _settings
+
+
+def settings_for_client(
+    *,
+    cache_path: Union[Optional[PathLike], object] = _UNSET,
+    cache_ttl: Union[Optional[float], object] = _UNSET,
+    cache_enabled: Union[Optional[bool], object] = _UNSET,
+) -> CacheSettings:
+    current = get_settings()
+    path = (
+        current.path
+        if cache_path is _UNSET or cache_path is None
+        else Path(cache_path).expanduser()
+    )
+    ttl = current.ttl_seconds if cache_ttl is _UNSET else cache_ttl
+    enabled = (
+        current.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),
+    )

cached_openai/_version.py

@@ -0,0 +1,3 @@
+"""Package version information."""
+
+PACKAGE_VERSION = "0.0.1"

cached_openai/py.typed

@@ -0,0 +1 @@
+

openai_sqlite_cache-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+cached_openai/__init__.py,sha256=SrjO8Mntmt7OiPUaQlR9xCoQcWPX6xAUhrfYzlRWNs0,4703
+cached_openai/_cache.py,sha256=TJizYukVUsBonsvTnqi7Bmx62B9sLi0ZbzC-hGUuTmo,4978
+cached_openai/_client.py,sha256=oDZokr-B6TT1gfz-u0ANFDEC2zfL1QCTjFN4PYNDCX8,4618
+cached_openai/_fingerprint.py,sha256=yhkt5ZixD7TO80-xD7MklmiIZuhUjeiuyPhfE-6GPv0,6234
+cached_openai/_http.py,sha256=5_Ky-YPrD-s6kcg8x_sdvOSQYwdhKH6k-8md9mWY56U,17488
+cached_openai/_module_alias.py,sha256=QYHlNKyds6eD-Mfic81-9aOKKEGebXefzmH0mnBsw08,2973
+cached_openai/_settings.py,sha256=ZpOVq4ngCKjnmzTxbB-b48N0WLaEI4w4HfgXmhgwyDw,3657
+cached_openai/_version.py,sha256=yXe71I5Ds7WgI-daxeCN0TpK2xgujsfxH7z7GjPCZqA,62
+cached_openai/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+openai_sqlite_cache-0.0.1.dist-info/licenses/LICENSE,sha256=3nKN1iGgSEww3R8uNaFoxf54TmEQVaJr7Fw3draZZVI,1089
+openai_sqlite_cache-0.0.1.dist-info/METADATA,sha256=zdvmq8DWv_nrn2grSd4AFWmZlCNh-DvUnvAy1NuBTz0,4847
+openai_sqlite_cache-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+openai_sqlite_cache-0.0.1.dist-info/top_level.txt,sha256=DlzMut0JtFH9dwVNMedzyoKmV3m03J_dUFWq2LHYpDA,14
+openai_sqlite_cache-0.0.1.dist-info/RECORD,,

openai_sqlite_cache-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openai_sqlite_cache-0.0.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+cached_openai