Anotamelo

Bot de gastos conversacional sobre FastAPI. El producto actual combina:

• WhatsApp Cloud API como canal principal y Telegram Bot API como canal adicional para chats privados de texto, audio e imágenes
• LLM configurable para interpretación
• PostgreSQL como storage operativo de gastos y metadata relacional
• OCR de tickets por imagen con extracción de monto y comercio
• presupuestos por categoría con alertas por desvío y gasto inusual
• insights conversacionales para comparativas y detección de gastos repetidos
• proyecciones de ahorro por escenarios manuales o recortes sobre histórico
• seguimiento de cuotas/deudas y lectura educativa personalizada
• Google Sheets solo como fuente legacy para importar histórico

Punto de entrada

• Setup local: docs/setup/local.md
• Guía de Groq para audios: docs/setup/groq-api-key.md
• Estado actual de arquitectura: docs/architecture/current-state.md
• Deploy en Render: docs/deploy/render.md
• Readiness histórico con Supabase: docs/deploy/supabase.md

SDD

La fuente viva para features, specs, diseño y task plans es sdd/.

• Config del proyecto: sdd/PROJECT.md
• Features activas: sdd/wip

openspec/ queda como material histórico en transición. Ver openspec/README.md.

Desarrollo rápido

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000

Importación legacy

Si necesitás pasar histórico viejo desde Google Sheets a DB:

python scripts/import_expenses_from_sheets.py --dry-run
python scripts/import_expenses_from_sheets.py --phone 5491123456789

Webhook

• Verificación: GET /webhook
• Recepción: POST /webhook
• Telegram: POST /telegram/webhook

Para producción, además de WHATSAPP_VERIFY_TOKEN, configurá WHATSAPP_APP_SECRET para validar la firma X-Hub-Signature-256 de Meta. Para Telegram configurá TELEGRAM_BOT_TOKEN + TELEGRAM_WEBHOOK_SECRET; el canal actual soporta chats privados de texto, audio e imágenes. El rate limit actual es local por proceso y no requiere Redis para el deploy mínimo.

Planes

• FREE: hasta 5 audios por semana y hasta 3 reportes PDF por mes.
• PREMIUM: audio y reportes sin límite.
• Las cuotas usan semana/mes calendario en la timezone efectiva del usuario.

Tiempo y zonas horarias

• La base persiste timestamps en UTC.
• La app infiere la zona horaria local del usuario a partir del prefijo internacional del número de WhatsApp.
• Si la identidad no trae teléfono, usa DEFAULT_USER_TIMEZONE.
• Las fechas y horas que se muestran al usuario se renderizan en esa zona horaria resultante.