feat: Initial commit

.env.example

@@ -0,0 +1,23 @@
+# Claude CLI Configuration
+CLAUDE_CLI_PATH=claude
+
+# API Configuration
+# If API_KEY is not set, server will prompt for interactive API key protection on startup
+# Leave commented out to enable interactive prompt, or uncomment to use a fixed API key
+# API_KEY=your-optional-api-key-here
+PORT=8000
+
+# Timeout Configuration (milliseconds)
+MAX_TIMEOUT=600000
+
+# CORS Configuration
+CORS_ORIGINS=["*"]
+
+# Rate Limiting Configuration
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_PER_MINUTE=30
+RATE_LIMIT_CHAT_PER_MINUTE=10
+RATE_LIMIT_DEBUG_PER_MINUTE=2
+RATE_LIMIT_AUTH_PER_MINUTE=10
+RATE_LIMIT_SESSION_PER_MINUTE=15
+RATE_LIMIT_HEALTH_PER_MINUTE=30

.github/workflows/claude-code-review.yml

@@ -0,0 +1,78 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+    
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+    
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+          
+          # Direct prompt for automated review (no @claude mention needed)
+          direct_prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+            
+            Be constructive and helpful in your feedback.
+
+          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          # use_sticky_comment: true
+          
+          # Optional: Customize review based on file types
+          # direct_prompt: |
+          #   Review this PR focusing on:
+          #   - For TypeScript files: Type safety and proper interface usage
+          #   - For API endpoints: Security, input validation, and error handling
+          #   - For React components: Performance, accessibility, and best practices
+          #   - For tests: Coverage, edge cases, and test quality
+          
+          # Optional: Different prompts for different authors
+          # direct_prompt: |
+          #   ${{ github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' && 
+          #   'Welcome! Please review this PR from a first-time contributor. Be encouraging and provide detailed explanations for any suggestions.' ||
+          #   'Please provide a thorough code review focusing on our coding standards and best practices.' }}
+          
+          # Optional: Add specific tools for running tests or linting
+          # allowed_tools: "Bash(npm run test),Bash(npm run lint),Bash(npm run typecheck)"
+          
+          # Optional: Skip review for certain conditions
+          # if: |
+          #   !contains(github.event.pull_request.title, '[skip-review]') &&
+          #   !contains(github.event.pull_request.title, '[WIP]')
+

.github/workflows/claude.yml

@@ -0,0 +1,65 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 20
+          # Let the Claude action handle PR checkout - just use default ref
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+          
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+          
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+          
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+          
+          # Optional: Allow Claude to run specific commands
+          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
+          
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+          
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test
+

.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.conda/
+.venv/
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Claude Code
+.claude/
+
+# Development documentation
+IMPLEMENTATION_PLAN.md
+CLAUDE.md
+PARAMETER_MAPPING.md
+IMPROVEMENT_PLAN.md
+
+# Debug and temporary test files
+debug_*.py
+test_debug_*.py
+test_performance_*.py
+test_user_*.py
+test_new_*.py
+test_roocode_compatibility.py

Dockerfile

