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)

# Install package
npm install @anthropic-ai/sdk

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

Option 2: OpenAI

# Install package
npm install openai

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

Option 3: Gemini

# 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:

# 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:

# 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:

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

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

# Restart backend
npm run dev

Option B: Multi-Provider Setup (Automatic Failover)

Configure multiple API keys for automatic failover:

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:

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:

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:

npm install @anthropic-ai/sdk

Provider not working

Check logs for initialization errors:

# 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:

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.