Re_Backend/docs/VERTEX_AI_INTEGRATION.md

# Vertex AI Gemini Integration

## Overview

The AI service has been migrated from multi-provider support (Claude, OpenAI, Gemini API) to **Google Cloud Vertex AI Gemini** using service account authentication. This provides better enterprise-grade security and uses the same credentials as Google Cloud Storage.

## Changes Made

### 1. Package Dependencies

**Removed:**
- `@anthropic-ai/sdk` (Claude SDK)
- `@google/generative-ai` (Gemini API SDK)
- `openai` (OpenAI SDK)

**Added:**
- `@google-cloud/vertexai` (Vertex AI SDK)

### 2. Service Account Authentication

The AI service now uses the same service account JSON file as GCS:
- **Location**: `credentials/re-platform-workflow-dealer-3d5738fcc1f9.json`
- **Project ID**: `re-platform-workflow-dealer`
- **Default Region**: `us-central1`

### 3. Configuration

**Environment Variables:**
```env
# Required (already configured for GCS)
GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json

# Optional (defaults provided)
VERTEX_AI_MODEL=gemini-2.5-flash
VERTEX_AI_LOCATION=asia-south1
AI_ENABLED=true
```

**Admin Panel Configuration:**
- `AI_ENABLED` - Enable/disable AI features
- `VERTEX_AI_MODEL` - Model name (default: `gemini-2.5-flash`)
- `AI_MAX_REMARK_LENGTH` - Maximum characters for conclusion remarks (default: 2000)

### 4. Available Models

| Model Name | Description | Use Case |
|------------|-------------|----------|
| `gemini-2.5-flash` | Latest fast model (default) | General purpose, quick responses |
| `gemini-1.5-flash` | Previous fast model | General purpose |
| `gemini-1.5-pro` | Advanced model | Complex tasks, better quality |
| `gemini-1.5-pro-latest` | Latest Pro version | Best quality, complex reasoning |

### 5. Supported Regions

| Region Code | Location | Availability |
|-------------|----------|--------------|
| `us-central1` | Iowa, USA | ✅ Default |
| `us-east1` | South Carolina, USA | ✅ |
| `us-west1` | Oregon, USA | ✅ |
| `europe-west1` | Belgium | ✅ |
| `asia-south1` | Mumbai, India | ✅ |

## Setup Instructions

### Step 1: Install Dependencies

```bash
cd Re_Backend
npm install
```

This will install `@google-cloud/vertexai` and remove old AI SDKs.

### Step 2: Verify Service Account Permissions

Ensure your service account (`re-bridge-workflow@re-platform-workflow-dealer.iam.gserviceaccount.com`) has:
- **Vertex AI User** role (`roles/aiplatform.user`)

### Step 3: Enable Vertex AI API

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Navigate to **APIs & Services** > **Library**
3. Search for **"Vertex AI API"**
4. Click **Enable**

### Step 4: Verify Configuration

Check that your `.env` file has:
```env
GCP_PROJECT_ID=re-platform-workflow-dealer
GCP_KEY_FILE=./credentials/re-platform-workflow-dealer-3d5738fcc1f9.json
VERTEX_AI_MODEL=gemini-2.5-flash
VERTEX_AI_LOCATION=us-central1
```

### Step 5: Test the Integration

Start the backend and check logs for:
```
[AI Service] ✅ Vertex AI provider initialized successfully with model: gemini-2.5-flash
```

## API Interface (Unchanged)

The public API remains the same - no changes needed in controllers or routes:

```typescript
// Check if AI is available
aiService.isAvailable(): boolean

// Get provider name
aiService.getProviderName(): string

// Generate conclusion remark
aiService.generateConclusionRemark(context): Promise<{
  remark: string;
  confidence: number;
  keyPoints: string[];
  provider: string;
}>

// Reinitialize (after config changes)
aiService.reinitialize(): Promise<void>
```

## Troubleshooting

### Error: "Module not found: @google-cloud/vertexai"

**Solution:**
```bash
npm install @google-cloud/vertexai
```

### Error: "Service account key file not found"

**Solution:**
- Verify file exists at: `credentials/re-platform-workflow-dealer-3d5738fcc1f9.json`
- Check `GCP_KEY_FILE` path in `.env` is correct
- Ensure file has read permissions

### Error: "Model was not found or your project does not have access"

**Solution:**
- Verify Vertex AI API is enabled in Google Cloud Console
- Check model name is correct (e.g., `gemini-2.5-flash`)
- Ensure model is available in your selected region
- Verify service account has `roles/aiplatform.user` role

### Error: "Permission denied"

**Solution:**
- Verify service account has Vertex AI User role
- Check service account key hasn't been revoked
- Regenerate service account key if needed

### Error: "API not enabled"

**Solution:**
- Enable Vertex AI API in Google Cloud Console
- Wait a few minutes for propagation
- Restart the backend service

## Migration Notes

### What Changed
- ✅ Removed multi-provider support (Claude, OpenAI, Gemini API)
- ✅ Now uses Vertex AI Gemini exclusively
- ✅ Uses service account authentication (same as GCS)
- ✅ Simplified configuration (no API keys needed)

### What Stayed the Same
- ✅ Public API interface (`aiService` methods)
- ✅ Conclusion generation functionality
- ✅ Admin panel configuration structure
- ✅ Error handling and logging

### Backward Compatibility
- ✅ Existing code using `aiService` will work without changes
- ✅ Conclusion controller unchanged
- ✅ Admin panel can still enable/disable AI features
- ✅ Configuration cache system still works

## Verification Checklist

- [ ] `@google-cloud/vertexai` package installed
- [ ] Service account key file exists and is valid
- [ ] Vertex AI API is enabled in Google Cloud Console
- [ ] Service account has `Vertex AI User` role
- [ ] `.env` file has correct `GCP_PROJECT_ID` and `GCP_KEY_FILE`
- [ ] Backend logs show successful initialization
- [ ] AI conclusion generation works for test requests

## Support

For issues or questions:
1. Check backend logs for detailed error messages
2. Verify Google Cloud Console settings
3. Ensure service account permissions are correct
4. Test with a simple request to isolate issues