Base Docker Space with Python backend

.dockerignore

@@ -0,0 +1,5 @@
+python_backend/.venv
+__pycache__
+.pytest_cache
+.env
+.git

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,10 @@
+.env
+.env.*
+!.env.example
+python_backend/.env
+python_backend/.env.*
+!python_backend/.env.example
+__pycache__/
+.pytest_cache/
+.venv/
+data/

Dockerfile

@@ -0,0 +1,28 @@
+FROM python:3.14-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends ffmpeg build-essential \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY python_backend /app/python_backend
+
+RUN python -m pip install --upgrade pip setuptools wheel \
+  && pip install -e /app/python_backend
+
+COPY . /app
+
+RUN mkdir -p /data
+
+ENV PORT=7860
+ENV SQLITE_PATH=/data/inventario.sqlite
+
+EXPOSE 7860
+
+WORKDIR /app/python_backend
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -7,4 +7,83 @@ sdk: docker
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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 y sincronización.
+
+## 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.
+- `WHISPER_MODEL`: por defecto `tiny`.
+- `WHISPER_DEVICE`: `cpu`.
+- `WHISPER_COMPUTE_TYPE`: `int8`.
+- `REMINDER_HOUR` y `REMINDER_MINUTE`: horario del aviso diario.
+- `EXPIRY_WARNING_DAYS`: ventana de alerta de vencimiento.
+
+## 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 y usuarios.
+5. Google Sheets se actualiza como respaldo.
+6. El scheduler diario envía alertas de vencimiento por Telegram.
+
+## Comandos de Telegram
+
+- `/registrar leche gloria 6 unidades a 4.2 vence 2026-04-10 ingreso 2026-03-26 producido 2026-03-01`
+- `/consumir leche gloria 2 unidades desayuno`
+- `/buscar que productos vencen este mes`
+- `/diagrama arma un flowchart por fechas de caducidad`
+- `/vencimientos`
+- `/stock leche`
+
+## Webhook de Telegram
+
+Cuando el Space ya esté arriba y `APP_BASE_URL` apunte a la URL final:
+
+```bash
+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
+
+- Al iniciar, el backend intenta sincronizar desde Sheets hacia SQLite.
+- Cada alta y cada consumo replica a Sheets.
+- 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`.

docs/arquitectura.md

@@ -0,0 +1,65 @@
+# Arquitectura propuesta
+
+## Componentes
+
+1. `Python Backend`
+   - `FastAPI` asíncrono como backend principal.
+   - Atiende webhook de Telegram.
+   - Ejecuta transcripción local con `faster-whisper tiny`.
+   - Usa Claude Haiku para estructurar texto, responder preguntas y generar Mermaid.
+   - Ejecuta recordatorios diarios.
+
+2. `SQLite`
+   - Base operativa principal.
+   - Guarda productos, movimientos y usuarios de Telegram.
+   - Responde consultas de stock y vencimiento.
+
+3. `Google Sheets + Google Apps Script`
+   - Respaldo editable por negocio.
+   - Expone web service para altas, consumos, listados y snapshot.
+   - Mantiene hojas `Productos` y `Movimientos`.
+
+4. `Telegram`
+   - Canal operativo principal.
+   - Registra ingresos, consumos, stock y recordatorios.
+
+## Flujos
+
+### Registro de producto
+
+1. Usuario envía texto o audio por Telegram o usa la web.
+2. Si es audio, Whisper tiny lo transcribe dentro del contenedor.
+3. Claude Haiku convierte el texto a JSON estructurado.
+4. FastAPI valida y guarda en SQLite.
+5. El backend replica a Google Sheets como respaldo.
+
+### Consumo
+
+1. Usuario envía `/consumir`.
+2. Claude Haiku extrae producto, cantidad y unidad.
+3. SQLite descuenta stock y registra movimiento.
+4. Google Sheets recibe la réplica del consumo.
+
+### Recordatorio diario
+
+1. Un scheduler asíncrono corre cada día.
+2. Busca productos con stock positivo próximos a vencer.
+3. Envía el resumen a los usuarios de Telegram registrados.
+
+### Sincronización
+
+1. Al iniciar, el backend intenta traer snapshot desde Google Sheets.
+2. Existen endpoints para sincronizar manualmente desde y hacia Sheets.
+
+## Diagrama
+
+```mermaid
+flowchart LR
+  Usuario[Usuario Web o Telegram] --> API[FastAPI Python]
+  Telegram[Telegram Bot] --> API
+  API --> SQLite[(SQLite)]
+  API --> Whisper[Whisper Tiny Local]
+  API --> Claude[Claude Haiku API]
+  API --> GAS[Google Apps Script]
+  GAS --> Sheets[Google Sheets]
+```

google-apps-script/Code.gs

