README.md

---
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

```json
{
  "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:
```bash
pip install -r requirements.txt
```

2. Set environment variables:
```bash
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:
```bash
uvicorn app.main:app --reload
```

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

## Docker Deployment

### Build Docker Image
```bash
docker build -t smart-budget-recommendation .
```

### Run Docker Container
```bash
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