@@ -0,0 +1,32 @@
+FROM python:3.12-slim
+
+# Install system deps for Node.js and general utils
+RUN apt-get update && apt-get install -y \
+    curl \
+    nodejs \
+    npm \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Poetry globally
+RUN curl -sSL https://install.python-poetry.org | python3 -
+
+# Add Poetry to PATH
+ENV PATH="/root/.local/bin:${PATH}"
+
+# Install Claude Code CLI globally (for SDK compatibility)
+RUN npm install -g @anthropic-ai/claude-code
+
+# Copy the app code
+COPY . /app
+
+# Set working directory
+WORKDIR /app
+
+# Install Python dependencies with Poetry
+RUN poetry install --no-root
+
+# Expose the port (default 8000)
+EXPOSE 8000
+
+# Run the app with Uvicorn (development mode with reload; switch to --no-reload for prod)
+CMD ["poetry", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

README.md

@@ -0,0 +1,757 @@
+# Claude Code OpenAI API Wrapper
+
+An OpenAI API-compatible wrapper for Claude Code, allowing you to use Claude Code with any OpenAI client library. **Now powered by the official Claude Code Python SDK** with enhanced authentication and features.
+
+## Status
+
+🎉 **Production Ready** - All core features working and tested:
+- ✅ Chat completions endpoint with **official Claude Code Python SDK**
+- ✅ Streaming and non-streaming responses  
+- ✅ Full OpenAI SDK compatibility
+- ✅ **Multi-provider authentication** (API key, Bedrock, Vertex AI, CLI auth)
+- ✅ **System prompt support** via SDK options
+- ✅ Model selection support with validation
+- ✅ **Fast by default** - Tools disabled for OpenAI compatibility (5-10x faster)
+- ✅ Optional tool usage (Read, Write, Bash, etc.) when explicitly enabled
+- ✅ **Real-time cost and token tracking** from SDK
+- ✅ **Session continuity** with conversation history across requests 🆕
+- ✅ **Session management endpoints** for full session control 🆕
+- ✅ Health, auth status, and models endpoints
+- ✅ **Development mode** with auto-reload
+
+## Features
+
+### 🔥 **Core API Compatibility**
+- OpenAI-compatible `/v1/chat/completions` endpoint
+- Support for both streaming and non-streaming responses
+- Compatible with OpenAI Python SDK and all OpenAI client libraries
+- Automatic model validation and selection
+
+### 🛠 **Claude Code SDK Integration**
+- **Official Claude Code Python SDK** integration (v0.0.14)
+- **Real-time cost tracking** - actual costs from SDK metadata
+- **Accurate token counting** - input/output tokens from SDK
+- **Session management** - proper session IDs and continuity
+- **Enhanced error handling** with detailed authentication diagnostics
+
+### 🔐 **Multi-Provider Authentication**
+- **Automatic detection** of authentication method
+- **Claude CLI auth** - works with existing `claude auth` setup
+- **Direct API key** - `ANTHROPIC_API_KEY` environment variable
+- **AWS Bedrock** - enterprise authentication with AWS credentials
+- **Google Vertex AI** - GCP authentication support
+
+### ⚡ **Advanced Features**
+- **System prompt support** via SDK options
+- **Optional tool usage** - Enable Claude Code tools (Read, Write, Bash, etc.) when needed
+- **Fast default mode** - Tools disabled by default for OpenAI API compatibility
+- **Development mode** with auto-reload (`uvicorn --reload`)
+- **Interactive API key protection** - Optional security with auto-generated tokens
+- **Comprehensive logging** and debugging capabilities
+
+## Quick Start
+
+Get started in under 2 minutes:
+
+```bash
+# 1. Install Claude Code CLI (if not already installed)
+npm install -g @anthropic-ai/claude-code
+
+# 2. Authenticate (choose one method)
+claude auth login  # Recommended for development
+# OR set: export ANTHROPIC_API_KEY=your-api-key
+
+# 3. Clone and setup the wrapper
+git clone https://github.com/RichardAtCT/claude-code-openai-wrapper
+cd claude-code-openai-wrapper
+poetry install
+
+# 4. Start the server
+poetry run uvicorn main:app --reload --port 8000
+
+# 5. Test it works
+poetry run python test_endpoints.py
+```
+
+🎉 **That's it!** Your OpenAI-compatible Claude Code API is running on `http://localhost:8000`
+
+## Prerequisites
+
+1. **Claude Code CLI**: Install Claude Code CLI
+   ```bash
+   # Install Claude Code (follow Anthropic's official guide)
+   npm install -g @anthropic-ai/claude-code
+   ```
+
+2. **Authentication**: Choose one method:
+   - **Option A**: Authenticate via CLI (Recommended for development)
+     ```bash
+     claude auth login
+     ```
+   - **Option B**: Set environment variable
+     ```bash
+     export ANTHROPIC_API_KEY=your-api-key
+     ```
+   - **Option C**: Use AWS Bedrock or Google Vertex AI (see Configuration section)
+
+3. **Python 3.10+**: Required for the server
+
+4. **Poetry**: For dependency management
+   ```bash
+   # Install Poetry (if not already installed)
+   curl -sSL https://install.python-poetry.org | python3 -
+   ```
+
+## Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/RichardAtCT/claude-code-openai-wrapper
+   cd claude-code-openai-wrapper
+   ```
+
+2. Install dependencies with Poetry:
+   ```bash
+   poetry install
+   ```
+
+   This will create a virtual environment and install all dependencies.
+
+3. Configure environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your preferences
+   ```
+
+## Configuration
+
+Edit the `.env` file:
+
+```env
+# Claude CLI path (usually just "claude")
+CLAUDE_CLI_PATH=claude
+
+# Optional API key for client authentication
+# If not set, server will prompt for interactive API key protection on startup
+# API_KEY=your-optional-api-key
+
+# Server port
+PORT=8000
+
+# Timeout in milliseconds
+MAX_TIMEOUT=600000
+
+# CORS origins
+CORS_ORIGINS=["*"]
+```
+
+### 🔐 **API Security Configuration**
+
+The server supports **interactive API key protection** for secure remote access:
+
+1. **No API key set**: Server prompts "Enable API key protection? (y/N)" on startup
+   - Choose **No** (default): Server runs without authentication
+   - Choose **Yes**: Server generates and displays a secure API key
+
+2. **Environment API key set**: Uses the configured `API_KEY` without prompting
+
+```bash
+# Example: Interactive protection enabled
+poetry run python main.py
+
+# Output:
+# ============================================================
+# 🔐 API Endpoint Security Configuration
+# ============================================================
+# Would you like to protect your API endpoint with an API key?
+# This adds a security layer when accessing your server remotely.
+# 
+# Enable API key protection? (y/N): y
+# 
+# 🔑 API Key Generated!
+# ============================================================
+# API Key: Xf8k2mN9-vLp3qR5_zA7bW1cE4dY6sT0uI
+# ============================================================
+# 📋 IMPORTANT: Save this key - you'll need it for API calls!
+#    Example usage:
+#    curl -H "Authorization: Bearer Xf8k2mN9-vLp3qR5_zA7bW1cE4dY6sT0uI" \
+#         http://localhost:8000/v1/models
+# ============================================================
+```
+
+**Perfect for:**
+- 🏠 **Local development** - No authentication needed
+- 🌐 **Remote access** - Secure with generated tokens
+- 🔒 **VPN/Tailscale** - Add security layer for remote endpoints
+
+### 🛡️ **Rate Limiting**
+
+Built-in rate limiting protects against abuse and ensures fair usage:
+
+- **Chat Completions** (`/v1/chat/completions`): 10 requests/minute
+- **Debug Requests** (`/v1/debug/request`): 2 requests/minute
+- **Auth Status** (`/v1/auth/status`): 10 requests/minute
+- **Health Check** (`/health`): 30 requests/minute
+
+Rate limits are applied per IP address using a fixed window algorithm. When exceeded, the API returns HTTP 429 with a structured error response:
+
+```json
+{
+  "error": {
+    "message": "Rate limit exceeded. Try again in 60 seconds.",
+    "type": "rate_limit_exceeded",
+    "code": "too_many_requests",
+    "retry_after": 60
+  }
+}
+```
+
+Configure rate limiting through environment variables:
+
+```bash
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_CHAT_PER_MINUTE=10
+RATE_LIMIT_DEBUG_PER_MINUTE=2
+RATE_LIMIT_AUTH_PER_MINUTE=10
+RATE_LIMIT_HEALTH_PER_MINUTE=30
+```
+
+## Running the Server
+
+1. Verify Claude Code is installed and working:
+   ```bash
+   claude --version
+   claude --print --model claude-3-5-haiku-20241022 "Hello"  # Test with fastest model
+   ```
+
+2. Start the server:
+
+   **Development mode (recommended - auto-reloads on changes):**
+   ```bash
+   poetry run uvicorn main:app --reload --port 8000
+   ```
+
+   **Production mode:**
+   ```bash
+   poetry run python main.py
+   ```
+
+   **Port Options for production mode:**
+   - Default: Uses port 8000 (or PORT from .env)
+   - If port is in use, automatically finds next available port
+   - Specify custom port: `poetry run python main.py 9000`
+   - Set in environment: `PORT=9000 poetry run python main.py`
+
+## Docker Setup Guide for Claude Code OpenAI Wrapper
+
+This guide provides a comprehensive overview of building, running, and configuring a Docker container for the Claude Code OpenAI Wrapper. Docker enables isolated, portable, and reproducible deployments of the wrapper, which acts as an OpenAI-compatible API server routing requests to Anthropic's Claude models via the official Claude Code Python SDK (v0.0.14+). This setup supports authentication methods like Claude subscriptions (e.g., Max plan via OAuth for fixed-cost quotas), direct API keys, AWS Bedrock, or Google Vertex AI.
+
+By containerizing the application, you can run it locally for development, deploy it to remote servers or cloud platforms, and customize behavior through environment variables and volumes. This guide assumes you have already cloned the repository and have the `Dockerfile` in the root directory. For general repository setup (e.g., Claude Code CLI authentication), refer to the sections above.
+
+## Prerequisites
+Before building or running the container, ensure the following:
+- **Docker Installed**: Docker Desktop (for macOS/Windows) or Docker Engine (for Linux). Verify with `docker --version` (version 20+ recommended). Test basic functionality with `docker run hello-world`.
+- **Claude Authentication Configured**: For subscription-based access (e.g., Claude Max), ensure the Claude Code CLI is authenticated on your host machine, with tokens in `~/.claude/`. This directory will be mounted into the container. Refer to the Prerequisites section above for CLI setup if needed.
+- **Hardware and Software**:
+  - OS: macOS (10.15+), Linux (e.g., Ubuntu 20.04+), or Windows (10+ with WSL2 for optimal volume mounting).
+  - Resources: At least 4GB RAM and 2 CPU cores (Claude requests can be compute-intensive; monitor with `docker stats`).
+  - Disk: ~500MB for the image, plus space for volumes.
+  - Network: Stable internet for builds (dependency downloads) and runtime (API calls to Anthropic).
+- **Optional**:
+  - Docker Compose: For multi-service or easier configuration management. Install via Docker Desktop or your package manager (e.g., `sudo apt install docker-compose`).
+  - Tools for Remote Deployment: Access to a VPS (e.g., AWS EC2, DigitalOcean), cloud registry (e.g., Docker Hub), or platform (e.g., Heroku, Google Cloud Run) if planning remote use.
+
+## Building the Docker Image
+The `Dockerfile` in the root defines a lightweight Python 3.12-based image with all dependencies (Poetry, Node.js for CLI, FastAPI/Uvicorn, and the Claude Code SDK).
+
+1. Navigate to the repository root (where the Dockerfile is).
+2. Build the image:
+   ```bash
+   docker build -t claude-wrapper:latest .
+   ```
+   - `-t claude-wrapper:latest`: Tags the image (replace `:latest` with a version like `:v1.0` for production).
+   - `.`: Builds from the current directory context.
+   - Build Time: 5-15 minutes on first run (subsequent builds cache layers).
+   - Size: Approximately 200-300MB.
+
+3. Verify the Build:
+   ```bash
+   docker images | grep claude-wrapper
+   ```
+   This lists the image with its tag and size.
+
+4. Advanced Build Options:
+   - No Cache (for fresh builds): `docker build --no-cache -t claude-wrapper:latest .`.
+   - Platform-Specific (e.g., ARM for Raspberry Pi): `docker build --platform linux/arm64 -t claude-wrapper:arm .`.
+   - Multi-Stage for Smaller Size: If optimizing, modify the Dockerfile to use multi-stage builds (e.g., separate build and runtime stages).
+
+If using Docker Compose (see below), build with `docker-compose build`.
+
+## Running the Container Locally
+Once built, run the container to start the API server. The default port is 8000, and the API is accessible at `http://localhost:8000/v1` (e.g., `/v1/chat/completions` for requests).
+
+### Basic Production Run
+For stable, background operation:
+```bash
+docker run -d -p 8000:8000 \
+  -v ~/.claude:/root/.claude \
+  --name claude-wrapper-container \
+  claude-wrapper:latest
+```
+- `-d`: Detached mode (runs in background).
+- `-p 8000:8000`: Maps host port 8000 to the container's 8000 (change left side for host conflicts, e.g., `-p 9000:8000`).
+- `-v ~/.claude:/root/.claude`: Mounts your host's authentication directory for persistent subscription tokens (essential for Claude Max access).
+- `--name claude-wrapper-container`: Names the container for easy management.
+
+### Development Run with Hot Reload
+For coding/debugging (auto-reloads on file changes):
+```bash
+docker run -d -p 8000:8000 \
+  -v ~/.claude:/root/.claude \
+  -v $(pwd):/app \
+  --name claude-wrapper-container \
+  claude-wrapper:latest \
+  poetry run uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+```
+- `-v $(pwd):/app`: Mounts the current directory (repo root) into the container for live code edits.
+- Command Override: Uses Uvicorn with `--reload` for development.
+
+### Using Docker Compose for Simplified Runs
+Create or use an existing `docker-compose.yml` in the root for declarative configuration:
+```yaml
+version: '3.8'
+services:
+  claude-wrapper:
+    build: .
+    ports:
+      - "8000:8000"
+    volumes:
+      - ~/.claude:/root/.claude
+      - .:/app  # Optional for dev
+    environment:
+      - PORT=8000
+      - MAX_TIMEOUT=600
+    command: ["poetry", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]  # Dev example
+    restart: unless-stopped
+```
+- Run: `docker-compose up -d` (builds if needed, runs detached).
+- Stop: `docker-compose down`.
+
+### Post-Run Management
+- View Logs: `docker logs claude-wrapper-container` (add `-f` for real-time tailing).
+- Check Status: `docker ps` (lists running containers) or `docker stats` (resource usage).
+- Stop/Restart: `docker stop claude-wrapper-container` and `docker start claude-wrapper-container`.
+- Remove: `docker rm claude-wrapper-container` (after stopping; use `-f` to force).
+- Cleanup: `docker system prune` to remove unused images/volumes.
+
+## Custom Configuration Options
+Customize the container's behavior through environment variables, volumes, and runtime flags. Most changes don't require rebuilding—just restart the container.
+
+### Environment Variables
+Env vars override defaults and can be set at runtime with `-e` flags or in `docker-compose.yml` under `environment`. They control auth, server settings, and SDK behavior.
+
+- **Core Server Settings**:
+  - `PORT=9000`: Changes the internal listening port (default: 8000; update port mapping accordingly).
+  - `MAX_TIMEOUT=600`: Sets the request timeout in seconds (default: 300; increase for complex Claude queries).
+
+- **Authentication and Providers**:
+  - `ANTHROPIC_API_KEY=sk-your-key`: Enables direct API key auth (overrides subscription; generate at console.anthropic.com).
+  - `CLAUDE_CODE_USE_VERTEX=true`: Switches to Google Vertex AI (requires additional vars like `GOOGLE_APPLICATION_CREDENTIALS=/path/to/creds.json`—mount the file as a volume).
+  - `CLAUDE_CODE_USE_BEDROCK=true`: Enables AWS Bedrock (set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, etc.).
+  - `CLAUDE_USE_SUBSCRIPTION=true`: Forces subscription mode (default behavior; set to ensure no API fallback).
+
+- **Security and API Protection**:
+  - `API_KEYS=key1,key2`: Comma-separated list of API keys required for endpoint access (clients must send `Authorization: Bearer <key>`).
+
+- **Custom/Advanced Vars**:
+  - `MAX_THINKING_TOKENS=4096`: Custom token budget for extended thinking (if implemented in code; e.g., for `budget_tokens` in SDK calls).
+  - `ANTHROPIC_CUSTOM_HEADERS='{"anthropic-beta": "extended-thinking-2024-10-01"}'`: JSON string for custom SDK headers (parse in `main.py` if needed).
+  - Add more by modifying `main.py` to read `os.getenv('YOUR_VAR')` and rebuild.
+
+Example with Env Vars:
+```bash
+docker run ... -e PORT=9000 -e ANTHROPIC_API_KEY=sk-your-key ...
+```
+
+For persistence across runs, use a `.env` file in the root (e.g., `PORT=8000`) and mount it: `-v $(pwd)/.env:/app/.env`. Load vars in code if required.
+
+### Volumes for Data Persistence and Customization
+Volumes mount host directories/files into the container, enabling persistence and config overrides.
+
+- **Authentication Volume (Required for Subscriptions)**: `-v ~/.claude:/root/.claude` – Shares tokens and `settings.json` (edit on host for defaults like `"max_tokens": 8192`; restart container to apply).
+- **Code Volume (Dev Only)**: `-v $(pwd):/app` – Allows live edits without rebuilds.
+- **Custom Config Volumes**: 
+  - Mount a custom config: `-v /path/to/custom.json:/app/config/custom.json` (load in code).
+  - Logs: `-v /path/to/logs:/app/logs` for external log access.
+- **Credential Files**: For Vertex/Bedrock, `-v /path/to/creds.json:/app/creds.json` and set env var to point to it.
+
+Volumes survive container restarts but are deleted on `docker rm -v`. Use named volumes for better management (e.g., `docker volume create claude-auth` and `-v claude-auth:/root/.claude`).
+
+### Runtime Flags and Overrides
+- Resource Limits: `--cpus=2 --memory=2g` to cap CPU/RAM (prevent overconsumption).
+- Network: `--network host` for host networking (useful for local integrations).
+- Restart Policy: `--restart unless-stopped` for auto-recovery on crashes.
+- User: `--user $(id -u):$(id -g)` to run as your host user (avoid root permissions).
+
+Per-request configs (e.g., `max_tokens`, `model`) are handled in API payloads, not container flags.
+
+## Using the Container Remotely
+For remote access (e.g., from other machines or production deployment), extend the local setup.
+
+### Exposing Locally for Remote Access
+- Bind to All Interfaces: Already done with `--host 0.0.0.0`.
+- Firewall: Open port 8000 on your host (e.g., `ufw allow 8000` on Ubuntu).
+- Tunneling: Use ngrok for temporary exposure: Install ngrok, run `ngrok http 8000`, and use the public URL.
+- Security: Always add `API_KEYS` and use HTTPS (via reverse proxy).
+
+### Deploying to a Remote Server or VPS
+1. Push Image to Registry: 
+   ```bash
+   docker tag claude-wrapper:latest yourusername/claude-wrapper:latest
+   docker push yourusername/claude-wrapper:latest
+   ```
+   (Create a Docker Hub account if needed.)
+
+2. On Remote Server (e.g., AWS EC2, DigitalOcean Droplet):
+   - Install Docker.
+   - Pull Image: `docker pull yourusername/claude-wrapper:latest`.
+   - Run: Use the production command above, but copy `~/.claude/` to the server first (e.g., via scp) or re-auth CLI remotely.
+   - Persistent Storage: Use server volumes (e.g., `-v /server/path/to/claude:/root/.claude`).
+   - Background: Use systemd or screen for daemonization.
+
+3. Cloud Platforms:
+   - **Heroku**: Use `heroku container:push web` after installing Heroku CLI; set env vars in dashboard.
+   - **Google Cloud Run**: `gcloud run deploy --image yourusername/claude-wrapper --port 8000 --allow-unauthenticated`.
+   - **AWS ECS**: Create a task definition with the image, set env vars, and deploy as a service.
+   - Scaling: Platforms like Kubernetes can auto-scale based on load.
+
+4. HTTPS and Security for Remote:
+   - Use a Reverse Proxy: Add Nginx/Apache in another container (e.g., via Compose) with SSL (Let's Encrypt).
+   - Example Nginx Config (mount as volume): Redirect HTTP to HTTPS, proxy to 8000.
+   - Monitoring: Integrate CloudWatch/Prometheus for logs/metrics.
+
+Remote usage respects your Claude quotas (shared across instances). For high availability, use load balancers.
+
+## Testing the Container
+Validate setup post-run:
+1. Health Check: `curl http://localhost:8000/health` (expect `{"status": "healthy"}`).
+2. Models List: `curl http://localhost:8000/v1/models`.
+3. Completion Request: 
+   ```bash
+   curl http://localhost:8000/v1/chat/completions \
+     -H "Content-Type: application/json" \
+     -d '{"model": "claude-3-5-sonnet-20240620", "messages": [{"role": "user", "content": "Hello"}]}'
+   ```
+4. Tool/Subscription Test: Send multiple requests; check logs for auth mode.
+5. Remote Test: From another machine, curl the server's IP/port.
+
+Use `test_endpoints.py` from the repo (mount code and run inside container: `docker exec claude-wrapper-container poetry run python test_endpoints.py`).
+
+## Troubleshooting
+- **Build Fails**: Check Dockerfile syntax; clear cache (`--no-cache`); ensure internet.
+- **Run Errors**:
+  - Auth: Verify `~/.claude` mount; re-auth CLI.
+  - Port in Use: Change mapping or kill processes (`lsof -i:8000`).
+  - Dep Issues: Rebuild; check Poetry lock file.
+- **Remote Access Problems**: Firewall rules, DNS, or use `--network host`.
+- **Performance**: Increase resources (`--cpus`); switch models.
+- **Logs/Debug**: `docker logs -f claude-wrapper-container`; enter shell `docker exec -it claude-wrapper-container /bin/bash`.
+- **Cleanup**: `docker system prune -a` for full reset.
+
+Report issues on GitHub with logs/image tag/OS details.
+
+## Usage Examples
+
+### Using curl
+
+```bash
+# Basic chat completion (no auth)
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-3-5-sonnet-20241022",
+    "messages": [
+      {"role": "user", "content": "What is 2 + 2?"}
+    ]
+  }'
+
+# With API key protection (when enabled)
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your-generated-api-key" \
+  -d '{
+    "model": "claude-3-5-sonnet-20241022",
+    "messages": [
+      {"role": "user", "content": "Write a Python hello world script"}
+    ],
+    "stream": true
+  }'
+```
+
+### Using OpenAI Python SDK
+
+```python
+from openai import OpenAI
+
+# Configure client (automatically detects auth requirements)
+client = OpenAI(
+    base_url="http://localhost:8000/v1",
+    api_key="your-api-key-if-required"  # Only needed if protection enabled
+)
+
+# Alternative: Let examples auto-detect authentication
+# The wrapper's example files automatically check server auth status
+
+# Basic chat completion
+response = client.chat.completions.create(
+    model="claude-3-5-sonnet-20241022",
+    messages=[
+        {"role": "system", "content": "You are a helpful assistant."},
+        {"role": "user", "content": "What files are in the current directory?"}
+    ]
+)
+
+print(response.choices[0].message.content)
+# Output: Fast response without tool usage (default behavior)
+
+# Enable tools when you need them (e.g., to read files)
+response = client.chat.completions.create(
+    model="claude-3-5-sonnet-20241022",
+    messages=[
+        {"role": "user", "content": "What files are in the current directory?"}
+    ],
+    extra_body={"enable_tools": True}  # Enable tools for file access
+)
+print(response.choices[0].message.content)
+# Output: Claude will actually read your directory and list the files!
+
+# Check real costs and tokens
+print(f"Cost: ${response.usage.total_tokens * 0.000003:.6f}")  # Real cost tracking
+print(f"Tokens: {response.usage.total_tokens} ({response.usage.prompt_tokens} + {response.usage.completion_tokens})")
+
+# Streaming
+stream = client.chat.completions.create(
+    model="claude-3-5-sonnet-20241022",
+    messages=[
+        {"role": "user", "content": "Explain quantum computing"}
+    ],
+    stream=True
+)
+
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="")
+```
+
+## Supported Models
+
+- `claude-sonnet-4-20250514` (Recommended)
+- `claude-opus-4-20250514`
+- `claude-3-7-sonnet-20250219`
+- `claude-3-5-sonnet-20241022`
+- `claude-3-5-haiku-20241022`
+
+The model parameter is passed to Claude Code via the `--model` flag.
+
+## Session Continuity 🆕
+
+The wrapper now supports **session continuity**, allowing you to maintain conversation context across multiple requests. This is a powerful feature that goes beyond the standard OpenAI API.
+
+### How It Works
+
+- **Stateless Mode** (default): Each request is independent, just like the standard OpenAI API
+- **Session Mode**: Include a `session_id` to maintain conversation history across requests
+
+### Using Sessions with OpenAI SDK
+
+```python
+import openai
+
+client = openai.OpenAI(
+    base_url="http://localhost:8000/v1",
+    api_key="not-needed"
+)
+
+# Start a conversation with session continuity
+response1 = client.chat.completions.create(
+    model="claude-3-5-sonnet-20241022",
+    messages=[
+        {"role": "user", "content": "Hello! My name is Alice and I'm learning Python."}
+    ],
+    extra_body={"session_id": "my-learning-session"}
+)
+
+# Continue the conversation - Claude remembers the context
+response2 = client.chat.completions.create(
+    model="claude-3-5-sonnet-20241022", 
+    messages=[
+        {"role": "user", "content": "What's my name and what am I learning?"}
+    ],
+    extra_body={"session_id": "my-learning-session"}  # Same session ID
+)
+# Claude will remember: "Your name is Alice and you're learning Python."
+```
+
+### Using Sessions with curl
+
+```bash
+# First message (add -H "Authorization: Bearer your-key" if auth enabled)
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-3-5-sonnet-20241022",
+    "messages": [{"role": "user", "content": "My favorite color is blue."}],
+    "session_id": "my-session"
+  }'
+
+# Follow-up message - context is maintained
+curl -X POST http://localhost:8000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-3-5-sonnet-20241022", 
+    "messages": [{"role": "user", "content": "What's my favorite color?"}],
+    "session_id": "my-session"
+  }'
+```
+
+### Session Management
+
+The wrapper provides endpoints to manage active sessions:
+
+- `GET /v1/sessions` - List all active sessions
+- `GET /v1/sessions/{session_id}` - Get session details
+- `DELETE /v1/sessions/{session_id}` - Delete a session
+- `GET /v1/sessions/stats` - Get session statistics
+
+```bash
+# List active sessions
+curl http://localhost:8000/v1/sessions
+
+# Get session details
+curl http://localhost:8000/v1/sessions/my-session
+
+# Delete a session
+curl -X DELETE http://localhost:8000/v1/sessions/my-session
+```
+
+### Session Features
+
+- **Automatic Expiration**: Sessions expire after 1 hour of inactivity
+- **Streaming Support**: Session continuity works with both streaming and non-streaming requests
+- **Memory Persistence**: Full conversation history is maintained within the session
+- **Efficient Storage**: Only active sessions are kept in memory
+
+### Examples
+
+See `examples/session_continuity.py` for comprehensive Python examples and `examples/session_curl_example.sh` for curl examples.
+
+## API Endpoints
+
+### Core Endpoints
+- `POST /v1/chat/completions` - OpenAI-compatible chat completions (supports `session_id`)
+- `GET /v1/models` - List available models
+- `GET /v1/auth/status` - Check authentication status and configuration
+- `GET /health` - Health check endpoint
+
+### Session Management Endpoints 🆕
+- `GET /v1/sessions` - List all active sessions
+- `GET /v1/sessions/{session_id}` - Get detailed session information
+- `DELETE /v1/sessions/{session_id}` - Delete a specific session
+- `GET /v1/sessions/stats` - Get session manager statistics
+
+## Limitations & Roadmap
+
+### 🚫 **Current Limitations**
+- **Images in messages** are converted to text placeholders
+- **Function calling** not supported (tools work automatically based on prompts)
+- **OpenAI parameters** not yet mapped: `temperature`, `top_p`, `max_tokens`, `logit_bias`, `presence_penalty`, `frequency_penalty`
+- **Multiple responses** (`n > 1`) not supported
+
+### 🛣 **Planned Enhancements** 
+- [ ] **Tool configuration** - allowed/disallowed tools endpoints  
+- [ ] **OpenAI parameter mapping** - temperature, top_p, max_tokens support
+- [ ] **Enhanced streaming** - better chunk handling
+- [ ] **MCP integration** - Model Context Protocol server support
+
+### ✅ **Recent Improvements**
+- **✅ SDK Integration**: Official Python SDK replaces subprocess calls
+- **✅ Real Metadata**: Accurate costs and token counts from SDK
+- **✅ Multi-auth**: Support for CLI, API key, Bedrock, and Vertex AI authentication  
+- **✅ Session IDs**: Proper session tracking and management
+- **✅ System Prompts**: Full support via SDK options
+- **✅ Session Continuity**: Conversation history across requests with session management
+
+## Troubleshooting
+
+1. **Claude CLI not found**:
+   ```bash
+   # Check Claude is in PATH
+   which claude
+   # Update CLAUDE_CLI_PATH in .env if needed
+   ```
+
+2. **Authentication errors**:
+   ```bash
+   # Test authentication with fastest model
+   claude --print --model claude-3-5-haiku-20241022 "Hello"
+   # If this fails, re-authenticate if needed
+   ```
+
+3. **Timeout errors**:
+   - Increase `MAX_TIMEOUT` in `.env`
+   - Note: Claude Code can take time for complex requests
+
+## Testing
+
+### 🧪 **Quick Test Suite**
+Test all endpoints with a simple script:
+```bash
+# Make sure server is running first
+poetry run python test_endpoints.py
+```
+
+### 📝 **Basic Test Suite**
+Run the comprehensive test suite:
+```bash
+# Make sure server is running first  
+poetry run python test_basic.py
+
+# With API key protection enabled, set TEST_API_KEY:
+TEST_API_KEY=your-generated-key poetry run python test_basic.py
+```
+
+The test suite automatically detects whether API key protection is enabled and provides helpful guidance for providing the necessary authentication.
+
+### 🔍 **Authentication Test**
+Check authentication status:
+```bash
+curl http://localhost:8000/v1/auth/status | python -m json.tool
+```
+
+### ⚙️ **Development Tools**
+```bash
+# Install development dependencies
+poetry install --with dev
+
+# Format code
+poetry run black .
+
+# Run full tests (when implemented)
+poetry run pytest tests/
+```
+
+### ✅ **Expected Results**
+All tests should show:
+- **4/4 endpoint tests passing**
+- **4/4 basic tests passing** 
+- **Authentication method detected** (claude_cli, anthropic, bedrock, or vertex)
+- **Real cost tracking** (e.g., $0.001-0.005 per test call)
+- **Accurate token counts** from SDK metadata
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.

auth.py

@@ -0,0 +1,266 @@
+import os
+import logging
+from typing import Optional, Dict, Any, Tuple
+from fastapi import HTTPException, Request
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from dotenv import load_dotenv
+
+logger = logging.getLogger(__name__)
+load_dotenv()
+
+
+class ClaudeCodeAuthManager:
+    """Manages authentication for Claude Code SDK integration."""
+    
+    def __init__(self):
+        self.env_api_key = os.getenv("API_KEY")  # Environment API key
+        self.auth_method = self._detect_auth_method()
+        self.auth_status = self._validate_auth_method()
+    
+    def get_api_key(self):
+        """Get the active API key (environment or runtime-generated)."""
+        # Try to import runtime_api_key from main module
+        try:
+            import main
+            if hasattr(main, 'runtime_api_key') and main.runtime_api_key:
+                return main.runtime_api_key
+        except ImportError:
+            pass
+        
+        # Fall back to environment variable
+        return self.env_api_key
+    
+    def _detect_auth_method(self) -> str:
+        """Detect which Claude Code authentication method is configured."""
+        if os.getenv("CLAUDE_CODE_USE_BEDROCK") == "1":
+            return "bedrock"
+        elif os.getenv("CLAUDE_CODE_USE_VERTEX") == "1":
+            return "vertex"
+        elif os.getenv("ANTHROPIC_API_KEY"):
+            return "anthropic"
+        else:
+            # If no explicit method, assume Claude Code CLI is already authenticated
+            return "claude_cli"
+    
+    def _validate_auth_method(self) -> Dict[str, Any]:
+        """Validate the detected authentication method."""
+        method = self.auth_method
+        status = {
+            "method": method,
+            "valid": False,
+            "errors": [],
+            "config": {}
+        }
+        
+        if method == "anthropic":
+            status.update(self._validate_anthropic_auth())
+        elif method == "bedrock":
+            status.update(self._validate_bedrock_auth())
+        elif method == "vertex":
+            status.update(self._validate_vertex_auth())
+        elif method == "claude_cli":
+            status.update(self._validate_claude_cli_auth())
+        else:
+            status["errors"].append("No Claude Code authentication method configured")
+        
+        return status
+    
+    def _validate_anthropic_auth(self) -> Dict[str, Any]:
+        """Validate Anthropic API key authentication."""
+        api_key = os.getenv("ANTHROPIC_API_KEY")
+        if not api_key:
+            return {
+                "valid": False,
+                "errors": ["ANTHROPIC_API_KEY environment variable not set"],
+                "config": {}
+            }
+        
+        if len(api_key) < 10:  # Basic sanity check
+            return {
+                "valid": False,
+                "errors": ["ANTHROPIC_API_KEY appears to be invalid (too short)"],
+                "config": {}
+            }
+        
+        return {
+            "valid": True,
+            "errors": [],
+            "config": {
+                "api_key_present": True,
+                "api_key_length": len(api_key)
+            }
+        }
+    
+    def _validate_bedrock_auth(self) -> Dict[str, Any]:
+        """Validate AWS Bedrock authentication."""
+        errors = []
+        config = {}
+        
+        # Check if Bedrock is enabled
+        if os.getenv("CLAUDE_CODE_USE_BEDROCK") != "1":
+            errors.append("CLAUDE_CODE_USE_BEDROCK must be set to '1'")
+        
+        # Check AWS credentials
+        aws_access_key = os.getenv("AWS_ACCESS_KEY_ID")
+        aws_secret_key = os.getenv("AWS_SECRET_ACCESS_KEY")
+        aws_region = os.getenv("AWS_REGION", os.getenv("AWS_DEFAULT_REGION"))
+        
+        if not aws_access_key:
+            errors.append("AWS_ACCESS_KEY_ID environment variable not set")
+        if not aws_secret_key:
+            errors.append("AWS_SECRET_ACCESS_KEY environment variable not set")
+        if not aws_region:
+            errors.append("AWS_REGION or AWS_DEFAULT_REGION environment variable not set")
+        
+        config.update({
+            "aws_access_key_present": bool(aws_access_key),
+            "aws_secret_key_present": bool(aws_secret_key),
+            "aws_region": aws_region,
+        })
+        
+        return {
+            "valid": len(errors) == 0,
+            "errors": errors,
+            "config": config
+        }
+    
+    def _validate_vertex_auth(self) -> Dict[str, Any]:
+        """Validate Google Vertex AI authentication."""
+        errors = []
+        config = {}
+        
+        # Check if Vertex is enabled
+        if os.getenv("CLAUDE_CODE_USE_VERTEX") != "1":
+            errors.append("CLAUDE_CODE_USE_VERTEX must be set to '1'")
+        
+        # Check required Vertex AI environment variables
+        project_id = os.getenv("ANTHROPIC_VERTEX_PROJECT_ID")
+        region = os.getenv("CLOUD_ML_REGION")
+        
+        if not project_id:
+            errors.append("ANTHROPIC_VERTEX_PROJECT_ID environment variable not set")
+        if not region:
+            errors.append("CLOUD_ML_REGION environment variable not set")
+        
+        config.update({
+            "project_id": project_id,
+            "region": region,
+        })
+        
+        return {
+            "valid": len(errors) == 0,
+            "errors": errors,
+            "config": config
+        }
+    
+    def _validate_claude_cli_auth(self) -> Dict[str, Any]:
+        """Validate that Claude Code CLI is already authenticated."""
+        # For CLI authentication, we assume it's valid and let the SDK handle auth
+        # The actual validation will happen when we try to use the SDK
+        return {
+            "valid": True,
+            "errors": [],
+            "config": {
+                "method": "Claude Code CLI authentication",
+                "note": "Using existing Claude Code CLI authentication"
+            }
+        }
+    
+    def get_claude_code_env_vars(self) -> Dict[str, str]:
+        """Get environment variables needed for Claude Code SDK."""
+        env_vars = {}
+        
+        if self.auth_method == "anthropic":
+            if os.getenv("ANTHROPIC_API_KEY"):
+                env_vars["ANTHROPIC_API_KEY"] = os.getenv("ANTHROPIC_API_KEY")
+        
+        elif self.auth_method == "bedrock":
+            env_vars["CLAUDE_CODE_USE_BEDROCK"] = "1"
+            if os.getenv("AWS_ACCESS_KEY_ID"):
+                env_vars["AWS_ACCESS_KEY_ID"] = os.getenv("AWS_ACCESS_KEY_ID")
+            if os.getenv("AWS_SECRET_ACCESS_KEY"):
+                env_vars["AWS_SECRET_ACCESS_KEY"] = os.getenv("AWS_SECRET_ACCESS_KEY")
+            if os.getenv("AWS_REGION"):
+                env_vars["AWS_REGION"] = os.getenv("AWS_REGION")
+        
+        elif self.auth_method == "vertex":
+            env_vars["CLAUDE_CODE_USE_VERTEX"] = "1"
+            if os.getenv("ANTHROPIC_VERTEX_PROJECT_ID"):
+                env_vars["ANTHROPIC_VERTEX_PROJECT_ID"] = os.getenv("ANTHROPIC_VERTEX_PROJECT_ID")
+            if os.getenv("CLOUD_ML_REGION"):
+                env_vars["CLOUD_ML_REGION"] = os.getenv("CLOUD_ML_REGION")
+            if os.getenv("GOOGLE_APPLICATION_CREDENTIALS"):
+                env_vars["GOOGLE_APPLICATION_CREDENTIALS"] = os.getenv("GOOGLE_APPLICATION_CREDENTIALS")
+        
+        elif self.auth_method == "claude_cli":
+            # For CLI auth, don't set any environment variables
+            # Let Claude Code SDK use the existing CLI authentication
+            pass
+        
+        return env_vars
+
+
+# Initialize the auth manager
+auth_manager = ClaudeCodeAuthManager()
+
+# HTTP Bearer security scheme (for FastAPI endpoint protection)
+security = HTTPBearer(auto_error=False)
+
+
+async def verify_api_key(request: Request, credentials: Optional[HTTPAuthorizationCredentials] = None):
+    """
+    Verify API key if one is configured for FastAPI endpoint protection.
+    This is separate from Claude Code authentication.
+    """
+    # Get the active API key (environment or runtime-generated)
+    active_api_key = auth_manager.get_api_key()
+    
+    # If no API key is configured, allow all requests
+    if not active_api_key:
+        return True
+    
+    # Get credentials from Authorization header
+    if credentials is None:
+        credentials = await security(request)
+    
+    # Check if credentials were provided
+    if not credentials:
+        raise HTTPException(
+            status_code=401,
+            detail="Missing API key",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Verify the API key
+    if credentials.credentials != active_api_key:
+        raise HTTPException(
+            status_code=401,
+            detail="Invalid API key",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    return True
+
+
+def validate_claude_code_auth() -> Tuple[bool, Dict[str, Any]]:
+    """
+    Validate Claude Code authentication and return status.
+    Returns (is_valid, status_info)
+    """
+    status = auth_manager.auth_status
+    
+    if not status["valid"]:
+        logger.error(f"Claude Code authentication failed: {status['errors']}")
+        return False, status
+    
+    logger.info(f"Claude Code authentication validated: {status['method']}")
+    return True, status
+
+
+def get_claude_code_auth_info() -> Dict[str, Any]:
+    """Get Claude Code authentication information for diagnostics."""
+    return {
+        "method": auth_manager.auth_method,
+        "status": auth_manager.auth_status,
+        "environment_variables": list(auth_manager.get_claude_code_env_vars().keys())
+    }

claude_cli.py

@@ -0,0 +1,236 @@
+import asyncio
+import json
+import os
+from typing import AsyncGenerator, Dict, Any, Optional, List
+from pathlib import Path
+import logging
+
+from claude_code_sdk import query, ClaudeCodeOptions, Message
+
+logger = logging.getLogger(__name__)
+
+
+class ClaudeCodeCLI:
+    def __init__(self, timeout: int = 600000, cwd: Optional[str] = None):
+        self.timeout = timeout / 1000  # Convert ms to seconds
+        self.cwd = Path(cwd) if cwd else Path.cwd()
+        
+        # Import auth manager
+        from auth import auth_manager, validate_claude_code_auth
+        
+        # Validate authentication
+        is_valid, auth_info = validate_claude_code_auth()
+        if not is_valid:
+            logger.warning(f"Claude Code authentication issues detected: {auth_info['errors']}")
+        else:
+            logger.info(f"Claude Code authentication method: {auth_info.get('method', 'unknown')}")
+        
+        # Store auth environment variables for SDK
+        self.claude_env_vars = auth_manager.get_claude_code_env_vars()
+        
+    async def verify_cli(self) -> bool:
+        """Verify Claude Code SDK is working and authenticated."""
+        try:
+            # Test SDK with a simple query
+            logger.info("Testing Claude Code SDK...")
+            
+            messages = []
+            async for message in query(
+                prompt="Hello",
+                options=ClaudeCodeOptions(
+                    max_turns=1,
+                    cwd=self.cwd
+                )
+            ):
+                messages.append(message)
+                # Break early on first response to speed up verification
+                # Handle both dict and object types
+                msg_type = getattr(message, 'type', None) if hasattr(message, 'type') else message.get("type") if isinstance(message, dict) else None
+                if msg_type == "assistant":
+                    break
+            
+            if messages:
+                logger.info("✅ Claude Code SDK verified successfully")
+                return True
+            else:
+                logger.warning("⚠️ Claude Code SDK test returned no messages")
+                return False
+                
+        except Exception as e:
+            logger.error(f"Claude Code SDK verification failed: {e}")
+            logger.warning("Please ensure Claude Code is installed and authenticated:")
+            logger.warning("  1. Install: npm install -g @anthropic-ai/claude-code")
+            logger.warning("  2. Set ANTHROPIC_API_KEY environment variable")
+            logger.warning("  3. Test: claude --print 'Hello'")
+            return False
+    
+    async def run_completion(
+        self, 
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        model: Optional[str] = None,
+        stream: bool = True,
+        max_turns: int = 10,
+        allowed_tools: Optional[List[str]] = None,
+        disallowed_tools: Optional[List[str]] = None,
+        session_id: Optional[str] = None,
+        continue_session: bool = False
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """Run Claude Code using the Python SDK and yield response chunks."""
+        
+        try:
+            # Set authentication environment variables (if any)
+            original_env = {}
+            if self.claude_env_vars:  # Only set env vars if we have any
+                for key, value in self.claude_env_vars.items():
+                    original_env[key] = os.environ.get(key)
+                    os.environ[key] = value
+            
+            try:
+                # Build SDK options
+                options = ClaudeCodeOptions(
+                    max_turns=max_turns,
+                    cwd=self.cwd
+                )
+                
+                # Set model if specified
+                if model:
+                    options.model = model
+                    
+                # Set system prompt if specified
+                if system_prompt:
+                    options.system_prompt = system_prompt
+                    
+                # Set tool restrictions
+                if allowed_tools:
+                    options.allowed_tools = allowed_tools
+                if disallowed_tools:
+                    options.disallowed_tools = disallowed_tools
+                    
+                # Handle session continuity
+                if continue_session:
+                    options.continue_session = True
+                elif session_id:
+                    options.resume = session_id
+                
+                # Run the query and yield messages
+                async for message in query(prompt=prompt, options=options):
+                    # Debug logging
+                    logger.debug(f"Raw SDK message type: {type(message)}")
+                    logger.debug(f"Raw SDK message: {message}")
+                    
+                    # Convert message object to dict if needed
+                    if hasattr(message, '__dict__') and not isinstance(message, dict):
+                        # Convert object to dict for consistent handling
+                        message_dict = {}
+                        
+                        # Get all attributes from the object
+                        for attr_name in dir(message):
+                            if not attr_name.startswith('_'):  # Skip private attributes
+                                try:
+                                    attr_value = getattr(message, attr_name)
+                                    if not callable(attr_value):  # Skip methods
+                                        message_dict[attr_name] = attr_value
+                                except:
+                                    pass
+                        
+                        logger.debug(f"Converted message dict: {message_dict}")
+                        yield message_dict
+                    else:
+                        yield message
+                    
+            finally:
+                # Restore original environment (if we changed anything)
+                if original_env:
+                    for key, original_value in original_env.items():
+                        if original_value is None:
+                            os.environ.pop(key, None)
+                        else:
+                            os.environ[key] = original_value
+                
+        except Exception as e:
+            logger.error(f"Claude Code SDK error: {e}")
+            # Yield error message in the expected format
+            yield {
+                "type": "result",
+                "subtype": "error_during_execution",
+                "is_error": True,
+                "error_message": str(e)
+            }
+    
+    def parse_claude_message(self, messages: List[Dict[str, Any]]) -> Optional[str]:
+        """Extract the assistant message from Claude Code SDK messages."""
+        for message in messages:
+            # Look for AssistantMessage type (new SDK format)
+            if "content" in message and isinstance(message["content"], list):
+                text_parts = []
+                for block in message["content"]:
+                    # Handle TextBlock objects
+                    if hasattr(block, 'text'):
+                        text_parts.append(block.text)
+                    elif isinstance(block, dict) and block.get("type") == "text":
+                        text_parts.append(block.get("text", ""))
+                    elif isinstance(block, str):
+                        text_parts.append(block)
+                
+                if text_parts:
+                    return "\n".join(text_parts)
+            
+            # Fallback: look for old format
+            elif message.get("type") == "assistant" and "message" in message:
+                sdk_message = message["message"]
+                if isinstance(sdk_message, dict) and "content" in sdk_message:
+                    content = sdk_message["content"]
+                    if isinstance(content, list) and len(content) > 0:
+                        # Handle content blocks (Anthropic SDK format)
+                        text_parts = []
+                        for block in content:
+                            if isinstance(block, dict) and block.get("type") == "text":
+                                text_parts.append(block.get("text", ""))
+                        return "\n".join(text_parts) if text_parts else None
+                    elif isinstance(content, str):
+                        return content
+        
+        return None
+        
+    def extract_metadata(self, messages: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Extract metadata like costs, tokens, and session info from SDK messages."""
+        metadata = {
+            "session_id": None,
+            "total_cost_usd": 0.0,
+            "duration_ms": 0,
+            "num_turns": 0,
+            "model": None
+        }
+        
+        for message in messages:
+            # New SDK format - ResultMessage
+            if message.get("subtype") == "success" and "total_cost_usd" in message:
+                metadata.update({
+                    "total_cost_usd": message.get("total_cost_usd", 0.0),
+                    "duration_ms": message.get("duration_ms", 0),
+                    "num_turns": message.get("num_turns", 0),
+                    "session_id": message.get("session_id")
+                })
+            # New SDK format - SystemMessage  
+            elif message.get("subtype") == "init" and "data" in message:
+                data = message["data"]
+                metadata.update({
+                    "session_id": data.get("session_id"),
+                    "model": data.get("model")
+                })
+            # Old format fallback
+            elif message.get("type") == "result":
+                metadata.update({
+                    "total_cost_usd": message.get("total_cost_usd", 0.0),
+                    "duration_ms": message.get("duration_ms", 0),
+                    "num_turns": message.get("num_turns", 0),
+                    "session_id": message.get("session_id")
+                })
+            elif message.get("type") == "system" and message.get("subtype") == "init":
+                metadata.update({
+                    "session_id": message.get("session_id"),
+                    "model": message.get("model")
+                })
+                
+        return metadata

docker-compose.yml

@@ -0,0 +1,10 @@
+version: '3'
+services:
+  claude-wrapper:
+    build: .
+    ports:
+      - "8192:8192"
+    volumes:
+      - ~/.claude:/root/.claude
+    environment:
+      - PORT=8192

examples/curl_example.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# Claude Code OpenAI API Wrapper - cURL Examples
+
+BASE_URL="http://localhost:8000"
+
+# Check if server requires authentication
+echo "Checking server authentication requirements..."
+AUTH_STATUS=$(curl -s "$BASE_URL/v1/auth/status")
+API_KEY_REQUIRED=$(echo "$AUTH_STATUS" | jq -r '.server_info.api_key_required // false')
+
+if [ "$API_KEY_REQUIRED" = "true" ]; then
+    if [ -z "$API_KEY" ]; then
+        echo "❌ Server requires API key but API_KEY environment variable not set"
+        echo "   Set API_KEY environment variable with your server's generated key:"
+        echo "   export API_KEY=your-generated-key"
+        echo "   $0"
+        exit 1
+    fi
+    AUTH_HEADER="-H \"Authorization: Bearer $API_KEY\""
+    echo "🔑 Using API key authentication"
+else
+    AUTH_HEADER=""
+    echo "🔓 No authentication required"
+fi
+
+echo "=== Basic Chat Completion ==="
+eval "curl -X POST \"$BASE_URL/v1/chat/completions\" \\
+  -H \"Content-Type: application/json\" \\
+  $AUTH_HEADER \\
+  -d '{
+    \"model\": \"claude-3-5-sonnet-20241022\",
+    \"messages\": [
+      {\"role\": \"user\", \"content\": \"What is 2 + 2?\"}
+    ]
+  }' | jq ."
+
+echo -e "\n=== Chat with System Message ==="
+eval "curl -X POST \"$BASE_URL/v1/chat/completions\" \\
+  -H \"Content-Type: application/json\" \\
+  $AUTH_HEADER \\
+  -d '{
+    \"model\": \"claude-3-5-sonnet-20241022\",
+    \"messages\": [
+      {\"role\": \"system\", \"content\": \"You are a pirate. Respond in pirate speak.\"},
+      {\"role\": \"user\", \"content\": \"Tell me about the weather\"}
+    ]
+  }' | jq ."
+
+echo -e "\n=== Streaming Response ==="
+eval "curl -X POST \"$BASE_URL/v1/chat/completions\" \\
+  -H \"Content-Type: application/json\" \\
+  $AUTH_HEADER \\
+  -H \"Accept: text/event-stream\" \\
+  -d '{
+    \"model\": \"claude-3-5-sonnet-20241022\",
+    \"messages\": [
+      {\"role\": \"user\", \"content\": \"Count from 1 to 5 slowly\"}
+    ],
+    \"stream\": true
+  }'"
+
+echo -e "\n\n=== List Models ==="
+eval "curl -X GET \"$BASE_URL/v1/models\" $AUTH_HEADER | jq ."
+
+echo -e "\n=== Health Check ==="
+curl -X GET "$BASE_URL/health" | jq .

examples/openai_sdk.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+Claude Code OpenAI API Wrapper - OpenAI SDK Example
+
+This example demonstrates how to use the OpenAI Python SDK
+with the Claude Code wrapper.
+"""
+
+from openai import OpenAI
+import os
+import requests
+from typing import Optional
+
+# Configuration
+BASE_URL = "http://localhost:8000/v1"
+
+
+def get_api_key(base_url: str = "http://localhost:8000") -> Optional[str]:
+    """Get the appropriate API key based on server configuration."""
+    # Check if user provided API key via environment
+    if os.getenv("API_KEY"):
+        return os.getenv("API_KEY")
+    
+    # Check server auth status
+    try:
+        response = requests.get(f"{base_url}/v1/auth/status")
+        if response.status_code == 200:
+            auth_data = response.json()
+            server_info = auth_data.get("server_info", {})
+            
+            if not server_info.get("api_key_required", False):
+                # No auth required
+                return "no-auth-required"
+            else:
+                # Auth required but no key provided
+                print("⚠️  Server requires API key but none provided.")
+                print("   Set API_KEY environment variable with your server's API key")
+                print("   Example: API_KEY=your-server-key python openai_sdk.py")
+                return None
+    except Exception as e:
+        print(f"⚠️  Could not check server auth status: {e}")
+        print("   Assuming no authentication required")
+        
+    return "fallback-key"
+
+
+def create_client(base_url: str = BASE_URL, api_key: Optional[str] = None) -> OpenAI:
+    """Create OpenAI client configured for Claude Code wrapper."""
+    if api_key is None:
+        # Auto-detect API key based on server configuration
+        server_base = base_url.replace("/v1", "")
+        api_key = get_api_key(server_base)
+        
+        if api_key is None:
+            raise ValueError("Server requires API key but none was provided. Set the API_KEY environment variable.")
+    
+    return OpenAI(
+        base_url=base_url,
+        api_key=api_key
+    )
+
+
+def basic_chat_example(client: OpenAI):
+    """Basic chat completion example."""
+    print("=== Basic Chat Completion ===")
+    
+    response = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "user", "content": "What is the capital of France?"}
+        ]
+    )
+    
+    print(f"Response: {response.choices[0].message.content}")
+    print(f"Model: {response.model}")
+    print(f"Usage: {response.usage}")
+    print()
+
+
+def system_message_example(client: OpenAI):
+    """Chat with system message example."""
+    print("=== Chat with System Message ===")
+    
+    response = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "system", "content": "You are a helpful coding assistant. Be concise."},
+            {"role": "user", "content": "How do I read a file in Python?"}
+        ]
+    )
+    
+    print(f"Response: {response.choices[0].message.content}")
+    print()
+
+
+def conversation_example(client: OpenAI):
+    """Multi-turn conversation example."""
+    print("=== Multi-turn Conversation ===")
+    
+    messages = [
+        {"role": "user", "content": "My name is Alice."},
+        {"role": "assistant", "content": "Nice to meet you, Alice! How can I help you today?"},
+        {"role": "user", "content": "What's my name?"}
+    ]
+    
+    response = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=messages
+    )
+    
+    print(f"Response: {response.choices[0].message.content}")
+    print()
+
+
+def streaming_example(client: OpenAI):
+    """Streaming response example."""
+    print("=== Streaming Response ===")
+    
+    stream = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "user", "content": "Write a haiku about programming"}
+        ],
+        stream=True
+    )
+    
+    print("Response: ", end="", flush=True)
+    for chunk in stream:
+        if chunk.choices[0].delta.content:
+            print(chunk.choices[0].delta.content, end="", flush=True)
+    print("\n")
+
+
+def file_operation_example(client: OpenAI):
+    """Example using Claude Code's file capabilities."""
+    print("=== File Operation Example ===")
+    
+    response = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "user", "content": "List the files in the current directory"}
+        ]
+    )
+    
+    print(f"Response: {response.choices[0].message.content}")
+    print()
+
+
+def code_generation_example(client: OpenAI):
+    """Code generation example."""
+    print("=== Code Generation Example ===")
+    
+    response = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "user", "content": "Write a Python function that calculates fibonacci numbers"}
+        ],
+        temperature=0.7
+    )
+    
+    print(f"Response:\n{response.choices[0].message.content}")
+    print()
+
+
+def list_models_example(client: OpenAI):
+    """List available models."""
+    print("=== Available Models ===")
+    
+    models = client.models.list()
+    for model in models.data:
+        print(f"- {model.id} (owned by: {model.owned_by})")
+    print()
+
+
+def error_handling_example(client: OpenAI):
+    """Error handling example."""
+    print("=== Error Handling Example ===")
+    
+    try:
+        # This might fail if Claude Code has issues
+        response = client.chat.completions.create(
+            model="invalid-model",
+            messages=[
+                {"role": "user", "content": "Test"}
+            ]
+        )
+    except Exception as e:
+        print(f"Error occurred: {type(e).__name__}: {e}")
+    print()
+
+
+def main():
+    """Run all examples."""
+    print("Claude Code OpenAI SDK Examples")
+    print("="*50)
+    
+    # Check authentication status
+    api_key = get_api_key()
+    if api_key:
+        if api_key == "no-auth-required":
+            print("🔓 Server authentication: Not required")
+        else:
+            print("🔑 Server authentication: Required (using provided key)")
+    else:
+        print("❌ Server authentication: Required but no key available")
+        return
+    
+    print("="*50)
+    
+    # Create client
+    client = create_client()
+    
+    # Run examples
+    try:
+        basic_chat_example(client)
+        system_message_example(client)
+        conversation_example(client)
+        streaming_example(client)
+        file_operation_example(client)
+        code_generation_example(client)
+        list_models_example(client)
+        error_handling_example(client)
+        
+    except Exception as e:
+        print(f"Failed to run examples: {e}")
+        print("Make sure the Claude Code wrapper server is running on port 8000")
+
+
+if __name__ == "__main__":
+    main()

