Credit-limit detection: inline + positional + OCR fallback (Kotak/Axis/IDFC/HDFC)

Dockerfile

@@ -1,9 +1,12 @@
 # RewardPilot API — Hugging Face Docker Space
 FROM python:3.11-slim
 
-# small system deps some wheels expect
+# build tools + Tesseract OCR & Poppler (for reading the credit limit off image-only
+# statement summaries like HDFC's)
 RUN apt-get update && apt-get install -y --no-install-recommends \
       build-essential \
+      tesseract-ocr \
+      poppler-utils \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app

app/card_catalogue.py

@@ -1,5 +1,5 @@
 """
-RewardPilot — Card Catalogue
+RewardPilot - Card Catalogue
 ============================
 Canonical, curated economics for major Indian consumer credit cards.
 
@@ -526,7 +526,7 @@ CATALOGUE_BY_ID = {c.id: c for c in CATALOGUE}
 
 # Per-card economics for the "should I apply" decision (mirrors app CARD_ECON):
 # annual_fee, fee_waiver_spend, welcome_bonus_inr, welcome_bonus_min_spend, milestones.
-# Curated 2025-26 estimates — validate against live T&C.
+# Curated 2025-26 estimates - validate against live T&C.
 CARD_ECON = {
     "hdfc_infinia": {"annual_fee": 12500, "fee_waiver_spend": 1000000, "welcome_bonus_inr": 12500, "welcome_bonus_min_spend": 0, "milestones": []},
     "hdfc_regalia_gold": {"annual_fee": 2500, "fee_waiver_spend": 400000, "welcome_bonus_inr": 2500, "welcome_bonus_min_spend": 0, "milestones": [{"spend": 400000, "value": 5000}]},

app/demo_data.py

@@ -4,7 +4,7 @@ DEMO_WALLET = ["hdfc_millennia", "sbi_cashback", "axis_ace", "amex_mrcc", "tatan
 
 DEMO_PERSONA = ["young_professional", "online_shopper", "traveller"]
 
-# 3 months of realistic transactions, some optimal, some not — to showcase the
+# 3 months of realistic transactions, some optimal, some not - to showcase the
 # "you used the wrong card" analysis.
 DEMO_TRANSACTIONS = [
     {"id": "t1",  "date": "2026-06-22", "merchant": "amazon",   "description": "Amazon - Electronics",        "category": "online_shopping", "amount": 42000, "brand_key": "amazon",  "card_id_used": "amex_mrcc"},

app/llm.py

@@ -1,7 +1,7 @@
 """
-RewardPilot — LLM personalization & speech-to-text layer
+RewardPilot - LLM personalization & speech-to-text layer
 ========================================================
-The model NEVER decides which card wins — the deterministic engine does that.
+The model NEVER decides which card wins - the deterministic engine does that.
 The LLM only:
   1. turns a spoken/typed phrase into a structured intent (merchant, category, amount)
   2. writes the human "why this card" narration around the engine's numbers
