Spaces:

Peterase
/

rag-api-node-1

Running

Peterase commited on 23 days ago

Commit

fa9ac33

1 Parent(s): 75375c8

feat(intent): complete rewrite of intent classifier v3

5-stage pipeline replacing fragile regex patches with systematic coverage:

Stage 1 - Exact match sets (0ms):
- _EXACT_OTHER: greetings, profanity, reactions, single chars
- _EXACT_NEWS_TEMPORAL: today, now, breaking, live, happening
- _EXACT_NEWS_GENERAL: ethiopia, amhara, tigray, news, conflict
- Handles all vague/single-word queries correctly

Stage 2 - Prefix/suffix rules (0ms):
- _TEMPORAL_PREFIXES: 'latest news', 'whats happening', 'news today'
- _HISTORICAL_PREFIXES: 'history of', 'background on', 'how did'
- _OTHER_PREFIXES: identity, math, creative, help queries
- Covers 'are you X', 'what model', 'write me', 'calculate'

Stage 3 - Regex pattern engine (0ms):
- _RE_TEMPORAL: 30+ temporal signals with word boundaries
- _RE_HISTORICAL: 20+ historical signals
- _RE_CONFLICT: 30+ conflict/security signals → NEWS_GENERAL/conflict
- _RE_HUMANITARIAN: 25+ humanitarian signals → NEWS_GENERAL/humanitarian
- _RE_OFF_TOPIC: recipes, movies, games, poems → OTHER

Stage 4 - Weighted keyword scoring (1ms):
- High weight (0.25): Ethiopia-specific terms, news signals
- Medium weight (0.12): General news vocabulary
- Low weight (0.05): Generic terms
- Score >= 0.40 → NEWS_GENERAL

Stage 5 - DeBERTa NLI (500ms, ambiguous only):
- Only fires when stages 1-4 produce no result
- Improved candidate labels for better accuracy
- Threshold raised to 0.35 (was 0.30)

New features:
- sub_type field: conflict|humanitarian|identity|math|creative|off_topic
- query_complexity: empty|vague|simple|medium|complex (was simple/medium/complex)
- Safe default: 2+ word unknown queries → NEWS_GENERAL (search and find nothing > refuse)
- Single unknown word → OTHER

Files changed (1) hide show

src/infrastructure/adapters/intent_classifier_v2.py +463 -424

src/infrastructure/adapters/intent_classifier_v2.py CHANGED Viewed

@@ -1,521 +1,560 @@
 """
-Production-Grade Intent Classifier v2
-Enhanced intent classification for hybrid RAG system with:
-- Multi-class classification (NEWS_TEMPORAL, NEWS_HISTORICAL, NEWS_GENERAL, OTHER)
-- Confidence scoring with thresholds
-- Query complexity analysis
-- Metrics tracking
-- Fallback strategies
-- Thread-safe lazy loading
-Classification Hierarchy:
-1. Instant shortcuts (regex patterns) - 0ms
-2. DeBERTa zero-shot NLI - ~20ms
-3. Keyword fallback - 0ms
-4. Default (NEWS_GENERAL) - safe fallback
 """
 import logging
 import re
 import threading
-from typing import Dict, Any, Optional, Tuple
-from dataclasses import dataclass
-from datetime import datetime
 import time
 logger = logging.getLogger(__name__)
-# ═══════════════════════════════════════════════════════════════════════════
-# PATTERN DEFINITIONS
-# ═══════════════════════════════════════════════════════════════════════════
-# Small talk patterns (instant OTHER classification)
-_SMALL_TALK_EXACT = {
-    "hi", "hello", "hey", "thanks", "thank you", "bye", "goodbye",
-    "good morning", "good afternoon", "good evening", "sup", "yo",
-    "hello there", "hey there", "hi there", "greetings", "howdy",
-    # Frustration / profanity
-    "wtf", "lol", "lmao", "omg", "damn", "shit", "fuck",
-    "for fuck sake", "for fucks sake", "oh my god", "are you kidding",
-    "seriously", "come on", "ugh", "argh", "ffs",
 }
-_SMALL_TALK_PREFIX = (
-    "how are you", "what are you", "who are you", "what can you do",
-    "tell me a joke", "make me laugh", "what's up", "whats up",
-    "for fuck", "for fucks", "what the fuck", "what the hell",
-    "are you serious", "you must be", "hello ", "hi ", "hey ",
-    "can you help", "i need help", "help me",
-    # Identity questions
-    "are you ", "what model", "which model", "what ai", "which ai",
-    "are you chatgpt", "are you gpt", "are you claude", "are you gemini",
-    "are you llama", "are you an ai", "are you a bot", "are you human",
-    "what version", "who built you", "who made you", "who created you",
-    "what are your capabilities", "what can you",
-    # Math / general knowledge (not news)
-    "what is ", "what's ", "calculate ", "solve ", "how much is ",
-    "how many ", "define ", "what does ", "translate ",
 )
