README.md

metadata

license: mit
title: SMART_BUDGET_RECOMMENDATION
sdk: docker
emoji: ⚡
colorFrom: blue
colorTo: pink

Smart Budget Recommendation API

A FastAPI-based service that provides intelligent budget recommendations based on past spending behavior. This service analyzes historical expense data and suggests personalized budgets for each category.

Features

• Smart Budget Recommendations: Analyzes past spending patterns and recommends personalized budgets
• Category-based Analysis: Provides recommendations for each expense category
• Confidence Scoring: Each recommendation includes a confidence score based on data quality
• MongoDB Integration: Stores expenses and budgets in MongoDB
• RESTful API: Clean API endpoints for expense tracking and budget management

Example Recommendation

{
  "category": "Groceries",
  "average_expense": 3800.0,
  "recommended_budget": 4000.0,
  "reason": "Your average monthly grocery expense is Rs.3,800. We suggest setting your budget to Rs.4,000 for next month (includes a 5% buffer for variability).",
  "confidence": 0.85
}

API Endpoints

Health Check

• GET /health - Check API and database connection status

Expenses

• POST /expenses - Create a new expense
• GET /expenses?user_id={user_id} - Get expenses for a user

Budgets

• POST /budgets - Create a new budget
• GET /budgets?user_id={user_id} - Get budgets for a user

Recommendations

• GET /recommendations/{user_id}?month={month}&year={year} - Get smart budget recommendations
• GET /category-expenses/{user_id}?months={months} - Get average expenses by category

Local Development

Prerequisites

• Python 3.11+
• MongoDB connection string

Setup

1. Install dependencies:

pip install -r requirements.txt

2. Set environment variables:

export MONGODB_URI="mongodb://expenseuser:Kem_6o%3F%[email protected]:27017/expense?authSource=admin"
# optional
export OPENAI_API_KEY="your_openai_key"

3. Run the application:

uvicorn app.main:app --reload

The API will be available at http://localhost:8000

Docker Deployment

Build Docker Image

docker build -t smart-budget-recommendation .

Run Docker Container

docker run -p 7860:7860 -e MONGODB_URI="your_mongodb_uri" smart-budget-recommendation

Hugging Face Deployment

Prerequisites

1. Hugging Face account
2. Docker installed
3. MongoDB connection string stored as a secret in Hugging Face

Steps

1. Store secrets in Hugging Face:

   • Go to your Hugging Face Space settings
   • Navigate to "Variables and secrets"
   • Add MONGODB_URI with your MongoDB connection string
   • (Optional) Add OPENAI_API_KEY if you want GPT-powered recommendations

2. Create Hugging Face Space:

   • Create a new Space on Hugging Face
   • Choose "Docker" as the SDK

3. Upload Files:

   • Upload all files from this repository to your Space
   • Ensure Dockerfile is in the root directory

4. Configure Space:

   • The Dockerfile will automatically build and run the application
   • The app will use the MONGODB_URI secret from Hugging Face environment variables

Hugging Face Space Configuration

The Dockerfile is configured to:

• Use Python 3.11
• Install all dependencies
• Expose port 7860 (Hugging Face default)
• Run the FastAPI application with Uvicorn

Hugging Face will automatically:

• Build the Docker image
• Set environment variables from secrets
• Deploy the container
• Provide a public URL

API Documentation

Once deployed, access interactive API documentation at:

• Swagger UI: http://your-url/docs
• ReDoc: http://your-url/redoc

Algorithm Details

The Smart Budget Recommendation engine:

1. Data Collection: Analyzes expenses from the past 6 months
2. Category Analysis: Groups expenses by category and calculates:
   • Average monthly spending
   • Standard deviation (variability)
   • Number of transactions
   • Months of data available
3. Budget Calculation:
   • Base: Average monthly expense
   • Buffer: 5-10% based on spending variability
   • Rounding: Rounds to nearest 100 for cleaner numbers
4. Confidence Scoring:
   • Based on data quality (months analyzed, transaction count, consistency)
   • Returns score from 0-1
5. (Optional) GPT Refinement:
   • If OPENAI_API_KEY is set, GPT reviews the history and suggests increase/decrease/keep along with a natural-language reason.

Environment Variables

• MONGODB_URI: MongoDB connection string (required)
• OPENAI_API_KEY: Optional. If set, GPT-based recommendations augment the rule-based engine.

License

Copyright © 2025 WalletSync. All Rights Reserved