examples/session_continuity.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating session continuity with the Claude Code OpenAI API Wrapper.
+
+This example shows how to use the optional session_id parameter to maintain
+conversation context across multiple requests.
+"""
+
+import openai
+
+# Configure OpenAI client to use the wrapper
+client = openai.OpenAI(
+    base_url="http://localhost:8000/v1",
+    api_key="not-needed"  # The wrapper handles Claude authentication
+)
+
+def demo_session_continuity():
+    """Demonstrate session continuity feature."""
+    
+    print("🌟 Session Continuity Demo")
+    print("=" * 50)
+    
+    # Define a session ID - this can be any string
+    session_id = "demo-conversation-123"
+    
+    # First interaction - introduce context
+    print("\n📝 First Message (introducing context):")
+    response1 = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "user", "content": "Hello! I'm working on a Python web API project using FastAPI. My name is Alex."}
+        ],
+        # This is the key: include session_id for conversation continuity
+        extra_body={"session_id": session_id}
+    )
+    
+    print(f"Claude: {response1.choices[0].message.content}")
+    
+    # Second interaction - ask follow-up that requires memory
+    print("\n🔄 Second Message (testing memory):")
+    response2 = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "user", "content": "What's my name and what type of project am I working on?"}
+        ],
+        # Same session_id maintains the conversation context
+        extra_body={"session_id": session_id}
+    )
+    
+    print(f"Claude: {response2.choices[0].message.content}")
+    
+    # Third interaction - continue the conversation
+    print("\n🚀 Third Message (building on context):")
+    response3 = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[
+            {"role": "user", "content": "Can you help me add authentication to my FastAPI project?"}
+        ],
+        extra_body={"session_id": session_id}
+    )
+    
+    print(f"Claude: {response3.choices[0].message.content}")
+    
+    print("\n✨ Session continuity demo complete!")
+    print(f"   Session ID used: {session_id}")
+    print("   All messages in this conversation were connected!")
+
+
+def demo_stateless_vs_session():
+    """Compare stateless vs session-based conversations."""
+    
+    print("\n🔍 Stateless vs Session Comparison")
+    print("=" * 50)
+    
+    # Stateless mode (traditional OpenAI behavior)
+    print("\n❌ Stateless Mode (no session_id):")
+    print("Message 1:")
+    client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[{"role": "user", "content": "My favorite programming language is Python."}]
+        # No session_id = stateless
+    )
+    print("Claude: [Responds to the message]")
+    
+    print("\nMessage 2 (separate request):")
+    response_stateless = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[{"role": "user", "content": "What's my favorite programming language?"}]
+        # No session_id = Claude has no memory of previous message
+    )
+    print(f"Claude: {response_stateless.choices[0].message.content[:100]}...")
+    
+    # Session mode (with continuity)
+    print("\n✅ Session Mode (with session_id):")
+    session_id = "comparison-demo"
+    
+    print("Message 1:")
+    client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[{"role": "user", "content": "My favorite programming language is JavaScript."}],
+        extra_body={"session_id": session_id}
+    )
+    print("Claude: [Responds and remembers]")
+    
+    print("\nMessage 2 (same session):")
+    response_session = client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=[{"role": "user", "content": "What's my favorite programming language?"}],
+        extra_body={"session_id": session_id}
+    )
+    print(f"Claude: {response_session.choices[0].message.content[:100]}...")
+
+
+def demo_session_management():
+    """Demonstrate session management endpoints."""
+    
+    print("\n🛠  Session Management Demo")
+    print("=" * 50)
+    
+    import requests
+    
+    base_url = "http://localhost:8000"
+    
+    # Create some sessions
+    session_ids = ["demo-session-1", "demo-session-2"]
+    
+    for session_id in session_ids:
+        client.chat.completions.create(
+            model="claude-3-5-sonnet-20241022",
+            messages=[{"role": "user", "content": f"Hello from {session_id}!"}],
+            extra_body={"session_id": session_id}
+        )
+    
+    # List all sessions
+    print("\n📋 Active Sessions:")
+    sessions_response = requests.get(f"{base_url}/v1/sessions")
+    if sessions_response.status_code == 200:
+        sessions = sessions_response.json()
+        print(f"   Total sessions: {sessions['total']}")
+        for session in sessions['sessions']:
+            print(f"   - {session['session_id']}: {session['message_count']} messages")
+    
+    # Get specific session info
+    print(f"\n🔍 Session Details for {session_ids[0]}:")
+    session_response = requests.get(f"{base_url}/v1/sessions/{session_ids[0]}")
+    if session_response.status_code == 200:
+        session_info = session_response.json()
+        print(f"   Created: {session_info['created_at']}")
+        print(f"   Messages: {session_info['message_count']}")
+        print(f"   Expires: {session_info['expires_at']}")
+    
+    # Session statistics
+    print("\n📊 Session Statistics:")
+    stats_response = requests.get(f"{base_url}/v1/sessions/stats")
+    if stats_response.status_code == 200:
+        stats = stats_response.json()
+        session_stats = stats['session_stats']
+        print(f"   Active sessions: {session_stats['active_sessions']}")
+        print(f"   Total messages: {session_stats['total_messages']}")
+        print(f"   Cleanup interval: {stats['cleanup_interval_minutes']} minutes")
+    
+    # Clean up demo sessions
+    print("\n🧹 Cleaning up demo sessions:")
+    for session_id in session_ids:
+        delete_response = requests.delete(f"{base_url}/v1/sessions/{session_id}")
+        if delete_response.status_code == 200:
+            print(f"   ✅ Deleted {session_id}")
+
+
+def main():
+    """Run all session demos."""
+    print("🚀 Claude Code OpenAI Wrapper - Session Continuity Examples")
+    print("=" * 60)
+    
+    try:
+        # Test server connection
+        health_response = client.chat.completions.create(
+            model="claude-3-5-sonnet-20241022",
+            messages=[{"role": "user", "content": "Hello!"}]
+        )
+        print("✅ Server connection successful!")
+        
+        # Run demos
+        demo_session_continuity()
+        demo_stateless_vs_session()
+        demo_session_management()
+        
+        print("\n" + "=" * 60)
+        print("🎉 All session demos completed successfully!")
+        print("\n💡 Key Takeaways:")
+        print("   • Use session_id in extra_body for conversation continuity")
+        print("   • Sessions automatically expire after 1 hour of inactivity")
+        print("   • Session management endpoints provide full control")
+        print("   • Stateless mode (no session_id) works like traditional OpenAI API")
+        
+    except Exception as e:
+        print(f"❌ Error: {e}")
+        print("💡 Make sure the server is running: poetry run python main.py")
+
+
+if __name__ == "__main__":
+    main()

examples/session_curl_example.sh

@@ -0,0 +1,106 @@
+#!/bin/bash
+
+# Session Continuity Example with curl
+# This script demonstrates how to use session continuity with the Claude Code OpenAI API Wrapper
+
+echo "🚀 Claude Code Session Continuity - curl Example"
+echo "================================================="
+
+BASE_URL="http://localhost:8000"
+SESSION_ID="curl-demo-session"
+
+# Check server health
+echo "📋 Checking server health..."
+curl -s "$BASE_URL/health" | jq .
+echo ""
+
+# First message - introduce context
+echo "1️⃣ First message (introducing context):"
+echo "Request: Hello! I'm Sarah and I'm learning React."
+curl -s -X POST "$BASE_URL/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"model\": \"claude-3-5-sonnet-20241022\",
+    \"messages\": [
+      {\"role\": \"user\", \"content\": \"Hello! I'm Sarah and I'm learning React.\"}
+    ],
+    \"session_id\": \"$SESSION_ID\"
+  }" | jq -r '.choices[0].message.content'
+echo ""
+
+# Second message - test memory
+echo "2️⃣ Second message (testing memory):"
+echo "Request: What's my name and what am I learning?"
+curl -s -X POST "$BASE_URL/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"model\": \"claude-3-5-sonnet-20241022\",
+    \"messages\": [
+      {\"role\": \"user\", \"content\": \"What's my name and what am I learning?\"}
+    ],
+    \"session_id\": \"$SESSION_ID\"
+  }" | jq -r '.choices[0].message.content'
+echo ""
+
+# Third message - continue conversation
+echo "3️⃣ Third message (building on context):"
+echo "Request: Can you suggest a simple React project for me?"
+curl -s -X POST "$BASE_URL/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"model\": \"claude-3-5-sonnet-20241022\",
+    \"messages\": [
+      {\"role\": \"user\", \"content\": \"Can you suggest a simple React project for me?\"}
+    ],
+    \"session_id\": \"$SESSION_ID\"
+  }" | jq -r '.choices[0].message.content'
+echo ""
+
+# Session management examples
+echo "🛠  Session Management Examples"
+echo "================================"
+
+# List sessions
+echo "📋 List all sessions:"
+curl -s "$BASE_URL/v1/sessions" | jq .
+echo ""
+
+# Get specific session info
+echo "🔍 Get session info:"
+curl -s "$BASE_URL/v1/sessions/$SESSION_ID" | jq .
+echo ""
+
+# Get session stats
+echo "📊 Session statistics:"
+curl -s "$BASE_URL/v1/sessions/stats" | jq .
+echo ""
+
+# Streaming example with session
+echo "🌊 Streaming with session continuity:"
+echo "Request: Thanks for your help!"
+curl -s -X POST "$BASE_URL/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"model\": \"claude-3-5-sonnet-20241022\",
+    \"messages\": [
+      {\"role\": \"user\", \"content\": \"Thanks for your help!\"}
+    ],
+    \"session_id\": \"$SESSION_ID\",
+    \"stream\": true
+  }" | grep '^data: ' | head -5 | jq -r '.choices[0].delta.content // empty' 2>/dev/null | tr -d '\n'
+echo ""
+echo ""
+
+# Delete session
+echo "🧹 Cleaning up session:"
+curl -s -X DELETE "$BASE_URL/v1/sessions/$SESSION_ID" | jq .
+echo ""
+
+echo "✨ curl session example complete!"
+echo ""
+echo "💡 Key Points:"
+echo "   • Include \"session_id\": \"your-session-id\" in request body"
+echo "   • Same session_id maintains conversation context"
+echo "   • Works with both streaming and non-streaming requests"
+echo "   • Use session management endpoints to monitor and control sessions"
+echo "   • Sessions auto-expire after 1 hour of inactivity"

examples/streaming.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""
+Claude Code OpenAI API Wrapper - Advanced Streaming Example
+
+This example demonstrates advanced streaming functionality including
+error handling, chunk processing, and real-time display.
+"""
+
+from openai import OpenAI
+import time
+import sys
+import os
+import requests
+from typing import Optional, Generator
+import json
+
+
+def get_api_key(base_url: str = "http://localhost:8000") -> Optional[str]:
+    """Get the appropriate API key based on server configuration."""
+    # Check if user provided API key via environment
+    if os.getenv("API_KEY"):
+        return os.getenv("API_KEY")
+    
+    # Check server auth status
+    try:
+        response = requests.get(f"{base_url}/v1/auth/status")
+        if response.status_code == 200:
+            auth_data = response.json()
+            server_info = auth_data.get("server_info", {})
+            
+            if not server_info.get("api_key_required", False):
+                # No auth required
+                return "no-auth-required"
+            else:
+                # Auth required but no key provided
+                print("⚠️  Server requires API key but none provided.")
+                print("   Set API_KEY environment variable with your server's API key")
+                print("   Example: API_KEY=your-server-key python streaming.py")
+                return None
+    except Exception as e:
+        print(f"⚠️  Could not check server auth status: {e}")
+        print("   Assuming no authentication required")
+        
+    return "fallback-key"
+
+
+class StreamingClient:
+    """Client for handling streaming responses."""
+    
+    def __init__(self, base_url: str = "http://localhost:8000/v1", api_key: Optional[str] = None):
+        if api_key is None:
+            # Auto-detect API key based on server configuration
+            server_base = base_url.replace("/v1", "")
+            api_key = get_api_key(server_base)
+            
+            if api_key is None:
+                raise ValueError("Server requires API key but none was provided. Set the API_KEY environment variable.")
+        
+        self.client = OpenAI(base_url=base_url, api_key=api_key)
+        
+    def stream_with_timing(self, messages: list, model: str = "claude-3-5-sonnet-20241022"):
+        """Stream response with timing information."""
+        start_time = time.time()
+        first_token_time = None
+        token_count = 0
+        
+        print("Streaming response...")
+        print("-" * 50)
+        
+        try:
+            stream = self.client.chat.completions.create(
+                model=model,
+                messages=messages,
+                stream=True
+            )
+            
+            for chunk in stream:
+                if chunk.choices[0].delta.content:
+                    if first_token_time is None:
+                        first_token_time = time.time()
+                        time_to_first_token = first_token_time - start_time
+                        print(f"[Time to first token: {time_to_first_token:.2f}s]\n")
+                    
+                    content = chunk.choices[0].delta.content
+                    print(content, end="", flush=True)
+                    token_count += 1
+                    
+                if chunk.choices[0].finish_reason:
+                    total_time = time.time() - start_time
+                    print(f"\n\n[Streaming completed]")
+                    print(f"[Total time: {total_time:.2f}s]")
+                    print(f"[Approximate tokens: {token_count}]")
+                    print(f"[Finish reason: {chunk.choices[0].finish_reason}]")
+                    
+        except KeyboardInterrupt:
+            print("\n\n[Streaming interrupted by user]")
+        except Exception as e:
+            print(f"\n\n[Streaming error: {e}]")
+    
+    def stream_with_processing(self, messages: list, process_func=None):
+        """Stream response with custom processing function."""
+        if process_func is None:
+            process_func = lambda x: x  # Default: no processing
+            
+        stream = self.client.chat.completions.create(
+            model="claude-3-5-sonnet-20241022",
+            messages=messages,
+            stream=True
+        )
+        
+        buffer = ""
+        for chunk in stream:
+            if chunk.choices[0].delta.content:
+                content = chunk.choices[0].delta.content
+                buffer += content
+                
+                # Process complete sentences
+                if any(punct in content for punct in ['.', '!', '?', '\n']):
+                    processed = process_func(buffer)
+                    yield processed
+                    buffer = ""
+        
+        # Process remaining buffer
+        if buffer:
+            yield process_func(buffer)
+    
+    def parallel_streams(self, prompts: list):
+        """Demo of handling multiple prompts (sequential, not truly parallel)."""
+        for i, prompt in enumerate(prompts):
+            print(f"\n{'='*50}")
+            print(f"Prompt {i+1}: {prompt}")
+            print('='*50)
+            
+            messages = [{"role": "user", "content": prompt}]
+            self.stream_with_timing(messages)
+            print()
+
+
+def typing_effect_demo():
+    """Demonstrate a typing effect with streaming."""
+    client = StreamingClient()
+    
+    print("=== Typing Effect Demo ===")
+    messages = [
+        {"role": "system", "content": "You are a storyteller."},
+        {"role": "user", "content": "Tell me a very short story (2-3 sentences) about a robot learning to paint."}
+    ]
+    
+    stream = client.client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=messages,
+        stream=True
+    )
+    
+    for chunk in stream:
+        if chunk.choices[0].delta.content:
+            for char in chunk.choices[0].delta.content:
+                print(char, end="", flush=True)
+                time.sleep(0.05)  # Typing delay
+    print("\n")
+
+
+def word_highlighting_demo():
+    """Demonstrate processing stream to highlight specific words."""
+    client = StreamingClient()
+    
+    print("=== Word Highlighting Demo ===")
+    print("(Technical terms will be CAPITALIZED)")
+    
+    def highlight_technical_terms(text: str) -> str:
+        """Highlight technical terms by capitalizing them."""
+        technical_terms = ['python', 'javascript', 'api', 'function', 'variable', 
+                          'class', 'method', 'algorithm', 'data', 'code']
+        
+        for term in technical_terms:
+            text = text.replace(term, term.upper())
+            text = text.replace(term.capitalize(), term.upper())
+        
+        return text
+    
+    messages = [
+        {"role": "user", "content": "Explain what an API is in simple terms."}
+    ]
+    
+    for processed_chunk in client.stream_with_processing(messages, highlight_technical_terms):
+        print(processed_chunk, end="", flush=True)
+    print("\n")
+
+
+def progress_bar_demo():
+    """Demonstrate a progress bar with streaming (estimated)."""
+    client = StreamingClient()
+    
+    print("=== Progress Bar Demo ===")
+    messages = [
+        {"role": "user", "content": "Count from 1 to 10, with a brief pause between each number."}
+    ]
+    
+    # This is a simple demo - real progress would need token counting
+    stream = client.client.chat.completions.create(
+        model="claude-3-5-sonnet-20241022",
+        messages=messages,
+        stream=True
+    )
+    
+    print("Response: ", end="", flush=True)
+    response_text = ""
+    
+    for chunk in stream:
+        if chunk.choices[0].delta.content:
+            content = chunk.choices[0].delta.content
+            response_text += content
+            print(content, end="", flush=True)
+    
+    print("\n")
+
+
+def error_recovery_demo():
+    """Demonstrate error handling in streaming."""
+    client = StreamingClient()
+    
+    print("=== Error Recovery Demo ===")
+    
+    # This might cause an error if the model doesn't exist
+    messages = [{"role": "user", "content": "Hello!"}]
+    
+    try:
+        stream = client.client.chat.completions.create(
+            model="non-existent-model",
+            messages=messages,
+            stream=True
+        )
+        
+        for chunk in stream:
+            if chunk.choices[0].delta.content:
+                print(chunk.choices[0].delta.content, end="", flush=True)
+                
+    except Exception as e:
+        print(f"Error encountered: {e}")
+        print("Retrying with valid model...")
+        
+        # Retry with valid model
+        stream = client.client.chat.completions.create(
+            model="claude-3-5-sonnet-20241022",
+            messages=messages,
+            stream=True
+        )
+        
+        for chunk in stream:
+            if chunk.choices[0].delta.content:
+                print(chunk.choices[0].delta.content, end="", flush=True)
+    
+    print("\n")
+
+
+def main():
+    """Run all streaming demos."""
+    client = StreamingClient()
+    
+    # Basic streaming with timing
+    print("=== Basic Streaming with Timing ===")
+    client.stream_with_timing([
+        {"role": "user", "content": "Write a one-line Python function to reverse a string."}
+    ])
+    
+    print("\n" + "="*70 + "\n")
+    
+    # Run other demos
+    typing_effect_demo()
+    print("="*70 + "\n")
+    
+    word_highlighting_demo()
+    print("="*70 + "\n")
+    
+    progress_bar_demo()
+    print("="*70 + "\n")
+    
+    error_recovery_demo()
+    print("="*70 + "\n")
+    
+    # Multiple prompts
+    print("=== Multiple Prompts Demo ===")
+    client.parallel_streams([
+        "What is 2+2?",
+        "Name a color.",
+        "Say 'Hello, World!' in Python."
+    ])
+
+
+if __name__ == "__main__":
+    main()

