docs/CHAT_AS_A_SERVICE.md

# Chat-as-a-Service Integration Guide

## Overview

The Multi-Language Chat Agent can be used as a service by external applications. This guide explains how to integrate the chat service into your application, manage sessions, and handle different use cases.

## Architecture

```
┌─────────────────┐    HTTP/REST API    ┌─────────────────┐
│   Your App      │◄──────────────────►│   Chat Service  │
│                 │                     │   (This App)    │
└─────────────────┘                     └─────────────────┘
                                                 │
                                                 ▼
                                    ┌─────────────────┐
                                    │   Groq API      │
                                    │   Redis Cache   │
                                    │   PostgreSQL    │
                                    └─────────────────┘
```

## Session Management

### How Sessions Work

1. **Session Creation**: Each user gets a unique session per programming language
2. **Session Persistence**: Sessions are stored in PostgreSQL with Redis caching
3. **Session Isolation**: Each session maintains its own conversation history
4. **Session Expiry**: Sessions automatically expire after inactivity (configurable)

### Session Lifecycle

```python
# 1. Create Session
POST /api/v1/chat/sessions
{
    "language": "python",
    "metadata": {"user_type": "student", "course": "CS101"}
}
# Returns: {"session_id": "uuid", "user_id": "your-user", ...}

# 2. Send Messages
POST /api/v1/chat/sessions/{session_id}/message
{
    "content": "What is a Python list?",
    "language": "python"  # optional override
}
# Returns: {"response": "A Python list is...", ...}

# 3. Manage Session
GET /api/v1/chat/sessions/{session_id}           # Get session info
PUT /api/v1/chat/sessions/{session_id}/language  # Switch language
DELETE /api/v1/chat/sessions/{session_id}        # Delete session
```

## Integration Patterns

### 1. Single User, Multiple Languages

```python
from examples.chat_service_client import ChatServiceClient

client = ChatServiceClient("http://localhost:5000", "MyApp")

# Create sessions for different languages
python_session = client.create_session("user123", "python")
js_session = client.create_session("user123", "javascript")

# Send language-specific questions
python_response = client.send_message(python_session['session_id'], "How do I create a list?")
js_response = client.send_message(js_session['session_id'], "How do I create an array?")
```

### 2. Multiple Users, Shared Service

```python
from examples.chat_service_client import MultiUserChatManager

manager = MultiUserChatManager("http://localhost:5000", "LearningPlatform")

# Start chats for multiple users
manager.start_chat_for_user("student1", "python")
manager.start_chat_for_user("student2", "javascript")

# Send messages for specific users
response1 = manager.send_user_message("student1", "What are Python functions?")
response2 = manager.send_user_message("student2", "What are JS functions?")
```

### 3. Anonymous/Guest Users

```python
from examples.integration_examples import WebsiteChatbot

chatbot = WebsiteChatbot("http://localhost:5000")

# Handle anonymous users with browser ID
browser_id = "browser_12345"  # From cookies/localStorage
chat_data = chatbot.start_anonymous_chat(browser_id, "python")

# Continue conversation
response = chatbot.continue_anonymous_chat(browser_id, "What is Python?")
```

## Authentication & Security

### User Identification

The service uses the `X-User-ID` header to identify users:

```python
headers = {
    "X-User-ID": "your-app-user-123",
    "Content-Type": "application/json"
}
```

### Session Ownership

- Users can only access their own sessions
- Session ownership is validated on every request
- Cross-user access returns 403 Forbidden

### Rate Limiting

Default rate limits (configurable):
- Session creation: 10 per minute
- Message sending: 30 per minute
- Other endpoints: 20 per minute

## Error Handling

### Common Error Responses

```python
# Session not found
{
    "error": "Session not found",
    "code": 404
}

# Session expired
{
    "error": "Session has expired", 
    "code": 410
}

# Rate limit exceeded
{
    "error": "Rate limit exceeded",
    "code": 429,
    "retry_after": 60
}

# Invalid language
{
    "error": "Unsupported language: xyz. Supported: python, javascript, java...",
    "code": 400
}
```

### Error Handling Best Practices

```python
import requests

def safe_api_call(url, headers, data):
    try:
        response = requests.post(url, headers=headers, json=data, timeout=30)
        
        if response.status_code == 429:
            # Rate limited - wait and retry
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            return safe_api_call(url, headers, data)
        
        elif response.status_code == 410:
            # Session expired - create new session
            return create_new_session_and_retry(data)
        
        elif response.status_code >= 400:
            error_data = response.json()
            raise Exception(f"API Error: {error_data.get('error', 'Unknown error')}")
        
        return response.json()
        
    except requests.exceptions.Timeout:
        raise Exception("Request timeout - service may be overloaded")
    except requests.exceptions.ConnectionError:
        raise Exception("Cannot connect to chat service")
```

## Use Case Examples

### 1. Learning Management System (LMS)

```python
class LMSIntegration:
    def __init__(self):
        self.chat_manager = MultiUserChatManager("http://chat-service:5000", "LMS")
    
    def enroll_student(self, student_id, course_id):
        # Map course to programming language
        language_map = {
            "python-101": "python",
            "js-fundamentals": "javascript",
            "java-oop": "java"
        }
        
        language = language_map.get(course_id, "python")
        user_id = f"{student_id}_{course_id}"
        
        # Create session with course context
        session_id = self.chat_manager.start_chat_for_user(
            user_id, 
            language,
            {"student_id": student_id, "course_id": course_id}
        )
        
        return session_id
    
    def student_ask_question(self, student_id, course_id, question):
        user_id = f"{student_id}_{course_id}"
        response = self.chat_manager.send_user_message(user_id, question)
        return response['response']
```

