sphere

app.py

@@ -730,124 +730,6 @@ async def trial_prescription_activity(request: Request):
         'date_range': {'start': str(start_date), 'end': str(end_date)},
     }
 
-
-@app.post("/trial/cashflow/data")
-async def trial_cashflow_data(request: Request):
-    """
-    Returns income + expense breakdown grouped by category and merchant
-    for the cash flow bubble visualization.
-    """
-    from plaid_client import _load_raw_transactions
-    from datetime import date, timedelta
-    from collections import defaultdict
-    import re
-    
-    try:
-        fixture = _load_raw_transactions()
-        all_transactions = fixture['transactions']
-    except Exception as e:
-        print(f"Cashflow fixture error: {e}", flush=True)
-        return {"income_total": 0, "categories": []}
-    
-    # Filter to last 30 days
-    end_date = date.today()
-    start_date = end_date - timedelta(days=30)
-    
-    income_total = 0.0
-    category_data = defaultdict(lambda: {
-        "total": 0.0,
-        "merchants": defaultdict(lambda: {"total": 0.0, "count": 0, "transactions": []}),
-        "count": 0,
-    })
-    
-    for txn in all_transactions:
-        txn_date_val = txn.get('date')
-        if isinstance(txn_date_val, str):
-            txn_date = date.fromisoformat(txn_date_val)
-        else:
-            txn_date = txn_date_val
-        
-        if txn_date < start_date or txn_date > end_date:
-            continue
-        
-        amount = txn['amount']
-        name = txn.get('name', 'Unknown')
-        category = txn.get('personal_finance_category', {}).get('primary', 'OTHER')
-        
-        # Skip transfers
-        if category in ['TRANSFER_IN', 'TRANSFER_OUT']:
-            continue
-        
-        # Identify income (negative amounts or payroll patterns)
-        name_lower = name.lower()
-        is_income = amount < 0 or (
-            category == 'LOAN_PAYMENTS' and 
-            any(w in name_lower for w in ['payroll', 'salary', 'direct dep', 'employer', 'wages'])
-        )
-        
-        if is_income:
-            income_total += abs(amount)
-            continue
-        
-        # Skip other loan payments (mortgage will get its own treatment via recurring)
-        if category == 'LOAN_PAYMENTS':
-            continue
-        
-        # Group into category → merchant
-        normalized_merchant = re.sub(r'[0-9#]+', '', name).strip()
-        normalized_merchant = re.sub(r'\s+', ' ', normalized_merchant).upper() or name
-        
-        category_data[category]["total"] += amount
-        category_data[category]["count"] += 1
-        category_data[category]["merchants"][normalized_merchant]["total"] += amount
-        category_data[category]["merchants"][normalized_merchant]["count"] += 1
-        category_data[category]["merchants"][normalized_merchant]["transactions"].append({
-            "date": str(txn_date),
-            "amount": round(amount, 2),
-            "name": name,
-        })
-    
-    # Convert to sorted list
-    categories = []
-    for cat_name, cat_info in category_data.items():
-        # Build merchant list
-        merchants = []
-        for merchant_name, merchant_info in cat_info["merchants"].items():
-            merchants.append({
-                "name": merchant_name,
-                "display_name": merchant_info["transactions"][0]["name"] if merchant_info["transactions"] else merchant_name,
-                "total": round(merchant_info["total"], 2),
-                "count": merchant_info["count"],
-                "transactions": sorted(
-                    merchant_info["transactions"],
-                    key=lambda x: x["date"],
-                    reverse=True
-                )[:10],  # Cap at 10 most recent
-            })
-        merchants.sort(key=lambda x: -x["total"])
-        
-        # Human-readable category name
-        readable_name = cat_name.replace("_", " ").title()
-        
-        categories.append({
-            "name": readable_name,
-            "raw_name": cat_name,
-            "total": round(cat_info["total"], 2),
-            "count": cat_info["count"],
-            "merchants": merchants,
-        })
-    
-    categories.sort(key=lambda x: -x["total"])
-    
-    return {
-        "income_total": round(income_total, 2),
-        "categories": categories,
-        "date_range": {
-            "start": str(start_date),
-            "end": str(end_date),
-        }
-    }
-
 @app.post("/trial/cashflow/data")
 async def trial_cashflow_data(request: Request):
     """
@@ -994,20 +876,20 @@ async def trial_cashflow_opinion(request: Request):
         
         prompt = f"""The user is looking at their cash flow for the last 30 days.
 
