QwenClaw-with-Auth/docs/QWEN-SETUP.md

# Qwen Provider Setup Guide

## Overview

QwenClaw uses **Qwen** as the default AI provider. This guide shows you how to configure and use Qwen with the Rig service.

---

## Quick Start

### 1. Get Your Qwen API Key

1. Visit: https://platform.qwen.ai/
2. Sign up or log in
3. Go to **API Keys** section
4. Click **Create New API Key**
5. Copy your key (starts with `sk-...`)

### 2. Configure Rig Service

Create `.env` file in `rig-service/`:

```bash
cd rig-service
cp .env.example .env
```

Edit `.env`:

```env
# Qwen API Configuration (REQUIRED)
QWEN_API_KEY=sk-your-actual-key-here
QWEN_BASE_URL=https://api.qwen.ai/v1

# Defaults (Qwen is default for QwenClaw)
RIG_DEFAULT_PROVIDER=qwen
RIG_DEFAULT_MODEL=qwen-plus

# Server settings
RIG_HOST=127.0.0.1
RIG_PORT=8080
```

### 3. Start Rig Service

```bash
# Build
cargo build --release

# Start
cargo run --release
```

### 4. Verify Connection

```bash
curl http://127.0.0.1:8080/health
# Should return: {"status":"ok","service":"qwenclaw-rig"}
```

---

## Available Qwen Models

| Model | Description | Use Case |
|-------|-------------|----------|
| `qwen-plus` | **Default** - Balanced performance | General tasks |
| `qwen-max` | Most powerful | Complex reasoning |
| `qwen-turbo` | Fastest, cheapest | Simple tasks |
| `qwen-long` | Long context (256K) | Document analysis |

---

## Using Qwen with Rig

### TypeScript Client

```typescript
import { initRigClient } from "./src/rig";

const rig = initRigClient();

// Create agent with Qwen
const sessionId = await rig.createAgent({
  name: "assistant",
  preamble: "You are a helpful assistant.",
  provider: "qwen",      // Use Qwen
  model: "qwen-plus",    // Qwen model
});

// Execute prompt
const result = await rig.executePrompt(sessionId, "Hello!");
console.log(result);
```

### HTTP API

```bash
# Create agent with Qwen
curl -X POST http://127.0.0.1:8080/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "assistant",
    "preamble": "You are helpful.",
    "provider": "qwen",
    "model": "qwen-plus"
  }'

# Execute prompt
curl -X POST http://127.0.0.1:8080/api/agents/{SESSION_ID}/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello!"}'
```

### Multi-Agent Council with Qwen

```typescript
const councilId = await rig.createCouncil("Research Team", [
  {
    name: "researcher",
    preamble: "You research thoroughly.",
    provider: "qwen",
    model: "qwen-max",  // Use most powerful for research
  },
  {
    name: "writer",
    preamble: "You write clearly.",
    provider: "qwen",
    model: "qwen-plus",  // Balanced for writing
  },
]);

const result = await rig.executeCouncil(councilId, "Write a report");
```

---

## Alternative Providers

### OpenAI (Fallback)

```env
# In rig-service/.env
OPENAI_API_KEY=sk-...
RIG_DEFAULT_PROVIDER=openai
RIG_DEFAULT_MODEL=gpt-4o
```

### Anthropic Claude

```env
# In rig-service/.env
ANTHROPIC_API_KEY=sk-ant-...
RIG_DEFAULT_PROVIDER=anthropic
RIG_DEFAULT_MODEL=claude-3-5-sonnet
```

### Ollama (Local)

```env
# In rig-service/.env
RIG_DEFAULT_PROVIDER=ollama
RIG_DEFAULT_MODEL=qwen2.5:7b
# No API key needed - runs locally
```

---

## Troubleshooting

### "QWEN_API_KEY not set"

**Error:**
```
Error: QWEN_API_KEY not set. Get it from https://platform.qwen.ai
```

**Solution:**
1. Get API key from https://platform.qwen.ai
2. Add to `rig-service/.env`:
   ```env
   QWEN_API_KEY=sk-your-key
   ```
3. Restart Rig service

### "Invalid API key"

**Error:**
```
Rig prompt execution failed: Invalid API key
```

**Solution:**
1. Verify API key is correct (no extra spaces)
2. Check key is active in Qwen dashboard
3. Ensure sufficient credits/quota

### Connection Timeout

**Error:**
```
Failed to connect to Qwen API
```

**Solution:**
1. Check internet connection
2. Verify `QWEN_BASE_URL` is correct
3. Try alternative: `https://api.qwen.ai/v1`

---

## Cost Optimization

### Use Appropriate Models

| Task | Recommended Model | Cost |
|------|------------------|------|
| Simple Q&A | `qwen-turbo` | $ |
| General tasks | `qwen-plus` | $$ |
| Complex reasoning | `qwen-max` | $$$ |
| Long documents | `qwen-long` | $$ |

### Example: Task-Based Routing

```typescript
// Simple task - use turbo
const simpleAgent = await rig.createAgent({
  name: "quick",
  model: "qwen-turbo",
});

// Complex task - use max
const complexAgent = await rig.createAgent({
  name: "analyst",
  model: "qwen-max",
});
```

---

## API Reference

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `QWEN_API_KEY` | ✅ For Qwen | - | Your Qwen API key |
| `QWEN_BASE_URL` | ❌ | `https://api.qwen.ai/v1` | API endpoint |
| `RIG_DEFAULT_PROVIDER` | ❌ | `qwen` | Default provider |
| `RIG_DEFAULT_MODEL` | ❌ | `qwen-plus` | Default model |

### Provider Values

| Value | Provider | Models |
|-------|----------|--------|
| `qwen` | Qwen | qwen-plus, qwen-max, qwen-turbo |
| `openai` | OpenAI | gpt-4o, gpt-4, gpt-3.5 |
| `anthropic` | Anthropic | claude-3-5-sonnet, claude-3 |
| `ollama` | Ollama | Any local model |

---

## Resources

- **Qwen Platform**: https://platform.qwen.ai/
- **Qwen Docs**: https://help.qwen.ai/
- **Pricing**: https://qwen.ai/pricing
- **Rig Integration**: `docs/RIG-INTEGRATION.md`

---

## Support

Issues? Check:
1. `docs/RIG-STATUS.md` - Known issues
2. Rig service logs: `cargo run --release --verbose`
3. Qwen status: https://status.qwen.ai/