Initial smart budget API

.dockerignore

@@ -0,0 +1,28 @@
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.log
+.git
+.gitignore
+.mypy_cache
+.pytest_cache
+.hypothesis
+.DS_Store
+*.swp
+*.swo
+*~
+

.gitignore

@@ -0,0 +1,46 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+.env.local
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db
+

API_DOCUMENTATION.md

@@ -0,0 +1,351 @@
+# API Documentation
+
+This is a **REST API** built with FastAPI. It provides endpoints for expense tracking and smart budget recommendations.
+
+## Base URL
+
+- **Local**: `http://localhost:8000`
+- **Hugging Face**: `https://your-username-your-space.hf.space`
+
+## Interactive Documentation
+
+FastAPI automatically generates interactive API documentation:
+
+- **Swagger UI**: `http://your-url/docs` - Interactive API explorer
+- **ReDoc**: `http://your-url/redoc` - Alternative documentation format
+
+## API Endpoints
+
+### 1. Health Check
+
+**GET** `/health`
+
+Check if the API and database are running.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "database": "connected"
+}
+```
+
+**Example:**
+```bash
+curl http://localhost:8000/health
+```
+
+---
+
+### 2. Root Endpoint
+
+**GET** `/`
+
+Get API status.
+
+**Response:**
+```json
+{
+  "message": "Smart Budget Recommendation API",
+  "status": "running"
+}
+```
+
+---
+
+### 3. Create Expense
+
+**POST** `/expenses`
+
+Create a new expense record.
+
+**Request Body:**
+```json
+{
+  "user_id": "user123",
+  "amount": 3800,
+  "category": "Groceries",
+  "description": "Monthly groceries",
+  "date": "2024-01-15T00:00:00",
+  "type": "expense"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "507f1f77bcf86cd799439011",
+  "message": "Expense created successfully"
+}
+```
+
+**Example:**
+```bash
+curl -X POST "http://localhost:8000/expenses" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "user123",
+    "amount": 3800,
+    "category": "Groceries",
+    "description": "Monthly groceries",
+    "date": "2024-01-15T00:00:00",
+    "type": "expense"
+  }'
+```
+
+---
+
+### 4. Get Expenses
+
+**GET** `/expenses?user_id={user_id}&limit={limit}`
+
+Get expenses for a specific user.
+
+**Query Parameters:**
+- `user_id` (required): User identifier
+- `limit` (optional): Maximum number of expenses to return (default: 100)
+
+**Response:**
+```json
+[
+  {
+    "id": "507f1f77bcf86cd799439011",
+    "user_id": "user123",
+    "amount": 3800,
+    "category": "Groceries",
+    "description": "Monthly groceries",
+    "date": "2024-01-15T00:00:00",
+    "type": "expense"
+  }
+]
+```
+
+**Example:**
+```bash
+curl "http://localhost:8000/expenses?user_id=user123&limit=10"
+```
+
+---
+
+### 5. Create Budget
+
+**POST** `/budgets`
+
+Create a new budget.
+
+**Request Body:**
+```json
+{
+  "user_id": "user123",
+  "category": "Groceries",
+  "amount": 4000,
+  "period": "monthly",
+  "start_date": "2024-02-01T00:00:00",
+  "end_date": "2024-02-29T00:00:00"
+}
+```
+
+**Response:**
+```json
+{
+  "id": "507f1f77bcf86cd799439012",
+  "message": "Budget created successfully"
+}
+```
+
+---
+
+### 6. Get Budgets
+
+**GET** `/budgets?user_id={user_id}`
+
+Get budgets for a specific user.
+
+**Query Parameters:**
+- `user_id` (required): User identifier
+
+**Response:**
+```json
+[
+  {
+    "id": "507f1f77bcf86cd799439012",
+    "user_id": "user123",
+    "category": "Groceries",
+    "amount": 4000,
+    "period": "monthly",
+    "start_date": "2024-02-01T00:00:00",
+    "end_date": "2024-02-29T00:00:00"
+  }
+]
+```
+
+---
+
+### 7. Get Smart Budget Recommendations ⭐
+
+**GET** `/recommendations/{user_id}?month={month}&year={year}`
+
+Get personalized budget recommendations based on past spending behavior.
+
+**Path Parameters:**
+- `user_id` (required): User identifier
+
+**Query Parameters:**
+- `month` (optional): Target month (1-12). Defaults to next month if not provided
+- `year` (optional): Target year. Defaults to next year if not provided
+
+**Response:**
+```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
+  },
+  {
+    "category": "Transport",
+    "average_expense": 2100.0,
+    "recommended_budget": 2200.0,
+    "reason": "Your average monthly transport expense is Rs.2,100. We suggest setting your budget to Rs.2,200 for next month (includes a 5% buffer for variability).",
+    "confidence": 0.75
+  }
+]
+```
+
+**Example:**
+```bash
+# Get recommendations for next month (default)
+curl "http://localhost:8000/recommendations/user123"
+
+# Get recommendations for specific month
+curl "http://localhost:8000/recommendations/user123?month=3&year=2024"
+```
+
+**How it works:**
+- Analyzes expenses from the past 6 months
+- Calculates average monthly spending per category
+- Adds a 5-10% buffer based on spending variability
+- Returns recommendations sorted by average expense (highest first)
+
+---
+
+### 8. Get Category Expenses
+
+**GET** `/category-expenses/{user_id}?months={months}`
+
+Get average expenses by category for the past N months.
+
+**Path Parameters:**
+- `user_id` (required): User identifier
+
+**Query Parameters:**
+- `months` (optional): Number of months to analyze (default: 3)
+
+**Response:**
+```json
+[
+  {
+    "category": "Groceries",
+    "average_monthly_expense": 3800.0,
+    "total_expenses": 12,
+    "months_analyzed": 3
+  },
+  {
+    "category": "Transport",
+    "average_monthly_expense": 2100.0,
+    "total_expenses": 6,
+    "months_analyzed": 3
+  }
+]
+```
+
+**Example:**
+```bash
+curl "http://localhost:8000/category-expenses/user123?months=6"
+```
+
+---
+
+## Using the API with Python
+
+```python
+import requests
+
+BASE_URL = "http://localhost:8000"
+
+# Create an expense
+expense = {
+    "user_id": "user123",
+    "amount": 3800,
+    "category": "Groceries",
+    "description": "Monthly groceries",
+    "date": "2024-01-15T00:00:00",
+    "type": "expense"
+}
+response = requests.post(f"{BASE_URL}/expenses", json=expense)
+print(response.json())
+
+# Get recommendations
+response = requests.get(f"{BASE_URL}/recommendations/user123")
+recommendations = response.json()
+for rec in recommendations:
+    print(f"{rec['category']}: {rec['recommended_budget']}")
+    print(f"Reason: {rec['reason']}")
+```
+
+## Using the API with JavaScript/Fetch
+
+```javascript
+const BASE_URL = "http://localhost:8000";
+
+// Create an expense
+const expense = {
+  user_id: "user123",
+  amount: 3800,
+  category: "Groceries",
+  description: "Monthly groceries",
+  date: "2024-01-15T00:00:00",
+  type: "expense"
+};
+
+fetch(`${BASE_URL}/expenses`, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(expense)
+})
+  .then(res => res.json())
+  .then(data => console.log(data));
+
+// Get recommendations
+fetch(`${BASE_URL}/recommendations/user123`)
+  .then(res => res.json())
+  .then(recommendations => {
+    recommendations.forEach(rec => {
+      console.log(`${rec.category}: ${rec.recommended_budget}`);
+      console.log(`Reason: ${rec.reason}`);
+    });
+  });
+```
+
+## Error Responses
+
+The API returns standard HTTP status codes:
+
+- `200 OK` - Request successful
+- `400 Bad Request` - Invalid request data
+- `422 Unprocessable Entity` - Validation error
+- `500 Internal Server Error` - Server error
+
+Error response format:
+```json
+{
+  "detail": "Error message description"
+}
+```
+
+## CORS
+
+The API has CORS enabled, allowing requests from any origin. This makes it easy to integrate with frontend applications.
+

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY app/ ./app/
+
+# Expose port
+EXPOSE 8000
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1
+
+# Run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+

HUGGINGFACE_DEPLOYMENT.md

@@ -0,0 +1,154 @@
+# Hugging Face Deployment Guide
+
+This guide will help you deploy the Smart Budget Recommendation API to Hugging Face Spaces.
+
+## Prerequisites
+
+1. A Hugging Face account (sign up at https://huggingface.co)
+2. MongoDB connection string ready
+3. Git installed (optional, you can also use the web interface)
+
+## Step-by-Step Deployment
+
+### Step 1: Create a New Space
+
+1. Go to https://huggingface.co/spaces
+2. Click "Create new Space"
+3. Fill in the details:
+   - **Space name**: `smart-budget-recommendation` (or your preferred name)
+   - **SDK**: Select **Docker**
+   - **Visibility**: Choose Public or Private
+4. Click "Create Space"
+
+### Step 2: Add MongoDB URI as Secret
+
+1. In your Space, go to **Settings** (gear icon)
+2. Navigate to **Variables and secrets** section
+3. Click **New secret**
+4. Add:
+   - **Name**: `MONGODB_URI`
+   - **Value**: `mongodb://expenseuser:Kem_6o%3F%[email protected]:27017/expense?authSource=admin`
+5. Click **Add secret**
+
+### Step 3: Upload Files
+
+You can upload files in two ways:
+
+#### Option A: Using Git (Recommended)
+
+1. Clone your Space repository:
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+```
+
+2. Copy all files from this project:
+   - `app/` directory (all Python files)
+   - `Dockerfile`
+   - `requirements.txt`
+   - `.dockerignore`
+   - `README.md` (optional)
+
+3. Commit and push:
+```bash
+git add .
+git commit -m "Initial deployment"
+git push
+```
+
+#### Option B: Using Web Interface
+
+1. In your Space, click **Files and versions** tab
+2. Click **Add file** → **Upload files**
+3. Upload all files:
+   - All files from `app/` directory
+   - `Dockerfile`
+   - `requirements.txt`
+   - `.dockerignore`
+
+### Step 4: Wait for Build
+
+1. Hugging Face will automatically detect the `Dockerfile` and start building
+2. You can monitor the build progress in the **Logs** tab
+3. The build typically takes 2-5 minutes
+
+### Step 5: Verify Deployment
+
+Once the build completes:
+
+1. Your API will be available at: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`
+2. Test the health endpoint: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health`
+3. View API documentation: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/docs`
+
+## Testing Your Deployment
+
+### Using cURL
+
+```bash
+# Health check
+curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health
+
+# Get recommendations (replace user123 with actual user_id)
+curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/recommendations/user123
+```
+
+### Using Python
+
+```python
+import requests
+
+BASE_URL = "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space"
+
+# Health check
+response = requests.get(f"{BASE_URL}/health")
+print(response.json())
+
+# Get recommendations
+response = requests.get(f"{BASE_URL}/recommendations/user123")
+print(response.json())
+```
+
+## Important Notes
+
+1. **Port Configuration**: Hugging Face automatically maps port 8000, so your Dockerfile should expose port 8000 (which it does)
+
+2. **Environment Variables**: The `MONGODB_URI` secret will be automatically available as an environment variable in your container
+
+3. **Cold Starts**: The first request after inactivity may take longer (cold start). Subsequent requests will be faster
+
+4. **Resource Limits**: Free Hugging Face Spaces have resource limits. For production use, consider upgrading
+
+5. **Custom Domain**: You can add a custom domain in Space settings if needed
+
+## Troubleshooting
+
+### Build Fails
+
+- Check the **Logs** tab for error messages
+- Ensure `Dockerfile` is in the root directory
+- Verify all required files are uploaded
+
+### Connection Errors
+
+- Verify `MONGODB_URI` secret is set correctly
+- Check MongoDB server is accessible from Hugging Face's servers
+- Review connection string encoding (special characters should be URL-encoded)
+
+### API Not Responding
+
+- Check the **Logs** tab for runtime errors
+- Verify the application starts successfully
+- Test the `/health` endpoint first
+
+## Updating Your Deployment
+
+1. Make changes to your code locally
+2. Commit and push to your Space repository
+3. Hugging Face will automatically rebuild and redeploy
+
+## Support
+
+For issues specific to:
+- **Hugging Face Spaces**: Check [Hugging Face Documentation](https://huggingface.co/docs/hub/spaces)
+- **This Application**: Check the main README.md file
+

QUICKSTART.md

@@ -0,0 +1,84 @@
+# Quick Start Guide
+
+## Local Development
+
+1. **Install dependencies:**
+```bash
+pip install -r requirements.txt
+```
+
+2. **Set environment variable:**
+```bash
+# Windows PowerShell
+$env:MONGODB_URI="mongodb://expenseuser:Kem_6o%3F%[email protected]:27017/expense?authSource=admin"
+
+# Linux/Mac
+export MONGODB_URI="mongodb://expenseuser:Kem_6o%3F%[email protected]:27017/expense?authSource=admin"
+```
+
+3. **Run the application:**
+```bash
+uvicorn app.main:app --reload
+```
+
+4. **Access the API:**
+- API: http://localhost:8000
+- Docs: http://localhost:8000/docs
+- Health: http://localhost:8000/health
+
+## Test the Smart Budget Recommendation
+
+1. **Create some sample expenses:**
+```bash
+curl -X POST "http://localhost:8000/expenses" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "user123",
+    "amount": 3800,
+    "category": "Groceries",
+    "description": "Monthly groceries",
+    "date": "2024-01-15T00:00:00",
+    "type": "expense"
+  }'
+```
+
+2. **Get recommendations:**
+```bash
+curl "http://localhost:8000/recommendations/user123?month=2&year=2024"
+```
+
+Expected response:
+```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
+  }
+]
+```
+
+## Docker Deployment
+
+1. **Build the image:**
+```bash
+docker build -t smart-budget-recommendation .
+```
+
+2. **Run the container:**
+```bash
+docker run -p 8000:8000 -e MONGODB_URI="your_mongodb_uri" smart-budget-recommendation
+```
+
+## Hugging Face Deployment
+
+See `HUGGINGFACE_DEPLOYMENT.md` for detailed instructions.
+
+Quick steps:
+1. Create a new Docker Space on Hugging Face
+2. Add `MONGODB_URI` as a secret
+3. Upload all files
+4. Wait for automatic build and deployment
+

README.md

@@ -0,0 +1,150 @@
+# 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 variable:
+```bash
+export MONGODB_URI="mongodb://expenseuser:Kem_6o%3F%[email protected]:27017/expense?authSource=admin"
+```
+
+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 8000:8000 -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 MongoDB URI as Secret in Hugging Face**:
+   - Go to your Hugging Face Space settings
+   - Navigate to "Variables and secrets"
+   - Add a new secret named `MONGODB_URI` with your MongoDB connection string
+
+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 8000
+- 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
+
+## Environment Variables
+
+- `MONGODB_URI`: MongoDB connection string (required)
+
+## License
+
+Copyright © 2025 WalletSync. All Rights Reserved
+

app.json

@@ -0,0 +1,6 @@
+{
+  "sdk": "docker",
+  "sdk_version": "3.0.0",
+  "app_file": "app/main.py"
+}
+

app/__init__.py

@@ -0,0 +1,2 @@
+# Smart Budget Recommendation API
+

app/main.py

@@ -0,0 +1,117 @@
+from fastapi import FastAPI, HTTPException, Depends
+from fastapi.middleware.cors import CORSMiddleware
+from pymongo import MongoClient
+from pymongo.errors import ConnectionFailure
+import os
+from typing import List, Optional
+from datetime import datetime, timedelta
+from models import BudgetRecommendation, Expense, Budget, CategoryExpense
+from smart_recommendation import SmartBudgetRecommender
+
+app = FastAPI(title="Smart Budget Recommendation API", version="1.0.0")
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# MongoDB connection - Get from environment variable (set as secret in Hugging Face)
+MONGODB_URI = os.getenv("MONGODB_URI")
+if not MONGODB_URI:
+    raise ValueError("MONGODB_URI environment variable is required. Please set it in Hugging Face secrets.")
+
+try:
+    client = MongoClient(MONGODB_URI)
+    db = client.expense
+    # Test connection
+    client.admin.command('ping')
+    print("Successfully connected to MongoDB")
+except ConnectionFailure as e:
+    print(f"Failed to connect to MongoDB: {e}")
+    raise
+
+# Initialize Smart Budget Recommender
+recommender = SmartBudgetRecommender(db)
+
+@app.get("/")
+async def root():
+    return {"message": "Smart Budget Recommendation API", "status": "running"}
+
+@app.get("/health")
+async def health_check():
+    try:
+        client.admin.command('ping')
+        return {"status": "healthy", "database": "connected"}
+    except Exception as e:
+        return {"status": "unhealthy", "error": str(e)}
+
+@app.post("/expenses", response_model=dict)
+async def create_expense(expense: Expense):
+    """Create a new expense"""
+    expense_dict = expense.model_dump()
+    expense_dict["created_at"] = datetime.utcnow()
+    result = db.expenses.insert_one(expense_dict)
+    return {"id": str(result.inserted_id), "message": "Expense created successfully"}
+
+@app.get("/expenses", response_model=List[Expense])
+async def get_expenses(user_id: str, limit: int = 100):
+    """Get expenses for a user"""
+    expenses = list(db.expenses.find({"user_id": user_id}).sort("date", -1).limit(limit))
+    for expense in expenses:
+        expense["id"] = str(expense["_id"])
+        del expense["_id"]
+    return expenses
+
+@app.post("/budgets", response_model=dict)
+async def create_budget(budget: Budget):
+    """Create a new budget"""
+    budget_dict = budget.model_dump()
+    budget_dict["created_at"] = datetime.utcnow()
+    result = db.budgets.insert_one(budget_dict)
+    return {"id": str(result.inserted_id), "message": "Budget created successfully"}
+
+@app.get("/budgets", response_model=List[Budget])
+async def get_budgets(user_id: str):
+    """Get budgets for a user"""
+    budgets = list(db.budgets.find({"user_id": user_id}))
+    for budget in budgets:
+        budget["id"] = str(budget["_id"])
+        del budget["_id"]
+    return budgets
+
+@app.get("/recommendations/{user_id}", response_model=List[BudgetRecommendation])
+async def get_budget_recommendations(user_id: str, month: Optional[int] = None, year: Optional[int] = None):
+    """
+    Get smart budget recommendations for a user based on past spending behavior.
+    
+    Example response:
+    {
+        "category": "Groceries",
+        "average_expense": 3800,
+        "recommended_budget": 4000,
+        "reason": "Your average monthly grocery expense is Rs.3,800. We suggest setting your budget to Rs.4,000 for next month."
+    }
+    """
+    if not month or not year:
+        # Default to next month
+        next_month = datetime.now().replace(day=1) + timedelta(days=32)
+        month = next_month.month
+        year = next_month.year
+    
+    recommendations = recommender.get_recommendations(user_id, month, year)
+    return recommendations
+
+@app.get("/category-expenses/{user_id}", response_model=List[CategoryExpense])
+async def get_category_expenses(user_id: str, months: int = 3):
+    """Get average expenses by category for the past N months"""
+    category_expenses = recommender.get_category_averages(user_id, months)
+    return category_expenses
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+

app/models.py

@@ -0,0 +1,38 @@
+from pydantic import BaseModel, Field
+from typing import Optional
+from datetime import datetime
+from enum import Enum
+
+class ExpenseType(str, Enum):
+    INCOME = "income"
+    EXPENSE = "expense"
+
+class Expense(BaseModel):
+    user_id: str
+    amount: float = Field(..., gt=0, description="Expense amount")
+    category: str = Field(..., description="Expense category (e.g., Groceries, Transport)")
+    description: Optional[str] = None
+    date: datetime
+    type: ExpenseType = ExpenseType.EXPENSE
+
+class Budget(BaseModel):
+    user_id: str
+    category: str
+    amount: float = Field(..., gt=0, description="Budget amount")
+    period: str = Field(..., description="Budget period: daily, weekly, monthly, yearly")
+    start_date: datetime
+    end_date: Optional[datetime] = None
+
+class BudgetRecommendation(BaseModel):
+    category: str
+    average_expense: float
+    recommended_budget: float
+    reason: str
+    confidence: float = Field(..., ge=0, le=1, description="Confidence score (0-1)")
+
+class CategoryExpense(BaseModel):
+    category: str
+    average_monthly_expense: float
+    total_expenses: int
+    months_analyzed: int
+

app/smart_recommendation.py

@@ -0,0 +1,218 @@
+from datetime import datetime, timedelta
+from typing import List, Dict
+from collections import defaultdict
+from models import BudgetRecommendation, CategoryExpense
+import math
+
+class SmartBudgetRecommender:
+    """
+    Smart Budget Recommendation Engine
+    
+    Analyzes past spending behavior and recommends personalized budgets
+    for each category based on historical data.
+    """
+    
+    def __init__(self, db):
+        self.db = db
+    
+    def get_recommendations(self, user_id: str, month: int, year: int) -> List[BudgetRecommendation]:
+        """
+        Get budget recommendations for all categories based on past behavior.
+        
+        Args:
+            user_id: User identifier
+            month: Target month (1-12)
+            year: Target year
+            
+        Returns:
+            List of budget recommendations for each category
+        """
+        # Get past expenses (last 6 months for better accuracy)
+        end_date = datetime(year, month, 1) - timedelta(days=1)
+        start_date = end_date - timedelta(days=180)  # ~6 months
+        
+        expenses = list(self.db.expenses.find({
+            "user_id": user_id,
+            "date": {"$gte": start_date, "$lte": end_date},
+            "type": "expense"
+        }))
+        
+        if not expenses:
+            return []
+        
+        # Group expenses by category and calculate monthly averages
+        category_data = self._calculate_category_statistics(expenses, start_date, end_date)
+        
+        recommendations = []
+        for category, data in category_data.items():
+            avg_expense = data["average_monthly"]
+            recommended_budget = self._calculate_recommended_budget(avg_expense, data)
+            confidence = self._calculate_confidence(data)
+            
+            reason = self._generate_reason(category, avg_expense, recommended_budget)
+            
+            recommendations.append(BudgetRecommendation(
+                category=category,
+                average_expense=round(avg_expense, 2),
+                recommended_budget=round(recommended_budget, 2),
+                reason=reason,
+                confidence=confidence
+            ))
+        
+        # Sort by average expense (highest first)
+        recommendations.sort(key=lambda x: x.average_expense, reverse=True)
+        
+        return recommendations
+    
+    def _calculate_category_statistics(self, expenses: List[Dict], start_date: datetime, end_date: datetime) -> Dict:
+        """Calculate statistics for each category"""
+        category_data = defaultdict(lambda: {
+            "total": 0,
+            "count": 0,
+            "months": set(),
+            "monthly_totals": defaultdict(float)
+        })
+        
+        for expense in expenses:
+            category = expense.get("category", "Uncategorized")
+            amount = expense.get("amount", 0)
+            date = expense.get("date")
+            
+            if isinstance(date, str):
+                date = datetime.fromisoformat(date.replace('Z', '+00:00'))
+            
+            category_data[category]["total"] += amount
+            category_data[category]["count"] += 1
+            
+            # Track monthly totals
+            month_key = (date.year, date.month)
+            category_data[category]["months"].add(month_key)
+            category_data[category]["monthly_totals"][month_key] += amount
+        
+        # Calculate averages
+        result = {}
+        for category, data in category_data.items():
+            num_months = len(data["months"]) or 1
+            avg_monthly = data["total"] / num_months
+            
+            # Calculate standard deviation for variability
+            monthly_values = list(data["monthly_totals"].values())
+            if len(monthly_values) > 1:
+                mean = sum(monthly_values) / len(monthly_values)
+                variance = sum((x - mean) ** 2 for x in monthly_values) / len(monthly_values)
+                std_dev = math.sqrt(variance)
+            else:
+                std_dev = 0
+            
+            result[category] = {
+                "average_monthly": avg_monthly,
+                "total": data["total"],
+                "count": data["count"],
+                "months_analyzed": num_months,
+                "std_dev": std_dev,
+                "monthly_values": monthly_values
+            }
+        
+        return result
+    
+    def _calculate_recommended_budget(self, avg_expense: float, data: Dict) -> float:
+        """
+        Calculate recommended budget based on average expense.
+        
+        Strategy:
+        - Base: Average monthly expense
+        - Add 5% buffer for variability
+        - Round to nearest 100 for cleaner numbers
+        """
+        # Add 5% buffer to handle variability
+        buffer = avg_expense * 0.05
+        
+        # If there's high variability (std_dev > 20% of mean), add more buffer
+        if data["std_dev"] > 0:
+            coefficient_of_variation = data["std_dev"] / avg_expense if avg_expense > 0 else 0
+            if coefficient_of_variation > 0.2:
+                buffer = avg_expense * 0.10  # 10% buffer for high variability
+        
+        recommended = avg_expense + buffer
+        
+        # Round to nearest 100 for cleaner budget numbers
+        recommended = round(recommended / 100) * 100
+        
+        # Ensure minimum of 100 if there was any expense
+        if recommended < 100 and avg_expense > 0:
+            recommended = 100
+        
+        return recommended
+    
+    def _calculate_confidence(self, data: Dict) -> float:
+        """
+        Calculate confidence score (0-1) based on data quality.
+        
+        Factors:
+        - Number of months analyzed (more = higher confidence)
+        - Number of transactions (more = higher confidence)
+        - Consistency of spending (lower std_dev = higher confidence)
+        """
+        months_score = min(data["months_analyzed"] / 6, 1.0)  # Max at 6 months
+        count_score = min(data["count"] / 10, 1.0)  # Max at 10 transactions
+        
+        # Consistency score (inverse of coefficient of variation)
+        if data["average_monthly"] > 0:
+            cv = data["std_dev"] / data["average_monthly"]
+            consistency_score = max(0, 1 - min(cv, 1.0))  # Lower CV = higher score
+        else:
+            consistency_score = 0.5
+        
+        # Weighted average
+        confidence = (months_score * 0.4 + count_score * 0.3 + consistency_score * 0.3)
+        
+        return round(confidence, 2)
+    
+    def _generate_reason(self, category: str, avg_expense: float, recommended_budget: float) -> str:
+        """Generate human-readable reason for the recommendation"""
+        # Format amounts with currency symbol
+        avg_formatted = f"Rs.{avg_expense:,.0f}"
+        budget_formatted = f"Rs.{recommended_budget:,.0f}"
+        
+        if recommended_budget > avg_expense:
+            buffer = recommended_budget - avg_expense
+            buffer_pct = (buffer / avg_expense * 100) if avg_expense > 0 else 0
+            return (
+                f"Your average monthly {category.lower()} expense is {avg_formatted}. "
+                f"We suggest setting your budget to {budget_formatted} for next month "
+                f"(includes a {buffer_pct:.0f}% buffer for variability)."
+            )
+        else:
+            return (
+                f"Your average monthly {category.lower()} expense is {avg_formatted}. "
+                f"We recommend a budget of {budget_formatted} for next month."
+            )
+    
+    def get_category_averages(self, user_id: str, months: int = 3) -> List[CategoryExpense]:
+        """Get average expenses by category for the past N months"""
+        end_date = datetime.now()
+        start_date = end_date - timedelta(days=months * 30)
+        
+        expenses = list(self.db.expenses.find({
+            "user_id": user_id,
+            "date": {"$gte": start_date, "$lte": end_date},
+            "type": "expense"
+        }))
+        
+        if not expenses:
+            return []
+        
+        category_data = self._calculate_category_statistics(expenses, start_date, end_date)
+        
+        result = []
+        for category, data in category_data.items():
+            result.append(CategoryExpense(
+                category=category,
+                average_monthly_expense=round(data["average_monthly"], 2),
+                total_expenses=data["count"],
+                months_analyzed=data["months_analyzed"]
+            ))
+        
+        result.sort(key=lambda x: x.average_monthly_expense, reverse=True)
+        return result
+

example_usage.py

@@ -0,0 +1,154 @@
+"""
+Example usage of the Smart Budget Recommendation API
+
+This script demonstrates how to use the API endpoints.
+"""
+
+import requests
+from datetime import datetime
+
+# Base URL - Update this to your deployed Hugging Face Space URL
+BASE_URL = "http://localhost:8000"  # Change to your Hugging Face Space URL
+
+# Example user ID
+USER_ID = "user123"
+
+def create_sample_expenses():
+    """Create sample expenses for testing"""
+    expenses = [
+        {
+            "user_id": USER_ID,
+            "amount": 3500,
+            "category": "Groceries",
+            "description": "Monthly groceries",
+            "date": "2024-01-15T00:00:00",
+            "type": "expense"
+        },
+        {
+            "user_id": USER_ID,
+            "amount": 4000,
+            "category": "Groceries",
+            "description": "Monthly groceries",
+            "date": "2024-02-15T00:00:00",
+            "type": "expense"
+        },
+        {
+            "user_id": USER_ID,
+            "amount": 3800,
+            "category": "Groceries",
+            "description": "Monthly groceries",
+            "date": "2024-03-15T00:00:00",
+            "type": "expense"
+        },
+        {
+            "user_id": USER_ID,
+            "amount": 4200,
+            "category": "Groceries",
+            "description": "Monthly groceries",
+            "date": "2024-04-15T00:00:00",
+            "type": "expense"
+        },
+        {
+            "user_id": USER_ID,
+            "amount": 2000,
+            "category": "Transport",
+            "description": "Monthly transport",
+            "date": "2024-01-20T00:00:00",
+            "type": "expense"
+        },
+        {
+            "user_id": USER_ID,
+            "amount": 2200,
+            "category": "Transport",
+            "description": "Monthly transport",
+            "date": "2024-02-20T00:00:00",
+            "type": "expense"
+        },
+    ]
+    
+    print("Creating sample expenses...")
+    for expense in expenses:
+        response = requests.post(f"{BASE_URL}/expenses", json=expense)
+        if response.status_code == 200:
+            print(f"✓ Created expense: {expense['category']} - Rs.{expense['amount']}")
+        else:
+            print(f"✗ Failed to create expense: {response.text}")
+
+def get_recommendations():
+    """Get budget recommendations"""
+    print("\n" + "="*50)
+    print("Getting Smart Budget Recommendations...")
+    print("="*50)
+    
+    # Get recommendations for next month
+    next_month = datetime.now().month + 1
+    next_year = datetime.now().year
+    if next_month > 12:
+        next_month = 1
+        next_year += 1
+    
+    response = requests.get(
+        f"{BASE_URL}/recommendations/{USER_ID}",
+        params={"month": next_month, "year": next_year}
+    )
+    
+    if response.status_code == 200:
+        recommendations = response.json()
+        print(f"\nFound {len(recommendations)} recommendations:\n")
+        
+        for rec in recommendations:
+            print(f"Category: {rec['category']}")
+            print(f"  Average Expense: Rs.{rec['average_expense']:,.0f}")
+            print(f"  Recommended Budget: Rs.{rec['recommended_budget']:,.0f}")
+            print(f"  Confidence: {rec['confidence']*100:.0f}%")
+            print(f"  Reason: {rec['reason']}")
+            print()
+    else:
+        print(f"Error: {response.status_code} - {response.text}")
+
+def get_category_expenses():
+    """Get category expense averages"""
+    print("\n" + "="*50)
+    print("Getting Category Expense Averages...")
+    print("="*50)
+    
+    response = requests.get(
+        f"{BASE_URL}/category-expenses/{USER_ID}",
+        params={"months": 3}
+    )
+    
+    if response.status_code == 200:
+        categories = response.json()
+        print(f"\nFound {len(categories)} categories:\n")
+        
+        for cat in categories:
+            print(f"{cat['category']}:")
+            print(f"  Average Monthly: Rs.{cat['average_monthly_expense']:,.0f}")
+            print(f"  Total Transactions: {cat['total_expenses']}")
+            print(f"  Months Analyzed: {cat['months_analyzed']}")
+            print()
+    else:
+        print(f"Error: {response.status_code} - {response.text}")
+
+if __name__ == "__main__":
+    print("Smart Budget Recommendation API - Example Usage")
+    print("="*50)
+    
+    # Check health
+    print("\nChecking API health...")
+    response = requests.get(f"{BASE_URL}/health")
+    if response.status_code == 200:
+        print(f"✓ API is healthy: {response.json()}")
+    else:
+        print(f"✗ API health check failed: {response.text}")
+        exit(1)
+    
+    # Uncomment to create sample data
+    # create_sample_expenses()
+    
+    # Get recommendations
+    get_recommendations()
+    
+    # Get category averages
+    get_category_expenses()
+

requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+pymongo==4.6.0
+pydantic==2.5.0
+python-multipart==0.0.6
+

test_api.py

@@ -0,0 +1,161 @@
+"""
+Simple test script to verify the API is working
+Run this after starting the server to test all endpoints
+"""
+
+import requests
+import json
+from datetime import datetime
+
+# Update this to your API URL
+# For local: http://localhost:8000
+# For Hugging Face: https://your-username-your-space.hf.space
+BASE_URL = "http://localhost:8000"
+
+def test_health():
+    """Test health endpoint"""
+    print("=" * 50)
+    print("Testing Health Endpoint")
+    print("=" * 50)
+    try:
+        response = requests.get(f"{BASE_URL}/health")
+        print(f"Status Code: {response.status_code}")
+        print(f"Response: {json.dumps(response.json(), indent=2)}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"Error: {e}")
+        return False
+
+def test_root():
+    """Test root endpoint"""
+    print("\n" + "=" * 50)
+    print("Testing Root Endpoint")
+    print("=" * 50)
+    try:
+        response = requests.get(f"{BASE_URL}/")
+        print(f"Status Code: {response.status_code}")
+        print(f"Response: {json.dumps(response.json(), indent=2)}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"Error: {e}")
+        return False
+
+def test_create_expense():
+    """Test creating an expense"""
+    print("\n" + "=" * 50)
+    print("Testing Create Expense Endpoint")
+    print("=" * 50)
+    try:
+        expense_data = {
+            "user_id": "test_user_123",
+            "amount": 3800,
+            "category": "Groceries",
+            "description": "Monthly groceries",
+            "date": datetime.now().isoformat(),
+            "type": "expense"
+        }
+        response = requests.post(
+            f"{BASE_URL}/expenses",
+            json=expense_data,
+            headers={"Content-Type": "application/json"}
+        )
+        print(f"Status Code: {response.status_code}")
+        print(f"Response: {json.dumps(response.json(), indent=2)}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"Error: {e}")
+        return False
+
+def test_get_expenses():
+    """Test getting expenses"""
+    print("\n" + "=" * 50)
+    print("Testing Get Expenses Endpoint")
+    print("=" * 50)
+    try:
+        response = requests.get(
+            f"{BASE_URL}/expenses",
+            params={"user_id": "test_user_123", "limit": 10}
+        )
+        print(f"Status Code: {response.status_code}")
+        print(f"Response: {json.dumps(response.json(), indent=2)}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"Error: {e}")
+        return False
+
+def test_get_recommendations():
+    """Test getting budget recommendations"""
+    print("\n" + "=" * 50)
+    print("Testing Get Recommendations Endpoint")
+    print("=" * 50)
+    try:
+        # Get recommendations for next month
+        next_month = datetime.now().month + 1
+        next_year = datetime.now().year
+        if next_month > 12:
+            next_month = 1
+            next_year += 1
+        
+        response = requests.get(
+            f"{BASE_URL}/recommendations/test_user_123",
+            params={"month": next_month, "year": next_year}
+        )
+        print(f"Status Code: {response.status_code}")
+        print(f"Response: {json.dumps(response.json(), indent=2)}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"Error: {e}")
+        return False
+
+def test_get_category_expenses():
+    """Test getting category expenses"""
+    print("\n" + "=" * 50)
+    print("Testing Get Category Expenses Endpoint")
+    print("=" * 50)
+    try:
+        response = requests.get(
+            f"{BASE_URL}/category-expenses/test_user_123",
+            params={"months": 3}
+        )
+        print(f"Status Code: {response.status_code}")
+        print(f"Response: {json.dumps(response.json(), indent=2)}")
+        return response.status_code == 200
+    except Exception as e:
+        print(f"Error: {e}")
+        return False
+
+if __name__ == "__main__":
+    print("\n" + "=" * 50)
+    print("Smart Budget Recommendation API - Test Suite")
+    print("=" * 50)
+    print(f"\nTesting API at: {BASE_URL}")
+    print("\nMake sure the server is running!")
+    print("Start server with: uvicorn app.main:app --reload\n")
+    
+    results = []
+    
+    # Test all endpoints
+    results.append(("Health Check", test_health()))
+    results.append(("Root Endpoint", test_root()))
+    results.append(("Create Expense", test_create_expense()))
+    results.append(("Get Expenses", test_get_expenses()))
+    results.append(("Get Recommendations", test_get_recommendations()))
+    results.append(("Get Category Expenses", test_get_category_expenses()))
+    
+    # Summary
+    print("\n" + "=" * 50)
+    print("Test Summary")
+    print("=" * 50)
+    for test_name, passed in results:
+        status = "✓ PASS" if passed else "✗ FAIL"
+        print(f"{status} - {test_name}")
+    
+    passed_count = sum(1 for _, passed in results if passed)
+    print(f"\nTotal: {passed_count}/{len(results)} tests passed")
+    
+    print("\n" + "=" * 50)
+    print("API Documentation available at:")
+    print(f"  - Swagger UI: {BASE_URL}/docs")
+    print(f"  - ReDoc: {BASE_URL}/redoc")
+    print("=" * 50)
+