-# Temporal patterns (instant NEWS_TEMPORAL classification)
-_TEMPORAL_PATTERNS = re.compile(
     r"\b("
-    r"today|yesterday|tomorrow|tonight|now|currently|"
-    r"this (week|month|year|morning|evening|afternoon)|"
-    r"last (week|month|year|night|hour|"
     r"monday|tuesday|wednesday|thursday|friday|saturday|sunday)|"
-    r"next (week|month|year)|"
-    r"past (\d+ )?(hour|hours|day|days|week|weeks|month|months)|"
-    r"recent(ly)?|latest|breaking|just (now|happened|announced|reported)|"
-    r"(monday|tuesday|wednesday|thursday|friday|saturday|sunday)|"
-    r"january|february|march|april|may|june|july|august|september|october|november|december|"
-    r"\d{4}|"                    # year like 2024, 2025
-    r"\d+(st|nd|rd|th)|"         # ordinal like 1st, 2nd
-    r"current|ongoing|live|real[- ]?time"
     r")\b",
     re.IGNORECASE
 )
-# Historical patterns (instant NEWS_HISTORICAL classification)
-_HISTORICAL_PATTERNS = re.compile(
     r"\b("
-    r"history|historical|background|context|origin|"
-    r"how (did|was|were)|why (did|was|were)|"
-    r"what (led to|caused|resulted in)|"
-    r"timeline|chronology|evolution|development|"
-    r"past|previous|former|old|ancient|"
     r"analysis|overview|summary|explanation|"
-    r"tell me about|explain|describe"
     r")\b",
     re.IGNORECASE
 )
-# News signal keywords (fallback NEWS classification)
-_NEWS_KEYWORDS = {
     "news", "report", "update", "development", "announcement",
     "conflict", "war", "peace", "crisis", "deal", "agreement",
-    "election", "vote", "campaign", "president", "minister", "government",
-    "economy", "market", "price", "inflation", "trade",
     "protest", "demonstration", "strike", "rally",
-    "attack", "violence", "security", "military",
-    "ethiopia", "addis", "abiy", "fano", "tigray", "amhara", "oromia",
-    "africa", "african", "horn of africa",
 }
-# ═══════════════════════════════════════════════════════════════════════════
-# DATA CLASSES
-# ═══════════════════════════════════════════════════════════════════════════
 @dataclass
 class IntentResult:
-    """
-    Intent classification result with confidence and metadata.
-    """
-    intent: str                    # NEWS_TEMPORAL, NEWS_HISTORICAL, NEWS_GENERAL, OTHER
-    confidence: float              # 0.0 to 1.0
-    method: str                    # "regex", "deberta", "keyword", "default"
-    inference_time_ms: float       # Time taken for classification
-    query_complexity: str          # "simple", "medium", "complex"
-    should_use_live: bool          # Recommendation for live search
-    should_use_db: bool            # Recommendation for DB search
-    metadata: Dict[str, Any]       # Additional info
     def to_dict(self) -> Dict[str, Any]:
-        """Convert to dictionary for logging/caching"""
         return {
             "intent": self.intent,
             "confidence": self.confidence,
             "method": self.method,
             "inference_time_ms": self.inference_time_ms,
             "query_complexity": self.query_complexity,
             "should_use_live": self.should_use_live,
             "should_use_db": self.should_use_db,
-            "metadata": self.metadata
         }
-# ═══════════════════════════════════════════════════════════════════════════
-# PRODUCTION-GRADE INTENT CLASSIFIER
-# ═══════════════════════════════════════════════════════════════════════════
 class IntentClassifierV2:
     """
-    Production-grade intent classifier with multi-class classification.
-    Intent Classes:
-    - NEWS_TEMPORAL: Time-sensitive news queries (use live search)
-    - NEWS_HISTORICAL: Historical/background queries (use DB only)
-    - NEWS_GENERAL: General news queries (use hybrid)
-    - OTHER: Non-news queries (skip search)
-    Features:
-    - Multi-stage classification (regex → DeBERTa → keyword → default)
-    - Confidence scoring with thresholds
-    - Query complexity analysis
-    - Metrics tracking
-    - Thread-safe lazy loading
     """
     MODEL_NAME = "MoritzLaurer/deberta-v3-base-zeroshot-v2.0"
-    # Confidence thresholds
-    HIGH_CONFIDENCE = 0.75
-    MEDIUM_CONFIDENCE = 0.50
-    LOW_CONFIDENCE = 0.30
     def __init__(self):
         self._pipe = None
         self._lock = threading.Lock()
         self._load_failed = False
-        # Metrics tracking
         self._metrics = {
-            "total_classifications": 0,
-            "by_intent": {"NEWS_TEMPORAL": 0, "NEWS_HISTORICAL": 0, "NEWS_GENERAL": 0, "OTHER": 0},
-            "by_method": {"regex": 0, "deberta": 0, "keyword": 0, "default": 0},
-            "avg_inference_time_ms": 0.0,
-            "total_inference_time_ms": 0.0,
         }
