README.md

metadata

title: Bot Fam
emoji: 🐨
colorFrom: gray
colorTo: purple
sdk: docker
pinned: false

Bot Fam

Space Docker para inventario del hogar con FastAPI, SQLite, Telegram, Claude Haiku y Whisper tiny local.

Stack

• FastAPI asíncrono como backend operativo.
• SQLite como base principal del servicio.
• faster-whisper con modelo tiny dentro del contenedor.
• Telegram como canal principal para registrar, consumir y consultar.
• Claude Haiku para estructurar texto, buscar registros y armar diagramas.
• Google Sheets + Apps Script solo como respaldo opcional e idempotente.

Estructura

• python_backend/: backend principal en Python.
• google-apps-script/: código que va en Apps Script dentro de Google Sheets.
• docs/: arquitectura.
• Dockerfile: imagen lista para Hugging Face Spaces.

Variables de entorno

Archivos plantilla:

• python_backend/.env.example
• python_backend/.env.huggingface.example

En Hugging Face Spaces no subes .env. Debes copiar esos valores a Settings > Variables and secrets.

Variables clave

• APP_BASE_URL: URL final del Space, por ejemplo https://JairoDanielMT-bot-fam.hf.space
• SQLITE_PATH: usar /data/inventario.sqlite si tienes almacenamiento persistente.
• ANTHROPIC_MODEL: usa un modelo explícito estable, por ejemplo claude-haiku-4-5.
• WHISPER_MODEL: por defecto tiny.
• WHISPER_DEVICE: cpu.
• WHISPER_COMPUTE_TYPE: int8.
• SHEETS_SYNC_ENABLED: activa o apaga el respaldo a Google Sheets sin afectar la operación principal.
• BOOTSTRAP_FROM_SHEETS: si es true, importa desde Sheets solo cuando SQLite aún está vacío.
• SYNC_INTERVAL_SECONDS: frecuencia del intento de sincronización en segundo plano.
• REMINDER_HOUR y REMINDER_MINUTE: horario del aviso diario en TIMEZONE. El default actual es 05:00.
• EXPIRY_WARNING_DAYS: ventana de alerta de vencimiento.
• MEMORY_SHORT_LIMIT: cantidad de turnos recientes que el bot conserva por chat.

Flujo principal

1. Telegram recibe texto o audio.
2. Si llega audio, el contenedor lo transcribe localmente con Whisper tiny.
3. Claude Haiku convierte texto libre a datos estructurados o responde consultas.
4. SQLite guarda productos, movimientos, memoria conversacional y tareas pendientes.
5. Google Sheets se actualiza como respaldo desde una cola local de sincronización.
6. El scheduler diario envía alertas de vencimiento por Telegram a la hora local configurada.

Telegram

No necesitas comandos para el uso normal. El bot entiende lenguaje natural, por ejemplo:

• compré leche gloria 6 unidades a 4.2 vence el 10 de abril
• consumimos 2 unidades de leche gloria
• qué productos vencen esta semana
• cuánto arroz queda
• hazme un gráfico del stock

También puede seguir aceptando comandos como compatibilidad:

• /registrar ...
• /consumir ...
• /buscar ...
• /diagrama ...
• /vencimientos
• /stock ...

Webhook de Telegram

Cuando el Space ya esté arriba y APP_BASE_URL apunte a la URL final:

curl -X POST https://TU-SPACE.hf.space/telegram/set-webhook

Ese endpoint registra automáticamente:

• https://TU-SPACE.hf.space/telegram/webhook

Sincronización con Google Sheets

• SQLite es la fuente principal del sistema.
• Sheets funciona como respaldo opcional.
• Las escrituras locales se encolan y la sincronización usa snapshot completo para evitar duplicados.
• El arranque no depende de Sheets salvo que actives BOOTSTRAP_FROM_SHEETS=true.
• Existen endpoints manuales:
  • POST /api/sync/from-sheets
  • POST /api/sync/to-sheets

Nota de compatibilidad

El contenedor usa python:3.14-slim. Si Hugging Face Spaces o faster-whisper mostraran incompatibilidad en build, el ajuste práctico inmediato es bajar a python:3.13-slim.