@@ -0,0 +1,348 @@
+const SHEET_NAME = 'Productos';
+const MOVEMENTS_SHEET_NAME = 'Movimientos';
+const HEADERS = [
+  'ID',
+  'Producto',
+  'Precio',
+  'Cantidad',
+  'Unidad',
+  'FechaCaducidad',
+  'FechaIngreso',
+  'FechaProduccion',
+  'Notas',
+  'Fuente',
+  'StockActual',
+  'ConsumidoTotal',
+  'CreadoEn',
+  'ActualizadoEn'
+];
+const MOVEMENT_HEADERS = [
+  'ID',
+  'ProductID',
+  'Producto',
+  'Tipo',
+  'Cantidad',
+  'Unidad',
+  'Notas',
+  'Fuente',
+  'CreadoEn'
+];
+
+function doGet(e) {
+  return handleRequest_({
+    method: 'GET',
+    params: e.parameter || {}
+  });
+}
+
+function doPost(e) {
+  const body = e.postData && e.postData.contents ? JSON.parse(e.postData.contents) : {};
+  return handleRequest_({
+    method: 'POST',
+    params: body
+  });
+}
+
+function handleRequest_(request) {
+  try {
+    const params = request.params || {};
+    validateToken_(params.token);
+
+    const action = params.action;
+    if (action === 'addRecord') return jsonResponse_(addRecord_(params.record || {}));
+    if (action === 'listRecords') return jsonResponse_(listRecords_(params.query || ''));
+    if (action === 'consumeProduct') return jsonResponse_(consumeProduct_(params.consumption || {}));
+    if (action === 'listMovements') return jsonResponse_(listMovements_());
+    if (action === 'replaceSnapshot') {
+      return jsonResponse_(replaceSnapshot_(params.records || [], params.movements || []));
+    }
+
+    return jsonResponse_({ ok: false, error: 'Accion no soportada.' });
+  } catch (error) {
+    return jsonResponse_({ ok: false, error: error.message });
+  }
+}
+
+function getSheet_() {
+  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
+  let sheet = spreadsheet.getSheetByName(SHEET_NAME);
+
+  if (!sheet) sheet = spreadsheet.insertSheet(SHEET_NAME);
+  if (sheet.getLastRow() === 0) {
+    sheet.getRange(1, 1, 1, HEADERS.length).setValues([HEADERS]);
+    sheet.setFrozenRows(1);
+  }
+
+  return sheet;
+}
+
+function getMovementSheet_() {
+  const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();
+  let sheet = spreadsheet.getSheetByName(MOVEMENTS_SHEET_NAME);
+
+  if (!sheet) sheet = spreadsheet.insertSheet(MOVEMENTS_SHEET_NAME);
+  if (sheet.getLastRow() === 0) {
+    sheet.getRange(1, 1, 1, MOVEMENT_HEADERS.length).setValues([MOVEMENT_HEADERS]);
+    sheet.setFrozenRows(1);
+  }
+
+  return sheet;
+}
+
+function validateToken_(token) {
+  const scriptToken = PropertiesService.getScriptProperties().getProperty('API_TOKEN');
+  if (!scriptToken) throw new Error('Falta API_TOKEN en Script Properties.');
+  if (token !== scriptToken) throw new Error('Token invalido.');
+}
+
+function addRecord_(record) {
+  const sheet = getSheet_();
+  const movementSheet = getMovementSheet_();
+  const createdAt = new Date().toISOString();
+  const id = record.id || Utilities.getUuid();
+
+  sheet.appendRow([
+    id,
+    record.producto || '',
+    Number(record.precio || 0),
+    Number(record.cantidad || 0),
+    record.unidad || 'unidad',
+    record.fechaCaducidad || '',
+    record.fechaIngreso || '',
+    record.fechaProduccion || '',
+    record.notas || '',
+    record.fuente || 'web',
+    Number(record.stockActual != null ? record.stockActual : record.cantidad || 0),
+    Number(record.consumidoTotal || 0),
+    record.createdAt || createdAt,
+    record.updatedAt || createdAt
+  ]);
+
+  movementSheet.appendRow([
+    Utilities.getUuid(),
+    id,
+    record.producto || '',
+    'ingreso',
+    Number(record.cantidad || 0),
+    record.unidad || 'unidad',
+    record.notas || '',
+    record.fuente || 'web',
+    createdAt
+  ]);
+
+  return { ok: true, id: id, createdAt: createdAt };
+}
+
+function listRecords_(query) {
+  const sheet = getSheet_();
+  const values = sheet.getDataRange().getValues();
+  if (values.length <= 1) return { ok: true, records: [] };
+
+  const headers = values[0];
+  const rows = values.slice(1).map(function(row) {
+    return toRecord_(headers, row);
+  });
+
+  const normalizedQuery = String(query || '').toLowerCase().trim();
+  const records = normalizedQuery
+    ? rows.filter(function(record) {
+        return JSON.stringify(record).toLowerCase().indexOf(normalizedQuery) >= 0;
+      })
+    : rows;
+
+  return { ok: true, records: records };
+}
+
+function toRecord_(headers, row) {
+  const result = {};
+  headers.forEach(function(header, index) {
+    result[header] = row[index];
+  });
+
+  return {
+    id: result.ID || '',
+    producto: result.Producto || '',
+    precio: result.Precio || 0,
+    cantidad: result.Cantidad || 0,
+    unidad: result.Unidad || 'unidad',
+    fechaCaducidad: formatDateValue_(result.FechaCaducidad),
+    fechaIngreso: formatDateValue_(result.FechaIngreso),
+    fechaProduccion: formatDateValue_(result.FechaProduccion),
+    notas: result.Notas || '',
+    fuente: result.Fuente || '',
+    stockActual: result.StockActual || 0,
+    consumidoTotal: result.ConsumidoTotal || 0,
+    createdAt: formatDateValue_(result.CreadoEn),
+    updatedAt: formatDateValue_(result.ActualizadoEn)
+  };
+}
+
+function consumeProduct_(consumption) {
+  const sheet = getSheet_();
+  const movementSheet = getMovementSheet_();
+  const values = sheet.getDataRange().getValues();
+  if (values.length <= 1) throw new Error('No hay productos registrados.');
+
+  const headers = values[0];
+  const rows = values.slice(1);
+  const targetProductId = consumption.productId || '';
+  let rowIndex = -1;
+
+  for (var i = 0; i < rows.length; i++) {
+    var record = toRecord_(headers, rows[i]);
+    if (targetProductId) {
+      if (record.id === targetProductId) {
+        rowIndex = i + 2;
+        break;
+      }
+    } else if (
+      String(record.producto).toLowerCase() === String(consumption.producto || '').toLowerCase() &&
+      Number(record.stockActual || 0) > 0
+    ) {
+      rowIndex = i + 2;
+      break;
+    }
+  }
+
+  if (rowIndex === -1) throw new Error('No se encontro el producto para consumir.');
+
+  const recordValues = sheet.getRange(rowIndex, 1, 1, headers.length).getValues()[0];
+  const record = toRecord_(headers, recordValues);
+  const quantity = Number(consumption.cantidad || 0);
+
+  if (record.unidad !== consumption.unidad) throw new Error('La unidad no coincide.');
+  if (Number(record.stockActual) < quantity) throw new Error('Stock insuficiente en Google Sheets.');
+
+  const newStock = Number(record.stockActual) - quantity;
+  const newConsumed = Number(record.consumidoTotal || 0) + quantity;
+  const updatedAt = new Date().toISOString();
+  const columns = headerIndexMap_(headers);
+
+  sheet.getRange(rowIndex, columns.StockActual).setValue(newStock);
+  sheet.getRange(rowIndex, columns.ConsumidoTotal).setValue(newConsumed);
+  sheet.getRange(rowIndex, columns.ActualizadoEn).setValue(updatedAt);
+
+  movementSheet.appendRow([
+    Utilities.getUuid(),
+    record.id,
+    record.producto,
+    'consumo',
+    quantity,
+    record.unidad,
+    consumption.notas || '',
+    consumption.fuente || 'telegram-consumo',
+    updatedAt
+  ]);
+
+  return {
+    ok: true,
+    id: record.id,
+    stockActual: newStock,
+    consumidoTotal: newConsumed,
+    updatedAt: updatedAt
+  };
+}
+
+function listMovements_() {
+  const sheet = getMovementSheet_();
+  const values = sheet.getDataRange().getValues();
+  if (values.length <= 1) return { ok: true, movements: [] };
+
+  const headers = values[0];
+  const movements = values.slice(1).map(function(row) {
+    const result = {};
+    headers.forEach(function(header, index) {
+      result[header] = row[index];
+    });
+
+    return {
+      id: result.ID || '',
+      productId: result.ProductID || '',
+      producto: result.Producto || '',
+      tipo: result.Tipo || '',
+      cantidad: result.Cantidad || 0,
+      unidad: result.Unidad || 'unidad',
+      notas: result.Notas || '',
+      fuente: result.Fuente || '',
+      createdAt: formatDateValue_(result.CreadoEn)
+    };
+  });
+
+  return { ok: true, movements: movements };
+}
+
+function replaceSnapshot_(records, movements) {
+  const productSheet = getSheet_();
+  const movementSheet = getMovementSheet_();
+
+  productSheet.clearContents();
+  movementSheet.clearContents();
+
+  productSheet.getRange(1, 1, 1, HEADERS.length).setValues([HEADERS]);
+  movementSheet.getRange(1, 1, 1, MOVEMENT_HEADERS.length).setValues([MOVEMENT_HEADERS]);
+
+  if (records.length) {
+    const productRows = records.map(function(record) {
+      return [
+        record.id || Utilities.getUuid(),
+        record.producto || '',
+        Number(record.precio || 0),
+        Number(record.cantidad || 0),
+        record.unidad || 'unidad',
+        record.fechaCaducidad || '',
+        record.fechaIngreso || '',
+        record.fechaProduccion || '',
+        record.notas || '',
+        record.fuente || 'web',
+        Number(record.stockActual || 0),
+        Number(record.consumidoTotal || 0),
+        record.createdAt || '',
+        record.updatedAt || record.createdAt || ''
+      ];
+    });
+    productSheet.getRange(2, 1, productRows.length, HEADERS.length).setValues(productRows);
+  }
+
+  if (movements.length) {
+    const movementRows = movements.map(function(movement) {
+      return [
+        movement.id || Utilities.getUuid(),
+        movement.productId || '',
+        movement.producto || '',
+        movement.tipo || '',
+        Number(movement.cantidad || 0),
+        movement.unidad || 'unidad',
+        movement.notas || '',
+        movement.fuente || '',
+        movement.createdAt || ''
+      ];
+    });
+    movementSheet.getRange(2, 1, movementRows.length, MOVEMENT_HEADERS.length).setValues(movementRows);
+  }
+
+  productSheet.setFrozenRows(1);
+  movementSheet.setFrozenRows(1);
+
+  return { ok: true, records: records.length, movements: movements.length };
+}
+
+function headerIndexMap_(headers) {
+  const result = {};
+  headers.forEach(function(header, index) {
+    result[header] = index + 1;
+  });
+  return result;
+}
+
+function formatDateValue_(value) {
+  if (Object.prototype.toString.call(value) === '[object Date]' && !isNaN(value)) {
+    return Utilities.formatDate(value, Session.getScriptTimeZone(), 'yyyy-MM-dd');
+  }
+  return value || '';
+}
+
+function jsonResponse_(payload) {
+  return ContentService
+    .createTextOutput(JSON.stringify(payload))
+    .setMimeType(ContentService.MimeType.JSON);
+}

