mirror of
https://github.com/marcogll/telegram_expenses_controller.git
synced 2026-01-13 21:35:15 +00:00
82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
# 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)
|
|
|
|
1. **Input**: The user sends a message to the Telegram bot (text, image, or voice).
|
|
2. **Ingestion**: The bot receives the update and passes it to the `/app/ingestion` layer to extract raw text.
|
|
3. **Routing**: `router.py` takes the raw text and coordinates the next steps.
|
|
4. **Extraction**: The `/app/ai/extractor.py` uses OpenAI's GPT models to parse the text into a structured `ExtractedExpense`.
|
|
5. **Audit & Classify**: The `/app/ai/classifier.py` assigns categories and a confidence score.
|
|
6. **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**
|
|
|
|
- [x] **Phase 1: Infrastructure**: FastAPI, Docker, and basic input handling.
|
|
- [x] **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:
|
|
```bash
|
|
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
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
### 3. Local Development (FastAPI)
|
|
```bash
|
|
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*
|