SmartWealth Agent

Agentic AI-powered digital financial assistant for financial health, risk profiling, idle balance detection, and ethical product recommendations.

Overview

SmartWealth Agent is a public GitHub project for an Agentic AI-powered digital financial assistant. It helps banking customers understand their financial health, assess risk appetite, identify idle money, and receive ethical, personalized recommendations such as emergency fund planning, Fixed Deposits, Recurring Deposits, SIPs, and mutual fund guidance.

The project currently uses mock customer data and a rule-based recommendation engine. It is designed as a strong foundation for future AI-powered financial guidance, analytics dashboards, and scalable digital relationship management.

Problem Statement

Many banking customers keep money idle in savings accounts because they may not know:

Whether their emergency fund is sufficient
How much surplus they can invest safely
Which financial products match their risk profile
How to compare safety, liquidity, and growth options
Whether a recommendation is suitable or too risky

This creates a gap in digital financial product adoption, financial literacy, and personalized banking engagement.

Solution

SmartWealth Agent acts like a digital financial relationship assistant. It combines customer profile data, emergency fund logic, risk profiling, financial health scoring, and personalized recommendations into a clean full-stack application.

The system is intentionally simple today, but structured for future expansion into LLM-powered advisory flows, database-backed profiles, analytics, and mutual fund discovery.

Why This Project Matters

SmartWealth Agent is built around practical financial inclusion and responsible digital banking.

Digital financial product adoption: Helps users move from idle savings toward suitable products.
Financial literacy: Explains emergency funds, savings ratio, risk profile, and recommendations clearly.
Ethical recommendations: Prioritizes user safety, liquidity, and suitability over aggressive selling.
Scalable digital relationship management: Gives banks a foundation for personalized, always-available customer guidance.

Risk profile should guide recommendations, not force risky investments.

Key Features

Feature	Status	Description
FastAPI backend	Built	REST APIs for profile, risk, recommendations, and financial health
React frontend	Built	Professional dashboard built with React, Vite, and plain CSS
Customer profile dashboard	Built	Displays customer income, expenses, balance, goal, and risk preference
Emergency fund calculation	Built	Calculates emergency fund using current mock customer expenses
Idle balance detection	Built	Finds money available after emergency fund requirement
Risk profiling form	Built	Collects horizon, tolerance, experience, and loss reaction
Personalized recommendations	Built	Suggests emergency fund, FD, RD, SIP, and education-oriented options
Financial health score	Built	Scores customer health from 0 to 100
Strengths and improvement areas	Built	Explains what is working and what can improve
GitHub daily push script	Built	Includes a PowerShell helper script for daily GitHub pushes

Current User Journey

User opens the React dashboard.
Dashboard fetches mock customer profile from FastAPI.
User reviews account balance, monthly income, expenses, emergency fund, and idle balance.
User completes the risk profiling form.
Backend calculates risk score and category.
User requests personalized recommendations.
Backend returns recommendations guided by risk profile and customer financial data.
Dashboard displays financial health score, strengths, improvement areas, and recommendation cards.

flowchart TD
    A["Open React Dashboard"] --> B["Fetch Customer Profile"]
    B --> C["Display Financial Dashboard"]
    C --> D["Fetch Financial Health Score"]
    C --> E["Complete Risk Profile Form"]
    E --> F["POST /risk/profile"]
    F --> G["Show Risk Score and Category"]
    G --> H["Get Personalized Recommendations"]
    H --> I["POST /recommendations/personalized"]
    I --> J["Show Recommendation Cards"]

Architecture

flowchart LR
    U["User"] --> FE["React + Vite Frontend"]
    FE --> API["FastAPI Backend"]
    API --> CS["Customer Service"]
    API --> RS["Risk Service"]
    API --> REC["Recommendation Service"]
    API --> FH["Financial Health Service"]
    CS --> MOCK["Mock Customer Data"]
    RS --> RULES["Rule-Based Scoring"]
    REC --> RULES
    FH --> RULES

Current System Design

Layer	Current Implementation
Frontend	React, Vite, plain CSS
Backend	FastAPI, Uvicorn, Pydantic
Data source	Mock customer profile
Recommendation logic	Rule-based service layer
Planned database	SQLite first, PostgreSQL later
Planned analytics	Power BI
Planned AI	LLM-powered financial assistant

Technology Stack

Area	Tools
Frontend	React, Vite, plain CSS
Backend	Python 3.12, FastAPI, Uvicorn, Pydantic
Current Data	Mock customer data
Planned Database	SQLite, later PostgreSQL
Version Control	Git, GitHub
Planned Analytics	Power BI
Planned AI	LLM-powered financial assistant
Planned Advanced Module	Mutual fund discovery and comparison

Screenshots

Screenshots can be added in the following locations as the UI evolves.

Screen	Placeholder
Dashboard	`docs/screenshots/dashboard.png`
Risk Profile	`docs/screenshots/risk-profile.png`
Recommendations	`docs/screenshots/recommendations.png`
Financial Health	`docs/screenshots/financial-health.png`

![Dashboard](docs/screenshots/dashboard.png)
![Risk Profile](docs/screenshots/risk-profile.png)
![Recommendations](docs/screenshots/recommendations.png)
![Financial Health](docs/screenshots/financial-health.png)

API Endpoints

