local-openai2anthropic 0.3.6__tar.gz → 0.3.8__tar.gz

{local_openai2anthropic-0.3.6 → local_openai2anthropic-0.3.8}/.claude/CLAUDE.md

@@ -77,7 +77,7 @@ websearch_max_uses = 5
 - **格式**: `assert app.version == "x.y.z"`
 - **示例**: `assert app.version == "0.3.5"`
 
-### 6. Git Tag
+### 6. Git Tag (重要：必须推送才能触发发布)
 - **格式**: `vx.y.z`
 - **示例**: `v0.3.5`
 - **命令**:
@@ -85,6 +85,7 @@ websearch_max_uses = 5
   git tag v0.3.5
   git push origin v0.3.5
   ```
+- **注意**: 推送 tag 会触发 GitHub Actions 自动发布到 PyPI，不要忘记推送 tag！
 
 ## 版本号格式
 
@@ -98,10 +99,16 @@ websearch_max_uses = 5
 1. 更新上述所有文件中的版本号
 2. 运行测试确保通过: `pytest`
 3. 提交更改: `git commit -m "chore(release): bump version to x.y.z"`
-4. 创建标签: `git tag vx.y.z`
-5. 推送代码和标签: `git push && git push origin vx.y.z`
+4. 推送代码: `git push`
+5. **创建并推送标签** (触发 GitHub Actions 发布):
+   ```bash
+   git tag vx.y.z
+   git push origin vx.y.z
+   ```
 6. GitHub Actions 将自动发布到 PyPI
 
+**重要**: 第 5 步推送 tag 是触发自动发布的关键步骤，不要忘记！
+
 ## 代码提交规范
 
 ### 测试覆盖率要求

{local_openai2anthropic-0.3.6 → local_openai2anthropic-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: local-openai2anthropic
-Version: 0.3.6
+Version: 0.3.8
 Summary: A lightweight proxy server that converts Anthropic Messages API to OpenAI API
 Project-URL: Homepage, https://github.com/dongfangzan/local-openai2anthropic
 Project-URL: Repository, https://github.com/dongfangzan/local-openai2anthropic
@@ -24,7 +24,7 @@ Requires-Dist: httpx>=0.25.0
 Requires-Dist: openai>=1.30.0
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: tomli-w>=1.0.0
 Requires-Dist: uvicorn[standard]>=0.23.0
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'
@@ -109,37 +109,47 @@ Examples:
 
 > **Note:** If you're using [Ollama](https://ollama.com), it natively supports the Anthropic API format, so you don't need this proxy. Just point your Claude SDK directly to `http://localhost:11434/v1`.
 
-### 3. Start the Proxy
+### 3. Start the Proxy (Recommended)
 
-**Option A: Run in background (recommended)**
+Run the following command to start the proxy in background mode:
 
 ```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1  # Your local LLM endpoint
-export OA2A_OPENAI_API_KEY=dummy  # Any value, not used by local backends
+oa2a start
+```
+
+**First-time setup**: If `~/.oa2a/config.toml` doesn't exist, an interactive setup wizard will guide you through:
+- Enter your OpenAI API Key (for the local LLM backend)
+- Enter the base URL of your local LLM (e.g., `http://localhost:8000/v1`)
+- Configure server host and port (optional)
+- Set server API key for authentication (optional)
 
-oa2a start              # Start server in background
-# Server starts at http://localhost:8080
+After configuration, the server starts at `http://localhost:8080`.
 
-# View logs
+**Daemon management commands:**
+
+```bash
 oa2a logs               # Show last 50 lines of logs
 oa2a logs -f            # Follow logs in real-time (Ctrl+C to exit)
-
-# Check status
 oa2a status             # Check if server is running
-
-# Stop server
 oa2a stop               # Stop background server
-
-# Restart server
 oa2a restart            # Restart with same settings
 ```
 
+**Manual Configuration**
+
+You can also manually create/edit the config file at `~/.oa2a/config.toml`:
+
+```toml
+# OA2A Configuration File
+openai_api_key = "dummy"
+openai_base_url = "http://localhost:8000/v1"
+host = "0.0.0.0"
+port = 8080
+```
+
 **Option B: Run in foreground**
 
 ```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1
-export OA2A_OPENAI_API_KEY=dummy
-
 oa2a                    # Run server in foreground (blocking)
 # Press Ctrl+C to stop
 ```