-Income this month: ${income_total:.2f}
-Top spending categories:
-{cats_str}
-Total spent: ${total_spent:.2f}
-Remaining: ${remaining:.2f}
+    Income this month: ${income_total:.2f}
+    Top spending categories:
+    {cats_str}
+    Total spent: ${total_spent:.2f}
+    Remaining: ${remaining:.2f}
 
-Give a warm, doctor-patient style overview of the whole month. Cover:
-1. What the balance looks like (income vs spending)
-2. What's healthy or notable in the split
-3. Which category stands out (biggest, or most movable) — just observation, not judgment
+    Give a warm, doctor-patient style overview of the whole month. Cover:
+    1. What the balance looks like (income vs spending)
+    2. What's healthy or notable in the split
+    3. Which category stands out (biggest, or most movable) — just observation, not judgment
 
-Keep it under 90 words. Warm, calm, non-judgmental. No advice yet — just the "here's what I see" moment. Speak like a doctor reviewing a chart, not a financial advisor giving tips.
+    Keep it under 90 words. Warm, calm, non-judgmental. No advice yet — just the "here's what I see" moment. Speak like a doctor reviewing a chart, not a financial advisor giving tips.
 
-CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no lists."""
+    CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no lists."""
     
     elif level == "category":
         cat_name = body.get("category_name", "")
@@ -1021,20 +903,20 @@ CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no l
         
         prompt = f"""The user just zoomed into their "{cat_name}" spending.
 
-Category: {cat_name}
-Total spent: ${cat_total:.2f} ({cat_count} transactions)
-Percentage of monthly income: {pct_of_income:.0f}%
-Top merchants in this category:
-{merchants_str}
+        Category: {cat_name}
+        Total spent: ${cat_total:.2f} ({cat_count} transactions)
+        Percentage of monthly income: {pct_of_income:.0f}%
+        Top merchants in this category:
+        {merchants_str}
 
-Give a warm, doctor-patient style diagnosis of this category. Cover:
-1. Whether the amount is normal, high, or low for this category
-2. What the merchant breakdown shows (concentration vs spread)
-3. One small observation about the pattern — only if genuinely useful
+        Give a warm, doctor-patient style diagnosis of this category. Cover:
+        1. Whether the amount is normal, high, or low for this category
+        2. What the merchant breakdown shows (concentration vs spread)
+        3. One small observation about the pattern — only if genuinely useful
 
-Keep under 90 words. Warm, calm, non-judgmental. Speak like a doctor examining a specific symptom.
+        Keep under 90 words. Warm, calm, non-judgmental. Speak like a doctor examining a specific symptom.
 
-CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no lists."""
+        CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no lists."""
     
     elif level == "merchant":
         merchant_name = body.get("merchant_name", "")
@@ -1048,22 +930,22 @@ CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no l
         
         prompt = f"""The user just zoomed into a specific merchant: {merchant_name}
 
-Merchant: {merchant_name}
-Category: {category_name}
-Total spent here: ${merchant_total:.2f}
-Number of transactions: {merchant_count}
-Average per transaction: ${avg:.2f}
-Recent transactions:
-{recent_str}
+        Merchant: {merchant_name}
+        Category: {category_name}
+        Total spent here: ${merchant_total:.2f}
+        Number of transactions: {merchant_count}
+        Average per transaction: ${avg:.2f}
+        Recent transactions:
+        {recent_str}
 
-Give a warm, doctor-patient style opinion on this specific merchant. Cover:
-1. What the pattern looks like (frequency, size)
-2. Whether it's a habit worth noticing (recurring visits, high per-transaction cost)
-3. Reassurance if it's fine, or a gentle prompt if there's something worth looking at
+        Give a warm, doctor-patient style opinion on this specific merchant. Cover:
+        1. What the pattern looks like (frequency, size)
+        2. Whether it's a habit worth noticing (recurring visits, high per-transaction cost)
+        3. Reassurance if it's fine, or a gentle prompt if there's something worth looking at
 
-Keep under 80 words. Warm, calm, non-judgmental, specific to this merchant.
+        Keep under 80 words. Warm, calm, non-judgmental, specific to this merchant.
 
-CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no lists."""
+        CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no lists."""
     else:
         return {"error": "Invalid level"}
     
@@ -1072,4 +954,233 @@ CRITICAL: Respond with prose only. No headers, no bullets, no chart syntax, no l
             yield f"data: {json.dumps({'chunk': token})}\n\n"
         yield "data: [DONE]\n\n"
     
