Telegram Expenses Bot

A modular, AI-powered bot to track and manage expenses via Telegram. It uses LLMs to extract structured data from text, images, and audio, and persists them for easy reporting.

Key Features

🤖 AI Extraction: Automatically parses amount, currency, description, and date from natural language.
🖼️ Multimodal: Supports text, images (receipts), and audio (voice notes) - in progress.
📊 Structured Storage: Saves data to a database with support for exporting to CSV/Google Sheets.
🛡️ Audit Trail: Keeps track of raw inputs and AI confidence scores for reliability.
🐳 Dockerized: Easy deployment using Docker and Docker Compose.

Project Structure

The project has transitioned to a more robust, service-oriented architecture located in the /app directory.

/app: Core application logic.
- /ai: LLM integration, prompts, and extraction logic.
- /audit: Logging and raw data storage for traceability.
- /ingestion: Handlers for different input types (text, image, audio, document).
- /integrations: External services (e.g., exporters, webhook clients).
- /modules: Telegram bot command handlers (/start, /status, etc.).
- /persistence: Database models and repositories (SQLAlchemy).
- /preprocessing: Data cleaning, validation, and language detection.
- /schema: Pydantic models for data validation and API documentation.
- main.py: FastAPI entry point and webhook handlers.
- router.py: Orchestrates the processing pipeline.
/config: Static configuration files (keywords, providers).
/src: Legacy/Initial implementation (Phase 1 & 2).
tasks.md: Detailed project roadmap and progress tracker.

How It Works (Workflow)

Input: The user sends a message to the Telegram bot (text, image, or voice).
Ingestion: The bot receives the update and passes it to the /app/ingestion layer to extract raw text.
Routing: router.py takes the raw text and coordinates the next steps.
Extraction: The /app/ai/extractor.py uses OpenAI's GPT models to parse the text into a structured ExtractedExpense.
Audit & Classify: The /app/ai/classifier.py assigns categories and a confidence score.
Persistence: If confidence is high, the expense is automatically saved via /app/persistence/repositories.py. If low, it awaits manual confirmation.

Project Status

Current Phase: Phase 3/4 - Intelligence & Processing

Phase 1: Infrastructure: FastAPI, Docker, and basic input handling.
Phase 2: Data Models: Explicit expense states and Pydantic schemas.
[/] Phase 3: Logic: Configuration loaders and provider matching (In Progress).
[/] Phase 4: AI Analyst: Multimodal extraction and confidence scoring (In Progress).

Setup & Development

1. Environment Variables

Copy .env.example to .env and fill in your credentials:

TELEGRAM_TOKEN=your_bot_token
OPENAI_API_KEY=your_openai_key
DATABASE_URL=mysql+pymysql://user:password@db:3306/expenses

# MySQL specific (for Docker)
MYSQL_ROOT_PASSWORD=root_password
MYSQL_DATABASE=expenses
MYSQL_USER=user
MYSQL_PASSWORD=password

2. Run with Docker

docker-compose up --build

3. Local Development (FastAPI)

pip install -r requirements.txt
uvicorn app.main:app --reload

4. Running the Bot (Polling)

For local testing without webhooks, you can run a polling script that uses the handlers in app/modules.

Maintained by Marco Gallegos

3.5 KiB Raw Blame History