@@ -195,15 +205,6 @@ You can configure [Claude Code](https://github.com/anthropics/claude-code) to us
 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Default model for Haiku mode |
 | `ANTHROPIC_REASONING_MODEL` | Default model for reasoning tasks |
 
-2. **Or set environment variables** before running Claude Code:
-
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8080
-export ANTHROPIC_API_KEY=dummy-key
-
-claude
-```
-
 ### Complete Workflow Example
 
 Make sure `~/.claude/settings.json` is configured as described above.
@@ -215,10 +216,7 @@ vllm serve meta-llama/Llama-2-7b-chat-hf
 
 Terminal 2 - Start the proxy (background mode):
 ```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1
-export OA2A_OPENAI_API_KEY=dummy
-export OA2A_TAVILY_API_KEY="tvly-your-tavily-api-key"  # Optional: enable web search
-
+# First run: interactive setup wizard will guide you
 oa2a start
 ```
 
@@ -241,102 +239,43 @@ oa2a stop
 - ✅ **Streaming responses** - Real-time token streaming via SSE
 - ✅ **Tool calling** - Local LLM function calling support
 - ✅ **Vision models** - Multi-modal input for vision-capable models
-- ✅ **Web Search** - Give your local LLM internet access (see below)
+- ✅ **Web Search** - Built-in Tavily web search for local models
 - ✅ **Thinking mode** - Supports reasoning/thinking model outputs
 
 ---
 
-## Web Search Capability 🔍
-
-**Bridge the gap: Give your local LLM the web search power that Claude Code users enjoy!**
-
-When using locally-hosted models with Claude Code, you lose access to the built-in web search tool. This proxy fills that gap by providing a server-side web search implementation powered by [Tavily](https://tavily.com).
+## Web Search 🔍
 
-### The Problem
+Enable web search for your local LLM using [Tavily](https://tavily.com).
 
-| Scenario | Web Search Available? |
-|----------|----------------------|
-| Using Claude (cloud) in Claude Code | ✅ Built-in |
-| Using local vLLM/SGLang in Claude Code | ❌ Not available |
-| **Using this proxy + local LLM** | ✅ **Enabled via Tavily** |
+**Setup:**
 
-### How It Works
+1. Get a free API key at [tavily.com](https://tavily.com)
 
+2. Add to your config (`~/.oa2a/config.toml`):
+```toml
+tavily_api_key = "tvly-your-api-key"
 ```
-Claude Code → Anthropic SDK → This Proxy → Local LLM
-                                      ↓
-                                 Tavily API (Web Search)
-```
-
-The proxy intercepts `web_search_20250305` tool calls and handles them directly, regardless of whether your local model supports web search natively.
-
-### Setup Tavily Search
 
-1. **Get a free API key** at [tavily.com](https://tavily.com) - generous free tier available
+3. Use `web_search_20250305` tool in your app - the proxy handles search automatically.
 
-2. **Configure the proxy:**
-```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1
-export OA2A_OPENAI_API_KEY=dummy
-export OA2A_TAVILY_API_KEY="tvly-your-tavily-api-key"  # Enable web search
-
-oa2a
-```
-
-3. **Use in your app:**
-```python
-import anthropic
-
-client = anthropic.Anthropic(
-    base_url="http://localhost:8080",
-    api_key="dummy-key",
-)
-
-message = client.messages.create(
-    model="meta-llama/Llama-2-7b-chat-hf",
-    max_tokens=1024,
-    tools=[
-        {
-            "name": "web_search_20250305",
-            "description": "Search the web for current information",
-            "input_schema": {
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Search query"},
-                },
-                "required": ["query"],
-            },
-        }
-    ],
-    messages=[{"role": "user", "content": "What happened in AI today?"}],
-)
-
-if message.stop_reason == "tool_use":
-    tool_use = message.content[-1]
-    print(f"Searching: {tool_use.input}")
-    # The proxy automatically calls Tavily and returns results
-```
-
-### Tavily Configuration Options
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OA2A_TAVILY_API_KEY` | - | Your Tavily API key ([get free at tavily.com](https://tavily.com)) |
-| `OA2A_TAVILY_MAX_RESULTS` | 5 | Number of search results to return |
-| `OA2A_TAVILY_TIMEOUT` | 30 | Search timeout in seconds |
-| `OA2A_WEBSEARCH_MAX_USES` | 5 | Max search calls per request |
+**Options:** `tavily_max_results` (default: 5), `tavily_timeout` (default: 30), `websearch_max_uses` (default: 5)
 
 ---
 
 ## Configuration
 
-| Variable | Required | Default | Description |
+Config file: `~/.oa2a/config.toml` (auto-created on first run)
+
+| Option | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `OA2A_OPENAI_BASE_URL` | ✅ | - | Your local LLM's OpenAI-compatible endpoint |
-| `OA2A_OPENAI_API_KEY` | ✅ | - | Any value (local backends usually ignore this) |
-| `OA2A_PORT` | ❌ | 8080 | Proxy server port |
-| `OA2A_HOST` | ❌ | 0.0.0.0 | Proxy server host |
-| `OA2A_TAVILY_API_KEY` | ❌ | - | Enable web search ([tavily.com](https://tavily.com)) |
+| `openai_base_url` | ✅ | - | Local LLM endpoint (e.g., `http://localhost:8000/v1`) |
+| `openai_api_key` | ✅ | - | API key for local LLM |
+| `port` | ❌ | 8080 | Proxy port |
+| `host` | ❌ | 0.0.0.0 | Proxy host |
+| `api_key` | ❌ | - | Auth key for this proxy |
+| `tavily_api_key` | ❌ | - | Enable web search |
+| `log_level` | ❌ | INFO | DEBUG, INFO, WARNING, ERROR |
 
 ---
 

{local_openai2anthropic-0.3.6 → local_openai2anthropic-0.3.8}/README.md

@@ -73,37 +73,47 @@ Examples:
 
 > **Note:** If you're using [Ollama](https://ollama.com), it natively supports the Anthropic API format, so you don't need this proxy. Just point your Claude SDK directly to `http://localhost:11434/v1`.
 
-### 3. Start the Proxy
+### 3. Start the Proxy (Recommended)
 
-**Option A: Run in background (recommended)**
+Run the following command to start the proxy in background mode:
 
 ```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1  # Your local LLM endpoint
-export OA2A_OPENAI_API_KEY=dummy  # Any value, not used by local backends
+oa2a start
+```
+
+**First-time setup**: If `~/.oa2a/config.toml` doesn't exist, an interactive setup wizard will guide you through:
+- Enter your OpenAI API Key (for the local LLM backend)
+- Enter the base URL of your local LLM (e.g., `http://localhost:8000/v1`)
+- Configure server host and port (optional)
+- Set server API key for authentication (optional)
 
-oa2a start              # Start server in background
-# Server starts at http://localhost:8080
+After configuration, the server starts at `http://localhost:8080`.
 
-# View logs
+**Daemon management commands:**
+
+```bash
 oa2a logs               # Show last 50 lines of logs
 oa2a logs -f            # Follow logs in real-time (Ctrl+C to exit)
-
-# Check status
 oa2a status             # Check if server is running
-
-# Stop server
 oa2a stop               # Stop background server
-
-# Restart server
 oa2a restart            # Restart with same settings
 ```
 
+**Manual Configuration**
+
+You can also manually create/edit the config file at `~/.oa2a/config.toml`:
+
+```toml
+# OA2A Configuration File
+openai_api_key = "dummy"
+openai_base_url = "http://localhost:8000/v1"
+host = "0.0.0.0"
+port = 8080
+```
+
 **Option B: Run in foreground**
 
 ```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1
-export OA2A_OPENAI_API_KEY=dummy
-
 oa2a                    # Run server in foreground (blocking)
 # Press Ctrl+C to stop
 ```
@@ -159,15 +169,6 @@ You can configure [Claude Code](https://github.com/anthropics/claude-code) to us
 | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Default model for Haiku mode |
 | `ANTHROPIC_REASONING_MODEL` | Default model for reasoning tasks |
 
-2. **Or set environment variables** before running Claude Code:
-
-```bash
-export ANTHROPIC_BASE_URL=http://localhost:8080
-export ANTHROPIC_API_KEY=dummy-key
-
-claude
-```
-
 ### Complete Workflow Example
 
 Make sure `~/.claude/settings.json` is configured as described above.
@@ -179,10 +180,7 @@ vllm serve meta-llama/Llama-2-7b-chat-hf
 
 Terminal 2 - Start the proxy (background mode):
 ```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1
-export OA2A_OPENAI_API_KEY=dummy
-export OA2A_TAVILY_API_KEY="tvly-your-tavily-api-key"  # Optional: enable web search
-
+# First run: interactive setup wizard will guide you
 oa2a start
 ```
 
@@ -205,102 +203,43 @@ oa2a stop
 - ✅ **Streaming responses** - Real-time token streaming via SSE
 - ✅ **Tool calling** - Local LLM function calling support
 - ✅ **Vision models** - Multi-modal input for vision-capable models
-- ✅ **Web Search** - Give your local LLM internet access (see below)
+- ✅ **Web Search** - Built-in Tavily web search for local models
 - ✅ **Thinking mode** - Supports reasoning/thinking model outputs
 
 ---
 
-## Web Search Capability 🔍
-
-**Bridge the gap: Give your local LLM the web search power that Claude Code users enjoy!**
-
-When using locally-hosted models with Claude Code, you lose access to the built-in web search tool. This proxy fills that gap by providing a server-side web search implementation powered by [Tavily](https://tavily.com).
+## Web Search 🔍
 
-### The Problem
+Enable web search for your local LLM using [Tavily](https://tavily.com).
 
-| Scenario | Web Search Available? |
-|----------|----------------------|
-| Using Claude (cloud) in Claude Code | ✅ Built-in |
-| Using local vLLM/SGLang in Claude Code | ❌ Not available |
-| **Using this proxy + local LLM** | ✅ **Enabled via Tavily** |
+**Setup:**
 
-### How It Works
+1. Get a free API key at [tavily.com](https://tavily.com)
 
+2. Add to your config (`~/.oa2a/config.toml`):
+```toml
+tavily_api_key = "tvly-your-api-key"
 ```
-Claude Code → Anthropic SDK → This Proxy → Local LLM
-                                      ↓
-                                 Tavily API (Web Search)
-```
-
-The proxy intercepts `web_search_20250305` tool calls and handles them directly, regardless of whether your local model supports web search natively.
-
-### Setup Tavily Search
 
-1. **Get a free API key** at [tavily.com](https://tavily.com) - generous free tier available
+3. Use `web_search_20250305` tool in your app - the proxy handles search automatically.
 
-2. **Configure the proxy:**
-```bash
-export OA2A_OPENAI_BASE_URL=http://localhost:8000/v1
-export OA2A_OPENAI_API_KEY=dummy
-export OA2A_TAVILY_API_KEY="tvly-your-tavily-api-key"  # Enable web search
-
-oa2a
-```
-
-3. **Use in your app:**
-```python
-import anthropic
-
-client = anthropic.Anthropic(
-    base_url="http://localhost:8080",
-    api_key="dummy-key",
-)
-
-message = client.messages.create(
-    model="meta-llama/Llama-2-7b-chat-hf",
-    max_tokens=1024,
-    tools=[
-        {
-            "name": "web_search_20250305",
-            "description": "Search the web for current information",
-            "input_schema": {
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Search query"},
-                },
-                "required": ["query"],
-            },
-        }
-    ],
-    messages=[{"role": "user", "content": "What happened in AI today?"}],
-)
-
-if message.stop_reason == "tool_use":
-    tool_use = message.content[-1]
-    print(f"Searching: {tool_use.input}")
-    # The proxy automatically calls Tavily and returns results
-```
-
-### Tavily Configuration Options
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OA2A_TAVILY_API_KEY` | - | Your Tavily API key ([get free at tavily.com](https://tavily.com)) |
-| `OA2A_TAVILY_MAX_RESULTS` | 5 | Number of search results to return |
-| `OA2A_TAVILY_TIMEOUT` | 30 | Search timeout in seconds |
-| `OA2A_WEBSEARCH_MAX_USES` | 5 | Max search calls per request |
+**Options:** `tavily_max_results` (default: 5), `tavily_timeout` (default: 30), `websearch_max_uses` (default: 5)
 
 ---
 
 ## Configuration
 
-| Variable | Required | Default | Description |
+Config file: `~/.oa2a/config.toml` (auto-created on first run)
+
+| Option | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `OA2A_OPENAI_BASE_URL` | ✅ | - | Your local LLM's OpenAI-compatible endpoint |
-| `OA2A_OPENAI_API_KEY` | ✅ | - | Any value (local backends usually ignore this) |
-| `OA2A_PORT` | ❌ | 8080 | Proxy server port |
-| `OA2A_HOST` | ❌ | 0.0.0.0 | Proxy server host |
-| `OA2A_TAVILY_API_KEY` | ❌ | - | Enable web search ([tavily.com](https://tavily.com)) |
+| `openai_base_url` | ✅ | - | Local LLM endpoint (e.g., `http://localhost:8000/v1`) |
+| `openai_api_key` | ✅ | - | API key for local LLM |
+| `port` | ❌ | 8080 | Proxy port |
+| `host` | ❌ | 0.0.0.0 | Proxy host |
+| `api_key` | ❌ | - | Auth key for this proxy |
+| `tavily_api_key` | ❌ | - | Enable web search |
+| `log_level` | ❌ | INFO | DEBUG, INFO, WARNING, ERROR |
 
 ---