python_backend/.env.example

@@ -0,0 +1,20 @@
+PORT=7860
+APP_BASE_URL=https://tu-space-o-dominio
+TIMEZONE=America/Lima
+
+ANTHROPIC_API_KEY=tu_api_key_anthropic
+ANTHROPIC_MODEL=claude-3-5-haiku-latest
+
+GOOGLE_SCRIPT_URL=https://script.google.com/macros/s/TU_DEPLOYMENT_ID/exec
+GOOGLE_SCRIPT_TOKEN=token-compartido-seguro
+
+SQLITE_PATH=/data/inventario.sqlite
+WHISPER_MODEL=tiny
+WHISPER_COMPUTE_TYPE=int8
+WHISPER_DEVICE=cpu
+
+TELEGRAM_BOT_TOKEN=token-del-bot
+TELEGRAM_WEBHOOK_SECRET=secret-opcional
+REMINDER_HOUR=8
+REMINDER_MINUTE=0
+EXPIRY_WARNING_DAYS=7

python_backend/app/__init__.py

@@ -0,0 +1 @@
+

python_backend/app/config.py

@@ -0,0 +1,29 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8", extra="ignore")
+
+    port: int = 7860
+    app_base_url: str = ""
+    timezone: str = "America/Lima"
+
+    anthropic_api_key: str = ""
+    anthropic_model: str = "claude-3-5-haiku-latest"
+
+    google_script_url: str = ""
+    google_script_token: str = ""
+
+    sqlite_path: str = "/data/inventario.sqlite"
+    whisper_model: str = "tiny"
+    whisper_compute_type: str = "int8"
+    whisper_device: str = "cpu"
+
+    telegram_bot_token: str = ""
+    telegram_webhook_secret: str = ""
+    reminder_hour: int = 8
+    reminder_minute: int = 0
+    expiry_warning_days: int = 7
+
+
+settings = Settings()

python_backend/app/database.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from .config import settings
+
+
+def _sqlite_url() -> str:
+    db_path = Path(settings.sqlite_path)
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    return f"sqlite+aiosqlite:///{db_path}"
+
+
+engine = create_async_engine(_sqlite_url(), future=True)
+SessionLocal = async_sessionmaker(engine, expire_on_commit=False, class_=AsyncSession)
+
+
+async def get_session() -> AsyncSession:
+    async with SessionLocal() as session:
+        yield session

python_backend/app/main.py

