onellmclient 0.1.0__tar.gz

onellmclient-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/python:*)",
+      "Bash(.venv/bin/pytest tests/test_client.py::test_completion_tools -k anthropic -v -s)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

onellmclient-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.dist/
+.build/
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+.uv/
+.env
+.mypy_cache/
+.DS_Store

onellmclient-0.1.0/CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Unified LLM Client - A Python library that provides a unified interface for OpenAI, Anthropic, and Gemini APIs. This allows applications to transparently switch between LLM providers without changing code.
+
+**Key Design Principle**: Zero mandatory runtime dependencies. Each provider's SDK is optional and installed via extras.
+
+## Common Commands
+
+### Environment Setup
+```bash
+# Create virtual environment and install package
+uv venv
+uv pip install -e .
+
+# Install specific provider SDKs
+uv pip install -e .[openai]
+uv pip install -e .[anthropic]
+uv pip install -e .[gemini]
+uv pip install -e .[all]
+
+# Install test dependencies
+uv pip install -e .[test]
+```
+
+### Testing
+```bash
+# Run all tests
+pytest
+
+# Run tests for a specific provider
+pytest tests/test_client.py::test_completion_say_cow -k openai
+pytest tests/test_client.py::test_completion_say_cow -k anthropic
+pytest tests/test_client.py::test_completion_say_cow -k gemini
+
+# Run a specific test function
+pytest tests/test_client.py::test_completion_schema -v
+```
+
+### Building and Publishing
+```bash
+# Build distribution packages
+uv build
+
+# Upload to TestPyPI
+uv tool install twine
+uv run twine upload --repository testpypi dist/*
+
+# Upload to PyPI
+uv run twine upload dist/*
+```
+
+## Architecture
+
+### Core Components
+
+**`client.py`**: Main `Client` class that provides two methods:
+- `completion()`: Single request/response interaction with provider
+- `agent()`: Automatic tool call execution loop (up to 10 iterations)
+
+Both methods accept unified parameters and return `UnifiedMessage` objects.
+
+**`types.py`**: Pydantic models defining the unified message format:
+- `UnifiedMessage`: Base message container with role and content
+- `UnifiedTextMessageContent`: Text content blocks
+- `UnifiedToolCallMessageContent`: Tool/function call requests
+- `UnifiedToolResultMessageContent`: Tool execution results
+- All types extend `UnifiedBaseModel` which adds `.get()` method for dict-like access
+
+**`utils.py`**: Conversion utilities between unified format and provider-specific formats:
+- `{provider}_messages()`: Convert `UnifiedMessage` → provider format
+- `{provider}_response_convert()`: Convert provider response → `UnifiedMessage`
+- `{provider}_tools()`: Convert unified tool definitions → provider format
+- `openai_json_schema()`: Recursively adds `additionalProperties: false` for OpenAI strict mode
+
+### Key Architectural Patterns
+
+1. **Message Format Unification**: All providers use different message formats. The library normalizes them:
+   - OpenAI uses `response.output` with separate `message` and `function_call` types
+   - Anthropic uses `message.content` with `text` and `tool_use` blocks
+   - Gemini uses `content.parts` with `text` and `function_call` attributes
+
+2. **Parameter Translation**: Provider-specific parameters are translated:
+   - `temperature`: Anthropic uses 0-1 range (divided by 2), others use 0-2
+   - `instructions`: Maps to `instructions` (OpenAI), `system` (Anthropic), `system_instruction` (Gemini)
+   - `schema`: OpenAI uses native support, Anthropic uses system prompt injection, Gemini uses `response_schema`
+   - `tool_choice`: Unified `auto/none/required` maps to provider-specific values
+   - `reasoning_effort`: Maps to `reasoning.effort` (OpenAI), `thinking.budget_tokens` (Anthropic), `thinking_budget` (Gemini)
+
+3. **Tool Call Loop**: The `agent()` method automatically handles multi-turn tool execution by:
+   - Calling `completion()` with tools
+   - If response contains tool calls, execute handlers and append results to messages
+   - Repeat until no tool calls in response or max iterations (10) reached
+
+4. **Role Mapping**: Gemini uses `model` instead of `assistant`, converted in `gemini_messages()` and `gemini_response_convert()`
+
+## Development Constraints
+
+- **Minimize implementation**: Only add features when needed
+- **Preserve `.env`**: Never modify the environment file
+- **Unit test coverage**: Only test modified code sections
+- **Dependency versioning**: Use format `>=x.y.z,<x.y+1.0` to prevent breaking updates while allowing patches
+- **Provider isolation**: Each provider implementation in `src/onellmclient/provider/{provider}/` is independent
+
+## Testing Requirements
+
+Tests require API keys in `.env`:
+```
+OPENAI_API_KEY=...
+OPENAI_API_BASE=...
+ANTHROPIC_API_KEY=...
+ANTHROPIC_API_BASE=...
+GEMINI_API_KEY=...
+GEMINI_API_BASE=...
+```
+
+All test functions are parameterized to run against all three providers with their respective models.

