Deploy RAG chatbot backend API

Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.10-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port 7860 (default for HF Spaces)
+EXPOSE 7860
+
+# Run the application
+CMD ["uvicorn", "rag_agent:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,28 @@
 ---
-title: Chatbot Deploy
-emoji: 🏢
-colorFrom: red
-colorTo: blue
+title: RAG Chatbot API
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
 sdk: docker
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# RAG Chatbot API
+
+A Retrieval-Augmented Generation (RAG) API for documentation Q&A.
+
+## API Endpoints
+
+- `POST /query` - Submit a question and get an answer with sources
+- `GET /health` - Health check endpoint
+- `GET /docs` - Swagger API documentation
+
+## Environment Variables
+
+Set these in your HF Space secrets:
+
+- `OPENAI_API_KEY` - OpenAI API key
+- `QDRANT_URL` - Qdrant cloud URL
+- `QDRANT_API_KEY` - Qdrant API key
+- `COHERE_API_KEY` - Cohere API key (for embeddings)

config/__init__.py

@@ -0,0 +1 @@
+# Config package

config/logging_config.py

@@ -0,0 +1,130 @@
+"""
+Logging Configuration for RAG Agent API
+
+Provides structured JSON logging for all components of the RAG Agent.
+Logs include timestamp, level, component name, message, and contextual data.
+
+Usage:
+    from config.logging_config import setup_logging, get_logger
+
+    setup_logging()
+    logger = get_logger('rag_agent')
+    logger.info("Message", extra={"query": "test", "latency_ms": 123})
+"""
+
+import logging
+import json
+import sys
+from datetime import datetime
+from typing import Any, Dict
+
+
+class JSONFormatter(logging.Formatter):
+    """
+    Custom formatter that outputs logs as JSON.
+
+    Format:
+        {
+            "timestamp": "2025-12-21T10:30:00Z",
+            "level": "INFO",
+            "component": "rag_agent",
+            "message": "Query processed",
+            "context": {"query": "...", "latency_ms": 123}
+        }
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Format log record as JSON string.
+
+        Args:
+            record: LogRecord to format
+
+        Returns:
+            JSON-formatted log string
+        """
+        log_data: Dict[str, Any] = {
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "level": record.levelname,
+            "component": record.name,
+            "message": record.getMessage(),
+        }
+
+        # Add any extra context from the log call
+        if hasattr(record, 'query'):
+            log_data['query'] = record.query
+        if hasattr(record, 'latency_ms'):
+            log_data['latency_ms'] = record.latency_ms
+        if hasattr(record, 'tokens_used'):
+            log_data['tokens_used'] = record.tokens_used
+        if hasattr(record, 'model'):
+            log_data['model'] = record.model
+        if hasattr(record, 'status_code'):
+            log_data['status_code'] = record.status_code
+        if hasattr(record, 'error_type'):
+            log_data['error_type'] = record.error_type
+
+        # Include exception info if present
+        if record.exc_info:
+            log_data['exception'] = self.formatException(record.exc_info)
+
+        return json.dumps(log_data)
+
+
+def setup_logging(level: str = "INFO", json_format: bool = False) -> None:
+    """
+    Configure logging for the application.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR)
+        json_format: If True, use JSON formatter; otherwise use standard format
+
+    Example:
+        >>> setup_logging(level="DEBUG", json_format=True)
+    """
+    log_level = getattr(logging, level.upper(), logging.INFO)
+
+    # Create handler for stdout
+    handler = logging.StreamHandler(sys.stdout)
+
+    if json_format:
+        handler.setFormatter(JSONFormatter())
+    else:
+        # Standard format for development
+        formatter = logging.Formatter(
+            '[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S'
+        )
+        handler.setFormatter(formatter)
+
+    # Configure root logger
+    logging.root.setLevel(log_level)
+    logging.root.handlers = [handler]
+
+    # Set levels for noisy libraries
+    logging.getLogger('httpx').setLevel(logging.WARNING)
+    logging.getLogger('httpcore').setLevel(logging.WARNING)
+    logging.getLogger('openai').setLevel(logging.WARNING)
+    logging.getLogger('urllib3').setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance for a component.
+
+    Args:
+        name: Component name (e.g., 'rag_agent', 'retrieval', 'generation')
+
+    Returns:
+        Logger instance
+
+    Example:
+        >>> logger = get_logger('rag_agent')
+        >>> logger.info("Processing query", extra={"query": "test"})
+    """
+    return logging.getLogger(name)
+
+
+# Default setup for imports
+if __name__ != "__main__":
+    setup_logging()

exceptions.py

@@ -0,0 +1,126 @@
+"""
+Custom Exceptions for RAG Agent API
+
+Exception classes for different error types in the RAG pipeline.
+
+Exceptions:
+    RAGException: Base exception for all RAG Agent errors
+    ValidationError: Request validation failures
+    RetrievalError: Document retrieval failures
+    GenerationError: Answer generation failures
+    RateLimitError: API rate limit exceeded
+"""
+
+
+class RAGException(Exception):
+    """
+    Base exception for all RAG Agent errors.
+
+    Attributes:
+        message: Error message
+        status_code: HTTP status code
+        error_type: Error classification
+    """
+
+    def __init__(self, message: str, status_code: int = 500, error_type: str = "UnknownError"):
+        """
+        Initialize RAG exception.
+
+        Args:
+            message: Error message
+            status_code: HTTP status code (default 500)
+            error_type: Error classification (default "UnknownError")
+        """
+        self.message = message
+        self.status_code = status_code
+        self.error_type = error_type
+        super().__init__(self.message)
+
+
+class ValidationError(RAGException):
+    """
+    Exception for request validation failures.
+
+    Raised when:
+        - Query is empty or invalid
+        - top_k is out of range
+        - Model name is invalid
+
+    Status Code: 422 Unprocessable Entity
+    """
+
+    def __init__(self, message: str):
+        """
+        Initialize validation error.
+
+        Args:
+            message: Validation error message
+        """
+        super().__init__(message, status_code=422, error_type="ValidationError")
+
+
+class RetrievalError(RAGException):
+    """
+    Exception for document retrieval failures.
+
+    Raised when:
+        - Qdrant database is unavailable
+        - Cohere API fails to embed query
+        - Network errors during retrieval
+
+    Status Code: 503 Service Unavailable
+    """
+
+    def __init__(self, message: str):
+        """
+        Initialize retrieval error.
+
+        Args:
+            message: Retrieval error message
+        """
+        super().__init__(message, status_code=503, error_type="RetrievalError")
+
+
+class GenerationError(RAGException):
+    """
+    Exception for answer generation failures.
+
+    Raised when:
+        - OpenAI API is unavailable
+        - OpenAI returns error response
+        - Network errors during generation
+        - Authentication failures
+
+    Status Code: 502 Bad Gateway
+    """
+
+    def __init__(self, message: str):
+        """
+        Initialize generation error.
+
+        Args:
+            message: Generation error message
+        """
+        super().__init__(message, status_code=502, error_type="GenerationError")
+
+
+class RateLimitError(RAGException):
+    """
+    Exception for API rate limit exceeded.
+
+    Raised when:
+        - OpenAI rate limit exceeded
+        - Cohere rate limit exceeded
+        - Qdrant rate limit exceeded
+
+    Status Code: 429 Too Many Requests
+    """
+
+    def __init__(self, message: str):
+        """
+        Initialize rate limit error.
+
+        Args:
+            message: Rate limit error message
+        """
+        super().__init__(message, status_code=429, error_type="RateLimitError")

models/__init__.py

@@ -0,0 +1,4 @@
+# Models package
+from .request_models import QueryRequest
+from .response_models import QueryResponse, ErrorResponse
+from .translation_models import TranslationRequest, TranslationResponse

models/request_models.py

@@ -0,0 +1,110 @@
+"""
+Request Models for RAG Agent API
+
+Pydantic models for validating incoming API requests.
+
+Models:
+    QueryRequest: User query with optional parameters
+"""
+
+from pydantic import BaseModel, Field, field_validator
+from typing import Optional
+
+
+class QueryRequest(BaseModel):
+    """
+    Request model for POST /query endpoint.
+
+    Attributes:
+        query: User's natural language question (1-2000 characters)
+        top_k: Number of documentation chunks to retrieve (1-50, default 5)
+        model: OpenAI model to use (default 'gpt-3.5-turbo')
+
+    Example:
+        {
+            "query": "How do I create a ROS 2 publisher in Python?",
+            "top_k": 5,
+            "model": "gpt-3.5-turbo"
+        }
+    """
+
+    query: str = Field(
+        ...,
+        min_length=1,
+        max_length=2000,
+        description="User's natural language question",
+        examples=["How do I create a ROS 2 publisher in Python?"]
+    )
+
+    top_k: int = Field(
+        default=5,
+        ge=1,
+        le=50,
+        description="Number of documentation chunks to retrieve"
+    )
+
+    model: str = Field(
+        default="xiaomi/mimo-v2-flash:free",
+        description="LLM model to use for answer generation (OpenAI or OpenRouter)"
+    )
+
+    @field_validator('query')
+    @classmethod
+    def query_not_empty(cls, v: str) -> str:
+        """
+        Validate that query is not empty or whitespace only.
+
+        Args:
+            v: Query string to validate
+
+        Returns:
+            Stripped query string
+
+        Raises:
+            ValueError: If query is empty or whitespace only
+        """
+        if not v or not v.strip():
+            raise ValueError("Query cannot be empty or whitespace only")
+        return v.strip()
+
+    @field_validator('model')
+    @classmethod
+    def valid_model(cls, v: str) -> str:
+        """
+        Validate that model is in the allowed list.
+
+        Args:
+            v: Model name to validate
+
+        Returns:
+            Model name if valid
+
+        Raises:
+            ValueError: If model is not in allowed list
+        """
+        allowed_models = [
+            "gpt-3.5-turbo",
+            "gpt-4",
+            "gpt-4-turbo-preview",
+            "xiaomi/mimo-v2-flash:free"
+        ]
+        if v not in allowed_models:
+            raise ValueError(f"Model must be one of {allowed_models}")
+        return v
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "query": "How do I create a ROS 2 publisher in Python?",
+                    "top_k": 5,
+                    "model": "xiaomi/mimo-v2-flash:free"
+                },
+                {
+                    "query": "What is a URDF file?",
+                    "top_k": 10,
+                    "model": "gpt-4"
+                }
+            ]
+        }
+    }

models/response_models.py

@@ -0,0 +1,221 @@
+"""
+Response Models for RAG Agent API
+
+Pydantic models for API responses.
+
+Models:
+    SourceReference: Reference to a documentation source
+    QueryResponse: Successful query response with answer and sources
+    ErrorResponse: Error response with details
+"""
+
+from pydantic import BaseModel, Field, HttpUrl
+from typing import List, Optional
+
+
+class SourceReference(BaseModel):
+    """
+    Reference to a documentation source used in answer generation.
+
+    Attributes:
+        url: URL of the source documentation page
+        page_title: Human-readable title of the page
+        relevance_score: Similarity score from vector search (0.0-1.0)
+        chunk_index: Position of chunk within the page (optional)
+
+    Example:
+        {
+            "url": "https://docs.ros.org/...",
+            "page_title": "Writing a simple publisher",
+            "relevance_score": 0.8642,
+            "chunk_index": 2
+        }
+    """
+
+    url: str = Field(
+        ...,
+        description="URL of the source documentation page"
+    )
+
+    page_title: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable title of the documentation page"
+    )
+
+    relevance_score: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Similarity score from vector search (0.0-1.0, higher is more relevant)"
+    )
+
+    chunk_index: Optional[int] = Field(
+        default=None,
+        ge=0,
+        description="Position of the chunk within the page (0-indexed)"
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "url": "https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Writing-A-Simple-Py-Publisher.html",
+                    "page_title": "Writing a simple publisher (Python)",
+                    "relevance_score": 0.8642,
+                    "chunk_index": 2
+                }
+            ]
+        }
+    }
+
+
+class QueryResponse(BaseModel):
+    """
+    Successful response to a query request.
+
+    Attributes:
+        query: Original user query (echoed back)
+        answer: Generated natural language answer
+        sources: List of source references (deduplicated by URL)
+        model_used: Actual OpenAI model used for generation
+        tokens_used: Total tokens consumed (prompt + completion)
+        retrieval_count: Number of chunks retrieved before deduplication
+
+    Example:
+        {
+            "query": "How do I create a ROS 2 publisher?",
+            "answer": "To create a ROS 2 publisher...",
+            "sources": [...],
+            "model_used": "gpt-3.5-turbo",
+            "tokens_used": 456,
+            "retrieval_count": 5
+        }
+    """
+
+    query: str = Field(
+        ...,
+        description="Original user query (echoed back)"
+    )
+
+    answer: str = Field(
+        ...,
+        min_length=1,
+        description="Generated natural language answer"
+    )
+
+    sources: List[SourceReference] = Field(
+        ...,
+        description="List of source references (deduplicated by URL)"
+    )
+
+    model_used: str = Field(
+        ...,
+        description="Actual OpenAI model used for generation"
+    )
+
+    tokens_used: int = Field(
+        ...,
+        ge=0,
+        description="Total tokens consumed (prompt + completion)"
+    )
+
+    retrieval_count: int = Field(
+        ...,
+        ge=0,
+        description="Number of chunks retrieved before deduplication"
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "query": "How do I create a ROS 2 publisher in Python?",
+                    "answer": "To create a ROS 2 publisher in Python, you need to import rclpy, create a node class, and use create_publisher()...",
+                    "sources": [
+                        {
+                            "url": "https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Writing-A-Simple-Py-Publisher.html",
+                            "page_title": "Writing a simple publisher (Python)",
+                            "relevance_score": 0.8642,
+                            "chunk_index": 2
+                        }
+                    ],
+                    "model_used": "gpt-3.5-turbo",
+                    "tokens_used": 456,
+                    "retrieval_count": 5
+                }
+            ]
+        }
+    }
+
+
+class ErrorResponse(BaseModel):
+    """
+    Error response for failed requests.
+
+    Attributes:
+        error: Error flag (always True for error responses)
+        error_type: Error classification (ValidationError, RetrievalError, etc.)
+        error_message: Human-readable error description
+        query: Original query if available
+        status_code: HTTP status code
+
+    Example:
+        {
+            "error": true,
+            "error_type": "ValidationError",
+            "error_message": "Query cannot be empty",
+            "query": "",
+            "status_code": 422
+        }
+    """
+
+    error: bool = Field(
+        default=True,
+        description="Error flag (always True for error responses)"
+    )
+
+    error_type: str = Field(
+        ...,
+        min_length=1,
+        description="Error classification"
+    )
+
+    error_message: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable error description"
+    )
+
+    query: Optional[str] = Field(
+        default=None,
+        description="Original query if available"
+    )
+
+    status_code: int = Field(
+        ...,
+        ge=400,
+        le=599,
+        description="HTTP status code"
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "error": True,
+                    "error_type": "ValidationError",
+                    "error_message": "Query cannot be empty or whitespace only",
+                    "query": "",
+                    "status_code": 422
+                },
+                {
+                    "error": True,
+                    "error_type": "RetrievalError",
+                    "error_message": "Vector database is currently unavailable",
+                    "query": "How do I create a publisher?",
+                    "status_code": 503
+                }
+            ]
+        }
+    }

models/translation_models.py

@@ -0,0 +1,92 @@
+"""
+Pydantic Models for Translation API
+
+Models:
+- TranslationRequest: Request payload for translation
+- TranslationResponse: Successful translation response
+- TranslationError: Error response with error codes
+"""
+
+from pydantic import BaseModel, Field, validator
+from typing import Optional
+from datetime import datetime
+
+
+class TranslationRequest(BaseModel):
+    """Request model for translation endpoint"""
+
+    text: str = Field(..., min_length=1, max_length=50000, description="Text content to translate")
+    source_language: str = Field(..., pattern="^en$", description="Source language code (only 'en' supported)")
+    target_language: str = Field(..., pattern="^ur$", description="Target language code (only 'ur' supported)")
+    content_hash: Optional[str] = Field(None, pattern="^[a-f0-9]{32}$", description="MD5 hash for cache lookup")
+    preserve_html: bool = Field(True, description="Whether to preserve HTML tags")
+
+    @validator('text')
+    def text_not_empty(cls, v):
+        """Validate text is not empty or whitespace-only"""
+        if not v or v.isspace():
+            raise ValueError('Text cannot be empty or whitespace-only')
+        return v
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "text": "<p>Welcome to the <strong>Physical AI</strong> guide</p>",
+                "source_language": "en",
+                "target_language": "ur",
+                "content_hash": "a3f5e8c9d2b14f6c8e7a9b2c3d4e5f6g",
+                "preserve_html": True
+            }
+        }
+
+
+class TranslationResponse(BaseModel):
+    """Response model for successful translation"""
+
+    translated_text: str = Field(..., description="Translated text in target language")
+    source_language: str = Field(..., description="Source language code (echoed)")
+    target_language: str = Field(..., description="Target language code (echoed)")
+    cached: bool = Field(..., description="Whether result was served from cache")
+    model_used: str = Field(..., description="Translation model identifier")
+    timestamp: str = Field(..., description="Timestamp of translation (ISO 8601)")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "translated_text": "<p>فزیکل AI گائیڈ میں <strong>خوش آمدید</strong></p>",
+                "source_language": "en",
+                "target_language": "ur",
+                "cached": False,
+                "model_used": "facebook/mbart-large-50",
+                "timestamp": "2025-12-22T10:30:00Z"
+            }
+        }
+
+
+class TranslationError(BaseModel):
+    """Error response model for translation failures"""
+
+    error: str = Field(..., description="Human-readable error message")
+    error_code: str = Field(..., description="Machine-readable error code")
+    retry_after: Optional[int] = Field(None, description="Seconds to wait before retry (for rate limits)")
+    timestamp: str = Field(..., description="Timestamp of error (ISO 8601)")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "error": "Translation service temporarily unavailable",
+                "error_code": "SERVICE_DOWN",
+                "retry_after": 60,
+                "timestamp": "2025-12-22T10:30:00Z"
+            }
+        }
+
+
+# Error code constants
+class ErrorCodes:
+    """Standard error codes for translation failures"""
+    SERVICE_DOWN = "SERVICE_DOWN"  # Translation model not loaded or crashed
+    RATE_LIMIT = "RATE_LIMIT"      # Too many requests
+    INVALID_LANGUAGE = "INVALID_LANGUAGE"  # Unsupported language pair
+    TIMEOUT = "TIMEOUT"             # Translation exceeded time limit
+    INVALID_INPUT = "INVALID_INPUT" # Malformed HTML or empty text

rag_agent.py

@@ -0,0 +1,270 @@
+"""
+RAG Agent API Service
+
+FastAPI application providing a RAG (Retrieval-Augmented Generation) endpoint
+for querying documentation and generating grounded answers.
+
+Endpoints:
+    POST /query - Submit a question and get an answer with sources
+    GET /health - Health check endpoint
+
+Features:
+    - Query validation with Pydantic
+    - Integration with Qdrant for document retrieval
+    - OpenAI integration for answer generation
+    - Source attribution and deduplication
+    - Structured logging
+    - CORS support for web clients
+
+Usage:
+    uvicorn rag_agent:app --reload --host 0.0.0.0 --port 8000
+"""
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+import logging
+from datetime import datetime
+
+from models.request_models import QueryRequest
+from models.response_models import QueryResponse, ErrorResponse
+from services.integration_service import IntegrationService
+from exceptions import RAGException, ValidationError, RetrievalError, GenerationError, RateLimitError
+from config.logging_config import setup_logging, get_logger
+
+# Try to import translation router (optional - requires PyTorch)
+translation_router = None
+try:
+    from routers.translation import router as translation_router
+except Exception as e:
+    print(f"[WARNING] Translation router not available: {e}")
+    print("[INFO] RAG agent will run without translation support")
+
+# Initialize FastAPI app
+app = FastAPI(
+    title="RAG Agent API",
+    description="Retrieval-Augmented Generation API for documentation Q&A",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+# Configure CORS for development (allow all origins)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, restrict to specific origins
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Configure logging
+setup_logging(level="INFO", json_format=False)
+logger = get_logger('rag_agent')
+
+# Initialize integration service
+integration_service = IntegrationService()
+
+# Register routers (only if available)
+if translation_router is not None:
+    app.include_router(translation_router)
+    print("[INFO] Translation router registered")
+else:
+    print("[INFO] Running without translation support - use mock_translation_server.py for translations")
+
+
+@app.get("/health")
+async def health_check():
+    """
+    Health check endpoint.
+
+    Returns:
+        dict: Health status with version and timestamp
+    """
+    return {
+        "status": "healthy",
+        "version": "1.0.0",
+        "timestamp": datetime.utcnow().isoformat() + "Z"
+    }
+
+
+@app.get("/")
+async def root():
+    """
+    Root endpoint with API information.
+
+    Returns:
+        dict: API info and documentation links
+    """
+    return {
+        "name": "RAG Agent API",
+        "version": "1.0.0",
+        "description": "Retrieval-Augmented Generation API for documentation Q&A",
+        "docs": "/docs",
+        "redoc": "/redoc",
+        "health": "/health"
+    }
+
+
+@app.post("/query", response_model=QueryResponse, responses={
+    422: {"model": ErrorResponse, "description": "Validation Error"},
+    503: {"model": ErrorResponse, "description": "Retrieval Error"},
+    502: {"model": ErrorResponse, "description": "Generation Error"},
+    429: {"model": ErrorResponse, "description": "Rate Limit Error"}
+})
+async def query_documentation(request: QueryRequest):
+    """
+    Submit a question and get an answer with source attribution.
+
+    This endpoint implements the full RAG pipeline:
+    1. Validates the query
+    2. Retrieves relevant documentation chunks from Qdrant
+    3. Generates a grounded answer using OpenAI
+    4. Returns the answer with deduplicated source references
+
+    Args:
+        request: QueryRequest with query, top_k, and model
+
+    Returns:
+        QueryResponse with answer, sources, and metadata
+
+    Raises:
+        HTTPException: For validation, retrieval, generation, or rate limit errors
+    """
+    start_time = datetime.utcnow()
+
+    logger.info(
+        "Received query request",
+        extra={
+            "query": request.query[:50] + "..." if len(request.query) > 50 else request.query,
+            "top_k": request.top_k,
+            "model": request.model
+        }
+    )
+
+    try:
+        # Process query through RAG pipeline
+        response = await integration_service.process_query(
+            query=request.query,
+            top_k=request.top_k,
+            model=request.model
+        )
+
+        # Log success
+        latency_ms = int((datetime.utcnow() - start_time).total_seconds() * 1000)
+        logger.info(
+            "Query processed successfully",
+            extra={
+                "query": request.query[:50] + "..." if len(request.query) > 50 else request.query,
+                "latency_ms": latency_ms,
+                "tokens_used": response.tokens_used,
+                "sources_count": len(response.sources)
+            }
+        )
+
+        return response
+
+    except ValidationError as e:
+        # Log validation error
+        logger.warning(
+            f"Validation error: {e.message}",
+            extra={
+                "query": request.query,
+                "error_type": e.error_type,
+                "status_code": e.status_code
+            }
+        )
+        return JSONResponse(
+            status_code=e.status_code,
+            content=ErrorResponse(
+                error_type=e.error_type,
+                error_message=e.message,
+                query=request.query,
+                status_code=e.status_code
+            ).model_dump()
+        )
+
+    except RetrievalError as e:
+        # Log retrieval error
+        logger.error(
+            f"Retrieval error: {e.message}",
+            extra={
+                "query": request.query,
+                "error_type": e.error_type,
+                "status_code": e.status_code
+            }
+        )
+        return JSONResponse(
+            status_code=e.status_code,
+            content=ErrorResponse(
+                error_type=e.error_type,
+                error_message=e.message,
+                query=request.query,
+                status_code=e.status_code
+            ).model_dump()
+        )
+
+    except GenerationError as e:
+        # Log generation error
+        logger.error(
+            f"Generation error: {e.message}",
+            extra={
+                "query": request.query,
+                "error_type": e.error_type,
+                "status_code": e.status_code
+            }
+        )
+        return JSONResponse(
+            status_code=e.status_code,
+            content=ErrorResponse(
+                error_type=e.error_type,
+                error_message=e.message,
+                query=request.query,
+                status_code=e.status_code
+            ).model_dump()
+        )
+
+    except RateLimitError as e:
+        # Log rate limit error
+        logger.warning(
+            f"Rate limit error: {e.message}",
+            extra={
+                "query": request.query,
+                "error_type": e.error_type,
+                "status_code": e.status_code
+            }
+        )
+        return JSONResponse(
+            status_code=e.status_code,
+            content=ErrorResponse(
+                error_type=e.error_type,
+                error_message=e.message,
+                query=request.query,
+                status_code=e.status_code
+            ).model_dump()
+        )
+
+    except Exception as e:
+        # Log unexpected error
+        logger.error(
+            f"Unexpected error: {str(e)}",
+            extra={
+                "query": request.query,
+                "error_type": "InternalServerError"
+            },
+            exc_info=True
+        )
+        return JSONResponse(
+            status_code=500,
+            content=ErrorResponse(
+                error_type="InternalServerError",
+                error_message=f"An unexpected error occurred: {str(e)}",
+                query=request.query,
+                status_code=500
+            ).model_dump()
+        )
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

requirements.txt

@@ -0,0 +1,20 @@
+# Existing dependencies (from previous specs)
+cohere>=5.20.1
+qdrant-client>=1.16.2
+beautifulsoup4>=4.14.3
+requests>=2.32.5
+lxml>=6.0.2
+python-dotenv>=1.0.0
+
+# RAG Agent API dependencies (002-rag-agent)
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+pydantic>=2.0.0
+openai>=1.0.0
+tiktoken>=0.5.0
+httpx>=0.25.0
+
+# Urdu Translation Agent dependencies (005-urdu-translation)
+transformers>=4.36.0
+torch>=2.0.0
+sentencepiece>=0.1.99  # Required for mBART tokenizer

retrieval.py

@@ -0,0 +1,252 @@
+"""
+Retrieval Pipeline Module
+
+Provides functions for querying embedded documentation in Qdrant.
+
+Functions:
+    embed_query: Generate query embedding using Cohere
+    search_qdrant: Search for similar chunks in Qdrant
+    format_results: Format search results as JSON
+    format_error: Format errors as JSON response
+    setup_logging: Configure structured logging
+
+Example:
+    >>> from retrieval import embed_query, search_qdrant
+    >>> embedding = embed_query("What is ROS 2?")
+    >>> results = search_qdrant(embedding, top_k=5)
+"""
+
+import os
+import logging
+from dataclasses import dataclass
+from typing import List, Dict, Any
+from dotenv import load_dotenv
+from cohere import Client as CohereClient
+from qdrant_client import QdrantClient
+from pathlib import Path
+
+# Load environment variables - explicit path for uvicorn compatibility
+_env_file = Path(__file__).parent / '.env'
+load_dotenv(dotenv_path=_env_file, override=True)
+
+# Constants
+MODEL = "embed-english-v3.0"
+COLLECTION_NAME = os.getenv("COLLECTION_NAME", "website_embeddings")
+DEFAULT_TOP_K = 5
+MAX_TOP_K = 50
+
+# Logging setup
+def setup_logging():
+    """Configure structured logging"""
+    logging.basicConfig(
+        level=logging.INFO,
+        format='[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+
+logger = logging.getLogger('retrieval')
+
+
+@dataclass
+class SearchResult:
+    """Single search result from Qdrant"""
+    rank: int
+    score: float
+    text: str
+    metadata: Dict[str, Any]
+
+
+def embed_query(query_text: str) -> List[float]:
+    """
+    Generate embedding vector for query text using Cohere.
+
+    Args:
+        query_text: Natural language query string
+
+    Returns:
+        1024-dimensional embedding vector
+
+    Raises:
+        ValueError: If query_text is empty or None
+        CohereAPIError: If API call fails
+    """
+    # Validation
+    if not query_text or not query_text.strip():
+        raise ValueError("Query text cannot be empty")
+
+    if len(query_text) > 2000:
+        raise ValueError("Query text too long (max 2000 characters)")
+
+    # Initialize Cohere client
+    api_key = os.getenv("COHERE_API_KEY")
+    if not api_key:
+        raise ValueError("COHERE_API_KEY not found in environment")
+
+    client = CohereClient(api_key=api_key)
+
+    # Log query embedding
+    logger.info(f"Embedding query: {query_text[:50]}...")
+
+    # Generate embedding
+    response = client.embed(
+        texts=[query_text],
+        model=MODEL,
+        input_type='search_query'  # Important: different from 'search_document'
+    )
+
+    return response.embeddings[0]
+
+
+def search_qdrant(
+    query_embedding: List[float],
+    top_k: int = DEFAULT_TOP_K,
+    collection_name: str = COLLECTION_NAME
+) -> List[SearchResult]:
+    """
+    Search Qdrant for similar chunks.
+
+    Args:
+        query_embedding: 1024-dim vector from embed_query()
+        top_k: Number of results to return (default 5, max 50)
+        collection_name: Qdrant collection to search
+
+    Returns:
+        List of SearchResult objects ranked by similarity
+
+    Raises:
+        ValueError: If top_k < 1 or > 50, or embedding dimension wrong
+        QdrantException: If search fails
+    """
+    # Validation
+    if not isinstance(query_embedding, list) or len(query_embedding) != 1024:
+        raise ValueError("query_embedding must be list of 1024 floats")
+
+    if not 1 <= top_k <= MAX_TOP_K:
+        raise ValueError(f"top_k must be between 1 and {MAX_TOP_K}")
+
+    # Initialize Qdrant client
+    qdrant_url = os.getenv("QDRANT_URL")
+    qdrant_api_key = os.getenv("QDRANT_API_KEY")
+
+    if not qdrant_url:
+        raise ValueError("QDRANT_URL required")
+
+    # For local Qdrant instances, API key is not required
+    # Only require API key if using a remote Qdrant instance
+    if qdrant_url != "localhost:6333" and qdrant_url.startswith("http") and not qdrant_api_key:
+        raise ValueError("QDRANT_API_KEY required for remote Qdrant instances")
+
+    # Initialize Qdrant client based on URL type
+    if qdrant_url == "localhost:6333":
+        # For local instance, use host and port
+        client = QdrantClient(host="localhost", port=6333)
+    elif qdrant_api_key:
+        # For remote instance with API key
+        client = QdrantClient(url=qdrant_url, api_key=qdrant_api_key)
+    else:
+        # For remote instance without API key
+        client = QdrantClient(url=qdrant_url)
+
+    # Verify collection exists
+    try:
+        collection_info = client.get_collection(collection_name)
+        if collection_info.points_count == 0:
+            raise ValueError(f"Collection '{collection_name}' is empty")
+    except Exception as e:
+        raise ValueError(f"Collection '{collection_name}' not found or inaccessible: {e}")
+
+    # Log search
+    logger.info(f"Searching Qdrant for top {top_k} results...")
+
+    # Perform search
+    search_results = client.query_points(
+        collection_name=collection_name,
+        query=query_embedding,
+        limit=top_k,
+        with_payload=True,
+        with_vectors=False
+    )
+
+    # Convert to SearchResult objects
+    results = []
+    for rank, hit in enumerate(search_results.points, start=1):
+        result = SearchResult(
+            rank=rank,
+            score=hit.score,
+            text=hit.payload.get('text', ''),
+            metadata={
+                'url': hit.payload.get('url', ''),
+                'page_title': hit.payload.get('page_title', ''),
+                'chunk_index': hit.payload.get('chunk_index', -1),
+                'total_chunks': hit.payload.get('total_chunks', -1),
+                'source': hit.payload.get('source', ''),
+                'file_path': hit.payload.get('file_path', '')
+            }
+        )
+        results.append(result)
+
+    logger.info(f"Retrieved {len(results)} results")
+    return results
+
+
+def format_results(
+    query: str,
+    results: List[SearchResult],
+    top_k: int
+) -> dict:
+    """
+    Format search results as JSON-serializable dict.
+
+    Args:
+        query: Original query text
+        results: List of search results
+        top_k: Requested number of results
+
+    Returns:
+        Dict conforming to response schema
+    """
+    logger.info("Formatting results as JSON")
+
+    return {
+        "query": query,
+        "top_k": top_k,
+        "result_count": len(results),
+        "results": [
+            {
+                "rank": r.rank,
+                "score": round(r.score, 4),  # Round to 4 decimal places
+                "text": r.text,
+                "metadata": {
+                    "url": r.metadata['url'],
+                    "page_title": r.metadata['page_title'],
+                    "chunk_index": r.metadata['chunk_index'],
+                    "total_chunks": r.metadata['total_chunks'],
+                    "source": r.metadata['source']
+                }
+            }
+            for r in results
+        ]
+    }
+
+
+def format_error(error: Exception, query: str = "") -> dict:
+    """
+    Format error as JSON response.
+
+    Args:
+        error: Exception that occurred
+        query: Original query text (if available)
+
+    Returns:
+        Error dict conforming to response schema
+    """
+    logger.error(f"Error occurred: {type(error).__name__}: {str(error)}")
+
+    return {
+        "error": True,
+        "error_type": type(error).__name__,
+        "error_message": str(error),
+        "query": query,
+        "result_count": 0,
+        "results": []
+    }

services/__init__.py

@@ -0,0 +1 @@
+# Services package

services/generation_service.py

@@ -0,0 +1,239 @@
+"""
+Answer Generation Service for RAG Agent
+
+Handles interaction with OpenAI Chat Completions API to generate natural language
+answers from documentation context. Includes retry logic, error handling, and
+comprehensive logging.
+
+This service:
+1. Calls OpenAI Chat Completions API
+2. Implements retry logic with exponential backoff
+3. Handles authentication and rate limit errors
+4. Logs generation metrics (tokens, latency, completion length)
+5. Returns structured results with answer and token usage
+
+Usage:
+    from services.generation_service import AnswerGenerationService
+
+    service = AnswerGenerationService(api_key="your-key")
+    result = service.generate_answer(prompt="<context>...</context>...", model="gpt-3.5-turbo")
+    print(result['answer'], result['tokens_used'])
+"""
+
+import os
+import logging
+import time
+from typing import Dict, Optional
+from datetime import datetime
+from openai import OpenAI
+
+from exceptions import GenerationError, RateLimitError
+
+logger = logging.getLogger('generation_service')
+
+
+class AnswerGenerationService:
+    """
+    Service for generating natural language answers using OpenAI.
+
+    This service manages all OpenAI API interactions with:
+    - Retry logic for transient errors (429, 500, 502, 503)
+    - Error handling for non-retryable errors (401, 400)
+    - Comprehensive logging (model, tokens, latency)
+    - Deterministic generation (low temperature)
+
+    Attributes:
+        openai_client: OpenAI client instance
+        max_retries: Maximum retry attempts (default 3)
+
+    Methods:
+        generate_answer: Generate answer from prompt
+    """
+
+    def __init__(self, api_key: Optional[str] = None, max_retries: int = 3):
+        """
+        Initialize answer generation service.
+
+        Args:
+            api_key: OpenRouter API key (default: from env)
+            max_retries: Maximum retry attempts for transient errors (default 3)
+
+        Raises:
+            ValueError: If API key not provided and not in environment
+        """
+        self.api_key = api_key or os.getenv("OPENROUTER_API_KEY")
+        if not self.api_key:
+            raise ValueError("OPENROUTER_API_KEY not found in environment")
+
+        self.openai_client = OpenAI(
+            api_key=self.api_key,
+            base_url="https://openrouter.ai/api/v1"
+        )
+        self.max_retries = max_retries
+
+        logger.info(
+            f"AnswerGenerationService initialized with OpenRouter",
+            extra={"max_retries": max_retries, "base_url": "https://openrouter.ai/api/v1"}
+        )
+
+    def generate_answer(
+        self,
+        prompt: str,
+        model: str = "xiaomi/mimo-v2-flash:free",
+        temperature: float = 0.1,
+        max_tokens: int = 500
+    ) -> Dict[str, any]:
+        """
+        Generate natural language answer from prompt using OpenAI.
+
+        Calls OpenAI Chat Completions API with retry logic for transient errors.
+        Uses low temperature (0.1) for deterministic, factual responses.
+
+        Args:
+            prompt: Full prompt with context and query
+            model: OpenAI model to use (default: gpt-3.5-turbo)
+            temperature: Sampling temperature (default: 0.1 for deterministic)
+            max_tokens: Maximum tokens in completion (default: 500)
+
+        Returns:
+            Dict with:
+                - answer: Generated text response
+                - tokens_used: Total tokens consumed (prompt + completion)
+                - model_used: Actual model used
+                - completion_length: Character length of answer
+
+        Raises:
+            GenerationError: If generation fails (non-retryable or max retries exceeded)
+            RateLimitError: If rate limit persists after retries
+
+        Example:
+            >>> service = AnswerGenerationService()
+            >>> result = service.generate_answer(
+            ...     prompt="<context>ROS 2 docs...</context><query>What is ROS 2?</query>...",
+            ...     model="gpt-3.5-turbo"
+            ... )
+            >>> print(result['answer'])
+            >>> print(f"Used {result['tokens_used']} tokens")
+        """
+        start_time = datetime.utcnow()
+
+        logger.info(
+            f"Starting answer generation",
+            extra={
+                "model": model,
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+                "prompt_length": len(prompt)
+            }
+        )
+
+        # Retry loop for transient errors
+        last_error = None
+        for attempt in range(self.max_retries):
+            try:
+                # Call OpenAI Chat Completions API
+                response = self.openai_client.chat.completions.create(
+                    model=model,
+                    messages=[
+                        {
+                            "role": "system",
+                            "content": "You are a helpful assistant that answers questions based on provided documentation. Always cite the documentation and be precise."
+                        },
+                        {
+                            "role": "user",
+                            "content": prompt
+                        }
+                    ],
+                    temperature=temperature,
+                    max_tokens=max_tokens
+                )
+
+                # Extract answer and metrics
+                answer = response.choices[0].message.content
+                tokens_used = response.usage.total_tokens
+                completion_length = len(answer)
+
+                # Calculate latency
+                latency_ms = int((datetime.utcnow() - start_time).total_seconds() * 1000)
+
+                # Log success
+                logger.info(
+                    f"Answer generated successfully",
+                    extra={
+                        "model": model,
+                        "tokens_used": tokens_used,
+                        "generation_latency_ms": latency_ms,
+                        "completion_length": completion_length,
+                        "attempt": attempt + 1
+                    }
+                )
+
+                return {
+                    "answer": answer,
+                    "tokens_used": tokens_used,
+                    "model_used": model,
+                    "completion_length": completion_length
+                }
+
+            except Exception as e:
+                last_error = e
+                error_message = str(e)
+                error_type = type(e).__name__
+
+                # Check for rate limit errors (429) - retryable
+                if "rate_limit" in error_message.lower() or "429" in error_message:
+                    if attempt < self.max_retries - 1:
+                        # Calculate exponential backoff
+                        wait_time = 2 ** attempt  # 1s, 2s, 4s
+                        logger.warning(
+                            f"Rate limit hit, retrying in {wait_time}s (attempt {attempt + 1}/{self.max_retries})",
+                            extra={
+                                "error_type": error_type,
+                                "attempt": attempt + 1,
+                                "wait_time": wait_time
+                            }
+                        )
+                        time.sleep(wait_time)
+                        continue
+                    else:
+                        # Max retries exceeded for rate limit
+                        logger.error(
+                            f"Rate limit persists after {self.max_retries} retries",
+                            extra={"error_message": error_message}
+                        )
+                        raise RateLimitError("OpenAI rate limit exceeded. Please try again later.")
+
+                # Check for server errors (500, 502, 503) - retryable
+                if any(code in error_message for code in ["500", "502", "503"]):
+                    if attempt < self.max_retries - 1:
+                        wait_time = 2 ** attempt
+                        logger.warning(
+                            f"Server error, retrying in {wait_time}s (attempt {attempt + 1}/{self.max_retries})",
+                            extra={
+                                "error_type": error_type,
+                                "error_message": error_message,
+                                "attempt": attempt + 1,
+                                "wait_time": wait_time
+                            }
+                        )
+                        time.sleep(wait_time)
+                        continue
+
+                # Non-retryable errors (401 auth, 400 bad request, etc.)
+                logger.error(
+                    f"Generation failed with non-retryable error: {error_message}",
+                    extra={
+                        "error_type": error_type,
+                        "model": model,
+                        "attempt": attempt + 1
+                    },
+                    exc_info=True
+                )
+                raise GenerationError(f"Failed to generate answer: {error_message}")
+
+        # If we exhausted all retries
+        logger.error(
+            f"Generation failed after {self.max_retries} retries",
+            extra={"last_error": str(last_error)}
+        )
+        raise GenerationError(f"Failed to generate answer after {self.max_retries} retries: {str(last_error)}")

services/integration_service.py

@@ -0,0 +1,286 @@
+"""
+Integration Service for RAG Agent
+
+Orchestrates the full RAG pipeline:
+1. Embed query using Cohere
+2. Retrieve relevant chunks from Qdrant
+3. Generate answer using OpenAI
+4. Deduplicate sources and format response
+
+This service integrates retrieval.py (existing) with OpenAI generation.
+"""
+
+import os
+import logging
+from typing import List, Dict, Any, Optional
+from dotenv import load_dotenv
+
+from retrieval import SearchResult
+from services.retrieval_service import RetrievalService
+from services.prompt_builder import PromptBuilder
+from services.generation_service import AnswerGenerationService
+from models.response_models import QueryResponse, SourceReference
+from exceptions import RetrievalError, GenerationError, RateLimitError
+
+# Load environment variables
+load_dotenv()
+
+# Constants
+DEFAULT_MODEL = os.getenv("DEFAULT_MODEL", "xiaomi/mimo-v2-flash:free")
+MAX_TOKENS = int(os.getenv("MAX_TOKENS", "3000"))
+# NOTE: Threshold set to 0.15 based on actual retrieval performance
+# The current embedding model (Cohere embed-english-v3.0) returns lower scores than expected.
+# Original requirement (FR-005) specified 0.7, but testing shows:
+# - Technical queries get scores of 0.15-0.30
+# - Irrelevant queries (like "hi") get scores of 0.10-0.23
+# Setting to 0.15 filters out very low-quality matches while keeping relevant docs
+RELEVANCE_THRESHOLD = 0.15  # Minimum relevance score for usable results (FR-005)
+
+# Greeting patterns for detection (FR-003)
+GREETING_PATTERNS = {
+    "hi", "hello", "hey", "helo", "hii", "heya", "greetings",
+    "good morning", "good afternoon", "good evening"
+}
+
+logger = logging.getLogger('integration_service')
+
+
+class IntegrationService:
+    """
+    Service for orchestrating RAG pipeline: retrieval + generation.
+
+    Methods:
+        process_query: Main entry point for RAG pipeline
+        _is_greeting: Detect if query is a casual greeting
+        _retrieve_chunks: Retrieve relevant documentation chunks
+        _deduplicate_sources: Deduplicate chunks by URL
+        _build_prompt: Build prompt with context and query
+        _generate_answer: Generate answer using OpenAI
+        _count_tokens: Count tokens in text
+    """
+
+    def __init__(self, openai_api_key: Optional[str] = None):
+        """
+        Initialize integration service.
+
+        Args:
+            openai_api_key: OpenRouter API key (default: from env)
+        """
+        self.openai_api_key = openai_api_key or os.getenv("OPENROUTER_API_KEY")
+        if not self.openai_api_key:
+            raise ValueError("OPENROUTER_API_KEY not found in environment")
+
+        self.retrieval_service = RetrievalService()
+        self.prompt_builder = PromptBuilder(max_tokens=MAX_TOKENS)
+        self.generation_service = AnswerGenerationService(api_key=self.openai_api_key)
+
+    def _is_greeting(self, query: str) -> bool:
+        """
+        Detect if query is a standalone greeting (FR-003).
+
+        Returns True for casual greetings like "hi", "hello", "hey".
+        Returns False for queries that contain greetings but have actual questions
+        (e.g., "Hi, how do I create a ROS 2 publisher?").
+
+        Args:
+            query: User query text
+
+        Returns:
+            True if query is a greeting, False otherwise
+        """
+        # Normalize: strip, lowercase, remove punctuation
+        normalized = query.strip().lower().rstrip('!?.,:;')
+
+        # Check if entire query is just a greeting (standalone)
+        # Don't match if query contains other words after greeting
+        return normalized in GREETING_PATTERNS
+
+    async def process_query(
+        self,
+        query: str,
+        top_k: int = 5,
+        model: str = DEFAULT_MODEL
+    ) -> QueryResponse:
+        """
+        Process a query through the full RAG pipeline.
+
+        Args:
+            query: User's natural language question
+            top_k: Number of chunks to retrieve
+            model: OpenAI model to use
+
+        Returns:
+            QueryResponse with answer and sources
+
+        Raises:
+            RetrievalError: If retrieval fails
+            GenerationError: If generation fails
+            RateLimitError: If rate limit exceeded
+        """
+        logger.info(f"Processing query", extra={"query": query, "top_k": top_k, "model": model})
+
+        # Step 0: Check for greetings FIRST (FR-003)
+        if self._is_greeting(query):
+            logger.info(f"Greeting detected: {query}")
+            return QueryResponse(
+                query=query,
+                answer="Hello! I'm here to help you learn about ROS 2 and humanoid robotics. What would you like to know?",
+                sources=[],
+                model_used="greeting-detector",
+                tokens_used=0,
+                retrieval_count=0
+            )
+
+        # Step 1: Retrieve chunks
+        chunks = await self._retrieve_chunks(query, top_k)
+        retrieval_count = len(chunks)
+
+        # Step 2: Deduplicate sources
+        deduplicated_sources = self._deduplicate_sources(chunks)
+
+        # Step 3: Build prompt
+        prompt = self._build_prompt(query, chunks, model)
+
+        # Step 4: Generate answer
+        answer, tokens_used = await self._generate_answer(prompt, model)
+
+        # Step 5: Format response
+        response = QueryResponse(
+            query=query,
+            answer=answer,
+            sources=deduplicated_sources,
+            model_used=model,
+            tokens_used=tokens_used,
+            retrieval_count=retrieval_count
+        )
+
+        logger.info(
+            f"Query processed successfully",
+            extra={
+                "query": query,
+                "tokens_used": tokens_used,
+                "retrieval_count": retrieval_count,
+                "sources_count": len(deduplicated_sources)
+            }
+        )
+
+        return response
+
+    async def _retrieve_chunks(self, query: str, top_k: int) -> List[SearchResult]:
+        """
+        Retrieve relevant documentation chunks using RetrievalService.
+        Filters results by relevance threshold (FR-005).
+
+        Args:
+            query: User query
+            top_k: Number of chunks to retrieve
+
+        Returns:
+            List of SearchResult objects with relevance >= 0.7
+
+        Raises:
+            RetrievalError: If retrieval fails or no relevant docs found (FR-006)
+        """
+        # Delegate to RetrievalService (already has error handling and logging)
+        chunks = self.retrieval_service.retrieve_context(query, top_k=top_k)
+
+        # Filter by relevance threshold (FR-005)
+        filtered_chunks = [c for c in chunks if c.score >= RELEVANCE_THRESHOLD]
+
+        logger.info(
+            f"Relevance filtering: {len(filtered_chunks)}/{len(chunks)} chunks pass threshold {RELEVANCE_THRESHOLD}",
+            extra={
+                "total_chunks": len(chunks),
+                "filtered_chunks": len(filtered_chunks),
+                "threshold": RELEVANCE_THRESHOLD
+            }
+        )
+
+        # Handle no relevant docs case (FR-006)
+        if not filtered_chunks:
+            logger.warning(f"No documents meet relevance threshold {RELEVANCE_THRESHOLD}")
+            raise RetrievalError(
+                "I couldn't find relevant information in the documentation. "
+                "Try rephrasing your question or ask about: ROS 2, Unity, Digital Twins, or Humanoid Robotics."
+            )
+
+        return filtered_chunks
+
+    def _deduplicate_sources(self, chunks: List[SearchResult]) -> List[SourceReference]:
+        """
+        Deduplicate chunks by URL, keeping highest-scoring chunk.
+
+        Args:
+            chunks: List of retrieved chunks
+
+        Returns:
+            List of deduplicated SourceReference objects
+        """
+        # Group by URL, keep highest score
+        url_to_best_chunk: Dict[str, tuple[SearchResult, float]] = {}
+
+        for chunk in chunks:
+            url = chunk.metadata.get('url', '')
+            if not url:
+                continue
+
+            if url not in url_to_best_chunk or chunk.score > url_to_best_chunk[url][1]:
+                url_to_best_chunk[url] = (chunk, chunk.score)
+
+        # Convert to SourceReference
+        sources = []
+        for url, (chunk, score) in url_to_best_chunk.items():
+            source = SourceReference(
+                url=url,
+                page_title=chunk.metadata.get('page_title') or 'Unknown',
+                relevance_score=round(score, 4),
+                chunk_index=chunk.metadata.get('chunk_index')
+            )
+            sources.append(source)
+
+        # Sort by relevance score (descending)
+        sources.sort(key=lambda s: s.relevance_score, reverse=True)
+
+        logger.info(f"Deduplicated {len(chunks)} chunks to {len(sources)} unique sources")
+        return sources
+
+    def _build_prompt(self, query: str, chunks: List[SearchResult], model: str = "gpt-3.5-turbo") -> str:
+        """
+        Build prompt with context and query using PromptBuilder.
+
+        Args:
+            query: User query
+            chunks: Retrieved chunks
+            model: OpenAI model for token counting
+
+        Returns:
+            Formatted prompt string
+        """
+        # Delegate to PromptBuilder (already has XML formatting, token management, source URLs)
+        prompt = self.prompt_builder.build_prompt(query, chunks, model)
+        return prompt
+
+    async def _generate_answer(self, prompt: str, model: str) -> tuple[str, int]:
+        """
+        Generate answer using AnswerGenerationService.
+
+        Args:
+            prompt: Full prompt with context and query
+            model: OpenAI model to use
+
+        Returns:
+            Tuple of (answer, tokens_used)
+
+        Raises:
+            GenerationError: If generation fails (propagated from AnswerGenerationService)
+            RateLimitError: If rate limit exceeded (propagated from AnswerGenerationService)
+        """
+        # Delegate to AnswerGenerationService (already has retry logic, error handling, logging)
+        result = self.generation_service.generate_answer(
+            prompt=prompt,
+            model=model,
+            temperature=0.1,  # Low temperature for deterministic, factual responses
+            max_tokens=500
+        )
+
+        return result['answer'], result['tokens_used']

services/prompt_builder.py

@@ -0,0 +1,264 @@
+"""
+Prompt Builder Service for RAG Agent
+
+Combines retrieved documentation chunks with user queries into well-formatted
+prompts for OpenAI. Handles token management, XML formatting, and source attribution.
+
+This service:
+1. Formats context with XML delimiters
+2. Manages token budgets to stay within API limits
+3. Selects top-scoring chunks that fit
+4. Includes source metadata for attribution
+5. Adds system instructions for grounded answers
+
+Usage:
+    from services.prompt_builder import PromptBuilder
+
+    builder = PromptBuilder(max_tokens=3000)
+    prompt = builder.build_prompt(query="What is ROS 2?", chunks=results)
+"""
+
+import logging
+from typing import List
+from retrieval import SearchResult
+from utils.token_counter import count_tokens
+
+logger = logging.getLogger('prompt_builder')
+
+
+class PromptBuilder:
+    """
+    Service for building prompts with context and query.
+
+    This service creates well-formatted prompts that:
+    - Use XML tags (<context>, <query>) for clear structure
+    - Stay within token limits
+    - Include source URLs for attribution
+    - Provide system instructions for grounded answers
+
+    Attributes:
+        max_tokens: Maximum tokens for entire prompt (default 3000)
+        reserved_tokens: Tokens reserved for query + instructions (default 500)
+
+    Methods:
+        build_prompt: Build formatted prompt from query and chunks
+    """
+
+    def __init__(self, max_tokens: int = 3000, reserved_tokens: int = 500):
+        """
+        Initialize prompt builder.
+
+        Args:
+            max_tokens: Maximum tokens for entire prompt (default 3000)
+            reserved_tokens: Tokens reserved for query/instructions (default 500)
+        """
+        self.max_tokens = max_tokens
+        self.reserved_tokens = reserved_tokens
+        self.context_budget = max_tokens - reserved_tokens
+
+        logger.info(
+            f"PromptBuilder initialized",
+            extra={
+                "max_tokens": max_tokens,
+                "reserved_tokens": reserved_tokens,
+                "context_budget": self.context_budget
+            }
+        )
+
+    def build_prompt(self, query: str, chunks: List[SearchResult], model: str = "gpt-3.5-turbo") -> str:
+        """
+        Build formatted prompt with context and query.
+
+        Creates a prompt with the following structure:
+        ```
+        <context>
+        [chunk 1 text]
+        Source: [url 1]
+
+        [chunk 2 text]
+        Source: [url 2]
+        ...
+        </context>
+
+        <query>
+        [user query]
+        </query>
+
+        Please answer the query using ONLY the information provided...
+        ```
+
+        The method:
+        1. Selects chunks that fit within token budget
+        2. Formats each chunk with source URL
+        3. Wraps in XML tags
+        4. Adds system instructions
+
+        Args:
+            query: User's natural language question
+            chunks: Retrieved documentation chunks (sorted by relevance)
+            model: OpenAI model for token counting (default: gpt-3.5-turbo)
+
+        Returns:
+            Formatted prompt string ready for OpenAI API
+
+        Example:
+            >>> builder = PromptBuilder(max_tokens=3000)
+            >>> prompt = builder.build_prompt("What is ROS 2?", chunks)
+            >>> print(prompt[:100])
+            <context>
+            ROS 2 is a set of software libraries and tools...
+        """
+        logger.info(
+            f"Building prompt",
+            extra={
+                "query": query[:50] + "..." if len(query) > 50 else query,
+                "total_chunks": len(chunks),
+                "model": model
+            }
+        )
+
+        # Select chunks that fit within budget (T036)
+        selected_chunks = self._select_chunks_within_budget(chunks, model)
+
+        # Format context with chunks and source URLs (T037)
+        context = self._format_context_with_sources(selected_chunks)
+
+        # Build full prompt with XML template (T034)
+        prompt = self._format_prompt_with_xml(context, query)
+
+        # Count final tokens
+        final_tokens = count_tokens(prompt, model)
+
+        logger.info(
+            f"Prompt built successfully",
+            extra={
+                "query": query[:50] + "..." if len(query) > 50 else query,
+                "selected_chunks": len(selected_chunks),
+                "total_chunks": len(chunks),
+                "final_tokens": final_tokens,
+                "max_tokens": self.max_tokens
+            }
+        )
+
+        return prompt
+
+    def _select_chunks_within_budget(
+        self,
+        chunks: List[SearchResult],
+        model: str
+    ) -> List[SearchResult]:
+        """
+        Select top-scoring chunks that fit within token budget.
+
+        Iterates through chunks (already sorted by relevance) and adds
+        them to context until budget is exhausted. Prioritizes higher-scoring
+        chunks when space is limited.
+
+        Args:
+            chunks: Retrieved chunks sorted by relevance (highest first)
+            model: Model for token counting
+
+        Returns:
+            List of chunks that fit within context_budget
+        """
+        selected = []
+        total_tokens = 0
+
+        for chunk in chunks:
+            # Format chunk with source for accurate token count
+            chunk_text = chunk.text
+            source_url = chunk.metadata.get('url', '')
+            formatted_chunk = f"{chunk_text}\nSource: {source_url}\n"
+
+            # Count tokens for this chunk
+            chunk_tokens = count_tokens(formatted_chunk, model)
+
+            # Check if adding this chunk would exceed budget
+            if total_tokens + chunk_tokens > self.context_budget:
+                logger.warning(
+                    f"Hit token budget, truncating context at {len(selected)} chunks",
+                    extra={
+                        "selected_chunks": len(selected),
+                        "total_chunks": len(chunks),
+                        "current_tokens": total_tokens,
+                        "context_budget": self.context_budget
+                    }
+                )
+                break
+
+            selected.append(chunk)
+            total_tokens += chunk_tokens
+
+        logger.debug(
+            f"Selected {len(selected)} chunks using {total_tokens} tokens"
+        )
+
+        return selected
+
+    def _format_context_with_sources(self, chunks: List[SearchResult]) -> str:
+        """
+        Format chunks with source URLs.
+
+        Each chunk is formatted as:
+        ```
+        [chunk text]
+        Source: [url]
+        ```
+
+        Args:
+            chunks: Selected chunks to format
+
+        Returns:
+            Formatted context string with sources
+        """
+        context_parts = []
+
+        for chunk in chunks:
+            chunk_text = chunk.text
+            source_url = chunk.metadata.get('url', 'Unknown')
+
+            # Format: chunk text + source URL
+            formatted_chunk = f"{chunk_text}\nSource: {source_url}"
+            context_parts.append(formatted_chunk)
+
+        # Join with blank line between chunks
+        context = "\n\n".join(context_parts)
+
+        return context
+
+    def _format_prompt_with_xml(self, context: str, query: str) -> str:
+        """
+        Format prompt with XML tags and system instructions.
+
+        Creates the final prompt structure:
+        ```
+        <context>
+        [formatted context with sources]
+        </context>
+
+        <query>
+        [user query]
+        </query>
+
+        [system instructions]
+        ```
+
+        Args:
+            context: Formatted context with chunks and sources
+            query: User query
+
+        Returns:
+            Complete formatted prompt
+        """
+        # Build prompt with XML delimiters (T034)
+        prompt = f"""<context>
+{context}
+</context>
+
+<query>
+{query}
+</query>
+
+Please answer the query using ONLY the information provided in the context above. If the context doesn't contain enough information to answer the query, say so. Be concise and cite specific details from the context."""
+
+        return prompt

services/retrieval_service.py

@@ -0,0 +1,147 @@
+"""
+Retrieval Service for RAG Agent
+
+Provides a clean service layer abstraction over the retrieval pipeline.
+Wraps retrieval.py functions with enhanced error handling and logging.
+
+This service:
+1. Embeds user queries using Cohere
+2. Searches Qdrant for relevant documentation chunks
+3. Handles errors gracefully
+4. Provides detailed logging and metrics
+
+Usage:
+    from services.retrieval_service import RetrievalService
+
+    retrieval_service = RetrievalService()
+    results = retrieval_service.retrieve_context("How do I create a publisher?", top_k=5)
+"""
+
+import logging
+from typing import List
+from datetime import datetime
+
+from retrieval import embed_query, search_qdrant, SearchResult
+from exceptions import RetrievalError
+
+logger = logging.getLogger('retrieval_service')
+
+
+class RetrievalService:
+    """
+    Service for retrieving relevant documentation chunks.
+
+    This service wraps the lower-level retrieval.py functions and provides:
+    - Enhanced error handling with custom exceptions
+    - Detailed logging with metrics (latency, relevance scores)
+    - Clean abstraction for integration layer
+
+    Methods:
+        retrieve_context: Retrieve relevant chunks for a query
+    """
+
+    def __init__(self):
+        """Initialize retrieval service."""
+        logger.info("RetrievalService initialized")
+
+    def retrieve_context(self, query: str, top_k: int = 5) -> List[SearchResult]:
+        """
+        Retrieve relevant documentation chunks for a query.
+
+        This method:
+        1. Embeds the query using Cohere (via retrieval.embed_query)
+        2. Searches Qdrant for similar chunks (via retrieval.search_qdrant)
+        3. Calculates and logs relevance metrics
+        4. Handles errors with specific error messages
+
+        Args:
+            query: User's natural language question
+            top_k: Number of chunks to retrieve (default 5)
+
+        Returns:
+            List of SearchResult objects with text, metadata, and relevance scores
+
+        Raises:
+            RetrievalError: If embedding fails (Cohere issue)
+            RetrievalError: If vector search fails (Qdrant issue)
+
+        Example:
+            >>> service = RetrievalService()
+            >>> results = service.retrieve_context("What is ROS 2?", top_k=5)
+            >>> print(f"Retrieved {len(results)} chunks")
+            >>> print(f"Top score: {results[0].score}")
+        """
+        start_time = datetime.utcnow()
+
+        logger.info(
+            f"Starting retrieval",
+            extra={
+                "query": query[:50] + "..." if len(query) > 50 else query,
+                "top_k": top_k
+            }
+        )
+
+        try:
+            # Step 1: Embed query using Cohere
+            logger.debug(f"Embedding query with Cohere")
+            query_embedding = embed_query(query)
+
+        except ValueError as e:
+            # Handle validation errors from retrieval.py
+            error_message = f"Query embedding failed: {str(e)}"
+            logger.error(error_message, exc_info=True)
+            raise RetrievalError(error_message)
+
+        except Exception as e:
+            # Handle Cohere API failures
+            error_message = f"Query embedding failed: {str(e)}"
+            logger.error(
+                error_message,
+                extra={"query": query, "error_type": type(e).__name__},
+                exc_info=True
+            )
+            raise RetrievalError(error_message)
+
+        try:
+            # Step 2: Search Qdrant for similar chunks
+            logger.debug(f"Searching Qdrant with top_k={top_k}")
+            results = search_qdrant(query_embedding, top_k=top_k)
+
+        except ValueError as e:
+            # Handle validation errors from retrieval.py
+            error_message = f"Vector database search failed: {str(e)}"
+            logger.error(error_message, exc_info=True)
+            raise RetrievalError(error_message)
+
+        except Exception as e:
+            # Handle Qdrant connection/query failures
+            error_message = f"Vector database unavailable: {str(e)}"
+            logger.error(
+                error_message,
+                extra={"query": query, "top_k": top_k, "error_type": type(e).__name__},
+                exc_info=True
+            )
+            raise RetrievalError("Vector database unavailable")
+
+        # Calculate metrics
+        latency_ms = int((datetime.utcnow() - start_time).total_seconds() * 1000)
+        retrieval_count = len(results)
+
+        # Calculate average relevance score
+        average_relevance_score = 0.0
+        if retrieval_count > 0:
+            average_relevance_score = sum(r.score for r in results) / retrieval_count
+
+        # Log success with metrics
+        logger.info(
+            f"Retrieval completed successfully",
+            extra={
+                "query": query[:50] + "..." if len(query) > 50 else query,
+                "top_k": top_k,
+                "retrieval_count": retrieval_count,
+                "average_relevance_score": round(average_relevance_score, 4),
+                "retrieval_latency_ms": latency_ms
+            }
+        )
+
+        return results

services/translation_service.py

@@ -0,0 +1,292 @@
+"""
+Translation Service for English to Urdu translation using mBART model.
+
+This service handles:
+- Loading and managing the mBART translation model
+- Translating text content from English to Urdu
+- Content extraction (excluding code blocks)
+- Server-side caching with TTL and LRU eviction
+- Error handling and timeout management
+"""
+
+import asyncio
+import hashlib
+import logging
+from datetime import datetime, timedelta
+from typing import Dict, Optional, Tuple
+from bs4 import BeautifulSoup
+import time
+
+# Translation model imports (will be loaded lazily)
+try:
+    from transformers import MBartForConditionalGeneration, MBart50TokenizerFast
+    TRANSFORMERS_AVAILABLE = True
+except ImportError:
+    TRANSFORMERS_AVAILABLE = False
+    logging.warning("Transformers library not available. Translation service will be disabled.")
+
+logger = logging.getLogger(__name__)
+
+
+class TranslationCache:
+    """Server-side cache for translations with TTL and LRU eviction"""
+
+    def __init__(self, ttl_seconds: int = 86400, max_size_bytes: int = 1_000_000_000):
+        """
+        Initialize translation cache
+
+        Args:
+            ttl_seconds: Time-to-live for cache entries (default: 24 hours)
+            max_size_bytes: Maximum cache size in bytes (default: 1GB)
+        """
+        self.cache: Dict[str, Dict] = {}
+        self.ttl_seconds = ttl_seconds
+        self.max_size_bytes = max_size_bytes
+        self.access_times: Dict[str, float] = {}
+
+    def get(self, key: str) -> Optional[str]:
+        """
+        Get cached translation if not expired
+
+        Args:
+            key: Cache key (hash of content)
+
+        Returns:
+            Translated text if found and not expired, None otherwise
+        """
+        if key not in self.cache:
+            return None
+
+        entry = self.cache[key]
+        created_at = datetime.fromisoformat(entry["timestamp"])
+        age = datetime.now() - created_at
+
+        # Check if expired
+        if age.total_seconds() > self.ttl_seconds:
+            del self.cache[key]
+            del self.access_times[key]
+            return None
+
+        # Update access time for LRU
+        self.access_times[key] = time.time()
+        return entry["translated"]
+
+    def set(self, key: str, translated_text: str):
+        """
+        Store translation in cache
+
+        Args:
+            key: Cache key (hash of content)
+            translated_text: Translated text to cache
+        """
+        # Evict if cache is too large
+        self._evict_if_needed()
+
+        self.cache[key] = {
+            "translated": translated_text,
+            "timestamp": datetime.now().isoformat(),
+            "access_count": 1
+        }
+        self.access_times[key] = time.time()
+
+    def _evict_if_needed(self):
+        """Evict least recently used entries if cache exceeds size limit"""
+        current_size = self._estimate_size()
+
+        while current_size > self.max_size_bytes and self.cache:
+            # Find least recently used entry
+            lru_key = min(self.access_times, key=self.access_times.get)
+            del self.cache[lru_key]
+            del self.access_times[lru_key]
+            current_size = self._estimate_size()
+
+    def _estimate_size(self) -> int:
+        """Estimate cache size in bytes"""
+        total_size = 0
+        for entry in self.cache.values():
+            total_size += len(entry["translated"].encode('utf-8'))
+        return total_size
+
+    def clear(self) -> int:
+        """Clear all cache entries. Returns number of entries cleared."""
+        count = len(self.cache)
+        self.cache.clear()
+        self.access_times.clear()
+        return count
+
+    def get_stats(self) -> Dict:
+        """Get cache statistics"""
+        total_entries = len(self.cache)
+        total_size_mb = self._estimate_size() / (1024 * 1024)
+
+        oldest_age_hours = 0
+        if self.cache:
+            oldest_timestamp = min(
+                datetime.fromisoformat(entry["timestamp"])
+                for entry in self.cache.values()
+            )
+            oldest_age_hours = (datetime.now() - oldest_timestamp).total_seconds() / 3600
+
+        return {
+            "total_entries": total_entries,
+            "total_size_mb": round(total_size_mb, 2),
+            "oldest_entry_age_hours": round(oldest_age_hours, 2)
+        }
+
+
+class TranslationService:
+    """Service for translating English text to Urdu using mBART"""
+
+    def __init__(self):
+        self.model = None
+        self.tokenizer = None
+        self.model_name = "facebook/mbart-large-50-many-to-many-mmt"
+        self.cache = TranslationCache()
+        self._model_loading = False
+        self._model_loaded = False
+
+    async def load_model(self):
+        """Load mBART model (lazy loading on first translation request)"""
+        if self._model_loaded or not TRANSFORMERS_AVAILABLE:
+            return
+
+        if self._model_loading:
+            # Wait for concurrent load to complete
+            while self._model_loading:
+                await asyncio.sleep(0.1)
+            return
+
+        self._model_loading = True
+        try:
+            logger.info(f"Loading translation model: {self.model_name}")
+            # Note: Actual model loading would happen here
+            # For now, we'll mark as loaded but note that actual inference won't work
+            # until the model is properly downloaded
+            logger.warning(
+                "Translation model loading skipped in setup phase. "
+                "Run 'python -c \"from transformers import MBartForConditionalGeneration; "
+                "MBartForConditionalGeneration.from_pretrained('facebook/mbart-large-50-many-to-many-mmt')\" "
+                "to download the model."
+            )
+            self._model_loaded = True
+            logger.info("Translation service initialized (model download pending)")
+        except Exception as e:
+            logger.error(f"Failed to load translation model: {e}")
+            raise
+        finally:
+            self._model_loading = False
+
+    def extract_translatable_content(self, html: str) -> Tuple[str, Dict[str, str]]:
+        """
+        Extract translatable content from HTML, excluding code blocks
+
+        Args:
+            html: HTML string to process
+
+        Returns:
+            Tuple of (processable_html, placeholders_dict)
+        """
+        soup = BeautifulSoup(html, 'html.parser')
+
+        # Tags to exclude from translation
+        EXCLUDE_TAGS = ['code', 'pre', 'script', 'style']
+
+        placeholders = {}
+        for i, tag in enumerate(soup.find_all(EXCLUDE_TAGS)):
+            placeholder = f"__SKIP_{i}__"
+            placeholders[placeholder] = str(tag)
+            tag.replace_with(placeholder)
+
+        return str(soup), placeholders
+
+    def restore_excluded_content(self, translated_html: str, placeholders: Dict[str, str]) -> str:
+        """
+        Restore excluded content (code blocks) after translation
+
+        Args:
+            translated_html: Translated HTML with placeholders
+            placeholders: Dictionary of placeholders and their original content
+
+        Returns:
+            Final HTML with code blocks restored
+        """
+        for placeholder, original_content in placeholders.items():
+            translated_html = translated_html.replace(placeholder, original_content)
+
+        return translated_html
+
+    async def translate_text(
+        self,
+        text: str,
+        source_lang: str = "en_XX",
+        target_lang: str = "ur_PK",
+        timeout_seconds: int = 10
+    ) -> str:
+        """
+        Translate text from English to Urdu
+
+        Args:
+            text: Text to translate
+            source_lang: Source language code (mBART format)
+            target_lang: Target language code (mBART format)
+            timeout_seconds: Maximum time for translation
+
+        Returns:
+            Translated text
+
+        Raises:
+            TimeoutError: If translation exceeds timeout
+            RuntimeError: If model not loaded or translation fails
+        """
+        # Check cache first
+        cache_key = hashlib.md5(text.encode('utf-8')).hexdigest()
+        cached = self.cache.get(cache_key)
+        if cached:
+            logger.debug(f"Cache hit for key: {cache_key}")
+            return cached
+
+        # Ensure model is loaded
+        await self.load_model()
+
+        if not self._model_loaded:
+            raise RuntimeError("Translation model not loaded")
+
+        try:
+            # For now, return a placeholder since actual model isn't loaded
+            # In production, this would call the actual mBART model:
+            #
+            # self.tokenizer.src_lang = source_lang
+            # encoded = self.tokenizer(text, return_tensors="pt")
+            # generated = self.model.generate(
+            #     **encoded,
+            #     forced_bos_token_id=self.tokenizer.lang_code_to_id[target_lang]
+            # )
+            # translated = self.tokenizer.batch_decode(generated, skip_special_tokens=True)[0]
+
+            # Placeholder implementation
+            translated = f"[URDU TRANSLATION PLACEHOLDER]: {text}"
+            logger.warning("Using placeholder translation (model not actually loaded)")
+
+            # Cache the result
+            self.cache.set(cache_key, translated)
+
+            return translated
+
+        except asyncio.TimeoutError:
+            logger.error(f"Translation timeout after {timeout_seconds} seconds")
+            raise TimeoutError(f"Translation took longer than {timeout_seconds} seconds")
+        except Exception as e:
+            logger.error(f"Translation failed: {e}")
+            raise RuntimeError(f"Translation failed: {str(e)}")
+
+
+# Global service instance
+_translation_service: Optional[TranslationService] = None
+
+
+def get_translation_service() -> TranslationService:
+    """Get or create the global translation service instance"""
+    global _translation_service
+    if _translation_service is None:
+        _translation_service = TranslationService()
+    return _translation_service