@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path
+
+from fastapi import Depends, FastAPI, Header, HTTPException, Request
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from .config import settings
+from .database import SessionLocal, engine, get_session
+from .models import Base
+from .schemas import ConsumptionCreate, DiagramRequest, ProductCreate, SearchRequest, TextExtractionRequest
+from .services.ai import answer_question, build_mermaid, extract_consumption, extract_product
+from .services.inventory import (
+    consume_product,
+    create_product,
+    get_expiring_products,
+    list_products,
+    register_telegram_user,
+    sync_from_sheets,
+    sync_to_sheets,
+)
+from .services.reminders import reminder_loop
+from .services.telegram import download_file, get_file_url, send_message, set_webhook
+from .services.whisper_local import transcribe_audio_bytes
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI):
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    try:
+        async with SessionLocal() as session:
+            await sync_from_sheets(session)
+    except Exception as exc:
+        print(f"Sync inicial desde Sheets omitido: {exc}")
+
+    reminder_task = asyncio.create_task(reminder_loop(SessionLocal))
+    try:
+        yield
+    finally:
+        reminder_task.cancel()
+        with suppress(asyncio.CancelledError):
+            await reminder_task
+
+
+app = FastAPI(lifespan=lifespan)
+STATIC_DIR = Path(__file__).parent / "static"
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+@app.get("/health")
+async def health() -> dict:
+    return {"ok": True}
+
+
+@app.get("/")
+async def index() -> FileResponse:
+    return FileResponse(STATIC_DIR / "index.html")
+
+
+@app.get("/api/products")
+async def api_list_products(query: str = "", session: AsyncSession = Depends(get_session)) -> dict:
+    return {"ok": True, "records": await list_products(session, query)}
+
+
+@app.post("/api/products")
+async def api_create_product(payload: ProductCreate, session: AsyncSession = Depends(get_session)) -> dict:
+    return {"ok": True, "record": await create_product(session, payload.model_dump())}
+
+
+@app.post("/api/consume")
+async def api_consume(payload: ConsumptionCreate, session: AsyncSession = Depends(get_session)) -> dict:
+    try:
+        return {"ok": True, "record": await consume_product(session, payload.model_dump())}
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.post("/api/extract-product")
+async def api_extract_product(payload: TextExtractionRequest) -> dict:
+    return {"ok": True, "product": await extract_product(payload.text, "web")}
+
+
+@app.post("/api/search")
+async def api_search(payload: SearchRequest, session: AsyncSession = Depends(get_session)) -> dict:
+    records = await list_products(session, "")
+    return {"ok": True, "answer": await answer_question(payload.question, records)}
+
+
+@app.post("/api/diagram")
+async def api_diagram(payload: DiagramRequest, session: AsyncSession = Depends(get_session)) -> dict:
+    records = await list_products(session, "")
+    return {"ok": True, "mermaid": await build_mermaid(payload.instruction, records)}
+
+
+@app.get("/api/expiring")
+async def api_expiring(days: int | None = None, session: AsyncSession = Depends(get_session)) -> dict:
+    return {"ok": True, "records": await get_expiring_products(session, days or settings.expiry_warning_days)}
+
+
+@app.post("/api/sync/from-sheets")
+async def api_sync_from_sheets(session: AsyncSession = Depends(get_session)) -> dict:
+    return {"ok": True, "result": await sync_from_sheets(session)}
+
+
+@app.post("/api/sync/to-sheets")
+async def api_sync_to_sheets(session: AsyncSession = Depends(get_session)) -> dict:
+    return {"ok": True, "result": await sync_to_sheets(session)}
+
+
+@app.post("/telegram/set-webhook")
+async def api_set_webhook() -> dict:
+    return await set_webhook()
+
+
+@app.post("/telegram/webhook")
+async def telegram_webhook(
+    request: Request,
+    session: AsyncSession = Depends(get_session),
+    x_telegram_bot_api_secret_token: str | None = Header(default=None),
+) -> dict:
+    if settings.telegram_webhook_secret and x_telegram_bot_api_secret_token != settings.telegram_webhook_secret:
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    update = await request.json()
+    message = update.get("message") or update.get("edited_message")
+    if not message or not message.get("chat", {}).get("id"):
+        return {"ok": True}
+
+    chat_id = message["chat"]["id"]
+    await register_telegram_user(
+        session,
+        str(chat_id),
+        message.get("from", {}).get("username", ""),
+        message.get("from", {}).get("first_name", ""),
+        message.get("from", {}).get("last_name", ""),
+    )
+
+    try:
+        if message.get("voice") or message.get("audio"):
+            audio = message.get("voice") or message.get("audio")
+            file_url = await get_file_url(audio["file_id"])
+            audio_bytes = await download_file(file_url)
+            transcript = await transcribe_audio_bytes(audio_bytes, ".ogg")
+            product = await extract_product(transcript, "telegram-audio")
+            record = await create_product(session, product)
+            await send_message(
+                chat_id,
+                f"Registro guardado desde audio.\nProducto: {record['producto']}\nCantidad: {record['cantidad']} {record['unidad']}\nCaducidad: {record['fechaCaducidad']}",
+            )
+            return {"ok": True}
+
+        text = str(message.get("text", "")).strip()
+        if not text:
+            await send_message(chat_id, "Envia texto o audio para registrar o consultar productos.")
+            return {"ok": True}
+
+        if text.startswith("/start"):
+            await send_message(
+                chat_id,
+                "Comandos:\n/registrar <texto libre>\n/consumir <texto libre>\n/buscar <pregunta>\n/diagrama <instruccion>\n/vencimientos\n/stock <producto>",
+            )
+            return {"ok": True}
+
+        if text.startswith("/buscar "):
+            records = await list_products(session, "")
+            answer = await answer_question(text.replace("/buscar", "", 1).strip(), records)
+            await send_message(chat_id, answer)
+            return {"ok": True}
+
+        if text.startswith("/diagrama "):
+            records = await list_products(session, "")
+            mermaid = await build_mermaid(text.replace("/diagrama", "", 1).strip(), records)
+            await send_message(chat_id, mermaid)
+            return {"ok": True}
+
+        if text.startswith("/vencimientos"):
+            records = await get_expiring_products(session, settings.expiry_warning_days)
+            if not records:
+                await send_message(chat_id, "No hay productos proximos a vencer.")
+            else:
+                lines = [f"- {r['producto']}: vence {r['fechaCaducidad']}, stock {r['stockActual']} {r['unidad']}" for r in records]
+                await send_message(chat_id, "Productos por vencer:\n" + "\n".join(lines))
+            return {"ok": True}
+
+        if text.startswith("/stock "):
+            records = await list_products(session, text.replace("/stock", "", 1).strip())
+            if not records:
+                await send_message(chat_id, "No encontre registros.")
+            else:
+                lines = [f"- {r['producto']}: stock {r['stockActual']}/{r['cantidad']} {r['unidad']}, vence {r['fechaCaducidad']}" for r in records[:10]]
+                await send_message(chat_id, "Stock encontrado:\n" + "\n".join(lines))
+            return {"ok": True}
+
+        if text.startswith("/consumir "):
+            payload = await extract_consumption(text.replace("/consumir", "", 1).strip(), "telegram-consumo")
+            result = await consume_product(session, payload)
+            await send_message(
+                chat_id,
+                f"Consumo registrado.\nProducto: {result['producto']}\nConsumido: {result['consumedNow']} {result['unidad']}\nStock restante: {result['stockActual']} {result['unidad']}",
+            )
+            return {"ok": True}
+
+        raw_text = text.replace("/registrar", "", 1).strip() if text.startswith("/registrar ") else text
+        payload = await extract_product(raw_text, "telegram-texto")
+        record = await create_product(session, payload)
+        await send_message(
+            chat_id,
+            f"Registro guardado.\nProducto: {record['producto']}\nCantidad: {record['cantidad']} {record['unidad']}\nIngreso: {record['fechaIngreso']}",
+        )
+    except ValueError as exc:
+        await send_message(chat_id, str(exc))
+    except Exception as exc:
+        await send_message(chat_id, f"Hubo un error: {exc}")
+
+    return {"ok": True}

