# CC-Balancer
Intelligent proxy for Claude Code with automatic failover, load balancing, and cost optimization across multiple API providers.
## Features
**Phase 1 (Current - MVP Foundation)**
- ✅ FastAPI-based async proxy server
- ✅ Pydantic v2 configuration with YAML support
- ✅ Environment variable expansion (`${VAR_NAME}`)
- ✅ Multiple routing strategies (round-robin, weighted)
- ✅ API key authentication
- ✅ Basic health check endpoint
- ✅ Provider abstraction layer
**Coming Soon**
- 🔄 Health monitoring with automatic failover (Phase 3)
- 📊 Prometheus metrics and structured logging (Phase 5)
- 🔒 OAuth 2.0 support (Phase 6)
- 💾 Request deduplication cache (Phase 4)
- 🎛️ Admin API for dynamic configuration (Phase 8)
## Quick Start
### Installation
1. **Clone the repository**
```bash
git clone <repository-url>
cd CC-B
```
2. **Install dependencies**
```bash
# Using pip
pip install -e .
# Or using uv (recommended)
uv pip install -e .
# Install development dependencies
pip install -e ".[dev]"
```
3. **Configure providers**
```bash
# Copy example environment file
cp .env.example .env
# Edit .env and add your API keys
nano .env
```
4. **Review configuration**
```bash
# Edit config.yaml to adjust provider settings
nano config.yaml
```
### Running the Server
```bash
# Start the server
cc-balancer
# Or with custom config
cc-balancer --config /path/to/config.yaml
# Development mode with auto-reload
cc-balancer --reload
# Custom host and port
cc-balancer --host 127.0.0.1 --port 8080
```
The server will start on `http://0.0.0.0:8000` by default.
### config Claude Code
```
# 配置环境变量
export ANTHROPIC_BASE_URL=http://localhost:8000
```
### Testing the Setup
```bash
# Check health
curl http://localhost:8000/healthz
# Test proxy (requires valid API key in config)
curl "http://localhost:8000/v1/messages" \
-H "x-api-key: sk-xxxx" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, Claude"}
]
}'
respose example:
{"model":"claude-sonnet-4-20250514","id":"msg_0198XFCY8VW5cq131jNsJptD","type":"message","role":"assistant","content":[{"type":"text","text":"Hello! It's nice to meet you. How are you doing today? Is there anything I can help you with or would you like to chat about something in particular?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"cache_creation":{"ephemeral_5m_input_tokens":0,"ephemeral_1h_input_tokens":0},"output_tokens":37,"service_tier":"standard"}}
```
### API Documentation
FastAPI provides automatic interactive documentation:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
## Configuration
Configuration is managed through `config.yaml` with environment variable support.
### Example Configuration
```yaml
server:
host: "0.0.0.0"
port: 8000
log_level: "INFO"
routing:
strategy: "weighted" # or "round-robin"
providers:
- name: "anthropic-primary"
base_url: "https://api.anthropic.com"
auth_type: "api_key"
api_key: "${ANTHROPIC_API_KEY}"
weight: 2 # Receives 2x traffic
priority: 1
```
### Environment Variables
Set in `.env` file or export directly:
```bash
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
export ANTHROPIC_BACKUP_KEY="sk-ant-backup-key-here"
```
## Architecture
### Components
- **Router Engine**: Intelligent request routing with configurable strategies
- **Provider Abstraction**: Unified interface for different authentication types
- **Config Loader**: YAML-based configuration with validation
- **Health Monitor**: (Coming in Phase 3) Provider health tracking
### Routing Strategies
**Round-Robin**: Equal distribution across all providers
```yaml
routing:
strategy: "round-robin"
```
**Weighted**: Distribution based on provider weights
```yaml
routing:
strategy: "weighted"
providers:
- name: "primary"
weight: 3 # Gets 75% of traffic
- name: "backup"
weight: 1 # Gets 25% of traffic
```
## Development
### Setup Development Environment
```bash
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=cc_balancer --cov-report=html
# Type checking
mypy cc_balancer
# Code formatting
black cc_balancer tests
ruff check cc_balancer tests
```
### Project Structure
```
CC-B/
├── cc_balancer/ # Main package
│ ├── __init__.py
│ ├── main.py # FastAPI application
│ ├── config.py # Pydantic models
│ ├── config_loader.py # YAML config loading
│ ├── router.py # Routing strategies
│ └── providers.py # Provider abstraction
├── tests/ # Test suite
├── config.yaml # Configuration
├── pyproject.toml # Package metadata
└── README.md
```
### Running Tests
```bash
# Run all tests
pytest
# Run specific test file
pytest tests/test_router.py
# Run with verbose output
pytest -v
# Run with coverage report
pytest --cov=cc_balancer --cov-report=term-missing
```
## Roadmap
### Phase 1: Foundation ✅ (Current)
- FastAPI skeleton + Pydantic models
- YAML config loading
- Basic health endpoint
- Round-robin routing
### Phase 2: Provider Abstraction ✅ (Current)
- Provider abstract base class
- APIKeyProvider implementation
- ProviderRegistry
### Phase 3: Health & Failover (Next)
- HealthMonitor with failure tracking
- Circuit breaker logic
- Background health checks
- Automatic failover
### Phase 4: Advanced Features
- Request deduplication cache
- Weighted routing optimization
- OAuth provider (deferred to Phase 6)
### Phase 5: Observability
- Prometheus metrics
- Structured JSON logging
- Performance tracking
### Phase 6: OAuth Support
- OAuth 2.0 flow implementation
- Token management
## Performance
**Target Metrics** (to be validated in Phase 9):
- Proxy latency overhead: <50ms (p95)
- Concurrent requests: 100+ without degradation
- Memory usage: <512MB under normal load
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and type checking
5. Submit a pull request
## License
MIT License - See LICENSE file for details
## Support
- Documentation: [GitHub README](https://github.com/yourusername/cc-balancer)
- Issues: [GitHub Issues](https://github.com/yourusername/cc-balancer/issues)
Raw data
{
"_id": null,
"home_page": null,
"name": "cc-balancer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "proxy, load-balancer, fastapi, claude, ai",
"author": "CC-Balancer Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/77/1b/9e3b1329861987895e5582dbf00ca83fba36313e6632eefb41cf81e46bfb/cc_balancer-0.1.1.tar.gz",
"platform": null,
"description": "# CC-Balancer\n\nIntelligent proxy for Claude Code with automatic failover, load balancing, and cost optimization across multiple API providers.\n\n## Features\n\n**Phase 1 (Current - MVP Foundation)**\n- \u2705 FastAPI-based async proxy server\n- \u2705 Pydantic v2 configuration with YAML support\n- \u2705 Environment variable expansion (`${VAR_NAME}`)\n- \u2705 Multiple routing strategies (round-robin, weighted)\n- \u2705 API key authentication\n- \u2705 Basic health check endpoint\n- \u2705 Provider abstraction layer\n\n**Coming Soon**\n- \ud83d\udd04 Health monitoring with automatic failover (Phase 3)\n- \ud83d\udcca Prometheus metrics and structured logging (Phase 5)\n- \ud83d\udd12 OAuth 2.0 support (Phase 6)\n- \ud83d\udcbe Request deduplication cache (Phase 4)\n- \ud83c\udf9b\ufe0f Admin API for dynamic configuration (Phase 8)\n\n## Quick Start\n\n### Installation\n\n1. **Clone the repository**\n```bash\ngit clone <repository-url>\ncd CC-B\n```\n\n2. **Install dependencies**\n```bash\n# Using pip\npip install -e .\n\n# Or using uv (recommended)\nuv pip install -e .\n\n# Install development dependencies\npip install -e \".[dev]\"\n```\n\n3. **Configure providers**\n```bash\n# Copy example environment file\ncp .env.example .env\n\n# Edit .env and add your API keys\nnano .env\n```\n\n4. **Review configuration**\n```bash\n# Edit config.yaml to adjust provider settings\nnano config.yaml\n```\n\n### Running the Server\n\n```bash\n# Start the server\ncc-balancer\n\n# Or with custom config\ncc-balancer --config /path/to/config.yaml\n\n# Development mode with auto-reload\ncc-balancer --reload\n\n# Custom host and port\ncc-balancer --host 127.0.0.1 --port 8080\n```\n\nThe server will start on `http://0.0.0.0:8000` by default.\n\n### config Claude Code\n```\n# \u914d\u7f6e\u73af\u5883\u53d8\u91cf\nexport ANTHROPIC_BASE_URL=http://localhost:8000\n```\n\n### Testing the Setup\n\n```bash\n# Check health\ncurl http://localhost:8000/healthz\n\n# Test proxy (requires valid API key in config)\ncurl \"http://localhost:8000/v1/messages\" \\\n -H \"x-api-key: sk-xxxx\" \\\n -H \"anthropic-version: 2023-06-01\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"claude-sonnet-4-20250514\",\n \"max_tokens\": 1024,\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Hello, Claude\"}\n ]\n }'\n\nrespose example:\n{\"model\":\"claude-sonnet-4-20250514\",\"id\":\"msg_0198XFCY8VW5cq131jNsJptD\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"text\",\"text\":\"Hello! It's nice to meet you. How are you doing today? Is there anything I can help you with or would you like to chat about something in particular?\"}],\"stop_reason\":\"end_turn\",\"stop_sequence\":null,\"usage\":{\"input_tokens\":10,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0,\"cache_creation\":{\"ephemeral_5m_input_tokens\":0,\"ephemeral_1h_input_tokens\":0},\"output_tokens\":37,\"service_tier\":\"standard\"}} \n```\n\n### API Documentation\n\nFastAPI provides automatic interactive documentation:\n- Swagger UI: http://localhost:8000/docs\n- ReDoc: http://localhost:8000/redoc\n\n## Configuration\n\nConfiguration is managed through `config.yaml` with environment variable support.\n\n### Example Configuration\n\n```yaml\nserver:\n host: \"0.0.0.0\"\n port: 8000\n log_level: \"INFO\"\n\nrouting:\n strategy: \"weighted\" # or \"round-robin\"\n\nproviders:\n - name: \"anthropic-primary\"\n base_url: \"https://api.anthropic.com\"\n auth_type: \"api_key\"\n api_key: \"${ANTHROPIC_API_KEY}\"\n weight: 2 # Receives 2x traffic\n priority: 1\n```\n\n### Environment Variables\n\nSet in `.env` file or export directly:\n```bash\nexport ANTHROPIC_API_KEY=\"sk-ant-your-key-here\"\nexport ANTHROPIC_BACKUP_KEY=\"sk-ant-backup-key-here\"\n```\n\n## Architecture\n\n### Components\n\n- **Router Engine**: Intelligent request routing with configurable strategies\n- **Provider Abstraction**: Unified interface for different authentication types\n- **Config Loader**: YAML-based configuration with validation\n- **Health Monitor**: (Coming in Phase 3) Provider health tracking\n\n### Routing Strategies\n\n**Round-Robin**: Equal distribution across all providers\n```yaml\nrouting:\n strategy: \"round-robin\"\n```\n\n**Weighted**: Distribution based on provider weights\n```yaml\nrouting:\n strategy: \"weighted\"\n\nproviders:\n - name: \"primary\"\n weight: 3 # Gets 75% of traffic\n - name: \"backup\"\n weight: 1 # Gets 25% of traffic\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=cc_balancer --cov-report=html\n\n# Type checking\nmypy cc_balancer\n\n# Code formatting\nblack cc_balancer tests\nruff check cc_balancer tests\n```\n\n### Project Structure\n\n```\nCC-B/\n\u251c\u2500\u2500 cc_balancer/ # Main package\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 main.py # FastAPI application\n\u2502 \u251c\u2500\u2500 config.py # Pydantic models\n\u2502 \u251c\u2500\u2500 config_loader.py # YAML config loading\n\u2502 \u251c\u2500\u2500 router.py # Routing strategies\n\u2502 \u2514\u2500\u2500 providers.py # Provider abstraction\n\u251c\u2500\u2500 tests/ # Test suite\n\u251c\u2500\u2500 config.yaml # Configuration\n\u251c\u2500\u2500 pyproject.toml # Package metadata\n\u2514\u2500\u2500 README.md\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run specific test file\npytest tests/test_router.py\n\n# Run with verbose output\npytest -v\n\n# Run with coverage report\npytest --cov=cc_balancer --cov-report=term-missing\n```\n\n## Roadmap\n\n### Phase 1: Foundation \u2705 (Current)\n- FastAPI skeleton + Pydantic models\n- YAML config loading\n- Basic health endpoint\n- Round-robin routing\n\n### Phase 2: Provider Abstraction \u2705 (Current)\n- Provider abstract base class\n- APIKeyProvider implementation\n- ProviderRegistry\n\n### Phase 3: Health & Failover (Next)\n- HealthMonitor with failure tracking\n- Circuit breaker logic\n- Background health checks\n- Automatic failover\n\n### Phase 4: Advanced Features\n- Request deduplication cache\n- Weighted routing optimization\n- OAuth provider (deferred to Phase 6)\n\n### Phase 5: Observability\n- Prometheus metrics\n- Structured JSON logging\n- Performance tracking\n\n### Phase 6: OAuth Support\n- OAuth 2.0 flow implementation\n- Token management\n\n## Performance\n\n**Target Metrics** (to be validated in Phase 9):\n- Proxy latency overhead: <50ms (p95)\n- Concurrent requests: 100+ without degradation\n- Memory usage: <512MB under normal load\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Run tests and type checking\n5. Submit a pull request\n\n## License\n\nMIT License - See LICENSE file for details\n\n## Support\n\n- Documentation: [GitHub README](https://github.com/yourusername/cc-balancer)\n- Issues: [GitHub Issues](https://github.com/yourusername/cc-balancer/issues)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Intelligent proxy for Claude Code with automatic failover and load balancing",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/yourusername/cc-balancer#readme",
"Homepage": "https://github.com/yourusername/cc-balancer",
"Issues": "https://github.com/yourusername/cc-balancer/issues",
"Repository": "https://github.com/yourusername/cc-balancer"
},
"split_keywords": [
"proxy",
" load-balancer",
" fastapi",
" claude",
" ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ab2ecbd29a81cd729c7b6393421919199684a7f996735e09189f456e4428ba28",
"md5": "a588a49c242eb585cc6499ca9d219474",
"sha256": "5f07d89b22e85fafc2adbc300165d02579eb81fac76d9c75726b5417a010108f"
},
"downloads": -1,
"filename": "cc_balancer-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a588a49c242eb585cc6499ca9d219474",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 112415,
"upload_time": "2025-10-21T05:47:08",
"upload_time_iso_8601": "2025-10-21T05:47:08.956493Z",
"url": "https://files.pythonhosted.org/packages/ab/2e/cbd29a81cd729c7b6393421919199684a7f996735e09189f456e4428ba28/cc_balancer-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "771b9e3b1329861987895e5582dbf00ca83fba36313e6632eefb41cf81e46bfb",
"md5": "7c8654ab2583850372587c959a878f55",
"sha256": "9a61ea8b638f4292de1c7e84102ec6e55581149b6f3ef6622b604844a3130d94"
},
"downloads": -1,
"filename": "cc_balancer-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7c8654ab2583850372587c959a878f55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 120135,
"upload_time": "2025-10-21T05:47:10",
"upload_time_iso_8601": "2025-10-21T05:47:10.942595Z",
"url": "https://files.pythonhosted.org/packages/77/1b/9e3b1329861987895e5582dbf00ca83fba36313e6632eefb41cf81e46bfb/cc_balancer-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 05:47:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "cc-balancer#readme",
"github_not_found": true,
"lcname": "cc-balancer"
}
JSON