@@ -152,7 +152,7 @@ _SYSTEM = (
     "explanation. Hard rules, never break them:\n"
     "1. Use ONLY the card names and facts provided. Never mention a card, benefit, "
     "offer, fee or number that is not in the input.\n"
-    "2. Do NOT state specific rupee amounts or percentages — they are shown to the "
+    "2. Do NOT state specific rupee amounts or percentages - they are shown to the "
     "user separately. Refer to value qualitatively (e.g. 'clearly ahead', 'a bit more').\n"
     "3. 2-3 sentences. Say which card to use and why, then the runner-up in a few words, "
     "then one line on the better card to consider if one is provided.\n"

app/main.py

@@ -162,9 +162,10 @@ async def parse_statements(
     files: List[UploadFile] = File(...),
     password: Optional[str] = Form(None),
 ):
-    from statement_parser import parse_statement
+    from statement_parser import parse_statement, detect_credit_limit
     all_txns = []
     errors = []
+    limits = []
     for f in files:
         try:
             content = await f.read()
@@ -172,9 +173,16 @@ async def parse_statements(
             for t in txns:
                 t["source_file"] = f.filename
             all_txns.extend(txns)
+            try:
+                lim = detect_credit_limit(f.filename, content, password=password)
+                if lim:
+                    limits.append(lim)
+            except Exception:
+                pass   # credit-limit detection is best-effort, never fails the parse
         except Exception as e:
             errors.append({"file": f.filename, "error": str(e)})
-    return {"transactions": all_txns, "count": len(all_txns), "errors": errors}
+    return {"transactions": all_txns, "count": len(all_txns), "errors": errors,
+            "credit_limit": max(limits) if limits else None}
 
 
 @app.post("/transactions/analyze")

app/merchants.py

@@ -1,5 +1,5 @@
 """
-RewardPilot — Merchant & MCC resolution
+RewardPilot - Merchant & MCC resolution
 =======================================
 Maps a free-text merchant / spoken phrase to a canonical category and detects
 live brand offers. In production this is backed by a continuously curated
@@ -127,7 +127,7 @@ MERCHANT_MAP: Dict[str, Tuple[str, Optional[str]]] = {
     "figma": ("online_shopping", None),
     "vercel": ("online_shopping", None),
     "digitalocean": ("online_shopping", None),
-    # test prep / education (correct category — GMAT/MBA prep is education spend)
+    # test prep / education (correct category - GMAT/MBA prep is education spend)
     "gmatclub": ("education", None),
     "gmat": ("education", None),
     "targettestprep": ("education", None),
@@ -174,7 +174,7 @@ LIVE_OFFERS: Dict[str, List[Dict]] = {
 }
 
 
-# Retailers / merchants — preferred over product words so "iPhone at Croma"
+# Retailers / merchants - preferred over product words so "iPhone at Croma"
 # resolves the merchant to Croma, not iPhone.
 STORE_KEYWORDS = {
     "reliance digital", "vijay sales", "croma", "amazon", "flipkart", "myntra", "ajio",

app/offers.py

@@ -1,9 +1,9 @@
 """
-RewardPilot — Offers store
+RewardPilot - Offers store
 ==========================
 Structured, dated, source-attributed card offers. This is the source of truth
 the engine reads at recommend time. It is fed by the ingestion connectors
-(issuer scrapers, CLO networks, affiliate feeds) after human QA — see
+(issuer scrapers, CLO networks, affiliate feeds) after human QA - see
 connectors/ingest.py. Until a live feed is wired, it ships a curated seed.
 
 Each offer is structured (not free text), so the engine can value it exactly:

app/places.py

@@ -1,5 +1,5 @@
 """
-RewardPilot — Places proxy
+RewardPilot - Places proxy
 ==========================
 Turns GPS coordinates into known-merchant candidates. The provider key (Google
 Places / Foursquare) is held SERVER-SIDE (never in the app), mirroring how the

app/scoring_engine.py

@@ -1,5 +1,5 @@
 """
-RewardPilot — Deterministic Scoring Engine
+RewardPilot - Deterministic Scoring Engine
 ==========================================
 The engine sets the number; the LLM only narrates it.
 
@@ -91,7 +91,7 @@ class CardScore:
     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 (rounded for display)
-    raw_total: float                 # unrounded total — used for ranking
+    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]
@@ -243,7 +243,7 @@ def score_transaction(
             )
         if offer_inr > 0 and offer_note:
             reasons.append(f"Live offer: {offer_note} (~₹{offer_inr:,.0f}).")
-        # Portal-only elevated rate (HDFC SmartBuy, Axis Travel Edge) — informational,
+        # Portal-only elevated rate (HDFC SmartBuy, Axis Travel Edge) - informational,
         # NOT scored, since it isn't earned on a direct merchant booking.
         portal_rate = card.portal_rates.get(ctx.category) if not upi_block else None
         if portal_rate and portal_rate > rate and ctx.category not in card.excluded_categories:
@@ -284,7 +284,7 @@ def score_transaction(
 
     # sort best-first by the unrounded total (display rounding must not flip ties).
     # On the UPI rail a non-RuPay card can't be linked at all, so it must never rank above a
-    # UPI-eligible card of equal value (e.g. a sub-₹2,000 UPI spend earns everyone ₹0 — the top
+    # UPI-eligible card of equal value (e.g. a sub-₹2,000 UPI spend earns everyone ₹0 - the top
     # pick should still be a card you can actually pay with on UPI).
     _upi_ok = {c.id for c in all_cards() if getattr(c, "upi_eligible", False)}
     def _rank_key(s):

app/statement_parser.py

@@ -1,5 +1,5 @@
 """
-RewardPilot — Statement Parser
+RewardPilot - Statement Parser
 ==============================
 Parses uploaded credit card statements (PDF or CSV) into normalized
 transactions. Real PDF text extraction via pdfplumber; CSV via stdlib.
@@ -25,8 +25,8 @@ DATE_PATTERNS = [
     "%Y-%m-%d", "%m/%d/%Y", "%d.%m.%Y", "%d-%b-%y", "%d %b %y",
 ]
 
-AMOUNT_RE = re.compile(r"(-?\d[\d,]*\.\d{2})")              # strict (decimals) — safe to scan whole rows
-_AMOUNT_LENIENT_RE = re.compile(r"(-?\d[\d,]*(?:\.\d{1,2})?)")  # integer-or-decimal — dedicated amount column only
+AMOUNT_RE = re.compile(r"(-?\d[\d,]*\.\d{2})")              # strict (decimals) - safe to scan whole rows
+_AMOUNT_LENIENT_RE = re.compile(r"(-?\d[\d,]*(?:\.\d{1,2})?)")  # integer-or-decimal - dedicated amount column only
 
 
 def _parse_amount_cell(s: str):
@@ -245,7 +245,7 @@ def parse_csv(content: bytes) -> List[Dict]:
             amount = _parse_amount_cell(r[ai]) if 0 <= ai < len(r) else None
             if amount is None and ai < 0:
                 # ONLY when no amount/debit column exists: scan the row. If a debit column
-                # exists but is empty, the row is a credit/refund — do NOT scan (that would
+                # exists but is empty, the row is a credit/refund - do NOT scan (that would
                 # grab the Credit-column value and count it as a spend).
                 m = AMOUNT_RE.search(" ".join(r))
                 amount = float(m.group(1).replace(",", "")) if m else None
@@ -260,7 +260,7 @@ def parse_csv(content: bytes) -> List[Dict]:
             out.append(_normalize_row(iso, desc, amount))
         return out  # header found: trust it (even if every row was a credit/payment)
 
-    # fallback: no recognizable header — infer per row from date + amount tokens
+    # fallback: no recognizable header - infer per row from date + amount tokens
     for r in rows:
         date_field = next((c for c in r if _parse_date(c)), None)
         if not date_field:
@@ -467,6 +467,156 @@ def parse_pdf(content: bytes, password: Optional[str] = None) -> List[Dict]:
     return out
 
 
+# "Credit Limit Rs. 11,30,000" appears in the statement header. We use it to estimate
+# income when the user hasn't given one. Excludes "available" / "cash" limits, which are
+# lower/different. `credit\s*limit` tolerates the glued "TotalCreditLimit" some PDFs render.
+# Require a currency marker (Rs/INR/₹) right before the figure so we don't grab a stray
+# year ("Credit Limit ... Jan 2026") when the label and value sit on different lines.
+_CREDIT_LIMIT_RE = re.compile(
+    r"credit\s*limit\b[^0-9₹]{0,18}(?:rs\.?|inr|₹)\s*([1-9][\d,]{3,}(?:\.\d{1,2})?)", re.I)
+# A word that is a rupee amount, possibly with an 'r'/Rs/₹ prefix (many PDFs render ₹ as 'r').
+_LIMIT_AMT_WORD = re.compile(r"^(?:r|rs\.?|inr|₹)?\s*(\d[\d,]{4,}(?:\.\d{1,2})?)$", re.I)
+
+
+def _plausible_limit(v: float) -> bool:
+    return 25000 <= v <= 1e8   # real card limits; floor rejects years/small numbers
+
+
+def _inline_credit_limit(text: str) -> Optional[float]:
+    """Inline 'Credit Limit Rs 11,30,000' on a single line (Kotak, SBI, many issuers)."""
+    best = None
+    for m in _CREDIT_LIMIT_RE.finditer(text or ""):
+        pre = text[max(0, m.start() - 18):m.start()].lower()
+        if "available" in pre or "cash" in pre:
+            continue
+        try:
+            v = float(m.group(1).replace(",", ""))
+        except ValueError:
+            continue
+        if _plausible_limit(v) and (best is None or v > best):
+            best = v
+    return best
+
+
+def _credit_limit_from_words(words: List[dict]) -> Optional[float]:
+    """Given positioned words ({text,x0,x1,top}) from a page or OCR, find the total credit
+    limit near a (non-available) 'Credit Limit' label: prefer a rupee amount to its right or
+    directly beneath it; failing that, take the LARGEST plausible amount in the summary band
+    around the label - a credit limit is always the biggest figure in its box (dues can never
+    exceed it), which reliably picks it out of statements like HDFC where labels and values
+    don't align in a column."""
+    best = None
+    for i in range(len(words) - 1):
+        if words[i]["text"].lower() != "credit" or words[i + 1]["text"].lower() != "limit":
+            continue
+        if abs(words[i + 1]["top"] - words[i]["top"]) > 4:
+            continue
+        pre = words[i - 1]["text"].lower() if i > 0 else ""
+        if pre in ("available", "cash") or "avl" in pre:
+            continue
+        lx0, lx1, ltop = words[i]["x0"], words[i + 1]["x1"], words[i]["top"]
+        aligned, band = [], []
+        for a in words:
+            m = _LIMIT_AMT_WORD.match(a["text"].replace(" ", ""))
+            if not m:
+                continue
+            try:
+                v = float(m.group(1).replace(",", ""))
+            except ValueError:
+                continue
+            if not _plausible_limit(v):
+                continue
+            if (abs(a["top"] - ltop) <= 4 and lx1 < a["x0"] < lx1 + 130) or \
+               (ltop < a["top"] <= ltop + 70 and a["x0"] < lx1 + 30 and a["x1"] > lx0 - 30):
+                aligned.append(v)
+            if ltop - 55 <= a["top"] <= ltop + 80:
+                band.append(v)
+        cand = max(aligned) if aligned else (max(band) if band else None)
+        if cand is not None and (best is None or cand > best):
+            best = cand
+    return best
+
+
+def _positional_credit_limit(pdf) -> Optional[float]:
+    best = None
+    try:
+        pages = pdf.pages[:3]
+    except Exception:
+        return None
+    for page in pages:
+        try:
+            v = _credit_limit_from_words(page.extract_words())
+        except Exception:
+            continue
+        if v and (best is None or v > best):
+            best = v
+    return best
+
+
+def _ocr_credit_limit(content: bytes, password: Optional[str] = None) -> Optional[float]:
+    """Last-resort OCR for statements whose summary is a rendered image / has no usable text
+    layer (HDFC). Rasterises the first two pages and reuses the positional logic on the OCR'd
+    words. All heavy deps are lazily imported so a Space without them just skips this."""
+    try:
+        import io as _io
+        import pdf2image
+        import pytesseract
+        from pypdf import PdfReader, PdfWriter
+    except Exception:
+        return None
+    try:
+        reader = PdfReader(_io.BytesIO(content))
+        if reader.is_encrypted:
+            reader.decrypt(password or "")
+        writer = PdfWriter()
+        for p in reader.pages[:2]:
+            writer.add_page(p)
+        buf = _io.BytesIO(); writer.write(buf)
+        images = pdf2image.convert_from_bytes(buf.getvalue(), dpi=200)
+    except Exception:
+        return None
+    best = None
+    scale = 72.0 / 200.0   # normalise OCR pixels to PDF points so the same tolerances apply
+    for img in images[:2]:
+        try:
+            d = pytesseract.image_to_data(img, output_type=pytesseract.Output.DICT)
+        except Exception:
+            continue
+        words = []
+        for j in range(len(d["text"])):
+            t = (d["text"][j] or "").strip()
+            if t:
+                words.append({"text": t, "x0": d["left"][j] * scale,
+                              "x1": (d["left"][j] + d["width"][j]) * scale, "top": d["top"][j] * scale})
+        text = " ".join(w["text"] for w in words)
+        v = _inline_credit_limit(text) or _credit_limit_from_words(words)
+        if v and (best is None or v > best):
+            best = v
+    return best
+
+
+def detect_credit_limit(filename: str, content: bytes, password: Optional[str] = None) -> Optional[float]:
+    """The card's total credit limit from the statement, ignoring available/cash limits.
+    Tiered: inline text, then column-aligned positional, then OCR (only if the text layer
+    yields nothing). Returns None (never a wrong guess) when nothing plausible is found."""
+    name = (filename or "").lower()
+    if name.endswith(".pdf"):
+        try:
+            import pdfplumber
+            with pdfplumber.open(io.BytesIO(content), password=password or "") as pdf:
+                text = "\n".join((p.extract_text() or "") for p in pdf.pages[:3])
+                cands = [x for x in (_inline_credit_limit(text), _positional_credit_limit(pdf)) if x]
+                if cands:
+                    return max(cands)
+        except Exception:
+            pass
+        return _ocr_credit_limit(content, password)   # image-only statements (HDFC)
+    try:
+        return _inline_credit_limit(content.decode("utf-8-sig", errors="ignore"))
+    except Exception:
+        return None
+
+
 def parse_statement(filename: str, content: bytes, password: Optional[str] = None) -> List[Dict]:
     name = filename.lower()
     if name.endswith(".csv"):

requirements.txt

@@ -2,6 +2,9 @@ fastapi==0.111.0
 uvicorn[standard]==0.30.1
 python-multipart==0.0.9
 pdfplumber==0.11.0
+pypdf==4.2.0
+pdf2image==1.17.0
+pytesseract==0.3.10
 pydantic==2.7.4
 openai==1.35.7
 anthropic==0.30.1