python_backend/app/models.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from sqlalchemy import Float, Integer, String, Text
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Product(Base):
+    __tablename__ = "products"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    producto: Mapped[str] = mapped_column(String, index=True)
+    precio: Mapped[float] = mapped_column(Float)
+    cantidad: Mapped[float] = mapped_column(Float)
+    unidad: Mapped[str] = mapped_column(String)
+    fecha_caducidad: Mapped[str] = mapped_column(String, index=True)
+    fecha_ingreso: Mapped[str] = mapped_column(String)
+    fecha_produccion: Mapped[str] = mapped_column(String)
+    notas: Mapped[str] = mapped_column(Text, default="")
+    fuente: Mapped[str] = mapped_column(String, default="web")
+    stock_actual: Mapped[float] = mapped_column(Float)
+    consumido_total: Mapped[float] = mapped_column(Float, default=0)
+    created_at: Mapped[str] = mapped_column(String)
+    updated_at: Mapped[str] = mapped_column(String)
+
+
+class Movement(Base):
+    __tablename__ = "movements"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    product_id: Mapped[str] = mapped_column(String, index=True)
+    producto: Mapped[str] = mapped_column(String, index=True)
+    tipo: Mapped[str] = mapped_column(String)
+    cantidad: Mapped[float] = mapped_column(Float)
+    unidad: Mapped[str] = mapped_column(String)
+    notas: Mapped[str] = mapped_column(Text, default="")
+    fuente: Mapped[str] = mapped_column(String, default="")
+    created_at: Mapped[str] = mapped_column(String)
+
+
+class TelegramUser(Base):
+    __tablename__ = "telegram_users"
+
+    chat_id: Mapped[str] = mapped_column(String, primary_key=True)
+    username: Mapped[str] = mapped_column(String, default="")
+    first_name: Mapped[str] = mapped_column(String, default="")
+    last_name: Mapped[str] = mapped_column(String, default="")
+    is_active: Mapped[int] = mapped_column(Integer, default=1)
+    updated_at: Mapped[str] = mapped_column(String)

python_backend/app/schemas.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ProductCreate(BaseModel):
+    producto: str
+    precio: float = Field(ge=0)
+    cantidad: float = Field(gt=0)
+    unidad: str = "unidad"
+    fechaCaducidad: str
+    fechaIngreso: str
+    fechaProduccion: str
+    notas: str = ""
+    fuente: str = "web"
+
+
+class ConsumptionCreate(BaseModel):
+    producto: str
+    cantidad: float = Field(gt=0)
+    unidad: str = "unidad"
+    notas: str = ""
+    fuente: str = "telegram-consumo"
+
+
+class SearchRequest(BaseModel):
+    question: str
+
+
+class DiagramRequest(BaseModel):
+    instruction: str
+
+
+class TextExtractionRequest(BaseModel):
+    text: str

python_backend/app/services/__init__.py

@@ -0,0 +1 @@
+

python_backend/app/services/ai.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+import httpx
+
+from ..config import settings
+
+
+def extract_json(text: str) -> dict[str, Any]:
+    fenced = re.search(r"```json\s*(.*?)```", text, re.DOTALL | re.IGNORECASE)
+    if fenced:
+        return json.loads(fenced.group(1))
+
+    inline = re.search(r"\{.*\}", text, re.DOTALL)
+    if inline:
+        return json.loads(inline.group(0))
+
+    raise ValueError("No se encontro JSON valido en la respuesta de Claude.")
+
+
+async def call_claude(system: str, user_content: str, max_tokens: int = 1200) -> str:
+    async with httpx.AsyncClient(timeout=90) as client:
+        response = await client.post(
+            "https://api.anthropic.com/v1/messages",
+            headers={
+                "content-type": "application/json",
+                "x-api-key": settings.anthropic_api_key,
+                "anthropic-version": "2023-06-01",
+            },
+            json={
+                "model": settings.anthropic_model,
+                "max_tokens": max_tokens,
+                "system": system,
+                "messages": [{"role": "user", "content": user_content}],
+            },
+        )
+        response.raise_for_status()
+        payload = response.json()
+        return "\n".join(part["text"] for part in payload.get("content", []) if part.get("type") == "text")
+
+
+async def extract_product(raw_text: str, source: str) -> dict[str, Any]:
+    system = f"""
+Eres un extractor de inventario domestico.
+Devuelve solo JSON exacto.
+Esquema:
+{{
+  "producto": "string",
+  "precio": 0,
+  "cantidad": 0,
+  "unidad": "unidad",
+  "fechaCaducidad": "YYYY-MM-DD",
+  "fechaIngreso": "YYYY-MM-DD",
+  "fechaProduccion": "YYYY-MM-DD",
+  "notas": "string",
+  "fuente": "{source}"
+}}
+Si falta algo, usa 0 o cadena vacia.
+"""
+    text = await call_claude(system, f"Texto:\n{raw_text}")
+    return extract_json(text)
+
+
+async def extract_consumption(raw_text: str, source: str) -> dict[str, Any]:
+    system = f"""
+Eres un extractor de consumo de inventario.
+Devuelve solo JSON exacto.
+Esquema:
+{{
+  "producto": "string",
+  "cantidad": 0,
+  "unidad": "unidad",
+  "notas": "string",
+  "fuente": "{source}"
+}}
+"""
+    text = await call_claude(system, f"Texto:\n{raw_text}")
+    return extract_json(text)
+
+
+def _records_to_context(records: list[dict[str, Any]]) -> str:
+    return "\n".join(
+        f"{index + 1}. producto={r.get('producto')}; precio={r.get('precio')}; cantidad={r.get('cantidad')}; unidad={r.get('unidad')}; stockActual={r.get('stockActual')}; fechaCaducidad={r.get('fechaCaducidad')}; consumidoTotal={r.get('consumidoTotal')}"
+        for index, r in enumerate(records)
+    )
+
+
+async def answer_question(question: str, records: list[dict[str, Any]]) -> str:
+    system = """
+Eres un asistente de inventario domestico.
+Responde solo con informacion sustentada por los registros.
+Si los datos no alcanzan, dilo claramente.
+"""
+    return await call_claude(system, f"Pregunta:\n{question}\n\nRegistros:\n{_records_to_context(records)}")
+
+
+async def build_mermaid(instruction: str, records: list[dict[str, Any]]) -> str:
+    system = """
+Genera solo codigo Mermaid valido.
+No uses markdown.
+"""
+    return await call_claude(
+        system,
+        f"Instruccion:\n{instruction}\n\nRegistros:\n{_records_to_context(records)}",
+    )