Method	Endpoint	Purpose
GET	`/`	Backend root status message
GET	`/health`	Health check endpoint
GET	`/customer/profile`	Returns mock customer financial profile
GET	`/recommendations`	Returns basic rule-based recommendations
POST	`/risk/profile`	Calculates risk score and risk category
POST	`/recommendations/personalized`	Generates personalized recommendations from risk answers
GET	`/financial-health`	Calculates financial health score and insights

Browser URLs

Service	URL
Frontend	http://localhost:5173
Backend	http://127.0.0.1:8000
API Docs	http://127.0.0.1:8000/docs

Financial Health Score Logic

The financial health score is calculated from 0 to 100 using the current mock customer profile.

Category	Maximum Points	Logic
Emergency fund coverage	30	Full points if account balance covers required emergency fund; otherwise proportional
Savings ratio	30	Based on monthly surplus divided by monthly income
Idle balance availability	20	Full points if idle balance is greater than zero
Investment readiness	20	Based on emergency fund coverage and positive monthly surplus

Score Labels

Score Range	Label
80-100	Excellent
60-79	Good
40-59	Needs Improvement
Below 40	At Risk

Project Folder Structure

smartwealth-agent/
├── backend/
│   └── app/
│       ├── main.py
│       ├── schemas/
│       │   ├── customer.py
│       │   ├── financial_health.py
│       │   ├── recommendation.py
│       │   └── risk.py
│       └── services/
│           ├── customer_service.py
│           ├── financial_health_service.py
│           ├── recommendation_service.py
│           └── risk_service.py
├── frontend/
│   └── src/
│       ├── App.jsx
│       ├── App.css
│       ├── FinancialHealthSection.jsx
│       ├── RecommendationsSection.jsx
│       ├── RiskProfileForm.jsx
│       ├── index.css
│       └── main.jsx
├── docs/
│   └── screenshots/
├── mock_data/
├── powerbi/
├── daily-push.ps1
└── README.md

Installation and Setup

Prerequisites

Python 3.12
Node.js and npm
Git
Windows PowerShell

Clone the Repository

git clone https://github.com/bhardwajhardik0404-art/SmartWealth-Agent.git
cd C:\Users\Hardik\smartwealth-agent

Backend Environment Setup

cd C:\Users\Hardik\smartwealth-agent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install fastapi uvicorn pydantic

Frontend Setup

cd C:\Users\Hardik\smartwealth-agent\frontend
npm install

How to Run Backend

cd C:\Users\Hardik\smartwealth-agent
.\.venv\Scripts\Activate.ps1
cd backend
uvicorn app.main:app --reload

Backend runs at:

http://127.0.0.1:8000

API docs:

http://127.0.0.1:8000/docs

How to Run Frontend

cd C:\Users\Hardik\smartwealth-agent\frontend
npm run dev

Frontend runs at:

http://localhost:5173

Example API Flow

1. Fetch Customer Profile

GET http://127.0.0.1:8000/customer/profile

2. Calculate Risk Profile

POST http://127.0.0.1:8000/risk/profile
Content-Type: application/json

{
  "investment_horizon": "long",
  "risk_tolerance": "high",
  "investment_experience": "advanced",
  "reaction_to_loss": "invest_more"
}

3. Get Personalized Recommendations

POST http://127.0.0.1:8000/recommendations/personalized
Content-Type: application/json

{
  "investment_horizon": "long",
  "risk_tolerance": "high",
  "investment_experience": "advanced",
  "reaction_to_loss": "invest_more"
}

4. Fetch Financial Health Score

GET http://127.0.0.1:8000/financial-health

Ethical Recommendation Principles

SmartWealth Agent is designed around responsible financial guidance.

Emergency fund needs should be checked before investment recommendations.
Idle balance should be identified carefully, not treated as automatically investable.
Risk profile should guide recommendations, not force risky investments.
Aggressive users should still receive safe options such as emergency fund buffers or Fixed Deposits.
Recommendations should be educational, transparent, and easy to understand.
The system should avoid presenting prototype outputs as regulated financial advice.

Current Limitations

Uses mock customer data only.
No authentication or user accounts yet.
No database integration yet.
No real banking transaction data or financial APIs yet.
Recommendation engine is rule-based, not LLM-powered yet.
Mutual fund discovery and comparison module is planned but not built yet.
Testing and deployment are still planned work.

Roadmap

Completed

Planned

Future Advanced Mutual Fund Module

The planned mutual fund discovery and comparison module may include:

Mutual fund category discovery
Risk-return comparison
Expense ratio and fund objective summaries
SIP suitability mapping
Education-first explanations for beginner investors
Integration with real financial data APIs

This module is not currently built. It is part of the future product roadmap.

Disclaimer

SmartWealth Agent is currently a prototype built for educational, portfolio, and hackathon purposes. It does not provide regulated financial advice. Any recommendation shown by the system should be treated as an educational suggestion and reviewed with appropriate financial professionals before real-world use.

Author

Hardik Bhardwaj

GitHub: bhardwajhardik0404-art

Contributing

Contributions, suggestions, and issue reports are welcome as the project evolves.

Suggested contribution areas:

Backend tests
Frontend polish
Database integration
Authentication
Financial education content
Mutual fund discovery logic
Deployment setup

Please open an issue or pull request with a clear description of the proposed change.

License

License: TBD

This repository currently uses a license placeholder. Add a formal open-source license before production or public reuse.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
backend/app		backend/app
frontend		frontend
.gitignore		.gitignore
README.md		README.md
daily-push.ps1		daily-push.ps1

Folders and files

Latest commit

History

Repository files navigation