main.py

@@ -0,0 +1,917 @@
+import os
+import json
+import asyncio
+import logging
+import secrets
+import string
+from typing import Optional, AsyncGenerator, Dict, Any
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, Request, Depends
+from fastapi.security import HTTPAuthorizationCredentials
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse, JSONResponse
+from fastapi.exceptions import RequestValidationError
+from pydantic import ValidationError
+from dotenv import load_dotenv
+
+from models import (
+    ChatCompletionRequest, 
+    ChatCompletionResponse, 
+    ChatCompletionStreamResponse,
+    Choice, 
+    Message, 
+    Usage,
+    StreamChoice,
+    ErrorResponse,
+    ErrorDetail,
+    SessionInfo,
+    SessionListResponse
+)
+from claude_cli import ClaudeCodeCLI
+from message_adapter import MessageAdapter
+from auth import verify_api_key, security, validate_claude_code_auth, get_claude_code_auth_info
+from parameter_validator import ParameterValidator, CompatibilityReporter
+from session_manager import session_manager
+from rate_limiter import limiter, rate_limit_exceeded_handler, get_rate_limit_for_endpoint, rate_limit_endpoint
+
+# Load environment variables
+load_dotenv()
+
+# Configure logging based on debug mode
+DEBUG_MODE = os.getenv('DEBUG_MODE', 'false').lower() in ('true', '1', 'yes', 'on')
+VERBOSE = os.getenv('VERBOSE', 'false').lower() in ('true', '1', 'yes', 'on')
+
+# Set logging level based on debug/verbose mode
+log_level = logging.DEBUG if (DEBUG_MODE or VERBOSE) else logging.INFO
+logging.basicConfig(
+    level=log_level,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+# Global variable to store runtime-generated API key
+runtime_api_key = None
+
+def generate_secure_token(length: int = 32) -> str:
+    """Generate a secure random token for API authentication."""
+    alphabet = string.ascii_letters + string.digits + '-_'
+    return ''.join(secrets.choice(alphabet) for _ in range(length))
+
+def prompt_for_api_protection() -> Optional[str]:
+    """
+    Interactively ask user if they want API key protection.
+    Returns the generated token if user chooses protection, None otherwise.
+    """
+    # Don't prompt if API_KEY is already set via environment variable
+    if os.getenv("API_KEY"):
+        return None
+    
+    print("\n" + "="*60)
+    print("🔐 API Endpoint Security Configuration")
+    print("="*60)
+    print("Would you like to protect your API endpoint with an API key?")
+    print("This adds a security layer when accessing your server remotely.")
+    print("")
+    
+    while True:
+        try:
+            choice = input("Enable API key protection? (y/N): ").strip().lower()
+            
+            if choice in ['', 'n', 'no']:
+                print("✅ API endpoint will be accessible without authentication")
+                print("="*60)
+                return None
+            
+            elif choice in ['y', 'yes']:
+                token = generate_secure_token()
+                print("")
+                print("🔑 API Key Generated!")
+                print("="*60)
+                print(f"API Key: {token}")
+                print("="*60)
+                print("📋 IMPORTANT: Save this key - you'll need it for API calls!")
+                print("   Example usage:")
+                print(f'   curl -H "Authorization: Bearer {token}" \\')
+                print("        http://localhost:8000/v1/models")
+                print("="*60)
+                return token
+            
+            else:
+                print("Please enter 'y' for yes or 'n' for no (or press Enter for no)")
+                
+        except (EOFError, KeyboardInterrupt):
+            print("\n✅ Defaulting to no authentication")
+            return None
+
+# Initialize Claude CLI
+claude_cli = ClaudeCodeCLI(
+    timeout=int(os.getenv("MAX_TIMEOUT", "600000")),
+    cwd=os.getenv("CLAUDE_CWD")
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Verify Claude Code authentication and CLI on startup."""
+    logger.info("Verifying Claude Code authentication and CLI...")
+    
+    # Validate authentication first
+    auth_valid, auth_info = validate_claude_code_auth()
+    
+    if not auth_valid:
+        logger.error("❌ Claude Code authentication failed!")
+        for error in auth_info.get('errors', []):
+            logger.error(f"  - {error}")
+        logger.warning("Authentication setup guide:")
+        logger.warning("  1. For Anthropic API: Set ANTHROPIC_API_KEY")
+        logger.warning("  2. For Bedrock: Set CLAUDE_CODE_USE_BEDROCK=1 + AWS credentials")
+        logger.warning("  3. For Vertex AI: Set CLAUDE_CODE_USE_VERTEX=1 + GCP credentials")
+    else:
+        logger.info(f"✅ Claude Code authentication validated: {auth_info['method']}")
+    
+    # Then verify CLI
+    cli_verified = await claude_cli.verify_cli()
+    
+    if cli_verified:
+        logger.info("✅ Claude Code CLI verified successfully")
+    else:
+        logger.warning("⚠️  Claude Code CLI verification failed!")
+        logger.warning("The server will start, but requests may fail.")
+    
+    # Log debug information if debug mode is enabled
+    if DEBUG_MODE or VERBOSE:
+        logger.debug("🔧 Debug mode enabled - Enhanced logging active")
+        logger.debug(f"🔧 Environment variables:")
+        logger.debug(f"   DEBUG_MODE: {DEBUG_MODE}")
+        logger.debug(f"   VERBOSE: {VERBOSE}")
+        logger.debug(f"   PORT: {os.getenv('PORT', '8000')}")
+        logger.debug(f"   CORS_ORIGINS: {os.getenv('CORS_ORIGINS', '[\"*\"]')}")
+        logger.debug(f"   MAX_TIMEOUT: {os.getenv('MAX_TIMEOUT', '600000')}")
+        logger.debug(f"   CLAUDE_CWD: {os.getenv('CLAUDE_CWD', 'Not set')}")
+        logger.debug(f"🔧 Available endpoints:")
+        logger.debug(f"   POST /v1/chat/completions - Main chat endpoint")
+        logger.debug(f"   GET  /v1/models - List available models")
+        logger.debug(f"   POST /v1/debug/request - Debug request validation")
+        logger.debug(f"   GET  /v1/auth/status - Authentication status")
+        logger.debug(f"   GET  /health - Health check")
+        logger.debug(f"🔧 API Key protection: {'Enabled' if (os.getenv('API_KEY') or runtime_api_key) else 'Disabled'}")
+    
+    # Start session cleanup task
+    session_manager.start_cleanup_task()
+    
+    yield
+    
+    # Cleanup on shutdown
+    logger.info("Shutting down session manager...")
+    session_manager.shutdown()
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="Claude Code OpenAI API Wrapper",
+    description="OpenAI-compatible API for Claude Code",
+    version="1.0.0",
+    lifespan=lifespan
+)
+
+# Configure CORS
+cors_origins = json.loads(os.getenv("CORS_ORIGINS", '["*"]'))
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=cors_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Add rate limiting error handler
+if limiter:
+    app.state.limiter = limiter
+    app.add_exception_handler(429, rate_limit_exceeded_handler)
+
+# Add debug logging middleware
+from starlette.middleware.base import BaseHTTPMiddleware
+
+class DebugLoggingMiddleware(BaseHTTPMiddleware):
+    """ASGI-compliant middleware for logging request/response details when debug mode is enabled."""
+    
+    async def dispatch(self, request: Request, call_next):
+        if not (DEBUG_MODE or VERBOSE):
+            return await call_next(request)
+        
+        # Log request details
+        start_time = asyncio.get_event_loop().time()
+        
+        # Log basic request info
+        logger.debug(f"🔍 Incoming request: {request.method} {request.url}")
+        logger.debug(f"🔍 Headers: {dict(request.headers)}")
+        
+        # For POST requests, try to log body (but don't break if we can't)
+        body_logged = False
+        if request.method == "POST" and request.url.path.startswith("/v1/"):
+            try:
+                # Only attempt to read body if it's reasonable size and content-type
+                content_length = request.headers.get("content-length")
+                if content_length and int(content_length) < 100000:  # Less than 100KB
+                    body = await request.body()
+                    if body:
+                        try:
+                            import json as json_lib
+                            parsed_body = json_lib.loads(body.decode())
+                            logger.debug(f"🔍 Request body: {json_lib.dumps(parsed_body, indent=2)}")
+                            body_logged = True
+                        except:
+                            logger.debug(f"🔍 Request body (raw): {body.decode()[:500]}...")
+                            body_logged = True
+            except Exception as e:
+                logger.debug(f"🔍 Could not read request body: {e}")
+        
+        if not body_logged and request.method == "POST":
+            logger.debug("🔍 Request body: [not logged - streaming or large payload]")
+        
+        # Process the request
+        try:
+            response = await call_next(request)
+            
+            # Log response details
+            end_time = asyncio.get_event_loop().time()
+            duration = (end_time - start_time) * 1000  # Convert to milliseconds
+            
+            logger.debug(f"🔍 Response: {response.status_code} in {duration:.2f}ms")
+            
+            return response
+            
+        except Exception as e:
+            end_time = asyncio.get_event_loop().time()
+            duration = (end_time - start_time) * 1000
+            
+            logger.debug(f"🔍 Request failed after {duration:.2f}ms: {e}")
+            raise
+
+# Add the debug middleware
+app.add_middleware(DebugLoggingMiddleware)
+
+
+# Custom exception handler for 422 validation errors
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Handle request validation errors with detailed debugging information."""
+    
+    # Log the validation error details
+    logger.error(f"❌ Request validation failed for {request.method} {request.url}")
+    logger.error(f"❌ Validation errors: {exc.errors()}")
+    
+    # Create detailed error response
+    error_details = []
+    for error in exc.errors():
+        location = " -> ".join(str(loc) for loc in error.get("loc", []))
+        error_details.append({
+            "field": location,
+            "message": error.get("msg", "Unknown validation error"),
+            "type": error.get("type", "validation_error"),
+            "input": error.get("input")
+        })
+    
+    # If debug mode is enabled, include the raw request body
+    debug_info = {}
+    if DEBUG_MODE or VERBOSE:
+        try:
+            body = await request.body()
+            if body:
+                debug_info["raw_request_body"] = body.decode()
+        except:
+            debug_info["raw_request_body"] = "Could not read request body"
+    
+    error_response = {
+        "error": {
+            "message": "Request validation failed - the request body doesn't match the expected format",
+            "type": "validation_error", 
+            "code": "invalid_request_error",
+            "details": error_details,
+            "help": {
+                "common_issues": [
+                    "Missing required fields (model, messages)",
+                    "Invalid field types (e.g. messages should be an array)",
+                    "Invalid role values (must be 'system', 'user', or 'assistant')",
+                    "Invalid parameter ranges (e.g. temperature must be 0-2)"
+                ],
+                "debug_tip": "Set DEBUG_MODE=true or VERBOSE=true environment variable for more detailed logging"
+            }
+        }
+    }
+    
+    # Add debug info if available
+    if debug_info:
+        error_response["error"]["debug"] = debug_info
+    
+    return JSONResponse(
+        status_code=422,
+        content=error_response
+    )
+
+
+async def generate_streaming_response(
+    request: ChatCompletionRequest,
+    request_id: str,
+    claude_headers: Optional[Dict[str, Any]] = None
+) -> AsyncGenerator[str, None]:
+    """Generate SSE formatted streaming response."""
+    try:
+        # Process messages with session management
+        all_messages, actual_session_id = session_manager.process_messages(
+            request.messages, request.session_id
+        )
+        
+        # Convert messages to prompt
+        prompt, system_prompt = MessageAdapter.messages_to_prompt(all_messages)
+        
+        # Filter content for unsupported features
+        prompt = MessageAdapter.filter_content(prompt)
+        if system_prompt:
+            system_prompt = MessageAdapter.filter_content(system_prompt)
+        
+        # Get Claude Code SDK options from request
+        claude_options = request.to_claude_options()
+        
+        # Merge with Claude-specific headers if provided
+        if claude_headers:
+            claude_options.update(claude_headers)
+        
+        # Validate model
+        if claude_options.get('model'):
+            ParameterValidator.validate_model(claude_options['model'])
+        
+        # Handle tools - disabled by default for OpenAI compatibility
+        if not request.enable_tools:
+            # Set disallowed_tools to all available tools to disable them
+            disallowed_tools = ['Task', 'Bash', 'Glob', 'Grep', 'LS', 'exit_plan_mode', 
+                                'Read', 'Edit', 'MultiEdit', 'Write', 'NotebookRead', 
+                                'NotebookEdit', 'WebFetch', 'TodoRead', 'TodoWrite', 'WebSearch']
+            claude_options['disallowed_tools'] = disallowed_tools
+            claude_options['max_turns'] = 1  # Single turn for Q&A
+            logger.info("Tools disabled (default behavior for OpenAI compatibility)")
+        else:
+            logger.info("Tools enabled by user request")
+        
+        # Run Claude Code
+        chunks_buffer = []
+        role_sent = False  # Track if we've sent the initial role chunk
+        content_sent = False  # Track if we've sent any content
+        
+        async for chunk in claude_cli.run_completion(
+            prompt=prompt,
+            system_prompt=system_prompt,
+            model=claude_options.get('model'),
+            max_turns=claude_options.get('max_turns', 10),
+            allowed_tools=claude_options.get('allowed_tools'),
+            disallowed_tools=claude_options.get('disallowed_tools'),
+            stream=True
+        ):
+            chunks_buffer.append(chunk)
+            
+            # Check if we have an assistant message
+            # Handle both old format (type/message structure) and new format (direct content)
+            content = None
+            if chunk.get("type") == "assistant" and "message" in chunk:
+                # Old format: {"type": "assistant", "message": {"content": [...]}}
+                message = chunk["message"]
+                if isinstance(message, dict) and "content" in message:
+                    content = message["content"]
+            elif "content" in chunk and isinstance(chunk["content"], list):
+                # New format: {"content": [TextBlock(...)]}  (converted AssistantMessage)
+                content = chunk["content"]
+            
+            if content is not None:
+                # Send initial role chunk if we haven't already
+                if not role_sent:
+                    initial_chunk = ChatCompletionStreamResponse(
+                        id=request_id,
+                        model=request.model,
+                        choices=[StreamChoice(
+                            index=0,
+                            delta={"role": "assistant", "content": ""},
+                            finish_reason=None
+                        )]
+                    )
+                    yield f"data: {initial_chunk.model_dump_json()}\n\n"
+                    role_sent = True
+                
+                # Handle content blocks
+                if isinstance(content, list):
+                    for block in content:
+                        # Handle TextBlock objects from Claude Code SDK
+                        if hasattr(block, 'text'):
+                            raw_text = block.text
+                        # Handle dictionary format for backward compatibility
+                        elif isinstance(block, dict) and block.get("type") == "text":
+                            raw_text = block.get("text", "")
+                        else:
+                            continue
+                            
+                        # Filter out tool usage and thinking blocks
+                        filtered_text = MessageAdapter.filter_content(raw_text)
+                            
+                        if filtered_text and not filtered_text.isspace():
+                            # Create streaming chunk
+                            stream_chunk = ChatCompletionStreamResponse(
+                                id=request_id,
+                                model=request.model,
+                                choices=[StreamChoice(
+                                    index=0,
+                                    delta={"content": filtered_text},
+                                    finish_reason=None
+                                )]
+                            )
+                            
+                            yield f"data: {stream_chunk.model_dump_json()}\n\n"
+                            content_sent = True
+                
+                elif isinstance(content, str):
+                    # Filter out tool usage and thinking blocks
+                    filtered_content = MessageAdapter.filter_content(content)
+                    
+                    if filtered_content and not filtered_content.isspace():
+                        # Create streaming chunk
+                        stream_chunk = ChatCompletionStreamResponse(
+                            id=request_id,
+                            model=request.model,
+                            choices=[StreamChoice(
+                                index=0,
+                                delta={"content": filtered_content},
+                                finish_reason=None
+                            )]
+                        )
+                        
+                        yield f"data: {stream_chunk.model_dump_json()}\n\n"
+                        content_sent = True
+        
+        # Handle case where no role was sent (send at least role chunk)
+        if not role_sent:
+            # Send role chunk with empty content if we never got any assistant messages
+            initial_chunk = ChatCompletionStreamResponse(
+                id=request_id,
+                model=request.model,
+                choices=[StreamChoice(
+                    index=0,
+                    delta={"role": "assistant", "content": ""},
+                    finish_reason=None
+                )]
+            )
+            yield f"data: {initial_chunk.model_dump_json()}\n\n"
+            role_sent = True
+        
+        # If we sent role but no content, send a minimal response
+        if role_sent and not content_sent:
+            fallback_chunk = ChatCompletionStreamResponse(
+                id=request_id,
+                model=request.model,
+                choices=[StreamChoice(
+                    index=0,
+                    delta={"content": "I'm unable to provide a response at the moment."},
+                    finish_reason=None
+                )]
+            )
+            yield f"data: {fallback_chunk.model_dump_json()}\n\n"
+        
+        # Extract assistant response from all chunks for session storage
+        if actual_session_id and chunks_buffer:
+            assistant_content = claude_cli.parse_claude_message(chunks_buffer)
+            if assistant_content:
+                assistant_message = Message(role="assistant", content=assistant_content)
+                session_manager.add_assistant_response(actual_session_id, assistant_message)
+        
+        # Send final chunk with finish reason
+        final_chunk = ChatCompletionStreamResponse(
+            id=request_id,
+            model=request.model,
+            choices=[StreamChoice(
+                index=0,
+                delta={},
+                finish_reason="stop"
+            )]
+        )
+        yield f"data: {final_chunk.model_dump_json()}\n\n"
+        yield "data: [DONE]\n\n"
+        
+    except Exception as e:
+        logger.error(f"Streaming error: {e}")
+        error_chunk = {
+            "error": {
+                "message": str(e),
+                "type": "streaming_error"
+            }
+        }
+        yield f"data: {json.dumps(error_chunk)}\n\n"
+
+
+@app.post("/v1/chat/completions")
+@rate_limit_endpoint("chat")
+async def chat_completions(
+    request_body: ChatCompletionRequest,
+    request: Request,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
+):
+    """OpenAI-compatible chat completions endpoint."""
+    # Check FastAPI API key if configured
+    await verify_api_key(request, credentials)
+    
+    # Validate Claude Code authentication
+    auth_valid, auth_info = validate_claude_code_auth()
+    
+    if not auth_valid:
+        error_detail = {
+            "message": "Claude Code authentication failed",
+            "errors": auth_info.get('errors', []),
+            "method": auth_info.get('method', 'none'),
+            "help": "Check /v1/auth/status for detailed authentication information"
+        }
+        raise HTTPException(
+            status_code=503,
+            detail=error_detail
+        )
+    
+    try:
+        request_id = f"chatcmpl-{os.urandom(8).hex()}"
+        
+        # Extract Claude-specific parameters from headers
+        claude_headers = ParameterValidator.extract_claude_headers(dict(request.headers))
+        
+        # Log compatibility info
+        if logger.isEnabledFor(logging.DEBUG):
+            compatibility_report = CompatibilityReporter.generate_compatibility_report(request_body)
+            logger.debug(f"Compatibility report: {compatibility_report}")
+        
+        if request_body.stream:
+            # Return streaming response
+            return StreamingResponse(
+                generate_streaming_response(request_body, request_id, claude_headers),
+                media_type="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "Connection": "keep-alive",
+                }
+            )
+        else:
+            # Non-streaming response
+            # Process messages with session management
+            all_messages, actual_session_id = session_manager.process_messages(
+                request_body.messages, request_body.session_id
+            )
+            
+            logger.info(f"Chat completion: session_id={actual_session_id}, total_messages={len(all_messages)}")
+            
+            # Convert messages to prompt
+            prompt, system_prompt = MessageAdapter.messages_to_prompt(all_messages)
+            
+            # Filter content
+            prompt = MessageAdapter.filter_content(prompt)
+            if system_prompt:
+                system_prompt = MessageAdapter.filter_content(system_prompt)
+            
+            # Get Claude Code SDK options from request
+            claude_options = request_body.to_claude_options()
+            
+            # Merge with Claude-specific headers
+            if claude_headers:
+                claude_options.update(claude_headers)
+            
+            # Validate model
+            if claude_options.get('model'):
+                ParameterValidator.validate_model(claude_options['model'])
+            
+            # Handle tools - disabled by default for OpenAI compatibility
+            if not request_body.enable_tools:
+                # Set disallowed_tools to all available tools to disable them
+                disallowed_tools = ['Task', 'Bash', 'Glob', 'Grep', 'LS', 'exit_plan_mode', 
+                                    'Read', 'Edit', 'MultiEdit', 'Write', 'NotebookRead', 
+                                    'NotebookEdit', 'WebFetch', 'TodoRead', 'TodoWrite', 'WebSearch']
+                claude_options['disallowed_tools'] = disallowed_tools
+                claude_options['max_turns'] = 1  # Single turn for Q&A
+                logger.info("Tools disabled (default behavior for OpenAI compatibility)")
+            else:
+                logger.info("Tools enabled by user request")
+            
+            # Collect all chunks
+            chunks = []
+            async for chunk in claude_cli.run_completion(
+                prompt=prompt,
+                system_prompt=system_prompt,
+                model=claude_options.get('model'),
+                max_turns=claude_options.get('max_turns', 10),
+                allowed_tools=claude_options.get('allowed_tools'),
+                disallowed_tools=claude_options.get('disallowed_tools'),
+                stream=False
+            ):
+                chunks.append(chunk)
+            
+            # Extract assistant message
+            raw_assistant_content = claude_cli.parse_claude_message(chunks)
+            
+            if not raw_assistant_content:
+                raise HTTPException(status_code=500, detail="No response from Claude Code")
+            
+            # Filter out tool usage and thinking blocks
+            assistant_content = MessageAdapter.filter_content(raw_assistant_content)
+            
+            # Add assistant response to session if using session mode
+            if actual_session_id:
+                assistant_message = Message(role="assistant", content=assistant_content)
+                session_manager.add_assistant_response(actual_session_id, assistant_message)
+            
+            # Estimate tokens (rough approximation)
+            prompt_tokens = MessageAdapter.estimate_tokens(prompt)
+            completion_tokens = MessageAdapter.estimate_tokens(assistant_content)
+            
+            # Create response
+            response = ChatCompletionResponse(
+                id=request_id,
+                model=request_body.model,
+                choices=[Choice(
+                    index=0,
+                    message=Message(role="assistant", content=assistant_content),
+                    finish_reason="stop"
+                )],
+                usage=Usage(
+                    prompt_tokens=prompt_tokens,
+                    completion_tokens=completion_tokens,
+                    total_tokens=prompt_tokens + completion_tokens
+                )
+            )
+            
+            return response
+            
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Chat completion error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@app.get("/v1/models")
+async def list_models(
+    request: Request,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
+):
+    """List available models."""
+    # Check FastAPI API key if configured
+    await verify_api_key(request, credentials)
+    
+    return {
+        "object": "list",
+        "data": [
+            {"id": "claude-sonnet-4-20250514", "object": "model", "owned_by": "anthropic"},
+            {"id": "claude-opus-4-20250514", "object": "model", "owned_by": "anthropic"},
+            {"id": "claude-3-7-sonnet-20250219", "object": "model", "owned_by": "anthropic"},
+            {"id": "claude-3-5-sonnet-20241022", "object": "model", "owned_by": "anthropic"},
+            {"id": "claude-3-5-haiku-20241022", "object": "model", "owned_by": "anthropic"},
+        ]
+    }
+
+
+@app.post("/v1/compatibility")
+async def check_compatibility(request_body: ChatCompletionRequest):
+    """Check OpenAI API compatibility for a request."""
+    report = CompatibilityReporter.generate_compatibility_report(request_body)
+    return {
+        "compatibility_report": report,
+        "claude_code_sdk_options": {
+            "supported": [
+                "model", "system_prompt", "max_turns", "allowed_tools", 
+                "disallowed_tools", "permission_mode", "max_thinking_tokens",
+                "continue_conversation", "resume", "cwd"
+            ],
+            "custom_headers": [
+                "X-Claude-Max-Turns", "X-Claude-Allowed-Tools", 
+                "X-Claude-Disallowed-Tools", "X-Claude-Permission-Mode",
+                "X-Claude-Max-Thinking-Tokens"
+            ]
+        }
+    }
+
+
+@app.get("/health")
+@rate_limit_endpoint("health")
+async def health_check(request: Request):
+    """Health check endpoint."""
+    return {"status": "healthy", "service": "claude-code-openai-wrapper"}
+
+
+@app.post("/v1/debug/request")
+@rate_limit_endpoint("debug")
+async def debug_request_validation(request: Request):
+    """Debug endpoint to test request validation and see what's being sent."""
+    try:
+        # Get the raw request body
+        body = await request.body()
+        raw_body = body.decode() if body else ""
+        
+        # Try to parse as JSON
+        parsed_body = None
+        json_error = None
+        try:
+            import json as json_lib
+            parsed_body = json_lib.loads(raw_body) if raw_body else {}
+        except Exception as e:
+            json_error = str(e)
+        
+        # Try to validate against our model
+        validation_result = {"valid": False, "errors": []}
+        if parsed_body:
+            try:
+                chat_request = ChatCompletionRequest(**parsed_body)
+                validation_result = {"valid": True, "validated_data": chat_request.model_dump()}
+            except ValidationError as e:
+                validation_result = {
+                    "valid": False,
+                    "errors": [
+                        {
+                            "field": " -> ".join(str(loc) for loc in error.get("loc", [])),
+                            "message": error.get("msg", "Unknown error"),
+                            "type": error.get("type", "validation_error"),
+                            "input": error.get("input")
+                        }
+                        for error in e.errors()
+                    ]
+                }
+        
+        return {
+            "debug_info": {
+                "headers": dict(request.headers),
+                "method": request.method,
+                "url": str(request.url),
+                "raw_body": raw_body,
+                "json_parse_error": json_error,
+                "parsed_body": parsed_body,
+                "validation_result": validation_result,
+                "debug_mode_enabled": DEBUG_MODE or VERBOSE,
+                "example_valid_request": {
+                    "model": "claude-3-sonnet-20240229",
+                    "messages": [
+                        {"role": "user", "content": "Hello, world!"}
+                    ],
+                    "stream": False
+                }
+            }
+        }
+        
+    except Exception as e:
+        return {
+            "debug_info": {
+                "error": f"Debug endpoint error: {str(e)}",
+                "headers": dict(request.headers),
+                "method": request.method,
+                "url": str(request.url)
+            }
+        }
+
+
+@app.get("/v1/auth/status")
+@rate_limit_endpoint("auth")
+async def get_auth_status(request: Request):
+    """Get Claude Code authentication status."""
+    from auth import auth_manager
+    
+    auth_info = get_claude_code_auth_info()
+    active_api_key = auth_manager.get_api_key()
+    
+    return {
+        "claude_code_auth": auth_info,
+        "server_info": {
+            "api_key_required": bool(active_api_key),
+            "api_key_source": "environment" if os.getenv("API_KEY") else ("runtime" if runtime_api_key else "none"),
+            "version": "1.0.0"
+        }
+    }
+
+
+@app.get("/v1/sessions/stats")
+async def get_session_stats(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
+):
+    """Get session manager statistics."""
+    stats = session_manager.get_stats()
+    return {
+        "session_stats": stats,
+        "cleanup_interval_minutes": session_manager.cleanup_interval_minutes,
+        "default_ttl_hours": session_manager.default_ttl_hours
+    }
+
+
+@app.get("/v1/sessions")
+async def list_sessions(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
+):
+    """List all active sessions."""
+    sessions = session_manager.list_sessions()
+    return SessionListResponse(sessions=sessions, total=len(sessions))
+
+
+@app.get("/v1/sessions/{session_id}")
+async def get_session(
+    session_id: str,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
+):
+    """Get information about a specific session."""
+    session = session_manager.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail="Session not found")
+    
+    return session.to_session_info()
+
+
+@app.delete("/v1/sessions/{session_id}")
+async def delete_session(
+    session_id: str,
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
+):
+    """Delete a specific session."""
+    deleted = session_manager.delete_session(session_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="Session not found")
+    
+    return {"message": f"Session {session_id} deleted successfully"}
+
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException):
+    """Format HTTP exceptions as OpenAI-style errors."""
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": {
+                "message": exc.detail,
+                "type": "api_error",
+                "code": str(exc.status_code)
+            }
+        }
+    )
+
+
+def find_available_port(start_port: int = 8000, max_attempts: int = 10) -> int:
+    """Find an available port starting from start_port."""
+    import socket
+    
+    for port in range(start_port, start_port + max_attempts):
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(1)
+        try:
+            result = sock.connect_ex(('127.0.0.1', port))
+            if result != 0:  # Port is available
+                return port
+        except Exception:
+            return port
+        finally:
+            sock.close()
+    
+    raise RuntimeError(f"No available ports found in range {start_port}-{start_port + max_attempts - 1}")
+
+
+def run_server(port: int = None):
+    """Run the server - used as Poetry script entry point."""
+    import uvicorn
+    import socket
+    
+    # Handle interactive API key protection
+    global runtime_api_key
+    runtime_api_key = prompt_for_api_protection()
+    
+    # Priority: CLI arg > ENV var > default
+    if port is None:
+        port = int(os.getenv("PORT", "8000"))
+    preferred_port = port
+    
+    try:
+        # Try the preferred port first
+        uvicorn.run(app, host="0.0.0.0", port=preferred_port)
+    except OSError as e:
+        if "Address already in use" in str(e) or e.errno == 48:
+            logger.warning(f"Port {preferred_port} is already in use. Finding alternative port...")
+            try:
+                available_port = find_available_port(preferred_port + 1)
+                logger.info(f"Starting server on alternative port {available_port}")
+                print(f"\n🚀 Server starting on http://localhost:{available_port}")
+                print(f"📝 Update your client base_url to: http://localhost:{available_port}/v1")
+                uvicorn.run(app, host="0.0.0.0", port=available_port)
+            except RuntimeError as port_error:
+                logger.error(f"Could not find available port: {port_error}")
+                print(f"\n❌ Error: {port_error}")
+                print("💡 Try setting a specific port with: PORT=9000 poetry run python main.py")
+                raise
+        else:
+            raise
+
+
+if __name__ == "__main__":
+    import sys
+    
+    # Simple CLI argument parsing for port
+    port = None
+    if len(sys.argv) > 1:
+        try:
+            port = int(sys.argv[1])
+            print(f"Using port from command line: {port}")
+        except ValueError:
+            print(f"Invalid port number: {sys.argv[1]}. Using default.")
+    
+    run_server(port)