-    def _load(self):
-        """Lazy load DeBERTa model (thread-safe)"""
-        if self._pipe is not None or self._load_failed:
-            return
-        with self._lock:
-            if self._pipe is not None or self._load_failed:
-                return
-            try:
-                from transformers import pipeline
-                logger.info(f"Loading intent classifier: {self.MODEL_NAME} ...")
-                self._pipe = pipeline(
-                    "zero-shot-classification",
-                    model=self.MODEL_NAME,
-                    device=-1,  # CPU (use device=0 for GPU)
-                    multi_label=False,
-                )
-                logger.info("✅ Intent classifier v2 loaded successfully")
-            except Exception as e:
-                logger.error(f"❌ Failed to load intent classifier: {e}")
-                self._load_failed = True
-    def classify(self, query: str, use_cache: bool = True) -> IntentResult:
-        """
-        Classify query intent with confidence scoring.
-        Args:
-            query: User query string
-            use_cache: Whether to use cached results (if available)
-        Returns:
-            IntentResult with classification and metadata
-        """
-        start_time = time.time()
-        # Normalize query
-        query_normalized = query.strip()
-        query_lower = query_normalized.lower()
-        # Analyze query complexity
-        complexity = self._analyze_complexity(query_normalized)
-        # ── Stage 1: Instant Regex Shortcuts ──────────────────────────────────
-        # Check small talk (OTHER)
-        if query_lower in _SMALL_TALK_EXACT:
-            return self._create_result(
-                intent="OTHER",
-                confidence=1.0,
-                method="regex_exact",
-                start_time=start_time,
-                complexity=complexity,
-                metadata={"pattern": "small_talk_exact"}
             )
-        if any(query_lower.startswith(p) for p in _SMALL_TALK_PREFIX):
-            return self._create_result(
-                intent="OTHER",
-                confidence=0.95,
-                method="regex_prefix",
-                start_time=start_time,
-                complexity=complexity,
-                metadata={"pattern": "small_talk_prefix"}
             )
-        # Check temporal patterns (NEWS_TEMPORAL)
-        temporal_match = _TEMPORAL_PATTERNS.search(query_normalized)
-        if temporal_match:
-            return self._create_result(
-                intent="NEWS_TEMPORAL",
-                confidence=0.90,
-                method="regex_temporal",
-                start_time=start_time,
-                complexity=complexity,
-                metadata={"pattern": "temporal", "matched": temporal_match.group(0)}
             )
-        # Check historical patterns (NEWS_HISTORICAL)
-        historical_match = _HISTORICAL_PATTERNS.search(query_normalized)
-        if historical_match:
-            return self._create_result(
-                intent="NEWS_HISTORICAL",
-                confidence=0.85,
-                method="regex_historical",
-                start_time=start_time,
-                complexity=complexity,
-                metadata={"pattern": "historical", "matched": historical_match.group(0)}
             )
-        # ── Stage 2: DeBERTa Zero-Shot Classification ─────────────────────────
-        self._load()
         if self._pipe is not None:
             try:
-                result = self._classify_with_deberta(query_normalized)
                 if result:
-                    return self._create_result(
-                        intent=result["intent"],
-                        confidence=result["confidence"],
-                        method="deberta",
-                        start_time=start_time,
-                        complexity=complexity,
-                        metadata=result["metadata"]
                     )
             except Exception as e:
-                logger.warning(f"DeBERTa classification failed: {e}")
-        # ── Stage 3: Keyword Fallback ─────────────────────────────────────────
-        keyword_result = self._classify_with_keywords(query_lower)
-        if keyword_result:
-            return self._create_result(
-                intent=keyword_result["intent"],
-                confidence=keyword_result["confidence"],
-                method="keyword",
-                start_time=start_time,
-                complexity=complexity,
-                metadata=keyword_result["metadata"]
-            )
-        # ── Stage 4: Default (Safe Fallback) ──────────────────────────────────
-        return self._create_result(
-            intent="NEWS_GENERAL",
-            confidence=0.50,
-            method="default",
-            start_time=start_time,
-            complexity=complexity,
-            metadata={"reason": "no_pattern_match"}
-        )
-    def _classify_with_deberta(self, query: str) -> Optional[Dict[str, Any]]:
-        """
-        Classify using DeBERTa zero-shot model.
-        Returns dict with intent, confidence, metadata or None if failed.
-        """
-        try:
-            # Multi-class classification
-            result = self._pipe(
-                query,
-                candidate_labels=[
-                    "breaking news, current events, today's news, latest updates, real-time news",
-                    "historical background, past events, context, analysis, explanation",
-                    "general news, politics, economy, world affairs, sports, technology",
-                    "small talk, greeting, joke, general question unrelated to news",
-                ],
-                hypothesis_template="This message is about {}.",
-            )
-            top_label = result["labels"][0]
-            top_score = result["scores"][0]
-            # Map label to intent
-            if "breaking" in top_label or "current" in top_label or "latest" in top_label:
-                intent = "NEWS_TEMPORAL"
-            elif "historical" in top_label or "background" in top_label or "context" in top_label:
-                intent = "NEWS_HISTORICAL"
-            elif "general news" in top_label or "politics" in top_label:
-                intent = "NEWS_GENERAL"
-            elif "small talk" in top_label or "greeting" in top_label:
-                intent = "OTHER"
-            else:
-                intent = "NEWS_GENERAL"  # Default to general news
-            # Only return if confidence is above threshold
-            if top_score >= self.LOW_CONFIDENCE:
-                return {
-                    "intent": intent,
-                    "confidence": float(top_score),
-                    "metadata": {
-                        "top_label": top_label,
-                        "all_scores": {
-                            label: float(score)
-                            for label, score in zip(result["labels"], result["scores"])
-                        }
-                    }
-                }
-            return None
-        except Exception as e:
-            logger.error(f"DeBERTa inference error: {e}")
-            return None
-    def _classify_with_keywords(self, query_lower: str) -> Optional[Dict[str, Any]]:
-        """
-        Classify using keyword matching (fallback).
-        Returns dict with intent, confidence, metadata or None if no match.
-        """
-        # Count news keyword matches
-        matches = [kw for kw in _NEWS_KEYWORDS if kw in query_lower]
-        if matches:
-            # More matches = higher confidence
-            confidence = min(0.70, 0.50 + (len(matches) * 0.05))
-            return {
-                "intent": "NEWS_GENERAL",
-                "confidence": confidence,
-                "metadata": {
-                    "matched_keywords": matches[:5],  # Top 5
-                    "match_count": len(matches)
-                }
-            }
-        return None
-    def _analyze_complexity(self, query: str) -> str:
-        """
-        Analyze query complexity based on length and structure.
-        Returns: "simple", "medium", or "complex"
-        """
-        word_count = len(query.split())
-        char_count = len(query)
-        # Check for question words
-        question_words = ["what", "when", "where", "who", "why", "how"]
-        has_question = any(qw in query.lower() for qw in question_words)
-        if word_count <= 3 and not has_question:
             return "simple"
