RuPay-on-UPI, economics, raw-total ranking, merchant fix, remove debug

app/card_catalogue.py

@@ -55,6 +55,9 @@ class Card:
     highlights: List[str] = field(default_factory=list)
     persona_fit: List[str] = field(default_factory=list)
     annual_fee_text: str = ""
+    upi_eligible: bool = False   # RuPay credit cards can be linked to UPI
+    upi_base_rate: Optional[float] = None              # some UPI-first cards earn more on UPI
+    upi_category_rates: Dict[str, float] = field(default_factory=dict)
 
     def effective_rate(self, category: str) -> float:
         """Reward units earned per INR 100 for a given category."""
@@ -62,6 +65,18 @@ class Card:
             return 0.0
         return self.category_rates.get(category, self.base_rate)
 
+    def upi_effective_rate(self, category: str) -> float:
+        """Reward units per INR 100 on the UPI rail (UPI-specific rates take priority)."""
+        if category in self.excluded_categories:
+            return 0.0
+        if category in self.upi_category_rates:
+            return self.upi_category_rates[category]
+        if category in self.category_rates:
+            return self.category_rates[category]
+        if self.upi_base_rate is not None:
+            return self.upi_base_rate
+        return self.base_rate
+
     def value_per_100(self, category: str) -> float:
         """Net INR value earned per INR 100 spent in a category."""
         return self.effective_rate(category) * self.point_value_inr
@@ -341,6 +356,62 @@ CATALOGUE: List[Card] = [
         persona_fit=["young_professional", "food_lover", "value"],
         annual_fee_text="INR 500 + GST",
     ),
+    # ---- RuPay credit cards (linkable to UPI) ----
+    Card(
+        id="tataneu_infinity",
+        name="Tata Neu Infinity HDFC (RuPay)",
+        issuer="HDFC Bank",
+        network="RuPay",
+        segment="mid",
+        reward_unit="cashback",
+        point_value_inr=1.0,
+        base_rate=1.5,
+        category_rates={"online_shopping": 5.0, "groceries": 5.0},
+        caps={"online_shopping": 2000, "groceries": 2000},
+        excluded_categories=["fuel", "rent", "wallet_load"],
+        fees=FeeStructure(1499, 1499, 300000),
+        highlights=["1.5% NeuCoins on UPI spends", "5% on Tata Neu & partners", "UPI-linked"],
+        persona_fit=["online_shopper", "value", "young_professional"],
+        annual_fee_text="INR 1,499 + GST, waived on INR 3L spend",
+        upi_eligible=True,
+    ),
+    Card(
+        id="kiwi_axis",
+        name="Kiwi (Axis Bank) RuPay",
+        issuer="Axis Bank",
+        network="RuPay",
+        segment="entry",
+        reward_unit="cashback",
+        point_value_inr=1.0,
+        base_rate=1.0,
+        category_rates={"online_shopping": 2.0, "dining": 2.0, "groceries": 2.0, "utilities": 2.0},
+        caps={"online_shopping": 1000, "dining": 1000, "groceries": 1000, "utilities": 1000},
+        excluded_categories=["rent", "wallet_load"],
+        fees=FeeStructure(0, 0, None),
+        highlights=["Built for credit-on-UPI", "2% Neon cashback on UPI (vs 1% on swipe)", "Lifetime free"],
+        persona_fit=["young_professional", "value", "online_shopper"],
+        annual_fee_text="Lifetime free",
+        upi_eligible=True,
+        upi_base_rate=2.0,   # earns 2% on UPI vs 1% base on a normal swipe
+    ),
+    Card(
+        id="sbi_rupay_select",
+        name="SBI Card (RuPay) SELECT",
+        issuer="SBI Card",
+        network="RuPay",
+        segment="mid",
+        reward_unit="points",
+        point_value_inr=0.25,
+        base_rate=2.0,
+        category_rates={"dining": 5.0, "online_shopping": 5.0, "entertainment": 5.0},
+        caps={"dining": 5000, "online_shopping": 5000, "entertainment": 5000},
+        excluded_categories=["fuel", "rent", "wallet_load"],
+        fees=FeeStructure(499, 499, 100000),
+        highlights=["5x on dining & online via UPI", "RuPay UPI-linked", "Movie offers"],
+        persona_fit=["mid_spender", "lifestyle", "value"],
+        annual_fee_text="INR 499 + GST, waived on INR 1L spend",
+        upi_eligible=True,
+    ),
 ]
 
 