python_backend/app/services/inventory.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import uuid
+from datetime import date, datetime
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ..models import Movement, Product, TelegramUser
+from . import sheets_backup
+
+
+def now_iso() -> str:
+    return datetime.utcnow().replace(microsecond=0).isoformat()
+
+
+def product_to_dict(product: Product) -> dict:
+    return {
+        "id": product.id,
+        "producto": product.producto,
+        "precio": product.precio,
+        "cantidad": product.cantidad,
+        "unidad": product.unidad,
+        "fechaCaducidad": product.fecha_caducidad,
+        "fechaIngreso": product.fecha_ingreso,
+        "fechaProduccion": product.fecha_produccion,
+        "notas": product.notas,
+        "fuente": product.fuente,
+        "stockActual": product.stock_actual,
+        "consumidoTotal": product.consumido_total,
+        "createdAt": product.created_at,
+        "updatedAt": product.updated_at,
+    }
+
+
+def movement_to_dict(movement: Movement) -> dict:
+    return {
+        "id": movement.id,
+        "productId": movement.product_id,
+        "producto": movement.producto,
+        "tipo": movement.tipo,
+        "cantidad": movement.cantidad,
+        "unidad": movement.unidad,
+        "notas": movement.notas,
+        "fuente": movement.fuente,
+        "createdAt": movement.created_at,
+    }
+
+
+async def register_telegram_user(session: AsyncSession, chat_id: str, username: str = "", first_name: str = "", last_name: str = "") -> None:
+    user = await session.get(TelegramUser, str(chat_id))
+    if user is None:
+        user = TelegramUser(
+            chat_id=str(chat_id),
+            username=username or "",
+            first_name=first_name or "",
+            last_name=last_name or "",
+            is_active=1,
+            updated_at=now_iso(),
+        )
+        session.add(user)
+    else:
+        user.username = username or ""
+        user.first_name = first_name or ""
+        user.last_name = last_name or ""
+        user.is_active = 1
+        user.updated_at = now_iso()
+    await session.commit()
+
+
+async def list_active_users(session: AsyncSession) -> list[TelegramUser]:
+    result = await session.execute(select(TelegramUser).where(TelegramUser.is_active == 1))
+    return list(result.scalars().all())
+
+
+async def create_product(session: AsyncSession, payload: dict) -> dict:
+    timestamp = now_iso()
+    product = Product(
+        id=str(uuid.uuid4()),
+        producto=payload["producto"],
+        precio=float(payload["precio"]),
+        cantidad=float(payload["cantidad"]),
+        unidad=payload["unidad"],
+        fecha_caducidad=payload["fechaCaducidad"],
+        fecha_ingreso=payload["fechaIngreso"],
+        fecha_produccion=payload["fechaProduccion"],
+        notas=payload.get("notas", ""),
+        fuente=payload.get("fuente", "web"),
+        stock_actual=float(payload["cantidad"]),
+        consumido_total=0,
+        created_at=timestamp,
+        updated_at=timestamp,
+    )
+    movement = Movement(
+        id=str(uuid.uuid4()),
+        product_id=product.id,
+        producto=product.producto,
+        tipo="ingreso",
+        cantidad=product.cantidad,
+        unidad=product.unidad,
+        notas=product.notas,
+        fuente=product.fuente,
+        created_at=timestamp,
+    )
+    session.add(product)
+    session.add(movement)
+    await session.commit()
+    await sheets_backup.add_product(product_to_dict(product))
+    return product_to_dict(product)
+
+
+async def list_products(session: AsyncSession, query: str = "") -> list[dict]:
+    result = await session.execute(select(Product).order_by(Product.fecha_caducidad.asc(), Product.producto.asc()))
+    products = list(result.scalars().all())
+    if query:
+        needle = query.lower().strip()
+        products = [p for p in products if needle in p.producto.lower() or needle in p.notas.lower()]
+    return [product_to_dict(product) for product in products]
+
+
+async def list_movements_local(session: AsyncSession) -> list[dict]:
+    result = await session.execute(select(Movement).order_by(Movement.created_at.desc()))
+    return [movement_to_dict(item) for item in result.scalars().all()]
+
+
+async def consume_product(session: AsyncSession, payload: dict) -> dict:
+    result = await session.execute(
+        select(Product)
+        .where(Product.producto.ilike(payload["producto"]), Product.stock_actual > 0)
+        .order_by(Product.fecha_caducidad.asc(), Product.created_at.asc())
+        .limit(1)
+    )
+    product = result.scalar_one_or_none()
+    if product is None:
+        raise ValueError(f'No existe stock disponible para "{payload["producto"]}".')
+    if product.unidad.lower() != payload["unidad"].lower():
+        raise ValueError(f"La unidad esperada para {product.producto} es {product.unidad}.")
+    if product.stock_actual < payload["cantidad"]:
+        raise ValueError(f"Stock insuficiente de {product.producto}.")
+
+    product.stock_actual -= float(payload["cantidad"])
+    product.consumido_total += float(payload["cantidad"])
+    product.updated_at = now_iso()
+
+    movement = Movement(
+        id=str(uuid.uuid4()),
+        product_id=product.id,
+        producto=product.producto,
+        tipo="consumo",
+        cantidad=float(payload["cantidad"]),
+        unidad=product.unidad,
+        notas=payload.get("notas", ""),
+        fuente=payload.get("fuente", "telegram-consumo"),
+        created_at=product.updated_at,
+    )
+    session.add(movement)
+    await session.commit()
+
+    response = product_to_dict(product) | {"consumedNow": float(payload["cantidad"])}
+    await sheets_backup.consume_product(
+        {
+            "productId": product.id,
+            "producto": product.producto,
+            "cantidad": float(payload["cantidad"]),
+            "unidad": product.unidad,
+            "notas": payload.get("notas", ""),
+            "fuente": payload.get("fuente", "telegram-consumo"),
+        }
+    )
+    return response
+
+
+async def get_expiring_products(session: AsyncSession, days_ahead: int) -> list[dict]:
+    products = await list_products(session)
+    today = date.today()
+    expiring = []
+    for item in products:
+        if item["stockActual"] <= 0 or not item["fechaCaducidad"]:
+            continue
+        expiry = date.fromisoformat(item["fechaCaducidad"])
+        diff = (expiry - today).days
+        if 0 <= diff <= days_ahead:
+            expiring.append(item)
+    return expiring
+
+
+async def sync_from_sheets(session: AsyncSession) -> dict:
+    products_response, movements_response = await sheets_backup.list_products(), await sheets_backup.list_movements()
+    records = products_response.get("records", [])
+    movements = movements_response.get("movements", [])
+
+    await session.execute(delete(Product))
+    await session.execute(delete(Movement))
+
+    for item in records:
+        session.add(
+            Product(
+                id=item["id"],
+                producto=item["producto"],
+                precio=float(item.get("precio", 0)),
+                cantidad=float(item.get("cantidad", 0)),
+                unidad=item.get("unidad", "unidad"),
+                fecha_caducidad=item.get("fechaCaducidad", ""),
+                fecha_ingreso=item.get("fechaIngreso", ""),
+                fecha_produccion=item.get("fechaProduccion", ""),
+                notas=item.get("notas", ""),
+                fuente=item.get("fuente", "web"),
+                stock_actual=float(item.get("stockActual", item.get("cantidad", 0))),
+                consumido_total=float(item.get("consumidoTotal", 0)),
+                created_at=item.get("createdAt", now_iso()),
+                updated_at=item.get("updatedAt", item.get("createdAt", now_iso())),
+            )
+        )
+
+    for item in movements:
+        session.add(
+            Movement(
+                id=item["id"],
+                product_id=item.get("productId", ""),
+                producto=item["producto"],
+                tipo=item["tipo"],
+                cantidad=float(item.get("cantidad", 0)),
+                unidad=item.get("unidad", "unidad"),
+                notas=item.get("notas", ""),
+                fuente=item.get("fuente", ""),
+                created_at=item.get("createdAt", now_iso()),
+            )
+        )
+
+    await session.commit()
+    return {"products": len(records), "movements": len(movements)}
+
+
+async def sync_to_sheets(session: AsyncSession) -> dict:
+    records = await list_products(session)
+    movements = await list_movements_local(session)
+    await sheets_backup.replace_snapshot(records, movements)
+    return {"products": len(records), "movements": len(movements)}

