ccproxy-api 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

ccproxy_api-0.1.4.dist-info/METADATA

@@ -1,369 +0,0 @@
-Metadata-Version: 2.4
-Name: ccproxy-api
-Version: 0.1.4
-Summary: API server that provides an Anthropic and OpenAI compatible interface over Claude Code, allowing to use your Claude OAuth account or over the API.
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: aiofiles>=24.1.0
-Requires-Dist: aiosqlite>=0.21.0
-Requires-Dist: claude-code-sdk>=0.0.14
-Requires-Dist: duckdb-engine>=0.17.0
-Requires-Dist: duckdb>=1.1.0
-Requires-Dist: fastapi-mcp
-Requires-Dist: fastapi[standard]>=0.115.14
-Requires-Dist: httpx-sse>=0.4.1
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: jsonschema>=0.33.2
-Requires-Dist: keyring>=25.6.0
-Requires-Dist: openai>=1.93.0
-Requires-Dist: prometheus-client>=0.22.1
-Requires-Dist: pydantic-settings>=2.4.0
-Requires-Dist: pydantic>=2.8.0
-Requires-Dist: rich-toolkit>=0.14.8
-Requires-Dist: rich>=13.0.0
-Requires-Dist: sqlmodel>=0.0.24
-Requires-Dist: structlog>=25.4.0
-Requires-Dist: textual>=3.7.1
-Requires-Dist: tomli>=2.0.0; python_version < '3.11'
-Requires-Dist: typer>=0.16.0
-Requires-Dist: typing-extensions>=4.0.0
-Requires-Dist: uvicorn>=0.34.0
-Description-Content-Type: text/markdown
-
-# CCProxy API Server
-
-`ccproxy` is a local reverse proxy server for Anthropic Claude LLM at `api.anthropic.com/v1/messages`. It allows you to use your existing Claude Max subscription to interact with the Anthropic API, bypassing the need for separate API key billing.
-
-The server provides two primary modes of operation:
-*   **SDK Mode (`/sdk`):** Routes requests through the local `claude-code-sdk`. This enables access to tools configured in your Claude environment and includes an integrated MCP (Model Context Protocol) server for permission management.
-*   **API Mode (`/api`):** Acts as a direct reverse proxy, injecting the necessary authentication headers. This provides full access to the underlying API features and model settings.
-
-It includes a translation layer to support both Anthropic and OpenAI-compatible API formats for requests and responses, including streaming.
-
-## Installation
-
-```bash
-# The official claude-code CLI is required for SDK mode
-npm install -g @anthropic-ai/claude-code
-
-# run it with uv
-uvx ccproxy-api
-
-# run it with pipx
-pipx run ccproxy-api
-
-# install with uv
-uv tool install ccproxy-api
-
-# Install ccproxy with pip
-pipx install ccproxy-api
-
-# Optional: Enable shell completion
-eval "$(ccproxy --show-completion zsh)"  # For zsh
-eval "$(ccproxy --show-completion bash)" # For bash
-```
-
-
-For dev version replace `ccproxy-api` with `git+https://github.com/caddyglow/ccproxy-api.git@dev`
-
-## Authentication
-
-The proxy uses two different authentication mechanisms depending on the mode.
-
-1.  **Claude CLI (`sdk` mode):**
-    This mode relies on the authentication handled by the `claude-code-sdk`.
-    ```bash
-    claude /login
-    ```
-
-    It's also possible now to get a long live token to avoid renewing issues
-    using
-    ```sh
-    ```bash
-    claude setup-token`
-
-2.  **ccproxy (`api` mode):**
-    This mode uses its own OAuth2 flow to obtain credentials for direct API access.
-    ```bash
-    ccproxy auth login
-    ```
-
-    If you are already connected with Claude CLI the credentials should be found automatically
-
-You can check the status of these credentials with `ccproxy auth validate` and `ccproxy auth info`.
-
-Warning is show on start up if no credentials are setup.
-
-## Usage
-
-### Running the Server
-
-```bash
-# Start the proxy server
-ccproxy
-```
-The server will start on `http://127.0.0.1:8000` by default.
-
-### Client Configuration
-
-Point your existing tools and applications to the local proxy instance by setting the appropriate environment variables. A dummy API key is required by most client libraries but is not used by the proxy itself.
-
-**For OpenAI-compatible clients:**
-```bash
-# For SDK mode
-export OPENAI_BASE_URL="http://localhost:8000/sdk/v1"
-# For API mode
-export OPENAI_BASE_URL="http://localhost:8000/api/v1"
-
-export OPENAI_API_KEY="dummy-key"
-```
-
-**For Anthropic-compatible clients:**
-```bash
-# For SDK mode
-export ANTHROPIC_BASE_URL="http://localhost:8000/sdk"
-# For API mode
-export ANTHROPIC_BASE_URL="http://localhost:8000/api"
-
-export ANTHROPIC_API_KEY="dummy-key"
-```
-
-
-## MCP Server Integration & Permission System
-
-In SDK mode, CCProxy automatically configures an MCP (Model Context Protocol) server that provides permission checking tools for Claude Code. This enables interactive permission management for tool execution.
-
-### Permission Management
-
-**Starting the Permission Handler:**
-```bash
-# In a separate terminal, start the permission handler
-ccproxy permission-handler
-
-# Or with custom settings
-ccproxy permission-handler --host 127.0.0.1 --port 8000
-```
-
-The permission handler provides:
-- **Real-time Permission Requests**: Streams permission requests via Server-Sent Events (SSE)
-- **Interactive Approval/Denial**: Command-line interface for managing tool permissions
-- **Automatic MCP Integration**: Works seamlessly with Claude Code SDK tools
-
-**Working Directory Control:**
-Control which project the Claude SDK API can access using the `--cwd` flag:
-```bash
-# Set working directory for Claude SDK
-ccproxy --claude-code-options-cwd /path/to/your/project
-
-# Example with permission bypass and formatted output
-ccproxy --claude-code-options-cwd /tmp/tmp.AZyCo5a42N \
-        --claude-code-options-permission-mode bypassPermissions \
-        --claude-sdk-message-mode formatted
-
-# Alternative: Change to project directory and start ccproxy
-cd /path/to/your/project
-ccproxy
-```
-
-### Claude SDK Message Formatting
-
-CCProxy supports flexible message formatting through the `sdk_message_mode` configuration:
-
-- **`forward`** (default): Preserves original Claude SDK content blocks with full metadata
-- **`formatted`**: Converts content to XML tags with pretty-printed JSON data
-- **`ignore`**: Filters out Claude SDK-specific content entirely
-
-Configure via environment variables:
-```bash
-# Use formatted XML output
-CLAUDE__SDK_MESSAGE_MODE=formatted ccproxy
-
-# Use compact formatting without pretty-printing
-CLAUDE__PRETTY_FORMAT=false ccproxy
-```
-
-## Using with Aider
-
-CCProxy works seamlessly with Aider and other AI coding assistants:
-
-### Anthropic Mode
-```bash
-export ANTHROPIC_API_KEY=dummy
-export ANTHROPIC_BASE_URL=http://127.0.0.1:8000/api
-aider --model claude-sonnet-4-20250514
-```
-
-### OpenAI Mode with Model Mapping
-
-If your tool only supports OpenAI settings, ccproxy automatically maps OpenAI models to Claude:
-
-```bash
-export OPENAI_API_KEY=dummy
-export OPENAI_BASE_URL=http://127.0.0.1:8000/api/v1
-aider --model o3-mini
-```
-
-### API Mode (Direct Proxy)
-
-For minimal interference and direct API access:
-
-```bash
-export OPENAI_API_KEY=dummy
-export OPENAI_BASE_URL=http://127.0.0.1:8000/api/v1
-aider --model o3-mini
-```
-
-### `curl` Example
-
-```bash
-# SDK mode
-curl -X POST http://localhost:8000/sdk/v1/messages \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude-3-5-sonnet-20241022",
-    "messages": [{"role": "user", "content": "Hello!"}],
-    "max_tokens": 100
-  }'
-
-# API mode
-curl -X POST http://localhost:8000/api/v1/messages \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "claude-3-5-sonnet-20241022",
-    "messages": [{"role": "user", "content": "Hello!"}],
-    "max_tokens": 100
-  }'
-```
-More examples are available in the `examples/` directory.
-
-## Endpoints
-
-The proxy exposes endpoints under two prefixes, corresponding to its operating modes.
-
-| Mode | URL Prefix | Description | Use Case |
-|------|------------|-------------|----------|
-| **SDK** | `/sdk/` | Uses `claude-code-sdk` with its configured tools. | Accessing Claude with local tools. |
-| **API** | `/api/` | Direct proxy with header injection. | Full API control, direct access. |
-
-*   **Anthropic:**
-    *   `POST /sdk/v1/messages`
-    *   `POST /api/v1/messages`
-*   **OpenAI-Compatible:**
-    *   `POST /sdk/v1/chat/completions`
-    *   `POST /api/v1/chat/completions`
-*   **Utility:**
-    *   `GET /health`
-    *   `GET /sdk/models`, `GET /api/models`
-    *   `GET /sdk/status`, `GET /api/status`
-    *   `GET /oauth/callback`
-*   **MCP & Permissions:**
-    *   `POST /mcp/permission/check` - MCP permission checking endpoint
-    *   `GET /permissions/stream` - SSE stream for permission requests
-    *   `GET /permissions/{id}` - Get permission request details
-    *   `POST /permissions/{id}/respond` - Respond to permission request
-*   **Observability (Optional):**
-    *   `GET /metrics`
-    *   `GET /logs/status`, `GET /logs/query`
-    *   `GET /dashboard`
-
-## Supported Models
-
-CCProxy supports recent Claude models including Opus, Sonnet, and Haiku variants. The specific models available to you will depend on your Claude account and the features enabled for your subscription.
-
- * `claude-opus-4-20250514`
- * `claude-sonnet-4-20250514`
- * `claude-3-7-sonnet-20250219`
- * `claude-3-5-sonnet-20241022`
- * `claude-3-5-sonnet-20240620`
-
-## Configuration
-
-Settings can be configured through (in order of precedence):
-1. Command-line arguments
-2. Environment variables
-3. `.env` file
-4. TOML configuration files (`.ccproxy.toml`, `ccproxy.toml`, or `~/.config/ccproxy/config.toml`)
-5. Default values
-
-For complex configurations, you can use a nested syntax for environment variables with `__` as a delimiter:
-
-```bash
-# Server settings
-SERVER__HOST=0.0.0.0
-SERVER__PORT=8080
-# etc.
-```
-
-## Securing the Proxy (Optional)
-
-You can enable token authentication for the proxy. This supports multiple header formats (`x-api-key` for Anthropic, `Authorization: Bearer` for OpenAI) for compatibility with standard client libraries.
-
-**1. Generate a Token:**
-```bash
-ccproxy generate-token
-# Output: SECURITY__AUTH_TOKEN=abc123xyz789...
-```
-
-**2. Configure the Token:**
-```bash
-# Set environment variable
-export SECURITY__AUTH_TOKEN=abc123xyz789...
-
-# Or add to .env file
-echo "SECURITY__AUTH_TOKEN=abc123xyz789..." >> .env
-```
-
-**3. Use in Requests:**
-When authentication is enabled, include the token in your API requests.
-```bash
-# Anthropic Format (x-api-key)
-curl -H "x-api-key: your-token" ...
-
-# OpenAI/Bearer Format
-curl -H "Authorization: Bearer your-token" ...
-```
-
-## Observability
-
-`ccproxy` includes an optional but powerful observability suite for monitoring and analytics. When enabled, it provides:
-
-*   **Prometheus Metrics:** A `/metrics` endpoint for real-time operational monitoring.
-*   **Access Log Storage:** Detailed request logs, including token usage and costs, are stored in a local DuckDB database.
-*   **Analytics API:** Endpoints to query and analyze historical usage data.
-*   **Real-time Dashboard:** A live web interface at `/dashboard` to visualize metrics and request streams.
-
-These features are disabled by default and can be enabled via configuration. For a complete guide on setting up and using these features, see the [Observability Documentation](docs/observability.md).
-
-## Troubleshooting
-
-### Common Issues
-
-1.  **Authentication Error:** Ensure you're using the correct mode (`/sdk` or `/api`) for your authentication method.
-2.  **Claude Credentials Expired:** Run `ccproxy auth login` to refresh credentials for API mode. Run `claude /login` for SDK mode.
-3.  **Missing API Auth Token:** If you've enabled security, include the token in your request headers.
-4.  **Port Already in Use:** Start the server on a different port: `ccproxy --port 8001`.
-5.  **Model Not Available:** Check that your Claude subscription includes the requested model.
-
-## Contributing
-
-Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Documentation
-
-- **[Online Documentation](https://caddyglow.github.io/ccproxy-api)**
-- **[API Reference](https://caddyglow.github.io/ccproxy-api/api-reference/overview/)**
-- **[Developer Guide](https://caddyglow.github.io/ccproxy-api/developer-guide/architecture/)**
-
-## Support
-
-- Issues: [GitHub Issues](https://github.com/CaddyGlow/ccproxy-api/issues)
-- Documentation: [Project Documentation](https://caddyglow.github.io/ccproxy-api)
-
-## Acknowledgments
-
-- [Anthropic](https://anthropic.com) for Claude and the Claude Code SDK
-- The open-source community