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