Deploy backend from GitHub Actions

🚀 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

.env.hf

@@ -0,0 +1,122 @@
+# =============================================================================
+# HuggingFace Spaces Environment Variables
+# =============================================================================
+# Configure these in your HuggingFace Space settings (Repository > Settings > Variables)
+
+# =============================================================================
+# Required API Keys (Configure in HF Space Settings)
+# =============================================================================
+# OpenAI API Key - Required for translation service
+# Add as secret: OPENAI_API_KEY
+OPENAI_API_KEY=
+
+# OpenRouter API Key - Required for AI chat service
+# Add as secret: OPENROUTER_API_KEY
+OPENROUTER_API_KEY=
+
+# Google Gemini API Key - Alternative AI service
+# Add as secret: GEMINI_API_KEY
+GEMINI_API_KEY=
+
+# =============================================================================
+# Database Configuration
+# =============================================================================
+# SQLite Database URL (HF Spaces default)
+DATABASE_URL=sqlite:///./database/auth.db
+
+# =============================================================================
+# Vector Database (Qdrant) Configuration
+# =============================================================================
+# Qdrant URL for vector storage (optional - defaults to local)
+QDRANT_URL=http://localhost:6333
+
+# =============================================================================
+# Model Configuration
+# =============================================================================
+# OpenAI Model for translation (use stable model)
+OPENAI_MODEL=gpt-4o-mini
+
+# OpenRouter Model for chat (use free tier model for reliability)
+OPENROUTER_MODEL=meta-llama/llama-3.2-3b-instruct:free
+
+# Gemini Model configuration
+GEMINI_MODEL=gemini-2.0-flash-lite
+
+# =============================================================================
+# HuggingFace Spaces Auto-Configuration
+# =============================================================================
+# These are automatically set by HF Spaces
+SPACE_ID=
+HF_HOME=/app/.cache/huggingface
+TRANSFORMERS_CACHE=/app/.cache/transformers
+
+# =============================================================================
+# Server Configuration
+# =============================================================================
+# Server port (HF Spaces default - must be 7860)
+PORT=7860
+
+# Server host (required for containerized deployments)
+HOST=0.0.0.0
+
+# Number of worker processes (keep at 1 for HF Spaces free tier)
+WORKERS=1
+
+# Log level (INFO for production, DEBUG for troubleshooting)
+LOG_LEVEL=INFO
+
+# =============================================================================
+# Environment Detection
+# =============================================================================
+NODE_ENV=production
+ENVIRONMENT=production
+
+# =============================================================================
+# Security Configuration
+# =============================================================================
+# JWT Secret Key (generate a strong random string)
+# Add as secret: JWT_SECRET_KEY
+JWT_SECRET_KEY=
+
+# JWT Algorithm
+JWT_ALGORITHM=HS256
+
+# JWT Expiration Time (7 days)
+JWT_EXPIRE_MINUTES=10080
+
+# =============================================================================
+# CORS Configuration
+# =============================================================================
+# Allowed origins for HF Spaces
+CORS_ORIGINS=https://huggingface.co,https://*.hf.space,https://mrowaisabdullah.github.io
+
+# =============================================================================
+# Rate Limiting (Conservative for HF Spaces)
+# =============================================================================
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_RPM=30
+RATE_LIMIT_RPH=500
+TRANSLATION_RPM=5
+
+# =============================================================================
+# Cache Configuration (Memory-based for HF Spaces)
+# =============================================================================
+CACHE_BACKEND=memory
+CACHE_DEFAULT_TTL=24
+REDIS_URL=
+
+# =============================================================================
+# Feature Flags (Optimized for HF Spaces)
+# =============================================================================
+FEATURE_STREAMING=true
+FEATURE_QUALITY_CHECK=false
+FEATURE_BATCH_TRANSLATION=false
+OPENAI_AGENTS_ENABLED=false
+
+# =============================================================================
+# Monitoring (Basic for HF Spaces)
+# =============================================================================
+MONITORING_ENABLED=true
+HEALTH_ENDPOINT=/health
+LOG_FILE_ENABLED=true
+LOG_FILE_PATH=logs/app.log

Dockerfile

@@ -1,11 +1,14 @@
-# Use Python 3.11 slim image
+# Use Python 3.11 slim image for Hugging Face Spaces
 FROM python:3.11-slim
 