-        elif word_count <= 10:
             return "medium"
-        else:
-            return "complex"
-    def _create_result(
         self,
         intent: str,
         confidence: float,
         method: str,
-        start_time: float,
         complexity: str,
-        metadata: Dict[str, Any]
     ) -> IntentResult:
-        """
-        Create IntentResult with recommendations and metrics.
-        """
-        inference_time_ms = (time.time() - start_time) * 1000
-        # Determine search recommendations
-        should_use_live = intent == "NEWS_TEMPORAL"
-        should_use_db = intent in ["NEWS_TEMPORAL", "NEWS_HISTORICAL", "NEWS_GENERAL"]
-        # Update metrics
-        self._update_metrics(intent, method, inference_time_ms)
-        result = IntentResult(
             intent=intent,
             confidence=confidence,
             method=method,
-            inference_time_ms=inference_time_ms,
             query_complexity=complexity,
-            should_use_live=should_use_live,
-            should_use_db=should_use_db,
-            metadata=metadata
         )
-        # Log classification
-        logger.debug(
-            f"Intent: {intent} (conf={confidence:.2f}, method={method}, "
-            f"time={inference_time_ms:.1f}ms, complexity={complexity})"
-        )
-        return result
-    def _update_metrics(self, intent: str, method: str, inference_time_ms: float):
-        """Update classification metrics"""
-        self._metrics["total_classifications"] += 1
-        self._metrics["by_intent"][intent] = self._metrics["by_intent"].get(intent, 0) + 1
-        self._metrics["by_method"][method] = self._metrics["by_method"].get(method, 0) + 1
-        self._metrics["total_inference_time_ms"] += inference_time_ms
-        self._metrics["avg_inference_time_ms"] = (
-            self._metrics["total_inference_time_ms"] / self._metrics["total_classifications"]
         )
     def get_metrics(self) -> Dict[str, Any]:
-        """Get classification metrics for monitoring"""
-        return dict(self._metrics)
-    def reset_metrics(self):
-        """Reset metrics (useful for testing)"""
-        self._metrics = {
-            "total_classifications": 0,
-            "by_intent": {"NEWS_TEMPORAL": 0, "NEWS_HISTORICAL": 0, "NEWS_GENERAL": 0, "OTHER": 0},
-            "by_method": {"regex": 0, "deberta": 0, "keyword": 0, "default": 0},
-            "avg_inference_time_ms": 0.0,
-            "total_inference_time_ms": 0.0,
         }
-# ═══════════════════════════════════════════════════════════════════════════
-# MODULE-LEVEL SINGLETON
-# ═══════════════════════════════════════════════════════════════════════════
-# Global singleton instance
 intent_classifier_v2 = IntentClassifierV2()
-# ═══════════════════════════════════════════════════════════════════════════
-# BACKWARD COMPATIBILITY WRAPPER
-# ═══════════════════════════════════════════════════════════════════════════
 class IntentClassifier:
-    """
-    Backward-compatible wrapper for existing code.
-    Maps v2 multi-class intents to v1 binary (NEWS/OTHER).
-    """
     def __init__(self):
-        self._classifier_v2 = intent_classifier_v2
     def classify(self, query: str) -> str:
-        """
-        Classify query intent (backward compatible).
-        Returns: "NEWS" or "OTHER"
-        """
-        result = self._classifier_v2.classify(query)
-        # Map v2 intents to v1 binary
-        if result.intent == "OTHER":
-            return "OTHER"
-        else:
-            return "NEWS"  # All NEWS_* intents map to NEWS
-# Backward-compatible singleton
 intent_classifier = IntentClassifier()

 """
+Intent Classifier v3 — Sharp, Fast, Comprehensive
+5-stage classification pipeline:
+  Stage 1: Exact match set          (0ms)   — greetings, profanity, single chars
+  Stage 2: Prefix/suffix rules      (0ms)   — identity, math, commands
+  Stage 3: Regex pattern engine     (0ms)   — temporal, historical, conflict, humanitarian
+  Stage 4: Weighted keyword scoring (1ms)   — domain-specific vocabulary
+  Stage 5: DeBERTa NLI fallback     (500ms) — ambiguous edge cases only
+Handles:
+  - Vague / single-word queries     ("news", "ethiopia", "amhara")
+  - Short queries                   ("latest", "update", "today")
+  - Identity questions              ("who are you", "are you gpt")
+  - Math / general knowledge        ("2+2", "capital of france")
+  - Conflict queries                ("clashes", "attack", "fano")
+  - Humanitarian queries            ("displaced", "aid", "refugees")
+  - Historical queries              ("history of", "background on")
+  - Temporal queries                ("today", "breaking", "just now")
+  - General news                    ("ethiopia news", "abiy ahmed")
+  - Off-topic                       ("write a poem", "recipe for pasta")
 """
 import logging
 import re
 import threading
 import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
 logger = logging.getLogger(__name__)
