finance-intelligence-mcp 0.1.0__py3-none-any.whl

analytics.py

@@ -0,0 +1,184 @@
+import os
+from datetime import date as pydate
+import matplotlib
+matplotlib.use('Agg')  # Configure headless non-interactive backend
+import matplotlib.pyplot as plt
+from budget import validate_category_and_subcategory
+
+async def expense_summary_impl(
+    conn,
+    user_id: int,
+    period: str = None,
+    group_by: str = None,
+    category: str = None,
+    subcategory: str = None,
+    start_date: str = None,
+    end_date: str = None
+) -> dict:
+    # 1. Parameter Validations
+    if not period and not group_by:
+        return {
+            "status": "error",
+            "message": "At least one grouping dimension ('period' or 'group_by') must be specified."
+        }
+        
+    if period and period not in ["weekly", "monthly", "quarterly", "yearly"]:
+        return {
+            "status": "error",
+            "message": "Invalid period. Allowed values: 'weekly', 'monthly', 'quarterly', 'yearly'."
+        }
+        
+    if group_by and group_by not in ["category", "subcategory"]:
+        return {
+            "status": "error",
+            "message": "Invalid group_by. Allowed values: 'category', 'subcategory'."
+        }
+
+    # 2. Date validations
+    try:
+        parsed_start = pydate.fromisoformat(start_date) if start_date else None
+        parsed_end = pydate.fromisoformat(end_date) if end_date else None
+        if parsed_start and parsed_end and parsed_start > parsed_end:
+            raise ValueError(f"start_date '{start_date}' cannot be after end_date '{end_date}'.")
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Date validation failed: {str(e)}"
+        }
+
+    # 3. Category / Subcategory normalization
+    matched_cat = None
+    matched_sub = None
+    if category:
+        try:
+            matched_cat, matched_sub = validate_category_and_subcategory(category, subcategory)
+        except ValueError as e:
+            return {
+                "status": "error",
+                "message": f"Validation failed: {str(e)}"
+            }
+
+    # 4. Build dynamic SQL
+    select_fields = []
+    group_fields = []
+    
+    if period:
+        trunc_map = {
+            "weekly": "week",
+            "monthly": "month",
+            "quarterly": "quarter",
+            "yearly": "year"
+        }
+        select_fields.append(f"DATE_TRUNC('{trunc_map[period]}', date)::date AS period_bucket")
+        group_fields.append("period_bucket")
+        
+    if group_by:
+        select_fields.append(f"{group_by} AS group_bucket")
+        group_fields.append("group_bucket")
+        
+    query = (
+        f"SELECT {', '.join(select_fields)}, SUM(amount) as total_amount, COUNT(id) as transaction_count "
+        f"FROM expenses WHERE user_id = $1"
+    )
+    params = [user_id]
+    param_idx = 2
+    
+    if parsed_start:
+        query += f" AND date >= ${param_idx}"
+        params.append(parsed_start)
+        param_idx += 1
+    if parsed_end:
+        query += f" AND date <= ${param_idx}"
+        params.append(parsed_end)
+        param_idx += 1
+    if matched_cat:
+        query += f" AND category = ${param_idx}"
+        params.append(matched_cat)
+        param_idx += 1
+    if matched_sub:
+        query += f" AND subcategory = ${param_idx}"
+        params.append(matched_sub)
+        param_idx += 1
+        
+    query += f" GROUP BY {', '.join(group_fields)} ORDER BY {group_fields[0]} ASC"
+    if len(group_fields) > 1:
+        query += f", {group_fields[1]} ASC"
+        
+    rows = await conn.fetch(query, *params)
+    if not rows:
+        return {
+            "status": "ok",
+            "message": "No expenses found matching the criteria.",
+            "data": []
+        }
+
+    # 5. Generate Matplotlib Chart
+    charts_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "charts")
+    os.makedirs(charts_dir, exist_ok=True)
+    chart_filename = "expense_analysis.png"
+    chart_path = os.path.join(charts_dir, chart_filename)
+    
+    fig, ax = plt.subplots(figsize=(10, 6))
+    
+    # Render different chart configurations
+    if period and not group_by:
+        # Time-series trend (Bar chart)
+        x_vals = [str(r["period_bucket"]) for r in rows]
+        y_vals = [float(r["total_amount"]) for r in rows]
+        ax.bar(x_vals, y_vals, color="#3f51b5", width=0.6)
+        ax.set_ylabel("Spent Amount ($)")
+        ax.set_xlabel("Period")
+        ax.set_title(f"Expense Trend over Time ({period.capitalize()})")
+        plt.xticks(rotation=45)
+        
+    elif group_by and not period:
+        # Category breakdown (Bar chart)
+        x_vals = [str(r["group_bucket"]) for r in rows]
+        y_vals = [float(r["total_amount"]) for r in rows]
+        ax.bar(x_vals, y_vals, color="#e91e63", width=0.6)
+        ax.set_ylabel("Spent Amount ($)")
+        ax.set_xlabel(group_by.capitalize())
+        ax.set_title(f"Expenses Grouped by {group_by.capitalize()}")
+        plt.xticks(rotation=45)
+        
+    elif period and group_by:
+        # Both (Stacked bar chart)
+        periods = sorted(list(set(str(r["period_bucket"]) for r in rows)))
+        groups = sorted(list(set(str(r["group_bucket"]) for r in rows)))
+        
+        # Build mapping matrices
+        data_matrix = {g: [0.0] * len(periods) for g in groups}
+        period_idx_map = {p: i for i, p in enumerate(periods)}
+        
+        for r in rows:
+            p_val = str(r["period_bucket"])
+            g_val = str(r["group_bucket"])
+            amt = float(r["total_amount"])
+            data_matrix[g_val][period_idx_map[p_val]] = amt
+            
+        bottoms = [0.0] * len(periods)
+        for g_val in groups:
+            y_vals = data_matrix[g_val]
+            ax.bar(periods, y_vals, bottom=bottoms, label=g_val)
+            bottoms = [b + y for b, y in zip(bottoms, y_vals)]
+            
+        ax.set_ylabel("Spent Amount ($)")
+        ax.set_xlabel("Period")
+        ax.set_title(f"Expenses Trend Grouped by {group_by.capitalize()}")
+        ax.legend(title=group_by.capitalize())
+        plt.xticks(rotation=45)
+
+    ax.grid(axis='y', linestyle='--', alpha=0.7)
+    plt.tight_layout()
+    plt.savefig(chart_path, dpi=150)
+    plt.close(fig)
+    
+    chart_url = f"file:///{chart_path.replace(os.sep, '/')}"
+    
+    return {
+        "status": "ok",
+        "chart_path": chart_path,
+        "chart_url": chart_url,
+        "message": f"Expense analytics trend chart generated successfully:\n\n![Expense Analytics Chart]({chart_url})",
+        "data": [dict(r) for r in rows]
+    }

