An intelligent personal finance assistant powered by AI
Track expenses and income, generate reports, and set reminders — all through natural language conversations in your preferred language.
- Overview
- Key Features
- Technology Stack
- Installation
- Configuration
- Usage
- Project Structure
- Architecture
- Contributing
- License
- Author
SmartExpenseBot is a sophisticated Telegram bot that makes personal finance management effortless. Instead of filling out forms, users can simply chat with the bot — in text or voice — to record expenses, check balances, and receive intelligent financial reports.
Powered by DeepSeek AI and advanced NLP, the bot understands context across Uzbek, Russian, and English.
- AI-Powered Intelligence — Four specialized AI instances handle parsing, categorization, reporting, and reminders.
- Universal Language Support — Full support for English, Russian, and Uzbek with intelligent country detection.
- Voice-First Design — Record expenses and income via voice messages with automatic transcription.
- Smart Automation — Automated daily reminders at personalized times.
- Intelligent Reporting — Ask natural language questions for instant financial insights and balance summaries.
- Income Tracking — Track monthly and daily income alongside expenses.
- Unified Currency System — Single currency preference for all financial operations.
- Privacy-Focused — Local SQLite database by default, with optional PostgreSQL support.
| Component | Technology |
|---|---|
| Bot Framework | python-telegram-bot |
| AI / NLP | DeepSeek AI |
| Database | SQLite (default) / PostgreSQL (optional) |
| Scheduling | APScheduler |
| Language | Python 3.8+ |
- Python 3.8 or higher
- A Telegram Bot Token from @BotFather
- DeepSeek AI API key
# Clone the repository
git clone https://github.com/BotirBakhtiyarov/SmartExpenseBot.git
cd SmartExpenseBot
# Create a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure environment variables
cp .env.example .env
# Edit .env with your Telegram token and DeepSeek API key
# Run the bot
python main.pyCreate a .env file with the following variables:
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
DEEPSEEK_API_KEY=your_deepseek_api_key
DATABASE_URL=sqlite:///expenses.dbFor PostgreSQL, set:
DATABASE_URL=postgresql://user:password@localhost:5432/smartexpenseStart a conversation with your bot on Telegram and try:
I spent 50,000 UZS on lunch todayShow my monthly reportRemind me about rent every 1st dayHow much did I earn this month?
SmartExpenseBot/
├── bot/ # Telegram bot handlers and dialogs
├── ai/ # DeepSeek AI integration modules
├── database/ # Database models and migrations
├── services/ # Business logic (reports, reminders, parsing)
├── config.py # Configuration management
├── main.py # Application entry point
├── requirements.txt # Python dependencies
├── .env.example # Environment variable template
└── README.md
SmartExpenseBot uses a modular pipeline architecture:
- Input Layer — Receives text or voice messages from Telegram.
- AI Parsing Layer — DeepSeek AI extracts amount, category, date, and type.
- Storage Layer — Saves transactions to SQLite or PostgreSQL.
- Reporting Layer — Generates summaries and answers natural language queries.
- Scheduler Layer — Sends reminders at configured times.
Contributions are welcome!
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -m 'Add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
Please follow PEP 8 style guidelines.
This project is licensed under the MIT License — see the LICENSE file for details.
Botir Bakhtiyarov
- Email: hello@bbotir.xyz
- Website: https://bbotir.xyz
- Telegram: @opensource_uz