-    return StreamingResponse(generate(), media_type="text/event-stream")
+    return StreamingResponse(generate(), media_type="text/event-stream")
+
+
+
+@app.post("/trial/yearsphere/data")
+async def trial_yearsphere_data(request: Request):
+    """
+    Returns 12 months of data for the Year Sphere.
+    Consumes get_recurring_from_fixtures() — same source as the working calendar.
+    Recurring items are placed on the days they historically hit (past) or are projected to hit (future).
+    """
+    from plaid_client import _load_raw_transactions, get_recurring_from_fixtures
+    from datetime import date
+    from collections import defaultdict
+    from calendar import monthrange
+
+    try:
+        fixture = _load_raw_transactions()
+        all_transactions = fixture['transactions']
+    except Exception as e:
+        print(f"YearSphere fixture error: {e}", flush=True)
+        return {"months": [], "current_month_index": 0}
+
+    # Pull the same recurring data the working calendar uses
+    try:
+        recurring_data = get_recurring_from_fixtures()
+    except Exception as e:
+        print(f"YearSphere recurring fetch error: {e}", flush=True)
+        recurring_data = {"recurring_expenses": [], "recurring_income": [], "projected_events": []}
+
+    recurring_expenses = recurring_data.get("recurring_expenses", [])
+    recurring_income = recurring_data.get("recurring_income", [])
+    projected_events = recurring_data.get("projected_events", [])
+
+    today = date.today()
+
+    # Build the month window: 8 months back through 3 months forward
+    window = []
+    for offset in range(-8, 4):
+        target_month = today.month + offset
+        target_year = today.year
+        while target_month < 1:
+            target_month += 12
+            target_year -= 1
+        while target_month > 12:
+            target_month -= 12
+            target_year += 1
+        window.append((target_year, target_month))
+
+    # --- Build a per-month index of recurring occurrences (both historical + projected) ---
+    # Key: (year, month) -> list of {name, amount, date, is_income}
+    recurring_by_month: dict = defaultdict(list)
+    # Track which (year, month, normalized_name) we've seen so we don't double-list
+    seen_month_names: set = set()
+
+    def add_recurring_occurrence(year: int, month: int, day: int, name: str, amount: float, is_income: bool):
+        # Guard against duplicate entries for the same recurring item in the same month
+        # (e.g. biweekly items hit twice — those are legit, don't dedupe those; dedupe monthly ones)
+        dedupe_key = (year, month, name.upper().strip(), day)
+        if dedupe_key in seen_month_names:
+            return
+        seen_month_names.add(dedupe_key)
+        recurring_by_month[(year, month)].append({
+            "name": name[:30],
+            "amount": round(abs(amount), 2),
+            "date": f"{year:04d}-{month:02d}-{day:02d}",
+            "is_income": is_income,
+        })
+
+    # Add historical occurrences from the recurring_expenses / recurring_income "history" arrays
+    for item in recurring_expenses:
+        for hist in item.get("history", []):
+            hist_date = date.fromisoformat(hist["date"])
+            add_recurring_occurrence(
+                hist_date.year, hist_date.month, hist_date.day,
+                item["merchant"], hist["amount"], is_income=False,
+            )
+    for item in recurring_income:
+        for hist in item.get("history", []):
+            hist_date = date.fromisoformat(hist["date"])
+            add_recurring_occurrence(
+                hist_date.year, hist_date.month, hist_date.day,
+                item["merchant"], hist["amount"], is_income=True,
+            )
+
+    # Add projected future events
+    for ev in projected_events:
+        ev_date = date.fromisoformat(ev["date"])
+        if ev_date <= today:
+            continue  # Only add projections for future dates
+        add_recurring_occurrence(
+            ev_date.year, ev_date.month, ev_date.day,
+            ev.get("merchant", "Unknown"), ev.get("amount", 0.0),
+            is_income=ev.get("is_income", False),
+        )
+
+    # --- Build per-month output ---
+    months_out = []
+    for (year, month) in window:
+        month_start = date(year, month, 1)
+        _, last_day = monthrange(year, month)
+        month_end = date(year, month, last_day)
+
+        is_past = month_end < today
+        is_current = month_start <= today <= month_end
+        is_future = month_start > today
+
+        total_spent = 0.0
+        total_income = 0.0
+        daily_spending = defaultdict(float)
+        daily_transactions = defaultdict(list)
+
+        # Real transactions from fixture (only for past + current)
+        if not is_future:
+            for txn in all_transactions:
+                txn_date_val = txn.get('date')
+                if isinstance(txn_date_val, str):
+                    txn_date = date.fromisoformat(txn_date_val)
+                else:
+                    txn_date = txn_date_val
+
+                if txn_date < month_start or txn_date > month_end:
+                    continue
+
+                amount = txn['amount']
+                name = txn.get('name', 'Unknown')
+                category = txn.get('personal_finance_category', {}).get('primary', 'OTHER')
+                name_lower = name.lower()
+
+                if category in ['TRANSFER_IN', 'TRANSFER_OUT']:
+                    continue
+
+                is_income = amount < 0 or (
+                    category == 'LOAN_PAYMENTS' and
+                    any(w in name_lower for w in ['payroll', 'salary', 'direct dep', 'employer', 'wages'])
+                )
+
+                daily_transactions[str(txn_date)].append({
+                    "name": name[:30],
+                    "amount": round(abs(amount), 2),
+                    "is_income": is_income,
+                    "category": category,
+                })
+
+                if is_income:
+                    total_income += abs(amount)
+                else:
+                    total_spent += amount
+                    daily_spending[str(txn_date)] += amount
+
+        # Overlay recurring occurrences (historical for past/current, projected for future)
+        # These are added on top of raw transactions so future months get populated,
+        # and past months get any recurring occurrences that the raw fixture might miss.
+        for rec in recurring_by_month.get((year, month), []):
+            rec_date_str = rec["date"]
+            already_in_day = any(
+                t["name"].upper().strip() == rec["name"].upper().strip()
+                for t in daily_transactions.get(rec_date_str, [])
+            )
+            if not already_in_day:
+                daily_transactions[rec_date_str].append({
+                    "name": rec["name"],
+                    "amount": rec["amount"],
+                    "is_income": rec["is_income"],
+                    "category": "RECURRING",
+                })
+                if is_future:
+                    if rec["is_income"]:
+                        total_income += rec["amount"]
+                    else:
+                        total_spent += rec["amount"]
+                        daily_spending[rec_date_str] += rec["amount"]
+
+        # For the recurring lists at the bottom of the zoomed view, use the recurring_by_month entries
+        month_recurring = recurring_by_month.get((year, month), [])
+        recurring_income_items = [
+            {"name": r["name"], "amount": r["amount"], "date": r["date"]}
+            for r in month_recurring if r["is_income"]
+        ]
+        recurring_expense_items = [
+            {"name": r["name"], "amount": r["amount"], "date": r["date"]}
+            for r in month_recurring if not r["is_income"]
+        ]
+
+        # Future months: total_spent stays 0 so the sphere stays flat
+        # (recurring projections were added above but we reset total_spent to 0 for the elevation math)
+        if is_future:
+            total_spent = 0.0
+
+        # Build daily_data
+        days_in_month = last_day
+        max_day_spending = max(daily_spending.values()) if daily_spending else 1
+        daily_data = []
+        for day_num in range(1, days_in_month + 1):
+            day_str = str(date(year, month, day_num))
+            spent = daily_spending.get(day_str, 0.0)
+            intensity = spent / max_day_spending if max_day_spending > 0 else 0
+            daily_data.append({
+                "day": day_num,
+                "amount": round(spent, 2),
+                "intensity": round(intensity, 2),
+                "transactions": daily_transactions.get(day_str, []),
+            })
+
+        first_weekday = month_start.weekday()
+        first_weekday = (first_weekday + 1) % 7  # Sun=0
+
+        months_out.append({
+            "year": year,
+            "month": month,
+            "month_name": month_start.strftime("%b").upper(),
+            "month_name_full": month_start.strftime("%B"),
+            "total_spent": round(total_spent, 2),
+            "total_income": round(total_income, 2),
+            "is_past": is_past,
+            "is_current": is_current,
+            "is_future": is_future,
+            "daily_data": daily_data,
+            "first_weekday": first_weekday,
+            "days_in_month": days_in_month,
+            "recurring_income": sorted(recurring_income_items, key=lambda x: -x["amount"])[:5],
+            "recurring_expenses": sorted(recurring_expense_items, key=lambda x: -x["amount"])[:10],
+        })
+
+    current_idx = next((i for i, m in enumerate(months_out) if m["is_current"]), 8)
+
+    return {
+        "months": months_out,
+        "current_month_index": current_idx,
+    }