@@ -362,6 +433,9 @@ CARD_ECON = {
     "amex_mrcc": {"annual_fee": 4500, "fee_waiver_spend": None, "welcome_bonus_inr": 450, "welcome_bonus_min_spend": 20000, "milestones": [{"spend": 180000, "value": 8100}]},
     "amex_platinum_travel": {"annual_fee": 5000, "fee_waiver_spend": None, "welcome_bonus_inr": 0, "welcome_bonus_min_spend": 0, "milestones": [{"spend": 190000, "value": 11250}, {"spend": 400000, "value": 22000}]},
     "hdfc_swiggy": {"annual_fee": 500, "fee_waiver_spend": 200000, "welcome_bonus_inr": 1500, "welcome_bonus_min_spend": 0, "milestones": []},
+    "tataneu_infinity": {"annual_fee": 1499, "fee_waiver_spend": 300000, "welcome_bonus_inr": 1499, "welcome_bonus_min_spend": 0, "milestones": []},
+    "kiwi_axis": {"annual_fee": 0, "fee_waiver_spend": None, "welcome_bonus_inr": 0, "welcome_bonus_min_spend": 0, "milestones": []},
+    "sbi_rupay_select": {"annual_fee": 499, "fee_waiver_spend": 100000, "welcome_bonus_inr": 500, "welcome_bonus_min_spend": 0, "milestones": []},
 }
 
 

app/demo_data.py

@@ -1,6 +1,6 @@
 """Seed data so the app demos flawlessly with zero setup."""
 
-DEMO_WALLET = ["hdfc_millennia", "sbi_cashback", "axis_ace", "amex_mrcc"]
+DEMO_WALLET = ["hdfc_millennia", "sbi_cashback", "axis_ace", "amex_mrcc", "tataneu_infinity", "kiwi_axis"]
 
 DEMO_PERSONA = ["young_professional", "online_shopper", "traveller"]
 

app/main.py

@@ -61,6 +61,7 @@ class RecommendRequest(BaseModel):
     amount: Optional[float] = None
     merchant: Optional[str] = None
     persona: Optional[List[str]] = None
+    rail: Optional[str] = None            # "card" | "upi"; if None, inferred from query
 
 
 class AnalyzeRequest(BaseModel):
@@ -118,6 +119,7 @@ def recommend(req: RecommendRequest):
     held = req.held_cards or demo_data.DEMO_WALLET
     persona = req.persona or demo_data.DEMO_PERSONA
 
+    from merchants import detect_rail
     if req.query:
         intent = llm.parse_intent(req.query)
         category = intent["category"]
@@ -125,6 +127,7 @@ def recommend(req: RecommendRequest):
         merchant = intent.get("merchant")
         offers = intent.get("offers") or []
         brand_key = intent.get("brand_key")
+        rail = req.rail or detect_rail(req.query) or "card"
     else:
         category = req.category or "general"
         amount = req.amount or 5000
@@ -132,14 +135,15 @@ def recommend(req: RecommendRequest):
         resolved = resolve_merchant(merchant or "")
         offers = resolved["offers"]
         brand_key = resolved["brand_key"]
+        rail = req.rail or "card"
 
     ctx = TxnContext(category=category, amount=float(amount), merchant=merchant,
-                     brand_key=brand_key, offers=offers)
+                     brand_key=brand_key, offers=offers, rail=rail)
     result = score_transaction(held, ctx, include_discovery=True, persona=persona)
     result["narration"] = llm.narrate_recommendation(
         result["context"], result["held_ranked"], result["discovery"]
     )
