smartdocs-api / retrieval /query_classifier.py
Sahilalaknur's picture
Clean HF API deploy (no binary history)
fa1fead
Raw History Blame Contribute Delete
3.81 kB
# retrieval/query_classifier.py
# WHY THIS EXISTS: Classifies query type before retrieval.
# Each type has a different suggested_top_k for retrieval.
# Fast keyword matching — no API call, no latency.
import logging
from enum import Enum
from dataclasses import dataclass
logger = logging.getLogger(__name__)
class QueryType(str, Enum):
FACTUAL = "factual"
ANALYTICAL = "analytical"
CONVERSATIONAL = "conversational"
COMPARATIVE = "comparative"
OUT_OF_SCOPE = "out_of_scope"
@dataclass
class QueryClassificationResult:
query_type: QueryType
confidence: float
reasoning: str
suggested_top_k: int
# Keyword signals per query type — English + Hindi + Tamil + Telugu
QUERY_SIGNALS: dict[QueryType, list[str]] = {
QueryType.FACTUAL: [
"what is", "how much", "when", "who", "which", "where",
"क्या है", "कितना", "कब", "कौन", "कहाँ",
"என்ன", "எவ்வளவு", "ఏమిటి", "ఎంత",
],
QueryType.ANALYTICAL: [
"why", "how does", "explain", "reason", "cause", "impact",
"क्यों", "कैसे", "समझाइए", "कारण", "प्रभाव",
"ஏன்", "எப்படி", "ఎందుకు", "ఎలా",
],
QueryType.CONVERSATIONAL: [
"summarize", "overview", "tell me about", "describe", "brief",
"सारांश", "बताइए", "संक्षेप", "विवरण",
"சுருக்கம்", "సారాంశం",
],
QueryType.COMPARATIVE: [
"difference", "compare", "versus", "vs", "between", "unlike",
"अंतर", "तुलना", "बनाम", "वित्तीय अंतर",
"வித்தியாசம்", "తేడా",
],
}
QUERY_TYPE_TOP_K: dict[QueryType, int] = {
QueryType.FACTUAL: 5,
QueryType.ANALYTICAL: 8,
QueryType.CONVERSATIONAL: 10,
QueryType.COMPARATIVE: 8,
QueryType.OUT_OF_SCOPE: 0,
}
def classify_query(query: str) -> QueryClassificationResult:
"""
Classifies query into one of 5 types via keyword matching.
Zero API calls — pure local logic.
Determines suggested_top_k passed to hybrid_retriever.
Args:
query: Raw user query
Returns:
QueryClassificationResult — never raises
"""
if not query or not query.strip():
return QueryClassificationResult(
query_type=QueryType.FACTUAL,
confidence=0.5,
reasoning="Empty query — defaulting to factual",
suggested_top_k=5,
)
query_lower = query.lower().strip()
scores: dict[QueryType, int] = {qt: 0 for qt in QueryType}
for query_type, signals in QUERY_SIGNALS.items():
for signal in signals:
if signal in query_lower:
scores[query_type] += 1
scoreable = [qt for qt in QueryType if qt != QueryType.OUT_OF_SCOPE]
best_type = max(scoreable, key=lambda qt: scores[qt])
best_score = scores[best_type]
if best_score == 0:
best_type = QueryType.FACTUAL
confidence = 0.6
reasoning = "No signals matched — defaulting to factual"
else:
total = max(sum(scores.values()), 1)
confidence = round(best_score / total, 2)
reasoning = f"Matched {best_score} {best_type.value} signals"
logger.debug(
"Query classified",
extra={
"query_type": best_type.value,
"confidence": confidence,
"suggested_top_k": QUERY_TYPE_TOP_K[best_type],
},
)
return QueryClassificationResult(
query_type=best_type,
confidence=confidence,
reasoning=reasoning,
suggested_top_k=QUERY_TYPE_TOP_K[best_type],
)