onellmclient-0.1.0/CURSOR.md

@@ -0,0 +1,43 @@
+# CURSOR.md
+
+统一LLM接口客户端
+
+## 技术架构
+- 语言：Python 3.9+
+- 构建：hatchling（PEP 517/518）
+- 环境管理：uv（推荐）
+- 包布局：`src/` 结构
+
+## 项目结构
+- `src/onellmclient/`：核心包
+- `tests/`：单元测试
+
+## 开发约定
+- 仅最小化实现，按需引入依赖（extras）。
+- 单元测试仅覆盖改动部分。
+- 禁止改动 `.env`。
+
+## 依赖管理策略
+- 使用版本范围限制：`>=x.y.z,<x.y+1.0` 格式
+- 防止破坏性更新，允许安全补丁更新
+- 保持构建可重现性
+
+## 开发环境安装
+```bash
+# 安装开发依赖
+uv sync --extra dev
+
+# 安装测试依赖
+uv sync --extra test
+
+# 安装所有开发测试依赖
+uv sync --extra all-dev
+
+# 安装特定 LLM 提供商依赖
+uv sync --extra openai
+```
+
+## TODO 记录
+- 初始化包与发布配置
+- 实现统一 Client（OpenAI/Anthropic/Gemini）
+- 增加 provider 适配层与最小集成测试

onellmclient-0.1.0/LICENSE

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

onellmclient-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: onellmclient
+Version: 0.1.0
+Summary: A unified Python client to normalize interfaces across major LLM providers (OpenAI, Anthropic, Gemini).
+Author-email: Your Name <you@example.com>
+License: MIT License
+        
+        Copyright (c) 2025
+        
+        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.
+License-File: LICENSE
+Keywords: anthropic,client,gemini,llm,openai,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Provides-Extra: all
+Requires-Dist: anthropic<1.0.0,>=0.68.0; extra == 'all'
+Requires-Dist: google-genai<2.0.0,>=1.38.0; extra == 'all'
+Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1.0.0,>=0.68.0; extra == 'anthropic'
+Provides-Extra: gemini
+Requires-Dist: google-genai<2.0.0,>=1.38.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'openai'
+Provides-Extra: test
+Requires-Dist: anthropic<1.0.0,>=0.68.0; extra == 'test'
+Requires-Dist: google-genai<2.0.0,>=1.38.0; extra == 'test'
+Requires-Dist: openai<2.0.0,>=1.109.1; extra == 'test'
+Requires-Dist: pytest<9.0.0,>=8.4.2; extra == 'test'
+Requires-Dist: python-dotenv<2.0,>=1.1.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+# onellmclient
+
+统一主要 LLM 提供商（OpenAI、Anthropic、Gemini）接口格式的 Python 客户端。
+
+- 运行时零强制依赖；通过 extras 按需安装各家 SDK。
+- 提供统一的 `Client` 接口以便上层应用透明切换供应商。
+
+## 安装
+
+使用 uv（推荐）：
+
+```bash
+uv venv
+uv pip install -e .
+# 或安装某家 SDK：
+uv pip install -e .[openai]
+uv pip install -e .[anthropic]
+uv pip install -e .[gemini]
+uv pip install -e .[all]
+```
+
+## 构建与发布
+
+使用 uv 构建 sdist 与 wheel：
+
+```bash
+uv build
+ls dist/
+```
+
+发布到 TestPyPI：
+
+```bash
+uv tool install twine  # 首次需要安装
+uv run twine upload --repository testpypi dist/*
+# 安装测试：
+uv pip install -i https://test.pypi.org/simple/ onellmclient==0.1.0
+```
+
+发布到 PyPI（确认版本号已递增且能在 TestPyPI 正常安装后）：
+
+```bash
+uv run twine upload dist/*
+```
+
+## 使用
+
+```python
+from onellmclient import Client
+
+client = Client(openai={"api_key": "..."})
+resp = client.completion(
+    provider="openai", model="gpt-4o-mini", messages=[{"role":"user","content":"hi"}]
+)
+print(resp)
+```
+
+## 开源协议
+
+MIT

