int-layer/docs/rag-migration-guide.md

# RAG Migration Guide

## Overview

This guide explains how to migrate from Dialogflow CX to the RAG (Retrieval-Augmented Generation) server for intent detection and response generation.

## Architecture

The integration layer now supports **both Dialogflow and RAG** implementations through a common interface (`IntentDetectionService`). You can switch between them using a configuration property.

```
┌─────────────────────────────────────────┐
│  ConversationManagerService /           │
│  NotificationManagerService             │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│    IntentDetectionService (interface)   │
└────────────┬────────────────────────────┘
             │
      ┌──────┴──────┐
      │             │
      ▼             ▼
┌──────────┐  ┌──────────┐
│Dialogflow│  │   RAG    │
│ Client   │  │  Client  │
└──────────┘  └──────────┘
```

## Quick Start

### 1. Configure the RAG Server

Set the following environment variables:

```bash
# Select RAG as the intent detection client
export INTENT_DETECTION_CLIENT=rag

# RAG server URL
export RAG_SERVER_URL=https://your-rag-server.com

# Optional: API key for authentication
export RAG_SERVER_API_KEY=your-api-key-here

# Optional: Customize timeouts and retries (defaults shown)
export RAG_SERVER_TIMEOUT=30s
export RAG_SERVER_RETRY_MAX_ATTEMPTS=3
export RAG_SERVER_RETRY_BACKOFF=1s
```

### 2. Deploy and Test

Deploy the application with the new configuration:

```bash
# Using Docker
docker build -t capa-integracion:rag .
docker run -e INTENT_DETECTION_CLIENT=rag \
           -e RAG_SERVER_URL=https://your-rag-server.com \
           capa-integracion:rag

# Or using Maven
mvn spring-boot:run -Dspring-boot.run.profiles=dev
```

### 3. Monitor Logs

On startup, you should see:

```
✓ Intent detection configured to use RAG client
RAG Client initialized successfully with endpoint: https://your-rag-server.com
```

## Configuration Reference

### Intent Detection Selection

| Property | Values | Default | Description |
|----------|--------|---------|-------------|
| `intent.detection.client` | `dialogflow`, `rag` | `dialogflow` | Selects which implementation to use |

### RAG Server Configuration

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `rag.server.url` | URL | `http://localhost:8080` | RAG server base URL |
| `rag.server.timeout` | Duration | `30s` | HTTP request timeout |
| `rag.server.retry.max-attempts` | Integer | `3` | Maximum retry attempts on errors |
| `rag.server.retry.backoff` | Duration | `1s` | Initial backoff duration for retries |
| `rag.server.api-key` | String | (empty) | Optional API key for authentication |

### Dialogflow Configuration (Kept for Rollback)

These properties remain unchanged and are used when `intent.detection.client=dialogflow`:

```properties
dialogflow.cx.project-id=${DIALOGFLOW_CX_PROJECT_ID}
dialogflow.cx.location=${DIALOGFLOW_CX_LOCATION}
dialogflow.cx.agent-id=${DIALOGFLOW_CX_AGENT_ID}
dialogflow.default-language-code=${DIALOGFLOW_DEFAULT_LANGUAGE_CODE:es}
```

## Switching Between Implementations

### Switch to RAG

```bash
export INTENT_DETECTION_CLIENT=rag
```

### Switch Back to Dialogflow

```bash
export INTENT_DETECTION_CLIENT=dialogflow
```

**No code changes required!** Just restart the application.

## What Stays the Same

✅ **External API contracts** - Controllers remain unchanged
✅ **DTOs** - `DetectIntentRequestDTO` and `DetectIntentResponseDTO` unchanged
✅ **Conversation storage** - Memorystore + Firestore persistence unchanged
✅ **DLP obfuscation** - Data Loss Prevention flow unchanged
✅ **Session management** - 30-minute timeout logic unchanged
✅ **Notification handling** - Notification storage and retrieval unchanged

## What Changes