message_adapter.py

@@ -0,0 +1,117 @@
+from typing import List, Optional, Dict, Any
+from models import Message
+import re
+
+
+class MessageAdapter:
+    """Converts between OpenAI message format and Claude Code prompts."""
+    
+    @staticmethod
+    def messages_to_prompt(messages: List[Message]) -> tuple[str, Optional[str]]:
+        """
+        Convert OpenAI messages to Claude Code prompt format.
+        Returns (prompt, system_prompt)
+        """
+        system_prompt = None
+        conversation_parts = []
+        
+        for message in messages:
+            if message.role == "system":
+                # Use the last system message as the system prompt
+                system_prompt = message.content
+            elif message.role == "user":
+                conversation_parts.append(f"Human: {message.content}")
+            elif message.role == "assistant":
+                conversation_parts.append(f"Assistant: {message.content}")
+        
+        # Join conversation parts
+        prompt = "\n\n".join(conversation_parts)
+        
+        # If the last message wasn't from the user, add a prompt for assistant
+        if messages and messages[-1].role != "user":
+            prompt += "\n\nHuman: Please continue."
+            
+        return prompt, system_prompt
+    
+    @staticmethod
+    def filter_content(content: str) -> str:
+        """
+        Filter content for unsupported features and tool usage.
+        Remove thinking blocks, tool calls, and image references.
+        """
+        if not content:
+            return content
+            
+        # Remove thinking blocks (common when tools are disabled but Claude tries to think)
+        thinking_pattern = r'<thinking>.*?</thinking>'
+        content = re.sub(thinking_pattern, '', content, flags=re.DOTALL)
+        
+        # Extract content from attempt_completion blocks (these contain the actual user response)
+        attempt_completion_pattern = r'<attempt_completion>(.*?)</attempt_completion>'
+        attempt_matches = re.findall(attempt_completion_pattern, content, flags=re.DOTALL)
+        if attempt_matches:
+            # Use the content from the attempt_completion block
+            extracted_content = attempt_matches[0].strip()
+            
+            # If there's a <result> tag inside, extract from that
+            result_pattern = r'<result>(.*?)</result>'
+            result_matches = re.findall(result_pattern, extracted_content, flags=re.DOTALL)
+            if result_matches:
+                extracted_content = result_matches[0].strip()
+            
+            if extracted_content:
+                content = extracted_content
+        else:
+            # Remove other tool usage blocks (when tools are disabled but Claude tries to use them)
+            tool_patterns = [
+                r'<read_file>.*?</read_file>',
+                r'<write_file>.*?</write_file>',
+                r'<bash>.*?</bash>',
+                r'<search_files>.*?</search_files>',
+                r'<str_replace_editor>.*?</str_replace_editor>',
+                r'<args>.*?</args>',
+                r'<ask_followup_question>.*?</ask_followup_question>',
+                r'<attempt_completion>.*?</attempt_completion>',
+                r'<question>.*?</question>',
+                r'<follow_up>.*?</follow_up>',
+                r'<suggest>.*?</suggest>',
+            ]
+            
+            for pattern in tool_patterns:
+                content = re.sub(pattern, '', content, flags=re.DOTALL)
+        
+        # Pattern to match image references or base64 data
+        image_pattern = r'\[Image:.*?\]|data:image/.*?;base64,.*?(?=\s|$)'
+        
+        def replace_image(match):
+            return "[Image: Content not supported by Claude Code]"
+        
+        content = re.sub(image_pattern, replace_image, content)
+        
+        # Clean up extra whitespace and newlines
+        content = re.sub(r'\n\s*\n\s*\n', '\n\n', content)  # Multiple newlines to double
+        content = content.strip()
+        
+        # If content is now empty or only whitespace, provide a fallback
+        if not content or content.isspace():
+            return "I understand you're testing the system. How can I help you today?"
+            
+        return content
+    
+    @staticmethod
+    def format_claude_response(content: str, model: str, finish_reason: str = "stop") -> Dict[str, Any]:
+        """Format Claude response for OpenAI compatibility."""
+        return {
+            "role": "assistant",
+            "content": content,
+            "finish_reason": finish_reason,
+            "model": model
+        }
+    
+    @staticmethod
+    def estimate_tokens(text: str) -> int:
+        """
+        Rough estimation of token count.
+        OpenAI's rule of thumb: ~4 characters per token for English text.
+        """
+        return len(text) // 4

