README.md

metadata

title: FlexiGo Support Bot
emoji: 💬
colorFrom: red
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false

Shopify Support Chatbot

Chatbot de soporte embebible para tiendas Shopify. Responde dudas de información (catálogo en vivo + base de conocimiento de PDFs/URLs) y de pedidos (estado y nº de seguimiento, con verificación de identidad), en el idioma del cliente. Cerebro LLM gratis (Groq con failover a Cloudflare Workers AI), embeddings locales. Pensado para una tienda y reutilizable.

Diseño: docs/superpowers/specs/2026-06-09-shopify-support-chatbot-design.md Plan: docs/superpowers/plans/2026-06-09-shopify-support-chatbot.md

Arquitectura

Widget (Theme App Extension)  ──/apps/chat (App Proxy, sin CORS, HMAC)──►  FastAPI
                                                                            │
   ┌────────────────────────────────────────────────────────────────────┐ │
   │ Orquestador (tool-calling)                                           │ │
   │   • search_knowledge  → RAG (pgvector + embeddings locales)          │ │
   │   • search_products   → Shopify GraphQL Admin API                    │ │
   │   • lookup_order      → Shopify GraphQL + verificación de identidad  │ │
   │   • escalate_to_human → email al equipo                              │ │
   │ LLM: Groq (primario) → Cloudflare Workers AI (failover)              │ │
   └────────────────────────────────────────────────────────────────────┘ │
                                  Postgres + pgvector ◄──────────────────────┘

Stack

Python 3.12 · FastAPI · SQLAlchemy 2 (async) · Postgres + pgvector · Alembic · fastembed (ONNX, multilingüe) · httpx · pytest. Gestor: uv.

Desarrollo local

uv sync                      # crea el venv (Python 3.12) e instala dependencias
cp .env.example .env         # rellena las claves (ver abajo)
uv run uvicorn app.main:app --reload
# Tests:
uv run pytest                # suite completa (incluye el test lento del embedder)
uv run pytest -m "not slow"  # rápido (sin cargar el modelo de embeddings)
uv run ruff check .          # lint

Sin Postgres local puedes usar sqlite para una prueba rápida: DATABASE_URL=sqlite+aiosqlite:///./dev.db (pgvector solo en Postgres; en sqlite la búsqueda RAG usa coseno en Python).

Claves LLM (gratis)

• Groq (primario): crea una API key en https://console.groq.com (gratis, sin tarjeta). Uso comercial permitido y no entrena con tus datos. → GROQ_API_KEY.
• Cloudflare Workers AI (failover): Account ID + API token de Workers AI. Gratis (10.000 neuronas/día), no entrena con tus datos. → CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN.

Mismos modelos Llama 3.3 70B / 3.1 8B en ambos, así que el failover es transparente. Camino de upgrade si la tienda crece: Groq de pago, o Cloudflare con facturación, o Gemini de pago — basta cambiar variables de entorno (LLM_PROVIDER_ORDER + claves).

Embeddings: modelo multilingüe local (fastembed), 0 €, sin enviar datos a terceros.

🚀 Despliegue (multi-tenant: el cliente no toca nada)

Modelo: NOSOTROS alojamos un solo backend que sirve a todos los clientes (cada uno es un tenant). El cliente solo recibe una línea para pegar (o se la pegamos). Cero infraestructura, cero claves, cero Railway para el cliente.

Una vez (nosotros) — desplegar el backend

1. Desplegar este repo en Railway (usa railway.json: migraciones + uvicorn + healthcheck /healthz, automático).
2. Volumen en /app/data (SQLite + caché del modelo).
3. Variables: GROQ_API_KEY (nuestra), ADMIN_TOKEN (nuestra), SECRET_KEY (cifra los secretos de los tenants), DATABASE_URL=sqlite+aiosqlite:////app/data/bot.db. (Opcional CLOUDFLARE_* para el failover.)

Por cada cliente (alta de 5 min, en /admin/)

1. Entrar en https://NUESTRO_BACKEND/admin/ con el ADMIN_TOKEN.
2. Crear la tienda (slug, p.ej. toorx), poner nombre/color/bienvenida.
3. Subir sus PDFs/URLs (base de conocimiento, aislada por tenant).
4. (Opcional, para pedidos) pegar las credenciales de su custom app de Shopify (shop, client_id, client_secret — se guarda cifrado). Sin esto = bot solo-info.
5. Copiar la línea de incrustación que muestra el panel:

<script src="https://NUESTRO_BACKEND/widget.js?t=toorx" defer></script>

El cliente — pega 1 línea

En su tema de Shopify (Online Store → Themes → Edit code → theme.liquid, antes de </body>), pega esa línea. Fin. El widget se sirve solo, detecta su backend y su tienda por el ?t=, lee su marca de /widget-config y habla con /chat (CORS).

Aislamiento: la base de conocimiento, sesiones y pedidos de cada tenant están separados por tenant_id; una tienda nunca ve los datos de otra.

(Opcional) Modo seguro con App Proxy

Si un cliente quiere firmas HMAC + logged_in_customer_id en vez del <script>: desplegar extension/ con shopify app deploy, configurar el App Proxy (subpath=chat, prefix=apps, URL → /apps/chat) y activar el bloque en App embeds. /apps/chat resuelve el tenant por el shop firmado.

(Opcional) Postgres + pgvector a escala

Cambia DATABASE_URL a Postgres; la migración crea la extensión vector y usa búsqueda vectorial nativa. (En SQLite la búsqueda RAG usa coseno en Python.)

Privacidad / GDPR

• LLMs sin entrenamiento con datos (Groq + Cloudflare) → seguro para datos de pedidos.
• Verificación por niveles: email + nº de pedido; solo se revela estado de envío + seguimiento (nunca dirección completa ni pago). Errores genéricos + bloqueo por intentos.
• Retención: las sesiones/mensajes se purgan automáticamente a los SESSION_RETENTION_DAYS días.