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.