🤖 Telegram Income Bot

Bot de Telegram orientado a clases particulares que entiende lenguaje natural, registra ingresos y gestiona agenda en Google Calendar/Sheets usando un LLM orquestado con herramientas específicas.

📺 Demo

Video corto: https://youtu.be/x_u1HeXIj40

Qué hace

• NLP con LLM + tools: entiende frases como “el viernes de 14 a 16 clase en instituto”.
• Registro de ingresos en Google Sheets: crea filas, ordena por mes y actualiza métricas automáticamente.
• Gestión de medios: precios por hora por origen (Instituto, Particular, Facultad, etc.).
• Agenda en Google Calendar: crear, listar, resolver, actualizar y eliminar eventos por referencias humanas (día relativo + hora). Nueva capa de logs estructurados para cada tool/servicio de calendario.
• Confirmaciones seguras: acciones críticas usan pendientes con botones en Telegram.
• Listo para contenedores: Docker/Docker Compose para levantar backend + webhook.

Stack

• Python 3.11, FastAPI, SQLAlchemy (aiosqlite)
• LLM: OpenAI GPT-4o-mini (configurable)
• Integraciones: Telegram Bot API, Google Sheets API, Google Calendar API
• Infra: Docker, Docker Compose

Arquitectura rápida

• app/chat: orquestación LLM, memoria corta y prompts.
• app/tools: “functions” que el LLM puede invocar (incomes, medios, calendar).
• app/services: wrappers para Google Sheets/Calendar y Telegram.
• app/api: endpoints FastAPI (health, telegram webhook, calendar helpers).

Configuración

1. Copiá .env.example a .env y completá:
   • Telegram: TELEGRAM_BOT_TOKEN, TELEGRAM_WEBHOOK_SECRET, WEBHOOK_BASE_URL
   • OpenAI: OPENAI_API_KEY, OPENAI_MODEL
   • Google: GOOGLE_SHEETS_ID, GOOGLE_SHEETS_KEY_FILE, GOOGLE_CALENDAR_ID, GOOGLE_CALENDAR_KEY_FILE (puede reutilizarse el de Sheets)
2. Colocá la clave JSON del Service Account en la ruta indicada por la variable *_KEY_FILE (ej. ./secrets/clasesbot-key.json).

Cómo correrlo rápido

Opción contenedores:

docker-compose up --build

Opción local (sin Docker):

python -m venv .venv
.venv\Scripts\activate  # Windows
pip install -r requirements.txt
uvicorn app.main:app --reload

Configura el webhook de Telegram apuntando a WEBHOOK_BASE_URL/api/telegram/webhook (Caddy/NGINX o túnel tipo localtunnel/ngrok).

Notas de observabilidad

• Logging unificado (app logger). Las tools de Calendar ahora registran inputs, rangos y resultados (ok, ambiguo, not_found, error) para depurar flujos como “resolve/update/delete”.

Licencia

Uso personal/educativo. Ajusta según tus necesidades.***