budget.py

@@ -0,0 +1,558 @@
+import os
+import json
+from datetime import date as pydate
+
+CATEGORIES_PATH = os.path.join(os.path.dirname(__file__), "categories.json")
+
+def validate_category_and_subcategory(category: str = None, subcategory: str = None):
+    if category is None:
+        return None, None
+    
+    if not os.path.exists(CATEGORIES_PATH):
+        valid_categories = ["Food", "Travel", "Utilities", "Entertainment", "Health", "Other"]
+        matched_cat = next((c for c in valid_categories if c.lower() == category.lower()), None)
+        if matched_cat is None:
+            raise ValueError(f"Category '{category}' is invalid. Allowed: {valid_categories}")
+        return matched_cat, None
+
+    with open(CATEGORIES_PATH, 'r', encoding="utf-8") as f:
+        data = json.load(f)
+        
+    categories_lower = {k.lower(): k for k in data.keys()}
+    category_lower = category.lower()
+    
+    if category_lower not in categories_lower:
+        raise ValueError(f"Category '{category}' is invalid.")
+        
+    matched_category_key = categories_lower[category_lower]
+    
+    matched_subcategory = None
+    if subcategory:
+        subcats_lower = {s.lower(): s for s in data[matched_category_key]}
+        subcat_lower = subcategory.lower()
+        if subcat_lower not in subcats_lower:
+            raise ValueError(f"Subcategory '{subcategory}' is invalid for category '{matched_category_key}'.")
+        matched_subcategory = subcats_lower[subcat_lower]
+        
+    return matched_category_key, matched_subcategory
+
+async def create_budget_impl(
+    conn,
+    user_id: int,
+    budget_type: str = None,
+    amount: float = None,
+    period: str = None,
+    start_date: str = None,
+    end_date: str = None,
+    category: str = None,
+    subcategory: str = None,
+    budgets: list[dict] = None
+) -> dict:
+    budget_list = []
+    if budgets is not None:
+        budget_list = budgets
+    else:
+        if budget_type is None or amount is None or period is None or start_date is None or end_date is None:
+            return {
+                "status": "error",
+                "message": (
+                    "Either 'budgets' list must be provided, or all single budget parameters "
+                    "(budget_type, amount, period, start_date, end_date) must be provided."
+                )
+            }
+        budget_list = [{
+            "budget_type": budget_type,
+            "amount": amount,
+            "period": period,
+            "start_date": start_date,
+            "end_date": end_date,
+            "category": category,
+            "subcategory": subcategory
+        }]
+        
+    if not budget_list:
+        return {
+            "status": "error",
+            "message": "No budgets specified to create."
+        }
+        
+    validated_budgets = []
+    try:
+        for b in budget_list:
+            b_type = b.get("budget_type")
+            b_amount = b.get("amount")
+            b_period = b.get("period")
+            b_start = b.get("start_date")
+            b_end = b.get("end_date")
+            b_cat = b.get("category")
+            b_subcat = b.get("subcategory")
+            
+            if not all([b_type, b_amount is not None, b_period, b_start, b_end]):
+                raise ValueError("Missing required fields in budget details.")
+                
+            d_start = pydate.fromisoformat(b_start)
+            d_end = pydate.fromisoformat(b_end)
+            if d_start > d_end:
+                raise ValueError(f"start_date '{b_start}' cannot be after end_date '{b_end}'.")
+                
+            matched_cat, matched_sub = validate_category_and_subcategory(b_cat, b_subcat)
+            
+            if b_type == "overall":
+                if b_cat is not None or b_subcat is not None:
+                    raise ValueError("Overall budget cannot have category or subcategory set.")
+            elif b_type == "category":
+                if b_cat is None:
+                    raise ValueError("Category budget must specify a category.")
+                if b_subcat is not None:
+                    raise ValueError("Category budget cannot specify a subcategory.")
+            elif b_type == "subcategory":
+                if b_cat is None or b_subcat is None:
+                    raise ValueError("Subcategory budget must specify both category and subcategory.")
+                    
+            validated_budgets.append({
+                "budget_type": b_type,
+                "amount": float(b_amount),
+                "period": b_period,
+                "start_date": d_start,
+                "end_date": d_end,
+                "category": matched_cat,
+                "subcategory": matched_sub
+            })
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Validation failed: {str(e)}"
+        }
+        
+    created_ids = []
+    async with conn.transaction():
+        for vb in validated_budgets:
+            bid = await conn.fetchval(
+                """
+                INSERT INTO budgets (user_id, budget_type, category, subcategory, amount, period, start_date, end_date)
+                VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+                RETURNING id
+                """,
+                user_id, vb["budget_type"], vb["category"], vb["subcategory"], vb["amount"], vb["period"], vb["start_date"], vb["end_date"]
+            )
+            created_ids.append(bid)
+            
+    return {
+        "status": "ok",
+        "created_count": len(created_ids),
+        "created_ids": created_ids
+    }
+
+async def list_budgets_impl(
+    conn,
+    user_id: int,
+    budget_type: str = None,
+    category: str = None,
+    subcategory: str = None,
+    period: str = None
+) -> list:
+    matched_cat = None
+    matched_sub = None
+    
+    if category:
+        try:
+            matched_cat, matched_sub = validate_category_and_subcategory(category, subcategory)
+        except ValueError:
+            return []
+
+    query = (
+        "SELECT id, budget_type, category, subcategory, amount, period, "
+        "start_date::text, end_date::text FROM budgets WHERE user_id = $1"
+    )
+    params = [user_id]
+    param_idx = 2
+    
+    if budget_type:
+        query += f" AND budget_type = ${param_idx}"
+        params.append(budget_type)
+        param_idx += 1
+        
+    if matched_cat:
+        query += f" AND category = ${param_idx}"
+        params.append(matched_cat)
+        param_idx += 1
+        
+    if matched_sub:
+        query += f" AND subcategory = ${param_idx}"
+        params.append(matched_sub)
+        param_idx += 1
+        
+    if period:
+        query += f" AND period = ${param_idx}"
+        params.append(period)
+        param_idx += 1
+        
+    query += " ORDER BY id ASC"
+    
+    rows = await conn.fetch(query, *params)
+    return [dict(row) for row in rows]
+
+async def update_budgets_impl(
+    conn,
+    user_id: int,
+    # Filters
+    budget_ids: list[int] = None,
+    filter_budget_type: str = None,
+    filter_category: str = None,
+    filter_subcategory: str = None,
+    filter_period: str = None,
+    # Update Fields
+    budget_type: str = None,
+    amount: float = None,
+    period: str = None,
+    start_date: str = None,
+    end_date: str = None,
+    category: str = None,
+    subcategory: str = None
+) -> dict:
+    # 1. Parameter Validation
+    if not any([budget_ids, filter_budget_type, filter_category, filter_subcategory, filter_period]):
+        return {
+            "status": "error",
+            "message": "At least one target filter must be specified."
+        }
+        
+    if not any([budget_type is not None, amount is not None, period is not None, 
+                start_date is not None, end_date is not None, category is not None, subcategory is not None]):
+        return {
+            "status": "error",
+            "message": "At least one budget field must be specified to update."
+        }
+
+    # 2. Category & Subcategory normalizations for updates
+    matched_update_cat = None
+    matched_update_sub = None
+    if category is not None or subcategory is not None:
+        try:
+            if subcategory is not None and category is None:
+                raise ValueError("Cannot update subcategory without specifying the category.")
+            matched_update_cat, matched_update_sub = validate_category_and_subcategory(category, subcategory)
+        except ValueError as e:
+            return {
+                "status": "error",
+                "message": f"Validation failed: {str(e)}"
+            }
+
+    # 3. Filter normalizations
+    matched_filter_cat = None
+    matched_filter_sub = None
+    if filter_category:
+        try:
+            matched_filter_cat, matched_filter_sub = validate_category_and_subcategory(filter_category, filter_subcategory)
+        except ValueError:
+            # If the filter category is invalid, there won't be any matching budgets in the DB
+            return {
+                "status": "ok",
+                "updated_count": 0,
+                "updated_ids": []
+            }
+
+    # 4. Date validation
+    try:
+        parsed_start = pydate.fromisoformat(start_date) if start_date else None
+        parsed_end = pydate.fromisoformat(end_date) if end_date else None
+        if parsed_start and parsed_end and parsed_start > parsed_end:
+            raise ValueError(f"start_date '{start_date}' cannot be after end_date '{end_date}'.")
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Date validation failed: {str(e)}"
+        }
+
+    # 5. Build dynamic SQL
+    set_clauses = []
+    params = []
+    param_idx = 1
+
+    # SET parameters
+    if budget_type is not None:
+        set_clauses.append(f"budget_type = ${param_idx}")
+        params.append(budget_type)
+        param_idx += 1
+    if amount is not None:
+        set_clauses.append(f"amount = ${param_idx}")
+        params.append(float(amount))
+        param_idx += 1
+    if period is not None:
+        set_clauses.append(f"period = ${param_idx}")
+        params.append(period)
+        param_idx += 1
+    if start_date is not None:
+        set_clauses.append(f"start_date = ${param_idx}")
+        params.append(parsed_start)
+        param_idx += 1
+    if end_date is not None:
+        set_clauses.append(f"end_date = ${param_idx}")
+        params.append(parsed_end)
+        param_idx += 1
+    if category is not None:
+        set_clauses.append(f"category = ${param_idx}")
+        params.append(matched_update_cat)
+        param_idx += 1
+    if subcategory is not None:
+        set_clauses.append(f"subcategory = ${param_idx}")
+        params.append(matched_update_sub)
+        param_idx += 1
+        
+    set_clauses.append("updated_at = CURRENT_TIMESTAMP")
+
+    # WHERE parameters (user restriction is always present)
+    where_clauses = [f"user_id = ${param_idx}"]
+    params.append(user_id)
+    param_idx += 1
+
+    if budget_ids:
+        where_clauses.append(f"id = ANY(${param_idx}::integer[])")
+        params.append(budget_ids)
+        param_idx += 1
+    if filter_budget_type:
+        where_clauses.append(f"budget_type = ${param_idx}")
+        params.append(filter_budget_type)
+        param_idx += 1
+    if matched_filter_cat:
+        where_clauses.append(f"category = ${param_idx}")
+        params.append(matched_filter_cat)
+        param_idx += 1
+    if matched_filter_sub:
+        where_clauses.append(f"subcategory = ${param_idx}")
+        params.append(matched_filter_sub)
+        param_idx += 1
+    if filter_period:
+        where_clauses.append(f"period = ${param_idx}")
+        params.append(filter_period)
+        param_idx += 1
+
+    query = f"UPDATE budgets SET {', '.join(set_clauses)} WHERE {' AND '.join(where_clauses)} RETURNING id"
+
+    try:
+        rows = await conn.fetch(query, *params)
+        updated_ids = [row["id"] for row in rows]
+        return {
+            "status": "ok",
+            "updated_count": len(updated_ids),
+            "updated_ids": updated_ids
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Update failed: {str(e)}"
+        }
+
+async def delete_budgets_impl(
+    conn,
+    user_id: int,
+    budget_ids: list[int] = None,
+    start_date: str = None,
+    end_date: str = None,
+    budget_type: str = None,
+    category: str = None,
+    subcategory: str = None,
+    period: str = None
+) -> dict:
+    # 1. Safety verification
+    if not any([budget_ids, start_date, end_date, budget_type, category, subcategory, period]):
+        return {
+            "status": "error",
+            "message": "At least one target filter must be specified to delete budgets."
+        }
+
+    # 2. Casing normalization for category/subcategory filters
+    matched_filter_cat = None
+    matched_filter_sub = None
+    if category:
+        try:
+            matched_filter_cat, matched_filter_sub = validate_category_and_subcategory(category, subcategory)
+        except ValueError:
+            # If the filter category is invalid, there won't be any matching budgets in the DB to delete
+            return {
+                "status": "ok",
+                "deleted_count": 0,
+                "deleted_ids": []
+            }
+
+    # 3. Date validation
+    try:
+        parsed_start = pydate.fromisoformat(start_date) if start_date else None
+        parsed_end = pydate.fromisoformat(end_date) if end_date else None
+        if parsed_start and parsed_end and parsed_start > parsed_end:
+            raise ValueError(f"start_date '{start_date}' cannot be after end_date '{end_date}'.")
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Date validation failed: {str(e)}"
+        }
+
+    # 4. Build dynamic query
+    where_clauses = ["user_id = $1"]
+    params = [user_id]
+    param_idx = 2
+
+    if budget_ids:
+        where_clauses.append(f"id = ANY(${param_idx}::integer[])")
+        params.append(budget_ids)
+        param_idx += 1
+    if parsed_start:
+        where_clauses.append(f"start_date >= ${param_idx}")
+        params.append(parsed_start)
+        param_idx += 1
+    if parsed_end:
+        where_clauses.append(f"end_date <= ${param_idx}")
+        params.append(parsed_end)
+        param_idx += 1
+    if budget_type:
+        where_clauses.append(f"budget_type = ${param_idx}")
+        params.append(budget_type)
+        param_idx += 1
+    if matched_filter_cat:
+        where_clauses.append(f"category = ${param_idx}")
+        params.append(matched_filter_cat)
+        param_idx += 1
+    if matched_filter_sub:
+        where_clauses.append(f"subcategory = ${param_idx}")
+        params.append(matched_filter_sub)
+        param_idx += 1
+    if period:
+        where_clauses.append(f"period = ${param_idx}")
+        params.append(period)
+        param_idx += 1
+
+    query = f"DELETE FROM budgets WHERE {' AND '.join(where_clauses)} RETURNING id"
+
+    try:
+        rows = await conn.fetch(query, *params)
+        deleted_ids = [row["id"] for row in rows]
+        return {
+            "status": "ok",
+            "deleted_count": len(deleted_ids),
+            "deleted_ids": deleted_ids
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Deletion failed: {str(e)}"
+        }
+
+async def compare_budget_vs_expenses_impl(
+    conn,
+    user_id: int,
+    reference_date: str = None,
+    budget_type: str = None,
+    category: str = None,
+    subcategory: str = None,
+    period: str = None
+) -> dict:
+    # 1. Resolve reference date
+    try:
+        ref_date = pydate.fromisoformat(reference_date) if reference_date else pydate.today()
+    except Exception as e:
+        return {
+            "status": "error",
+            "message": f"Invalid reference_date format: {str(e)}"
+        }
+
+    # 2. Casing normalization for category/subcategory filters
+    matched_filter_cat = None
+    matched_filter_sub = None
+    if category:
+        try:
+            matched_filter_cat, matched_filter_sub = validate_category_and_subcategory(category, subcategory)
+        except ValueError:
+            return {
+                "status": "ok",
+                "reference_date": ref_date.isoformat(),
+                "budgets": []
+            }
+
+    # 3. Retrieve matching active budgets
+    query = (
+        "SELECT id, budget_type, category, subcategory, amount, period, "
+        "start_date::text, end_date::text FROM budgets "
+        "WHERE user_id = $1 AND start_date <= $2 AND end_date >= $2"
+    )
+    params = [user_id, ref_date]
+    param_idx = 3
+
+    if budget_type:
+        query += f" AND budget_type = ${param_idx}"
+        params.append(budget_type)
+        param_idx += 1
+    if matched_filter_cat:
+        query += f" AND category = ${param_idx}"
+        params.append(matched_filter_cat)
+        param_idx += 1
+    if matched_filter_sub:
+        query += f" AND subcategory = ${param_idx}"
+        params.append(matched_filter_sub)
+        param_idx += 1
+    if period:
+        query += f" AND period = ${param_idx}"
+        params.append(period)
+        param_idx += 1
+
+    query += " ORDER BY id ASC"
+    rows = await conn.fetch(query, *params)
+
+    # 4. Aggregating expenses for each budget
+    budget_status_list = []
+    for r in rows:
+        bid = r["id"]
+        b_type = r["budget_type"]
+        b_cat = r["category"]
+        b_sub = r["subcategory"]
+        b_amount = r["amount"]
+        b_period = r["period"]
+        b_start = pydate.fromisoformat(r["start_date"])
+        b_end = pydate.fromisoformat(r["end_date"])
+
+        # Construct expense sum query
+        exp_query = (
+            "SELECT COALESCE(SUM(amount), 0.0) FROM expenses "
+            "WHERE user_id = $1 AND date BETWEEN $2 AND $3"
+        )
+        exp_params = [user_id, b_start, b_end]
+        exp_param_idx = 4
+
+        if b_type == "category":
+            exp_query += f" AND category = ${exp_param_idx}"
+            exp_params.append(b_cat)
+            exp_param_idx += 1
+        elif b_type == "subcategory":
+            exp_query += f" AND category = ${exp_param_idx} AND subcategory = ${exp_param_idx+1}"
+            exp_params.extend([b_cat, b_sub])
+            exp_param_idx += 2
+
+        total_spent = await conn.fetchval(exp_query, *exp_params)
+
+        # Calculations
+        remaining = b_amount - total_spent
+        percentage = (total_spent / b_amount) * 100.0 if b_amount > 0 else (100.0 if total_spent > 0 else 0.0)
+        status_label = "over_budget" if total_spent > b_amount else "under_budget"
+
+        budget_status_list.append({
+            "budget_id": bid,
+            "budget_type": b_type,
+            "category": b_cat,
+            "subcategory": b_sub,
+            "period": b_period,
+            "start_date": r["start_date"],
+            "end_date": r["end_date"],
+            "limit_amount": b_amount,
+            "total_spent": total_spent,
+            "remaining": remaining,
+            "percentage_spent": round(percentage, 2),
+            "status": status_label
+        })
+
+    return {
+        "status": "ok",
+        "reference_date": ref_date.isoformat(),
+        "budgets": budget_status_list
+    }
+
+
+