python_backend/app/services/reminders.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timedelta
+
+from sqlalchemy.ext.asyncio import async_sessionmaker
+
+from ..config import settings
+from .inventory import get_expiring_products, list_active_users
+from .telegram import send_message
+
+
+def seconds_until_next_run() -> float:
+    now = datetime.now()
+    target = now.replace(hour=settings.reminder_hour, minute=settings.reminder_minute, second=0, microsecond=0)
+    if target <= now:
+        target = target + timedelta(days=1)
+    return (target - now).total_seconds()
+
+
+def render_reminder(records: list[dict]) -> str:
+    if not records:
+        return f"Recordatorio diario: no hay productos por vencer en los proximos {settings.expiry_warning_days} dias."
+    lines = [
+        f"- {item['producto']}: vence {item['fechaCaducidad']}, stock {item['stockActual']} {item['unidad']}"
+        for item in records
+    ]
+    return "Recordatorio diario de vencimientos:\n" + "\n".join(lines)
+
+
+async def run_daily_reminders(session_factory: async_sessionmaker) -> None:
+    async with session_factory() as session:
+        users = await list_active_users(session)
+        if not users:
+            return
+        records = await get_expiring_products(session, settings.expiry_warning_days)
+        message = render_reminder(records)
+        for user in users:
+            try:
+                await send_message(user.chat_id, message)
+            except Exception as exc:
+                print(f"No se pudo enviar recordatorio a {user.chat_id}: {exc}")
+
+
+async def reminder_loop(session_factory: async_sessionmaker) -> None:
+    while True:
+        await asyncio.sleep(seconds_until_next_run())
+        await run_daily_reminders(session_factory)

python_backend/app/services/sheets_backup.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ..config import settings
+
+
+async def _call(action: str, payload: dict[str, Any] | None = None, method: str = "POST") -> dict[str, Any]:
+    payload = payload or {}
+    async with httpx.AsyncClient(timeout=60, follow_redirects=True) as client:
+        if method == "GET":
+            params = {"action": action, "token": settings.google_script_token, **payload}
+            response = await client.get(settings.google_script_url, params=params)
+        else:
+            response = await client.post(
+                settings.google_script_url,
+                json={"action": action, "token": settings.google_script_token, **payload},
+            )
+        response.raise_for_status()
+        return response.json()
+
+
+async def add_product(record: dict[str, Any]) -> dict[str, Any]:
+    return await _call("addRecord", {"record": record})
+
+
+async def consume_product(consumption: dict[str, Any]) -> dict[str, Any]:
+    return await _call("consumeProduct", {"consumption": consumption})
+
+
+async def list_products() -> dict[str, Any]:
+    return await _call("listRecords", {"query": ""}, method="GET")
+
+
+async def list_movements() -> dict[str, Any]:
+    return await _call("listMovements", method="GET")
+
+
+async def replace_snapshot(records: list[dict[str, Any]], movements: list[dict[str, Any]]) -> dict[str, Any]:
+    return await _call("replaceSnapshot", {"records": records, "movements": movements})

python_backend/app/services/telegram.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import httpx
+
+from ..config import settings
+
+
+def _api_url(path: str) -> str:
+    return f"https://api.telegram.org/bot{settings.telegram_bot_token}/{path}"
+
+
+async def send_message(chat_id: str | int, text: str) -> None:
+    async with httpx.AsyncClient(timeout=30) as client:
+        response = await client.post(_api_url("sendMessage"), json={"chat_id": chat_id, "text": text})
+        response.raise_for_status()
+
+
+async def get_file_url(file_id: str) -> str:
+    async with httpx.AsyncClient(timeout=30) as client:
+        response = await client.get(_api_url("getFile"), params={"file_id": file_id})
+        response.raise_for_status()
+        file_path = response.json()["result"]["file_path"]
+        return f"https://api.telegram.org/file/bot{settings.telegram_bot_token}/{file_path}"
+
+
+async def download_file(file_url: str) -> bytes:
+    async with httpx.AsyncClient(timeout=120) as client:
+        response = await client.get(file_url)
+        response.raise_for_status()
+        return response.content
+
+
+async def set_webhook() -> dict:
+    async with httpx.AsyncClient(timeout=30) as client:
+        response = await client.post(
+            _api_url("setWebhook"),
+            json={
+                "url": f"{settings.app_base_url}/telegram/webhook",
+                "secret_token": settings.telegram_webhook_secret or None,
+            },
+        )
+        response.raise_for_status()
+        return response.json()

