# Ask API - Edge Worker

Edge service for interacting with multiple LLM providers via a unified API.

## Architecture

```
src/worker/
├── @worker.ts              # Main worker entry point
├── adapters/
│   ├── cloudflare.ts       # Cloudflare Workers adapter
│   └── debug.ts            # Local development adapter
├── controllers/
│   └── completion.ts       # Completion endpoint logic
├── modules/
│   ├── LlmManager.ts       # Provider orchestration
│   └── handlers/
│       ├── BaseHandler.ts  # Abstract handler interface
│       ├── OpenAiHandler.ts
│       └── AnthropicHandler.ts
├── routes/
│   └── v1/
│       ├── index.ts        # V1 route registry
│       ├── completion.ts   # Completion routes
│       └── models.ts       # Models list routes
└── types/
    └── index.ts            # TypeScript interfaces
```

## Supported Providers

- ✅ **OpenAI** - GPT-4, GPT-3.5, o1, o3-mini
- ✅ **Anthropic** - Claude 3.5, Claude 3 Opus/Sonnet/Haiku
- 🚧 **Google** - Gemini (coming soon)
- 🚧 **Groq** - Fast inference (coming soon)
- 🚧 **OpenRouter** - Multi-provider aggregator (coming soon)

## API Endpoints

### POST /v1/completion
Main completion endpoint supporting both streaming and sync responses.

**Request:**
```json
{
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "systemPrompt": "You are a helpful assistant.",
  "config": {
    "provider": "openai",
    "model": "gpt-4",
    "temperature": 0.7,
    "maxTokens": 2000,
    "stream": true
  }
}
```

**Response (streaming):**
```
data: {"delta": "Hello"}
data: {"delta": " there"}
data: [DONE]
```

**Response (sync):**
```json
{
  "content": "Hello there!",
  "model": "gpt-4",
  "usage": { ... }
}
```

### GET /v1/models
List all supported models across providers.

### GET /v1/health
Health check endpoint.

## Local Development

### Setup

1. Copy environment variables:
```bash
cp .env.example .env
# Edit .env and add your API keys
```

2. Install dependencies:
```bash
npm install
```

3. Start development server:
```bash
npm run worker:dev
# or with auto-reload:
npm run worker:watch
```

4. Test the API:
```bash
curl -X POST http://localhost:59898/v1/completion \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}],
    "config": {
      "provider": "openai",
      "model": "gpt-3.5-turbo",
      "stream": false
    }
  }'
```

## Cloudflare Workers Deployment

### Prerequisites

1. Install Wrangler CLI:
```bash
npm install -g wrangler
```

2. Login to Cloudflare:
```bash
wrangler login
```

### Deploy

1. Set API keys as secrets:
```bash
wrangler secret put OPENAI_API_KEY
wrangler secret put ANTHROPIC_API_KEY
# ... other providers
```

2. Deploy to development:
```bash
npm run worker:deploy:dev
```

3. Deploy to production:
```bash
npm run worker:deploy
```

4. View logs:
```bash
npm run worker:tail
```

## Configuration

### API Keys

API keys can be provided in three ways:

1. **Environment Variables** (recommended for production):
   Set as Cloudflare Worker secrets via `wrangler secret put`

2. **Request Headers** (for per-user keys):
   ```bash
   curl -H "x-openai-api-key: sk-..." http://localhost:59898/v1/completion
   ```

3. **Environment File** (local development only):
   Add to `.env` file

### Provider Configuration

Each provider handler supports different features:

- **OpenAI**: All models, including o1/o3 (reasoning models)
- **Anthropic**: Claude 3.x and 4.x with proper temperature/top_p handling

## Multi-Modal Support

### Image Input

```json
{
  "messages": [
    {
      "role": "user",
      "content": "What's in this image?",
      "files": [
        {
          "url": "https://example.com/image.png",
          "type": "image/png"
        }
      ]
    }
  ],
  "config": {
    "provider": "openai",
    "model": "gpt-4-vision-preview"
  }
}
```

## Error Handling

Errors are returned in a consistent format:

```json
{
  "error": "Error message",
  "timestamp": "2025-10-08T12:00:00.000Z"
}
```

## Performance

- **Cold Start**: <50ms (Cloudflare Workers)
- **Latency**: <100ms to first token (depending on provider)
- **Throughput**: Scales automatically

## Security

- API keys stored as encrypted secrets
- CORS enabled for specified origins
- Input validation on all requests
- Rate limiting (coming soon)

## Testing

```bash
# Run unit tests
npm test

# Run integration tests
npm run test:integration
```

## License

MIT