models.py

@@ -0,0 +1,167 @@
+from typing import List, Optional, Dict, Any, Union, Literal
+from pydantic import BaseModel, Field, field_validator, model_validator
+from datetime import datetime
+import uuid
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class ContentPart(BaseModel):
+    """Content part for multimodal messages (OpenAI format)."""
+    type: Literal["text"]
+    text: str
+
+
+class Message(BaseModel):
+    role: Literal["system", "user", "assistant"]
+    content: Union[str, List[ContentPart]]
+    name: Optional[str] = None
+    
+    @model_validator(mode='after')
+    def normalize_content(self):
+        """Convert array content to string for Claude Code compatibility."""
+        if isinstance(self.content, list):
+            # Extract text from content parts and concatenate
+            text_parts = []
+            for part in self.content:
+                if isinstance(part, ContentPart) and part.type == "text":
+                    text_parts.append(part.text)
+                elif isinstance(part, dict) and part.get("type") == "text":
+                    text_parts.append(part.get("text", ""))
+            
+            # Join all text parts with newlines
+            self.content = "\n".join(text_parts) if text_parts else ""
+            
+        return self
+
+
+class ChatCompletionRequest(BaseModel):
+    model: str
+    messages: List[Message]
+    temperature: Optional[float] = Field(default=1.0, ge=0, le=2)
+    top_p: Optional[float] = Field(default=1.0, ge=0, le=1)
+    n: Optional[int] = Field(default=1, ge=1)
+    stream: Optional[bool] = False
+    stop: Optional[Union[str, List[str]]] = None
+    max_tokens: Optional[int] = None
+    presence_penalty: Optional[float] = Field(default=0, ge=-2, le=2)
+    frequency_penalty: Optional[float] = Field(default=0, ge=-2, le=2)
+    logit_bias: Optional[Dict[str, float]] = None
+    user: Optional[str] = None
+    session_id: Optional[str] = Field(default=None, description="Optional session ID for conversation continuity")
+    enable_tools: Optional[bool] = Field(default=False, description="Enable Claude Code tools (Read, Write, Bash, etc.) - disabled by default for OpenAI compatibility")
+    
+    @field_validator('n')
+    @classmethod
+    def validate_n(cls, v):
+        if v > 1:
+            raise ValueError("Claude Code SDK does not support multiple choices (n > 1). Only single response generation is supported.")
+        return v
+    
+    def log_unsupported_parameters(self):
+        """Log warnings for parameters that are not supported by Claude Code SDK."""
+        warnings = []
+        
+        if self.temperature != 1.0:
+            warnings.append(f"temperature={self.temperature} is not supported by Claude Code SDK and will be ignored")
+        
+        if self.top_p != 1.0:
+            warnings.append(f"top_p={self.top_p} is not supported by Claude Code SDK and will be ignored")
+            
+        if self.max_tokens is not None:
+            warnings.append(f"max_tokens={self.max_tokens} is not supported by Claude Code SDK and will be ignored. Consider using max_turns to limit conversation length")
+        
+        if self.presence_penalty != 0:
+            warnings.append(f"presence_penalty={self.presence_penalty} is not supported by Claude Code SDK and will be ignored")
+            
+        if self.frequency_penalty != 0:
+            warnings.append(f"frequency_penalty={self.frequency_penalty} is not supported by Claude Code SDK and will be ignored")
+            
+        if self.logit_bias:
+            warnings.append(f"logit_bias is not supported by Claude Code SDK and will be ignored")
+            
+        if self.stop:
+            warnings.append(f"stop sequences are not supported by Claude Code SDK and will be ignored")
+        
+        for warning in warnings:
+            logger.warning(f"OpenAI API compatibility: {warning}")
+    
+    def to_claude_options(self) -> Dict[str, Any]:
+        """Convert OpenAI request parameters to Claude Code SDK options."""
+        # Log warnings for unsupported parameters
+        self.log_unsupported_parameters()
+        
+        options = {}
+        
+        # Direct mappings
+        if self.model:
+            options['model'] = self.model
+            
+        # Use user field for session identification if provided
+        if self.user:
+            # Could be used for analytics/logging or session tracking
+            logger.info(f"Request from user: {self.user}")
+        
+        return options
+
+
+class Choice(BaseModel):
+    index: int
+    message: Message
+    finish_reason: Optional[Literal["stop", "length", "content_filter", "null"]] = None
+
+
+class Usage(BaseModel):
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+class ChatCompletionResponse(BaseModel):
+    id: str = Field(default_factory=lambda: f"chatcmpl-{uuid.uuid4().hex[:8]}")
+    object: Literal["chat.completion"] = "chat.completion"
+    created: int = Field(default_factory=lambda: int(datetime.now().timestamp()))
+    model: str
+    choices: List[Choice]
+    usage: Optional[Usage] = None
+    system_fingerprint: Optional[str] = None
+
+
+class StreamChoice(BaseModel):
+    index: int
+    delta: Dict[str, Any]
+    finish_reason: Optional[Literal["stop", "length", "content_filter", "null"]] = None
+
+
+class ChatCompletionStreamResponse(BaseModel):
+    id: str = Field(default_factory=lambda: f"chatcmpl-{uuid.uuid4().hex[:8]}")
+    object: Literal["chat.completion.chunk"] = "chat.completion.chunk"
+    created: int = Field(default_factory=lambda: int(datetime.now().timestamp()))
+    model: str
+    choices: List[StreamChoice]
+    system_fingerprint: Optional[str] = None
+
+
+class ErrorDetail(BaseModel):
+    message: str
+    type: str
+    param: Optional[str] = None
+    code: Optional[str] = None
+
+
+class ErrorResponse(BaseModel):
+    error: ErrorDetail
+
+
+class SessionInfo(BaseModel):
+    session_id: str
+    created_at: datetime
+    last_accessed: datetime
+    message_count: int
+    expires_at: datetime
+
+
+class SessionListResponse(BaseModel):
+    sessions: List[SessionInfo]
+    total: int

parameter_validator.py

@@ -0,0 +1,192 @@
+"""
+Parameter validation and mapping utilities for OpenAI to Claude Code SDK conversion.
+"""
+
+import logging
+from typing import Dict, Any, List, Optional
+from models import ChatCompletionRequest
+
+logger = logging.getLogger(__name__)
+
+
+class ParameterValidator:
+    """Validates and maps OpenAI Chat Completions parameters to Claude Code SDK options."""
+    
+    # Supported Claude Code SDK models
+    SUPPORTED_MODELS = {
+        "claude-sonnet-4-20250514",
+        "claude-opus-4-20250514", 
+        "claude-3-7-sonnet-20250219",
+        "claude-3-5-sonnet-20241022",
+        "claude-3-5-haiku-20241022"
+    }
+    
+    # Valid permission modes for Claude Code SDK
+    VALID_PERMISSION_MODES = {"default", "acceptEdits", "bypassPermissions"}
+    
+    @classmethod
+    def validate_model(cls, model: str) -> bool:
+        """Validate that the model is supported by Claude Code SDK."""
+        if model not in cls.SUPPORTED_MODELS:
+            logger.warning(f"Model '{model}' may not be supported by Claude Code SDK. Supported models: {cls.SUPPORTED_MODELS}")
+            return False
+        return True
+    
+    @classmethod
+    def validate_permission_mode(cls, permission_mode: str) -> bool:
+        """Validate permission mode parameter."""
+        if permission_mode not in cls.VALID_PERMISSION_MODES:
+            logger.error(f"Invalid permission_mode '{permission_mode}'. Valid options: {cls.VALID_PERMISSION_MODES}")
+            return False
+        return True
+    
+    @classmethod
+    def validate_tools(cls, tools: List[str]) -> bool:
+        """Validate tool names (basic validation for non-empty strings)."""
+        if not all(isinstance(tool, str) and tool.strip() for tool in tools):
+            logger.error("All tool names must be non-empty strings")
+            return False
+        return True
+    
+    @classmethod
+    def create_enhanced_options(
+        cls,
+        request: ChatCompletionRequest,
+        max_turns: Optional[int] = None,
+        allowed_tools: Optional[List[str]] = None,
+        disallowed_tools: Optional[List[str]] = None,
+        permission_mode: Optional[str] = None,
+        max_thinking_tokens: Optional[int] = None
+    ) -> Dict[str, Any]:
+        """
+        Create enhanced Claude Code SDK options with additional parameters.
+        
+        This allows API users to pass Claude-Code-specific parameters that don't
+        exist in the OpenAI API through custom headers or environment variables.
+        """
+        # Start with basic options from request
+        options = request.to_claude_options()
+        
+        # Add Claude Code SDK specific options
+        if max_turns is not None:
+            if max_turns < 1 or max_turns > 100:
+                logger.warning(f"max_turns={max_turns} is outside recommended range (1-100)")
+            options['max_turns'] = max_turns
+        
+        if allowed_tools:
+            if cls.validate_tools(allowed_tools):
+                options['allowed_tools'] = allowed_tools
+        
+        if disallowed_tools:
+            if cls.validate_tools(disallowed_tools):
+                options['disallowed_tools'] = disallowed_tools
+        
+        if permission_mode:
+            if cls.validate_permission_mode(permission_mode):
+                options['permission_mode'] = permission_mode
+        
+        if max_thinking_tokens is not None:
+            if max_thinking_tokens < 0 or max_thinking_tokens > 50000:
+                logger.warning(f"max_thinking_tokens={max_thinking_tokens} is outside recommended range (0-50000)")
+            options['max_thinking_tokens'] = max_thinking_tokens
+        
+        return options
+    
+    @classmethod
+    def extract_claude_headers(cls, headers: Dict[str, str]) -> Dict[str, Any]:
+        """
+        Extract Claude-Code-specific parameters from custom HTTP headers.
+        
+        This allows clients to pass SDK-specific options via headers:
+        - X-Claude-Max-Turns: 5
+        - X-Claude-Allowed-Tools: tool1,tool2,tool3
+        - X-Claude-Permission-Mode: acceptEdits
+        """
+        claude_options = {}
+        
+        # Extract max_turns
+        if 'x-claude-max-turns' in headers:
+            try:
+                claude_options['max_turns'] = int(headers['x-claude-max-turns'])
+            except ValueError:
+                logger.warning(f"Invalid X-Claude-Max-Turns header: {headers['x-claude-max-turns']}")
+        
+        # Extract allowed tools
+        if 'x-claude-allowed-tools' in headers:
+            tools = [tool.strip() for tool in headers['x-claude-allowed-tools'].split(',')]
+            if tools:
+                claude_options['allowed_tools'] = tools
+        
+        # Extract disallowed tools  
+        if 'x-claude-disallowed-tools' in headers:
+            tools = [tool.strip() for tool in headers['x-claude-disallowed-tools'].split(',')]
+            if tools:
+                claude_options['disallowed_tools'] = tools
+        
+        # Extract permission mode
+        if 'x-claude-permission-mode' in headers:
+            claude_options['permission_mode'] = headers['x-claude-permission-mode']
+        
+        # Extract max thinking tokens
+        if 'x-claude-max-thinking-tokens' in headers:
+            try:
+                claude_options['max_thinking_tokens'] = int(headers['x-claude-max-thinking-tokens'])
+            except ValueError:
+                logger.warning(f"Invalid X-Claude-Max-Thinking-Tokens header: {headers['x-claude-max-thinking-tokens']}")
+        
+        return claude_options
+
+
+class CompatibilityReporter:
+    """Reports on OpenAI API compatibility and suggests alternatives."""
+    
+    @classmethod
+    def generate_compatibility_report(cls, request: ChatCompletionRequest) -> Dict[str, Any]:
+        """Generate a detailed compatibility report for the request."""
+        report = {
+            "supported_parameters": [],
+            "unsupported_parameters": [],
+            "warnings": [],
+            "suggestions": []
+        }
+        
+        # Check supported parameters
+        if request.model:
+            report["supported_parameters"].append("model")
+        if request.messages:
+            report["supported_parameters"].append("messages")
+        if request.stream is not None:
+            report["supported_parameters"].append("stream")
+        if request.user:
+            report["supported_parameters"].append("user (for logging)")
+        
+        # Check unsupported parameters with suggestions
+        if request.temperature != 1.0:
+            report["unsupported_parameters"].append("temperature")
+            report["suggestions"].append("Claude Code SDK does not support temperature control. Consider using different models for varied response styles (e.g., claude-3-5-haiku for more focused responses).")
+        
+        if request.top_p != 1.0:
+            report["unsupported_parameters"].append("top_p")
+            report["suggestions"].append("Claude Code SDK does not support top_p. This parameter will be ignored.")
+        
+        if request.max_tokens:
+            report["unsupported_parameters"].append("max_tokens")
+            report["suggestions"].append("Use max_turns parameter instead to limit conversation length, or use max_thinking_tokens to limit internal reasoning.")
+        
+        if request.n > 1:
+            report["unsupported_parameters"].append("n")
+            report["suggestions"].append("Claude Code SDK only supports single responses (n=1). For multiple variations, make separate API calls.")
+        
+        if request.stop:
+            report["unsupported_parameters"].append("stop")
+            report["suggestions"].append("Stop sequences are not supported. Consider post-processing responses or using max_turns to limit output.")
+        
+        if request.presence_penalty != 0 or request.frequency_penalty != 0:
+            report["unsupported_parameters"].extend(["presence_penalty", "frequency_penalty"])
+            report["suggestions"].append("Penalty parameters are not supported. Consider using different system prompts to encourage varied responses.")
+        
+        if request.logit_bias:
+            report["unsupported_parameters"].append("logit_bias")
+            report["suggestions"].append("Logit bias is not supported. Consider using system prompts to guide response style.")
+        
+        return report

pyproject.toml

