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

local_openai2anthropic-0.3.6/.claude/CLAUDE.md

@@ -0,0 +1,163 @@
+# Claude 开发指南
+
+## Configuration File
+
+### Config File Location
+
+- **Linux/macOS**: `~/.oa2a/config.toml`
+- **Windows**: `%USERPROFILE%\.oa2a\config.toml`
+
+### First Run
+
+A default config file will be created automatically on first startup. Edit this file to add your API keys.
+
+### Configuration Example
+
+```toml
+# OA2A Configuration File
+# Place this file at ~/.oa2a/config.toml
+
+# OpenAI API Configuration
+openai_api_key = "your-openai-api-key"
+openai_base_url = "https://api.openai.com/v1"
+openai_org_id = ""
+openai_project_id = ""
+
+# Server Configuration
+host = "0.0.0.0"
+port = 8080
+request_timeout = 300.0
+
+# API Key for authenticating requests to this server (optional)
+api_key = ""
+
+# CORS settings
+cors_origins = ["*"]
+cors_credentials = true
+cors_methods = ["*"]
+cors_headers = ["*"]
+
+# Logging
+log_level = "DEBUG"
+log_dir = ""  # Empty uses platform-specific default
+
+# Tavily Web Search Configuration
+tavily_api_key = ""
+tavily_timeout = 30.0
+tavily_max_results = 5
+websearch_max_uses = 5
+```
+
+## 版本号更新清单
+
+当修改项目版本号时，需要同步更新以下所有位置：
+
+### 1. pyproject.toml
+- **位置**: 第3行
+- **格式**: `version = "x.y.z"`
+- **示例**: `version = "0.3.5"`
+
+### 2. src/local_openai2anthropic/__init__.py
+- **位置**: 第6行
+- **格式**: `__version__ = "x.y.z"`
+- **示例**: `__version__ = "0.3.5"`
+
+### 3. src/local_openai2anthropic/main.py (FastAPI 应用版本)
+- **位置**: 第104行
+- **格式**: `version="x.y.z"`
+- **示例**: `version="0.3.5"`
+
+### 4. src/local_openai2anthropic/main.py (命令行 --version)
+- **位置**: 第254行
+- **格式**: `version="%(prog)s x.y.z"`
+- **示例**: `version="%(prog)s 0.3.5"`
+
+### 5. tests/test_main.py (测试断言)
+- **位置**: 第26行
+- **格式**: `assert app.version == "x.y.z"`
+- **示例**: `assert app.version == "0.3.5"`
+
+### 6. Git Tag
+- **格式**: `vx.y.z`
+- **示例**: `v0.3.5`
+- **命令**:
+  ```bash
+  git tag v0.3.5
+  git push origin v0.3.5
+  ```
+
+## 版本号格式
+
+使用语义化版本控制 (Semantic Versioning)：
+- **MAJOR**: 不兼容的 API 修改
+- **MINOR**: 向下兼容的功能新增
+- **PATCH**: 向下兼容的问题修复
+
+## 发布流程
+
+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`
+6. GitHub Actions 将自动发布到 PyPI
+
+## 代码提交规范
+
+### 测试覆盖率要求
+
+在提交任何新代码之前，必须满足以下测试要求：
+
+#### 1. 新代码单元测试
+- **必须**为所有未提交的新代码编写单元测试
+- 新代码的测试覆盖率**必须 > 90%**
+- 测试文件命名规范: `test_<module_name>.py`
+- 测试函数命名规范: `test_<function_name>_<scenario>`
+
+#### 2. 总体覆盖率检查
+- 运行 `/everything-claude-code:test-coverage` 检查总体覆盖率
+- **总体覆盖率必须 ≥ 80%**
+- 如果总体覆盖率低于 80%，需要补充测试或优化现有代码
+
+#### 3. 代码审查
+
+在提交代码前，必须进行代码审查：
+
+```bash
+# 运行代码审查（检查安全漏洞、代码质量、最佳实践）
+/code-review:code-review
+
+# 根据审查结果修复问题
+# - CRITICAL/HIGH 级别问题必须修复
+# - MEDIUM/LOW 级别问题根据情况处理
+```
+
+代码审查将检查：
+- **安全问题**: 硬编码凭证、SQL注入、XSS、路径遍历等
+- **代码质量**: 函数长度、嵌套深度、错误处理、console.log等
+- **最佳实践**: 不可变模式、emoji使用、测试覆盖、可访问性等
+
+#### 4. 提交流程
+```bash
+# 1. 编写新代码
+# 2. 编写对应的单元测试
+# 3. 运行测试并检查覆盖率
+pytest --cov=src/local_openai2anthropic --cov-report=term-missing
+
+# 4. 运行 Claude Code 覆盖率检查
+/everything-claude-code:test-coverage
+
+# 5. 运行代码审查
+/code-review:code-review
+
+# 6. 确认新代码覆盖率 > 90% 且总体覆盖率 ≥ 80%，且无 CRITICAL/HIGH 问题
+# 7. 提交代码
+git add .
+git commit -m "feat: your commit message"
+```
+
+#### 4. 测试质量标准
+- 测试用例应覆盖正常路径、边界条件和异常情况
+- 使用 `pytest` 作为测试框架
+- 异步代码使用 `pytest-asyncio`
+- 适当的测试夹具 (fixtures) 和参数化测试

local_openai2anthropic-0.3.6/.reports/dead-code-analysis.md

@@ -0,0 +1,282 @@
+# Dead Code Analysis Report
+
+**Project:** local-openai2anthropic
+**Analysis Date:** 2026-02-03
+**Tools Used:** vulture, pylint, ruff
+
+---
+
+## Executive Summary
+
+This report identifies potentially unused code in the codebase. The analysis found **47 issues** across the source code, categorized by severity level. No code has been deleted - this is for review purposes only.
+
+### Summary by Severity
+
+| Severity | Count | Description |
+|----------|-------|-------------|
+| SAFE | 23 | Unused imports, variables, and f-strings - safe to remove |
+| CAUTION | 15 | Unused functions/methods - verify before removal |
+| DANGER | 9 | Model fields and properties - may be used externally |
+
+---
+
+## Detailed Findings
+
+### SEVERITY: SAFE (High Confidence for Removal)
+
+These items are safe to remove with minimal risk.
+
+#### 1. Unused Imports
+
+| File | Line | Item | Tool | Notes |
+|------|------|------|------|-------|
+| `src/local_openai2anthropic/converter.py` | 20 | `ChatCompletionChunk` from `openai.types.chat` | vulture (90%), ruff, pylint | Imported but never referenced |
+| `src/local_openai2anthropic/converter.py` | 26 | `ServerToolRegistry` from `local_openai2anthropic.server_tools` | vulture (90%), ruff, pylint | Imported but never referenced |
+| `src/local_openai2anthropic/protocol.py` | 9 | `Field` from `pydantic` | vulture (90%), ruff, pylint | Imported but never used in file |
+| `tests/test_daemon_runner.py` | 8 | `datetime` | vulture (90%) | Unused import in test file |
+| `tests/test_router_comprehensive.py` | 7 | `Mock` from `unittest.mock` | vulture (90%) | Unused import |
+| `tests/test_router_comprehensive.py` | 9 | `Request` from `fastapi` | vulture (90%) | Unused import |
+| `tests/test_router_comprehensive.py` | 10 | `StreamingResponse` from `fastapi.responses` | vulture (90%) | Unused import |
+| `tests/test_router_comprehensive.py` | 12 | `_handle_with_server_tools` from `local_openai2anthropic.router` | vulture (90%) | Unused import |
+| `tests/test_router_streaming.py` | 7 | `Mock` from `unittest.mock` | vulture (90%) | Unused import |
+| `tests/test_router_streaming.py` | 9 | `StreamingResponse` from `fastapi.responses` | vulture (90%) | Unused import |
+| `tests/test_router_streaming.py` | 11 | `_handle_with_server_tools` from `local_openai2anthropic.router` | vulture (90%) | Unused import |
+
+#### 2. Unused Local Variables
+
+| File | Line | Variable | Tool | Notes |
+|------|------|----------|------|-------|
+| `src/local_openai2anthropic/converter.py` | 297 | `is_error` | ruff (F841) | Assigned but never used in tool_result handling |
+| `src/local_openai2anthropic/daemon.py` | 274 | `e` (exception) | ruff (F841) | Exception variable not used in except block |
+| `src/local_openai2anthropic/main.py` | 240 | `status_parser` | vulture (60%), ruff | Assigned but status command parser not used |
+| `src/local_openai2anthropic/router.py` | 483 | `openai_stop_reason` | vulture (60%), ruff | Variable assigned but never used |
+| `src/local_openai2anthropic/router.py` | 1182 | `model` | ruff (F841) | Extracted from request but never used |
+
+#### 3. F-strings Without Placeholders
+
+| File | Line | Content | Tool | Notes |
+|------|------|---------|------|-------|
+| `src/local_openai2anthropic/daemon.py` | 146 | `"Use 'oa2a logs' to view output"` | ruff (F541) | No placeholders in f-string |
+| `src/local_openai2anthropic/daemon.py` | 152 | `"Another process may be listening on this port"` | ruff (F541) | No placeholders in f-string |
+| `src/local_openai2anthropic/daemon.py` | 263 | `"Server did not stop gracefully, use -f to force kill"` | ruff (F541) | No placeholders in f-string |
+| `src/local_openai2anthropic/daemon_runner.py` | 84 | `"Configuration loaded:"` | ruff (F541) | No placeholders in f-string |
+
+#### 4. Unused Arguments
+
+| File | Line | Function/Method | Argument | Tool | Notes |
+|------|------|-----------------|----------|------|-------|
+| `src/local_openai2anthropic/daemon_runner.py` | 45 | signal handler | `frame` | vulture (100%), pylint | Signal handler frame argument not used |
+| `src/local_openai2anthropic/main.py` | 95 | `http_exception_handler` | `request` | pylint | FastAPI exception handler receives request but doesn't use it |
+| `src/local_openai2anthropic/main.py` | 116 | `general_exception_handler` | `request` | pylint | FastAPI exception handler receives request but doesn't use it |
+| `src/local_openai2anthropic/router.py` | 860 | (inline function) | `handler` | pylint | Exception handler argument not used |
+| `src/local_openai2anthropic/router.py` | 1138 | `count_tokens` | `settings` | pylint | Settings dependency injected but not used |
+
+---
+
+### SEVERITY: CAUTION (Verify Before Removal)
+
+These items appear unused but may be called dynamically or through external APIs.
+
+#### 1. Unused Functions
+
+| File | Line | Function | Tool | Risk Assessment |
+|------|------|----------|------|-----------------|
+| `src/local_openai2anthropic/converter.py` | 348 | `_build_usage_with_cache` | vulture (60%) | **LOW RISK** - Private function, appears truly unused. Could be removed or used for future cache token support. |
+| `src/local_openai2anthropic/main.py` | 55 | `auth_middleware` | vulture (60%) | **MEDIUM RISK** - Middleware that may be registered dynamically. Verify if used in app setup. |
+| `src/local_openai2anthropic/main.py` | 94 | `http_exception_handler` | vulture (60%) | **LOW RISK** - Exception handler, may be registered via decorator. Check FastAPI app setup. |
+| `src/local_openai2anthropic/main.py` | 115 | `general_exception_handler` | vulture (60%) | **LOW RISK** - Exception handler, may be registered via decorator. Check FastAPI app setup. |
+| `src/local_openai2anthropic/router.py` | 898 | `create_message` | vulture (60%) | **MEDIUM RISK** - API endpoint handler. May be registered as route. Verify router setup. |
+| `src/local_openai2anthropic/router.py` | 1106 | `list_models` | vulture (60%) | **MEDIUM RISK** - API endpoint handler. May be registered as route. Verify router setup. |
+| `src/local_openai2anthropic/router.py` | 1135 | `count_tokens` | vulture (60%) | **MEDIUM RISK** - API endpoint handler. May be registered as route. Verify router setup. |
+| `src/local_openai2anthropic/router.py` | 1241 | `health_check` | vulture (60%) | **MEDIUM RISK** - API endpoint handler. May be registered as route. Verify router setup. |
+
+#### 2. Unused Methods
+
+| File | Line | Class | Method | Tool | Risk Assessment |
+|------|------|-------|--------|------|-----------------|
+| `src/local_openai2anthropic/server_tools/base.py` | 167 | `ServerToolRegistry` | `all_tools` | vulture (60%) | **LOW RISK** - Method that returns all registered tools. May be useful for debugging/admin. |
+
+#### 3. Unused Test Functions/Fixtures
+
+| File | Line | Function | Tool | Notes |
+|------|------|----------|------|-------|
+| `tests/test_router_comprehensive.py` | 31 | `async_iter` | vulture (60%) | Helper function, may be used in tests |
+| `tests/test_router_streaming.py` | 25 | `async_iter` | vulture (60%) | Helper function, may be used in tests |
+| `tests/test_router_streaming.py` | 614 | `async_iter` | vulture (60%) | Duplicate helper function |
+
+---
+
+### SEVERITY: DANGER (Do Not Remove Without Careful Review)
+
+These items are model fields, properties, or public API components that may be used externally even if not referenced internally.
+
+#### 1. Model Configuration and Properties
+
+| File | Line | Item | Type | Tool | Risk Assessment |
+|------|------|------|------|------|-----------------|
+| `src/local_openai2anthropic/config.py` | 15 | `model_config` | Class variable | vulture (60%) | **HIGH RISK** - Pydantic Settings configuration. Required by pydantic-settings. |
+| `src/local_openai2anthropic/config.py` | 52 | `openai_auth_headers` | Property | vulture (60%) | **HIGH RISK** - Public property that may be used by external code. Verify usage before removal. |
+
+#### 2. TypedDict Fields (May be Required for API Compatibility)
+
+| File | Line | Field | Parent Class | Tool | Risk Assessment |
+|------|------|-------|--------------|------|-----------------|
+| `src/local_openai2anthropic/openai_types.py` | 20 | `description` | `ChatCompletionToolFunction` | vulture (60%) | **HIGH RISK** - TypedDict field for OpenAI API compatibility. |
+| `src/local_openai2anthropic/openai_types.py` | 21 | `parameters` | `ChatCompletionToolFunction` | vulture (60%) | **HIGH RISK** - TypedDict field for OpenAI API compatibility. |
+| `src/local_openai2anthropic/openai_types.py` | 41 | `stop` | `CompletionCreateParams` | vulture (60%) | **HIGH RISK** - TypedDict field for OpenAI API compatibility. |
+| `src/local_openai2anthropic/openai_types.py` | 44 | `stream_options` | `CompletionCreateParams` | vulture (60%) | **HIGH RISK** - TypedDict field for OpenAI API compatibility. |
+| `src/local_openai2anthropic/openai_types.py` | 46 | `chat_template_kwargs` | `CompletionCreateParams` | vulture (60%) | **HIGH RISK** - TypedDict field for vLLM/SGLang compatibility. |
+
+#### 3. Pydantic Model Fields (Default Values)
+
+| File | Line | Field | Parent Class | Tool | Risk Assessment |
+|------|------|-------|--------------|------|-----------------|
+| `src/local_openai2anthropic/openai_types.py` | 80 | `index` | `Choice` | vulture (60%) | **MEDIUM RISK** - Model field with default value. May be used in serialization. |
+| `src/local_openai2anthropic/openai_types.py` | 95 | `index` | `ChatCompletionDeltaToolCall` | vulture (60%) | **MEDIUM RISK** - Model field with default value. |
+| `src/local_openai2anthropic/openai_types.py` | 114 | `index` | `StreamingChoice` | vulture (60%) | **MEDIUM RISK** - Model field with default value. |
+| `src/local_openai2anthropic/openai_types.py` | 135 | `created` | `ChatCompletion` | vulture (60%) | **MEDIUM RISK** - Model field. Required for OpenAI API compatibility. |
+| `src/local_openai2anthropic/openai_types.py` | 146 | `created` | `ChatCompletionChunk` | vulture (60%) | **MEDIUM RISK** - Model field. Required for OpenAI API compatibility. |
+
+#### 4. Unused Classes
+
+| File | Line | Class | Tool | Risk Assessment |
+|------|------|-------|------|-----------------|
+| `src/local_openai2anthropic/openai_types.py` | 141 | `ChatCompletionChunk` | vulture (60%) | **HIGH RISK** - Public Pydantic model. May be imported by external code. |
+
+#### 5. Protocol Model Fields (Web Search Tool Types)
+
+| File | Line | Field | Parent Class | Tool | Risk Assessment |
+|------|------|-------|--------------|------|-----------------|
+| `src/local_openai2anthropic/protocol.py` | 77 | `city` | `ApproximateLocation` | vulture (60%) | **MEDIUM RISK** - Optional field for web search location. |
+| `src/local_openai2anthropic/protocol.py` | 78 | `region` | `ApproximateLocation` | vulture (60%) | **MEDIUM RISK** - Optional field for web search location. |
+| `src/local_openai2anthropic/protocol.py` | 79 | `country` | `ApproximateLocation` | vulture (60%) | **MEDIUM RISK** - Optional field with default. |
+| `src/local_openai2anthropic/protocol.py` | 80 | `timezone` | `ApproximateLocation` | vulture (60%) | **MEDIUM RISK** - Optional field for web search location. |
+| `src/local_openai2anthropic/protocol.py` | 89 | `allowed_domains` | `WebSearchToolDefinition` | vulture (60%) | **MEDIUM RISK** - Optional field for domain filtering. |
+| `src/local_openai2anthropic/protocol.py` | 90 | `blocked_domains` | `WebSearchToolDefinition` | vulture (60%) | **MEDIUM RISK** - Optional field for domain filtering. |
+| `src/local_openai2anthropic/protocol.py` | 91 | `user_location` | `WebSearchToolDefinition` | vulture (60%) | **MEDIUM RISK** - Optional field for location context. |
+| `src/local_openai2anthropic/protocol.py` | 148 | `web_search_requests` | `ServerToolUseUsage` | vulture (60%) | **MEDIUM RISK** - Usage tracking field. |
+| `src/local_openai2anthropic/protocol.py` | 158 | `server_tool_use` | `UsageWithServerToolUse` | vulture (60%) | **MEDIUM RISK** - Usage tracking field. |
+
+---
+
+## Test File Analysis
+
+The test files contain many mock-related unused attributes. These are typically false positives because:
+
+1. **Mock return_value assignments** - Used to configure mock behavior even if not directly referenced
+2. **Mock side_effect assignments** - Configure mock behavior
+3. **Test fixtures** - May be used indirectly by pytest
+
+### Test File Recommendations
+
+| File | Issue Count | Recommendation |
+|------|-------------|----------------|
+| `test_daemon.py` | 4 | Review mock configurations - likely false positives |
+| `test_daemon_advanced.py` | 5 | Review mock configurations - likely false positives |
+| `test_daemon_runner.py` | 8 | Remove unused `datetime` import; review mocks |
+| `test_main.py` | 14 | Review mock configurations - likely false positives |
+| `test_router_comprehensive.py` | 7 | Remove unused imports; review helper functions |
+| `test_router_edge_cases.py` | 2 | Review mock configurations |
+| `test_router_streaming.py` | 6 | Remove unused imports; review helper functions |
+| `test_server_tools.py` | 13 | Review test fixtures - `cls` in `@classmethod` is required |
+| `test_tavily_client.py` | 14 | Review mock configurations - likely false positives |
+
+**Note:** The `cls` variable in `@classmethod` decorators is a false positive - it's required by Python even if not explicitly used.
+
+---
+
+## Recommendations
+
+### Immediate Actions (SAFE)
+
+1. **Remove unused imports:**
+   ```python
+   # In converter.py - Remove lines 18-22 and 26
+   from openai.types.chat import ChatCompletionChunk  # REMOVE
+   from local_openai2anthropic.server_tools import ServerToolRegistry  # REMOVE
+   ```
+
+2. **Remove unused variable assignments:**
+   ```python
+   # In converter.py line 297
+   is_error = getattr(block, "is_error", False)  # REMOVE or use
+   ```
+
+3. **Fix f-strings without placeholders:**
+   ```python
+   # Change f"..." to "..." where no placeholders exist
+   ```
+
+4. **Clean up test file imports** as listed above
+
+### Cautionary Actions (CAUTION)
+
+1. **Verify API endpoint functions** in `router.py`:
+   - Check if `create_message`, `list_models`, `count_tokens`, `health_check` are registered as routes
+   - If not registered, they can be removed
+
+2. **Review exception handlers** in `main.py`:
+   - Verify if they're registered with FastAPI's exception handlers
+   - If not registered, they can be removed
+
+### Do Not Remove (DANGER)
+
+1. **Pydantic model fields** - Required for API compatibility
+2. **TypedDict fields** - Define API contract
+3. **Config properties** - May be used externally
+4. **Web search tool type fields** - Part of feature implementation
+
+---
+
+## Verification Commands
+
+Before removing any code, verify with these commands:
+
+```bash
+# Check if a function is referenced anywhere
+grep -r "function_name" --include="*.py" .
+
+# Check for dynamic imports
+grep -r "importlib\|__import__\|import_module" --include="*.py" .
+
+# Check for string-based references (common in web frameworks)
+grep -r "\"create_message\"\|'create_message'" --include="*.py" .
+
+# Run tests after changes
+pytest tests/ -v
+
+# Check for import errors
+python -c "from local_openai2anthropic import *"
+```
+
+---
+
+## Appendix: Tool Configuration
+
+### Vulture
+```bash
+vulture src/ tests/ --min-confidence 60
+```
+
+### Pylint
+```bash
+pylint src/ --disable=all --enable=W0611,W0613,W0614,W1300,W1301,W1302,W1303,W1304,W1305,W1306,W1307,W1401,W1404,W1405,W1505
+```
+
+### Ruff
+```bash
+ruff check src/ tests/ --select F401,F541,F841
+```
+
+---
+
+## Changelog
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2026-02-03 | 1.0 | Initial analysis report |
+
+---
+
+**Report Generated By:** Claude Code Dead Code Analysis Agent
+**Disclaimer:** This report is generated by automated tools and requires human review before any code deletion. Always verify findings with grep searches and run the full test suite before removing code.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: local-openai2anthropic
-Version: 0.2.9
+Version: 0.3.6
 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,6 +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: uvicorn[standard]>=0.23.0
 Provides-Extra: dev
 Requires-Dist: black>=23.0.0; extra == 'dev'

{local_openai2anthropic-0.2.9 → local_openai2anthropic-0.3.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "local-openai2anthropic"
-version = "0.2.9"
+version = "0.3.6"
 description = "A lightweight proxy server that converts Anthropic Messages API to OpenAI API"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -29,6 +29,7 @@ dependencies = [
     "pydantic-settings>=2.0.0",
     "anthropic>=0.30.0",
     "openai>=1.30.0",
+    "tomli>=2.0.0; python_version<'3.11'",
 ]
 
 [project.optional-dependencies]

{local_openai2anthropic-0.2.9 → local_openai2anthropic-0.3.6}/src/local_openai2anthropic/__init__.py

@@ -3,7 +3,7 @@
 local-openai2anthropic: A proxy server that converts Anthropic Messages API to OpenAI API.
 """
 
-__version__ = "0.2.5"
+__version__ = "0.3.6"
 
 from local_openai2anthropic.protocol import (
     AnthropicError,

local_openai2anthropic-0.3.6/src/local_openai2anthropic/config.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: Apache-2.0
+"""
+Configuration settings for the proxy server.
+"""
+
+import sys
+from functools import lru_cache
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+
+def get_config_dir() -> Path:
+    """Get platform-specific config directory.
+
+    Returns:
+        Path to the config directory (~/.oa2a)
+    """
+    return Path.home() / ".oa2a"
+
+
+def get_config_file() -> Path:
+    """Get config file path.
+
+    Returns:
+        Path to the config file (~/.oa2a/config.toml)
+    """
+    return get_config_dir() / "config.toml"
+
+
+def create_default_config() -> bool:
+    """Create default config file if not exists.
+
+    Returns:
+        True if a new config file was created, False if it already exists
+    """
+    config_file = get_config_file()
+    if config_file.exists():
+        return False
+
+    config_dir = get_config_dir()
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Set restrictive permissions (0o600) for the config directory on Unix-like systems
+    if sys.platform != "win32":
+        config_dir.chmod(0o700)
+
+    default_config = """# OA2A Configuration File
+# Place this file at ~/.oa2a/config.toml
+
+# OpenAI API Configuration
+openai_api_key = ""
+openai_base_url = "https://api.openai.com/v1"
+openai_org_id = ""
+openai_project_id = ""
+
+# Server Configuration
+host = "0.0.0.0"
+port = 8080
+request_timeout = 300.0
+
+# API Key for authenticating requests to this server (optional)
+api_key = ""
+
+# CORS settings
+cors_origins = ["*"]
+cors_credentials = true
+cors_methods = ["*"]
+cors_headers = ["*"]
+
+# Logging
+log_level = "INFO"
+log_dir = ""  # Empty uses platform-specific default
+
+# Tavily Web Search Configuration
+tavily_api_key = ""
+tavily_timeout = 30.0
+tavily_max_results = 5
+websearch_max_uses = 5
+"""
+    config_file.write_text(default_config, encoding="utf-8")
+
+    # Set restrictive permissions (0o600) for the config file on Unix-like systems
+    if sys.platform != "win32":
+        config_file.chmod(0o600)
+
+    return True
+
+
+def load_config_from_file() -> dict:
+    """Load configuration from TOML file.
+
+    Returns:
+        Dictionary containing configuration values, empty dict if file doesn't exist
+    """
+    if sys.version_info >= (3, 11):
+        import tomllib
+    else:
+        import tomli as tomllib
+
+    config_file = get_config_file()
+    if not config_file.exists():
+        return {}
+    with open(config_file, "rb") as f:
+        return tomllib.load(f)
+
+
+class Settings(BaseModel):
+    """Application settings loaded from config file."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    # OpenAI API Configuration
+    openai_api_key: Optional[str] = None
+    openai_base_url: str = "https://api.openai.com/v1"
+    openai_org_id: Optional[str] = None
+    openai_project_id: Optional[str] = None
+
+    # Server Configuration
+    host: str = "0.0.0.0"
+    port: int = 8080
+    request_timeout: float = 300.0  # 5 minutes
+
+    # API Key for authenticating requests to this server (optional)
+    api_key: Optional[str] = None
+
+    # CORS settings
+    cors_origins: list[str] = ["*"]
+    cors_credentials: bool = True
+    cors_methods: list[str] = ["*"]
+    cors_headers: list[str] = ["*"]
+
+    # Logging
+    log_level: str = "INFO"
+    log_dir: str = ""  # Empty means use platform-specific default
+
+    # Tavily Web Search Configuration
+    tavily_api_key: Optional[str] = None
+    tavily_timeout: float = 30.0
+    tavily_max_results: int = 5
+    websearch_max_uses: int = 5  # Default max_uses per request
+
+    @property
+    def openai_auth_headers(self) -> dict[str, str]:
+        """Get OpenAI authentication headers."""
+        headers = {
+            "Authorization": f"Bearer {self.openai_api_key}",
+        }
+        if self.openai_org_id:
+            headers["OpenAI-Organization"] = self.openai_org_id
+        if self.openai_project_id:
+            headers["OpenAI-Project"] = self.openai_project_id
+        return headers
+
+    @classmethod
+    def from_toml(cls) -> "Settings":
+        """Load settings from TOML config file.
+
+        Returns:
+            Settings instance populated from config file
+        """
+        config_data = load_config_from_file()
+        return cls(**config_data)
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings instance.
+
+    Creates default config file if it doesn't exist and notifies the user.
+
+    Returns:
+        Settings instance loaded from config file
+    """
+    created = create_default_config()
+    if created:
+        config_file = get_config_file()
+        print(f"Created default config file: {config_file}")
+        print("Please edit it to add your API keys and settings.")
+    return Settings.from_toml()