topic classifier

src/summarization/topic_classifier.py

@@ -0,0 +1,249 @@
+"""
+Topic Classifier — maps dynamic LLM-extracted topics to predefined UI categories.
+
+Usage:
+    from src.summarization.topic_classifier import classify_topics
+
+    topics = ["Python", "Machine Learning", "Neural Networks"]
+    result = classify_topics(topics)
+    # => ["Technology & AI"]
+
+Categories:
+    Technology & AI | Business & Finance | Education & Science
+    Productivity & Self-Growth | News & Politics
+    Entertainment & Lifestyle | Health & Sports
+"""
+
+from typing import List, Set
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PREDEFINED CATEGORIES
+# ─────────────────────────────────────────────────────────────────────────────
+
+CATEGORIES = [
+    "Technology & AI",
+    "Business & Finance",
+    "Education & Science",
+    "Productivity & Self-Growth",
+    "News & Politics",
+    "Entertainment & Lifestyle",
+    "Health & Sports",
+]
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# KEYWORD → CATEGORY MAPPING  (English + Arabic)
+# All keywords are stored lowercase for case-insensitive matching.
+# ─────────────────────────────────────────────────────────────────────────────
+
+_KEYWORD_MAP: dict[str, str] = {}
+
+
+def _register(category: str, keywords: list[str]):
+    """Register a list of keywords for a category (lowercase)."""
+    for kw in keywords:
+        _KEYWORD_MAP[kw.lower()] = category
+
+
+# ── Technology & AI ──
+_register("Technology & AI", [
+    # English
+    "ai", "artificial intelligence", "machine learning", "deep learning",
+    "neural network", "neural networks", "nlp", "natural language processing",
+    "computer vision", "robotics", "automation", "algorithm", "algorithms",
+    "python", "javascript", "typescript", "java", "c++", "rust", "golang", "go",
+    "programming", "coding", "software", "software engineering", "web development",
+    "frontend", "backend", "full stack", "fullstack", "devops", "cloud",
+    "cloud computing", "aws", "azure", "gcp", "docker", "kubernetes",
+    "database", "sql", "nosql", "mongodb", "api", "rest api", "graphql",
+    "cybersecurity", "security", "hacking", "encryption", "blockchain",
+    "cryptocurrency", "bitcoin", "ethereum", "web3", "metaverse",
+    "data science", "data analysis", "data engineering", "big data",
+    "iot", "internet of things", "5g", "hardware", "semiconductor",
+    "gpu", "chip", "processor", "tech", "technology", "computing",
+    "linux", "git", "github", "open source", "framework", "react",
+    "vue", "angular", "node", "nodejs", "django", "flask", "fastapi",
+    "tensorflow", "pytorch", "llm", "large language model", "chatgpt",
+    "gpt", "gemini", "copilot", "transformer", "diffusion model",
+    "generative ai", "prompt engineering", "fine tuning", "rag",
+    "mobile development", "android", "ios", "swift", "kotlin", "flutter", "dart",
+    # Arabic
+    "ذكاء اصطناعي", "تعلم آلي", "تعلم عميق", "برمجة", "تقنية", "تكنولوجيا",
+    "خوارزمية", "حاسوب", "شبكات عصبية", "بيانات", "أمن سيبراني",
+    "حوسبة سحابية", "تطوير برمجيات", "تطوير ويب", "قواعد بيانات",
+])
+
+# ── Business & Finance ──
+_register("Business & Finance", [
+    # English
+    "business", "finance", "economics", "economy", "stock", "stocks",
+    "stock market", "trading", "investing", "investment", "real estate",
+    "entrepreneurship", "startup", "startups", "marketing", "digital marketing",
+    "seo", "branding", "sales", "revenue", "profit", "accounting",
+    "budgeting", "money", "wealth", "financial", "banking", "bank",
+    "fintech", "venture capital", "vc", "ipo", "merger", "acquisition",
+    "management", "leadership", "strategy", "e-commerce", "ecommerce",
+    "supply chain", "logistics", "consulting", "mba", "corporate",
+    "tax", "taxes", "inflation", "gdp", "interest rate", "forex",
+    "commodity", "commodities", "portfolio", "dividend", "bond", "bonds",
+    "freelancing", "freelance", "passive income", "side hustle",
+    # Arabic
+    "أعمال", "تجارة", "اقتصاد", "مالية", "استثمار", "أسهم", "بورصة",
+    "تسويق", "ريادة أعمال", "مشروع", "تمويل", "محاسبة", "بنك", "عقارات",
+    "ربح", "دخل", "ميزانية",
+])
+
+# ── Education & Science ──
+_register("Education & Science", [
+    # English
+    "education", "learning", "teaching", "school", "university", "college",
+    "academic", "research", "study", "studying", "exam", "exams", "course",
+    "tutorial", "lecture", "scholarship", "degree", "phd", "thesis",
+    "science", "physics", "chemistry", "biology", "math", "mathematics",
+    "statistics", "calculus", "algebra", "geometry", "astronomy", "space",
+    "nasa", "quantum", "quantum physics", "quantum computing",
+    "neuroscience", "genetics", "evolution", "ecology", "geology",
+    "climate", "climate change", "environment", "engineering",
+    "mechanical engineering", "electrical engineering", "civil engineering",
+    "experiment", "laboratory", "lab", "hypothesis", "theory",
+    "history", "philosophy", "psychology", "sociology", "linguistics",
+    "anthropology", "archaeology", "literature", "language", "grammar",
+    # Arabic
+    "تعليم", "تعلم", "مدرسة", "جامعة", "علوم", "فيزياء", "كيمياء",
+    "أحياء", "رياضيات", "بحث", "دراسة", "امتحان", "منهج", "محاضرة",
+    "هندسة", "تاريخ", "فلسفة", "علم نفس", "فلك", "بيئة",
+])
+
+# ── Productivity & Self-Growth ──
+_register("Productivity & Self-Growth", [
+    # English
+    "productivity", "self improvement", "self-improvement", "self growth",
+    "self-growth", "personal development", "motivation", "discipline",
+    "habits", "habit", "time management", "goal setting", "goals",
+    "mindset", "focus", "concentration", "efficiency", "organization",
+    "planning", "journaling", "morning routine", "routine", "success",
+    "self help", "self-help", "life coaching", "coaching", "mentoring",
+    "mentor", "stoicism", "minimalism", "mindfulness", "meditation",
+    "emotional intelligence", "communication skills", "public speaking",
+    "negotiation", "critical thinking", "problem solving", "creativity",
+    "decision making", "confidence", "resilience", "work-life balance",
+    "burnout", "career", "career development", "skill building",
+    # Arabic
+    "إنتاجية", "تطوير ذات", "تحفيز", "عادات", "إدارة الوقت",
+    "أهداف", "تركيز", "نجاح", "تخطيط", "تأمل", "ثقة بالنفس",
+    "مهارات", "تفكير", "إبداع",
+])
+
+# ── News & Politics ──
+_register("News & Politics", [
+    # English
+    "news", "politics", "political", "government", "policy", "election",
+    "elections", "democracy", "geopolitics", "diplomacy", "war", "conflict",
+    "military", "defense", "law", "legal", "legislation", "regulation",
+    "human rights", "immigration", "refugee", "sanctions", "united nations",
+    "nato", "eu", "european union", "congress", "parliament", "senate",
+    "president", "prime minister", "foreign policy", "domestic policy",
+    "protest", "activism", "corruption", "media", "journalism",
+    "press", "freedom of speech", "censorship", "propaganda",
+    "international relations", "treaty", "nuclear",
+    # Arabic
+    "أخبار", "سياسة", "حكومة", "انتخابات", "ديمقراطية", "حرب",
+    "قانون", "حقوق إنسان", "دبلوماسية", "برلمان", "رئيس",
+    "إعلام", "صحافة",
+])
+
+# ── Entertainment & Lifestyle ──
+_register("Entertainment & Lifestyle", [
+    # English
+    "entertainment", "movie", "movies", "film", "films", "cinema",
+    "tv", "television", "series", "netflix", "streaming", "anime",
+    "manga", "gaming", "video games", "esports", "twitch", "youtube",
+    "podcast", "music", "song", "album", "concert", "artist",
+    "celebrity", "fashion", "style", "beauty", "makeup", "skincare",
+    "travel", "tourism", "food", "cooking", "recipe", "restaurant",
+    "cuisine", "vlog", "vlogging", "photography", "art", "design",
+    "graphic design", "illustration", "architecture", "interior design",
+    "diy", "crafts", "comedy", "humor", "drama", "reality tv",
+    "social media", "tiktok", "instagram", "influencer", "content creator",
+    "lifestyle", "luxury", "culture", "pop culture",
+    # Arabic
+    "ترفيه", "أفلام", "سينما", "مسلسلات", "ألعاب", "موسيقى",
+    "سفر", "طبخ", "أزياء", "جمال", "تصوير", "فن", "تصميم",
+    "ثقافة", "كوميديا", "يوتيوب",
+])
+
+# ── Health & Sports ──
+_register("Health & Sports", [
+    # English
+    "health", "fitness", "exercise", "workout", "gym", "bodybuilding",
+    "weight loss", "diet", "nutrition", "calories", "protein", "vitamins",
+    "supplements", "wellness", "mental health", "therapy", "depression",
+    "anxiety", "stress", "sleep", "yoga", "pilates", "crossfit",
+    "running", "marathon", "swimming", "cycling", "hiking",
+    "sports", "football", "soccer", "basketball", "tennis", "baseball",
+    "cricket", "rugby", "boxing", "mma", "ufc", "wrestling",
+    "olympics", "world cup", "premier league", "nba", "nfl",
+    "medicine", "medical", "doctor", "hospital", "surgery", "disease",
+    "virus", "vaccine", "pandemic", "covid", "cancer", "diabetes",
+    "heart", "cardio", "physical therapy", "rehabilitation",
+    "first aid", "pharmacy", "drug", "prescription",
+    # Arabic
+    "صحة", "رياضة", "تمارين", "لياقة", "تغذية", "حمية",
+    "صحة نفسية", "علاج", "طب", "مستشفى", "كرة قدم", "سباحة",
+    "يوغا", "نوم", "فيتامينات",
+])
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# PUBLIC API
+# ─────────────────────────────────────────────────────────────────────────────
+
+def classify_topics(topics: List[str]) -> List[str]:
+    """
+    Map a list of dynamically extracted topics to predefined UI categories.
+
+    Args:
+        topics: List of topic strings from the LLM (e.g. ["Python", "Deep Learning"]).
+
+    Returns:
+        A deduplicated, ordered list of matching category names.
+        Falls back to ["Education & Science"] if no match is found.
+
+    Example:
+        >>> classify_topics(["Python", "Machine Learning", "Neural Networks"])
+        ["Technology & AI"]
+        >>> classify_topics(["Investing", "AI Stocks"])
+        ["Business & Finance", "Technology & AI"]
+    """
+    matched: Set[str] = set()
+
+    for topic in topics:
+        topic_lower = topic.lower().strip()
+
+        # 1. Exact match
+        if topic_lower in _KEYWORD_MAP:
+            matched.add(_KEYWORD_MAP[topic_lower])
+            continue
+
+        # 2. Substring match — check if any keyword appears inside the topic
+        for keyword, category in _KEYWORD_MAP.items():
+            if keyword in topic_lower or topic_lower in keyword:
+                matched.add(category)
+                break
+
+    if not matched:
+        matched.add("Education & Science")
+
+    # Return in the same order as CATEGORIES for consistency
+    return [cat for cat in CATEGORIES if cat in matched]
+
+
+def get_primary_category(topics: List[str]) -> str:
+    """
+    Return the single best-matching category for the given topics.
+
+    Useful when only one category tag is needed (e.g. a badge in the UI).
+    """
+    categories = classify_topics(topics)
+    return categories[0] if categories else "Education & Science"