### RAG Receives:
- Phone number (for internal conversation history tracking)
- Obfuscated user input (already processed by DLP)
- Notification context (when applicable)

### RAG Returns:
- Response text (generated by RAG)
- Response ID (for tracking)
- Optional parameters (extracted/computed by RAG)

## Data Flow

### Conversation Flow
```
User Message
    ↓
DLP Obfuscation
    ↓
ConversationManagerService
    ↓
IntentDetectionService (RAG or Dialogflow)
    ↓
RagRequestMapper → RAG Server → RagResponseMapper
    ↓
DetectIntentResponseDTO
    ↓
Persist to Memorystore + Firestore
    ↓
Response to User
```

### Notification Flow
```
Notification Event
    ↓
DLP Obfuscation
    ↓
NotificationManagerService
    ↓
Store Notification (Memorystore + Firestore)
    ↓
IntentDetectionService (RAG or Dialogflow)
    ↓
RagRequestMapper → RAG Server → RagResponseMapper
    ↓
DetectIntentResponseDTO
    ↓
Response to User
```

## Redundancy by Design

The integration layer intentionally maintains **redundant functionality** to ensure safe migration:

1. **Conversation History**
   - Integration layer: Continues to store history in Memorystore + Firestore
   - RAG server: Maintains its own history by phone number
   - **Why:** Allows gradual migration without data loss

2. **Session Management**
   - Integration layer: Continues to enforce 30-minute timeout
   - RAG server: Handles session internally by phone number
   - **Why:** Preserves existing business logic

3. **Parameter Passing**
   - Integration layer: Continues to extract and pass all parameters
   - RAG server: Uses only what it needs (phone number, text, notifications)
   - **Why:** Maintains flexibility for future requirements

## Troubleshooting

### RAG Server Not Responding

**Symptom:** Errors like "RAG connection failed" or "RAG request timeout"

**Solution:**
1. Verify `RAG_SERVER_URL` is correct
2. Check RAG server is running and accessible
3. Verify network connectivity
4. Check RAG server logs for errors
5. Temporarily switch back to Dialogflow:
   ```bash
   export INTENT_DETECTION_CLIENT=dialogflow
   ```

### Invalid RAG Response Format

**Symptom:** Errors like "Failed to parse RAG response"

**Solution:**
1. Verify RAG server implements the API specification (see `docs/rag-api-specification.md`)
2. Check RAG server response format matches expected structure
3. Review `RagResponseMapper` logs for specific parsing errors

### Missing Phone Number

**Symptom:** Error "Phone number is required in request parameters"

**Solution:**
1. Verify external requests include phone number in user data
2. Check `ExternalConvRequestMapper` correctly maps phone number to `telefono` parameter

### Dialogflow Fallback Issues

**Symptom:** After switching back to Dialogflow, errors occur

**Solution:**
1. Verify all Dialogflow environment variables are still set:
   - `DIALOGFLOW_CX_PROJECT_ID`
   - `DIALOGFLOW_CX_LOCATION`
   - `DIALOGFLOW_CX_AGENT_ID`
2. Check Dialogflow credentials are valid

## Rollback Plan

If issues arise with RAG, immediately rollback:

### Step 1: Switch Configuration
```bash
export INTENT_DETECTION_CLIENT=dialogflow
```

### Step 2: Restart Application
```bash
# Docker
docker restart <container-id>

# Kubernetes
kubectl rollout restart deployment/capa-integracion
```

### Step 3: Verify
Check logs for:
```
✓ Intent detection configured to use Dialogflow CX client
Dialogflow CX SessionsClient initialized successfully
```

## Monitoring

### Key Metrics to Monitor

1. **Response Time**
   - RAG should respond within 2 seconds (p95)
   - Monitor: Log entries with "RAG query successful"

2. **Error Rate**
   - Target: < 0.5% error rate
   - Monitor: Log entries with "RAG query failed"

3. **Retry Rate**
   - Monitor: Log entries with "Retrying RAG call"
   - High retry rate may indicate RAG server issues