-# Set environment variables
+# Set environment variables for HF Spaces
 ENV PYTHONUNBUFFERED=1 \
     PYTHONDONTWRITEBYTECODE=1 \
     PIP_NO_CACHE_DIR=1 \
-    PIP_DISABLE_PIP_VERSION_CHECK=1
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    HF_HOME=/app/.cache/huggingface \
+    TRANSFORMERS_CACHE=/app/.cache/transformers \
+    PORT=7860
 
 # Set the working directory
 WORKDIR /app
@@ -16,7 +19,12 @@ RUN apt-get update && apt-get install -y \
     g++ \
     curl \
     build-essential \
-    && rm -rf /var/lib/apt/lists/*
+    git \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+# Create cache directories
+RUN mkdir -p /app/.cache/huggingface /app/.cache/transformers /app/logs
 
 # Copy requirements first for better caching
 COPY pyproject.toml ./
@@ -31,9 +39,10 @@ COPY . .
 # Create necessary directories and set permissions
 RUN mkdir -p database logs && \
     touch database/auth.db && \
-    chmod +x start_server.py
+    chmod +x start_server.py && \
+    chmod -R 755 /app
 
-# For HF Spaces, we run as root to avoid permission issues
+# For HF Spaces compatibility, run as root (avoid permission issues)
 # USER user
 
 # Expose the port (HF Spaces default)
@@ -43,5 +52,5 @@ EXPOSE 7860
 HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
     CMD curl -f http://localhost:7860/health || exit 1
 
-# Run the application
+# Run the application with proper error handling
 CMD ["python", "start_server.py"]

Dockerfile.hf

@@ -0,0 +1,58 @@
+# Use Python 3.11 slim image for Hugging Face Spaces
+FROM python:3.11-slim
+
+# Set environment variables for HF Spaces
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    HF_HOME=/app/.cache/huggingface \
+    TRANSFORMERS_CACHE=/app/.cache/transformers \
+    PORT=7860
+
+# Set the working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    g++ \
+    curl \
+    build-essential \
+    git \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+# Create cache directories
+RUN mkdir -p /app/.cache/huggingface /app/.cache/transformers /app/logs
+
+# Copy requirements first for better caching
+COPY pyproject.toml ./
+
+# Install Python dependencies
+RUN pip install --upgrade pip setuptools wheel
+RUN pip install --no-cache-dir -e .
+
+# Copy the rest of the application code
+COPY . .
+
+# Create necessary directories and set permissions
+RUN mkdir -p database logs && \
+    touch database/auth.db && \
+    chmod +x start_server.py && \
+    chmod -R 755 /app
+
+# Create non-root user for security (commented out for HF Spaces compatibility)
+# RUN adduser --disabled-password --gecos '' appuser && \
+#     chown -R appuser:appuser /app
+# USER appuser
+
+# Expose the port (HF Spaces default)
+EXPOSE 7860
+
+# Health check for HF Spaces monitoring
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Run the application with proper error handling
+CMD ["python", "start_server.py"]

rag/chat.py

@@ -58,7 +58,7 @@ class ChatHandler:
         self.retrieval_engine = RetrievalEngine(
             qdrant_manager=qdrant_manager,
             embedder=self.embedder,
-            score_threshold=0.5,  # Lowered to 0.5 to better match document scores
+            score_threshold=0.2,  # Lowered to 0.2 to match document scores (0.38+)
             enable_mmr=True,
             mmr_lambda=0.5
         )
@@ -77,19 +77,19 @@ class ChatHandler:
         Returns:
             Adaptive threshold value
         """
-        base_threshold = 0.5
+        base_threshold = 0.2
 
         # Lower threshold for very specific queries (longer)
         if query_length > 100:
-            return max(0.5, base_threshold - 0.2)
+            return max(0.1, base_threshold - 0.1)
 
         # Raise threshold if too many results found
         if result_count > 20:
-            return min(0.9, base_threshold + 0.2)
+            return min(0.5, base_threshold + 0.3)
 
         # Lower threshold if very few results found
         if result_count < 3:
-            return max(0.5, base_threshold - 0.1)
+            return max(0.1, base_threshold - 0.1)
 
         return base_threshold
 

start_server.py

@@ -1,46 +1,188 @@
 """
-Startup script for Hugging Face Spaces deployment.
-Initializes the database and starts the FastAPI server.
+Robust startup script for Hugging Face Spaces deployment.
+Initializes the database and starts the FastAPI server with comprehensive error handling.
 """
 import os
 import sys
+import time
+import logging
+import asyncio
 from pathlib import Path
 import subprocess
+from datetime import datetime
 
-def main():
-    """Initialize database and start the server."""
-    print("🚀 Starting server initialization...")
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.FileHandler('logs/startup.log'),
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+logger = logging.getLogger(__name__)
 
-    # Change to backend directory if needed
-    if os.path.exists("backend"):
-        os.chdir("backend")
-        print("Changed to backend directory")
+def check_environment():
+    """Check if required environment variables are set."""
+    logger.info("🔍 Checking environment variables...")
 
-    # Initialize database first
-    print("📦 Initializing database...")
-    result = subprocess.run([sys.executable, "init_database.py"], capture_output=True, text=True)
-    if result.returncode == 0:
-        print("✅ Database initialization completed successfully!")
-    else:
-        print(f"⚠️ Database initialization failed: {result.stderr}")
+    required_vars = ['OPENAI_API_KEY', 'OPENROUTER_API_KEY']
+    missing_vars = []
+
+    for var in required_vars:
+        if not os.getenv(var):
+            missing_vars.append(var)
+            logger.error(f"❌ {var} is not set")
+        else:
+            logger.info(f"✅ {var} is set")
+
+    # Optional variables
+    optional_vars = ['DATABASE_URL', 'QDRANT_URL', 'HF_SPACE_ID']
+    for var in optional_vars:
+        if os.getenv(var):
+            logger.info(f"✅ {var} is set")
+        else:
+            logger.info(f"⚠️ {var} is not set (optional)")
+
+    if missing_vars:
+        logger.error(f"❌ Missing required environment variables: {missing_vars}")
+        return False
+
+    return True
 
-    # Check if database file exists
+def initialize_database():
+    """Initialize the database with retries."""
+    logger.info("📦 Initializing database...")
+    max_retries = 3
+
+    for attempt in range(max_retries):
+        try:
+            # Check if init_database.py exists
+            if not Path("init_database.py").exists():
+                logger.warning("⚠️ init_database.py not found, skipping database initialization")
+                return True
+
+            result = subprocess.run(
+                [sys.executable, "init_database.py"],
+                capture_output=True,
+                text=True,
+                timeout=30
+            )
+
+            if result.returncode == 0:
+                logger.info("✅ Database initialization completed successfully!")
+                if result.stdout:
+                    logger.info(f"Database init output: {result.stdout}")
+                return True
+            else:
+                logger.error(f"⚠️ Database initialization attempt {attempt + 1} failed: {result.stderr}")
+                if attempt < max_retries - 1:
+                    time.sleep(2)
+
+        except subprocess.TimeoutExpired:
+            logger.error(f"⚠️ Database initialization timeout on attempt {attempt + 1}")
+            if attempt < max_retries - 1:
+                time.sleep(2)
+        except Exception as e:
+            logger.error(f"⚠️ Database initialization error on attempt {attempt + 1}: {str(e)}")
+            if attempt < max_retries - 1:
+                time.sleep(2)
+
+    logger.error("❌ Database initialization failed after all attempts")
+    return False
+
+def verify_database_file():
+    """Check if database file exists and is accessible."""
     db_path = Path("database/auth.db")
     if db_path.exists():
-        print("✅ Database file found!")
+        try:
+            size = db_path.stat().st_size
+            logger.info(f"✅ Database file found! Size: {size} bytes")
+            return True
+        except Exception as e:
+            logger.error(f"❌ Error accessing database file: {str(e)}")
+            return False
     else:
-        print("⚠️ Database file not found. The server will create it on startup.")
+        logger.info("⚠️ Database file not found. The server will create it on startup.")
+        return True
+
+def create_directories():
+    """Create necessary directories."""
+    directories = ['database', 'logs', '.cache/huggingface', '.cache/transformers']
+    for directory in directories:
+        Path(directory).mkdir(parents=True, exist_ok=True)
+        logger.info(f"✅ Directory {directory} ready")
+
+def start_server():
+    """Start the FastAPI server with error handling."""
+    logger.info("🌟 Starting FastAPI server...")
+
+    # Get port from environment or use default
+    port = int(os.getenv('PORT', 7860))
+    host = os.getenv('HOST', '0.0.0.0')
+    workers = int(os.getenv('WORKERS', 1))
+
+    cmd = [
+        sys.executable, "-m", "uvicorn",
+        "main:app",
+        "--host", host,
+        "--port", str(port),
+        "--workers", str(workers),
+        "--log-level", "info",
+        "--access-log"
+    ]
+
+    logger.info(f"Command: {' '.join(cmd)}")
+
+    try:
+        # Replace current process with uvicorn
+        os.execvp(sys.executable, cmd)
+    except Exception as e:
+        logger.error(f"❌ Failed to start server: {str(e)}")
+        sys.exit(1)
+
+def main():
+    """Main startup function."""
+    logger.info("🚀 Starting server initialization for Hugging Face Spaces...")
+    logger.info(f"📅 Timestamp: {datetime.utcnow().isoformat()}")
+    logger.info(f"🐍 Python version: {sys.version}")
+    logger.info(f"📁 Working directory: {os.getcwd()}")
+
+    # Change to backend directory if needed
+    if os.path.exists("backend") and not os.getcwd().endswith("backend"):
+        os.chdir("backend")
+        logger.info(f"Changed to backend directory: {os.getcwd()}")
+
+    try:
+        # Create necessary directories
+        create_directories()
+
+        # Check environment
+        if not check_environment():
+            logger.error("❌ Environment check failed. Exiting...")
+            sys.exit(1)
+
+        # Initialize database
+        if not initialize_database():
+            logger.error("❌ Database initialization failed. Continuing anyway...")
+
+        # Verify database file
+        verify_database_file()
 
-    # Print environment variables for debugging
-    print("🔍 Environment check:")
-    print(f"  - OPENAI_API_KEY: {'✅' if os.getenv('OPENAI_API_KEY') else '❌'}")
-    print(f"  - OPENROUTER_API_KEY: {'✅' if os.getenv('OPENROUTER_API_KEY') else '❌'}")
-    print(f"  - DATABASE_URL: {'✅' if os.getenv('DATABASE_URL') else '❌'}")
+        # Print final status
+        logger.info("🎉 Initialization completed successfully!")
+        logger.info(f"🌍 Environment: {'HF Spaces' if os.getenv('SPACE_ID') else 'Local'}")
+        logger.info(f"🔧 Port: {os.getenv('PORT', 7860)}")
 
-    # Start the FastAPI server
-    print("🌟 Starting FastAPI server...")
-    os.execvp(sys.executable, [sys.executable, "-m", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"])
+        # Start server
+        start_server()
 
+    except KeyboardInterrupt:
+        logger.info("⏹️ Startup interrupted by user")
+        sys.exit(0)
+    except Exception as e:
+        logger.error(f"💥 Fatal error during startup: {str(e)}", exc_info=True)
+        sys.exit(1)
 
 if __name__ == "__main__":
     main()

start_server_hf.py

@@ -0,0 +1,188 @@
+"""
+Robust startup script for Hugging Face Spaces deployment.
+Initializes the database and starts the FastAPI server with comprehensive error handling.
+"""
+import os
+import sys
+import time
+import logging
+import asyncio
+from pathlib import Path
+import subprocess
+from datetime import datetime
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    handlers=[
+        logging.FileHandler('/app/logs/startup.log'),
+        logging.StreamHandler(sys.stdout)
+    ]
+)
+logger = logging.getLogger(__name__)
+
+def check_environment():
+    """Check if required environment variables are set."""
+    logger.info("🔍 Checking environment variables...")
+
+    required_vars = ['OPENAI_API_KEY', 'OPENROUTER_API_KEY']
+    missing_vars = []
+
+    for var in required_vars:
+        if not os.getenv(var):
+            missing_vars.append(var)
+            logger.error(f"❌ {var} is not set")
+        else:
+            logger.info(f"✅ {var} is set")
+
+    # Optional variables
+    optional_vars = ['DATABASE_URL', 'QDRANT_URL', 'HF_SPACE_ID']
+    for var in optional_vars:
+        if os.getenv(var):
+            logger.info(f"✅ {var} is set")
+        else:
+            logger.info(f"⚠️ {var} is not set (optional)")
+
+    if missing_vars:
+        logger.error(f"❌ Missing required environment variables: {missing_vars}")
+        return False
+
+    return True
+
+def initialize_database():
+    """Initialize the database with retries."""
+    logger.info("📦 Initializing database...")
+    max_retries = 3
+
+    for attempt in range(max_retries):
+        try:
+            # Check if init_database.py exists
+            if not Path("init_database.py").exists():
+                logger.warning("⚠️ init_database.py not found, skipping database initialization")
+                return True
+
+            result = subprocess.run(
+                [sys.executable, "init_database.py"],
+                capture_output=True,
+                text=True,
+                timeout=30
+            )
+
+            if result.returncode == 0:
+                logger.info("✅ Database initialization completed successfully!")
+                if result.stdout:
+                    logger.info(f"Database init output: {result.stdout}")
+                return True
+            else:
+                logger.error(f"⚠️ Database initialization attempt {attempt + 1} failed: {result.stderr}")
+                if attempt < max_retries - 1:
+                    time.sleep(2)
+
+        except subprocess.TimeoutExpired:
+            logger.error(f"⚠️ Database initialization timeout on attempt {attempt + 1}")
+            if attempt < max_retries - 1:
+                time.sleep(2)
+        except Exception as e:
+            logger.error(f"⚠️ Database initialization error on attempt {attempt + 1}: {str(e)}")
+            if attempt < max_retries - 1:
+                time.sleep(2)
+
+    logger.error("❌ Database initialization failed after all attempts")
+    return False
+
+def verify_database_file():
+    """Check if database file exists and is accessible."""
+    db_path = Path("database/auth.db")
+    if db_path.exists():
+        try:
+            size = db_path.stat().st_size
+            logger.info(f"✅ Database file found! Size: {size} bytes")
+            return True
+        except Exception as e:
+            logger.error(f"❌ Error accessing database file: {str(e)}")
+            return False
+    else:
+        logger.info("⚠️ Database file not found. The server will create it on startup.")
+        return True
+
+def create_directories():
+    """Create necessary directories."""
+    directories = ['database', 'logs', '.cache/huggingface', '.cache/transformers']
+    for directory in directories:
+        Path(directory).mkdir(parents=True, exist_ok=True)
+        logger.info(f"✅ Directory {directory} ready")
+
+def start_server():
+    """Start the FastAPI server with error handling."""
+    logger.info("🌟 Starting FastAPI server...")
+
+    # Get port from environment or use default
+    port = int(os.getenv('PORT', 7860))
+    host = os.getenv('HOST', '0.0.0.0')
+    workers = int(os.getenv('WORKERS', 1))
+
+    cmd = [
+        sys.executable, "-m", "uvicorn",
+        "main:app",
+        "--host", host,
+        "--port", str(port),
+        "--workers", str(workers),
+        "--log-level", "info",
+        "--access-log"
+    ]
+
+    logger.info(f"Command: {' '.join(cmd)}")
+
+    try:
+        # Replace current process with uvicorn
+        os.execvp(sys.executable, cmd)
+    except Exception as e:
+        logger.error(f"❌ Failed to start server: {str(e)}")
+        sys.exit(1)
+
+def main():
+    """Main startup function."""
+    logger.info("🚀 Starting server initialization for Hugging Face Spaces...")
+    logger.info(f"📅 Timestamp: {datetime.utcnow().isoformat()}")
+    logger.info(f"🐍 Python version: {sys.version}")
+    logger.info(f"📁 Working directory: {os.getcwd()}")
+
+    # Change to backend directory if needed
+    if os.path.exists("backend") and not os.getcwd().endswith("backend"):
+        os.chdir("backend")
+        logger.info(f"Changed to backend directory: {os.getcwd()}")
+
+    try:
+        # Create necessary directories
+        create_directories()
+
+        # Check environment
+        if not check_environment():
+            logger.error("❌ Environment check failed. Exiting...")
+            sys.exit(1)
+
+        # Initialize database
+        if not initialize_database():
+            logger.error("❌ Database initialization failed. Continuing anyway...")
+
+        # Verify database file
+        verify_database_file()
+
+        # Print final status
+        logger.info("🎉 Initialization completed successfully!")
+        logger.info(f"🌍 Environment: {'HF Spaces' if os.getenv('SPACE_ID') else 'Local'}")
+        logger.info(f"🔧 Port: {os.getenv('PORT', 7860)}")
+
+        # Start server
+        start_server()
+
+    except KeyboardInterrupt:
+        logger.info("⏹️ Startup interrupted by user")
+        sys.exit(0)
+    except Exception as e:
+        logger.error(f"💥 Fatal error during startup: {str(e)}", exc_info=True)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()