Add Gradio UI with dark theme and professional card-based results

Dockerfile

@@ -1,7 +1,7 @@
-# Read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
 # SHL Assessment Recommendation Engine
+# HuggingFace Spaces with Gradio UI
 
-FROM python:3.9
+FROM python:3.10-slim
 
 RUN useradd -m -u 1000 user
 USER user
@@ -13,4 +13,7 @@ COPY --chown=user ./requirements.txt requirements.txt
 RUN pip install --no-cache-dir --upgrade -r requirements.txt
 
 COPY --chown=user . /app
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -3,41 +3,53 @@ title: SHL Assessment Recommendation Engine
 emoji: 🎯
 colorFrom: blue
 colorTo: purple
-sdk: docker
+sdk: gradio
+sdk_version: 4.44.0
+app_file: app.py
 pinned: false
 license: mit
+short_description: AI-powered SHL assessment recommendations using 2-Stage RAG
 ---
 
-# SHL Assessment Recommendation Engine
+# 🎯 SHL Assessment Recommendation Engine
 
-AI-powered assessment recommendations using 2-Stage RAG Pipeline:
+AI-powered recommendations for SHL assessments using a novel **2-Stage RAG Pipeline**.
 
-**Architecture**: Query → SBERT → FAISS → Top-K → Cross-Encoder Reranker → Results
+## 🏗️ Architecture
 
-## Performance
-- **P@1**: 1.000 (Top result always relevant)
-- **MRR**: 1.000 (First relevant at rank 1)
-- **NDCG@5**: 0.964 (Near-optimal ranking)
+```
+Query → SBERT Encoder → FAISS Index → Top-K → Cross-Encoder Reranker → Results
+```
 
-## API Endpoints
-- `GET /` - API info
-- `GET /health` - Health check  
-- `GET /recommend?query=...` - Get recommendations
-- `GET /evaluate` - Run evaluation metrics
-- `GET /docs` - Interactive API documentation
+| Component | Model | Purpose |
+|-----------|-------|---------|
+| **Retriever** | all-MiniLM-L6-v2 | Fast semantic embedding |
+| **Index** | FAISS IndexFlatIP | Efficient similarity search |
+| **Reranker** | ms-marco-MiniLM-L-6-v2 | Accurate pairwise scoring |
+| **Scoring** | Hybrid | 30% retrieval + 70% reranking |
 
-## Models Used
-| Component | Model |
-|-----------|-------|
-| Retriever | `all-MiniLM-L6-v2` |
-| Reranker | `ms-marco-MiniLM-L-6-v2` |
-| Index | FAISS (IndexFlatIP) |
+## 📊 Performance
 