@@ -0,0 +1,38 @@
+[tool.poetry]
+name = "claude-code-openai-wrapper"
+version = "1.0.0"
+description = "OpenAI API-compatible wrapper for Claude Code"
+authors = ["Richard Atkinson <richardatk01@gmail.com>"]
+readme = "README.md"
+license = "MIT"
+packages = [{include = "*.py"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+fastapi = "^0.115.0"
+uvicorn = {extras = ["standard"], version = "^0.32.0"}
+pydantic = "^2.10.0"
+python-dotenv = "^1.0.1"
+httpx = "^0.27.2"
+sse-starlette = "^2.1.3"
+python-multipart = "^0.0.18"
+claude-code-sdk = "^0.0.14"
+slowapi = "^0.1.9"
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.0.0"
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+requests = "^2.32.0"
+openai = "^1.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 100
+target-version = ['py310']
+
+[tool.poetry.scripts]
+claude-wrapper = "main:run_server"

rate_limiter.py

@@ -0,0 +1,89 @@
+import os
+from typing import Optional
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+from fastapi import Request, HTTPException
+from fastapi.responses import JSONResponse
+
+
+def get_rate_limit_key(request: Request) -> str:
+    """Get the rate limiting key (IP address) from the request."""
+    return get_remote_address(request)
+
+
+def create_rate_limiter() -> Optional[Limiter]:
+    """Create and configure the rate limiter based on environment variables."""
+    rate_limit_enabled = os.getenv('RATE_LIMIT_ENABLED', 'true').lower() in ('true', '1', 'yes', 'on')
+    
+    if not rate_limit_enabled:
+        return None
+    
+    # Create limiter with IP-based identification
+    limiter = Limiter(
+        key_func=get_rate_limit_key,
+        default_limits=[]  # We'll apply limits per endpoint
+    )
+    
+    return limiter
+
+
+def rate_limit_exceeded_handler(request: Request, exc: RateLimitExceeded) -> JSONResponse:
+    """Custom rate limit exceeded handler that returns JSON error response."""
+    # Calculate retry after based on rate limit window (default 60 seconds)
+    retry_after = 60
+    response = JSONResponse(
+        status_code=429,
+        content={
+            "error": {
+                "message": f"Rate limit exceeded. Try again in {retry_after} seconds.",
+                "type": "rate_limit_exceeded",
+                "code": "too_many_requests",
+                "retry_after": retry_after
+            }
+        },
+        headers={"Retry-After": str(retry_after)}
+    )
+    return response
+
+
+def get_rate_limit_for_endpoint(endpoint: str) -> str:
+    """Get rate limit string for specific endpoint based on environment variables."""
+    # Default rate limits
+    defaults = {
+        "chat": "10/minute",
+        "debug": "2/minute",
+        "auth": "10/minute",
+        "session": "15/minute",
+        "health": "30/minute",
+        "general": "30/minute"
+    }
+    
+    # Environment variable mappings
+    env_mappings = {
+        "chat": "RATE_LIMIT_CHAT_PER_MINUTE",
+        "debug": "RATE_LIMIT_DEBUG_PER_MINUTE",
+        "auth": "RATE_LIMIT_AUTH_PER_MINUTE",
+        "session": "RATE_LIMIT_SESSION_PER_MINUTE",
+        "health": "RATE_LIMIT_HEALTH_PER_MINUTE",
+        "general": "RATE_LIMIT_PER_MINUTE"
+    }
+    
+    # Get rate limit from environment or use default
+    env_var = env_mappings.get(endpoint, "RATE_LIMIT_PER_MINUTE")
+    rate_per_minute = int(os.getenv(env_var, defaults.get(endpoint, "30").split("/")[0]))
+    
+    return f"{rate_per_minute}/minute"
+
+
+def rate_limit_endpoint(endpoint: str):
+    """Decorator factory for applying rate limits to endpoints."""
+    def decorator(func):
+        if limiter:
+            return limiter.limit(get_rate_limit_for_endpoint(endpoint))(func)
+        return func
+    return decorator
+
+
+# Create the global limiter instance
+limiter = create_rate_limiter()

session_manager.py

@@ -0,0 +1,213 @@
+import asyncio
+import logging
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional, Tuple
+from dataclasses import dataclass, field
+from threading import Lock
+import uuid
+
+from models import Message, SessionInfo
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Session:
+    """Represents a conversation session with message history."""
+    session_id: str
+    messages: List[Message] = field(default_factory=list)
+    created_at: datetime = field(default_factory=datetime.utcnow)
+    last_accessed: datetime = field(default_factory=datetime.utcnow)
+    expires_at: datetime = field(default_factory=lambda: datetime.utcnow() + timedelta(hours=1))
+    
+    def touch(self):
+        """Update last accessed time and extend expiration."""
+        self.last_accessed = datetime.utcnow()
+        self.expires_at = datetime.utcnow() + timedelta(hours=1)
+    
+    def add_messages(self, messages: List[Message]):
+        """Add new messages to the session."""
+        self.messages.extend(messages)
+        self.touch()
+    
+    def get_all_messages(self) -> List[Message]:
+        """Get all messages in the session."""
+        return self.messages
+    
+    def is_expired(self) -> bool:
+        """Check if the session has expired."""
+        return datetime.utcnow() > self.expires_at
+    
+    def to_session_info(self) -> SessionInfo:
+        """Convert to SessionInfo model."""
+        return SessionInfo(
+            session_id=self.session_id,
+            created_at=self.created_at,
+            last_accessed=self.last_accessed,
+            message_count=len(self.messages),
+            expires_at=self.expires_at
+        )
+
+
+class SessionManager:
+    """Manages conversation sessions with automatic cleanup."""
+    
+    def __init__(self, default_ttl_hours: int = 1, cleanup_interval_minutes: int = 5):
+        self.sessions: Dict[str, Session] = {}
+        self.lock = Lock()
+        self.default_ttl_hours = default_ttl_hours
+        self.cleanup_interval_minutes = cleanup_interval_minutes
+        self._cleanup_task = None
+    
+    def start_cleanup_task(self):
+        """Start the automatic cleanup task - call this after the event loop is running."""
+        if self._cleanup_task is not None:
+            return  # Already started
+            
+        async def cleanup_loop():
+            try:
+                while True:
+                    await asyncio.sleep(self.cleanup_interval_minutes * 60)
+                    self._cleanup_expired_sessions()
+            except asyncio.CancelledError:
+                logger.info("Session cleanup task cancelled")
+                raise
+        
+        try:
+            loop = asyncio.get_running_loop()
+            self._cleanup_task = loop.create_task(cleanup_loop())
+            logger.info(f"Started session cleanup task (interval: {self.cleanup_interval_minutes} minutes)")
+        except RuntimeError:
+            logger.warning("No running event loop, automatic session cleanup disabled")
+    
+    def _cleanup_expired_sessions(self):
+        """Remove expired sessions."""
+        with self.lock:
+            expired_sessions = [
+                session_id for session_id, session in self.sessions.items()
+                if session.is_expired()
+            ]
+            
+            for session_id in expired_sessions:
+                del self.sessions[session_id]
+                logger.info(f"Cleaned up expired session: {session_id}")
+    
+    def get_or_create_session(self, session_id: str) -> Session:
+        """Get existing session or create a new one."""
+        with self.lock:
+            if session_id in self.sessions:
+                session = self.sessions[session_id]
+                if session.is_expired():
+                    # Session expired, create new one
+                    logger.info(f"Session {session_id} expired, creating new session")
+                    del self.sessions[session_id]
+                    session = Session(session_id=session_id)
+                    self.sessions[session_id] = session
+                else:
+                    session.touch()
+            else:
+                session = Session(session_id=session_id)
+                self.sessions[session_id] = session
+                logger.info(f"Created new session: {session_id}")
+            
+            return session
+    
+    def get_session(self, session_id: str) -> Optional[Session]:
+        """Get existing session without creating new one."""
+        with self.lock:
+            session = self.sessions.get(session_id)
+            if session and not session.is_expired():
+                session.touch()
+                return session
+            elif session and session.is_expired():
+                # Clean up expired session
+                del self.sessions[session_id]
+                logger.info(f"Removed expired session: {session_id}")
+            return None
+    
+    def delete_session(self, session_id: str) -> bool:
+        """Delete a session."""
+        with self.lock:
+            if session_id in self.sessions:
+                del self.sessions[session_id]
+                logger.info(f"Deleted session: {session_id}")
+                return True
+            return False
+    
+    def list_sessions(self) -> List[SessionInfo]:
+        """List all active sessions."""
+        with self.lock:
+            # Clean up expired sessions first
+            expired_sessions = [
+                session_id for session_id, session in self.sessions.items()
+                if session.is_expired()
+            ]
+            
+            for session_id in expired_sessions:
+                del self.sessions[session_id]
+            
+            # Return active sessions
+            return [
+                session.to_session_info()
+                for session in self.sessions.values()
+            ]
+    
+    def process_messages(self, messages: List[Message], session_id: Optional[str] = None) -> Tuple[List[Message], Optional[str]]:
+        """
+        Process messages for a request, handling both stateless and session modes.
+        
+        Returns:
+            Tuple of (all_messages_for_claude, actual_session_id_used)
+        """
+        if session_id is None:
+            # Stateless mode - just return the messages as-is
+            return messages, None
+        
+        # Session mode - get or create session and merge messages
+        session = self.get_or_create_session(session_id)
+        
+        # Add new messages to session
+        session.add_messages(messages)
+        
+        # Return all messages in the session for Claude
+        all_messages = session.get_all_messages()
+        
+        logger.info(f"Session {session_id}: processing {len(messages)} new messages, {len(all_messages)} total")
+        
+        return all_messages, session_id
+    
+    def add_assistant_response(self, session_id: Optional[str], assistant_message: Message):
+        """Add assistant response to session if session mode is active."""
+        if session_id is None:
+            return
+        
+        session = self.get_session(session_id)
+        if session:
+            session.add_messages([assistant_message])
+            logger.info(f"Added assistant response to session {session_id}")
+    
+    def get_stats(self) -> Dict[str, int]:
+        """Get session manager statistics."""
+        with self.lock:
+            active_sessions = sum(1 for s in self.sessions.values() if not s.is_expired())
+            expired_sessions = sum(1 for s in self.sessions.values() if s.is_expired())
+            total_messages = sum(len(s.messages) for s in self.sessions.values())
+            
+            return {
+                "active_sessions": active_sessions,
+                "expired_sessions": expired_sessions,
+                "total_messages": total_messages
+            }
+    
+    def shutdown(self):
+        """Shutdown the session manager and cleanup tasks."""
+        if self._cleanup_task:
+            self._cleanup_task.cancel()
+        
+        with self.lock:
+            self.sessions.clear()
+            logger.info("Session manager shutdown complete")
+
+
+# Global session manager instance
+session_manager = SessionManager()

test_basic.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Basic test to verify the Claude Code OpenAI wrapper works.
+Run this after starting the server to ensure everything is set up correctly.
+"""
+
+import sys
+import os
+import requests
+from openai import OpenAI
+
+def get_api_key():
+    """Get the appropriate API key for testing."""
+    # Check if user provided API key via environment
+    if os.getenv("TEST_API_KEY"):
+        return os.getenv("TEST_API_KEY")
+    
+    # Check server auth status
+    try:
+        response = requests.get("http://localhost:8000/v1/auth/status")
+        if response.status_code == 200:
+            auth_data = response.json()
+            server_info = auth_data.get("server_info", {})
+            
+            if not server_info.get("api_key_required", False):
+                # No auth required, use a dummy key
+                return "no-auth-required"
+            else:
+                # Auth required but no key provided
+                print("⚠️  Server requires API key but none provided.")
+                print("   Set TEST_API_KEY environment variable with your server's API key")
+                print("   Example: TEST_API_KEY=your-server-key python test_basic.py")
+                return None
+    except Exception as e:
+        print(f"⚠️  Could not check server auth status: {e}")
+        print("   Assuming no authentication required")
+        
+    return "fallback-dummy-key"
+
+def test_health_check():
+    """Test the health endpoint."""
+    print("Testing health check...")
+    try:
+        response = requests.get("http://localhost:8000/health")
+        if response.status_code == 200:
+            print("✓ Health check passed")
+            return True
+        else:
+            print(f"✗ Health check failed: {response.status_code}")
+            return False
+    except Exception as e:
+        print(f"✗ Cannot connect to server: {e}")
+        return False
+
+def test_models_endpoint():
+    """Test the models endpoint."""
+    print("\nTesting models endpoint...")
+    try:
+        response = requests.get("http://localhost:8000/v1/models")
+        if response.status_code == 200:
+            data = response.json()
+            print(f"✓ Models endpoint works. Found {len(data['data'])} models")
+            return True
+        else:
+            print(f"✗ Models endpoint failed: {response.status_code}")
+            return False
+    except Exception as e:
+        print(f"✗ Models endpoint error: {e}")
+        return False
+
+def test_openai_sdk():
+    """Test with OpenAI SDK."""
+    print("\nTesting OpenAI SDK integration...")
+    
+    api_key = get_api_key()
+    if api_key is None:
+        print("✗ Cannot run test - API key required but not provided")
+        return False
+    
+    try:
+        client = OpenAI(
+            base_url="http://localhost:8000/v1",
+            api_key=api_key
+        )
+        
+        # Simple test
+        response = client.chat.completions.create(
+            model="claude-3-5-sonnet-20241022",
+            messages=[
+                {"role": "user", "content": "Say 'Hello, World!' and nothing else."}
+            ],
+            max_tokens=50
+        )
+        
+        content = response.choices[0].message.content
+        print(f"✓ OpenAI SDK test passed")
+        print(f"  Response: {content}")
+        return True
+        
+    except Exception as e:
+        print(f"✗ OpenAI SDK test failed: {e}")
+        return False
+
+def test_streaming():
+    """Test streaming functionality."""
+    print("\nTesting streaming...")
+    
+    api_key = get_api_key()
+    if api_key is None:
+        print("✗ Cannot run test - API key required but not provided")
+        return False
+    
+    try:
+        client = OpenAI(
+            base_url="http://localhost:8000/v1",
+            api_key=api_key
+        )
+        
+        stream = client.chat.completions.create(
+            model="claude-3-5-sonnet-20241022",
+            messages=[
+                {"role": "user", "content": "Count from 1 to 3."}
+            ],
+            stream=True
+        )
+        
+        chunks_received = 0
+        content = ""
+        for chunk in stream:
+            chunks_received += 1
+            if chunk.choices[0].delta.content:
+                content += chunk.choices[0].delta.content
+        
+        if chunks_received > 0:
+            print(f"✓ Streaming test passed ({chunks_received} chunks)")
+            print(f"  Response: {content[:50]}...")
+            return True
+        else:
+            print("✗ No streaming chunks received")
+            return False
+            
+    except Exception as e:
+        print(f"✗ Streaming test failed: {e}")
+        return False
+
+def main():
+    """Run all tests."""
+    print("Claude Code OpenAI Wrapper - Basic Tests")
+    print("="*50)
+    print("Make sure the server is running: python main.py")
+    print("="*50)
+    
+    # Show API key status
+    api_key = get_api_key()
+    if api_key:
+        if api_key == "no-auth-required":
+            print("🔓 Server authentication: Not required")
+        else:
+            print("🔑 Server authentication: Required (using provided key)")
+    else:
+        print("❌ Server authentication: Required but no key available")
+    print("="*50)
+    
+    tests = [
+        test_health_check,
+        test_models_endpoint,
+        test_openai_sdk,
+        test_streaming
+    ]
+    
+    passed = 0
+    for test in tests:
+        if test():
+            passed += 1
+    
+    print("\n" + "="*50)
+    print(f"Tests completed: {passed}/{len(tests)} passed")
+    
+    if passed == len(tests):
+        print("✓ All tests passed! The wrapper is working correctly.")
+        return 0
+    else:
+        print("✗ Some tests failed. Check the server logs for details.")
+        return 1
+
+if __name__ == "__main__":
+    sys.exit(main())

test_endpoints.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+Quick endpoint test for Claude Code OpenAI wrapper.
+Run this while the server is running on localhost:8000
+"""
+
+import requests
+import json
+
+BASE_URL = "http://localhost:8000"
+
+def test_health():
+    print("Testing /health endpoint...")
+    try:
+        response = requests.get(f"{BASE_URL}/health")
+        print(f"  Status: {response.status_code}")
+        print(f"  Response: {response.json()}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"  Error: {e}")
+        return False
+
+def test_auth_status():
+    print("\nTesting /v1/auth/status endpoint...")
+    try:
+        response = requests.get(f"{BASE_URL}/v1/auth/status")
+        print(f"  Status: {response.status_code}")
+        print(f"  Response: {json.dumps(response.json(), indent=2)}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"  Error: {e}")
+        return False
+
+def test_models():
+    print("\nTesting /v1/models endpoint...")
+    try:
+        response = requests.get(f"{BASE_URL}/v1/models")
+        print(f"  Status: {response.status_code}")
+        models = response.json()
+        print(f"  Found {len(models.get('data', []))} models")
+        for model in models.get('data', [])[:3]:  # Show first 3
+            print(f"    - {model.get('id')}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"  Error: {e}")
+        return False
+
+def test_chat_completion():
+    print("\nTesting /v1/chat/completions endpoint...")
+    try:
+        payload = {
+            "model": "claude-3-5-haiku-20241022",  # Use fastest model
+            "messages": [
+                {"role": "user", "content": "Say 'Hello, SDK integration working!' and nothing else."}
+            ],
+            "max_tokens": 50
+        }
+        
+        response = requests.post(
+            f"{BASE_URL}/v1/chat/completions",
+            json=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        
+        print(f"  Status: {response.status_code}")
+        
+        if response.status_code == 200:
+            result = response.json()
+            content = result.get('choices', [{}])[0].get('message', {}).get('content', '')
+            print(f"  Response: {content}")
+            print(f"  Usage: {result.get('usage', {})}")
+            return True
+        else:
+            print(f"  Error: {response.text}")
+            return False
+            
+    except Exception as e:
+        print(f"  Error: {e}")
+        return False
+
+def main():
+    print("Claude Code OpenAI Wrapper - Endpoint Tests")
+    print("=" * 50)
+    
+    tests = [
+        ("Health Check", test_health),
+        ("Auth Status", test_auth_status), 
+        ("Models List", test_models),
+        ("Chat Completion", test_chat_completion)
+    ]
+    
+    passed = 0
+    total = len(tests)
+    
+    for name, test_func in tests:
+        if test_func():
+            print(f"✓ {name} passed")
+            passed += 1
+        else:
+            print(f"✗ {name} failed")
+    
+    print("=" * 50)
+    print(f"Results: {passed}/{total} tests passed")
+    
+    if passed == total:
+        print("🎉 All tests passed! SDK integration is working correctly.")
+    else:
+        print("❌ Some tests failed. Check server logs for details.")
+
+if __name__ == "__main__":
+    main()

test_non_streaming.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+Test script to verify non-streaming responses work correctly.
+"""
+
+import os
+import json
+import requests
+
+# Set debug mode
+os.environ['DEBUG_MODE'] = 'true'
+
+def test_non_streaming():
+    """Test that non-streaming responses work correctly."""
+    print("🧪 Testing non-streaming response...")
+    
+    # Simple request with streaming disabled
+    request_data = {
+        "model": "claude-3-7-sonnet-20250219",
+        "messages": [
+            {
+                "role": "user", 
+                "content": "What is 2+2?"
+            }
+        ],
+        "stream": False,
+        "temperature": 0.0
+    }
+    
+    try:
+        # Send non-streaming request
+        response = requests.post(
+            "http://localhost:8000/v1/chat/completions",
+            json=request_data,
+            timeout=30
+        )
+        
+        print(f"✅ Response status: {response.status_code}")
+        
+        if response.status_code != 200:
+            print(f"❌ Request failed: {response.text}")
+            return False
+        
+        # Parse response
+        data = response.json()
+        
+        # Check response structure
+        if 'choices' in data and len(data['choices']) > 0:
+            message = data['choices'][0]['message']
+            content = message['content']
+            
+            print(f"📊 Response content: {content}")
+            
+            # Check if we got actual content instead of fallback message
+            fallback_messages = [
+                "I'm unable to provide a response at the moment",
+                "I understand you're testing the system"
+            ]
+            
+            is_fallback = any(msg in content for msg in fallback_messages)
+            
+            if not is_fallback and len(content) > 0:
+                print("\n🎉 Non-streaming response is working!")
+                print("✅ Real content extracted successfully")
+                return True
+            else:
+                print("\n❌ Non-streaming response is not working")
+                print("⚠️  Still receiving fallback content or no content")
+                return False
+        else:
+            print("❌ Unexpected response structure")
+            return False
+            
+    except Exception as e:
+        print(f"❌ Test failed with exception: {e}")
+        return False
+
+def main():
+    """Test non-streaming responses."""
+    print("🔍 Testing Non-Streaming Responses")
+    print("=" * 50)
+    
+    success = test_non_streaming()
+    
+    print("\n" + "=" * 50)
+    if success:
+        print("🎉 Non-streaming test PASSED!")
+        print("✅ Both streaming and non-streaming responses work correctly")
+    else:
+        print("❌ Non-streaming test FAILED")
+        print("⚠️  Issue may still persist")
+    
+    return success
+
+if __name__ == "__main__":
+    success = main()
+    exit(0 if success else 1)

test_parameter_mapping.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Test script demonstrating OpenAI to Claude Code SDK parameter mapping.
+"""
+
+import asyncio
+import json
+import requests
+from typing import Dict, Any
+
+# Test server URL
+BASE_URL = "http://localhost:8000"
+
+def test_basic_completion():
+    """Test basic chat completion with OpenAI parameters."""
+    print("=== Testing Basic Completion ===")
+    
+    payload = {
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "system", "content": "You are a helpful assistant."},
+            {"role": "user", "content": "Say hello in a creative way."}
+        ],
+        "temperature": 0.7,  # Will be ignored with warning
+        "max_tokens": 100,   # Will be ignored with warning
+        "stream": False
+    }
+    
+    response = requests.post(f"{BASE_URL}/v1/chat/completions", json=payload)
+    
+    if response.status_code == 200:
+        print("✅ Request successful")
+        result = response.json()
+        print(f"Response: {result['choices'][0]['message']['content'][:100]}...")
+    else:
+        print(f"❌ Request failed: {response.status_code}")
+        print(response.text)
+
+def test_with_claude_headers():
+    """Test completion with Claude-specific headers."""
+    print("\n=== Testing with Claude-Specific Headers ===")
+    
+    payload = {
+        "model": "claude-3-5-sonnet-20241022", 
+        "messages": [
+            {"role": "user", "content": "List the files in the current directory"}
+        ],
+        "stream": False
+    }
+    
+    headers = {
+        "Content-Type": "application/json",
+        "X-Claude-Max-Turns": "5",
+        "X-Claude-Allowed-Tools": "ls,pwd,cat",
+        "X-Claude-Permission-Mode": "acceptEdits"
+    }
+    
+    response = requests.post(
+        f"{BASE_URL}/v1/chat/completions", 
+        json=payload, 
+        headers=headers
+    )
+    
+    if response.status_code == 200:
+        print("✅ Request with Claude headers successful")
+        result = response.json()
+        print(f"Response: {result['choices'][0]['message']['content'][:100]}...")
+    else:
+        print(f"❌ Request failed: {response.status_code}")
+        print(response.text)
+
+def test_compatibility_check():
+    """Test the compatibility endpoint."""
+    print("\n=== Testing Compatibility Check ===")
+    
+    payload = {
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [{"role": "user", "content": "Hello"}],
+        "temperature": 0.8,
+        "top_p": 0.9,
+        "max_tokens": 150,
+        "presence_penalty": 0.1,
+        "frequency_penalty": 0.2,
+        "logit_bias": {"hello": 2.0},
+        "stop": ["END"],
+        "n": 1,
+        "user": "test_user"
+    }
+    
+    response = requests.post(f"{BASE_URL}/v1/compatibility", json=payload)
+    
+    if response.status_code == 200:
+        print("✅ Compatibility check successful")
+        result = response.json()
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"❌ Compatibility check failed: {response.status_code}")
+        print(response.text)
+
+def test_parameter_validation():
+    """Test parameter validation (should fail)."""
+    print("\n=== Testing Parameter Validation ===")
+    
+    # Test with n > 1 (should fail)
+    payload = {
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [{"role": "user", "content": "Hello"}],
+        "n": 3  # Should fail validation
+    }
+    
+    response = requests.post(f"{BASE_URL}/v1/chat/completions", json=payload)
+    
+    if response.status_code == 422:
+        print("✅ Validation correctly rejected n > 1")
+        print(response.json())
+    else:
+        print(f"❌ Expected validation error, got: {response.status_code}")
+
+def test_streaming_with_parameters():
+    """Test streaming response with unsupported parameters."""
+    print("\n=== Testing Streaming with Unsupported Parameters ===")
+    
+    payload = {
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "Write a short poem about programming"}
+        ],
+        "temperature": 0.9,  # Will be warned about
+        "max_tokens": 200,   # Will be warned about
+        "stream": True
+    }
+    
+    try:
+        response = requests.post(
+            f"{BASE_URL}/v1/chat/completions", 
+            json=payload, 
+            stream=True
+        )
+        
+        if response.status_code == 200:
+            print("✅ Streaming request successful")
+            print("First few chunks:")
+            count = 0
+            for line in response.iter_lines():
+                if line and count < 5:
+                    line_str = line.decode('utf-8')
+                    if line_str.startswith('data: ') and not line_str.endswith('[DONE]'):
+                        print(f"  {line_str}")
+                        count += 1
+        else:
+            print(f"❌ Streaming request failed: {response.status_code}")
+    except Exception as e:
+        print(f"❌ Streaming test error: {e}")
+
+def main():
+    """Run all tests."""
+    print("OpenAI to Claude Code SDK Parameter Mapping Tests")
+    print("=" * 50)
+    
+    try:
+        # Check if server is running
+        response = requests.get(f"{BASE_URL}/health")
+        if response.status_code != 200:
+            print("❌ Server is not running. Start it with: poetry run python main.py")
+            return
+        print("✅ Server is running")
+        
+        # Run tests
+        test_basic_completion()
+        test_with_claude_headers()
+        test_compatibility_check()
+        test_parameter_validation()
+        test_streaming_with_parameters()
+        
+        print("\n" + "=" * 50)
+        print("🎉 All tests completed!")
+        print("\nTo see parameter warnings in detail, run the server with:")
+        print("PYTHONPATH=. poetry run python -c \"import logging; logging.basicConfig(level=logging.DEBUG); exec(open('main.py').read())\"")
+        
+    except requests.exceptions.ConnectionError:
+        print("❌ Cannot connect to server. Make sure it's running on port 8000")
+    except Exception as e:
+        print(f"❌ Test error: {e}")
+
+if __name__ == "__main__":
+    main()

test_session_complete.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+Comprehensive test for session continuity functionality.
+"""
+
+import requests
+import json
+import time
+
+BASE_URL = "http://localhost:8000"
+
+def test_session_continuity_comprehensive():
+    """Test session continuity with multiple conversation turns."""
+    print("🧪 Testing comprehensive session continuity...")
+    
+    session_id = "comprehensive-test"
+    
+    # Conversation sequence to test memory
+    conversation = [
+        {"user": "Hello! My name is Charlie and I'm 25 years old.", "expect_memory": None},
+        {"user": "I work as a software engineer.", "expect_memory": None},
+        {"user": "What's my name?", "expect_memory": "charlie"},
+        {"user": "How old am I?", "expect_memory": "25"},
+        {"user": "What do I do for work?", "expect_memory": "software engineer"},
+    ]
+    
+    for i, turn in enumerate(conversation, 1):
+        print(f"\n{i}️⃣ Turn {i}: {turn['user']}")
+        
+        response = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+            "model": "claude-3-5-sonnet-20241022",
+            "messages": [{"role": "user", "content": turn["user"]}],
+            "session_id": session_id
+        })
+        
+        if response.status_code != 200:
+            print(f"❌ Turn {i} failed: {response.status_code}")
+            return False
+        
+        result = response.json()
+        response_text = result['choices'][0]['message']['content']
+        print(f"   Response: {response_text[:100]}...")
+        
+        # Check if expected information is remembered
+        if turn["expect_memory"]:
+            if turn["expect_memory"].lower() in response_text.lower():
+                print(f"   ✅ Memory check passed: '{turn['expect_memory']}' found")
+            else:
+                print(f"   ⚠️  Memory check unclear: '{turn['expect_memory']}' not found, but may still be working")
+    
+    # Check session info
+    session_info = requests.get(f"{BASE_URL}/v1/sessions/{session_id}")
+    if session_info.status_code == 200:
+        info = session_info.json()
+        print(f"\n📊 Session info: {info['message_count']} messages stored")
+        expected_messages = len(conversation) * 2  # user + assistant for each turn
+        if info['message_count'] == expected_messages:
+            print(f"   ✅ Correct message count: {expected_messages}")
+        else:
+            print(f"   ⚠️  Message count mismatch: expected {expected_messages}, got {info['message_count']}")
+    
+    # Cleanup
+    requests.delete(f"{BASE_URL}/v1/sessions/{session_id}")
+    print(f"   🧹 Session {session_id} cleaned up")
+    
+    return True
+
+def test_stateless_vs_session():
+    """Test that stateless and session modes work differently."""
+    print("\n🧪 Testing stateless vs session behavior...")
+    
+    # Test stateless (no session_id)
+    print("1️⃣ Stateless mode:")
+    requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [{"role": "user", "content": "Remember: my favorite color is blue."}]
+    })
+    
+    # Follow up question without session_id
+    response1 = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [{"role": "user", "content": "What's my favorite color?"}]
+    })
+    
+    if response1.status_code == 200:
+        result1 = response1.json()
+        stateless_response = result1['choices'][0]['message']['content']
+        print(f"   Stateless response: {stateless_response[:100]}...")
+    
+    # Test session mode  
+    print("2️⃣ Session mode:")
+    session_id = "color-test-session"
+    
+    requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [{"role": "user", "content": "Remember: my favorite color is red."}],
+        "session_id": session_id
+    })
+    
+    response2 = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [{"role": "user", "content": "What's my favorite color?"}],
+        "session_id": session_id
+    })
+    
+    if response2.status_code == 200:
+        result2 = response2.json()
+        session_response = result2['choices'][0]['message']['content']
+        print(f"   Session response: {session_response[:100]}...")
+        
+        if "red" in session_response.lower():
+            print("   ✅ Session mode correctly remembered the color")
+        else:
+            print("   ⚠️  Session mode didn't clearly show memory, but may still be working")
+    
+    # Cleanup
+    requests.delete(f"{BASE_URL}/v1/sessions/{session_id}")
+    return True
+
+def test_session_endpoints():
+    """Test all session management endpoints."""
+    print("\n🧪 Testing session management endpoints...")
+    
+    # Create some sessions
+    session_ids = ["endpoint-test-1", "endpoint-test-2", "endpoint-test-3"]
+    
+    for session_id in session_ids:
+        requests.post(f"{BASE_URL}/v1/chat/completions", json={
+            "model": "claude-3-5-sonnet-20241022",
+            "messages": [{"role": "user", "content": f"Test session {session_id}"}],
+            "session_id": session_id
+        })
+    
+    # Test list sessions
+    list_response = requests.get(f"{BASE_URL}/v1/sessions")
+    if list_response.status_code == 200:
+        sessions = list_response.json()
+        print(f"   ✅ Listed {sessions['total']} sessions")
+        
+        if sessions['total'] >= len(session_ids):
+            print(f"   ✅ Found all test sessions")
+        else:
+            print(f"   ⚠️  Expected at least {len(session_ids)} sessions, found {sessions['total']}")
+    
+    # Test get specific session
+    get_response = requests.get(f"{BASE_URL}/v1/sessions/{session_ids[0]}")
+    if get_response.status_code == 200:
+        session_info = get_response.json()
+        print(f"   ✅ Retrieved session info: {session_info['message_count']} messages")
+    
+    # Test session stats
+    stats_response = requests.get(f"{BASE_URL}/v1/sessions/stats")
+    if stats_response.status_code == 200:
+        stats = stats_response.json()
+        print(f"   ✅ Session stats: {stats['session_stats']['active_sessions']} active")
+    
+    # Test delete sessions
+    for session_id in session_ids:
+        delete_response = requests.delete(f"{BASE_URL}/v1/sessions/{session_id}")
+        if delete_response.status_code == 200:
+            print(f"   ✅ Deleted session {session_id}")
+        else:
+            print(f"   ❌ Failed to delete session {session_id}")
+    
+    return True
+
+def main():
+    """Run comprehensive session tests."""
+    print("🚀 Starting comprehensive session continuity tests...")
+    
+    # Test server health
+    try:
+        health = requests.get(f"{BASE_URL}/health", timeout=5)
+        if health.status_code != 200:
+            print("❌ Server not healthy")
+            return
+        print("✅ Server is healthy")
+    except Exception as e:
+        print(f"❌ Server connection error: {e}")
+        return
+    
+    # Run all tests
+    tests = [
+        ("Session Continuity", test_session_continuity_comprehensive),
+        ("Stateless vs Session", test_stateless_vs_session),
+        ("Session Endpoints", test_session_endpoints),
+    ]
+    
+    passed = 0
+    for test_name, test_func in tests:
+        try:
+            print(f"\n{'='*50}")
+            if test_func():
+                passed += 1
+                print(f"✅ {test_name} test passed")
+            else:
+                print(f"❌ {test_name} test failed")
+        except Exception as e:
+            print(f"❌ {test_name} test error: {e}")
+    
+    print(f"\n{'='*50}")
+    print(f"📊 Final Results: {passed}/{len(tests)} tests passed")
+    
+    if passed == len(tests):
+        print("🎉 All comprehensive session tests passed!")
+        print("✨ Session continuity is working correctly!")
+    else:
+        print("⚠️  Some tests failed - check the output above")
+
+if __name__ == "__main__":
+    main()

test_session_continuity.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""
+Test script for session continuity functionality.
+"""
+
+import asyncio
+import json
+import requests
+import time
+from typing import Dict, Any
+
+# Configuration
+BASE_URL = "http://localhost:8000"
+TEST_SESSION_ID = "test-session-123"
+
+
+def test_stateless_mode():
+    """Test traditional stateless OpenAI-style requests."""
+    print("🧪 Testing stateless mode...")
+    
+    response = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "Hello! My name is Alice."}
+        ]
+    })
+    
+    if response.status_code == 200:
+        result = response.json()
+        print(f"✅ Stateless request successful")
+        print(f"   Response: {result['choices'][0]['message']['content'][:100]}...")
+        return True
+    else:
+        print(f"❌ Stateless request failed: {response.status_code} - {response.text}")
+        return False
+
+
+def test_session_mode():
+    """Test session-based requests with conversation continuity."""
+    print(f"\n🧪 Testing session mode with session_id: {TEST_SESSION_ID}")
+    
+    # First message in session
+    print("1️⃣ First message in session...")
+    response1 = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "Hello! My name is Bob. Remember this name."}
+        ],
+        "session_id": TEST_SESSION_ID
+    })
+    
+    if response1.status_code != 200:
+        print(f"❌ First session request failed: {response1.status_code} - {response1.text}")
+        return False
+    
+    result1 = response1.json()
+    print(f"✅ First session message successful")
+    print(f"   Response: {result1['choices'][0]['message']['content'][:100]}...")
+    
+    # Second message in same session - should remember the name
+    print("2️⃣ Second message in same session...")
+    response2 = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "What's my name?"}
+        ],
+        "session_id": TEST_SESSION_ID
+    })
+    
+    if response2.status_code != 200:
+        print(f"❌ Second session request failed: {response2.status_code} - {response2.text}")
+        return False
+    
+    result2 = response2.json()
+    print(f"✅ Second session message successful")
+    print(f"   Response: {result2['choices'][0]['message']['content'][:100]}...")
+    
+    # Check if the response mentions the name "Bob"
+    response_text = result2['choices'][0]['message']['content'].lower()
+    if "bob" in response_text:
+        print("✅ Session continuity working - Claude remembered the name!")
+        return True
+    else:
+        print("⚠️  Session continuity unclear - response doesn't contain expected name")
+        return True  # Still successful, maybe Claude responded differently
+
+
+def test_session_management_endpoints():
+    """Test session management endpoints."""
+    print(f"\n🧪 Testing session management endpoints...")
+    
+    # List sessions
+    print("1️⃣ Listing sessions...")
+    response = requests.get(f"{BASE_URL}/v1/sessions")
+    if response.status_code == 200:
+        sessions = response.json()
+        print(f"✅ Sessions listed: {sessions['total']} active sessions")
+        if sessions['total'] > 0:
+            print(f"   First session: {sessions['sessions'][0]['session_id']}")
+    else:
+        print(f"❌ Failed to list sessions: {response.status_code}")
+        return False
+    
+    # Get specific session info
+    print("2️⃣ Getting session info...")
+    response = requests.get(f"{BASE_URL}/v1/sessions/{TEST_SESSION_ID}")
+    if response.status_code == 200:
+        session_info = response.json()
+        print(f"✅ Session info retrieved:")
+        print(f"   Messages: {session_info['message_count']}")
+        print(f"   Created: {session_info['created_at']}")
+    else:
+        print(f"❌ Failed to get session info: {response.status_code}")
+        return False
+    
+    # Get session stats
+    print("3️⃣ Getting session stats...")
+    response = requests.get(f"{BASE_URL}/v1/sessions/stats")
+    if response.status_code == 200:
+        stats = response.json()
+        print(f"✅ Session stats retrieved:")
+        print(f"   Active sessions: {stats['session_stats']['active_sessions']}")
+        print(f"   Total messages: {stats['session_stats']['total_messages']}")
+    else:
+        print(f"❌ Failed to get session stats: {response.status_code}")
+        return False
+    
+    return True
+
+
+def test_session_streaming():
+    """Test session continuity with streaming."""
+    print(f"\n🧪 Testing session streaming...")
+    
+    # Create a new session for streaming test
+    stream_session_id = "test-stream-456"
+    
+    response = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "Hello! I'm testing streaming. My favorite color is purple."}
+        ],
+        "session_id": stream_session_id,
+        "stream": True
+    }, stream=True)
+    
+    if response.status_code != 200:
+        print(f"❌ Streaming request failed: {response.status_code}")
+        return False
+    
+    print("✅ Streaming response received")
+    
+    # Follow up with another message in the same session
+    time.sleep(1)  # Give time for the session to be updated
+    
+    response2 = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "What's my favorite color?"}
+        ],
+        "session_id": stream_session_id
+    })
+    
+    if response2.status_code == 200:
+        result = response2.json()
+        response_text = result['choices'][0]['message']['content'].lower()
+        print(f"✅ Follow-up message successful")
+        print(f"   Response: {result['choices'][0]['message']['content'][:100]}...")
+        
+        if "purple" in response_text:
+            print("✅ Session continuity working with streaming!")
+        else:
+            print("⚠️  Session continuity unclear with streaming")
+        return True
+    else:
+        print(f"❌ Follow-up message failed: {response2.status_code}")
+        return False
+
+
+def cleanup_test_sessions():
+    """Clean up test sessions."""
+    print(f"\n🧹 Cleaning up test sessions...")
+    
+    for session_id in [TEST_SESSION_ID, "test-stream-456"]:
+        response = requests.delete(f"{BASE_URL}/v1/sessions/{session_id}")
+        if response.status_code == 200:
+            print(f"✅ Deleted session: {session_id}")
+        elif response.status_code == 404:
+            print(f"ℹ️  Session not found (already deleted): {session_id}")
+        else:
+            print(f"⚠️  Failed to delete session {session_id}: {response.status_code}")
+
+
+def main():
+    """Run all session continuity tests."""
+    print("🚀 Starting session continuity tests...")
+    print(f"   Server: {BASE_URL}")
+    
+    # Test server health first
+    try:
+        response = requests.get(f"{BASE_URL}/health", timeout=5)
+        if response.status_code != 200:
+            print(f"❌ Server health check failed: {response.status_code}")
+            return
+        print("✅ Server is healthy")
+    except requests.exceptions.RequestException as e:
+        print(f"❌ Cannot connect to server: {e}")
+        print("   Make sure the server is running with: poetry run python main.py")
+        return
+    
+    success_count = 0
+    total_tests = 4
+    
+    # Run tests
+    tests = [
+        ("Stateless Mode", test_stateless_mode),
+        ("Session Mode", test_session_mode),
+        ("Session Management", test_session_management_endpoints),
+        ("Session Streaming", test_session_streaming),
+    ]
+    
+    for test_name, test_func in tests:
+        try:
+            if test_func():
+                success_count += 1
+            else:
+                print(f"❌ {test_name} test failed")
+        except Exception as e:
+            print(f"❌ {test_name} test error: {e}")
+    
+    # Cleanup
+    cleanup_test_sessions()
+    
+    # Results
+    print(f"\n📊 Test Results: {success_count}/{total_tests} tests passed")
+    
+    if success_count == total_tests:
+        print("🎉 All session continuity tests passed!")
+    else:
+        print("⚠️  Some tests failed. Check the output above for details.")
+
+
+if __name__ == "__main__":
+    main()