-    result["intent"] = {"category": category, "amount": amount, "merchant": merchant}
+    result["intent"] = {"category": category, "amount": amount, "merchant": merchant, "rail": rail}
     return result
 
 

app/merchants.py

@@ -167,6 +167,19 @@ def resolve_merchant(text: str) -> Dict:
     }
 
 
+UPI_HINTS = ["upi", "scan", " qr", "qr code", "gpay", "google pay", "phonepe", "paytm", "bhim", "rupay"]
+
+
+def detect_rail(text: str):
+    """Return 'upi', 'card', or None based on payment-method hints in the phrase."""
+    t = (text or "").lower()
+    if any(h in t for h in UPI_HINTS):
+        return "upi"
+    if "swipe" in t or "tap" in t or "card" in t:
+        return "card"
+    return None
+
+
 def extract_amount(text: str) -> Optional[float]:
     """Pull an INR amount out of a spoken phrase, if present."""
     import re

app/scoring_engine.py

@@ -57,6 +57,12 @@ def apply_url_for(card_id: str) -> str:
     return f"https://www.google.com/search?q={q}"
 
 
+# RuPay credit-on-UPI rules (NPCI): rewards only accrue at/above the interchange
+# floor, and these categories earn nothing on the UPI rail.
+UPI_MIN_REWARD_AMOUNT = 2000
+UPI_EXCLUDED_CATEGORIES = {"fuel", "rent", "wallet_load"}
+
+
 @dataclass
 class TxnContext:
     category: str
@@ -64,6 +70,7 @@ class TxnContext:
     merchant: Optional[str] = None
     brand_key: Optional[str] = None
     offers: Optional[List[Dict]] = None
+    rail: str = "card"               # "card" (POS/online) or "upi" (RuPay credit-on-UPI)
 
 
 @dataclass
@@ -74,7 +81,8 @@ class CardScore:
     network: str
     reward_value_inr: float          # rewards earned on this txn (capped)
     instant_offer_inr: float         # instant discount from live offers
-    total_value_inr: float           # reward + instant offer
+    total_value_inr: float           # reward + instant offer (rounded for display)
+    raw_total: float                 # unrounded total — used for ranking
     effective_rate_pct: float        # total value as % of spend
     capped: bool                     # whether monthly cap limited the reward
     reasons: List[str]
