Kasflow 🤖

Kasflow (or Cashflow) is an AI-powered Telegram bot for personal expense tracking, reporting and insights.

Disclaimer:
- For fun and personal use only.
- Do not send sensitive data to the bot (e.g. credit card numbers, passwords, etc).
- Currently no managed hosting solution, so you have to host and run yourself.
- Feel free to fork and extend to suite your need. Contributions to this project are always welcomed.

👉 Features:

• Record your expenses in natural language (tested on English and Indonesian).
• Multi-turn conversations.
• Can be added to Group (for group expense tracking).
• Choose SQLite or PostgreSQL as database backend.
• Telegram command to list all expenses.

👉 Why built this?

Recently I stumbled upon Langgraph for AI application development. Keen to try it out myself and to build a real project that I'll actually use is the most fun way to learn. Develop an expense tracking bot on Telegram platform seems like good and viable idea.

👉 Limitations:

• Tested only on conversation in English and Indonesian. Let me know it it works with your language too.
• Tested only on GPT-4.1-* models, may or may not work on other models and providers.
• Limited Telegram commands (more added soon).
• Uses very basic RAG system, might not perform well on large expense records.

👉 Tech stack:

• Python Telegram Bot
• LangGraph (LLM workflows orchestration)
• OpenAI API (LLM provider)
• SQLite or PostgreSQL (expense records database)

Setup

Option 1: Local Development

Make sure you have UV installed.

1. Install dependencies:

make deps

2. Create a .env file (see .env.example):

# Required environment variables:
BOT_TOKEN=your-telegram-token
OPENAI_API_KEY=your-openai-api-key

3. Run Database migrations:

make migrate

4. Run the bot:

# Run in polling mode (default)
make run

Option 2: Docker

1. Create a .env file with your configuration:

# Required environment variables:
BOT_TOKEN=your-telegram-token
OPENAI_API_KEY=your_openai_api_key_here

2. Build and run with Docker Compose:

docker-compose up