""" 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