4. **Response Quality**
   - Monitor user satisfaction or conversation completion rates
   - Compare before/after RAG migration

### Log Patterns

**Successful RAG Call:**
```
INFO  Initiating RAG query for session: <session-id>
DEBUG Successfully mapped request to RAG format
INFO  RAG query successful for session: <session-id>, response ID: <response-id>
```

**Failed RAG Call:**
```
ERROR RAG server error for session <session-id>: status=500
WARN  Retrying RAG call for session <session-id> due to status code: 500
ERROR RAG retries exhausted for session <session-id>
```

## Testing

### Manual Testing

1. **Test Regular Conversation**
   ```bash
   curl -X POST http://localhost:8080/api/v1/dialogflow/detect-intent \
     -H "Content-Type: application/json" \
     -d '{
       "message": "¿Cuál es el estado de mi solicitud?",
       "user": {
         "telefono": "573001234567",
         "nickname": "TestUser"
       },
       "channel": "web",
       "tipo": "text"
     }'
   ```

2. **Test Notification Flow**
   ```bash
   curl -X POST http://localhost:8080/api/v1/dialogflow/notification \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Tu documento ha sido aprobado",
       "phoneNumber": "573001234567",
       "hiddenParameters": {
         "document_id": "DOC-2025-001"
       }
     }'
   ```

### Expected Behavior

- RAG should return relevant responses based on conversation context
- Response time should be similar to or better than Dialogflow
- All parameters should be preserved in conversation history
- Notification context should be used in RAG responses

## Migration Phases (Recommended)

### Phase 1: Development Testing (1 week)
- Deploy RAG to dev environment
- Set `INTENT_DETECTION_CLIENT=rag`
- Test all conversation flows manually
- Verify notification handling

### Phase 2: QA Environment (1 week)
- Deploy to QA with RAG enabled
- Run automated test suite
- Perform load testing
- Compare responses with Dialogflow baseline

### Phase 3: Production Pilot (1-2 weeks)
- Deploy to production with `INTENT_DETECTION_CLIENT=dialogflow` (Dialogflow still active)
- Gradually switch to RAG:
  - Week 1: 10% of traffic
  - Week 2: 50% of traffic
  - Week 3: 100% of traffic
- Monitor metrics closely

### Phase 4: Full Migration
- Set `INTENT_DETECTION_CLIENT=rag` for all environments
- Keep Dialogflow config for potential rollback
- Monitor for 2 weeks before considering removal of Dialogflow dependencies

## Future Cleanup (Optional)

After RAG is stable in production for 1+ month:

### Phase 1: Deprecate Dialogflow
1. Add `@Deprecated` annotation to `DialogflowClientService`
2. Update documentation to mark Dialogflow as legacy

### Phase 2: Remove Dependencies (Optional)
Edit `pom.xml` and remove:
```xml
<!-- Can be removed after RAG is stable -->
<!--
<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-dialogflow-cx</artifactId>
</dependency>
<dependency>
    <groupId>com.google.protobuf</groupId>
    <artifactId>protobuf-java-util</artifactId>
</dependency>
<dependency>
    <groupId>com.google.api</groupId>
    <artifactId>gax</artifactId>
</dependency>
-->
```

### Phase 3: Code Cleanup
1. Remove `DialogflowClientService.java`
2. Remove `DialogflowRequestMapper.java`
3. Remove `DialogflowResponseMapper.java`
4. Remove Dialogflow-specific tests
5. Update documentation

**Note:** Only proceed with cleanup after confirming no rollback will be needed.

## Support

For issues or questions:
1. Check this guide and `docs/rag-api-specification.md`
2. Review application logs
3. Contact the RAG server team for API issues
4. Contact the integration layer team for mapping/configuration issues

## Summary

- **Minimal Code Changes:** Only configuration needed to switch
- **Safe Rollback:** Can switch back to Dialogflow instantly
- **Redundancy:** Both systems store data for safety
- **Gradual Migration:** Supports phased rollout
- **No External Impact:** API contracts unchanged