Oxinto-AI / services /recommendation.py
Ahsan
Initial deploy: Oxinto AI FastAPI backend
bd1531f
Raw History Blame Contribute Delete
13 kB
"""
Recommendation Engine — ported from Node.js to Python.
Scoring weights:
Category match: 35 pts
Budget compat: 25 pts (penalty -20 if >30% over ceiling)
Tag overlap: 25 pts (+10 bonus if overlap > 60%)
Feature keywords: 15 pts (0 if no free-text provided)
"""
import re
import json
import logging
from pathlib import Path
from typing import List, Dict, Optional, Any
logger = logging.getLogger(__name__)
WEIGHTS = {
"category": 35,
"budget": 25,
"tag": 25,
"feature": 15,
}
BUDGET_PENALTY = -20
TAG_BONUS_THRESHOLD = 0.6
TAG_BONUS_PTS = 10
BUDGET_OVERFLOW_PENALTY_THRESHOLD = 0.3
BUDGET_OVERFLOW_PARTIAL_MAX = 0.2
CATEGORY_KEYWORDS: Dict[str, List[str]] = {
"electronics": ["phone", "laptop", "tablet", "headphone", "earphone", "earbud",
"camera", "watch", "gaming", "console", "gadget", "electronic",
"tech", "device", "wireless", "bluetooth", "charger", "computer"],
"fashion": ["shoe", "sneaker", "clothing", "shirt", "pants", "jeans", "jacket",
"dress", "bag", "backpack", "watch", "sunglasses", "fashion", "style",
"wear", "outfit", "accessories", "jewelry"],
"home": ["kitchen", "furniture", "sofa", "desk", "lamp", "decor", "appliance",
"coffee", "cooker", "shelf", "shelf", "rug", "home", "house", "room"],
"health": ["skincare", "cream", "vitamin", "supplement", "fitness", "gym",
"dumbbell", "health", "beauty", "haircare", "sunscreen", "wellness"],
"entertainment": ["book", "game", "piano", "guitar", "sport", "tennis", "chess",
"puzzle", "music", "instrument", "hobby", "outdoor", "kindle"],
"grocery": ["food", "snack", "drink", "beverage", "organic", "grocery", "vitamin",
"cleaning", "pet", "dog", "cat", "household"],
}
BUDGET_PATTERNS = [
(r"under\s*\$?(\d+)", "max"),
(r"less\s+than\s*\$?(\d+)", "max"),
(r"below\s*\$?(\d+)", "max"),
(r"up\s+to\s*\$?(\d+)", "max"),
(r"\$(\d+)\s*(?:or\s+less|max|maximum)", "max"),
(r"\$(\d+)\s*[-–]\s*\$?(\d+)", "range"),
(r"around\s*\$?(\d+)", "around"),
(r"\$(\d+)\+", "min"),
(r"\$?(\d+)\s*budget", "max"),
]
def stem(word: str) -> str:
"""Minimal suffix stemmer."""
word = re.sub(r"ners?$", "n", word)
word = re.sub(r"ing$", "", word)
word = re.sub(r"ers?$", "", word)
word = re.sub(r"tion$", "", word)
word = re.sub(r"s$", "", word)
return word
def parse_query(query: str, forced_category: Optional[str] = None,
forced_budget_max: Optional[float] = None) -> Dict[str, Any]:
"""
Extract category, budget range, and keywords from a free-text query.
Returns a scoring context dict compatible with calculate_match_score().
"""
q = query.lower()
tokens = re.split(r"\W+", q)
tokens = [t for t in tokens if len(t) > 2]
# --- Detect category ---
category = forced_category
if not category:
scores = {cat: 0 for cat in CATEGORY_KEYWORDS}
for cat, kws in CATEGORY_KEYWORDS.items():
for kw in kws:
if kw in q:
scores[cat] += 1
best_cat = max(scores, key=lambda c: scores[c])
if scores[best_cat] > 0:
category = best_cat
# --- Detect budget ---
budget_min = 0.0
budget_max = float("inf")
if forced_budget_max is not None:
budget_max = forced_budget_max
else:
for pattern, mode in BUDGET_PATTERNS:
m = re.search(pattern, q)
if m:
if mode == "max":
budget_max = float(m.group(1))
break
elif mode == "min":
budget_min = float(m.group(1))
break
elif mode == "around":
val = float(m.group(1))
budget_min = val * 0.7
budget_max = val * 1.3
break
elif mode == "range":
budget_min = float(m.group(1))
budget_max = float(m.group(2))
break
# --- Extract tags from query tokens ---
tags = set()
for cat, kws in CATEGORY_KEYWORDS.items():
for kw in kws:
if kw in q:
tags.add(kw)
# Add budget tier tags
if budget_max <= 50:
tags.add("budget")
tags.add("value")
elif budget_max <= 150:
tags.add("mid-range")
elif budget_max > 200 or budget_min >= 200:
tags.add("premium")
# --- Extract keyword stems ---
keywords = [stem(t) for t in tokens if len(t) > 2]
wants_bundle = any(w in q for w in ["bundle", "kit", "package", "set"])
return {
"tags": list(tags),
"budget_min": budget_min,
"budget_max": budget_max,
"keywords": keywords,
"wants_bundle": wants_bundle,
"category": category,
"has_freetext_response": True, # query IS free text
}
def build_context_from_responses(responses: List[Dict], questionnaire_config: Dict) -> Dict[str, Any]:
"""Build scoring context from structured questionnaire responses."""
CATEGORY_MAP = ["electronics", "fashion", "home", "health", "entertainment", "grocery"]
context = {
"tags": set(),
"budget_min": 0.0,
"budget_max": float("inf"),
"keywords": [],
"wants_bundle": False,
"category": None,
"has_freetext_response": False,
}
questions_by_id = {q["id"]: q for q in questionnaire_config.get("questions", [])}
for response in responses:
if response.get("skipped"):
continue
qid = response.get("question_id") or response.get("questionId")
question = questions_by_id.get(qid)
if not question:
continue
answer_index = response.get("answer_index") if response.get("answer_index") is not None else response.get("answerIndex")
answer_text = response.get("answer_text") or response.get("answerText")
if answer_index is not None and "tags" in question:
tag_list = question["tags"].get(str(answer_index), [])
for t in tag_list:
context["tags"].add(t)
if qid == "q_category" and answer_index is not None:
context["category"] = CATEGORY_MAP[answer_index] if answer_index < len(CATEGORY_MAP) else None
if qid == "q_budget" and answer_index is not None and "budgetRanges" in question:
ranges = question["budgetRanges"]
if answer_index < len(ranges):
r = ranges[answer_index]
context["budget_min"] = r.get("min", 0)
context["budget_max"] = r.get("max", float("inf"))
if qid == "q_bundle" and answer_index == 0:
context["wants_bundle"] = True
if question.get("type") == "text" and answer_text:
context["has_freetext_response"] = True
words = re.split(r"\s+", answer_text.lower())
words = [w for w in words if len(w) > 2]
context["keywords"].extend([stem(w) for w in words])
return {
"tags": list(context["tags"]),
"budget_min": context["budget_min"],
"budget_max": context["budget_max"],
"keywords": context["keywords"],
"wants_bundle": context["wants_bundle"],
"category": context["category"],
"has_freetext_response": context["has_freetext_response"],
}
def calculate_match_score(product: Dict, context: Dict) -> float:
"""Score a single product against scoring context (0-100)."""
score = 0.0
budget_min = context.get("budget_min", 0)
budget_max = context.get("budget_max", float("inf"))
price = product.get("price", 0)
prod_category = product.get("category", "")
prod_tags = [t.lower() for t in product.get("tags", [])]
prod_features = product.get("features", [])
ctx_category = context.get("category")
ctx_tags = context.get("tags", [])
ctx_keywords = context.get("keywords", [])
has_freetext = context.get("has_freetext_response", False)
# 1. Category match (35 pts)
if ctx_category:
if prod_category == ctx_category:
score += WEIGHTS["category"]
# no category match → 0 pts
else:
score += round(WEIGHTS["category"] * 0.5)
# 2. Budget compatibility (25 pts) with penalty
if price >= budget_min and price <= budget_max:
score += WEIGHTS["budget"]
elif price < budget_min:
pass # below stated minimum — no points
elif budget_max != float("inf") and price > budget_max:
overflow = (price - budget_max) / budget_max
if overflow > BUDGET_OVERFLOW_PENALTY_THRESHOLD:
score += BUDGET_PENALTY
elif overflow <= BUDGET_OVERFLOW_PARTIAL_MAX:
score += round(WEIGHTS["budget"] * (1 - overflow / BUDGET_OVERFLOW_PARTIAL_MAX))
# 3. Tag overlap (25 pts) with bonus for high overlap
if ctx_tags and prod_tags:
prod_tag_set = set(prod_tags)
match_count = sum(1 for t in ctx_tags if t.lower() in prod_tag_set)
overlap = match_count / len(ctx_tags)
score += round(WEIGHTS["tag"] * min(overlap, 1.0))
if overlap > TAG_BONUS_THRESHOLD:
score += TAG_BONUS_PTS
elif not ctx_tags:
score += round(WEIGHTS["tag"] * 0.5)
# 4. Feature keyword match (15 pts) — only if free-text was provided
if has_freetext and ctx_keywords:
feature_text = " ".join(prod_features).lower()
name_text = (product.get("name", "") + " " + product.get("description", "")).lower()
combined = feature_text + " " + name_text
stemmed_tokens = [stem(t) for t in re.split(r"\W+", combined) if len(t) > 1]
match_count = sum(1 for kw in ctx_keywords if stem(kw) in stemmed_tokens)
kw_score = match_count / len(ctx_keywords)
score += round(WEIGHTS["feature"] * min(kw_score, 1.0))
return float(min(max(round(score), 0), 100))
def generate_reason(product: Dict, context: Dict, lang: str = "en") -> str:
"""Generate a human-readable reason for recommending this product."""
tags = [t.lower() for t in product.get("tags", [])]
features = [f.lower() for f in product.get("features", [])]
price = product.get("price", 0)
budget_max = context.get("budget_max", float("inf"))
score = product.get("score", 0)
reasons_en = []
reasons_pt = []
if "budget" in tags or "value" in tags:
reasons_en.append("great value for money")
reasons_pt.append("ótimo custo-benefício")
if "premium" in tags or "audiophile" in tags or "luxury" in tags:
reasons_en.append("premium quality")
reasons_pt.append("qualidade premium")
if "portable" in tags:
reasons_en.append("perfect for on-the-go")
reasons_pt.append("perfeito para usar em movimento")
if "professional" in tags:
reasons_en.append("ideal for professionals")
reasons_pt.append("ideal para profissionais")
if "noise-canceling" in features or "noise canceling" in features:
reasons_en.append("noise-canceling for focus")
reasons_pt.append("cancelamento de ruído para foco")
if "waterproof" in features or "water resistant" in features or "sports" in tags:
reasons_en.append("built for active use")
reasons_pt.append("feito para uso ativo")
if budget_max != float("inf") and price <= budget_max:
reasons_en.append(f"fits your budget at ${price:.0f}")
reasons_pt.append(f"cabe no seu orçamento por ${price:.0f}")
if score >= 70:
reasons_en.append("highly rated match for your needs")
reasons_pt.append("excelente compatibilidade com suas necessidades")
reasons = reasons_pt if lang == "pt" else reasons_en
if not reasons:
return "solid overall option" if lang != "pt" else "boa opção geral"
return ", ".join(reasons[:2])
def score_products(products: List[Dict], context: Dict) -> List[Dict]:
"""Score and sort all products against the context."""
# Filter to category if known
if context.get("category"):
filtered = [p for p in products if p.get("category") == context["category"]]
if filtered:
products = filtered
logger.info(
"Scoring %d products | category=%s budget=[%.0f-%.0f] tags=%s",
len(products),
context.get("category"),
context.get("budget_min", 0),
context.get("budget_max", float("inf")),
context.get("tags", [])[:5],
)
scored = []
for i, p in enumerate(products):
p_copy = dict(p)
p_copy["id"] = p.get("id", i + 1)
p_copy["score"] = calculate_match_score(p_copy, context)
p_copy["reason"] = generate_reason(p_copy, context)
scored.append(p_copy)
scored.sort(key=lambda x: x["score"], reverse=True)
return scored