Re_Backend/AI_PROVIDER_SETUP.md

# AI Provider Configuration Guide

The Workflow Management System supports multiple AI providers for generating conclusion remarks. The system uses a **provider-agnostic architecture** with automatic fallback, making it easy to switch between providers.

## Supported Providers

| Provider | Environment Variable | Model Used | Installation |
|----------|---------------------|------------|--------------|
| **Claude (Anthropic)** | `CLAUDE_API_KEY` or `ANTHROPIC_API_KEY` | `claude-3-5-sonnet-20241022` | `npm install @anthropic-ai/sdk` |
| **OpenAI (GPT)** | `OPENAI_API_KEY` | `gpt-4o` | `npm install openai` |
| **Gemini (Google)** | `GEMINI_API_KEY` or `GOOGLE_AI_API_KEY` | `gemini-1.5-pro` | `npm install @google/generative-ai` |

---

## Quick Start

### Option 1: Claude (Recommended)

```bash
# Install package
npm install @anthropic-ai/sdk

# Set environment variable
AI_PROVIDER=claude
CLAUDE_API_KEY=sk-ant-xxxxxxxxxxxxx
```

### Option 2: OpenAI

```bash
# Install package
npm install openai

# Set environment variable
AI_PROVIDER=openai
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
```

### Option 3: Gemini

```bash
# Install package
npm install @google/generative-ai

# Set environment variable
AI_PROVIDER=gemini
GEMINI_API_KEY=xxxxxxxxxxxxx
```

---

## Configuration

### 1. Set Preferred Provider (Optional)

Add to your `.env` file:

```bash
# Preferred AI provider (claude, openai, or gemini)
# Default: claude
AI_PROVIDER=claude
```

### 2. Add API Key

Add the corresponding API key for your chosen provider:

```bash
# For Claude (Anthropic)
CLAUDE_API_KEY=sk-ant-xxxxxxxxxxxxx

# For OpenAI
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx

# For Gemini (Google)
GEMINI_API_KEY=xxxxxxxxxxxxx
```

---

## Automatic Fallback

The system has built-in intelligence to handle provider failures:

1. **Primary**: Tries the provider specified in `AI_PROVIDER`
2. **Fallback**: If primary fails, tries other available providers in order
3. **Graceful Degradation**: If no provider is available, shows error to user

**Example Startup Logs:**

```
info: [AI Service] Preferred provider: claude
info: [AI Service] ✅ Claude provider initialized
info: [AI Service] ✅ Active provider: Claude (Anthropic)
```

**Example Fallback:**

```
info: [AI Service] Preferred provider: openai
warn: [AI Service] OpenAI API key not configured.
warn: [AI Service] Preferred provider unavailable. Trying fallbacks...
info: [AI Service] ✅ Claude provider initialized
info: [AI Service] ✅ Using fallback provider: Claude (Anthropic)
```

---

## Provider Comparison

### Claude (Anthropic)
- ✅ **Best for**: Professional, well-structured summaries
- ✅ **Strengths**: Excellent at following instructions, consistent output
- ✅ **Pricing**: Moderate (pay-per-token)
- ⚠️ **Requires**: API key from console.anthropic.com

### OpenAI (GPT-4)
- ✅ **Best for**: General-purpose text generation
- ✅ **Strengths**: Fast, widely adopted, good documentation
- ✅ **Pricing**: Moderate to high
- ⚠️ **Requires**: API key from platform.openai.com

### Gemini (Google)
- ✅ **Best for**: Cost-effective solution
- ✅ **Strengths**: Free tier available, good performance
- ✅ **Pricing**: Free tier + paid tiers
- ⚠️ **Requires**: API key from ai.google.dev

---

## Switching Providers

### Option A: Simple Switch (via .env)

Just change the `AI_PROVIDER` variable and restart the server:

```bash
# Old
AI_PROVIDER=claude
CLAUDE_API_KEY=sk-ant-xxxxxxxxxxxxx

# New
AI_PROVIDER=openai
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
```

```bash
# Restart backend
npm run dev
```

### Option B: Multi-Provider Setup (Automatic Failover)

Configure multiple API keys for automatic failover:

```bash
AI_PROVIDER=claude
CLAUDE_API_KEY=sk-ant-xxxxxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
GEMINI_API_KEY=xxxxxxxxxxxxx
```

If Claude fails, the system automatically tries OpenAI, then Gemini.

---

## Testing AI Generation

### 1. Check if AI is configured:

```bash
curl http://localhost:5000/api/v1/health
```

Look for logs:
```
info: [AI Service] ✅ Active provider: Claude (Anthropic)
```

### 2. Test conclusion generation:

1. Create a workflow request
2. Complete all approvals (as final approver)
3. As initiator, click "Finalize & Close Request"
4. Click "Generate with AI"
5. Review AI-generated conclusion
6. Edit if needed
7. Finalize

---

## Troubleshooting

### Error: "AI Service not configured"

**Solution**: Add at least one API key to `.env`:
```bash
CLAUDE_API_KEY=your-key-here
# OR
OPENAI_API_KEY=your-key-here
# OR
GEMINI_API_KEY=your-key-here
```

### Error: "Cannot find module '@anthropic-ai/sdk'"

**Solution**: Install the required package:
```bash
npm install @anthropic-ai/sdk
```

### Provider not working

**Check logs** for initialization errors:
```bash
# Successful
info: [AI Service] ✅ Claude provider initialized

# Failed
error: [AI Service] Failed to initialize Claude: Invalid API key
```

**Verify API key**:
- Claude: Should start with `sk-ant-`
- OpenAI: Should start with `sk-proj-` or `sk-`
- Gemini: No specific prefix

---

## Cost Management

### Estimated Costs (per conclusion generation):

| Provider | Tokens | Cost (approx) |
|----------|--------|---------------|
| Claude Sonnet | ~500 input + ~300 output | $0.004 |
| GPT-4o | ~500 input + ~300 output | $0.005 |
| Gemini Pro | ~500 input + ~300 output | Free tier or $0.0001 |

**Tips to reduce costs:**
- Use Gemini for development/testing (free tier)
- Use Claude/OpenAI for production
- Monitor usage via provider dashboards

---

## Security Best Practices

1. **Never commit API keys** to version control
2. **Use environment variables** for all sensitive data
3. **Rotate keys regularly** (every 3-6 months)
4. **Set rate limits** on provider dashboards
5. **Monitor usage** to detect anomalies

---

## Adding a New Provider

To add a new AI provider (e.g., Cohere, Hugging Face):

1. **Create Provider Class**:

```typescript
class NewProvider implements AIProvider {
  private client: any = null;
  
  constructor() {
    const apiKey = process.env.NEW_PROVIDER_API_KEY;
    if (!apiKey) return;
    
    try {
      const SDK = require('new-provider-sdk');
      this.client = new SDK({ apiKey });
    } catch (error) {
      logger.error('Failed to initialize NewProvider:', error);
    }
  }
  
  async generateText(prompt: string): Promise<string> {
    // Implementation
  }
  
  isAvailable(): boolean {
    return this.client !== null;
  }
  
  getProviderName(): string {
    return 'NewProvider';
  }
}
```

2. **Register in AIService**:

Add to constructor's switch statement and fallback array.

3. **Update Documentation**: Add to this README.

---

## Support

For issues with AI providers:
- **Claude**: https://docs.anthropic.com
- **OpenAI**: https://platform.openai.com/docs
- **Gemini**: https://ai.google.dev/docs

For system-specific issues, check application logs or contact the development team.