feat(insights): Add weekly financial summary feature

[qwldcl-del]

Summary

This PR adds a new /insights/weekly-summary endpoint that generates weekly financial digests with trends and insights.

Changes

New Endpoint: /insights/weekly-summary

• Query Parameters:
  • week (optional): Week offset (0 = current week, -1 = last week, etc.)
  • X-Gemini-Api-Key (optional header): Use custom Gemini API key
  • X-Insight-Persona (optional header): Custom AI persona

Features

• Week-over-week comparison: Compare spending between current and previous week
• Category breakdown: Top spending categories for the week
• Daily spending pattern: Daily spending for each day of the week
• Upcoming bills: Bills due in the next 7 days
• Trend analysis: Determine if spending is increasing, decreasing, or stable
• AI-powered insights: Using Gemini AI for intelligent insights (with fallback to heuristic)
• Actionable tips: Personalized recommendations based on spending patterns

Response Example

{
  "week_start": "2025-08-11",
  "week_end": "2025-08-17",
  "trend": "increasing",
  "method": "heuristic",
  "analytics": {
    "week_over_week_change_pct": 15.5,
    "current_week_expenses": 350.0,
    "previous_week_expenses": 303.0,
    "current_week_income": 500.0,
    "net_flow": 150.0,
    "top_categories": [...],
    "daily_spending": {...}
  },
  "upcoming_bills": [...],
  "insights": [...],
  "tips": [...]
}

Testing

• Added 7 comprehensive tests in test_insights.py:
  • test_weekly_summary_returns_weekly_data
  • test_weekly_summary_analytics_structure
  • test_weekly_summary_with_bills
  • test_weekly_summary_with_week_offset
  • test_weekly_summary_prefers_user_gemini_key
  • test_weekly_summary_falls_back_when_gemini_fails
  • test_weekly_summary_with_income

Documentation

• Updated README.md with new endpoint
• Updated openapi.yaml with full API specification

Implementation Details

• Built on existing FinMind architecture
• Uses same patterns as monthly budget suggestion
• Graceful fallback from Gemini AI to heuristic when unavailable
• Production-ready code with proper error handling

Closes: Smart digest with weekly financial summary