utils/scoring.py

from typing import List, Dict, Any
import math

def rerank_mentors(
    similar_mentors: List[Dict[str, Any]],
    mentee_data: Dict[str, Any],
    final_count: int = 8
) -> List[Dict[str, Any]]:
    scored_mentors = []
    
    for mentor in similar_mentors:
        score = mentor["score"]
        metadata = mentor.get("metadata", {})
        
        semantic_score = score * 0.7
        
        rating_score = _calculate_rating_score(metadata.get("rating", 0.0))
        availability_score = _calculate_availability_score(metadata.get("available_slots", 0))
        
        rule_based_score = (
            rating_score * 0.5 +
            availability_score * 0.5
        ) * 0.3
        
        final_score = semantic_score + rule_based_score
        
        reason = _generate_reason(
            score,
            metadata,
            mentee_data,
            rating_score,
            availability_score
        )
        
        scored_mentors.append({
            "mentor_id": mentor["mentor_id"],
            "score": final_score,
            "semantic_similarity": score,
            "metadata": metadata,
            "reason": reason
        })
    
    scored_mentors.sort(key=lambda x: x["score"], reverse=True)
    
    return scored_mentors[:final_count]

def _calculate_rating_score(rating: float) -> float:
    if rating <= 0:
        return 0.0
    return min(rating / 5.0, 1.0)

def _calculate_availability_score(available_slots: int) -> float:
    if available_slots <= 0:
        return 0.0
    if available_slots >= 10:
        return 1.0
    return min(available_slots / 10.0, 1.0)


def _generate_reason(
    semantic_score: float,
    metadata: Dict[str, Any],
    mentee_data: Dict[str, Any],
    rating_score: float,
    availability_score: float
) -> str:
    reasons = []
    
    if semantic_score >= 0.8:
        reasons.append("Highly relevant expertise")
    elif semantic_score >= 0.6:
        reasons.append("Good match for your goals")
    
    rating = metadata.get("rating", 0.0)
    if rating >= 4.5:
        reasons.append("Excellent ratings")
    elif rating >= 4.0:
        reasons.append("High ratings")
    
    available_slots = metadata.get("available_slots", 0)
    if available_slots > 0:
        reasons.append("Has available slots")
    
    if not reasons:
        reasons.append("Good overall match")
    
    return "; ".join(reasons[:3])