### 2. Code Editor Plugin

```python
class CodeEditorPlugin:
    def __init__(self):
        self.client = ChatServiceClient("http://chat-service:5000", "CodeEditor")
        self.user_sessions = {}
    
    def explain_code(self, user_id, language, code_snippet, question):
        # Get or create session for this language
        session_id = self.get_session_for_language(user_id, language)
        
        # Format question with code context
        formatted_question = f"""
I have this {language} code:
```{language}
{code_snippet}
```
{question}
"""
        
        response = self.client.send_message(session_id, formatted_question)
        return response['response']
    
    def get_session_for_language(self, user_id, language):
        key = f"{user_id}_{language}"
        if key not in self.user_sessions:
            session = self.client.create_session(key, language)
            self.user_sessions[key] = session['session_id']
        return self.user_sessions[key]
```

### 3. Mobile App with Offline Support

```python
class MobileAppIntegration:
    def __init__(self):
        self.chat_manager = MultiUserChatManager("http://chat-service:5000", "MobileApp")
        self.offline_queue = {}
    
    def send_message_with_offline(self, user_id, message):
        try:
            # Try to send immediately
            response = self.chat_manager.send_user_message(user_id, message)
            return {"status": "sent", "response": response['response']}
        
        except Exception:
            # Queue for later if offline
            if user_id not in self.offline_queue:
                self.offline_queue[user_id] = []
            
            self.offline_queue[user_id].append(message)
            return {"status": "queued", "message": "Will send when online"}
    
    def sync_offline_messages(self, user_id):
        if user_id not in self.offline_queue:
            return {"synced": 0}
        
        messages = self.offline_queue[user_id]
        synced = 0
        
        for message in messages:
            try:
                self.chat_manager.send_user_message(user_id, message)
                synced += 1
            except Exception:
                break
        
        # Remove synced messages
        self.offline_queue[user_id] = messages[synced:]
        if not self.offline_queue[user_id]:
            del self.offline_queue[user_id]
        
        return {"synced": synced, "remaining": len(messages) - synced}
```

## Deployment Considerations

### Scaling the Service

1. **Horizontal Scaling**: Run multiple instances behind a load balancer
2. **Database Scaling**: Use PostgreSQL read replicas for heavy read workloads
3. **Redis Clustering**: Use Redis cluster for high availability caching
4. **API Gateway**: Use an API gateway for rate limiting and authentication

### Configuration for Production

```bash
# Environment variables for production
GROQ_API_KEY=your-production-api-key
DATABASE_URL=postgresql://user:pass@db-cluster:5432/chatdb
REDIS_URL=redis://redis-cluster:6379/0

# Rate limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_STORAGE=redis

# Session management
SESSION_TIMEOUT=7200  # 2 hours
CLEANUP_INTERVAL=300  # 5 minutes

# Security
SECRET_KEY=your-production-secret-key
CORS_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
```

### Monitoring & Observability

```python
# Health check endpoint
GET /api/v1/chat/health

# Response
{
    "status": "healthy",
    "services": {
        "database": "connected",
        "redis": "connected",
        "groq_api": "available"
    },
    "timestamp": "2023-01-01T00:00:00Z"
}
```

### Docker Deployment

```yaml
# docker-compose.yml
version: '3.8'
services:
  chat-service:
    build: .
    ports:
      - "5000:5000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/chatdb
      - REDIS_URL=redis://redis:6379/0
      - GROQ_API_KEY=${GROQ_API_KEY}
    depends_on:
      - db
      - redis
  
  db:
    image: postgres:13
    environment:
      - POSTGRES_DB=chatdb
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  redis:
    image: redis:6-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:
```

## Best Practices

### 1. Session Management
- Create sessions per user per language context
- Clean up expired sessions regularly
- Use meaningful metadata for tracking

### 2. Error Handling
- Implement retry logic for transient failures
- Handle rate limiting gracefully
- Provide fallback responses when service is unavailable

### 3. Performance
- Cache session IDs in your application
- Batch operations when possible
- Use connection pooling for HTTP requests

### 4. Security
- Validate user IDs before making requests
- Use HTTPS in production
- Implement proper authentication in your app

### 5. Monitoring
- Monitor API response times
- Track error rates and types
- Set up alerts for service health

## Testing Your Integration

```python
# Test script for your integration
def test_chat_integration():
    client = ChatServiceClient("http://localhost:5000", "TestApp")
    
    # Test health
    health = client.health_check()
    assert health['status'] == 'healthy'
    
    # Test session creation
    session = client.create_session("test-user", "python")
    assert 'session_id' in session
    
    # Test message sending
    response = client.send_message(session['session_id'], "What is Python?")
    assert 'response' in response
    assert len(response['response']) > 0
    
    # Test language switching
    switch_result = client.switch_language(session['session_id'], "javascript")
    assert switch_result['new_language'] == 'javascript'
    
    # Cleanup
    client.delete_session(session['session_id'])
    
    print("✅ All integration tests passed!")

if __name__ == "__main__":
    test_chat_integration()
```

## Support & Troubleshooting

### Common Issues

1. **Connection Refused**: Check if the service is running on the correct port
2. **Session Not Found**: Session may have expired, create a new one
3. **Rate Limited**: Implement exponential backoff retry logic
4. **Invalid Language**: Check supported languages via `/api/v1/chat/languages`

### Getting Help

- Check the API documentation at `/api/v1/chat/` (when service is running)
- Review logs for detailed error messages
- Use the health check endpoint to verify service status

---

This guide provides everything you need to integrate the chat service into your application. The service is designed to be stateless and scalable, making it suitable for production use across different types of applications.