-## Data
-74 SHL assessments covering:
+| Metric | Score | Interpretation |
+|--------|-------|----------------|
+| **P@1** | 0.90 | 90% top-1 accuracy |
+| **MRR** | 0.95 | First relevant at rank ~1 |
+| **NDCG@5** | 0.944 | Near-optimal ranking |
+
+## 🚀 Usage
+
+1. Enter a job description or role requirements
+2. Click "Get Recommendations"
+3. View matching SHL assessments with scores
+
+## 📚 Dataset
+
+74 SHL assessments from the [SHL Product Catalog](https://www.shl.com/products/product-catalog/) including:
 - Job Focused Assessments
 - Cognitive Assessments
 - Personality Assessments
 - Skills & Simulations
 
-Built for SHL Research Internship - December 2024
+---
+
+Built for SHL Research Internship Assessment • December 2024

app.py

@@ -1,17 +1,15 @@
-# SHL Assessment Recommendation Engine - HuggingFace Spaces
+# SHL Assessment Recommendation Engine - HuggingFace Spaces with Gradio UI
 # 2-Stage RAG Pipeline: SBERT + Cross-Encoder Reranking
-# Performance: P@1=1.0, MRR=1.0, NDCG@5=0.964
+# Performance: P@1=0.9, MRR=0.95, NDCG@5=0.944
 
 import json
 import math
 import os
 import statistics
 import numpy as np
+import gradio as gr
 from dataclasses import dataclass
 from typing import List, Optional, Dict, Any
-from fastapi import FastAPI, Query, HTTPException
-from fastapi.middleware.cors import CORSMiddleware
-from pydantic import BaseModel
 from sentence_transformers import CrossEncoder, SentenceTransformer
 import faiss
 
@@ -154,7 +152,7 @@ class SHLRecommendationEngine:
     
     Pipeline: Query -> SBERT -> FAISS -> Top-K -> Cross-Encoder -> Results
     
-    Performance: P@1=1.0, MRR=1.0, NDCG@5=0.964
+    Performance: P@1=0.9, MRR=0.95, NDCG@5=0.944
     """
     
     def __init__(self):
@@ -245,209 +243,231 @@ class SHLRecommendationEngine:
         # Sort by hybrid score and return top results
         results.sort(key=lambda x: x["similarity_score"], reverse=True)
         return results[:max_results]
-    
-    def get_architecture_info(self) -> Dict[str, Any]:
-        return {
-            "name": "2-Stage RAG Pipeline",
-            "retriever": "SBERT (all-MiniLM-L6-v2)",
-            "reranker": "Cross-Encoder (ms-marco-MiniLM-L-6-v2)",
-            "index": "FAISS IndexFlatIP",
-            "scoring": "Hybrid (30% retrieval + 70% reranking)",
-            "assessments": len(self.assessments),
-            "performance": {"P@1": 1.0, "MRR": 1.0, "NDCG@5": 0.964}
-        }
 
 
 # ============================================================================
-# EVALUATION METRICS
+# INITIALIZE ENGINE (Global singleton)
 # ============================================================================
 
-class EvaluationMetrics:
-    """Standard IR (Information Retrieval) Evaluation Metrics"""
-    
-    @staticmethod
-    def precision_at_k(retrieved: List[str], relevant: List[str], k: int) -> float:
-        """Precision@K: Fraction of top-K results that are relevant"""
-        hits = sum(1 for r in retrieved[:k] if any(rel.lower() in r.lower() for rel in relevant))
-        return hits / k if k > 0 else 0.0
-    
-    @staticmethod
-    def mean_reciprocal_rank(retrieved: List[str], relevant: List[str]) -> float:
-        """MRR: 1/rank of first relevant result"""
-        for i, r in enumerate(retrieved, 1):
-            if any(rel.lower() in r.lower() for rel in relevant):
-                return 1.0 / i
-        return 0.0
-    
-    @staticmethod
-    def ndcg_at_k(retrieved: List[str], relevant: List[str], k: int) -> float:
-        """NDCG@K: Normalized Discounted Cumulative Gain (0-1)"""
-        hits = [i for i, r in enumerate(retrieved[:k], 1) if any(rel.lower() in r.lower() for rel in relevant)]
-        if not hits:
-            return 0.0
-        dcg = sum(1.0 / math.log2(pos + 1) for pos in hits)
-        ideal = sum(1.0 / math.log2(i + 1) for i in range(1, len(hits) + 1))
-        return min(dcg / ideal, 1.0) if ideal > 0 else 0.0
+print("Initializing SHL Recommendation Engine...")
+engine = SHLRecommendationEngine()
 
 
 # ============================================================================
-# FASTAPI APPLICATION
+# GRADIO UI FUNCTIONS
 # ============================================================================
 
-# Initialize engine on startup
-engine = SHLRecommendationEngine()
-
-# Create FastAPI app
-app = FastAPI(
-    title="SHL Assessment Recommendation API",
-    description="""
-    AI-powered assessment recommendations using 2-Stage RAG Pipeline.
+def format_recommendations_html(results: List[Dict]) -> str:
+    """Format recommendations as beautiful HTML cards"""
+    if not results:
+        return "<div style='text-align: center; padding: 40px; color: #666;'>No recommendations found. Try a different query.</div>"
     
-    ## Architecture
-    - **Stage 1**: SBERT retrieval with FAISS index (fast)
-    - **Stage 2**: Cross-Encoder reranking (accurate)
-    - **Hybrid Scoring**: 30% retrieval + 70% reranking
+    html = "<div style='display: flex; flex-direction: column; gap: 16px;'>"
     
-    ## Performance
-    - **P@1**: 1.000 (Top result always relevant)
-    - **MRR**: 1.000 (First relevant at rank 1)
-    - **NDCG@5**: 0.964 (Near-optimal ranking)
-    """,
-    version="2.0.0"
-)
-
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-
-# Response models
-class AssessmentResponse(BaseModel):
-    name: str
-    url: str
-    category: str
-    job_levels: List[str]
-    focus_areas: List[str]
-    test_type: List[str]
-    duration_minutes: Optional[int]
-    remote_testing: bool
-    adaptive: bool
-    similarity_score: float
-    rerank_score: float
+    for i, r in enumerate(results, 1):
+        # Determine badge colors
+        score = r.get('similarity_score', 0)
+        if score >= 0.3:
+            score_color = "#10b981"  # Green
+        elif score >= 0.15:
+            score_color = "#f59e0b"  # Yellow
+        else:
+            score_color = "#6b7280"  # Gray
+        
+        duration = f"{r['duration_minutes']} min" if r['duration_minutes'] else "Variable"
+        adaptive = "✓ Adaptive" if r['adaptive'] else ""
+        remote = "✓ Remote" if r['remote_testing'] else ""
+        
+        html += f"""
+        <div style='background: linear-gradient(135deg, #1e293b 0%, #334155 100%); 
+                    border-radius: 12px; padding: 20px; 
+                    border-left: 4px solid {score_color};
+                    box-shadow: 0 4px 6px rgba(0,0,0,0.3);'>
+            <div style='display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 12px;'>
+                <div>
+                    <span style='background: {score_color}; color: white; padding: 4px 10px; 
+                                 border-radius: 20px; font-size: 12px; font-weight: 600;'>
+                        #{i} • Score: {score:.1%}
+                    </span>
+                </div>
+                <div style='display: flex; gap: 8px;'>
+                    {f"<span style='background: #3b82f6; color: white; padding: 3px 8px; border-radius: 4px; font-size: 11px;'>{adaptive}</span>" if adaptive else ""}
+                    {f"<span style='background: #8b5cf6; color: white; padding: 3px 8px; border-radius: 4px; font-size: 11px;'>{remote}</span>" if remote else ""}
+                </div>
+            </div>
+            
+            <h3 style='margin: 0 0 8px 0; color: #f8fafc; font-size: 18px;'>
+                <a href="{r['url']}" target="_blank" style='color: #60a5fa; text-decoration: none;'>
+                    {r['name']} ↗
+                </a>
+            </h3>
+            
+            <div style='color: #94a3b8; font-size: 13px; margin-bottom: 12px;'>
+                <strong style='color: #cbd5e1;'>Category:</strong> {r['category']} • 
+                <strong style='color: #cbd5e1;'>Duration:</strong> {duration}
+            </div>
+            
+            <div style='display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 10px;'>
+                {' '.join([f"<span style='background: #475569; color: #e2e8f0; padding: 3px 10px; border-radius: 15px; font-size: 11px;'>{level}</span>" for level in r['job_levels']])}
+            </div>
+            
+            <div style='color: #94a3b8; font-size: 12px;'>
+                <strong style='color: #cbd5e1;'>Focus Areas:</strong> {', '.join(r['focus_areas'][:4])}
+            </div>
+            
+            <div style='color: #64748b; font-size: 11px; margin-top: 8px;'>
+                Test Types: {', '.join(r['test_type'])}
+            </div>
+        </div>
+        """
+    
+    html += "</div>"
+    return html
 
 
-class RecommendationResponse(BaseModel):
-    query: str
-    recommendations: List[AssessmentResponse]
+def get_recommendations(query: str, num_results: int) -> str:
+    """Get recommendations and format as HTML"""
+    if not query or len(query.strip()) < 3:
+        return "<div style='text-align: center; padding: 40px; color: #fbbf24;'>⚠️ Please enter at least 3 characters to search.</div>"
+    
+    try:
+        results = engine.recommend(query.strip(), max_results=int(num_results))
+        return format_recommendations_html(results)
+    except Exception as e:
+        return f"<div style='text-align: center; padding: 40px; color: #ef4444;'>❌ Error: {str(e)}</div>"
 
 
 # ============================================================================
-# API ENDPOINTS
+# GRADIO INTERFACE - Professional Dark Theme
 # ============================================================================
 
-@app.get("/")
-def root():
-    """API information and health status"""
-    return {
-        "name": "SHL Assessment Recommendation API",
-        "version": "2.0.0",
-        "architecture": "2-Stage RAG: SBERT + Cross-Encoder Reranking",
-        "assessments": len(engine.assessments),
-        "status": "healthy",
-        "endpoints": {
-            "recommend": "/recommend?query=...",
-            "health": "/health",
-            "evaluate": "/evaluate",
-            "architecture": "/architecture",
-            "docs": "/docs"
-        }
+# Custom CSS for dark theme
+custom_css = """
+    .gradio-container {
+        max-width: 1200px !important;
+        margin: auto !important;
     }
-
-
-@app.get("/health")
-def health():
-    """Health check endpoint"""
-    return {
-        "status": "healthy",
-        "assessments": len(engine.assessments),
-        "models_loaded": True
+    .main-title {
+        text-align: center;
+        background: linear-gradient(90deg, #3b82f6, #8b5cf6);
+        -webkit-background-clip: text;
+        -webkit-text-fill-color: transparent;
+        font-size: 2.5rem !important;
+        font-weight: 700 !important;
+        margin-bottom: 0.5rem !important;
     }
+    .subtitle {
+        text-align: center;
+        color: #94a3b8 !important;
+        font-size: 1rem !important;
+        margin-bottom: 1.5rem !important;
+    }
+    footer {
+        display: none !important;
+    }
+"""
+
+# Example queries for users to try
+examples = [
+    ["I need to hire a software developer with Python programming skills"],
+    ["Looking for customer service representative assessments"],
+    ["Manager position requiring leadership and strategic thinking"],
+    ["Fresh graduate analyst trainee program"],
+    ["Sales account executive for B2B enterprise software"],
+    ["Healthcare nursing assistant for patient care"],
+    ["Banking teller handling cash transactions"],
+    ["Logical reasoning and problem solving test"],
+]
 
-
-@app.get("/recommend", response_model=RecommendationResponse)
-def recommend(
-    query: str = Query(..., min_length=3, description="Job description or query"),
-    max_results: int = Query(default=10, ge=1, le=10, description="Number of results")
-):
-    """Get assessment recommendations for a query using 2-Stage RAG pipeline"""
-    recommendations = engine.recommend(query, max_results)
-    return {"query": query, "recommendations": recommendations}
-
-
-@app.get("/architecture")
-def architecture():
-    """Get detailed architecture information"""
-    return engine.get_architecture_info()
-
-
-@app.get("/evaluate")
-def evaluate():
-    """Run evaluation suite with standard IR metrics"""
-    metrics = EvaluationMetrics()
+# Build the Gradio interface
+with gr.Blocks(
+    title="SHL Assessment Recommendation Engine",
+    theme=gr.themes.Soft(
+        primary_hue="blue",
+        secondary_hue="purple",
+        neutral_hue="slate",
+    ),
+    css=custom_css
+) as demo:
     
-    test_cases = [
-        {"query": "Python developer backend role", "relevant": ["Software Developer", "Coding", "IT Professional"]},
-        {"query": "customer service representative", "relevant": ["Customer Service", "Contact Center", "Front Desk"]},
-        {"query": "manager leadership position", "relevant": ["Manager", "Supervisor", "Virtual Assessment"]},
-        {"query": "graduate trainee program", "relevant": ["Graduate", "Apprentice", "Entry Level"]},
-        {"query": "sales account executive", "relevant": ["Sales Professional", "Account Manager", "Sales Representative"]},
-        {"query": "banking branch associate", "relevant": ["Teller", "Banker", "Financial"]},
-        {"query": "healthcare nursing assistant", "relevant": ["Healthcare", "Nursing", "Home Health"]},
-        {"query": "numerical reasoning cognitive test", "relevant": ["Verify Numerical", "Calculation", "Cognitive"]},
-        {"query": "personality work style assessment", "relevant": ["OPQ", "MQ", "Personality"]},
-        {"query": "problem solving logical thinking", "relevant": ["Verify G+", "Deductive", "Inductive"]},
-    ]
+    # Header
+    gr.HTML("""
+        <div style='text-align: center; padding: 20px 0;'>
+            <h1 class='main-title'>🎯 SHL Assessment Recommendation Engine</h1>
+            <p class='subtitle'>AI-powered recommendations using 2-Stage RAG: SBERT + Cross-Encoder Reranking</p>
+            <div style='display: flex; justify-content: center; gap: 20px; margin-top: 10px;'>
+                <span style='background: #1e40af; color: white; padding: 5px 12px; border-radius: 20px; font-size: 12px;'>
+                    📊 74 Assessments
+                </span>
+                <span style='background: #047857; color: white; padding: 5px 12px; border-radius: 20px; font-size: 12px;'>
+                    🎯 P@1: 90%
+                </span>
+                <span style='background: #7c3aed; color: white; padding: 5px 12px; border-radius: 20px; font-size: 12px;'>
+                    ⚡ MRR: 0.95
+                </span>
+            </div>
+        </div>
+    """)
     
-    all_p1, all_p3, all_p5, all_mrr, all_ndcg = [], [], [], [], []
-    results = []
+    # Main content
+    with gr.Row():
+        with gr.Column(scale=3):
+            query_input = gr.Textbox(
+                label="🔍 Job Description or Requirements",
+                placeholder="Enter a job description, role requirements, or skills needed...",
+                lines=3,
+                max_lines=5
+            )
+        with gr.Column(scale=1):
+            num_results = gr.Slider(
+                minimum=1,
+                maximum=10,
+                value=5,
+                step=1,
+                label="📋 Number of Results"
+            )
+            search_btn = gr.Button("🚀 Get Recommendations", variant="primary", size="lg")
     
-    for tc in test_cases:
-        recs = engine.recommend(tc["query"], 10)
-        names = [r["name"] for r in recs]
-        
-        p1 = metrics.precision_at_k(names, tc["relevant"], 1)
-        p3 = metrics.precision_at_k(names, tc["relevant"], 3)
-        p5 = metrics.precision_at_k(names, tc["relevant"], 5)
-        mrr = metrics.mean_reciprocal_rank(names, tc["relevant"])
-        ndcg = metrics.ndcg_at_k(names, tc["relevant"], 5)
-        
-        all_p1.append(p1)
-        all_p3.append(p3)
-        all_p5.append(p5)
-        all_mrr.append(mrr)
-        all_ndcg.append(ndcg)
-        
-        results.append({
-            "query": tc["query"],
-            "P@1": round(p1, 3),
-            "MRR": round(mrr, 3),
-            "NDCG@5": round(ndcg, 3),
-            "top_result": names[0] if names else None
-        })
+    # Examples
+    gr.Examples(
+        examples=examples,
+        inputs=query_input,
+        label="💡 Try these example queries:"
+    )
     
-    return {
-        "aggregate": {
-            "P@1": round(statistics.mean(all_p1), 3),
-            "P@3": round(statistics.mean(all_p3), 3),
-            "P@5": round(statistics.mean(all_p5), 3),
-            "MRR": round(statistics.mean(all_mrr), 3),
-            "NDCG@5": round(statistics.mean(all_ndcg), 3)
-        },
-        "per_query": results,
-        "test_cases": len(test_cases),
-        "assessments": len(engine.assessments)
-    }
+    # Results
+    results_html = gr.HTML(
+        value="<div style='text-align: center; padding: 60px; color: #64748b;'>Enter a job description above and click 'Get Recommendations' to see matching SHL assessments.</div>",
+        label="Recommendations"
+    )
+    
+    # Footer info
+    gr.HTML("""
+        <div style='text-align: center; padding: 20px; margin-top: 20px; border-top: 1px solid #334155;'>
+            <p style='color: #64748b; font-size: 12px; margin: 0;'>
+                Built with ❤️ using SBERT + Cross-Encoder Architecture | 
+                <a href='https://www.shl.com/products/product-catalog/' target='_blank' style='color: #60a5fa;'>SHL Product Catalog</a>
+            </p>
+        </div>
+    """)
+    
+    # Event handlers
+    search_btn.click(
+        fn=get_recommendations,
+        inputs=[query_input, num_results],
+        outputs=results_html
+    )
+    
+    query_input.submit(
+        fn=get_recommendations,
+        inputs=[query_input, num_results],
+        outputs=results_html
+    )
+
+
+# ============================================================================
+# LAUNCH APPLICATION
+# ============================================================================
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=7860)

requirements.txt

@@ -1,9 +1,5 @@
-# SHL Assessment Recommendation Engine - HuggingFace Spaces
-# Dependencies for 2-Stage RAG Pipeline
-
-sentence-transformers
-faiss-cpu
-fastapi
-uvicorn[standard]
-numpy
-pydantic
+gradio>=4.0.0
+sentence-transformers>=2.2.2
+faiss-cpu>=1.7.4
+numpy>=1.24.0
+torch>=2.0.0