onellmclient-0.1.0/README.md

@@ -0,0 +1,60 @@
+# onellmclient
+
+统一主要 LLM 提供商（OpenAI、Anthropic、Gemini）接口格式的 Python 客户端。
+
+- 运行时零强制依赖；通过 extras 按需安装各家 SDK。
+- 提供统一的 `Client` 接口以便上层应用透明切换供应商。
+
+## 安装
+
+使用 uv（推荐）：
+
+```bash
+uv venv
+uv pip install -e .
+# 或安装某家 SDK：
+uv pip install -e .[openai]
+uv pip install -e .[anthropic]
+uv pip install -e .[gemini]
+uv pip install -e .[all]
+```
+
+## 构建与发布
+
+使用 uv 构建 sdist 与 wheel：
+
+```bash
+uv build
+ls dist/
+```
+
+发布到 TestPyPI：
+
+```bash
+uv tool install twine  # 首次需要安装
+uv run twine upload --repository testpypi dist/*
+# 安装测试：
+uv pip install -i https://test.pypi.org/simple/ onellmclient==0.1.0
+```
+
+发布到 PyPI（确认版本号已递增且能在 TestPyPI 正常安装后）：
+
+```bash
+uv run twine upload dist/*
+```
+
+## 使用
+
+```python
+from onellmclient import Client
+
+client = Client(openai={"api_key": "..."})
+resp = client.completion(
+    provider="openai", model="gpt-4o-mini", messages=[{"role":"user","content":"hi"}]
+)
+print(resp)
+```
+
+## 开源协议
+
+MIT

onellmclient-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling>=1.24.2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "onellmclient"
+version = "0.1.0"
+description = "A unified Python client to normalize interfaces across major LLM providers (OpenAI, Anthropic, Gemini)."
+authors = [{ name = "Your Name", email = "you@example.com" }]
+license = { file = "LICENSE" }
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = ["llm", "openai", "anthropic", "gemini", "client", "sdk"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+# 运行时硬依赖尽量为空；第三方SDK由用户按需安装（extras）
+dependencies = []
+
+[project.optional-dependencies]
+openai = ["openai>=1.109.1,<2.0.0"]
+anthropic = ["anthropic>=0.68.0,<1.0.0"]
+gemini = ["google-genai>=1.38.0,<2.0.0"]
+all = [
+    "openai>=1.109.1,<2.0.0",
+    "anthropic>=0.68.0,<1.0.0",
+    "google-genai>=1.38.0,<2.0.0",
+]
+
+# 开发测试依赖
+test = [
+    "openai>=1.109.1,<2.0.0",
+    "anthropic>=0.68.0,<1.0.0",
+    "google-genai>=1.38.0,<2.0.0",
+    "pytest>=8.4.2,<9.0.0",
+    "python-dotenv>=1.1.1,<2.0",
+]
+
+[project.urls]
+
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/onellmclient"]
+
+[tool.hatch.version]
+path = "src/onellmclient/__init__.py"
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+pythonpath = ["src"]

onellmclient-0.1.0/src/onellmclient/__init__.py

@@ -0,0 +1,6 @@
+"""Unified LLM Client package."""
+
+from .client import Client
+
+__all__ = ["Client"]
+__version__ = "0.1.0"