+# ═══════════════════════════════════════════════════════════════════════════════
+# STAGE 1: EXACT MATCH SET  (0ms)
+# ═══════════════════════════════════════════════════════════════════════════════
+_EXACT_OTHER = {
+    # Greetings
+    "hi", "hello", "hey", "yo", "sup", "howdy", "greetings",
+    "good morning", "good afternoon", "good evening", "good night",
+    "hello there", "hey there", "hi there",
+    # Farewells
+    "bye", "goodbye", "see you", "later", "cya", "ttyl",
+    # Thanks
+    "thanks", "thank you", "thx", "ty", "cheers",
+    # Reactions
+    "ok", "okay", "sure", "cool", "nice", "great", "awesome",
+    "lol", "lmao", "haha", "hehe", "omg", "wtf", "wow",
+    "ugh", "argh", "hmm", "oh", "ah", "aha",
+    # Single characters / gibberish triggers
+    ".", "..", "...", "?", "??", "!", "!!", "test", "testing",
+    # Profanity (route to OTHER, not news)
+    "damn", "shit", "fuck", "crap", "hell",
+}
+# Vague single-word queries that ARE news-related → NEWS_GENERAL
+_EXACT_NEWS_GENERAL = {
+    "news", "update", "updates", "latest", "headlines", "stories",
+    "ethiopia", "africa", "amhara", "tigray", "oromia", "somalia",
+    "addis", "abiy", "fano", "tplf", "olf", "ene",
+    "conflict", "war", "peace", "crisis", "politics",
+    "economy", "election", "government",
+}
+# Vague single-word queries that are temporal → NEWS_TEMPORAL
+_EXACT_NEWS_TEMPORAL = {
+    "today", "now", "tonight", "breaking", "live", "current",
+    "happening", "recent", "fresh",
 }
+# ═══════════════════════════════════════════════════════════════════════════════
+# STAGE 2: PREFIX / SUFFIX RULES  (0ms)
+# ═══════════════════════════════════════════════════════════════════════════════
+# These prefixes → OTHER (identity, math, off-topic commands)
+_OTHER_PREFIXES = (
+    # Identity
+    "who are you", "what are you", "are you ", "what model",
+    "which model", "what ai", "which ai", "what version",
+    "who built you", "who made you", "who created you",
+    "tell me about yourself", "introduce yourself",
+    # Math / calculations
+    "what is ", "what's ", "whats ", "calculate ", "compute ",
+    "solve ", "how much is ", "convert ", "define ",
+    "what does ", "translate ", "spell ", "how do you spell",
+    # Commands / creative
+    "write ", "generate ", "create ", "make me ", "give me a ",
+    "tell me a joke", "tell me a story", "write a poem",
+    "write me ", "compose ", "draft ",
+    # Help / capability
+    "can you help", "help me with", "how do i", "how to ",
+    "what can you do", "what are your capabilities",
+    # Greetings with space (catches "hello world" etc.)
+    "hello ", "hi ", "hey ",
+)
+# These prefixes → NEWS_TEMPORAL
+_TEMPORAL_PREFIXES = (
+    "what happened today", "what's happening", "whats happening",
+    "what is happening", "latest news", "breaking news",
+    "today's news", "todays news", "news today",
+    "what's new", "whats new", "any news",
+    "tell me the latest", "give me the latest",
+    "what's going on", "whats going on",
 )
+# These prefixes → NEWS_HISTORICAL
+_HISTORICAL_PREFIXES = (
+    "history of ", "historical ", "background on ", "background of ",
+    "origin of ", "origins of ", "context of ", "context on ",
+    "tell me about the history", "what is the history",
+    "how did ", "why did ", "what caused ", "what led to ",
+    "timeline of ", "chronology of ",
+)
+# ═══════════════════════════════════════════════════════════════════════════════
+# STAGE 3: REGEX PATTERN ENGINE  (0ms)
+# ═══════════════════════════════════════════════════════════════════════════════
+# Temporal signals
+_RE_TEMPORAL = re.compile(
     r"\b("
+    r"today|tonight|yesterday|tomorrow|"
+    r"this\s+(morning|afternoon|evening|week|month|year)|"
+    r"last\s+(night|hour|week|month|year|"
     r"monday|tuesday|wednesday|thursday|friday|saturday|sunday)|"
+    r"past\s+\d+\s*(hour|hours|day|days|week|weeks|month|months)|"
+    r"just\s+(now|happened|announced|reported|released)|"
+    r"breaking|latest|recent(ly)?|current(ly)?|ongoing|live|"
+    r"right\s+now|as\s+of\s+(now|today)|"
+    r"this\s+just\s+in|developing\s+story|"
+    r"hours?\s+ago|minutes?\s+ago|days?\s+ago|"
+    r"monday|tuesday|wednesday|thursday|friday|saturday|sunday|"
+    r"january|february|march|april|june|july|august|"
+    r"september|october|november|december|"
+    r"2024|2025|2026|"
+    r"real[\s-]?time|up[\s-]?to[\s-]?date"
     r")\b",
     re.IGNORECASE
 )
