feat: enhance UI, fix timezone, improve vision agent and email extraction, update README

.gitignore

@@ -9,3 +9,5 @@ __pycache__/
 .env
 models/
 data/
+fix_indent.py
+test_extraction.py

README.md

@@ -36,6 +36,17 @@ tags:
 
 ---
 
+## 📺 Video Demo & 📖 Full Write-up
+
+Check out the deep dive into the architecture and the story behind the build:
+
+📰 **Read the full breakdown on Medium**: [Sorting my bank emails offline with small AI models](https://medium.com/@aa911mdccxxix/sorting-my-bank-emails-offline-with-small-ai-models-fec305c564f6)
+
+🎥 **Watch the Demo on YouTube:**
+[![YouTube Demo](https://img.youtube.com/vi/s6H9iZR8PDs/maxresdefault.jpg)](https://youtu.be/s6H9iZR8PDs)
+
+---
+
 ## 🎯 The Problem
 
 Indian consumers receive **hundreds** of banking emails monthly — transaction alerts from HDFC, SBI, ICICI, Kotak, IDFC First, Amex, and more. Buried in these emails are:

app.py

@@ -415,7 +415,13 @@ def get_dashboard_stats_html() -> str:
     """Generate HTML for dashboard statistics cards."""
     stats = db.get_dashboard_stats()
     latest = stats.get("latest_sync_date")
-    latest_str = latest.strftime("%d %b %Y, %H:%M") if latest else "Never"
+    if latest:
+        from datetime import timedelta
+        # Add 5 hours 30 mins to convert UTC to IST
+        latest_ist = latest + timedelta(hours=5, minutes=30)
+        latest_str = latest_ist.strftime("%d %b %Y, %H:%M IST")
+    else:
+        latest_str = "Never"
 
     return f"""
 <div style="display: grid; grid-template-columns: repeat(4, 1fr); gap: 12px; margin: 10px 0;">
@@ -869,19 +875,11 @@ def create_app():
                         type="password",
                         placeholder="xxxx xxxx xxxx xxxx",
                         elem_id="password-input",
+                        info="Need an App Password? [Gmail](https://myaccount.google.com/apppasswords) | [Outlook](https://account.live.com/proofs/manage/additional) | [Yahoo](https://login.yahoo.com/account/security)"
                     )
 
-                    gr.HTML("""
-                        <div style='font-size: 0.8em; color: #8888aa; margin-top: -10px; margin-bottom: 10px;'>
-                            Need an App Password?
-                            <a href='https://myaccount.google.com/apppasswords' target='_blank' style='color: #43E8D8;'>Gmail</a> |
-                            <a href='https://account.live.com/proofs/manage/additional' target='_blank' style='color: #43E8D8;'>Outlook</a> |
-                            <a href='https://login.yahoo.com/account/security' target='_blank' style='color: #43E8D8;'>Yahoo</a>
-                        </div>
-                    """)
-
                     add_account_btn = gr.Button("Add Account", variant="secondary")
-                    accounts_display = gr.Markdown("No accounts added yet.", elem_classes=["markdown-text"])
+                    accounts_display = gr.Markdown("No accounts added yet.", elem_classes=["markdown-text"], elem_id="accounts-display")
 
                 gr.HTML('<hr style="margin: 8px 0; border-color: #2a2a4a;">')
 
@@ -926,8 +924,8 @@ def create_app():
                         )
                         sync_log_output = gr.Textbox(
                             label="Sync Progress",
-                            lines=20,
-                            max_lines=30,
+                            lines=12,
+                            max_lines=18,
                             interactive=False,
                             elem_classes=["log-output"],
                             elem_id="sync-log",

classifier_agent.py

@@ -47,12 +47,6 @@ try:
     HAS_SPACES = True
 except ImportError:
     HAS_SPACES = False
-    class spaces:
-        @staticmethod
-        def GPU(func=None, **kwargs):
-            if func is None:
-                return lambda f: f
-            return func
 
 try:
     from openai import OpenAI
@@ -89,7 +83,7 @@ DEFINITIONS:
 INSTRUCTIONS:
 - Step 1: Read the email SUBJECT first. The subject is the STRONGEST signal and should be checked BEFORE analyzing the body.
   * Transaction subjects: "Debit Alert", "Transaction Alert", "Credit Alert", "Debit Card Transaction", "Fund Transfer".
-  * Promotion subjects: "Pre Approved", "Upgrade", "Rewards Points", "Membership", "Cashback Offer", "Exclusive Offer", "Special Offer", "Congratulations", "Limited Period", "wish list", "personal loan", "loan". If the subject contains any of these promotion keywords, classify as CREDIT_LOAN_PROMOTION or CREDIT_LIMIT_CARD_MANAGEMENT — do NOT classify as a transaction even if the body mentions amounts.
+  * Promotion subjects: "Pre Approved", "Upgrade", "Rewards Points", "Membership", "Cashback Offer", "Exclusive Offer", "Special Offer", "Congratulations", "Limited Period". If the subject contains any of these promotion keywords, classify as CREDIT_LOAN_PROMOTION or CREDIT_LIMIT_CARD_MANAGEMENT — do NOT classify as a transaction even if the body mentions amounts.
 - Step 2: Only if the subject is ambiguous, read the body. Note Indian financial terminology (INR, Rs., amount/-, Lakh, Cr).
 - Step 3: Determine the primary trigger. Pay strict attention to the direction of cash flow (Credited vs. Debited).
 - Step 4: CRITICAL: For FUNDS_CREDITED_ALERT or FUNDS_DEBITED_ALERT, the email MUST contain a specific account number (A/c XX1234) or card number (ending 5678) AND use explicit debit/credit language ("debited from", "credited to"). If the email mentions amounts alongside promotional language (reward points, upgrade, membership, cashback offer, discount, limit) without a specific card/account number being debited/credited, it is a PROMOTION, not a transaction.
@@ -167,16 +161,6 @@ Output:
   "amount_inr": null
 }}
 
-Subject: Your wish list calling? ₹50,000 will be credited to your account!
-Body: Dear Customer, get a Kotak Personal Loan of ₹50,000 instantly. The amount will be credited to your account in 3 seconds. Apply now!
-Output:
-{{
-  "thought_process": "Although the email mentions 'will be credited' and an amount, it is an offer for a personal loan ('wish list calling', 'Personal Loan'). It is a future marketing offer, not an actual completed transaction.",
-  "category": "CREDIT_LOAN_PROMOTION",
-  "bank_or_platform": "Kotak Mahindra Bank",
-  "amount_inr": 50000.00
-}}
-
 Subject: {subject}
 Body: {body}
 Output:"""
@@ -378,11 +362,36 @@ class ClassifierAgent:
                 base_url=LMSTUDIO_BASE_URL,
                 api_key="lm-studio",
             )
-            # Quick connectivity check
-            self._openai_client.models.list()
+            # Fetch currently loaded models
+            models = self._openai_client.models.list()
+            model_ids = [m.id for m in models.data]
+            
+            # Prioritize Qwen models first (as per guidelines)
+            matched_model = None
+            for m in model_ids:
+                if "qwen" in m.lower():
+                    matched_model = m
+                    break
+            
+            # If Qwen isn't found, find any text model that isn't a vision model
+            if not matched_model:
+                for m in model_ids:
+                    if "moondream" not in m.lower() and "vision" not in m.lower() and "vl" not in m.lower():
+                        matched_model = m
+                        break
+            
+            # Fallback to the first model if we couldn't find a clear text model, but prefer the matched one
+            if matched_model:
+                self._active_lmstudio_model = matched_model
+                log(f"  Model detected: {self._active_lmstudio_model}")
+            elif model_ids:
+                self._active_lmstudio_model = model_ids[0]
+                log(f"  Model detected (fallback): {self._active_lmstudio_model}")
+            else:
+                self._active_lmstudio_model = LMSTUDIO_MODEL
+                log(f"  Model: {LMSTUDIO_MODEL}")
             self._loaded = True
             log(f"[OK] Connected to LMStudio at {LMSTUDIO_BASE_URL}")
-            log(f"  Model: {LMSTUDIO_MODEL}")
         except Exception as e:
             log(f"[ERROR] LMStudio connection failed: {e}")
             log("[WARN] Falling back to rule-based classification")
@@ -469,23 +478,29 @@ class ClassifierAgent:
         """Generate text via LMStudio's OpenAI-compatible API."""
         if not self._openai_client:
             return ""
-        try:
-            response = self._openai_client.chat.completions.create(
-                model=LMSTUDIO_MODEL,
-                messages=[
-                    {"role": "system", "content": system_prompt},
-                    {"role": "user", "content": prompt},
-                ],
-                max_tokens=max_tokens,
-                temperature=QWEN_TEMPERATURE,
-                top_p=0.9,
-            )
-            return response.choices[0].message.content.strip()
-        except Exception as e:
-            logger.warning(f"LMStudio generation failed: {e}")
-            return ""
+            
+        for attempt in range(3):
+            try:
+                response = self._openai_client.chat.completions.create(
+                    model=getattr(self, "_active_lmstudio_model", LMSTUDIO_MODEL),
+                    messages=[
+                        {"role": "system", "content": system_prompt},
+                        {"role": "user", "content": prompt},
+                    ],
+                    max_tokens=max_tokens,
+                    temperature=QWEN_TEMPERATURE,
+                    top_p=0.9,
+                )
+                return response.choices[0].message.content.strip()
+            except Exception as e:
+                if attempt < 2:
+                    import time
+                    logger.debug(f"LMStudio generation failed (attempt {attempt+1}): {e}. Retrying...")
+                    time.sleep(3)
+                else:
+                    logger.warning(f"LMStudio generation failed after 3 attempts: {e}")
+        return ""
 
-    @spaces.GPU
     def _generate_transformers(self, prompt: str, max_tokens: int, system_prompt: str) -> str:
         """Generate text using loaded transformers model (ZeroGPU or CPU)."""
         if not self._loaded or self.model is None:
@@ -533,7 +548,7 @@ class ClassifierAgent:
             "FUNDS_CREDITED_ALERT": sum(1 for kw in ["credited", "received", "added", "refund"] if kw in text),
             "FUNDS_DEBITED_ALERT": sum(1 for kw in ["debited", "spent", "paid", "withdrawn"] if kw in text),
             "OTP_SECURITY_ALERT": sum(1 for kw in ["otp", "login", "password", "security"] if kw in text),
-            "CREDIT_LOAN_PROMOTION": sum(1 for kw in ["loan", "pre-approved", "pre approved", "cashback", "offer", "discount", "upgrade", "reward", "points", "membership", "wish list", "will be credited", "personal loan"] if kw in text),
+            "CREDIT_LOAN_PROMOTION": sum(1 for kw in ["loan", "pre-approved", "pre approved", "cashback", "offer", "discount", "upgrade", "reward", "points", "membership"] if kw in text),
             "REGULATORY_KYC_NOTICE": sum(1 for kw in ["kyc", "rbi", "pan", "aadhaar"] if kw in text),
             "ACCOUNT_STATEMENT_BILL": sum(1 for kw in ["statement", "due", "bill", "amb"] if kw in text),
             "CREDIT_SCORE_BUREAU_ALERT": sum(1 for kw in ["cibil", "experian", "score", "inquiry"] if kw in text),
@@ -1036,26 +1051,27 @@ By Category (sorted by spend):
         return fig
 
     def plot_daywise_trend(self, db: BankingDatabase) -> Optional[go.Figure]:
-        """Generate an interactive Plotly line chart of daywise spending with drill down."""
+        """Generate an interactive Plotly line chart of daily spending and credits."""
         summary = db.get_spending_summary()
         daywise = summary.get("daywise", [])
 
         if not daywise:
             return None
 
-        days = [d["day"] for d in daywise]
-        debits = [d["debits"] for d in daywise]
-        credits_ = [d["credits"] for d in daywise]
+        display_days = [m["day"] for m in daywise]
+
+        debits = [m["debits"] for m in daywise]
+        credits_ = [m["credits"] for m in daywise]
 
         fig = go.Figure()
 
         # Debits trace
         fig.add_trace(go.Scatter(
-            x=days, y=debits,
+            x=display_days, y=debits,
             mode="lines+markers",
             name="Debits",
-            line=dict(color=PLOT_ACCENT_COLORS[1], width=2),
-            marker=dict(size=4, color=PLOT_ACCENT_COLORS[1]),
+            line=dict(color=PLOT_ACCENT_COLORS[1], width=3),
+            marker=dict(size=8, color=PLOT_ACCENT_COLORS[1]),
             fill="tozeroy",
             fillcolor="rgba(255,101,132,0.1)",
             hovertext=[f"Debits: {format_inr(d)}" for d in debits],
@@ -1064,11 +1080,11 @@ By Category (sorted by spend):
 
         # Credits trace
         fig.add_trace(go.Scatter(
-            x=days, y=credits_,
+            x=display_days, y=credits_,
             mode="lines+markers",
             name="Credits",
-            line=dict(color=PLOT_ACCENT_COLORS[2], width=2),
-            marker=dict(size=4, symbol="square", color=PLOT_ACCENT_COLORS[2]),
+            line=dict(color=PLOT_ACCENT_COLORS[2], width=3),
+            marker=dict(size=8, symbol="square", color=PLOT_ACCENT_COLORS[2]),
             fill="tozeroy",
             fillcolor="rgba(67,232,216,0.1)",
             hovertext=[f"Credits: {format_inr(c)}" for c in credits_],
@@ -1076,25 +1092,26 @@ By Category (sorted by spend):
         ))
 
         fig.update_layout(**self._plotly_layout(
-            "Transaction Trend (Daywise)",
+            "Day-wise Transaction Trend",
             xaxis=dict(
                 gridcolor=PLOT_GRID_COLOR, 
                 gridwidth=0.5, 
                 title="Date", 
                 type="date",
+                rangeslider=dict(visible=True, bgcolor="#0f0f1a", bordercolor=PLOT_GRID_COLOR, borderwidth=1),
                 rangeselector=dict(
                     buttons=list([
-                        dict(count=1, label="1m", step="month", stepmode="backward"),
-                        dict(count=3, label="3m", step="month", stepmode="backward"),
-                        dict(count=6, label="6m", step="month", stepmode="backward"),
-                        dict(count=1, label="1y", step="year", stepmode="backward"),
-                        dict(step="all")
+                        dict(count=7, label="1W", step="day", stepmode="backward"),
+                        dict(count=1, label="1M", step="month", stepmode="backward"),
+                        dict(count=6, label="6M", step="month", stepmode="backward"),
+                        dict(count=1, label="YTD", step="year", stepmode="todate"),
+                        dict(count=1, label="1Y", step="year", stepmode="backward"),
+                        dict(step="all", label="All")
                     ]),
                     bgcolor="rgba(26,26,46,0.8)",
-                    activecolor=PLOT_ACCENT_COLORS[0],
-                    font=dict(color=PLOT_TEXT_COLOR)
-                ),
-                rangeslider=dict(visible=True, bgcolor="rgba(26,26,46,0.5)")
+                    font=dict(color=PLOT_TEXT_COLOR, size=11),
+                    activecolor="#3b3b5c",
+                )
             ),
             yaxis=dict(gridcolor=PLOT_GRID_COLOR, gridwidth=0.5, title="Amount (₹)", zeroline=False),
             legend=dict(
@@ -1104,7 +1121,7 @@ By Category (sorted by spend):
                 borderwidth=1,
             ),
             hovermode="x unified",
-            height=450,
+            height=400,
         ))
 
         return fig
@@ -1156,9 +1173,15 @@ By Category (sorted by spend):
                         "payment_mode": "Other",
                         "merchant": "Unknown"
                     }
+                # ONLY use amount_inr from initial classification if we didn't extract a valid one!
                 amount_inr = email_result.get("amount_inr")
-                if amount_inr is not None:
-                    txn["amount"] = amount_inr
+                if amount_inr is not None and str(amount_inr).lower() != "null":
+                    try:
+                        parsed_amount = float(str(amount_inr).replace(",", ""))
+                        if parsed_amount > 0 and not txn.get("amount"):
+                            txn["amount"] = parsed_amount
+                    except ValueError:
+                        pass
                 txn["transaction_type"] = "credit" if email_type == "FUNDS_CREDITED_ALERT" else "debit"
                 txn["email_id"] = eid
                 if not txn.get("transaction_date"):
@@ -1176,7 +1199,7 @@ By Category (sorted by spend):
                 # Progress logging per email
                 desc = f"Classified {results['classified']}/{total_emails} emails... (Last: {email_type})"
                 log(desc)
-                if progress_bar:
+                if progress_bar is not None:
                     progress_bar(results['classified'] / total_emails, desc=desc)
                 
                 if txn and txn.get("amount"):

config.py

@@ -66,7 +66,7 @@ IMAP_FOLDERS_OUTLOOK = ["INBOX", "Promotions", "Updates"]
 IMAP_FOLDERS_YAHOO = ["INBOX", "Bulk Mail"]
 
 # ─── Delta Sync ──────────────────────────────────────────────────────────────
-INITIAL_SYNC_DAYS = 7  # How far back on first sync (demo: 7 days)
+INITIAL_SYNC_DAYS = 3  # How far back on first sync (demo: 90 days)
 
 # ─── Indian Bank Domain Mapping ──────────────────────────────────────────────
 INDIAN_BANK_DOMAINS = {

email_agent.py

@@ -189,8 +189,15 @@ class EmailAgent:
                                     continue
 
                                 # Extract email content
-                                body_text = self._clean_text(msg.text or "")
+                                raw_text = msg.text or ""
                                 body_html = msg.html or ""
+                                if not raw_text.strip() and body_html:
+                                    try:
+                                        soup = BeautifulSoup(body_html, "html.parser")
+                                        raw_text = soup.get_text(separator=" ", strip=True)
+                                    except Exception:
+                                        pass
+                                body_text = self._clean_text(raw_text)
                                 msg_date = msg.date
                                 if msg_date:
                                     # Strip timezone info — SQLite strftime only

vision_agent.py

@@ -42,12 +42,6 @@ try:
     HAS_SPACES = True
 except ImportError:
     HAS_SPACES = False
-    class spaces:
-        @staticmethod
-        def GPU(func=None, **kwargs):
-            if func is None:
-                return lambda f: f
-            return func
 
 try:
     from openai import OpenAI
@@ -60,25 +54,20 @@ except ImportError:
 # VISION PROMPT TEMPLATES — Multi-Pass Strategy
 # ══════════════════════════════════════════════════════════════════════════════
 
-# OCR Extraction — get ALL text from the image (no classification)
-VISION_OCR_PROMPT = """Look at this banking promotional banner image carefully.
-Your task is to perform an accurate OCR (Optical Character Recognition) extraction.
-
-Extract ALL text you can see in the image exactly as written, including:
-1. Headlines and main promotional text
-2. Specific numbers: Percentages (%), flat discount amounts (Rs./₹), minimum spend criteria
-3. Bank names, card names, and merchant/app names (e.g., Swiggy, Amazon, Zomato)
-4. Validity dates (e.g., "Valid till 30 June", "Offer ends today")
-5. Promo codes or coupon codes
-6. Fine print and terms & conditions (T&C)
-
-Output the extracted text clearly, preserving the original formatting and hierarchy as much as possible. Do not summarize; just transcribe the text."""
+# OCR Extraction — get ALL text from the image using RECAT Strategy
+VISION_OCR_PROMPT = """**Role**: You are a highly accurate Optical Character Recognition (OCR) assistant.
+**Expertise**: You specialize in analyzing Indian banking and financial images, including transaction alerts, e-statements, and promotional banners.
+**Context**: You are analyzing an image extracted from a banking email. The image may contain critical transaction details (money sent/received) OR promotional offers. 
+**Action**: Extract ALL text you can see in the image exactly as written. Pay extremely close attention to:
+1. Transaction details: Amounts (Rs./₹/INR), "debited from" / "credited to", merchant names, and transaction IDs/references.
+2. Account details: Last 4 digits of cards or accounts.
+3. Promotional details: Percentages (%), flat discounts, promo codes.
+4. Dates and timestamps.
+**Tone**: Be purely objective, accurate, and precise. Do not summarize or interpret; simply transcribe the text clearly and preserve the visual hierarchy."""
 
 # LMStudio vision system prompt (OCR-focused)
-VISION_SYSTEM_PROMPT = """You are a highly accurate OCR assistant specializing in Indian banking and financial promotional banners.
-You can read text in English and Hindi from images.
-Pay extremely close attention to numbers, currencies (Rs, INR, ₹), percentages (%), and dates.
-Transcribe all visible text accurately without adding your own commentary or summarizing."""
+VISION_SYSTEM_PROMPT = """You are a highly accurate OCR assistant specializing in Indian banking.
+Extract all visible text accurately without adding commentary. Pay extremely close attention to transaction amounts, currency symbols (Rs, INR, ₹), merchant names, card numbers, percentages, and dates."""
 
 
 class VisionAgent:
@@ -349,7 +338,6 @@ class VisionAgent:
             logger.warning(f"LMStudio vision OCR failed: {e}")
             return ""
 
-    @spaces.GPU
     def _extract_moondream(self, image: Image.Image) -> str:
         """
         OCR text extraction using Moondream2 (transformers).