Stop paying the interest tax.
FinOps Engine turns your debt portfolio into a mathematically optimal payoff plan — then lets an AI advisor reason over it in plain English.
Features · Architecture · Quick Start · API Docs · DevSecOps · Roadmap
FinOps Engine is a personal finance tool built at the intersection of software engineering, AI, and DevSecOps. It combines a deterministic debt math engine with an agentic AI advisor that reasons across your actual portfolio.
| Layer | What It Does | Why It Matters |
|---|---|---|
| Math Engine | Full amortization — daily compounding, promo APRs, prepayment penalties | 100% deterministic, no approximation |
| Agentic AI | Claude Sonnet calls tools autonomously before answering | Grounded answers, not hallucinations |
| RAG Pipeline | Semantic search over bank Terms & Conditions PDFs | Cites the actual clause, not the internet |
| DevSecOps | Bandit + pip-audit + Docker + Prometheus on every build | Production-grade from day one |
Two mathematically sound repayment strategies, run side-by-side with a full month-by-month schedule:
| Strategy | Attack Order | Best For |
|---|---|---|
| Debt Avalanche | Highest APR first | Minimising total interest paid |
| Debt Snowball | Smallest balance first | Psychological momentum |
The engine supports the full range of real-world loan terms:
- Daily or monthly compounding — matches how credit cards actually accrue interest
- Percent-of-balance minimums — minimum shrinks as the balance falls (credit-card style)
- Promotional / intro APRs — 0% balance-transfer offers with a countdown
- Variable-rate schedules — ARM-style rate jumps at a specified month
- Prepayment penalties — flat or percent-of-balance, with an optional window
The "Ask AI" tab connects to Claude claude-sonnet-4-6 via Anthropic's native tool-use API. The agent drives a multi-turn reasoning loop — it decides autonomously which tools to call and chains results before answering.
User → "Which of my debts should I pay first, and what will I save?"
Agent → [calls get_user_debts] ← loads your portfolio
→ [calls run_avalanche_scenario] ← runs exact payoff math
→ [calls lookup_fee_clause] ← checks T&C for penalty clauses
→ Final answer with cited numbers and source page references
Three tools available to the agent:
| Tool | What It Does |
|---|---|
get_user_debts |
Returns the user's loaded portfolio as structured data |
run_avalanche_scenario |
Runs Avalanche / Snowball / compare against the Python engine |
lookup_fee_clause |
Semantic search over indexed bank T&C PDFs |
Prompt caching is applied to the system prompt and tool definitions — repeated questions within the 5-minute TTL window cost significantly fewer tokens.
The Streamlit UI supports 9 currencies out of the box: USD, EUR, GBP, AUD, CAD, JPY, INR, SGD, and LKR. All balances, interest totals, and chart labels update automatically.
Upload any bank Terms & Conditions PDF via POST /index-pdf. The document is chunked, embedded with sentence-transformers, and stored in ChromaDB. The agent's lookup_fee_clause tool then retrieves relevant clauses at query time — so answers about fees, penalty APRs, and grace periods are grounded in the actual document.
┌─────────────────────────────────────────────────────────┐
│ Streamlit UI (app.py) │
│ Manual Input │ Upload CSV │ Ask AI │
└──────────────────────┬──────────────────────────────────┘
│ Python imports
┌──────────────────────▼──────────────────────────────────┐
│ FastAPI Backend :8000 │
│ │
│ /analyze /analyze/csv /ask /index-pdf │
│ │ │ │ │ │
│ ┌───▼────┐ ┌────▼───┐ ┌──▼──────┐ │ │
│ │ Debt │ │ CSV │ │Agentic │ │ │
│ │ Engine │ │ Parser │ │Advisor │ │ │
│ └───┬────┘ └────────┘ └──┬──────┘ │ │
└───────┼─────────────────────┼──────────┼───────────────┘
│ │ │
│ ┌──────▼──────┐ │
│ │ Anthropic │ │
│ │ Claude API │ │
│ └─────────────┘ │
│ │
│ ┌────────────────▼──────────┐
│ │ ChromaDB (local persist) │
│ │ Bank PDF embeddings │
│ └───────────────────────────-┘
│
Pure Python math
(no external dep)
Manual input / CSV upload
│
▼
src/ingestor/parser.py ──► list[Debt]
│
▼
src/engine/avalanche.py ──► Avalanche plan ──► JSON / Streamlit UI
└──► Snowball plan ──► JSON / Streamlit UI
User question (Ask AI tab)
│
▼
src/rag/agent.py ──► multi-turn tool loop ──► grounded answer + trace
AI-powered-Personal-Finance-Optimization-Engine/
│
├── app.py # Streamlit UI entry point
│
├── src/
│ ├── api/
│ │ └── main.py # FastAPI app (5 endpoints + Prometheus)
│ ├── engine/
│ │ └── avalanche.py # Full amortization math engine
│ ├── ingestor/
│ │ └── parser.py # CSV bank statement parser
│ └── rag/
│ ├── agent.py # Anthropic tool-use agentic loop
│ └── knowledge_base.py # ChromaDB PDF indexing & search
│
├── tests/
│ ├── test_avalanche.py # Financial math unit tests
│ ├── test_api.py # FastAPI endpoint tests
│ ├── test_agent.py # Agent tool dispatch tests
│ └── test_ingestor.py # CSV parser tests
│
├── .github/
│ └── workflows/
│ └── ci.yml # Lint → Security → Test → Docker build
│
├── Dockerfile # Non-root, multi-stage container
├── docker-compose.yml # App + Prometheus
├── prometheus.yml # Prometheus scrape config
├── requirements.txt # All dependencies pinned
├── pyproject.toml # pytest + bandit config
├── .env.example # Template — never commit .env
└── LICENSE # MIT
- Python 3.11+
- An Anthropic API key (for the Ask AI tab and
/askendpoint) - Docker & Docker Compose (optional — for containerised deployment)
git clone https://github.com/Nethmini-Rathnayake/AI-powered-Personal-Finance-Optimization-Engine.git
cd AI-powered-Personal-Finance-Optimization-Enginecp .env.example .env
# Edit .env and add your key:
# ANTHROPIC_API_KEY=sk-ant-...python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# Start the Streamlit UI
streamlit run app.pyOpen http://localhost:8501 — the UI loads immediately. The Ask AI tab activates once ANTHROPIC_API_KEY is set.
uvicorn src.api.main:app --reload --port 8000| Service | URL |
|---|---|
| API | http://localhost:8000 |
| Swagger UI | http://localhost:8000/docs |
| Prometheus metrics | http://localhost:8000/metrics |
docker compose up --buildThis starts the FastAPI backend on :8000 and Prometheus on :9090.
Run Avalanche (and optionally Snowball) on a JSON debt list.
// Request
{
"debts": [
{
"name": "Chase Sapphire",
"balance": 5400,
"apr": 0.2399,
"min_payment": 50,
"compounding": "daily",
"promo_apr": 0.0,
"promo_months": 6
},
{
"name": "Student Loan",
"balance": 15000,
"apr": 0.0675,
"min_payment": 150
}
],
"monthly_budget": 600,
"compare_with_snowball": true
}
// Response (compare_with_snowball=true)
{
"avalanche": {
"months_to_payoff": 38,
"total_interest_paid": 1842.17,
"total_penalties_paid": 0.0,
"payoff_order": ["Chase Sapphire", "Student Loan"],
"schedule": [...]
},
"snowball": { ... },
"interest_saved_by_avalanche": 63.44,
"months_saved_by_avalanche": 1
}Upload a CSV file and receive an Avalanche payoff plan.
Required CSV columns: name, balance, apr (decimal, e.g. 0.2399), min_payment
curl -X POST http://localhost:8000/analyze/csv \
-F "file=@my_debts.csv" \
-F "monthly_budget=600"Ask the agentic AI advisor a natural-language question.
// Request
{
"question": "Which of my debts should I prioritise, and what will I save?",
"debts": [
{ "name": "Chase Sapphire", "balance": 5400, "apr": 0.2399, "min_payment": 50 },
{ "name": "Student Loan", "balance": 15000, "apr": 0.0675, "min_payment": 150 }
]
}
// Response
{
"answer": "Based on the Avalanche strategy with a $600 budget, you should prioritise Chase Sapphire (23.99% APR)...",
"tool_trace": [
{ "tool": "get_user_debts", "input": {}, "result": {...} },
{ "tool": "run_avalanche_scenario", "input": {...}, "result": {...} }
]
}Index a bank Terms & Conditions PDF into ChromaDB.
curl -X POST http://localhost:8000/index-pdf \
-F "file=@Chase_CC_Terms_2024.pdf"
# Response
{ "status": "indexed", "chunks": 142, "file": "Chase_CC_Terms_2024.pdf" }Liveness probe — returns {"status": "ok"}.
Every push to main triggers the full CI pipeline:
Push / Pull Request
│
▼
┌─────────────────────────────┐
│ Security Scan │
│ ├── bandit (SAST) │
│ └── pip-audit (CVE check) │
└──────────┬──────────────────┘
│ PASS
▼
┌─────────────────────────────┐
│ Test Suite │
│ └── pytest -v │
└──────────┬──────────────────┘
│ PASS
▼
┌─────────────────────────────┐
│ Docker Build │
│ └── Build & tag image │
└─────────────────────────────┘
Security principles:
- No hardcoded secrets — API key loaded from
.env, never committed - Non-root Docker container — runs as
appuser(principle of least privilege) - Pinned dependencies — all versions locked in
requirements.txt - SAST on every push — Bandit scans for Python security issues
- CVE auditing — pip-audit checks packages against known vulnerabilities
- Prometheus observability — request latency and error rates tracked at
/metrics
# Full test suite
pytest tests/ -v
# Financial math only
pytest tests/test_avalanche.py -v
# API endpoint tests
pytest tests/test_api.py -v
# Run security scan locally
bandit -r src/
pip-audit -r requirements.txt| Category | Technology | Purpose |
|---|---|---|
| Language | Python 3.11 | Core runtime |
| UI | Streamlit + Plotly | Interactive dashboard with charts |
| API Framework | FastAPI + Uvicorn + Pydantic | REST endpoints + auto Swagger docs |
| AI Agent | Anthropic SDK (Claude claude-sonnet-4-6) | Multi-turn tool use with prompt caching |
| Debt Math | Pure Python | Deterministic full amortization engine |
| Vector Store | ChromaDB + sentence-transformers | Embedding storage & semantic search |
| PDF Parsing | pypdf + pymupdf | Bank T&C document ingestion |
| Observability | Prometheus | Request metrics via FastAPI instrumentator |
| Containerization | Docker + Compose | Reproducible environments |
| CI/CD | GitHub Actions | Automated security → test → build pipeline |
| SAST | Bandit | Python static security analysis |
| Dependency Audit | pip-audit | CVE checks on all packages |
- Avalanche & Snowball optimizer with full amortization
- Daily/monthly compounding, promo APRs, prepayment penalties
- Agentic AI advisor (Anthropic tool use, multi-turn reasoning)
- RAG knowledge base (ChromaDB + bank T&C PDFs)
- Streamlit UI with interactive Plotly charts
- Multi-currency support (USD, EUR, GBP, AUD, CAD, JPY, INR, SGD, LKR)
- FastAPI backend with CSV upload
- Dockerized with Prometheus observability
- CI/CD with SAST and CVE scanning
- Plaid API integration — live bank account syncing
- React dashboard — replace Streamlit for production deployments
- Scheduler — monthly automated payoff progress reports
# 1. Fork the repo and clone your fork
git clone https://github.com/Nethmini-Rathnayake/AI-powered-Personal-Finance-Optimization-Engine.git
# 2. Create a feature branch
git checkout -b feat/your-feature-name
# 3. Install dependencies and run tests
pip install -r requirements.txt
pytest tests/ -v
# 4. Commit using Conventional Commits
git commit -m "feat: add your feature"
# 5. Push and open a Pull Request
git push origin feat/your-feature-nameDistributed under the MIT License. See LICENSE for details.
Built by Nethmini Rathnayake
Demonstrating Software Engineering + AI + DevSecOps skills in the Fintech domain
Star this repo if it helped you — it means a lot!