Kairos Finance 💰

Intelligent Financial Analytics Platform
Transform your bank statements into actionable insights with AI-powered analytics

Kairos Finance is a modern, AI-powered financial analytics platform that helps you understand your spending patterns, track expenses, and make informed financial decisions. Upload your bank statements and get instant insights through beautiful visualizations and natural language queries.

✨ Key Features

🤖 AI-Powered Intelligence

• Natural Language Queries: Ask questions like "How much did I spend on food last month?"
• Smart Insights: Get personalized financial recommendations
• Contextual Analysis: AI understands your spending context and patterns

📊 Advanced Analytics

• Category Breakdown: Visualize spending across categories with interactive ring charts
• Monthly Trends: Track income and expenses over time
• Merchant Analysis: See where your money goes by merchant and platform
• Drill-Down Reports: Multi-level analysis from categories to individual transactions

🏦 Bank Statement Processing

• Automatic Parsing: Support for SBI (Excel/CSV) with extensible parser framework
• Smart Categorization: Automatic transaction categorization using ML
• Merchant Detection: Identifies merchants and platforms (Swiggy, Amazon, etc.)
• Multiple Statements: Upload and manage multiple bank statements

🎨 Modern User Experience

• Responsive Design: Works seamlessly on desktop, tablet, and mobile
• Dark Mode: Easy on the eyes with beautiful dark theme
• Interactive Charts: Click to drill down into your data
• Real-time Updates: See changes instantly as you upload statements

🚀 Quick Start

Prerequisites

• Python 3.9+
• Node.js 20.9.0+
• PostgreSQL 12+

Installation

1. Clone the repository

   git clone https://github.com/pgokul695/Kairos.git
   cd Kairos

2. Follow the complete setup guide

   # See SETUP.md for detailed instructions
   cat SETUP.md

3. Quick setup (if you have all prerequisites)

   Backend:

   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   cp .env.example .env
   # Edit .env with your database credentials
   python database.py
   python main.py

   Frontend (in a new terminal):

   cd frontend/kairos
   npm install
   cp .env.example .env.local
   # Edit .env.local with your API keys
   npm run dev

4. Access the application

   • Frontend: http://localhost:4017
   • Backend API: http://localhost:8000
   • API Docs: http://localhost:8000/docs

📖 Documentation

• Complete Setup Guide - Step-by-step installation instructions
• Backend Documentation - API reference and backend details
• Frontend Documentation - UI components and customization

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Kairos Finance                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────┐         ┌──────────────────┐        │
│  │   Frontend       │         │    Backend       │        │
│  │   (Next.js)      │◄───────►│   (FastAPI)      │        │
│  │                  │  REST   │                  │        │
│  │  - Dashboard     │   API   │  - Parsers       │        │
│  │  - Analytics     │         │  - Analytics     │        │
│  │  - AI Chat       │         │  - Auth          │        │
│  └──────────────────┘         └──────────────────┘        │
│         │                              │                   │
│         │                              │                   │
│         ▼                              ▼                   │
│  ┌──────────────────┐         ┌──────────────────┐        │
│  │  Thesys C1 API   │         │   PostgreSQL     │        │
│  │  (AI Engine)     │         │   (Database)     │        │
│  └──────────────────┘         └──────────────────┘        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🛠️ Tech Stack

Backend

• FastAPI: Modern Python web framework
• PostgreSQL: Robust relational database
• SQLAlchemy: SQL toolkit and ORM
• Pandas: Data manipulation and analysis
• OpenPyXL: Excel file processing

Frontend

• Next.js 15: React framework with App Router
• React 19: UI library
• TypeScript: Type-safe JavaScript
• Tailwind CSS: Utility-first CSS framework
• Thesys C1: AI-powered chat interface

📊 Supported Banks

Currently supported:

• ✅ State Bank of India (SBI) - Excel (.xlsx, .xls), CSV (.csv)
• ✅ Synthetic Data - JSON format for testing

Coming soon:

• 🔄 HDFC Bank
• 🔄 ICICI Bank
• 🔄 Axis Bank
• 🔄 Kotak Mahindra Bank

Want to add support for your bank? See Adding New Bank Parsers

🎯 Use Cases

Personal Finance Management

• Track monthly expenses and income
• Identify spending patterns
• Set and monitor budgets
• Analyze spending by category

Financial Planning

• Understand where your money goes
• Identify areas to save
• Track investment contributions
• Monitor recurring expenses

Tax Preparation

• Categorize deductible expenses
• Track business expenses
• Generate expense reports
• Export transaction data

Business Analytics

• Analyze business cash flow
• Track vendor payments
• Monitor revenue streams
• Generate financial reports

🔒 Security & Privacy

• Local Data Storage: All data stored in your own PostgreSQL database
• Session-based Auth: Secure cookie-based authentication
• No Data Sharing: Your financial data never leaves your server
• Encrypted Connections: HTTPS support for production deployments
• Configurable Access: Control who can access your instance

🚢 Deployment

Development

# Backend
cd backend && python main.py

# Frontend
cd frontend/kairos && npm run dev

Production

Backend:

gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Frontend:

npm run build && npm start

See detailed deployment guides:

• Backend Deployment
• Frontend Deployment

Docker (Coming Soon)

docker-compose up -d

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report Bugs: Open an issue with details
2. Suggest Features: Share your ideas
3. Add Bank Parsers: Support more banks
4. Improve Documentation: Help others get started
5. Submit Pull Requests: Fix bugs or add features

Development Setup

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastAPI: For the amazing Python web framework
• Next.js: For the powerful React framework
• Thesys: For the AI-powered chat capabilities
• PostgreSQL: For reliable data storage
• Open Source Community: For inspiration and tools

📧 Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: pgokul695@users.noreply.github.com

🗺️ Roadmap

Version 1.1 (Current)

• SBI bank statement parsing
• Basic analytics dashboard
• AI-powered chat interface
• Category and merchant analysis

Version 1.2 (In Progress)

• Support for more banks (HDFC, ICICI, Axis)
• Budget tracking and alerts
• Export reports (PDF, Excel)
• Multi-user support

Version 2.0 (Planned)

• Mobile app (React Native)
• Recurring transaction detection
• Bill payment reminders
• Investment tracking
• Goal setting and tracking
• Financial health score

Future

• Bank account integration (read-only API)
• Credit card statement support
• Multi-currency support
• Advanced ML predictions
• Collaborative features for families

⭐ Star History

If you find Kairos Finance useful, please consider giving it a star! ⭐

📸 Screenshots

Dashboard

Analytics

AI Chat

Transaction Details

---

Built with ❤️ for better financial insights

Documentation • Report Bug • Request Feature