+# Historical signals
+_RE_HISTORICAL = re.compile(
     r"\b("
+    r"history|historical|background|context|origin(s)?|"
+    r"how\s+did|why\s+did|what\s+caused|what\s+led\s+to|"
+    r"timeline|chronology|evolution|development\s+of|"
+    r"past|previous|former|ancient|traditional|"
     r"analysis|overview|summary|explanation|"
+    r"tell\s+me\s+about|explain|describe|"
+    r"since\s+(19|20)\d{2}|from\s+(19|20)\d{2}|"
+    r"decade|century|era|period"
     r")\b",
     re.IGNORECASE
 )
+# Conflict / security signals → NEWS_GENERAL (with conflict sub-type)
+_RE_CONFLICT = re.compile(
+    r"\b("
+    r"clash(es)?|attack(ed|s)?|battle|fighting|armed|militia|"
+    r"killed|fatalities|casualties|wounded|dead|deaths|"
+    r"protest(s|ers)?|demonstration|rally|riot(s)?|"
+    r"military|troops|soldiers|forces|army|"
+    r"bomb(ing)?|explosion|airstrike|drone|"
+    r"fano|tplf|olf|ene|al[\s-]?shabaab|"
+    r"ceasefire|peace\s+deal|negotiation|"
+    r"coup|overthrow|uprising|insurgency|rebel"
+    r")\b",
+    re.IGNORECASE
+)
+# Humanitarian signals → NEWS_GENERAL (with humanitarian sub-type)
+_RE_HUMANITARIAN = re.compile(
+    r"\b("
+    r"displaced|displacement|idp|refugee(s)?|"
+    r"humanitarian|aid|relief|assistance|"
+    r"food\s+(security|insecurity|crisis)|famine|hunger|starvation|"
+    r"drought|flood(ing)?|disaster|emergency|"
+    r"unocha|unhcr|wfp|unicef|ngo|"
+    r"shelter|camp(s)?|evacuation|"
+    r"cholera|disease|outbreak|epidemic|"
+    r"poverty|malnutrition|sanitation"
+    r")\b",
+    re.IGNORECASE
+)
+# Off-topic signals → OTHER
+_RE_OFF_TOPIC = re.compile(
+    r"\b("
+    r"recipe|cook(ing)?|food\s+recipe|how\s+to\s+cook|"
+    r"movie|film|song|music|lyrics|"
+    r"game|gaming|play\s+game|"
+    r"joke|funny|humor|meme|"
+    r"poem|poetry|story|fiction|novel|"
+    r"math|algebra|calculus|equation|formula|"
+    r"weather\s+forecast|temperature\s+in|"
+    r"stock\s+price|crypto|bitcoin|"
+    r"sports\s+score|match\s+result|"
+    r"translate\s+to|how\s+do\s+you\s+say"
+    r")\b",
+    re.IGNORECASE
+)
+# ═══════════════════════════════════════════════════════════════════════════════
+# STAGE 4: WEIGHTED KEYWORD SCORING  (1ms)
+# ═══════════════════════════════════════════════════════════════════════════════
+# High-weight Ethiopia/Africa news keywords
+_KW_NEWS_HIGH = {
+    # Ethiopia-specific
+    "ethiopia", "ethiopian", "addis ababa", "addis", "abiy", "abiy ahmed",
+    "tigray", "amhara", "oromia", "oromo", "afar", "somali region",
+    "fano", "tplf", "olf", "ene", "gerd", "nile", "blue nile",
+    "mekelle", "gondar", "bahir dar", "dire dawa", "hawassa",
+    # Horn of Africa
+    "somalia", "somali", "kenya", "sudan", "south sudan", "eritrea",
+    "djibouti", "horn of africa",
+    # News signals
     "news", "report", "update", "development", "announcement",
+    "statement", "press release", "official",
+}
+# Medium-weight general news keywords
+_KW_NEWS_MED = {
     "conflict", "war", "peace", "crisis", "deal", "agreement",
+    "election", "vote", "campaign", "president", "prime minister",
+    "minister", "government", "parliament", "policy",
+    "economy", "market", "inflation", "trade", "investment",
     "protest", "demonstration", "strike", "rally",
+    "attack", "violence", "security", "military", "forces",
+    "humanitarian", "aid", "displaced", "refugee",
+    "africa", "african", "un", "united nations", "au", "african union",
+}
+# Low-weight general keywords (only count if no high/med match)
+_KW_NEWS_LOW = {
+    "situation", "issue", "problem", "challenge", "concern",
+    "region", "area", "zone", "district", "province",
+    "people", "community", "population", "civilian",
+    "international", "global", "world",
 }
+# ═══════════════════════════════════════════════════════════════════════════════
+# DATA CLASS
+# ═══════════════════════════════════════════════════════════════════════════════
 @dataclass
 class IntentResult:
+    intent: str            # NEWS_TEMPORAL | NEWS_HISTORICAL | NEWS_GENERAL | OTHER
+    confidence: float      # 0.0 – 1.0
+    method: str            # stage that produced the result
+    inference_time_ms: float
+    query_complexity: str  # vague | simple | medium | complex
+    sub_type: str          # conflict | humanitarian | general | identity | math | off_topic | ""
+    should_use_live: bool
+    should_use_db: bool
+    metadata: Dict[str, Any]
     def to_dict(self) -> Dict[str, Any]:
         return {
             "intent": self.intent,
             "confidence": self.confidence,
             "method": self.method,
             "inference_time_ms": self.inference_time_ms,
             "query_complexity": self.query_complexity,
+            "sub_type": self.sub_type,
             "should_use_live": self.should_use_live,
             "should_use_db": self.should_use_db,
+            "metadata": self.metadata,
         }
+# ═══════════════════════════════════════════════════════════════════════════════
+# CLASSIFIER
+# ═══════════════════════════════════════════════════════════════════════════════
 class IntentClassifierV2:
     """
+    Sharp, fast, comprehensive intent classifier.
+    5-stage pipeline — most queries resolved in Stage 1-4 (<2ms).
+    DeBERTa (Stage 5) only fires for genuinely ambiguous queries.
     """
     MODEL_NAME = "MoritzLaurer/deberta-v3-base-zeroshot-v2.0"
     def __init__(self):
         self._pipe = None
         self._lock = threading.Lock()
         self._load_failed = False
         self._metrics = {
+            "total": 0,
+            "by_intent": {},
+            "by_method": {},
+            "total_ms": 0.0,
         }
+    # ── Public API ────────────────────────────────────────────────────────────
+    def classify(self, query: str) -> IntentResult:
+        t0 = time.time()
+        q = query.strip()
+        ql = q.lower()
+        complexity = self._complexity(q)
+        # ── Stage 1: Exact match ──────────────────────────────────────────────
+        if ql in _EXACT_OTHER:
+            return self._result("OTHER", 1.0, "exact", t0, complexity, "identity")
+        if ql in _EXACT_NEWS_TEMPORAL:
+            return self._result("NEWS_TEMPORAL", 1.0, "exact", t0, complexity, "general")
+        if ql in _EXACT_NEWS_GENERAL:
+            return self._result("NEWS_GENERAL", 1.0, "exact", t0, complexity, "general")
+        # ── Stage 2: Prefix / suffix rules ───────────────────────────────────
+        for p in _TEMPORAL_PREFIXES:
+            if ql.startswith(p) or ql == p.strip():
+                return self._result("NEWS_TEMPORAL", 0.97, "prefix", t0, complexity, "general")
+        for p in _HISTORICAL_PREFIXES:
+            if ql.startswith(p):
+                return self._result("NEWS_HISTORICAL", 0.95, "prefix", t0, complexity, "general")
+        for p in _OTHER_PREFIXES:
+            if ql.startswith(p):
+                sub = self._other_subtype(ql)
+                return self._result("OTHER", 0.95, "prefix", t0, complexity, sub)
+        # ── Stage 3: Regex pattern engine ────────────────────────────────────
+        # Off-topic check first (before temporal/historical to avoid false positives)
+        if _RE_OFF_TOPIC.search(q):
+            return self._result("OTHER", 0.90, "regex_offtopic", t0, complexity, "off_topic")
+        # Temporal
+        tm = _RE_TEMPORAL.search(q)
+        if tm:
+            return self._result(
+                "NEWS_TEMPORAL", 0.90, "regex_temporal", t0, complexity, "general",
+                {"matched": tm.group(0)}
             )
+        # Historical
+        hm = _RE_HISTORICAL.search(q)
+        if hm:
+            return self._result(
+                "NEWS_HISTORICAL", 0.88, "regex_historical", t0, complexity, "general",
+                {"matched": hm.group(0)}
             )
+        # Conflict → NEWS_GENERAL with conflict sub-type
+        cm = _RE_CONFLICT.search(q)
+        if cm:
+            return self._result(
+                "NEWS_GENERAL", 0.88, "regex_conflict", t0, complexity, "conflict",
+                {"matched": cm.group(0)}
             )
+        # Humanitarian → NEWS_GENERAL with humanitarian sub-type
+        hum = _RE_HUMANITARIAN.search(q)
+        if hum:
+            return self._result(
+                "NEWS_GENERAL", 0.85, "regex_humanitarian", t0, complexity, "humanitarian",
+                {"matched": hum.group(0)}
             )
+        # ── Stage 4: Weighted keyword scoring ────────────────────────────────
+        score = self._keyword_score(ql)
+        if score >= 0.60:
+            return self._result("NEWS_GENERAL", score, "keyword", t0, complexity, "general")
+        if score >= 0.40:
+            # Weak news signal — still route to news but lower confidence
+            return self._result("NEWS_GENERAL", score, "keyword", t0, complexity, "general")
+        # ── Stage 5: DeBERTa NLI (ambiguous queries only) ────────────────────
+        self._load_deberta()
         if self._pipe is not None:
             try:
+                result = self._deberta_classify(q)
                 if result:
+                    return self._result(
+                        result["intent"], result["confidence"],
+                        "deberta", t0, complexity, "general",
+                        result["metadata"]
                     )
             except Exception as e:
+                logger.warning(f"DeBERTa failed: {e}")
+        # ── Stage 6: Safe default ─────────────────────────────────────────────
+        # If query has any content and we got here, treat as general news
+        # (better to search and find nothing than to refuse)
+        if len(ql.split()) >= 2:
+            return self._result("NEWS_GENERAL", 0.50, "default", t0, complexity, "general")
+        # Single unknown word → OTHER
+        return self._result("OTHER", 0.60, "default", t0, complexity, "unknown")
+    # ── Internal helpers ──────────────────────────────────────────────────────
+    def _keyword_score(self, ql: str) -> float:
+        """Weighted keyword scoring. Returns 0.0–1.0."""
+        score = 0.0
+        for kw in _KW_NEWS_HIGH:
+            if kw in ql:
+                score += 0.25
+        for kw in _KW_NEWS_MED:
+            if kw in ql:
+                score += 0.12
+        for kw in _KW_NEWS_LOW:
+            if kw in ql:
+                score += 0.05
+        return min(score, 1.0)
+    def _other_subtype(self, ql: str) -> str:
+        """Determine sub-type for OTHER queries."""
+        if any(p in ql for p in ("who are you", "what are you", "are you ", "what model", "what ai")):
+            return "identity"
+        if any(p in ql for p in ("calculate", "solve", "what is ", "how much", "convert")):
+            return "math"
+        if any(p in ql for p in ("write ", "generate ", "create ", "make me", "compose")):
+            return "creative"
+        return "off_topic"
+    def _complexity(self, query: str) -> str:
+        """Classify query complexity."""
+        words = query.split()
+        n = len(words)
+        if n == 0:
+            return "empty"
+        if n == 1:
+            return "vague"
+        if n <= 4:
             return "simple"
+        if n <= 12:
             return "medium"
+        return "complex"
+    def _result(
         self,
         intent: str,
         confidence: float,
         method: str,
+        t0: float,
         complexity: str,
+        sub_type: str,
+        metadata: Optional[Dict] = None,
     ) -> IntentResult:
+        ms = (time.time() - t0) * 1000
+        self._metrics["total"] += 1
+        self._metrics["by_intent"][intent] = self._metrics["by_intent"].get(intent, 0) + 1
+        self._metrics["by_method"][method] = self._metrics["by_method"].get(method, 0) + 1
+        self._metrics["total_ms"] += ms
+        logger.debug(
+            f"Intent={intent} conf={confidence:.2f} method={method} "
+            f"sub={sub_type} complexity={complexity} time={ms:.1f}ms"
+        )
+        return IntentResult(
             intent=intent,
             confidence=confidence,
             method=method,
+            inference_time_ms=ms,
             query_complexity=complexity,
+            sub_type=sub_type,
+            should_use_live=(intent == "NEWS_TEMPORAL"),
+            should_use_db=(intent in ("NEWS_TEMPORAL", "NEWS_HISTORICAL", "NEWS_GENERAL")),
+            metadata=metadata or {},
         )
+    def _load_deberta(self):
+        """Lazy-load DeBERTa (thread-safe)."""
+        if self._pipe is not None or self._load_failed:
+            return
+        with self._lock:
+            if self._pipe is not None or self._load_failed:
+                return
+            try:
+                from transformers import pipeline
+                logger.info(f"Loading DeBERTa: {self.MODEL_NAME}")
+                self._pipe = pipeline(
+                    "zero-shot-classification",
+                    model=self.MODEL_NAME,
+                    device=-1,
+                    multi_label=False,
+                )
+                logger.info("✅ DeBERTa loaded")
+            except Exception as e:
+                logger.error(f"DeBERTa load failed: {e}")
+                self._load_failed = True
+    def _deberta_classify(self, query: str) -> Optional[Dict[str, Any]]:
+        """DeBERTa zero-shot classification for ambiguous queries."""
+        result = self._pipe(
+            query,
+            candidate_labels=[
+                "current news, breaking news, today's events, latest updates",
+                "historical events, background, context, past analysis",
+                "general news, politics, economy, society, Africa",
+                "personal question, identity, math, creative writing, off-topic",
+            ],
+            hypothesis_template="This text is about {}.",
         )
+        top_label = result["labels"][0]
+        top_score = float(result["scores"][0])
+        if top_score < 0.35:
+            return None  # Too uncertain, let default handle it
+        if "current" in top_label or "breaking" in top_label or "latest" in top_label:
+            intent = "NEWS_TEMPORAL"
+        elif "historical" in top_label or "background" in top_label:
+            intent = "NEWS_HISTORICAL"
+        elif "general news" in top_label or "politics" in top_label:
+            intent = "NEWS_GENERAL"
+        else:
+            intent = "OTHER"
+        return {
+            "intent": intent,
+            "confidence": top_score,
+            "metadata": {
+                "top_label": top_label,
+                "scores": dict(zip(result["labels"], result["scores"])),
+            },
+        }
     def get_metrics(self) -> Dict[str, Any]:
+        total = self._metrics["total"] or 1
+        return {
+            **self._metrics,
+            "avg_ms": self._metrics["total_ms"] / total,
         }
+# ═══════════════════════════════════════════════════════════════════════════════
+# SINGLETONS
+# ═══════════════════════════════════════════════════════════════════════════════
 intent_classifier_v2 = IntentClassifierV2()
 class IntentClassifier:
+    """Backward-compatible binary wrapper (NEWS / OTHER)."""
     def __init__(self):
+        self._v2 = intent_classifier_v2
     def classify(self, query: str) -> str:
+        result = self._v2.classify(query)
+        return "OTHER" if result.intent == "OTHER" else "NEWS"
 intent_classifier = IntentClassifier()