python_backend/app/services/whisper_local.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import asyncio
+import tempfile
+from pathlib import Path
+
+from faster_whisper import WhisperModel
+
+from ..config import settings
+
+_model: WhisperModel | None = None
+
+
+def _get_model() -> WhisperModel:
+    global _model
+    if _model is None:
+        _model = WhisperModel(
+            settings.whisper_model,
+            device=settings.whisper_device,
+            compute_type=settings.whisper_compute_type,
+        )
+    return _model
+
+
+def _transcribe_file(file_path: str) -> str:
+    model = _get_model()
+    segments, _info = model.transcribe(file_path, beam_size=1, vad_filter=True)
+    return " ".join(segment.text.strip() for segment in segments).strip()
+
+
+async def transcribe_audio_bytes(audio_bytes: bytes, suffix: str = ".ogg") -> str:
+    with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as temp_file:
+        temp_file.write(audio_bytes)
+        temp_path = temp_file.name
+
+    try:
+        return await asyncio.to_thread(_transcribe_file, temp_path)
+    finally:
+        Path(temp_path).unlink(missing_ok=True)

python_backend/app/static/app.js

@@ -0,0 +1,23 @@
+async function postJson(url, body) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return response.json();
+}
+
+function bind(formId, resultId, endpoint, extra = {}) {
+  const form = document.getElementById(formId);
+  const result = document.getElementById(resultId);
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    result.textContent = "Procesando...";
+    const payload = Object.fromEntries(new FormData(form).entries());
+    const data = await postJson(endpoint, { ...payload, ...extra });
+    result.textContent = JSON.stringify(data, null, 2);
+  });
+}
+
+bind("product-form", "product-result", "/api/products", { fuente: "web" });
+bind("consume-form", "consume-result", "/api/consume", { fuente: "web-consumo" });

python_backend/app/static/index.html

@@ -0,0 +1,49 @@
+<!doctype html>
+<html lang="es">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Inventario Hogar</title>
+    <link rel="stylesheet" href="/static/styles.css" />
+    <script type="module" src="/static/app.js" defer></script>
+  </head>
+  <body>
+    <main class="layout">
+      <section class="hero">
+        <div>
+          <p class="eyebrow">Python Async + Whisper Local</p>
+          <h1>Inventario del hogar</h1>
+          <p class="lead">SQLite es la base principal. Google Sheets es respaldo. Telegram es el canal operativo.</p>
+        </div>
+      </section>
+      <section class="grid">
+        <article class="panel">
+          <h2>Registrar producto</h2>
+          <form id="product-form">
+            <label>Producto<input name="producto" required /></label>
+            <label>Precio<input name="precio" type="number" min="0" step="0.01" required /></label>
+            <label>Cantidad<input name="cantidad" type="number" min="0.01" step="0.01" required /></label>
+            <label>Unidad<input name="unidad" value="unidad" required /></label>
+            <label>Fecha caducidad<input name="fechaCaducidad" type="date" required /></label>
+            <label>Fecha ingreso<input name="fechaIngreso" type="date" required /></label>
+            <label>Fecha produccion<input name="fechaProduccion" type="date" required /></label>
+            <label>Notas<textarea name="notas" rows="3"></textarea></label>
+            <button type="submit">Guardar</button>
+          </form>
+          <pre id="product-result" class="result"></pre>
+        </article>
+        <article class="panel">
+          <h2>Consumir producto</h2>
+          <form id="consume-form">
+            <label>Producto<input name="producto" required /></label>
+            <label>Cantidad<input name="cantidad" type="number" min="0.01" step="0.01" required /></label>
+            <label>Unidad<input name="unidad" value="unidad" required /></label>
+            <label>Notas<textarea name="notas" rows="3"></textarea></label>
+            <button type="submit">Descontar</button>
+          </form>
+          <pre id="consume-result" class="result"></pre>
+        </article>
+      </section>
+    </main>
+  </body>
+</html>

python_backend/app/static/styles.css

@@ -0,0 +1,79 @@
+body {
+  margin: 0;
+  font-family: "IBM Plex Sans", sans-serif;
+  background: linear-gradient(180deg, #f8f4ee 0%, #efe4d4 100%);
+  color: #2f241d;
+}
+
+.layout {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 40px 20px 80px;
+}
+
+.hero {
+  margin-bottom: 24px;
+}
+
+.hero h1 {
+  font-family: Georgia, serif;
+  font-size: clamp(2.6rem, 4vw, 4.5rem);
+  margin: 0 0 10px;
+}
+
+.grid {
+  display: grid;
+  gap: 24px;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+
+.panel {
+  background: rgba(255, 250, 242, 0.88);
+  border: 1px solid rgba(47, 36, 29, 0.14);
+  border-radius: 22px;
+  padding: 22px;
+}
+
+form {
+  display: grid;
+  gap: 12px;
+}
+
+label {
+  display: grid;
+  gap: 6px;
+}
+
+input, textarea, button {
+  font: inherit;
+}
+
+input, textarea {
+  border: 1px solid rgba(47, 36, 29, 0.18);
+  border-radius: 14px;
+  padding: 12px;
+}
+
+button {
+  border: 0;
+  border-radius: 999px;
+  padding: 12px 18px;
+  background: #1f6a52;
+  color: white;
+  font-weight: 700;
+}
+
+.result {
+  min-height: 80px;
+  background: #f9f4ec;
+  border: 1px solid rgba(47, 36, 29, 0.12);
+  border-radius: 16px;
+  padding: 14px;
+  overflow: auto;
+}
+
+@media (max-width: 900px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+}

python_backend/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "registro-productos-hogar"
+version = "0.1.0"
+description = "Inventario domestico con Telegram, Claude, SQLite, Whisper local y respaldo en Google Sheets."
+requires-python = ">=3.14"
+dependencies = [
+  "aiosqlite>=0.21.0",
+  "fastapi>=0.116.0",
+  "faster-whisper>=1.2.0",
+  "httpx>=0.28.1",
+  "pydantic-settings>=2.10.1",
+  "sqlalchemy>=2.0.43",
+  "uvicorn[standard]>=0.35.0"
+]
+
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"