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

ccproxy_api-0.1.6.dist-info/METADATA

@@ -1,615 +0,0 @@
-Metadata-Version: 2.4
-Name: ccproxy-api
-Version: 0.1.6
-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.19
-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: pyjwt>=2.10.1
-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 that provides unified access to multiple AI providers through a single interface. It supports both Anthropic Claude and OpenAI Codex backends, allowing you to use your existing subscriptions without separate API key billing.
-
-## Supported Providers
-
-### Anthropic Claude
-
-Access Claude via your Claude Max subscription at `api.anthropic.com/v1/messages`.
-
-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.
-
-### OpenAI Codex Response API (Experimental)
-
-Access OpenAI's [Response API](https://platform.openai.com/docs/api-reference/responses) via your ChatGPT Plus subscription. This provides programmatic access to ChatGPT models through the `chatgpt.com/backend-api/codex` endpoint.
-
-- **Response API (`/codex/responses`):** Direct reverse proxy to ChatGPT backend for conversation responses
-- **Session Management:** Supports both auto-generated and persistent session IDs for conversation continuity
-- **OpenAI OAuth:** Uses the same OAuth2 PKCE authentication flow as the official Codex CLI
-- **ChatGPT Plus Required:** Requires an active ChatGPT Plus subscription for API access
-- **Instruction Prompt:** Automatically injects the Codex instruction prompt into conversations
-
-The server 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 different authentication mechanisms depending on the provider and mode.
-
-### Claude Authentication
-
-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
-
-    ```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
-
-### OpenAI Codex Authentication (Experimental)
-
-The Codex Response API requires ChatGPT Plus subscription and OAuth2 authentication:
-
-```bash
-# Enable Codex provider
-ccproxy config codex --enable
-
-# Authentication options:
-
-# Option 1: Use existing Codex CLI credentials (if available)
-# CCProxy will automatically detect and use valid credentials from:
-# - $HOME/.codex/auth.json (Codex CLI credentials)
-# - Automatically renews tokens if expired but refresh token is valid
-
-# Option 2: Login via CCProxy CLI (opens browser)
-ccproxy auth login-openai
-
-# Option 3: Use the official Codex CLI
-codex auth login
-
-# Check authentication status for all providers
-ccproxy auth status
-```
-
-**Important Notes:**
-
-- Credentials are stored in `$HOME/.codex/auth.json`
-- CCProxy reuses existing Codex CLI credentials when available
-- If credentials are expired, CCProxy attempts automatic renewal
-- Without valid credentials, users must authenticate using either CCProxy or Codex CLI
-
-### Authentication Status
-
-You can check the status of all credentials with:
-
-```bash
-ccproxy auth status       # All providers
-ccproxy auth validate     # Claude only
-ccproxy auth info         # Claude only
-```
-
-Warning is shown on startup 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 Claude (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 Claude (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"
-```
-
-**For OpenAI Codex Response API:**
-
-```bash
-# Create a new conversation response (auto-generated session)
-curl -X POST http://localhost:8000/codex/responses \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "gpt-5",
-    "messages": [
-      {"role": "user", "content": "Hello, can you help me with Python?"}
-    ]
-  }'
-
-# Continue conversation with persistent session ID
-curl -X POST http://localhost:8000/codex/my_session_123/responses \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "gpt-5",
-    "messages": [
-      {"role": "user", "content": "Show me an example of async/await"}
-    ]
-  }'
-
-# Stream responses (SSE format)
-curl -X POST http://localhost:8000/codex/responses \
-  -H "Content-Type: application/json" \
-  -d '{
-    "model": "gpt-5",
-    "messages": [{"role": "user", "content": "Explain quantum computing"}],
-    "stream": true
-  }'
-```
-
-**For OpenAI-compatible clients using Codex:**
-
-```yaml
-# Example aichat configuration (~/.config/aichat/config.yaml)
-clients:
-  - type: claude
-    api_base: http://127.0.0.1:8000/codex
-
-# Usage
-aichat --model openai:gpt-5 "hello"
-```
-
-**Important Codex Limitations:**
-
-- Limited model support (e.g., `gpt-5` works, others may not)
-- Many OpenAI parameters not supported (temperature, top_p, etc.)
-- Reasoning content appears in XML tags for capable models
-
-**Note:** The Codex instruction prompt is automatically injected into all conversations to maintain compatibility with the ChatGPT backend.
-
-### Codex Response API Details
-
-#### Session Management
-
-The Codex Response API supports flexible session management for conversation continuity:
-
-- **Auto-generated sessions**: `POST /codex/responses` - Creates a new session ID for each request
-- **Persistent sessions**: `POST /codex/{session_id}/responses` - Maintains conversation context across requests
-- **Header forwarding**: Optional `session_id` header for custom session tracking
-
-#### Instruction Prompt Injection
-
-**Important:** CCProxy automatically injects the Codex instruction prompt into every conversation. This is required for proper interaction with the ChatGPT backend but affects your token usage:
-
-- The instruction prompt is prepended to your messages
-- This consumes additional tokens in each request
-- The prompt ensures compatibility with ChatGPT's response generation
-- You cannot disable this injection as it's required by the backend
-
-#### Model Differences
-
-The Response API models differ from standard OpenAI API models:
-
-- Uses ChatGPT Plus models (e.g., `gpt-4`, `gpt-4-turbo`)
-- Model behavior matches ChatGPT web interface
-- Token limits and pricing follow ChatGPT Plus subscription terms
-- See [OpenAI Response API Documentation](https://platform.openai.com/docs/api-reference/responses) for details
-
-## 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
-```
-
-## Claude SDK Pool Mode
-
-CCProxy supports connection pooling for Claude Code SDK clients to improve request performance by maintaining a pool of pre-initialized Claude instances.
-
-### Benefits
-
-- **Reduced Latency**: Eliminates Claude Code startup overhead on each request
-- **Improved Performance**: Reuses established connections for faster response times
-- **Resource Efficiency**: Maintains a configurable pool size to balance performance and resource usage
-
-### Usage
-
-Pool mode is disabled by default and can be enabled using the CLI flag:
-
-```bash
-# Enable pool mode with default settings
-ccproxy --sdk-enable-pool
-
-# Configure pool size (default: 3)
-ccproxy --sdk-enable-pool --sdk-pool-size 5
-```
-
-### Limitations
-
-- **No Dynamic Options**: Pool instances cannot change Claude options (max_tokens, model, etc.) after initialization
-- **Shared Configuration**: All requests using the pool must use identical Claude configuration
-- **Memory Usage**: Each pool instance consumes additional memory
-
-Pool mode is most effective for high-frequency requests with consistent configuration requirements.
-
-## 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
-```
-
-### Using with OpenAI Codex
-
-For tools that support custom API bases, you can use the Codex provider. Note that this has significant limitations compared to Claude providers.
-
-**Example with aichat:**
-
-```yaml
-# ~/.config/aichat/config.yaml
-clients:
-  - type: claude
-    api_base: http://127.0.0.1:8000/codex
-```
-
-```bash
-# Usage with confirmed working model
-aichat --model openai:gpt-5 "hello"
-```
-
-**Codex Limitations:**
-
-- Only select models work (gpt-5 confirmed, others may fail)
-- No support for temperature, top_p, or most OpenAI parameters
-- When using reasoning models, reasoning appears as XML tags in output
-
-### `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 multiple prefixes for different providers and modes.
-
-### Claude Endpoints
-
-| 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 Format:**
-  - `POST /sdk/v1/messages`
-  - `POST /api/v1/messages`
-- **OpenAI-Compatible Format:**
-  - `POST /sdk/v1/chat/completions`
-  - `POST /api/v1/chat/completions`
-
-### OpenAI Codex Endpoints
-
-- **Response API:**
-  - `POST /codex/responses` - Create response with auto-generated session
-  - `POST /codex/{session_id}/responses` - Create response with persistent session
-  - `POST /codex/chat/completions` - OpenAI-compatible chat completions endpoint
-  - `POST /codex/v1/chat/completions` - Alternative OpenAI-compatible endpoint
-  - Supports streaming via SSE when `stream: true` is set
-  - See [Response API docs](https://platform.openai.com/docs/api-reference/responses)
-
-**Codex Chat Completions Limitations:**
-
-- **No Tool/Function Calling Support**: Tool use and function calling are not supported (use `/codex/responses` for tool calls)
-- **Limited Parameter Support**: Many OpenAI parameters (temperature, top_p, frequency_penalty, etc.) are not supported
-- **Restricted Model Support**: Only certain models work (e.g., `gpt-5` confirmed working, others may fail)
-- **No Custom System Prompts**: System messages and instructions are overridden by the required Codex instruction prompt
-- **Reasoning Mode**: GPT models with reasoning capabilities pass reasoning content between XML tags (`<reasoning>...</reasoning>`)
-- **Session Management**: Uses auto-generated sessions; persistent sessions require the `/codex/{session_id}/responses` endpoint
-- **ChatGPT Plus Required**: Requires active ChatGPT Plus subscription for access
-
-**Note**: The `/codex/responses` endpoint supports tool calling and more parameters, but specific feature availability depends on ChatGPT's backend - users should test individual capabilities.
-
-### Utility Endpoints
-
-- **Health & Status:**
-  - `GET /health`
-  - `GET /sdk/models`, `GET /api/models`
-  - `GET /sdk/status`, `GET /api/status`
-- **Authentication:**
-  - `GET /oauth/callback` - OAuth callback for both Claude and OpenAI
-- **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.  **OpenAI/Codex Authentication Failed:**
-    - Check if valid credentials exist: `ccproxy auth status`
-    - Ensure you have an active ChatGPT Plus subscription
-    - Try re-authenticating: `ccproxy auth login-openai` or `codex auth login`
-    - Verify credentials in `$HOME/.codex/auth.json`
-4.  **Codex Response API Errors:**
-    - "Instruction prompt injection failed": The backend requires the Codex prompt; this is automatic
-    - "Session not found": Use persistent session IDs for conversation continuity
-    - "Model not available": Ensure you're using ChatGPT Plus compatible models
-5.  **Missing API Auth Token:** If you've enabled security, include the token in your request headers.
-6.  **Port Already in Use:** Start the server on a different port: `ccproxy --port 8001`.
-7.  **Model Not Available:** Check that your 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