@@ -123,23 +131,39 @@ def score_transaction(
     held_scores: List[CardScore] = []
     all_scores: List[CardScore] = []
 
+    rail = getattr(ctx, "rail", "card") or "card"
+
     for card in all_cards():
         held = card.id in held_card_ids
+
+        # --- RuPay credit-on-UPI eligibility ---
+        upi_block = None
+        if rail == "upi":
+            if not card.upi_eligible:
+                upi_block = f"{card.network} cards can't be linked to UPI — only RuPay credit cards work on UPI."
+            elif ctx.amount < UPI_MIN_REWARD_AMOUNT:
+                upi_block = f"UPI spends under ₹{UPI_MIN_REWARD_AMOUNT:,.0f} earn no rewards (issuers get no interchange below this)."
+            elif ctx.category in UPI_EXCLUDED_CATEGORIES:
+                upi_block = f"{ctx.category.replace('_', ' ').title()} earns nothing on the UPI rail (excluded category)."
+
         # --- reward value, respecting monthly caps ---
-        rate = card.effective_rate(ctx.category)          # reward units / 100
+        if upi_block:
+            rate = 0.0
+        elif rail == "upi":
+            rate = card.upi_effective_rate(ctx.category)
+        else:
+            rate = card.effective_rate(ctx.category)
         gross_units = ctx.amount / 100.0 * rate
         capped = False
 
         cap_units = card.caps.get(ctx.category)
-        if cap_units is not None:
+        if not upi_block and cap_units is not None and rate > 0:
             spent = mtd_spend.get(card.id, {}).get(ctx.category, 0.0)
             already_units = spent / 100.0 * rate
             remaining_units = max(0.0, cap_units - already_units)
             if gross_units > remaining_units:
-                # accelerated portion capped; remainder earns base rate
                 accel_units = remaining_units
                 base_units_value = card.base_rate if ctx.category not in card.excluded_categories else 0.0
-                # rupees beyond the cap earn base rate
                 rupees_at_accel = remaining_units / rate * 100.0 if rate > 0 else 0.0
                 rupees_beyond = max(0.0, ctx.amount - rupees_at_accel)
                 gross_units = accel_units + rupees_beyond / 100.0 * base_units_value
@@ -147,15 +171,20 @@ def score_transaction(
 
         reward_inr = gross_units * card.point_value_inr
 
-        # --- instant offers ---
-        offer_inr, offer_note = _instant_offer_value(card, ctx)
+        # --- instant offers (don't apply on the UPI rail) ---
+        if rail == "upi":
+            offer_inr, offer_note = 0.0, None
+        else:
+            offer_inr, offer_note = _instant_offer_value(card, ctx)
 
         total = reward_inr + offer_inr
         eff_pct = (total / ctx.amount * 100.0) if ctx.amount else 0.0
 
         # --- reasons ---
         reasons: List[str] = []
-        if ctx.category in card.excluded_categories:
+        if upi_block:
+            reasons.append(upi_block)
+        elif ctx.category in card.excluded_categories:
             reasons.append(f"{ctx.category.replace('_', ' ').title()} is excluded on this card — earns nothing.")
         else:
             reasons.append(
@@ -176,6 +205,7 @@ def score_transaction(
             reward_value_inr=round(reward_inr, 2),
             instant_offer_inr=round(offer_inr, 2),
             total_value_inr=round(total, 2),
+            raw_total=total,
             effective_rate_pct=round(eff_pct, 2),
             capped=capped,
             reasons=reasons,
@@ -185,9 +215,9 @@ def score_transaction(
         if held:
             held_scores.append(sc)
 
-    # sort best-first
-    held_scores.sort(key=lambda s: s.total_value_inr, reverse=True)
-    all_scores.sort(key=lambda s: s.total_value_inr, reverse=True)
+    # sort best-first by the unrounded total (display rounding must not flip ties)
+    held_scores.sort(key=lambda s: s.raw_total, reverse=True)
+    all_scores.sort(key=lambda s: s.raw_total, reverse=True)
 
     # --- personalized, comparative reasoning for why each card ranks where it does ---
     def _money(n: float) -> str:
@@ -195,23 +225,36 @@ def score_transaction(
 
     if held_scores:
         top = held_scores[0]
+        none_earn = top.total_value_inr <= 0
         for i, s in enumerate(held_scores):
             lead = []
+            pl = None
             if i == 0:
-                if len(held_scores) > 1:
+                if none_earn:
                     lead.append(
-                        f"Your #1 here — returns {_money(top.total_value_inr - held_scores[1].total_value_inr)} "
-                        f"more than your next-best card ({held_scores[1].card_name})."
+                        "None of your cards earn rewards on this UPI payment — here's why."
+                        if rail == "upi" else
+                        "None of your cards earn rewards on this purchase."
                     )
+                elif len(held_scores) > 1:
+                    d = top.total_value_inr - held_scores[1].total_value_inr
+                    if d > 0:
+                        lead.append(
+                            f"Your #1 here — returns {_money(d)} "
+                            f"more than your next-best card ({held_scores[1].card_name})."
+                        )
+                    else:
+                        lead.append(f"Tied best with {held_scores[1].card_name} — both earn the same here.")
+                    pl = _persona_line(s.card_id, persona)
                 else:
                     lead.append("Your best card for this purchase.")
-                pl = _persona_line(s.card_id, persona)
-            else:
-                lead.append(
-                    f"Ranks #{i+1} — {_money(top.total_value_inr - s.total_value_inr)} "
-                    f"less than {top.card_name} on this spend."
-                )
-                pl = None
+                    pl = _persona_line(s.card_id, persona)
+            elif not none_earn and s.total_value_inr > 0:
+                d = top.total_value_inr - s.total_value_inr
+                if d > 0:
+                    lead.append(f"Ranks #{i+1} — {_money(d)} less than {top.card_name} on this spend.")
+                else:
+                    lead.append(f"Ties {top.card_name} here — same value.")
             s.reasons = lead + s.reasons + ([pl] if pl else [])
 
     # discovery: best non-held card that beats the user's best held card by a margin
@@ -265,6 +308,7 @@ def score_transaction(
             "merchant": ctx.merchant,
             "brand_key": ctx.brand_key,
             "offers": ctx.offers or [],
+            "rail": rail,
         },
     }
 
@@ -284,37 +328,47 @@ def analyse_transaction_history(
     mtd: Dict[str, Dict[str, float]] = {}
 
     for txn in transactions:
-        ctx = TxnContext(
-            category=txn["category"],
-            amount=float(txn["amount"]),
-            merchant=txn.get("merchant"),
-            brand_key=txn.get("brand_key"),
-            offers=txn.get("offers"),
-        )
-        scored = score_transaction(held_card_ids, ctx, mtd_spend=mtd, include_discovery=False)
-        ranked = scored["held_ranked"]
+        def _ctx(rail):
+            return TxnContext(
+                category=txn["category"], amount=float(txn["amount"]),
+                merchant=txn.get("merchant"), brand_key=txn.get("brand_key"),
+                offers=txn.get("offers"), rail=rail,
+            )
+        # statement transactions were card swipes -> "used" is on the card rail;
+        # also check the UPI (RuPay) rail to find the true cross-rail optimum.
+        scored_card = score_transaction(held_card_ids, _ctx("card"), mtd_spend=mtd, include_discovery=False)
+        scored_upi = score_transaction(held_card_ids, _ctx("upi"), mtd_spend=mtd, include_discovery=False)
+        ranked_card = scored_card["held_ranked"]
         used_id = txn.get("card_id_used")
-        used = next((r for r in ranked if r["card_id"] == used_id), None)
-        best = ranked[0] if ranked else None
+        used = next((r for r in ranked_card if r["card_id"] == used_id), None)
+        best_card = ranked_card[0] if ranked_card else None
+        best_upi = scored_upi["held_ranked"][0] if scored_upi["held_ranked"] else None
+
+        optimal = best_card
+        optimal_rail = "card"
+        if best_upi and best_upi["total_value_inr"] > (best_card["total_value_inr"] if best_card else 0):
+            optimal = best_upi
+            optimal_rail = "upi"
 
         lost = 0.0
-        optimal = True
-        if used and best:
-            lost = round(best["total_value_inr"] - used["total_value_inr"], 2)
-            optimal = lost <= 0.01
+        was_optimal = True
+        if used and optimal:
+            lost = round(optimal["total_value_inr"] - used["total_value_inr"], 2)
+            was_optimal = lost <= 0.01
         total_lost += max(0.0, lost)
 
-        # update MTD spend
         if used_id:
-            mtd.setdefault(used_id, {}).setdefault(ctx.category, 0.0)
-            mtd[used_id][ctx.category] += ctx.amount
+            mtd.setdefault(used_id, {}).setdefault(txn["category"], 0.0)
+            mtd[used_id][txn["category"]] += float(txn["amount"])
 
         results.append({
             **txn,
             "used_card": used,
-            "optimal_card": best,
-            "was_optimal": optimal,
+            "optimal_card": optimal,
+            "was_optimal": was_optimal,
             "amount_lost": max(0.0, lost),
+            "optimal_rail": optimal_rail,
+            "rail_switch_helps": optimal_rail == "upi" and not was_optimal,
         })
 
     return {