FINANCE-AI-ADVISOR

AI-powered finance advisor project with:

• a Pyramid backend for the existing application flow
• a FastAPI ML service for training and inference APIs
• a React frontend for the user interface

Quick Start

Fastest way to run this project:

Updated:

• Docker images are now documented for Docker Hub usage.
• .env should be passed at runtime and is excluded from future Docker builds.

1. Pull the Docker image:

docker pull n8nproject2026/finance-ai-advisor:latest

2. Start FastAPI backend:

docker run --name finance-fastapi --rm -p 8000:8000 --env-file backend/.env -e APP_MODE=fastapi n8nproject2026/finance-ai-advisor:latest

3. Start Pyramid backend in another terminal:

docker run --name finance-pyramid --rm -p 6543:6543 --env-file backend/.env -e APP_MODE=pyramid n8nproject2026/finance-ai-advisor:latest

4. Start frontend locally:

cd frontend
$env:VITE_PYRAMID_API_ORIGIN="http://localhost:6543"
$env:VITE_FASTAPI_API_ORIGIN="http://localhost:8000"
npm install
npm run dev

5. Open:

• http://localhost:5173

For full Docker instructions, see Docker Hub Quickstart.

Preview

Features

• Loan approval prediction using a trained scikit-learn pipeline
• Prediction history persisted in SQLite
• FastAPI endpoints for training, loading, saving, and prediction
• Automatic Swagger and ReDoc documentation
• Postman-friendly JSON request/response workflow
• AI financial file analysis endpoints
• Follow-up advisor chat endpoints
• Local scripts for backend, frontend, and test execution

Project Structure

FINANCE-AI-ADVISOR/
|-- backend/
|   |-- finance_ai/
|   |   |-- fastapi_app.py
|   |   |-- services/
|   |   |   `-- ml_workflow_service.py
|   |   `-- ml_models/
|   |       |-- train_model.py
|   |       |-- model.pkl
|   |       `-- loan_status_prediction.csv
|   `-- tests/
|-- frontend/
|-- scripts/
|   |-- start-backend.ps1
|   |-- start-fastapi.ps1
|   |-- start-frontend.ps1
|   |-- train_expense_model.py
|   `-- train_anomaly_model.py
`-- docs/

Installation

1. Clone repository

git clone <YOUR_GITHUB_REPO_URL>
cd FINANCE-AI-ADVISOR

2. Backend setup

cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
cd ..

3. Frontend setup

cd frontend
npm install
cd ..

How To Run

Pyramid backend

.\scripts\start-backend.ps1

Default URL: http://localhost:6543

FastAPI ML API

.\scripts\start-fastapi.ps1

Default URL: http://localhost:8000

Docs:

• http://localhost:8000/docs
• http://localhost:8000/redoc

React frontend

.\scripts\start-frontend.ps1

Default URL: http://localhost:5173

Run both app layers

.\scripts\start-all.ps1

Docker Hub Quickstart

Published image:

• n8nproject2026/finance-ai-advisor:latest

This image supports two backend modes:

• APP_MODE=pyramid runs the Pyramid backend on port 6543
• APP_MODE=fastapi runs the FastAPI backend on port 8000

Important:

• The Docker image should not contain your private .env file.
• Pass secrets and API keys at runtime with --env-file backend/.env or -e KEY=value.

Step 1. Pull the image

docker pull n8nproject2026/finance-ai-advisor:latest

Step 2. Start the FastAPI backend

This backend handles prediction and AI upload/chat fallback:

docker run --name finance-fastapi --rm -p 8000:8000 --env-file backend/.env -e APP_MODE=fastapi n8nproject2026/finance-ai-advisor:latest

Open in browser after startup:

• http://localhost:8000/health
• http://localhost:8000/docs

Step 3. Start the Pyramid backend

This backend handles the original app routes and prediction history dashboard:

docker run --name finance-pyramid --rm -p 6543:6543 --env-file backend/.env -e APP_MODE=pyramid n8nproject2026/finance-ai-advisor:latest

Open in browser after startup:

• http://localhost:6543/

Step 4. Start the frontend locally

Open a new terminal:

cd frontend
$env:VITE_PYRAMID_API_ORIGIN="http://localhost:6543"
$env:VITE_FASTAPI_API_ORIGIN="http://localhost:8000"
npm install
npm run dev

Then open:

• http://localhost:5173

Step 5. Test the app

1. Run a loan prediction.
2. Upload a .csv, .txt, .json, or .xlsx file in the AI advisor section.
3. Ask a follow-up question after analysis completes.

One-container examples

If you only want one backend:

FastAPI only:

docker run --name finance-fastapi --rm -p 8000:8000 --env-file backend/.env -e APP_MODE=fastapi n8nproject2026/finance-ai-advisor:latest

Pyramid only:

docker run --name finance-pyramid --rm -p 6543:6543 --env-file backend/.env -e APP_MODE=pyramid n8nproject2026/finance-ai-advisor:latest

Stop the containers

docker stop finance-fastapi
docker stop finance-pyramid

Troubleshooting

• If the frontend shows Server returned non-JSON response (500), first confirm both backends are running.
• If Docker Desktop is used, create two containers, not one. One container should use APP_MODE=fastapi, and the other should use APP_MODE=pyramid.
• If AI upload/chat is used, make sure your runtime env file includes keys such as GOOGLE_API_KEY when needed.
• If you updated the image recently, pull again before starting:

docker pull n8nproject2026/finance-ai-advisor:latest

For users who want to build locally

docker build -f backend/Dockerfile -t finance-ai-advisor:latest .

For repository owners who want to publish updates

docker login
docker build -f backend/Dockerfile -t n8nproject2026/finance-ai-advisor:latest .
docker push n8nproject2026/finance-ai-advisor:latest

ML Workflow

The existing workflow is preserved:

1. Train the model locally
2. Save the model as a local artifact
3. Load the saved model
4. Send inputs for prediction
5. Return results as API responses instead of terminal-only output

Active model artifact:

• backend/finance_ai/ml_models/model.pkl

Training dataset:

• backend/finance_ai/ml_models/loan_status_prediction.csv

Local training

cd backend
.\venv\Scripts\python.exe .\finance_ai\ml_models\train_model.py
cd ..

Alternate script wrappers

python .\scripts\train_expense_model.py
python .\scripts\train_anomaly_model.py

These wrappers now call the shared ML workflow service and save artifacts using their current filenames.

FastAPI Endpoints

Health

• GET /health

Model status

• GET /api/v1/models/status

Train model

• POST /api/v1/models/train

Example body:

{
  "model_name": "loan_approval",
  "persist_model": true,
  "load_after_train": true
}

Load model

• POST /api/v1/models/load

Example body:

{
  "model_name": "loan_approval",
  "force_reload": false
}

Save loaded model

• POST /api/v1/models/save

Example body:

{
  "model_name": "loan_approval"
}

Predict

• POST /api/v1/predict

The API accepts both original column names and snake_case field names.

Example body:

{
  "ApplicantIncome": 5000,
  "CoapplicantIncome": 1500,
  "LoanAmount": 120,
  "Credit_History": 1
}

Postman-friendly example:

{
  "applicant_income": 5000,
  "coapplicant_income": 1500,
  "loan_amount": 120,
  "credit_history": 1
}

Postman Testing

Use:

• Method: POST
• URL: http://localhost:8000/api/v1/predict
• Header: Content-Type: application/json

Sample response shape:

{
  "status": "success",
  "message": "Prediction generated successfully",
  "data": {
    "prediction": "Approved",
    "probability_approved": 0.84
  }
}

Checks And Tests

Project checks:

.\scripts\run-tests.ps1

Focused backend test:

cd backend
.\venv\Scripts\python.exe -m unittest tests.test_fastapi_ml_api -v
cd ..

Ports

Common local ports:

• Pyramid backend: 6543
• FastAPI ML API: 8000
• React frontend: 5173

To inspect active ports:

Get-NetTCPConnection -State Listen | Sort-Object LocalPort | Select-Object LocalAddress, LocalPort, OwningProcess

Notes

• The original Pyramid backend was not replaced.
• FastAPI was added as a separate ML API layer for REST usage and later deployment.
• Model artifacts are stored locally and loaded from disk.
• The FastAPI layer is designed to be tested directly from Swagger UI or Postman.

AI.mp4