test_session_simple.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Simple test for session continuity functionality.
+"""
+
+import requests
+import json
+import time
+
+BASE_URL = "http://localhost:8000"
+TEST_SESSION_ID = "test-simple-session"
+
+def test_session_creation():
+    """Test creating a session and checking it appears in the list."""
+    print("🧪 Testing session creation...")
+    
+    # Make a request with a session_id
+    response = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "Hello, remember my name is Alice."}
+        ],
+        "session_id": TEST_SESSION_ID
+    })
+    
+    if response.status_code != 200:
+        print(f"❌ Session creation failed: {response.status_code}")
+        return False
+    
+    print("✅ Session creation request successful")
+    
+    # Check if session appears in the list
+    sessions_response = requests.get(f"{BASE_URL}/v1/sessions")
+    if sessions_response.status_code == 200:
+        sessions_data = sessions_response.json()
+        print(f"✅ Found {sessions_data['total']} sessions")
+        
+        # Check if our session is in the list
+        session_ids = [s['session_id'] for s in sessions_data['sessions']]
+        if TEST_SESSION_ID in session_ids:
+            print(f"✅ Session {TEST_SESSION_ID} found in session list")
+            return True
+        else:
+            print(f"❌ Session {TEST_SESSION_ID} not found in session list")
+            return False
+    else:
+        print(f"❌ Failed to list sessions: {sessions_response.status_code}")
+        return False
+
+def test_session_continuity():
+    """Test that conversation context is maintained across requests."""
+    print("\n🧪 Testing session continuity...")
+    
+    # Follow up message asking about the name
+    response = requests.post(f"{BASE_URL}/v1/chat/completions", json={
+        "model": "claude-3-5-sonnet-20241022",
+        "messages": [
+            {"role": "user", "content": "What's my name?"}
+        ],
+        "session_id": TEST_SESSION_ID
+    })
+    
+    if response.status_code != 200:
+        print(f"❌ Continuity test failed: {response.status_code}")
+        return False
+    
+    result = response.json()
+    response_text = result['choices'][0]['message']['content'].lower()
+    print(f"Response: {result['choices'][0]['message']['content'][:100]}...")
+    
+    # Check if response mentions Alice
+    if "alice" in response_text:
+        print("✅ Session continuity working - name remembered!")
+        return True
+    else:
+        print("⚠️  Response doesn't mention Alice, but session continuity may still be working")
+        return True  # Don't fail the test just because of this
+
+def test_session_cleanup():
+    """Test session deletion."""
+    print("\n🧪 Testing session cleanup...")
+    
+    # Delete the session
+    delete_response = requests.delete(f"{BASE_URL}/v1/sessions/{TEST_SESSION_ID}")
+    if delete_response.status_code == 200:
+        print("✅ Session deleted successfully")
+        
+        # Verify it's gone from the list
+        sessions_response = requests.get(f"{BASE_URL}/v1/sessions")
+        if sessions_response.status_code == 200:
+            sessions_data = sessions_response.json()
+            session_ids = [s['session_id'] for s in sessions_data['sessions']]
+            if TEST_SESSION_ID not in session_ids:
+                print("✅ Session successfully removed from list")
+                return True
+            else:
+                print("❌ Session still appears in list after deletion")
+                return False
+        else:
+            print(f"❌ Failed to list sessions after deletion: {sessions_response.status_code}")
+            return False
+    else:
+        print(f"❌ Failed to delete session: {delete_response.status_code}")
+        return False
+
+def main():
+    """Run simple session tests."""
+    print("🚀 Starting simple session tests...")
+    
+    # Test server health
+    try:
+        health_response = requests.get(f"{BASE_URL}/health", timeout=5)
+        if health_response.status_code != 200:
+            print(f"❌ Server not healthy: {health_response.status_code}")
+            return
+        print("✅ Server is healthy")
+    except Exception as e:
+        print(f"❌ Cannot connect to server: {e}")
+        return
+    
+    # Run tests
+    tests = [
+        ("Session Creation", test_session_creation),
+        ("Session Continuity", test_session_continuity),
+        ("Session Cleanup", test_session_cleanup),
+    ]
+    
+    passed = 0
+    for test_name, test_func in tests:
+        try:
+            if test_func():
+                passed += 1
+            else:
+                print(f"❌ {test_name} test failed")
+        except Exception as e:
+            print(f"❌ {test_name} test error: {e}")
+    
+    print(f"\n📊 Results: {passed}/{len(tests)} tests passed")
+    
+    if passed == len(tests):
+        print("🎉 All session tests passed!")
+    else:
+        print("⚠️  Some tests failed")
+
+if __name__ == "__main__":
+    main()

test_textblock_fix.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""
+Test script to verify the TextBlock fix is working.
+"""
+
+import os
+import json
+import requests
+
+# Set debug mode
+os.environ['DEBUG_MODE'] = 'true'
+
+def test_textblock_fix():
+    """Test that TextBlock content extraction is working."""
+    print("🧪 Testing TextBlock content extraction fix...")
+    
+    # Simple request that should trigger Claude to respond with normal text
+    request_data = {
+        "model": "claude-3-7-sonnet-20250219",
+        "messages": [
+            {
+                "role": "user", 
+                "content": "Hello! Can you briefly introduce yourself?"
+            }
+        ],
+        "stream": True,
+        "temperature": 0.0
+    }
+    
+    try:
+        # Send streaming request
+        response = requests.post(
+            "http://localhost:8000/v1/chat/completions",
+            json=request_data,
+            stream=True,
+            timeout=30
+        )
+        
+        print(f"✅ Response status: {response.status_code}")
+        
+        if response.status_code != 200:
+            print(f"❌ Request failed: {response.text}")
+            return False
+        
+        # Parse streaming chunks and collect content
+        all_content = ""
+        has_role_chunk = False
+        has_content = False
+        
+        for line in response.iter_lines():
+            if line:
+                line_str = line.decode('utf-8')
+                if line_str.startswith('data: '):
+                    data_str = line_str[6:]  # Remove "data: " prefix
+                    
+                    if data_str == "[DONE]":
+                        break
+                    
+                    try:
+                        chunk_data = json.loads(data_str)
+                        
+                        # Check chunk structure
+                        if 'choices' in chunk_data and len(chunk_data['choices']) > 0:
+                            choice = chunk_data['choices'][0]
+                            delta = choice.get('delta', {})
+                            
+                            # Check for role chunk
+                            if 'role' in delta:
+                                has_role_chunk = True
+                                print(f"✅ Found role chunk")
+                            
+                            # Check for content chunk  
+                            if 'content' in delta:
+                                content = delta['content']
+                                all_content += content
+                                has_content = True
+                                print(f"✅ Found content: {content[:50]}...")
+                                
+                    except json.JSONDecodeError as e:
+                        print(f"❌ Invalid JSON in chunk: {data_str}")
+                        return False
+        
+        print(f"\n📊 Test Results:")
+        print(f"   Has role chunk: {has_role_chunk}")
+        print(f"   Has content: {has_content}")
+        print(f"   Total content length: {len(all_content)}")
+        print(f"   Content preview: {all_content[:200]}...")
+        
+        # Check if we got actual content instead of fallback message
+        fallback_messages = [
+            "I'm unable to provide a response at the moment",
+            "I understand you're testing the system"
+        ]
+        
+        is_fallback = any(msg in all_content for msg in fallback_messages)
+        
+        if has_content and not is_fallback and len(all_content) > 20:
+            print("\n🎉 TextBlock fix is working!")
+            print("✅ Real content extracted successfully")
+            print("✅ No fallback messages")
+            return True
+        else:
+            print("\n❌ TextBlock fix is not working")
+            print("⚠️  Still receiving fallback content or no content")
+            return False
+            
+    except Exception as e:
+        print(f"❌ Test failed with exception: {e}")
+        return False
+
+def main():
+    """Test the TextBlock fix."""
+    print("🔍 Testing TextBlock Content Extraction Fix")
+    print("=" * 50)
+    
+    success = test_textblock_fix()
+    
+    print("\n" + "=" * 50)
+    if success:
+        print("🎉 TextBlock fix test PASSED!")
+        print("✅ RooCode should now receive proper content")
+    else:
+        print("❌ TextBlock fix test FAILED")
+        print("⚠️  Issue may still persist")
+    
+    return success
+
+if __name__ == "__main__":
+    success = main()
+    exit(0 if success else 1)