DepositGuide is a cutting-edge, multi-agent financial intelligence system designed to solve a ubiquitous problem: sub-optimal credit card repayment. By intelligently breaking down minimum payments, forecasting cash flow, and generating hyper-personalized deposit schedules, DepositGuide can mathematically reduce accrued interest by up to 33% per billing cycle.
Credit card statements are notoriously opaque, and the concept of "daily compounding interest" is widely misunderstood. Most consumers either pay the "Minimum Due" (which maximizes bank profits through interest) or they attempt to pay off the entire balance on the due date (which can still accrue massive interest if they carried a balance from the previous month).
DepositGuide solves this by identifying that depositing funds earlier in the billing cycle strictly reduces the average daily balance, thereby minimizing interest charges. The system autonomously reads your statement, analyzes your spending habits, and mathematically computes the perfect time to make partial deposits based on your actual liquidity constraints.
DepositGuide is powered by a sophisticated multi-agent pipeline mirroring modern AI research architectures:
- 📄 Statement Parsing Agent: Ingests opaque PDF or CSV statements from banks and extracts structured financial schemas (balances, APRs, dates).
- 👤 Behavioral Profiling Agent: Analyzes historical transaction velocity to infer salary cycles and discretionary spending habits.
- 🛒 Spending Insights & Bill Prediction Agent: Categorizes transactions, flags low-value "zombie" subscriptions, and forecasts recurring bills.
- 📈 Cash-Flow Forecast Agent: Merges behavioral profiles and bill predictions to project daily available liquidity limits.
- 🧮 Interest Computation Engine: A deterministic mathematical simulator calculating exact daily interest accruals based on the Average Daily Balance method.
- 🤖 Deposit Recommendation Agent: The optimization core. It executes a discrete search over feasible repayment schedules, constrained by the Cash-Flow Forecast, to find the exact two-installment schedule that minimizes interest.
- 📝 Statement Explainability Agent: Translates complex credit card legalese into plain-language summaries using Large Language Models (LLMs).
- 💬 Conversational Query Agent: A deeply grounded AI advisor that strictly answers user queries based on their internal financial context, refusing to hallucinate outside knowledge.
- 💾 Semantic Memory Agent (RAG): Automatically extracts user facts from chat and stores them in a vector database, enabling the AI advisor to remember personal context continuously.
- ✨ Interactive Dashboard: A glassmorphic, modern React interface displaying actionable insights, interactive Recharts comparisons, and the conversational AI.
- React 19 & Vite: Lightning-fast modern SPA development.
- Tailwind CSS: Utility-first styling for a sleek, dark-mode glassmorphic aesthetic.
- Recharts: Beautiful, responsive charting to visualize interest savings.
- Lucide-React: Clean, consistent SVG iconography.
- FastAPI: High-performance, async Python web framework.
- SQLModel & Alembic: Elegant ORM combining SQLAlchemy and Pydantic, with automated migrations.
- Google Gemini 2.5 (Flash): Ultra-fast LLM driving the Explainability and Conversational agents.
- Pytest: Rigorous end-to-end integration testing proving the mathematical models.
- PostgreSQL: Production-grade relational database.
- Docker Compose: Seamless local container orchestration.
- GitHub Actions: Automated CI pipeline running linting, builds, and Pytest suites.
The easiest way to run the entire system is via Docker Compose.
- Docker installed on your machine.
- A Google Gemini API Key.
- Clone the repository:
git clone https://github.com/SadeeshaJayaweera/DepositGuide.git cd DepositGuide - Export your Gemini API key:
export GEMINI_API_KEY="your-gemini-api-key"
- Boot the stack:
docker compose up --build
- Access the beautiful React dashboard at
http://localhost:3000and the backend API athttp://localhost:8000.
DepositGuide is built for modern cloud platforms:
- Backend (Render / Fly.io): We provide a
render.yamlblueprint to easily provision a managed PostgreSQL instance alongside the FastAPI web service. - Frontend (Vercel): A
vercel.jsonconfiguration is included to effortlessly deploy the Vite SPA with proper client-side routing.
For detailed instructions, refer to the DEPLOYMENT.md guide.
While the mathematical engine (Equation 2) has been rigorously tested in CI/CD to prove the ~33% interest reduction, the system currently operates on simulated user data.
Next Steps:
- User Studies: Conduct empirical validation through large-scale user studies to measure actual adherence to the recommended two-installment schedules.
- Deep Learning Profiling: Upgrade the Behavioral Profiling Agent with advanced time-series models to predict non-linear spending habits more accurately.
- Plaid Integration: Connect directly to live bank APIs (e.g., via Plaid) to synchronize real-time cash flow instead of relying solely on uploaded credit card histories.