finance_intelligence_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: finance-intelligence-mcp
+Version: 0.1.0
+Summary: A production-ready Model Context Protocol (MCP) server for private personal finance management.
+Author-email: Ronit Rajput <ronitrajput182005@gmail.com>
+License: MIT
+Keywords: mcp,fastmcp,finance,postgresql,ai,llm
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asyncpg>=0.31.0
+Requires-Dist: fastmcp>=3.4.2
+Requires-Dist: sqlalchemy[asyncio]>=2.0.51
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: openpyxl>=3.1.2
+Dynamic: license-file
+
+# Finance Intelligence MCP Server
+
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![FastMCP](https://img.shields.io/badge/framework-FastMCP-brightgreen.svg)](https://github.com/jlowin/fastmcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Specification](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/)
+[![Database](https://img.shields.io/badge/database-PostgreSQL-blue.svg)](https://www.postgresql.org/)
+
+Finance Intelligence MCP is a production-ready **Model Context Protocol (MCP)** server that enables AI assistants (like Claude, Cursor, and others) to securely manage and analyze personal finances through natural language. 
+
+Released under the MIT License and designed to be extended with additional finance tools.
+
+---
+
+## 🔍 Overview
+
+Unlike standard cloud-based personal finance apps, **Finance Intelligence MCP** keeps all financial data under your absolute control.
+
+*   **No Accounts / Subscriptions**: Direct connection to your private database with zero SaaS dependencies.
+*   **Zero Telemetry**: Your financial logs never go to external analytic APIs.
+*   **Full AI Context**: Your AI assistant can query history, check budget status, make charts, and answer financial questions instantly.
+
+
+
+---
+
+## 🛠️ Architecture
+
+```
+   ┌────────────────────────────────┐
+   │           MCP Client           │
+   │  (Claude Desktop, Cursor, etc) │
+   └───────────────┬────────────────┘
+                   │
+                   │ (STDIO Transport Protocol)
+                   ▼
+   ┌────────────────────────────────┐
+   │  Finance Intelligence Server   │
+   │           (Local)              │
+   └───────────────┬────────────────┘
+                   │
+                   │ (Direct SQL Pool Connection)
+                   ▼
+   ┌────────────────────────────────┐
+   │       PostgreSQL Database      │
+   │ (Supabase, Local, RDS, etc)    │
+   └────────────────────────────────┘
+```
+
+---
+
+## ✨ Features
+
+*   **Expense Operations**: Create, view, edit, and bulk-delete expense entries.
+*   **Multi-level Budgeting**: Set limits for `overall` spending, specific `category` thresholds, or down to nested `subcategory` targets.
+*   **Analytics Breakdowns**: Aggregate expenses by category, subcategory, notes, or dates over weekly/monthly/yearly time blocks.
+*   **Visual Charts**: Exposes tools that generate Matplotlib line/bar charts of historical spending automatically.
+*   **Excel Spreadsheet Export**: Truncates long list responses and generates download-ready Excel spreadsheets for massive datasets.
+*   **Financial Health Scoring**: Calculates a deterministic financial health score grade based on 6 core personal finance KPIs.
+
+---
+
+## ⚙️ Requirements & Compatibility
+
+*   **Transport**: `stdio`
+*   **Supported Platforms**:
+    *   Windows
+    *   macOS
+    *   Linux
+*   **Python Compatibility**: Python 3.10, 3.11, and 3.12 (Tested)
+*   **Database**: PostgreSQL 12+ (e.g. Supabase, RDS, or local Postgres)
+*   **Supported Clients**:
+    *   Claude Desktop
+    *   Cursor
+    *   *Compatible with any MCP client supporting stdio.*
+
+---
+
+## 💾 Installation & Setup
+
+### 1. Quick Setup (Shortcut)
+If you have `uv` installed, get started in 2 lines:
+```bash
+git clone https://github.com/Ronit-019/Finance-Intelligence-MCP.git
+cd Finance-Intelligence-MCP
+uv sync
+```
+
+### 2. Detailed Installation
+
+#### Step A: Get a PostgreSQL Connection URL
+The easiest, free option is **Supabase**:
+1. Go to [Supabase](https://supabase.com/) and create a free project.
+2. Go to **Project Settings** (gear icon) > **Database**.
+3. Under **Connection string**, select **URI** and copy the string.
+   * *Example*: `postgresql://postgres.[your-project-ref]:[your-password]@aws-0-us-east-1.pooler.supabase.com:5432/postgres`
+   * *(Replace `[your-password]` with your database password).*
+
+#### Step B: Clone the Repository
+Clone the codebase to a directory on your machine:
+```bash
+git clone https://github.com/Ronit-019/Finance-Intelligence-MCP.git
+cd Finance-Intelligence-MCP
+```
+Copy the absolute path of this directory (e.g. `C:/Users/Admin/Desktop/Finance-Intelligence-MCP`).
+*Note: Always use forward slashes (`/`) for paths in JSON configs.*
+
+#### Step C: Install Dependencies
+If you do not have `uv` installed, install from the project metadata:
+```bash
+pip install -e .
+```
+
+---
+
+### 3. Client Integration
+
+#### Claude Desktop Setup
+1. Open your Claude configuration file (`claude_desktop_config.json`):
+   * **Windows**: Press `Win + R`, paste `%APPDATA%\Claude\claude_desktop_config.json` and press Enter.
+   * **macOS**: Paste `~/Library/Application Support/Claude/claude_desktop_config.json` in Finder's Go to Folder.
+2. Add this entry to `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "finance-intelligence": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY",
+        "run",
+        "python",
+        "main.py"
+      ],
+      "env": {
+        "DATABASE_URL": "REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING"
+      }
+    }
+  }
+}
+```
+3. Save and completely **restart Claude Desktop**.
+
+#### Cursor IDE Setup
+1. Go to **Settings** > **Features** > **MCP**.
+2. Click **+ Add New MCP Server**:
+   * **Name**: `Finance Intelligence`
+   * **Type**: `command`
+   * **Command**: 
+     ```bash
+     uv --directory "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY" run python main.py
+     ```
+3. Click **+ Add Env Var**:
+   * **Key**: `DATABASE_URL`
+   * **Value**: `REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING`
+4. Click **Save** and refresh.
+
+---
+
+## 💬 Example Prompts
+
+Once configured, try talking to your AI assistant:
+*   *"Add ₹250 for lunch today under food."*
+*   *"Show my spending breakdown this month."*
+*   *"Generate an Excel report of all my expenses between May and July."*
+*   *"Am I exceeding my monthly budget limit?"*
+*   *"How much did I spend on dining out this week?"*
+*   *"Calculate my monthly financial health score and give me feedback."*
+*   *"Generate a spending chart for the last 30 days."*
+
+---
+
+## 🛠️ Available Tools
+
+The server registers 12 core tools on the client:
+
+| Tool Name | Parameters | Description |
+| :--- | :--- | :--- |
+| `add_expense` | `date`, `amount`, `category`, `subcategory`, `note` | Inserts a new expense transaction. |
+| `list_expenses` | `start_date`, `end_date` | Lists transactions, exports to Excel if count > 50. |
+| `expense_breakdown`| `start_date`, `end_date`, `group_by`, `breakdown`, `category`, `subcategory` | Aggregates spending sums and counts. |
+| `delete_expenses` | `expense_ids`, `start_date`, `end_date`, `category`, `subcategory` | Deletes expenses matching filters. |
+| `update_expenses` | `expense_ids`, `filter_...`, `date`, `amount`, `category`, `subcategory`, `note` | Edits expense records. |
+| `create_budget` | `budget_type`, `amount`, `period`, `start_date`, `end_date`, `category`, `subcategory`, `budgets` | Registers new spending limits. |
+| `list_budgets` | `budget_type`, `category`, `subcategory`, `period` | Returns registered budgets. |
+| `update_budgets` | `budget_ids`, `filter_...`, `budget_type`, `amount`, `period`, `start_date`, `end_date`, `category`, `subcategory` | Modifies active budgets. |
+| `delete_budgets` | `budget_ids`, `start_date`, `end_date`, `budget_type`, `category`, `subcategory`, `period` | Deletes target budget limits. |
+| `compare_budget_vs_expenses` | `reference_date`, `budget_type`, `category`, `subcategory`, `period` | Compares budget vs actual spending. |
+| `expense_summary` | `period`, `group_by`, `category`, `subcategory`, `start_date`, `end_date` | Generates a Matplotlib line/bar chart. |
+| `financial_health_score` | `reference_month` | Evaluates 6 key personal finance indicators. |
+
+---
+
+## 💡 Troubleshooting
+
+### 1. `uv: command not found`
+If the client cannot locate `uv`, update your config file to run standard Python:
+* Ensure you ran `pip install -e .` inside the repository.
+* Update config:
+```json
+"finance-intelligence": {
+  "command": "python",
+  "args": [
+    "REPLACE_WITH_ABSOLUTE_PATH_TO_CLONED_DIRECTORY/main.py"
+  ],
+  "env": {
+    "DATABASE_URL": "REPLACE_WITH_YOUR_SUPABASE_CONNECTION_STRING"
+  }
+}
+```
+
+### 2. Invalid `DATABASE_URL` / PostgreSQL Connection Errors
+* Make sure you replaced `[your-password]` with your actual database password in the Supabase URI string.
+* Ensure there are no surrounding spaces or special characters in the URL string.
+* Verify your Supabase instance is active and not paused.
+
+### 3. Claude Not Detecting the Server
+* Double check that the folder paths in `claude_desktop_config.json` use **forward slashes** (`/`), even on Windows.
+* Check the logs at `%APPDATA%\Claude\logs\mcp*.log` (Windows) or `~/Library/Logs/Claude/mcp*.log` (macOS) to see the exact startup error.
+
+---
+
+## 📁 Repository Structure
+```
+├── src/                       # Helper packages
+│   ├── __init__.py
+│   ├── budget.py              # Budget database operations
+│   ├── analytics.py           # Breakdown aggregations & Matplotlib routines
+│   └── health.py              # KPIs and financial health calculator
+├── main.py                    # FastMCP Server application
+├── categories.json            # Category mapping catalog
+├── pyproject.toml             # Dependencies
+├── LICENSE                    # MIT License file
+└── README.md                  # This file
+```
+
+---
+
+## 🤝 Contributing
+Contributions, bug reports, and feature requests are welcome! 
+Please open an issue before submitting major changes or pull requests.
+
+---
+
+## 📄 License
+This project is licensed under the [MIT License](LICENSE) - see the LICENSE file for details.
+
+---
+
+## 👨‍💻 Author
+
+Ronit Rajput
+
+- Portfolio: https://ronitportfolio-seven.vercel.app/assistant
+- GitHub: https://github.com/Ronit-019
+- LinkedIn: https://www.linkedin.com/in/ronit-rajput/

finance_intelligence_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+analytics.py,sha256=f21JFRE8OITbmAvuxj1VU17dpsZTUZX6lwDi_qe3OlE,6642
+budget.py,sha256=srXQBsSuCT13s3U3mfHT9JToxhJFyc_3y-Cy2o8abWY,19575
+health.py,sha256=RX_6xvyIlsM5DUnCGTd8nXsooOnrg59qfM6NXb6lhpk,11916
+finance_intelligence_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=kKF6ju9nT16naoSoTUUioKiizkzhtep70azqhqbAeHM,1062
+finance_intelligence_mcp-0.1.0.dist-info/METADATA,sha256=Dzqi4AYhuWkDasL693Z1RefDYt0rquisb3B817XRC-E,11523
+finance_intelligence_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+finance_intelligence_mcp-0.1.0.dist-info/top_level.txt,sha256=IiCm945orQ2l_gY2nzRrDjSGjNjjQFV71NUN24nZAXA,33
+finance_intelligence_mcp-0.1.0.dist-info/RECORD,,

finance_intelligence_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

finance_intelligence_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ronit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

finance_intelligence_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+__init__
+analytics
+budget
+health

health.py

@@ -0,0 +1,299 @@
+import os
+from datetime import date as pydate, timedelta
+import statistics
+
+# Define category lists
+ESSENTIALS = {'food', 'transport', 'housing', 'utilities', 'health', 'family_kids', 'home', 'taxes', 'finance_fees'}
+DISCRETIONARY = {'entertainment', 'shopping', 'travel', 'subscriptions', 'personal_care', 'gifts_donations', 'misc', 'business', 'investments'}
+
+async def financial_health_score_impl(conn, user_id: int, reference_month: str = None) -> dict:
+    # 1. Resolve date targets
+    if reference_month:
+        try:
+            parts = reference_month.split("-")
+            year = int(parts[0])
+            month = int(parts[1])
+            start_date = pydate(year, month, 1)
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Invalid reference_month format (expected YYYY-MM): {str(e)}"
+            }
+    else:
+        today = pydate.today()
+        year = today.year
+        month = today.month
+        start_date = pydate(year, month, 1)
+
+    # End of target month
+    if month == 12:
+        end_date = pydate(year, 12, 31)
+    else:
+        end_date = pydate(year, month + 1, 1) - timedelta(days=1)
+
+    # Previous Month M-1
+    if month == 1:
+        prev_start = pydate(year - 1, 12, 1)
+        prev_end = pydate(year - 1, 12, 31)
+    else:
+        prev_start = pydate(year, month - 1, 1)
+        prev_end = pydate(year, month, 1) - timedelta(days=1)
+
+    # Month M-2
+    if month == 1:
+        prev2_start = pydate(year - 1, 11, 1)
+        prev2_end = pydate(year - 1, 11, 30)
+    elif month == 2:
+        prev2_start = pydate(year - 1, 12, 1)
+        prev2_end = pydate(year - 1, 12, 31)
+    else:
+        prev2_start = pydate(year, month - 2, 1)
+        prev2_end = pydate(year, month - 1, 1) - timedelta(days=1)
+
+    # 2. Database Queries
+    
+    # 2.1 Get active budgets
+    budgets_rows = await conn.fetch(
+        """
+        SELECT id, budget_type, category, subcategory, amount, period, start_date, end_date
+        FROM budgets
+        WHERE user_id = $1 AND start_date <= $2 AND end_date >= $3
+        """,
+        user_id, end_date, start_date
+    )
+
+    # 2.2 Category spent breakdown for target month
+    cat_rows = await conn.fetch(
+        """
+        SELECT category, COALESCE(SUM(amount), 0.0) as total_amount
+        FROM expenses
+        WHERE user_id = $1 AND date BETWEEN $2 AND $3
+        GROUP BY category
+        """,
+        user_id, start_date, end_date
+    )
+
+    # 2.3 Max single transaction in target month
+    max_expense = await conn.fetchval(
+        """
+        SELECT COALESCE(MAX(amount), 0.0)
+        FROM expenses
+        WHERE user_id = $1 AND date BETWEEN $2 AND $3
+        """,
+        user_id, start_date, end_date
+    )
+
+    # 2.4 Total spending for M, M-1, M-2
+    monthly_spends = {}
+    for label, s, e in [("M", start_date, end_date), ("M-1", prev_start, prev_end), ("M-2", prev2_start, prev2_end)]:
+        val = await conn.fetchval(
+            "SELECT COALESCE(SUM(amount), 0.0) FROM expenses WHERE user_id = $1 AND date BETWEEN $2 AND $3",
+            user_id, s, e
+        )
+        monthly_spends[label] = val
+
+    # 3. KPI Scoring
+
+    breakdown = {}
+    reasons = {}
+
+    # 3.1 Budget Adherence
+    exceeded_count = 0
+    total_overshoot = 0.0
+    total_active_budgets = len(budgets_rows)
+    overall_budget_total = 0.0
+
+    for b in budgets_rows:
+        b_type = b["budget_type"]
+        b_cat = b["category"]
+        b_sub = b["subcategory"]
+        b_amount = b["amount"]
+        overall_budget_total += b_amount
+
+        # Find matching expenses sum
+        exp_query = "SELECT COALESCE(SUM(amount), 0.0) FROM expenses WHERE user_id = $1 AND date BETWEEN $2 AND $3"
+        exp_params = [user_id, b["start_date"], b["end_date"]]
+        exp_param_idx = 4
+        if b_type == "category":
+            exp_query += f" AND category = ${exp_param_idx}"
+            exp_params.append(b_cat)
+        elif b_type == "subcategory":
+            exp_query += f" AND category = ${exp_param_idx} AND subcategory = ${exp_param_idx+1}"
+            exp_params.extend([b_cat, b_sub])
+
+        spent = await conn.fetchval(exp_query, *exp_params)
+        if spent > b_amount:
+            exceeded_count += 1
+            overshoot_pct = (spent - b_amount) / b_amount if b_amount > 0 else 1.0
+            total_overshoot += overshoot_pct
+
+    if total_active_budgets == 0:
+        breakdown["budget_adherence"] = 7
+        reasons["budget_adherence"] = "No active budgets are currently configured. Create a budget to track spending limits."
+    else:
+        score = 10.0
+        deduct_freq = (exceeded_count / total_active_budgets) * 5.0
+        score -= deduct_freq
+        
+        if exceeded_count > 0:
+            avg_overshoot = total_overshoot / exceeded_count
+            if avg_overshoot > 0.50:
+                score -= 5.0
+            elif avg_overshoot > 0.20:
+                score -= 3.0
+            else:
+                score -= 1.0
+        score = max(0, round(score))
+        breakdown["budget_adherence"] = score
+        if exceeded_count == 0:
+            reasons["budget_adherence"] = "Excellent! You stayed within all defined budget limits."
+        else:
+            reasons["budget_adherence"] = f"Exceeded {exceeded_count}/{total_active_budgets} active budgets. Average overspend percentage was {round((total_overshoot / exceeded_count) * 100, 1)}%."
+
+    # 3.2 Expense Stability
+    totals = [monthly_spends["M-2"], monthly_spends["M-1"], monthly_spends["M"]]
+    mean_spend = statistics.mean(totals)
+    std_spend = statistics.stdev(totals) if len(totals) > 1 else 0.0
+    cv = (std_spend / mean_spend) if mean_spend > 0 else 0.0
+
+    # Neutral default if no spends are logged across history
+    if mean_spend == 0:
+        breakdown["expense_stability"] = 7
+        reasons["expense_stability"] = "Insufficient spending records to determine stability history."
+    else:
+        if cv <= 0.15:
+            score = 10
+            msg = "Highly stable: Month-to-month spending remains highly consistent."
+        elif cv <= 0.30:
+            score = 8
+            msg = "Stable: Spending exhibits standard minor fluctuations."
+        elif cv <= 0.50:
+            score = 5
+            msg = "Moderate: Spending shows noticeable volatility between periods."
+        else:
+            score = 2
+            msg = "Erratic: Spending fluctuates dramatically between months. Plan expenses in advance."
+        breakdown["expense_stability"] = score
+        reasons["expense_stability"] = f"{msg} (Coefficient of Variation: {round(cv, 3)})"
+
+    # 3.3 Savings Capacity
+    target_spent = monthly_spends["M"]
+    if overall_budget_total == 0:
+        breakdown["savings_capacity"] = 7
+        reasons["savings_capacity"] = "Configure budget limits to calculate savings ratio metrics."
+    else:
+        savings_ratio = (overall_budget_total - target_spent) / overall_budget_total
+        if savings_ratio >= 0.20:
+            score = 10
+            msg = f"Superb! You saved {round(savings_ratio * 100, 1)}% of your budgeted limit."
+        elif savings_ratio >= 0.10:
+            score = 8
+            msg = f"Good. You saved {round(savings_ratio * 100, 1)}% of your budgeted limit."
+        elif savings_ratio >= 0.00:
+            score = 5
+            msg = f"Marginal. You saved {round(savings_ratio * 100, 1)}% of your budgeted limit."
+        else:
+            score = 0
+            msg = f"Warning: Spend exceeded budget totals by {round(abs(savings_ratio) * 100, 1)}%."
+        breakdown["savings_capacity"] = score
+        reasons["savings_capacity"] = msg
+
+    # 3.4 Category Balance
+    essential_spend = 0.0
+    discretionary_spend = 0.0
+    for r in cat_rows:
+        cat_key = r["category"].lower()
+        amt = r["total_amount"]
+        if cat_key in DISCRETIONARY:
+            discretionary_spend += amt
+        else:
+            essential_spend += amt
+            
+    total_cat_spend = essential_spend + discretionary_spend
+    if total_cat_spend == 0:
+        breakdown["category_balance"] = 10
+        reasons["category_balance"] = "No transaction records exist for this month."
+    else:
+        discretionary_ratio = discretionary_spend / total_cat_spend
+        if discretionary_ratio <= 0.30:
+            score = 10
+            msg = "Ideal allocation: Discretionary wants make up 30% or less of total spending."
+        elif discretionary_ratio <= 0.50:
+            score = 7
+            msg = "Satisfactory: Discretionary categories compose between 30% and 50% of your expenses."
+        elif discretionary_ratio <= 0.70:
+            score = 4
+            msg = "Elevated wants: Discretionary categories consume 50% to 70% of expenses. Review subscriptions/shopping."
+        else:
+            score = 0
+            msg = "Critical: Over 70% of monthly spending was dedicated to discretionary desires."
+        breakdown["category_balance"] = score
+        reasons["category_balance"] = f"{msg} (Discretionary ratio: {round(discretionary_ratio * 100, 1)}%)"
+
+    # 3.5 Large Expense Ratio
+    if target_spent == 0:
+        breakdown["large_expense_ratio"] = 10
+        reasons["large_expense_ratio"] = "No transactions exist to evaluate."
+    else:
+        le_ratio = max_expense / target_spent
+        if le_ratio <= 0.15:
+            score = 10
+            msg = "Evenly distributed: No single transaction dominates your monthly expenses."
+        elif le_ratio <= 0.30:
+            score = 8
+            msg = "Healthy: Single largest transaction constitutes a moderate portion of spending."
+        elif le_ratio <= 0.50:
+            score = 5
+            msg = "High concentration: Single transaction accounted for over 30% of total spending."
+        else:
+            score = 2
+            msg = "Extreme concentration: Single transaction consumed more than 50% of the entire monthly spent."
+        breakdown["large_expense_ratio"] = score
+        reasons["large_expense_ratio"] = f"{msg} (Largest expense ratio: {round(le_ratio * 100, 1)}%)"
+
+    # 3.6 Spending Trend
+    curr_m = monthly_spends["M"]
+    prev_m = monthly_spends["M-1"]
+    
+    if prev_m == 0:
+        breakdown["spending_trend"] = 7
+        reasons["spending_trend"] = "No previous month records exist to check trend direction."
+    else:
+        if curr_m < prev_m:
+            score = 10
+            msg = f"Positive progress! Spending decreased by {round(((prev_m - curr_m) / prev_m) * 100, 1)}% MoM."
+        elif abs(curr_m - prev_m) / prev_m <= 0.05:
+            score = 7
+            msg = "Stable trend: Spending remained virtually unchanged from the previous month."
+        else:
+            pct_inc = ((curr_m - prev_m) / prev_m) * 100
+            if pct_inc <= 15.0:
+                score = 5
+                msg = f"Minor increase: Spending rose by {round(pct_inc, 1)}% compared to last month."
+            else:
+                score = 2
+                msg = f"Major increase: Spending grew significantly by {round(pct_inc, 1)}% MoM."
+        breakdown["spending_trend"] = score
+        reasons["spending_trend"] = msg
+
+    # 4. Overall score
+    total_raw = sum(breakdown.values())
+    health_score = int((total_raw / 60) * 100)
+    
+    if health_score >= 85:
+        grade = "Excellent"
+    elif health_score >= 70:
+        grade = "Good"
+    elif health_score >= 50:
+        grade = "Fair"
+    else:
+        grade = "Poor"
+
+    return {
+        "status": "ok",
+        "reference_month": f"{year}-{month:02d}",
+        "financial_health_score": health_score,
+        "grade": grade,
+        "breakdown": breakdown,
+        "reasons": reasons
+    }