deploy flexigo support bot

.dockerignore

@@ -0,0 +1,15 @@
+.git
+.venv
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.fastembed_cache
+.hf_cache
+tests
+uploads
+*.db
+*.sqlite3
+docs
+.env
+.env.*

.python-version

@@ -0,0 +1 @@
+3.12

Dockerfile

@@ -0,0 +1,27 @@
+# Docker image for Hugging Face Spaces (Docker SDK) — free, no card, 16GB RAM.
+# Listens on 7860 (HF default). DB is external (Neon Postgres) via DATABASE_URL.
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    UV_LINK_MODE=copy \
+    HF_HOME=/app/.cache/hf \
+    PORT=7860
+
+# HF Spaces run containers as UID 1000.
+RUN useradd -m -u 1000 user
+RUN pip install --no-cache-dir uv
+
+WORKDIR /app
+COPY --chown=user:user pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev && chown -R user:user /app
+
+COPY --chown=user:user . .
+RUN chown -R user:user /app
+
+USER user
+# Pre-download the embedding model into the image so cold starts are fast.
+RUN uv run python -c "from app.embeddings import _get_model; _get_model()"
+
+EXPOSE 7860
+CMD ["sh", "-c", "uv run alembic upgrade head && uv run uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860}"]

Procfile

@@ -0,0 +1 @@
+web: uv run alembic upgrade head && uv run uvicorn app.main:app --host 0.0.0.0 --port $PORT

README.md

@@ -1,10 +1,121 @@
 ---
-title: Flexigo Support Bot
-emoji: 🏃
-colorFrom: pink
-colorTo: red
+title: FlexiGo Support Bot
+emoji: 💬
+colorFrom: red
+colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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`](docs/superpowers/specs/2026-06-09-shopify-support-chatbot-design.md)
+> Plan: [`docs/superpowers/plans/2026-06-09-shopify-support-chatbot.md`](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
+
+```bash
+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`](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:
+
+```html
+<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.

alembic.ini

@@ -0,0 +1,149 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts.
+# this is typically a path given in POSIX (e.g. forward slashes)
+# format, relative to the token %(here)s which refers to the location of this
+# ini file
+script_location = %(here)s/migrations
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+# Or organize into date-based subdirectories (requires recursive_version_locations = true)
+# file_template = %%(year)d/%%(month).2d/%%(day).2d_%%(hour).2d%%(minute).2d_%%(second).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.  for multiple paths, the path separator
+# is defined by "path_separator" below.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the tzdata library which can be installed by adding
+# `alembic[tz]` to the pip requirements.
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to <script_location>/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "path_separator"
+# below.
+# version_locations = %(here)s/bar:%(here)s/bat:%(here)s/alembic/versions
+
+# path_separator; This indicates what character is used to split lists of file
+# paths, including version_locations and prepend_sys_path within configparser
+# files such as alembic.ini.
+# The default rendered in new alembic.ini files is "os", which uses os.pathsep
+# to provide os-dependent path splitting.
+#
+# Note that in order to support legacy alembic.ini files, this default does NOT
+# take place if path_separator is not present in alembic.ini.  If this
+# option is omitted entirely, fallback logic is as follows:
+#
+# 1. Parsing of the version_locations option falls back to using the legacy
+#    "version_path_separator" key, which if absent then falls back to the legacy
+#    behavior of splitting on spaces and/or commas.
+# 2. Parsing of the prepend_sys_path option falls back to the legacy
+#    behavior of splitting on spaces, commas, or colons.
+#
+# Valid values for path_separator are:
+#
+# path_separator = :
+# path_separator = ;
+# path_separator = space
+# path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+path_separator = os
+
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# database URL.  This is consumed by the user-maintained env.py script only.
+# other means of configuring database URLs may be customized within the env.py
+# file.
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the module runner, against the "ruff" module
+# hooks = ruff
+# ruff.type = module
+# ruff.module = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Alternatively, use the exec runner to execute a binary found on your PATH
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = ruff
+# ruff.options = check --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration.  This is also consumed by the user-maintained
+# env.py script only.
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

app/admin_ui/index.html

@@ -0,0 +1,188 @@
+<!doctype html>
+<html lang="es">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Admin · Chatbot de soporte</title>
+  <style>
+    :root { --fg:#1a1a1a; --muted:#666; --accent:#e8491d; --bg:#fafafa; --line:#e3e3e3; }
+    * { box-sizing: border-box; }
+    body { font-family: system-ui, sans-serif; margin: 0; color: var(--fg); background: var(--bg); }
+    header { background: var(--accent); color: #fff; padding: 16px 24px; }
+    header h1 { margin: 0; font-size: 18px; }
+    main { max-width: 920px; margin: 0 auto; padding: 24px; }
+    .card { background:#fff; border:1px solid var(--line); border-radius:10px; padding:18px; margin-bottom:18px; }
+    h2 { font-size:15px; margin:0 0 12px; }
+    label { display:block; font-size:13px; color:var(--muted); margin:8px 0 4px; }
+    input, select { width:100%; padding:9px 10px; border:1px solid var(--line); border-radius:8px; font-size:14px; }
+    button { background:var(--accent); color:#fff; border:0; border-radius:8px; padding:9px 14px; font-size:14px; cursor:pointer; }
+    button.secondary { background:#444; }
+    table { width:100%; border-collapse:collapse; font-size:13px; }
+    th, td { text-align:left; padding:8px; border-bottom:1px solid var(--line); }
+    .status-indexed { color:#1a7f37; } .status-error { color:#b00; } .status-pending { color:#a60; }
+    .row { display:flex; gap:10px; align-items:flex-end; flex-wrap:wrap; }
+    .row > div { flex:1; min-width:160px; }
+    .muted { color:var(--muted); font-size:12px; }
+    .embed { background:#f3f3f3; padding:10px; border-radius:8px; font-family:monospace; font-size:12px; word-break:break-all; }
+    .hidden { display:none; }
+  </style>
+</head>
+<body>
+  <header><h1>Chatbot de soporte · Administración (multi-tienda)</h1></header>
+  <main>
+    <div class="card">
+      <h2>Acceso</h2>
+      <label for="token">Admin token (Bearer)</label>
+      <input id="token" type="password" placeholder="pega aquí tu ADMIN_TOKEN" />
+      <p class="muted">Se guarda solo en memoria de esta pestaña.</p>
+    </div>
+
+    <div class="card">
+      <h2>Tienda (tenant)</h2>
+      <div class="row">
+        <div>
+          <label for="tenant">Selecciona la tienda</label>
+          <select id="tenant" onchange="onTenant()"></select>
+        </div>
+        <button class="secondary" onclick="loadTenants()">Recargar</button>
+      </div>
+      <hr style="border:none;border-top:1px solid var(--line);margin:16px 0;" />
+      <h2>Crear tienda nueva</h2>
+      <div class="row">
+        <div><label for="new-slug">Identificador (slug)</label><input id="new-slug" placeholder="toorx" /></div>
+        <div><label for="new-name">Nombre</label><input id="new-name" placeholder="TOORX" /></div>
+        <button onclick="createTenant()">Crear</button>
+      </div>
+    </div>
+
+    <div id="panel" class="hidden">
+      <div class="card">
+        <h2>Incrustar en la web del cliente (1 línea)</h2>
+        <div class="embed" id="embed"></div>
+        <p class="muted">Pegar antes de <code>&lt;/body&gt;</code> en el tema de Shopify.</p>
+      </div>
+
+      <div class="card">
+        <h2>Fuentes de conocimiento</h2>
+        <div class="row">
+          <div><label for="url">Añadir por URL</label><input id="url" type="url" placeholder="https://tienda.com/faq" /></div>
+          <button onclick="addUrl()">Añadir URL</button>
+        </div>
+        <div class="row" style="margin-top:12px;">
+          <div><label for="file">Subir fichero (PDF, Excel, Word, TXT)</label><input id="file" type="file" /></div>
+          <button onclick="addFile()">Subir</button>
+          <button class="secondary" onclick="reindex()">Reindexar</button>
+        </div>
+        <table style="margin-top:16px;">
+          <thead><tr><th>#</th><th>Nombre</th><th>Tipo</th><th>Estado</th><th></th></tr></thead>
+          <tbody id="sources"></tbody>
+        </table>
+      </div>
+
+      <div class="card">
+        <h2>Marca</h2>
+        <div class="row">
+          <div><label for="brand">Nombre del asistente</label><input id="brand" /></div>
+          <div><label for="color">Color</label><input id="color" /></div>
+          <button onclick="saveBrand()">Guardar marca</button>
+        </div>
+      </div>
+
+      <div class="card">
+        <h2>Pedidos (Shopify) — opcional</h2>
+        <div class="row">
+          <div><label>Shop</label><input id="sh-shop" placeholder="tienda.myshopify.com" /></div>
+          <div><label>Client ID</label><input id="sh-id" /></div>
+        </div>
+        <div class="row" style="margin-top:8px;">
+          <div><label>Client Secret</label><input id="sh-secret" type="password" placeholder="(se guarda cifrado)" /></div>
+          <button onclick="saveShopify()">Guardar Shopify</button>
+        </div>
+        <p class="muted" id="sh-state"></p>
+      </div>
+    </div>
+    <p class="muted" id="msg"></p>
+  </main>
+
+  <script>
+    var ORIGIN = location.origin;
+    var $ = function (id) { return document.getElementById(id); };
+    function auth() { return { "Authorization": "Bearer " + $("token").value.trim() }; }
+    function flash(m) { $("msg").textContent = m; }
+    function slug() { return $("tenant").value; }
+
+    async function api(path, opts) {
+      opts = opts || {};
+      var res = await fetch("/admin" + path, { ...opts, headers: { ...(opts.headers || {}), ...auth() } });
+      if (res.status === 401) { flash("Token inválido."); throw new Error("unauthorized"); }
+      return res;
+    }
+
+    async function loadTenants() {
+      try {
+        var rows = await (await api("/tenants")).json();
+        $("tenant").innerHTML = rows.map(function (t) {
+          return '<option value="' + t.slug + '">' + t.slug + (t.name ? " — " + t.name : "") + "</option>";
+        }).join("");
+        if (rows.length) onTenant();
+      } catch (e) {}
+    }
+
+    async function createTenant() {
+      var s = $("new-slug").value.trim(); if (!s) return;
+      await api("/tenants", { method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ slug: s, name: $("new-name").value.trim() }) });
+      $("new-slug").value = ""; $("new-name").value = "";
+      flash("Tienda creada."); await loadTenants(); $("tenant").value = s; onTenant();
+    }
+
+    async function onTenant() {
+      var s = slug(); if (!s) return;
+      $("panel").classList.remove("hidden");
+      $("embed").textContent = '<script src="' + ORIGIN + '/widget.js?t=' + s + '" defer><' + '/script>';
+      var rows = await (await api("/tenants")).json();
+      var t = rows.find(function (x) { return x.slug === s; }) || {};
+      $("brand").value = t.brand_name || ""; $("color").value = t.brand_color || "";
+      $("sh-shop").value = t.shopify_shop || ""; $("sh-id").value = t.shopify_client_id || "";
+      $("sh-state").textContent = t.has_shopify_secret ? "Secret guardado ✓" : "Sin secret (bot solo-info)";
+      loadSources();
+    }
+
+    async function loadSources() {
+      var s = slug();
+      var rows = await (await api("/tenants/" + s + "/sources")).json();
+      $("sources").innerHTML = rows.map(function (r) {
+        return '<tr><td>' + r.id + '</td><td>' + r.name + '</td><td>' + r.kind + '</td>' +
+          '<td class="status-' + r.status + '">' + r.status + (r.error ? " · " + r.error : "") + '</td>' +
+          '<td><button class="secondary" onclick="del(' + r.id + ')">Borrar</button></td></tr>';
+      }).join("");
+    }
+    async function addUrl() {
+      var loc = $("url").value.trim(); if (!loc) return;
+      await api("/tenants/" + slug() + "/sources/url", { method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ kind: "url", location: loc }) });
+      $("url").value = ""; flash("URL añadida."); loadSources();
+    }
+    async function addFile() {
+      var f = $("file").files[0]; if (!f) return;
+      var fd = new FormData(); fd.append("file", f);
+      await api("/tenants/" + slug() + "/sources/file", { method: "POST", body: fd });
+      flash("Fichero subido."); loadSources();
+    }
+    async function del(id) { await api("/tenants/" + slug() + "/sources/" + id, { method: "DELETE" }); loadSources(); }
+    async function reindex() { await api("/tenants/" + slug() + "/reindex", { method: "POST" }); flash("Reindexando…"); loadSources(); }
+    async function saveBrand() {
+      await api("/tenants/" + slug(), { method: "PUT", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ brand_name: $("brand").value.trim(), brand_color: $("color").value.trim() }) });
+      flash("Marca guardada.");
+    }
+    async function saveShopify() {
+      var body = { shopify_shop: $("sh-shop").value.trim(), shopify_client_id: $("sh-id").value.trim() };
+      var sec = $("sh-secret").value.trim(); if (sec) body.shopify_client_secret = sec;
+      await api("/tenants/" + slug(), { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
+      $("sh-secret").value = ""; flash("Shopify guardado."); onTenant();
+    }
+    $("token").addEventListener("change", loadTenants);
+  </script>
+</body>
+</html>

app/config.py

@@ -0,0 +1,83 @@
+"""Application settings, loaded from environment / .env."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from pydantic import field_validator
+from pydantic_settings import BaseSettings, NoDecode, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore", case_sensitive=False)
+
+    # Core
+    database_url: str = "sqlite+aiosqlite://"
+    testing: bool = False
+
+    # LLM: Groq (primary)
+    groq_api_key: str = ""
+    groq_base_url: str = "https://api.groq.com/openai/v1"
+    model_large: str = "llama-3.3-70b-versatile"
+    model_small: str = "llama-3.1-8b-instant"
+
+    # LLM: Cloudflare Workers AI (failover)
+    cloudflare_account_id: str = ""
+    cloudflare_api_token: str = ""
+    cf_model_large: str = "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
+    cf_model_small: str = "@cf/meta/llama-3.1-8b-instruct"
+
+    llm_provider_order: Annotated[list[str], NoDecode] = ["groq", "cloudflare"]
+
+    # Shopify
+    shopify_shop: str = ""
+    shopify_client_id: str = ""
+    shopify_client_secret: str = ""
+    shopify_api_version: str = "2026-01"
+    shopify_app_proxy_secret: str = ""
+    shopify_read_all_orders: bool = False
+
+    # Admin
+    admin_token: str = ""
+    # Key used to encrypt per-tenant secrets at rest. CHANGE in production.
+    secret_key: str = "dev-insecure-change-me"
+
+    # Branding (overridable at runtime via the admin /config endpoint)
+    brand_name: str = "Asistente"
+
+    # CORS allow-list for the simple-mode /chat + widget (public chat widget).
+    # Comma-separated origins, or "*" for any (default; no cookies are used).
+    allowed_origins: Annotated[list[str], NoDecode] = ["*"]
+
+    # Embeddings
+    embedding_model: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+
+    # Verification / retention
+    order_verify_max_attempts: int = 5
+    order_verify_lockout_seconds: int = 900
+    session_retention_days: int = 30
+
+    # Escalation (SMTP)
+    support_email: str = ""
+    smtp_host: str = ""
+    smtp_port: int = 587
+    smtp_user: str = ""
+    smtp_password: str = ""
+    smtp_from: str = ""
+
+    @field_validator("llm_provider_order", "allowed_origins", mode="before")
+    @classmethod
+    def _split_csv(cls, v: object) -> object:
+        if isinstance(v, str):
+            return [item.strip() for item in v.split(",") if item.strip()]
+        return v
+
+
+_settings: Settings | None = None
+
+
+def get_settings() -> Settings:
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings

app/crypto.py

@@ -0,0 +1,28 @@
+"""Symmetric encryption for secrets stored at rest (per-tenant Shopify secret)."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from cryptography.fernet import Fernet
+
+from app.config import get_settings
+
+
+def _fernet() -> Fernet:
+    # Derive a stable 32-byte urlsafe key from the configured secret.
+    digest = hashlib.sha256(get_settings().secret_key.encode("utf-8")).digest()
+    return Fernet(base64.urlsafe_b64encode(digest))
+
+
+def encrypt(plaintext: str) -> str:
+    if not plaintext:
+        return ""
+    return _fernet().encrypt(plaintext.encode("utf-8")).decode("utf-8")
+
+
+def decrypt(token: str) -> str:
+    if not token:
+        return ""
+    return _fernet().decrypt(token.encode("utf-8")).decode("utf-8")

app/db.py

@@ -0,0 +1,68 @@
+"""Async database engine, session factory, and declarative base."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+_engine: AsyncEngine | None = None
+_sessionmaker: async_sessionmaker[AsyncSession] | None = None
+
+
+def init_engine(url: str, **engine_kwargs: Any) -> AsyncEngine:
+    """Create the global async engine + session factory.
+
+    Extra kwargs are forwarded to ``create_async_engine`` (used by tests to
+    pass a StaticPool so an in-memory sqlite DB is shared across sessions).
+    """
+    global _engine, _sessionmaker
+    # For networked DBs (e.g. Neon Postgres that autosuspends), validate
+    # connections before use so a dropped connection is transparently replaced.
+    if "sqlite" not in url and "pool_pre_ping" not in engine_kwargs:
+        engine_kwargs["pool_pre_ping"] = True
+    _engine = create_async_engine(url, future=True, **engine_kwargs)
+    _sessionmaker = async_sessionmaker(_engine, expire_on_commit=False, class_=AsyncSession)
+    return _engine
+
+
+def is_initialized() -> bool:
+    return _engine is not None
+
+
+def get_engine() -> AsyncEngine:
+    assert _engine is not None, "engine not initialized; call init_engine() first"
+    return _engine
+
+
+def get_sessionmaker() -> async_sessionmaker[AsyncSession]:
+    assert _sessionmaker is not None, "engine not initialized; call init_engine() first"
+    return _sessionmaker
+
+
+async def get_session() -> AsyncIterator[AsyncSession]:
+    """FastAPI dependency yielding a session (overridable in tests)."""
+    async with get_sessionmaker()() as session:
+        yield session
+
+
+async def create_all() -> None:
+    """Create all tables registered on Base.metadata (tests / sqlite dev)."""
+    async with get_engine().begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+def is_postgres(url: str) -> bool:
+    return url.startswith("postgresql") or url.startswith("postgres")

app/deps.py

@@ -0,0 +1,42 @@
+"""FastAPI dependencies: LLM router, Shopify client, admin auth (overridable)."""
+
+from __future__ import annotations
+
+import hmac
+
+from fastapi import Header, HTTPException
+
+from app.config import get_settings
+from app.llm.router import build_router_from_settings
+from app.shopify.client import ShopifyGraphQLClient
+from app.shopify.token import ShopifyTokenManager
+
+_router = None
+_shopify_built = False
+_shopify_client: ShopifyGraphQLClient | None = None
+
+
+def get_router():
+    global _router
+    if _router is None:
+        _router = build_router_from_settings(get_settings())
+    return _router
+
+
+def get_shopify() -> ShopifyGraphQLClient | None:
+    global _shopify_built, _shopify_client
+    if not _shopify_built:
+        s = get_settings()
+        if s.shopify_shop and s.shopify_client_id and s.shopify_client_secret:
+            tm = ShopifyTokenManager(s.shopify_shop, s.shopify_client_id, s.shopify_client_secret)
+            _shopify_client = ShopifyGraphQLClient(s.shopify_shop, s.shopify_api_version, tm)
+        _shopify_built = True
+    return _shopify_client
+
+
+async def require_admin(authorization: str = Header(default="")) -> bool:
+    token = authorization.removeprefix("Bearer ").strip()
+    s = get_settings()
+    if not s.admin_token or not hmac.compare_digest(token, s.admin_token):
+        raise HTTPException(status_code=401, detail="unauthorized")
+    return True

app/embeddings.py

@@ -0,0 +1,62 @@
+"""Local multilingual embeddings via fastembed (ONNX, no torch).
+
+Default model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
+(384-dim, multilingual incl. ES/PT/EN). If an e5 model is configured, the
+"query: " / "passage: " prefixes it expects are applied automatically.
+Inference runs in a worker thread; the model is loaded lazily and cached.
+"""
+
+from __future__ import annotations
+
+import math
+
+import anyio
+
+from app.config import get_settings
+
+_model = None
+
+
+def _get_model():
+    global _model
+    if _model is None:
+        from fastembed import TextEmbedding
+
+        _model = TextEmbedding(
+            model_name=get_settings().embedding_model, cache_dir=".fastembed_cache"
+        )
+    return _model
+
+
+def _embed_sync(texts: list[str]) -> list[list[float]]:
+    model = _get_model()
+    return [[float(x) for x in vec] for vec in model.embed(texts)]
+
+
+def _apply_prefix(kind: str, texts: list[str]) -> list[str]:
+    # e5 family expects "query: " / "passage: " prefixes; others must not.
+    if "e5" in get_settings().embedding_model.lower():
+        return [f"{kind}: {t}" for t in texts]
+    return texts
+
+
+async def embed_texts(texts: list[str], *, kind: str = "passage") -> list[list[float]]:
+    if not texts:
+        return []
+    return await anyio.to_thread.run_sync(_embed_sync, _apply_prefix(kind, texts))
+
+
+async def embed_query(text: str) -> list[float]:
+    result = await embed_texts([text], kind="query")
+    return result[0]
+
+
+def cosine(a: list[float], b: list[float]) -> float:
+    if not a or not b:
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b, strict=False))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0 or nb == 0:
+        return 0.0
+    return dot / (na * nb)

app/escalation.py

@@ -0,0 +1,26 @@
+"""Human escalation: forward an unanswered question + customer email to the store."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+
+Sender = Callable[[str, str, str], Awaitable[bool]]
+
+
+async def create_escalation(
+    email: str,
+    question: str,
+    *,
+    session_id: str,
+    support_email: str,
+    sender: Sender,
+) -> dict[str, object]:
+    subject = f"[Bot] Nueva consulta de soporte ({session_id})"
+    body = (
+        "Una consulta del chatbot necesita atención humana.\n\n"
+        f"Email del cliente: {email}\n"
+        f"Sesión: {session_id}\n\n"
+        f"Consulta:\n{question}\n"
+    )
+    sent = await sender(support_email, subject, body)
+    return {"sent": bool(sent), "support_email": support_email}

app/llm/base.py

@@ -0,0 +1,153 @@
+"""LLM provider protocol + a shared OpenAI-compatible HTTP provider.
+
+Groq and Cloudflare Workers AI both expose OpenAI-compatible
+``/chat/completions`` endpoints, so they share one implementation.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+import httpx
+
+
+class ProviderError(Exception):
+    """Any non-recoverable provider failure (triggers failover)."""
+
+
+class RateLimitError(ProviderError):
+    """HTTP 429 from a provider (triggers failover)."""
+
+
+@dataclass
+class ToolSpec:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+
+    def to_openai(self) -> dict[str, Any]:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+
+@dataclass
+class ChatResult:
+    content: str | None
+    tool_calls: list[ToolCall] = field(default_factory=list)
+    finish_reason: str | None = None
+
+
+class LLMProvider(Protocol):
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[ToolSpec],
+        model: str,
+        temperature: float = 0.3,
+    ) -> ChatResult: ...
+
+
+def parse_openai_choice(data: dict[str, Any]) -> ChatResult:
+    """Map an OpenAI-style chat completion response to ChatResult."""
+    choices = data.get("choices") if isinstance(data, dict) else None
+    if not choices:
+        raise ProviderError(f"malformed response: no choices ({str(data)[:200]})")
+    choice = choices[0]
+    msg = choice.get("message", {}) or {}
+    calls: list[ToolCall] = []
+    for c in msg.get("tool_calls") or []:
+        fn = c.get("function", {}) or {}
+        args = fn.get("arguments")
+        if isinstance(args, str):
+            try:
+                args = json.loads(args) if args.strip() else {}
+            except json.JSONDecodeError:
+                args = {}
+        calls.append(
+            ToolCall(id=c.get("id", ""), name=fn.get("name", ""), arguments=args or {})
+        )
+    return ChatResult(
+        content=msg.get("content"),
+        tool_calls=calls,
+        finish_reason=choice.get("finish_reason"),
+    )
+
+
+class OpenAICompatProvider:
+    """Generic OpenAI-compatible chat-completions provider over httpx."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        extra_headers: dict[str, str] | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+        }
+        if extra_headers:
+            self._headers.update(extra_headers)
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=self._timeout)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[ToolSpec],
+        model: str,
+        temperature: float = 0.3,
+    ) -> ChatResult:
+        payload: dict[str, Any] = {
+            "model": model,
+            "messages": messages,
+            "temperature": temperature,
+        }
+        if tools:
+            payload["tools"] = [t.to_openai() for t in tools]
+            payload["tool_choice"] = "auto"
+        try:
+            resp = await self._get_client().post(
+                f"{self.base_url}/chat/completions", json=payload, headers=self._headers
+            )
+        except httpx.HTTPError as exc:
+            raise ProviderError(f"network error: {exc}") from exc
+
+        if resp.status_code == 429:
+            raise RateLimitError(f"rate limited: {resp.text[:200]}")
+        if resp.status_code >= 400:
+            raise ProviderError(f"http {resp.status_code}: {resp.text[:200]}")
+        try:
+            return parse_openai_choice(resp.json())
+        except ProviderError:
+            raise
+        except Exception as exc:  # noqa: BLE001 - any parse failure should fail over
+            raise ProviderError(f"unparseable response: {exc}") from exc

app/llm/cloudflare.py

@@ -0,0 +1,11 @@
+"""Cloudflare Workers AI provider (OpenAI-compatible). Failover LLM."""
+
+from __future__ import annotations
+
+from app.llm.base import OpenAICompatProvider
+
+
+class CloudflareProvider(OpenAICompatProvider):
+    def __init__(self, account_id: str, api_token: str, **kwargs: object) -> None:
+        base_url = f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1"
+        super().__init__(base_url, api_token, **kwargs)  # type: ignore[arg-type]

app/llm/groq.py

@@ -0,0 +1,15 @@
+"""Groq provider (OpenAI-compatible). Primary LLM."""
+
+from __future__ import annotations
+
+from app.llm.base import OpenAICompatProvider
+
+
+class GroqProvider(OpenAICompatProvider):
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.groq.com/openai/v1",
+        **kwargs: object,
+    ) -> None:
+        super().__init__(base_url, api_key, **kwargs)  # type: ignore[arg-type]

app/llm/router.py

@@ -0,0 +1,86 @@
+"""LLMRouter: picks a model per tier and fails over across providers in order."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from app.llm.base import ChatResult, LLMProvider, ProviderError, ToolSpec
+
+log = logging.getLogger(__name__)
+
+
+class LLMRouter:
+    """Route a chat call to the first healthy provider in ``order``.
+
+    ``models`` maps provider name -> {"small": model_id, "large": model_id}.
+    On ProviderError/RateLimitError, fail over to the next provider.
+    """
+
+    def __init__(
+        self,
+        providers: dict[str, LLMProvider],
+        order: list[str],
+        models: dict[str, dict[str, str]],
+        temperature: float = 0.3,
+    ) -> None:
+        self.providers = providers
+        self.order = order
+        self.models = models
+        self.temperature = temperature
+
+    async def chat(
+        self,
+        messages: list[dict[str, Any]],
+        tools: list[ToolSpec],
+        tier: str = "large",
+        temperature: float | None = None,
+    ) -> ChatResult:
+        last_exc: Exception | None = None
+        for name in self.order:
+            provider = self.providers.get(name)
+            if provider is None:
+                continue
+            model = self.models.get(name, {}).get(tier)
+            if not model:
+                continue
+            try:
+                return await provider.chat(
+                    messages=messages,
+                    tools=tools,
+                    model=model,
+                    temperature=self.temperature if temperature is None else temperature,
+                )
+            except ProviderError as exc:
+                log.warning("LLM provider %s failed (%s); failing over", name, exc)
+                last_exc = exc
+                continue
+        raise last_exc or ProviderError("no LLM providers configured")
+
+
+def build_router_from_settings(settings: Any) -> LLMRouter:
+    """Construct an LLMRouter from Settings, including only configured providers."""
+    from app.llm.cloudflare import CloudflareProvider
+    from app.llm.groq import GroqProvider
+
+    providers: dict[str, LLMProvider] = {}
+    models: dict[str, dict[str, str]] = {}
+
+    if settings.groq_api_key:
+        providers["groq"] = GroqProvider(
+            api_key=settings.groq_api_key, base_url=settings.groq_base_url
+        )
+        models["groq"] = {"small": settings.model_small, "large": settings.model_large}
+
+    if settings.cloudflare_account_id and settings.cloudflare_api_token:
+        providers["cloudflare"] = CloudflareProvider(
+            account_id=settings.cloudflare_account_id,
+            api_token=settings.cloudflare_api_token,
+        )
+        models["cloudflare"] = {
+            "small": settings.cf_model_small,
+            "large": settings.cf_model_large,
+        }
+
+    order = [p for p in settings.llm_provider_order if p in providers]
+    return LLMRouter(providers=providers, order=order, models=models)

app/mailer.py

@@ -0,0 +1,46 @@
+"""SMTP mailer for human-escalation notifications."""
+
+from __future__ import annotations
+
+import logging
+import smtplib
+from email.message import EmailMessage
+from typing import Any
+
+import anyio
+
+log = logging.getLogger(__name__)
+
+
+class SmtpMailer:
+    def __init__(self, settings: Any) -> None:
+        self.settings = settings
+
+    def _send_sync(self, to: str, subject: str, body: str) -> bool:
+        s = self.settings
+        if not s.smtp_host:
+            log.warning("SMTP not configured; escalation email not sent: %s", subject)
+            return False
+        msg = EmailMessage()
+        msg["From"] = s.smtp_from or s.smtp_user
+        msg["To"] = to
+        msg["Subject"] = subject
+        msg.set_content(body)
+        with smtplib.SMTP(s.smtp_host, s.smtp_port) as server:
+            server.starttls()
+            if s.smtp_user:
+                server.login(s.smtp_user, s.smtp_password)
+            server.send_message(msg)
+        return True
+
+    async def send(self, to: str, subject: str, body: str) -> bool:
+        return await anyio.to_thread.run_sync(self._send_sync, to, subject, body)
+
+
+def default_sender(settings: Any):
+    mailer = SmtpMailer(settings)
+
+    async def _sender(to: str, subject: str, body: str) -> bool:
+        return await mailer.send(to, subject, body)
+
+    return _sender

app/main.py

@@ -0,0 +1,72 @@
+"""FastAPI application factory."""
+
+from __future__ import annotations
+
+import logging
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app import db as dbmod
+from app.config import get_settings
+from app.routes import admin, chat, health, widget
+
+log = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    settings = get_settings()
+    if not dbmod.is_initialized():
+        dbmod.init_engine(settings.database_url)
+
+    if not settings.testing:
+        # Dev convenience for sqlite; Postgres uses Alembic migrations.
+        if dbmod.get_engine().dialect.name == "sqlite":
+            await dbmod.create_all()
+        # Warm the embedding model so the first chat isn't slow.
+        try:
+            from app.embeddings import embed_query
+
+            await embed_query("warmup")
+        except Exception:  # noqa: BLE001 - warmup is best-effort
+            log.warning("embedding warmup failed", exc_info=True)
+        # Ensure a 'default' tenant exists + GDPR retention sweep at boot.
+        try:
+            from app.retention import purge_old_sessions
+            from app.tenancy import ensure_default_tenant
+
+            async with dbmod.get_sessionmaker()() as session:
+                await ensure_default_tenant(session)
+                await purge_old_sessions(session, settings.session_retention_days)
+                await session.commit()
+        except Exception:  # noqa: BLE001 - best-effort
+            log.warning("startup sweep failed", exc_info=True)
+    yield
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    if not dbmod.is_initialized():
+        dbmod.init_engine(settings.database_url)
+
+    if not settings.testing and not settings.admin_token:
+        log.warning("ADMIN_TOKEN is empty — the admin panel/API will reject all requests")
+
+    app = FastAPI(title="Shopify Support Bot", version="0.1.0", lifespan=lifespan)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.allowed_origins,
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+    app.include_router(health.router)
+    app.include_router(widget.router)
+    app.include_router(chat.router)
+    app.include_router(admin.router)
+    return app
+
+
+app = create_app()

app/models.py

@@ -0,0 +1,154 @@
+"""ORM models. The embedding column uses pgvector on Postgres and JSON
+elsewhere (so unit tests run on sqlite)."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import (
+    JSON,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    types,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from app.db import Base
+
+EMBEDDING_DIM = 384
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class EmbeddingType(types.TypeDecorator):
+    """Vector(384) on Postgres, JSON list[float] on other dialects."""
+
+    impl = JSON
+    cache_ok = True
+
+    def load_dialect_impl(self, dialect):
+        if dialect.name == "postgresql":
+            from pgvector.sqlalchemy import Vector
+
+            return dialect.type_descriptor(Vector(EMBEDDING_DIM))
+        return dialect.type_descriptor(JSON())
+
+    def process_bind_param(self, value, dialect):
+        if value is None:
+            return None
+        return list(value)
+
+    def process_result_value(self, value, dialect):
+        if value is None:
+            return None
+        return list(value)
+
+
+class Config(Base):
+    __tablename__ = "config"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    key: Mapped[str] = mapped_column(String(100), unique=True, index=True)
+    value: Mapped[dict] = mapped_column(JSON, default=dict)
+
+
+class Tenant(Base):
+    """A merchant served by the shared multi-tenant backend."""
+
+    __tablename__ = "tenants"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    slug: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    name: Mapped[str] = mapped_column(String(255), default="")
+    brand_name: Mapped[str] = mapped_column(String(255), default="Asistente")
+    brand_color: Mapped[str] = mapped_column(String(16), default="#e8491d")
+    welcome: Mapped[str] = mapped_column(Text, default="¡Hola! ¿En qué puedo ayudarte?")
+    # Shopify (optional — only for order tracking / live catalog). Secret encrypted.
+    shopify_shop: Mapped[str] = mapped_column(String(255), default="")
+    shopify_client_id: Mapped[str] = mapped_column(String(255), default="")
+    shopify_client_secret_enc: Mapped[str] = mapped_column(Text, default="")
+    shopify_api_version: Mapped[str] = mapped_column(String(20), default="2026-01")
+    read_all_orders: Mapped[bool] = mapped_column(default=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+
+
+class KnowledgeSource(Base):
+    __tablename__ = "knowledge_sources"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    tenant_id: Mapped[int | None] = mapped_column(
+        ForeignKey("tenants.id", ondelete="CASCADE"), nullable=True, index=True
+    )
+    kind: Mapped[str] = mapped_column(String(10))  # "file" | "url"
+    name: Mapped[str] = mapped_column(String(500))
+    location: Mapped[str] = mapped_column(String(2000))  # file path or URL
+    status: Mapped[str] = mapped_column(String(20), default="pending")  # pending|indexed|error
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+
+    chunks: Mapped[list[KnowledgeChunk]] = relationship(
+        back_populates="source", cascade="all, delete-orphan"
+    )
+
+
+class KnowledgeChunk(Base):
+    __tablename__ = "knowledge_chunks"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    source_id: Mapped[int] = mapped_column(
+        ForeignKey("knowledge_sources.id", ondelete="CASCADE"), index=True
+    )
+    tenant_id: Mapped[int | None] = mapped_column(
+        ForeignKey("tenants.id", ondelete="CASCADE"), nullable=True, index=True
+    )
+    ordinal: Mapped[int] = mapped_column(Integer, default=0)
+    text: Mapped[str] = mapped_column(Text)
+    embedding: Mapped[list[float]] = mapped_column(EmbeddingType)
+    meta: Mapped[dict] = mapped_column(JSON, default=dict)
+
+    source: Mapped[KnowledgeSource] = relationship(back_populates="chunks")
+
+
+class ChatSession(Base):
+    __tablename__ = "chat_sessions"
+
+    id: Mapped[str] = mapped_column(String(40), primary_key=True, default=lambda: uuid.uuid4().hex)
+    tenant_id: Mapped[int | None] = mapped_column(
+        ForeignKey("tenants.id", ondelete="CASCADE"), nullable=True, index=True
+    )
+    shop: Mapped[str] = mapped_column(String(255), default="")
+    lang: Mapped[str | None] = mapped_column(String(10), nullable=True)
+    verified: Mapped[bool] = mapped_column(default=False)
+    verify_attempts: Mapped[int] = mapped_column(Integer, default=0)
+    locked_until: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+    last_seen: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=_utcnow, onupdate=_utcnow
+    )
+
+    messages: Mapped[list[ChatMessage]] = relationship(
+        back_populates="session",
+        cascade="all, delete-orphan",
+        order_by="ChatMessage.id",
+        lazy="selectin",
+    )
+
+
+class ChatMessage(Base):
+    __tablename__ = "chat_messages"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    session_id: Mapped[str] = mapped_column(
+        ForeignKey("chat_sessions.id", ondelete="CASCADE"), index=True
+    )
+    role: Mapped[str] = mapped_column(String(20))  # user|assistant|tool|system
+    content: Mapped[str] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+
+    session: Mapped[ChatSession] = relationship(back_populates="messages")

app/orchestrator.py

@@ -0,0 +1,97 @@
+"""Chat orchestrator: builds the prompt, runs the LLM tool loop, persists turn."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sqlalchemy import select
+
+from app.llm.base import ToolCall
+from app.models import ChatMessage
+from app.prompts import build_system_prompt
+from app.schemas import ChatResponse
+from app.tools import registry
+from app.tools.registry import ToolContext
+
+HISTORY_LIMIT = 10
+MAX_TOOL_ITERS = 4
+FALLBACK_REPLY = "Lo siento, ahora mismo no he podido completar la consulta. ¿Puedes reformularla?"
+
+
+def _toolcall_to_openai(tc: ToolCall) -> dict[str, Any]:
+    return {
+        "id": tc.id,
+        "type": "function",
+        "function": {"name": tc.name, "arguments": json.dumps(tc.arguments, ensure_ascii=False)},
+    }
+
+
+async def _load_history(ctx: ToolContext) -> list[ChatMessage]:
+    rows = (
+        await ctx.db.execute(
+            select(ChatMessage)
+            .where(ChatMessage.session_id == ctx.session.id)
+            .order_by(ChatMessage.id)
+        )
+    ).scalars().all()
+    return list(rows)[-HISTORY_LIMIT:]
+
+
+async def run_turn(
+    router: Any,
+    ctx: ToolContext,
+    user_message: str,
+    *,
+    brand_name: str = "Asistente",
+) -> ChatResponse:
+    prior = await _load_history(ctx)
+
+    messages: list[dict[str, Any]] = [
+        {"role": "system", "content": build_system_prompt(brand_name)}
+    ]
+    for m in prior:
+        if m.role in ("user", "assistant"):
+            messages.append({"role": m.role, "content": m.content})
+    messages.append({"role": "user", "content": user_message})
+
+    ctx.db.add(ChatMessage(session_id=ctx.session.id, role="user", content=user_message))
+    await ctx.db.flush()
+
+    used_tools: list[str] = []
+    reply = FALLBACK_REPLY
+
+    for _ in range(MAX_TOOL_ITERS):
+        result = await router.chat(messages=messages, tools=registry.specs(), tier="large")
+        if result.tool_calls:
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": result.content or "",
+                    "tool_calls": [_toolcall_to_openai(tc) for tc in result.tool_calls],
+                }
+            )
+            for tc in result.tool_calls:
+                used_tools.append(tc.name)
+                tool_result = await registry.dispatch(tc.name, tc.arguments, ctx)
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": json.dumps(tool_result, ensure_ascii=False, default=str),
+                    }
+                )
+            continue
+        reply = result.content or FALLBACK_REPLY
+        break
+    else:
+        # Tool budget exhausted: force a final answer with no tools.
+        final = await router.chat(messages=messages, tools=[], tier="large")
+        reply = final.content or FALLBACK_REPLY
+
+    ctx.db.add(ChatMessage(session_id=ctx.session.id, role="assistant", content=reply))
+    await ctx.db.flush()
+
+    return ChatResponse(
+        session_id=ctx.session.id, reply=reply, lang=ctx.session.lang, used_tools=used_tools
+    )

app/prompts.py

@@ -0,0 +1,30 @@
+"""System prompt builder for the support assistant."""
+# ruff: noqa: E501 - this module is a natural-language prompt template
+
+from __future__ import annotations
+
+SYSTEM_TEMPLATE = """Eres {brand_name}, el asistente virtual de atención al cliente de la tienda.
+
+Reglas de idioma:
+- Responde SIEMPRE en el mismo idioma en el que te escribe el cliente (detéctalo del último mensaje).
+- Si el cliente escribe en portugués, usa portugués de Portugal (pt-PT).
+
+Qué puedes hacer (usa las herramientas, no inventes datos):
+- Información de la tienda y productos: usa `search_knowledge` (base de conocimiento con fichas, PDFs y enlaces) y `search_products` (catálogo en vivo: precios y disponibilidad).
+- Estado de pedidos y seguimiento: usa `lookup_order`.
+
+Política de pedidos (privacidad):
+- Para consultar un pedido necesitas el email del cliente y el número de pedido. Pídelos si faltan.
+- Revela ÚNICAMENTE el estado del envío y la información de seguimiento (transportista, número, enlace, fecha estimada). NUNCA reveles la dirección completa ni datos de pago.
+- Si la verificación falla, di de forma genérica que no has podido verificar los datos. NO digas qué campo es incorrecto.
+- Tras varios intentos fallidos la consulta queda bloqueada temporalmente; pide al cliente que lo intente más tarde.
+
+Honestidad y escalado:
+- Si no sabes algo o no puedes resolverlo, dilo con honestidad. Ofrece pasar la consulta al equipo humano: pide el email del cliente y usa `escalate_to_human`.
+
+Tono: cercano, claro y útil. Respuestas breves.
+"""
+
+
+def build_system_prompt(brand_name: str = "Asistente") -> str:
+    return SYSTEM_TEMPLATE.format(brand_name=brand_name or "Asistente")

app/rag/chunk.py

@@ -0,0 +1,29 @@
+"""Deterministic sliding-window text chunking."""
+
+from __future__ import annotations
+
+
+def chunk_text(text: str, size: int = 1000, overlap: int = 200) -> list[str]:
+    """Split text into overlapping windows.
+
+    Each chunk is at most ``size`` chars; consecutive chunks share ``overlap``
+    chars. Whitespace-only input yields no chunks.
+    """
+    if size <= 0:
+        raise ValueError("size must be positive")
+    if overlap < 0 or overlap >= size:
+        raise ValueError("overlap must be in [0, size)")
+
+    text = text.strip()
+    if not text:
+        return []
+
+    chunks: list[str] = []
+    step = size - overlap
+    start = 0
+    while start < len(text):
+        piece = text[start : start + size].strip()
+        if piece:
+            chunks.append(piece)
+        start += step
+    return chunks

app/rag/extract.py

@@ -0,0 +1,82 @@
+"""Extract plain text from uploaded files and from URLs."""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import httpx
+from selectolax.parser import HTMLParser
+
+
+def extract_html(html: bytes | str) -> str:
+    """Strip tags/scripts/styles and return visible text."""
+    tree = HTMLParser(html if isinstance(html, str) else html.decode("utf-8", errors="replace"))
+    for tag in tree.css("script, style, noscript"):
+        tag.decompose()
+    body = tree.body or tree.root
+    if body is None:
+        return ""
+    text = body.text(separator=" ", strip=True)
+    return " ".join(text.split())
+
+
+async def extract_url(url: str, *, client: httpx.AsyncClient | None = None) -> str:
+    owns = client is None
+    client = client or httpx.AsyncClient(timeout=20.0, follow_redirects=True)
+    try:
+        resp = await client.get(url, headers={"User-Agent": "shopify-support-bot/0.1"})
+        resp.raise_for_status()
+        return extract_html(resp.content)
+    finally:
+        if owns:
+            await client.aclose()
+
+
+def _extract_pdf(data: bytes) -> str:
+    from pypdf import PdfReader
+
+    reader = PdfReader(io.BytesIO(data))
+    parts = [page.extract_text() or "" for page in reader.pages]
+    return "\n".join(parts).strip()
+
+
+def _extract_xlsx(data: bytes) -> str:
+    from openpyxl import load_workbook
+
+    wb = load_workbook(io.BytesIO(data), read_only=True, data_only=True)
+    lines: list[str] = []
+    for ws in wb.worksheets:
+        for row in ws.iter_rows(values_only=True):
+            cells = [str(c) for c in row if c is not None and str(c).strip()]
+            if cells:
+                lines.append(" ".join(cells))
+    wb.close()
+    return "\n".join(lines).strip()
+
+
+def _extract_docx(data: bytes) -> str:
+    from docx import Document
+
+    doc = Document(io.BytesIO(data))
+    return "\n".join(p.text for p in doc.paragraphs if p.text.strip()).strip()
+
+
+def extract_bytes(data: bytes, suffix: str) -> str:
+    suffix = suffix.lower().lstrip(".")
+    if suffix == "pdf":
+        return _extract_pdf(data)
+    if suffix in ("xlsx", "xlsm"):
+        return _extract_xlsx(data)
+    if suffix == "docx":
+        return _extract_docx(data)
+    if suffix in ("txt", "md", "csv"):
+        return data.decode("utf-8", errors="replace").strip()
+    if suffix in ("html", "htm"):
+        return extract_html(data)
+    raise ValueError(f"unsupported file type: .{suffix}")
+
+
+def extract_file(path: str | Path) -> str:
+    path = Path(path)
+    return extract_bytes(path.read_bytes(), path.suffix)

app/rag/index.py

@@ -0,0 +1,103 @@
+"""Index knowledge sources into chunks+embeddings and search them."""
+
+from __future__ import annotations
+
+import logging
+
+from sqlalchemy import delete, select, text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app import embeddings
+from app.db import get_engine
+from app.models import KnowledgeChunk, KnowledgeSource
+from app.rag import extract
+from app.rag.chunk import chunk_text
+
+log = logging.getLogger(__name__)
+
+
+async def _source_text(source: KnowledgeSource) -> str:
+    if source.kind == "url":
+        return await extract.extract_url(source.location)
+    return extract.extract_file(source.location)
+
+
+async def index_source(session: AsyncSession, source: KnowledgeSource) -> KnowledgeSource:
+    """Extract -> chunk -> embed -> store. Sets source.status."""
+    # clear any prior chunks for idempotent reindex
+    await session.execute(
+        delete(KnowledgeChunk).where(KnowledgeChunk.source_id == source.id)
+    )
+    try:
+        raw = await _source_text(source)
+        chunks = chunk_text(raw)
+        if not chunks:
+            source.status = "error"
+            source.error = "no extractable text"
+            await session.flush()
+            return source
+        vectors = await embeddings.embed_texts(chunks)
+        for ordinal, (chunk, vector) in enumerate(zip(chunks, vectors, strict=True)):
+            session.add(
+                KnowledgeChunk(
+                    source_id=source.id,
+                    tenant_id=source.tenant_id,
+                    ordinal=ordinal,
+                    text=chunk,
+                    embedding=vector,
+                    meta={"source_name": source.name},
+                )
+            )
+        source.status = "indexed"
+        source.error = None
+    except Exception as exc:  # noqa: BLE001 - surface any extraction/embed failure on the source
+        log.exception("indexing source %s failed", source.id)
+        source.status = "error"
+        source.error = str(exc)[:500]
+    await session.flush()
+    return source
+
+
+async def delete_source(session: AsyncSession, source_id: int) -> None:
+    await session.execute(
+        delete(KnowledgeChunk).where(KnowledgeChunk.source_id == source_id)
+    )
+    await session.execute(
+        delete(KnowledgeSource).where(KnowledgeSource.id == source_id)
+    )
+    await session.flush()
+
+
+async def reindex_all(session: AsyncSession, *, tenant_id: int | None = None) -> None:
+    stmt = select(KnowledgeSource)
+    if tenant_id is not None:
+        stmt = stmt.where(KnowledgeSource.tenant_id == tenant_id)
+    sources = (await session.execute(stmt)).scalars().all()
+    for source in sources:
+        await index_source(session, source)
+
+
+async def search(
+    session: AsyncSession, query: str, k: int = 4, *, tenant_id: int | None = None
+) -> list[tuple[KnowledgeChunk, float]]:
+    """Return up to k (chunk, cosine_score) pairs, most similar first.
+
+    When tenant_id is given, only that tenant's chunks are searched (isolation).
+    """
+    qvec = await embeddings.embed_query(query)
+    if get_engine().dialect.name == "postgresql":
+        vec_literal = "[" + ",".join(repr(float(x)) for x in qvec) + "]"
+        stmt = select(KnowledgeChunk)
+        if tenant_id is not None:
+            stmt = stmt.where(KnowledgeChunk.tenant_id == tenant_id)
+        stmt = stmt.order_by(text("embedding <=> (:qv)::vector")).limit(k)
+        rows = (await session.execute(stmt, {"qv": vec_literal})).scalars().all()
+        return [(c, embeddings.cosine(qvec, c.embedding)) for c in rows]
+
+    stmt = select(KnowledgeChunk)
+    if tenant_id is not None:
+        stmt = stmt.where(KnowledgeChunk.tenant_id == tenant_id)
+    chunks = (await session.execute(stmt)).scalars().all()
+    scored = [(c, embeddings.cosine(qvec, c.embedding)) for c in chunks]
+    scored.sort(key=lambda pair: pair[1], reverse=True)
+    return scored[:k]

app/ratelimit.py

@@ -0,0 +1,48 @@
+"""In-process fixed-window rate limiter.
+
+Used to throttle order-verification attempts per email so the per-session
+lockout can't be bypassed by rotating the client-supplied session_id.
+Single-instance only (state is in-memory); fine for one Railway service.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import UTC, datetime
+
+from app.config import get_settings
+
+
+class RateLimiter:
+    def __init__(self, max_hits: int, window_seconds: int) -> None:
+        self.max_hits = max_hits
+        self.window = window_seconds
+        self._hits: dict[str, list[float]] = defaultdict(list)
+
+    def allow(self, key: str, now: datetime | None = None) -> bool:
+        ts = (now or datetime.now(UTC)).timestamp()
+        cutoff = ts - self.window
+        hits = [h for h in self._hits[key] if h > cutoff]
+        if len(hits) >= self.max_hits:
+            self._hits[key] = hits
+            return False
+        hits.append(ts)
+        self._hits[key] = hits
+        return True
+
+    def reset(self, key: str) -> None:
+        self._hits.pop(key, None)
+
+    def clear(self) -> None:
+        self._hits.clear()
+
+
+_order_limiter: RateLimiter | None = None
+
+
+def get_order_limiter() -> RateLimiter:
+    global _order_limiter
+    if _order_limiter is None:
+        s = get_settings()
+        _order_limiter = RateLimiter(s.order_verify_max_attempts, s.order_verify_lockout_seconds)
+    return _order_limiter

app/retention.py

@@ -0,0 +1,23 @@
+"""GDPR retention: purge chat sessions/messages older than N days."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import ChatMessage, ChatSession
+
+
+async def purge_old_sessions(db: AsyncSession, days: int) -> int:
+    cutoff = datetime.now(UTC) - timedelta(days=days)
+    ids = (
+        await db.execute(select(ChatSession.id).where(ChatSession.last_seen < cutoff))
+    ).scalars().all()
+    if not ids:
+        return 0
+    await db.execute(delete(ChatMessage).where(ChatMessage.session_id.in_(ids)))
+    await db.execute(delete(ChatSession).where(ChatSession.id.in_(ids)))
+    await db.flush()
+    return len(ids)

app/routes/admin.py

@@ -0,0 +1,166 @@
+"""Admin API + UI (multi-tenant): manage tenants + their knowledge sources.
+
+Super-admin (Bearer ADMIN_TOKEN) manages all tenants. Everything except the
+HTML page requires auth.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
+from fastapi.responses import HTMLResponse
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import get_session
+from app.deps import require_admin
+from app.models import KnowledgeSource, Tenant
+from app.rag import index
+from app.schemas import SourceIn, SourceOut, TenantIn, TenantOut, TenantUpdate
+from app.tenancy import create_tenant, get_tenant_by_slug, list_tenants, update_tenant
+
+router = APIRouter(prefix="/admin")
+
+_UI_PATH = Path(__file__).resolve().parent.parent / "admin_ui" / "index.html"
+_SAFE = re.compile(r"[^A-Za-z0-9._-]")
+_ALLOWED_EXTS = {".pdf", ".xlsx", ".xlsm", ".docx", ".txt", ".md", ".csv", ".html", ".htm"}
+_MAX_UPLOAD_BYTES = 25 * 1024 * 1024  # 25 MB
+
+
+@router.get("/", response_class=HTMLResponse)
+async def admin_ui() -> HTMLResponse:
+    return HTMLResponse(_UI_PATH.read_text(encoding="utf-8"))
+
+
+async def _require_tenant(db: AsyncSession, slug: str) -> Tenant:
+    tenant = await get_tenant_by_slug(db, slug)
+    if tenant is None:
+        raise HTTPException(status_code=404, detail="unknown tenant")
+    return tenant
+
+
+# ── Tenants ─────────────────────────────────────────────────────────────
+@router.get("/tenants", dependencies=[Depends(require_admin)])
+async def get_tenants(db: AsyncSession = Depends(get_session)) -> list[TenantOut]:
+    return [TenantOut.from_tenant(t) for t in await list_tenants(db)]
+
+
+@router.post("/tenants", status_code=201, dependencies=[Depends(require_admin)])
+async def post_tenant(body: TenantIn, db: AsyncSession = Depends(get_session)) -> TenantOut:
+    if await get_tenant_by_slug(db, body.slug) is not None:
+        raise HTTPException(status_code=409, detail="slug already exists")
+    fields = body.model_dump(exclude={"slug", "shopify_client_secret"}, exclude_none=True)
+    tenant = await create_tenant(
+        db, body.slug, shopify_client_secret=body.shopify_client_secret, **fields
+    )
+    await db.commit()
+    return TenantOut.from_tenant(tenant)
+
+
+@router.put("/tenants/{slug}", dependencies=[Depends(require_admin)])
+async def put_tenant(
+    slug: str, body: TenantUpdate, db: AsyncSession = Depends(get_session)
+) -> TenantOut:
+    tenant = await _require_tenant(db, slug)
+    fields = body.model_dump(exclude={"shopify_client_secret"}, exclude_none=True)
+    await update_tenant(
+        db, tenant, shopify_client_secret=body.shopify_client_secret, **fields
+    )
+    await db.commit()
+    return TenantOut.from_tenant(tenant)
+
+
+# ── Knowledge sources (per tenant) ──────────────────────────────────────
+@router.get("/tenants/{slug}/sources", dependencies=[Depends(require_admin)])
+async def list_sources(
+    slug: str, db: AsyncSession = Depends(get_session)
+) -> list[SourceOut]:
+    tenant = await _require_tenant(db, slug)
+    rows = (
+        await db.execute(
+            select(KnowledgeSource)
+            .where(KnowledgeSource.tenant_id == tenant.id)
+            .order_by(KnowledgeSource.id)
+        )
+    ).scalars().all()
+    return [SourceOut.model_validate(r, from_attributes=True) for r in rows]
+
+
+@router.post("/tenants/{slug}/sources/url", status_code=201, dependencies=[Depends(require_admin)])
+async def add_url_source(
+    slug: str, body: SourceIn, db: AsyncSession = Depends(get_session)
+) -> SourceOut:
+    tenant = await _require_tenant(db, slug)
+    if not body.location:
+        raise HTTPException(status_code=422, detail="location required for url sources")
+    src = KnowledgeSource(
+        kind="url", name=body.location, location=body.location, tenant_id=tenant.id
+    )
+    db.add(src)
+    await db.flush()
+    await index.index_source(db, src)
+    await db.commit()
+    return SourceOut.model_validate(src, from_attributes=True)
+
+
+@router.post("/tenants/{slug}/sources/file", status_code=201, dependencies=[Depends(require_admin)])
+async def add_file_source(
+    slug: str,
+    file: UploadFile = File(...),
+    db: AsyncSession = Depends(get_session),
+) -> SourceOut:
+    tenant = await _require_tenant(db, slug)
+    safe_name = _SAFE.sub("_", file.filename or "upload")
+    if safe_name in (".", "..", ""):
+        raise HTTPException(status_code=422, detail="invalid filename")
+    if Path(safe_name).suffix.lower() not in _ALLOWED_EXTS:
+        raise HTTPException(
+            status_code=415, detail=f"unsupported file type; allowed: {sorted(_ALLOWED_EXTS)}"
+        )
+    data = await file.read()
+    if len(data) > _MAX_UPLOAD_BYTES:
+        raise HTTPException(status_code=413, detail="file too large (max 25 MB)")
+
+    upload_dir = Path("uploads") / tenant.slug
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    dest = upload_dir / safe_name
+    dest.write_bytes(data)
+
+    src = KnowledgeSource(
+        kind="file", name=safe_name, location=str(dest), tenant_id=tenant.id
+    )
+    db.add(src)
+    await db.flush()
+    await index.index_source(db, src)
+    await db.commit()
+    return SourceOut.model_validate(src, from_attributes=True)
+
+
+@router.delete("/tenants/{slug}/sources/{source_id}", dependencies=[Depends(require_admin)])
+async def delete_source(
+    slug: str, source_id: int, db: AsyncSession = Depends(get_session)
+) -> dict[str, bool]:
+    tenant = await _require_tenant(db, slug)
+    src = (
+        await db.execute(
+            select(KnowledgeSource).where(
+                KnowledgeSource.id == source_id,
+                KnowledgeSource.tenant_id == tenant.id,
+            )
+        )
+    ).scalar_one_or_none()
+    if src is None:
+        raise HTTPException(status_code=404, detail="source not found for tenant")
+    await index.delete_source(db, source_id)
+    await db.commit()
+    return {"deleted": True}
+
+
+@router.post("/tenants/{slug}/reindex", dependencies=[Depends(require_admin)])
+async def reindex(slug: str, db: AsyncSession = Depends(get_session)) -> dict[str, str]:
+    tenant = await _require_tenant(db, slug)
+    await index.reindex_all(db, tenant_id=tenant.id)
+    await db.commit()
+    return {"status": "reindexed"}

app/routes/chat.py

@@ -0,0 +1,161 @@
+"""Chat endpoints (multi-tenant).
+
+- POST /chat?t=<slug>   — simple mode: public, CORS-enabled, no signature. The
+                          backend-served widget uses this (one <script> to embed).
+- POST /apps/chat       — secure mode: behind the Shopify App Proxy (HMAC); tenant
+                          resolved from the signed `shop` param (or ?t).
+
+Both share one handler. Order disclosure always requires email+order#
+verification + per-email rate limiting regardless of entry point.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.config import Settings, get_settings
+from app.db import get_session
+from app.deps import get_router
+from app.models import Tenant
+from app.orchestrator import run_turn
+from app.retention import purge_old_sessions
+from app.schemas import ChatRequest, ChatResponse
+from app.shopify.proxy import verify_proxy_signature
+from app.store import get_or_create_session
+from app.tenancy import DEFAULT_SLUG, get_tenant_by_slug, tenant_shopify_client
+from app.tools.registry import ToolContext
+from app.verification import mark_trusted
+
+router = APIRouter()
+
+PROXY_TIMESTAMP_TOLERANCE = 300  # seconds; reject replayed/stale signed requests
+
+
+def _collect_params(request: Request) -> dict[str, object]:
+    """Preserve repeated query keys as lists (required for correct HMAC)."""
+    params: dict[str, object] = {}
+    for key, value in request.query_params.multi_items():
+        if key in params:
+            existing = params[key]
+            if isinstance(existing, list):
+                existing.append(value)
+            else:
+                params[key] = [existing, value]
+        else:
+            params[key] = value
+    return params
+
+
+def _timestamp_fresh(params: dict[str, object], now: datetime) -> bool:
+    raw = params.get("timestamp")
+    if not isinstance(raw, str) or not raw.isdigit():
+        return False
+    return abs(now.timestamp() - int(raw)) <= PROXY_TIMESTAMP_TOLERANCE
+
+
+async def _resolve_tenant(db: AsyncSession, slug: str | None, *, shop: str = "") -> Tenant:
+    if slug:
+        tenant = await get_tenant_by_slug(db, slug)
+        if tenant is not None:
+            return tenant
+    if shop:
+        tenant = (
+            await db.execute(select(Tenant).where(Tenant.shopify_shop == shop))
+        ).scalar_one_or_none()
+        if tenant is not None:
+            return tenant
+    tenant = await get_tenant_by_slug(db, DEFAULT_SLUG)
+    if tenant is None:
+        raise HTTPException(status_code=404, detail="unknown tenant")
+    return tenant
+
+
+async def _run_chat(
+    *,
+    db: AsyncSession,
+    router_,
+    settings: Settings,
+    tenant: Tenant,
+    message: str,
+    session_id: str | None,
+    trusted: bool,
+    now: datetime,
+) -> ChatResponse:
+    session = await get_or_create_session(
+        db, session_id, shop=tenant.shopify_shop, tenant_id=tenant.id
+    )
+    if trusted:
+        mark_trusted(session)
+    ctx = ToolContext(
+        db=db,
+        session=session,
+        shopify=tenant_shopify_client(tenant),
+        tenant_id=tenant.id,
+        support_email=settings.support_email,
+        now=now,
+    )
+    response = await run_turn(router_, ctx, message, brand_name=tenant.brand_name)
+    await purge_old_sessions(db, settings.session_retention_days)
+    await db.commit()
+    return response
+
+
+@router.post("/chat", response_model=ChatResponse)
+async def chat_simple(
+    body: ChatRequest,
+    request: Request,
+    db: AsyncSession = Depends(get_session),
+    router_=Depends(get_router),
+    settings: Settings = Depends(get_settings),
+) -> ChatResponse:
+    """Simple-mode chat: public + CORS. No proxy signature required."""
+    tenant = await _resolve_tenant(db, request.query_params.get("t"))
+    return await _run_chat(
+        db=db,
+        router_=router_,
+        settings=settings,
+        tenant=tenant,
+        message=body.message,
+        session_id=body.session_id,
+        trusted=False,
+        now=datetime.now(UTC),
+    )
+
+
+@router.post("/apps/chat", response_model=ChatResponse)
+async def chat_proxied(
+    body: ChatRequest,
+    request: Request,
+    db: AsyncSession = Depends(get_session),
+    router_=Depends(get_router),
+    settings: Settings = Depends(get_settings),
+) -> ChatResponse:
+    """Secure-mode chat: behind the Shopify App Proxy (HMAC + timestamp)."""
+    now = datetime.now(UTC)
+    params = _collect_params(request)
+    if not verify_proxy_signature(params, settings.shopify_app_proxy_secret):
+        raise HTTPException(status_code=401, detail="invalid proxy signature")
+    if not _timestamp_fresh(params, now):
+        raise HTTPException(status_code=401, detail="stale or missing timestamp")
+
+    shop = params.get("shop", "")
+    t = params.get("t")
+    tenant = await _resolve_tenant(
+        db,
+        t if isinstance(t, str) else None,
+        shop=shop if isinstance(shop, str) else "",
+    )
+    return await _run_chat(
+        db=db,
+        router_=router_,
+        settings=settings,
+        tenant=tenant,
+        message=body.message,
+        session_id=body.session_id,
+        trusted=bool(params.get("logged_in_customer_id")),
+        now=now,
+    )

app/routes/health.py

@@ -0,0 +1,12 @@
+"""Health check."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+router = APIRouter()
+
+
+@router.get("/healthz")
+async def healthz() -> dict[str, str]:
+    return {"status": "ok"}

app/routes/widget.py

@@ -0,0 +1,49 @@
+"""Serve the embeddable chat widget (simple mode, multi-tenant).
+
+Embed in any Shopify theme with a single line (the ?t is the tenant slug):
+    <script src="https://YOUR_BACKEND/widget.js?t=toorx" defer></script>
+The widget auto-detects its backend + tenant from its own <script> src, reads
+branding from /widget-config?t=, and posts to /chat?t=. No App Proxy / CLI needed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import FileResponse
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import get_session
+from app.tenancy import DEFAULT_SLUG, get_tenant_by_slug
+
+router = APIRouter()
+
+_WIDGET_JS = Path(__file__).resolve().parent.parent / "static" / "widget.js"
+
+
+@router.get("/widget.js")
+async def widget_js() -> FileResponse:
+    return FileResponse(
+        _WIDGET_JS,
+        media_type="application/javascript",
+        headers={"Cache-Control": "public, max-age=300"},
+    )
+
+
+@router.get("/widget-config")
+async def widget_config(
+    t: str = DEFAULT_SLUG, db: AsyncSession = Depends(get_session)
+) -> dict[str, str]:
+    tenant = await get_tenant_by_slug(db, t)
+    if tenant is None:
+        return {
+            "brand_name": "Asistente",
+            "brand_color": "#e8491d",
+            "welcome": "¡Hola! ¿En qué puedo ayudarte?",
+        }
+    return {
+        "brand_name": tenant.brand_name,
+        "brand_color": tenant.brand_color,
+        "welcome": tenant.welcome,
+    }

app/schemas.py

@@ -0,0 +1,96 @@
+"""Pydantic request/response models for the HTTP API."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class ChatRequest(BaseModel):
+    message: str = Field(min_length=1, max_length=4000)
+    session_id: str | None = None
+
+
+class ChatResponse(BaseModel):
+    session_id: str
+    reply: str
+    lang: str | None = None
+    used_tools: list[str] = Field(default_factory=list)
+
+
+class SourceIn(BaseModel):
+    kind: str = Field(pattern="^(file|url)$")
+    location: str | None = None  # URL for kind="url"; ignored for file uploads
+
+
+class SourceOut(BaseModel):
+    id: int
+    kind: str
+    name: str
+    location: str
+    status: str
+    error: str | None = None
+    created_at: datetime
+
+
+class ConfigIn(BaseModel):
+    brand_name: str | None = None
+    brand_color: str | None = None
+    welcome: str | None = None
+    read_all_orders: bool | None = None
+
+
+class TenantIn(BaseModel):
+    slug: str = Field(pattern=r"^[a-z0-9][a-z0-9-]{1,63}$")
+    name: str | None = None
+    brand_name: str | None = None
+    brand_color: str | None = None
+    welcome: str | None = None
+    shopify_shop: str | None = None
+    shopify_client_id: str | None = None
+    shopify_client_secret: str | None = None
+    shopify_api_version: str | None = None
+    read_all_orders: bool | None = None
+
+
+class TenantUpdate(BaseModel):
+    name: str | None = None
+    brand_name: str | None = None
+    brand_color: str | None = None
+    welcome: str | None = None
+    shopify_shop: str | None = None
+    shopify_client_id: str | None = None
+    shopify_client_secret: str | None = None
+    shopify_api_version: str | None = None
+    read_all_orders: bool | None = None
+
+
+class TenantOut(BaseModel):
+    id: int
+    slug: str
+    name: str
+    brand_name: str
+    brand_color: str
+    welcome: str
+    shopify_shop: str
+    shopify_client_id: str
+    has_shopify_secret: bool
+    shopify_api_version: str
+    read_all_orders: bool
+
+    @classmethod
+    def from_tenant(cls, t) -> TenantOut:
+        return cls(
+            id=t.id,
+            slug=t.slug,
+            name=t.name,
+            brand_name=t.brand_name,
+            brand_color=t.brand_color,
+            welcome=t.welcome,
+            shopify_shop=t.shopify_shop,
+            shopify_client_id=t.shopify_client_id,
+            has_shopify_secret=bool(t.shopify_client_secret_enc),
+            shopify_api_version=t.shopify_api_version,
+            read_all_orders=t.read_all_orders,
+        )

app/shopify/client.py

@@ -0,0 +1,95 @@
+"""Thin async GraphQL Admin API client."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+import httpx
+
+from app.shopify.token import ShopifyTokenManager
+
+log = logging.getLogger(__name__)
+
+
+class ShopifyError(Exception):
+    pass
+
+
+class ShopifyGraphQLClient:
+    def __init__(
+        self,
+        shop: str,
+        api_version: str,
+        token_manager: ShopifyTokenManager,
+        *,
+        client: httpx.AsyncClient | None = None,
+        max_throttle_retries: int = 2,
+    ) -> None:
+        self.shop = shop
+        self.api_version = api_version
+        self.token_manager = token_manager
+        self._client = client
+        self._max_throttle_retries = max_throttle_retries
+
+    @property
+    def _url(self) -> str:
+        return f"https://{self.shop}/admin/api/{self.api_version}/graphql.json"
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=20.0)
+        return self._client
+
+    async def execute(
+        self, query: str, variables: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        payload = {"query": query, "variables": variables or {}}
+        auth_retried = False
+        throttle_tries = 0
+
+        while True:
+            token = await self.token_manager.get_token()
+            resp = await self._get_client().post(
+                self._url,
+                json=payload,
+                headers={
+                    "X-Shopify-Access-Token": token,
+                    "Content-Type": "application/json",
+                },
+            )
+
+            if resp.status_code == 401 and not auth_retried:
+                self.token_manager.invalidate()
+                auth_retried = True
+                continue
+
+            if resp.status_code == 429:
+                if throttle_tries < self._max_throttle_retries:
+                    throttle_tries += 1
+                    await asyncio.sleep(0.5 * throttle_tries)
+                    continue
+                raise ShopifyError("throttled (429) after retries")
+
+            if resp.status_code >= 400:
+                raise ShopifyError(f"http {resp.status_code}: {resp.text[:300]}")
+
+            body = resp.json()
+            if body.get("errors"):
+                # Retry once on THROTTLED user errors
+                codes = {
+                    (e.get("extensions") or {}).get("code") for e in body["errors"]
+                }
+                if "THROTTLED" in codes and throttle_tries < self._max_throttle_retries:
+                    throttle_tries += 1
+                    await asyncio.sleep(0.5 * throttle_tries)
+                    continue
+                raise ShopifyError(f"graphql errors: {body['errors']}")
+
+            return body.get("data", {})
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None

app/shopify/orders.py

@@ -0,0 +1,120 @@
+"""Order lookup + fulfillment/tracking parsing (GraphQL Admin API).
+
+Note: with the plain ``read_orders`` scope only orders from the last 60 days
+are visible. Older history needs the protected ``read_all_orders`` scope.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from app.shopify.client import ShopifyGraphQLClient
+
+_EMAIL_RE = re.compile(r"^[^@\s\"]+@[^@\s\"]+\.[^@\s\"]+$")
+
+
+def build_email_filter(email: str) -> str:
+    """Build a Shopify search filter for an email, validated + escaped.
+
+    Prevents search-query ('q') injection via crafted email values.
+    """
+    e = email.strip()
+    if not _EMAIL_RE.match(e):
+        raise ValueError("invalid email")
+    e = e.replace("\\", "\\\\").replace('"', '\\"')
+    return f'email:"{e}"'
+
+ORDERS_BY_EMAIL_QUERY = """
+query OrdersByEmail($q: String!) {
+  orders(first: 10, query: $q, sortKey: CREATED_AT, reverse: true) {
+    edges {
+      node {
+        id
+        name
+        createdAt
+        email
+        displayFinancialStatus
+        displayFulfillmentStatus
+        customer { firstName lastName email }
+        fulfillments(first: 10) {
+          displayStatus
+          estimatedDeliveryAt
+          inTransitAt
+          deliveredAt
+          trackingInfo { company number url }
+        }
+      }
+    }
+  }
+}
+"""
+
+
+def normalize_order_number(value: str) -> str:
+    return value.strip().lstrip("#").strip().lower()
+
+
+def _parse_order(node: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": node.get("id"),
+        "name": node.get("name", ""),
+        "created_at": node.get("createdAt"),
+        "email": node.get("email") or (node.get("customer") or {}).get("email") or "",
+        "financial_status": node.get("displayFinancialStatus"),
+        "fulfillment_status": node.get("displayFulfillmentStatus"),
+        "fulfillments": node.get("fulfillments", []),
+    }
+
+
+async def find_orders_by_email(
+    client: ShopifyGraphQLClient, email: str
+) -> list[dict[str, Any]]:
+    data = await client.execute(ORDERS_BY_EMAIL_QUERY, {"q": build_email_filter(email)})
+    edges = data.get("orders", {}).get("edges", [])
+    return [_parse_order(e["node"]) for e in edges]
+
+
+async def find_order_by_email_and_number(
+    client: ShopifyGraphQLClient, email: str, order_number: str
+) -> dict[str, Any] | None:
+    target = normalize_order_number(order_number)
+    for order in await find_orders_by_email(client, email):
+        if (
+            order["email"].lower() == email.strip().lower()
+            and normalize_order_number(order["name"]) == target
+        ):
+            return order
+    return None
+
+
+def parse_tracking(order: dict[str, Any]) -> dict[str, Any]:
+    """Summarise shipment status + tracking for an order (no PII beyond tracking)."""
+    fulfillments = order.get("fulfillments", []) or []
+    tracking: list[dict[str, Any]] = []
+    status = None
+    estimated_delivery = None
+    delivered_at = None
+    in_transit_at = None
+    for f in fulfillments:
+        status = f.get("displayStatus") or status
+        estimated_delivery = f.get("estimatedDeliveryAt") or estimated_delivery
+        delivered_at = f.get("deliveredAt") or delivered_at
+        in_transit_at = f.get("inTransitAt") or in_transit_at
+        for t in f.get("trackingInfo", []) or []:
+            tracking.append(
+                {
+                    "company": t.get("company"),
+                    "number": t.get("number"),
+                    "url": t.get("url"),
+                }
+            )
+    return {
+        "order_number": order.get("name"),
+        "fulfillment_status": order.get("fulfillment_status"),
+        "shipment_status": status,
+        "tracking": tracking,
+        "estimated_delivery": estimated_delivery,
+        "delivered_at": delivered_at,
+        "in_transit_at": in_transit_at,
+    }

app/shopify/products.py

@@ -0,0 +1,54 @@
+"""Live product search against the Shopify catalog (GraphQL Admin API)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.shopify.client import ShopifyGraphQLClient
+
+PRODUCTS_QUERY = """
+query ProductSearch($q: String!) {
+  products(first: 5, query: $q) {
+    edges {
+      node {
+        title
+        handle
+        onlineStoreUrl
+        description
+        variants(first: 50) {
+          edges { node { price availableForSale } }
+        }
+      }
+    }
+  }
+}
+"""
+
+
+def _truncate(text: str | None, n: int = 400) -> str:
+    text = (text or "").strip()
+    return text if len(text) <= n else text[:n].rstrip() + "…"
+
+
+def _parse_product(node: dict[str, Any]) -> dict[str, Any]:
+    variant_nodes = [e["node"] for e in node.get("variants", {}).get("edges", [])]
+    prices = []
+    for v in variant_nodes:
+        try:
+            prices.append(float(v.get("price")))
+        except (TypeError, ValueError):
+            continue
+    available = any(v.get("availableForSale") for v in variant_nodes)
+    return {
+        "title": node.get("title", ""),
+        "price": min(prices) if prices else None,
+        "available": available,
+        "url": node.get("onlineStoreUrl"),
+        "description": _truncate(node.get("description")),
+    }
+
+
+async def search_products(client: ShopifyGraphQLClient, query: str) -> list[dict[str, Any]]:
+    data = await client.execute(PRODUCTS_QUERY, {"q": query})
+    edges = data.get("products", {}).get("edges", [])
+    return [_parse_product(e["node"]) for e in edges]

app/shopify/proxy.py

@@ -0,0 +1,33 @@
+"""Shopify App Proxy request signature verification.
+
+Shopify signs proxied storefront requests: sort the query params (excluding
+``signature``), format each as ``key=value`` (array values joined by commas),
+concatenate WITHOUT separators, then HMAC-SHA256 with the app's shared secret.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def compute_proxy_signature(params: dict[str, object], secret: str) -> str:
+    items = {k: v for k, v in params.items() if k != "signature"}
+    parts = []
+    for key in sorted(items):
+        value = items[key]
+        if isinstance(value, (list, tuple)):
+            value = ",".join(str(v) for v in value)
+        parts.append(f"{key}={value}")
+    message = "".join(parts)
+    return hmac.new(
+        secret.encode("utf-8"), message.encode("utf-8"), hashlib.sha256
+    ).hexdigest()
+
+
+def verify_proxy_signature(params: dict[str, object], secret: str) -> bool:
+    provided = params.get("signature")
+    if not provided or not isinstance(provided, str):
+        return False
+    expected = compute_proxy_signature(params, secret)
+    return hmac.compare_digest(expected, provided)

app/shopify/token.py

@@ -0,0 +1,86 @@
+"""Shopify Admin API access token via the client_credentials grant.
+
+New (2026) custom apps no longer expose a static token; you exchange the
+app's client_id/secret for a token that expires in ~24h, so it must be
+refreshed programmatically.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+
+import httpx
+
+REFRESH_SKEW = timedelta(seconds=60)
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+class ShopifyTokenManager:
+    def __init__(
+        self,
+        shop: str,
+        client_id: str,
+        client_secret: str,
+        *,
+        now: Callable[[], datetime] = _now,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.shop = shop
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self._now = now
+        self._client = client
+        self._token: str | None = None
+        self._expires_at: datetime | None = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def _url(self) -> str:
+        return f"https://{self.shop}/admin/oauth/access_token"
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=20.0)
+        return self._client
+
+    def invalidate(self) -> None:
+        self._token = None
+        self._expires_at = None
+
+    def _is_fresh(self) -> bool:
+        return (
+            self._token is not None
+            and self._expires_at is not None
+            and self._now() < self._expires_at - REFRESH_SKEW
+        )
+
+    async def get_token(self) -> str:
+        if self._is_fresh():
+            return self._token  # type: ignore[return-value]
+        async with self._lock:
+            if self._is_fresh():
+                return self._token  # type: ignore[return-value]
+            resp = await self._get_client().post(
+                self._url,
+                json={
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                    "grant_type": "client_credentials",
+                },
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            self._token = data["access_token"]
+            expires_in = int(data.get("expires_in", 86399))
+            self._expires_at = self._now() + timedelta(seconds=expires_in)
+            return self._token
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None

app/static/widget.js

@@ -0,0 +1,104 @@
+/* Backend-served support chat widget (simple mode).
+   Embed: <script src="https://BACKEND/widget.js" defer></script>
+   Auto-detects its backend from its own origin and posts to BACKEND/chat. */
+(function () {
+  "use strict";
+
+  // Resolve our backend origin from this script's own URL.
+  var me = document.currentScript;
+  if (!me) {
+    var scripts = document.getElementsByTagName("script");
+    for (var i = scripts.length - 1; i >= 0; i--) {
+      if (scripts[i].src && scripts[i].src.indexOf("/widget.js") !== -1) { me = scripts[i]; break; }
+    }
+  }
+  var SRC = me ? new URL(me.src) : null;
+  var BACKEND = SRC ? SRC.origin : "";
+  var TENANT = (SRC && SRC.searchParams.get("t")) || "default";
+  var QS = "?t=" + encodeURIComponent(TENANT);
+  var SESSION_KEY = "ssb_session_id_" + TENANT;
+
+  var cfg = { brand_name: "Asistente", brand_color: "#e8491d", welcome: "¡Hola! ¿En qué puedo ayudarte?" };
+
+  function getSessionId() { try { return localStorage.getItem(SESSION_KEY) || null; } catch (e) { return null; } }
+  function setSessionId(id) { try { if (id) localStorage.setItem(SESSION_KEY, id); } catch (e) {} }
+
+  function injectStyles() {
+    var c = cfg.brand_color;
+    var style = document.createElement("style");
+    style.textContent =
+      "#ssb-bubble{position:fixed;bottom:20px;right:20px;width:60px;height:60px;border-radius:50%;background:" + c +
+      ";color:#fff;border:0;cursor:pointer;font-size:26px;box-shadow:0 4px 14px rgba(0,0,0,.25);z-index:99998}" +
+      "#ssb-panel{position:fixed;bottom:90px;right:20px;width:360px;max-width:92vw;height:520px;max-height:74vh;background:#fff;" +
+      "border-radius:14px;box-shadow:0 10px 40px rgba(0,0,0,.25);display:none;flex-direction:column;overflow:hidden;z-index:99999;font-family:system-ui,sans-serif}" +
+      "#ssb-panel.open{display:flex}" +
+      "#ssb-head{background:" + c + ";color:#fff;padding:14px 16px;font-weight:600}" +
+      "#ssb-msgs{flex:1;overflow-y:auto;padding:14px;background:#f7f7f7}" +
+      ".ssb-msg{margin:6px 0;padding:9px 12px;border-radius:12px;max-width:80%;white-space:pre-wrap;line-height:1.35;font-size:14px}" +
+      ".ssb-user{background:" + c + ";color:#fff;margin-left:auto;border-bottom-right-radius:3px}" +
+      ".ssb-bot{background:#fff;color:#1a1a1a;border:1px solid #e3e3e3;border-bottom-left-radius:3px}" +
+      "#ssb-form{display:flex;border-top:1px solid #e3e3e3}" +
+      "#ssb-input{flex:1;border:0;padding:13px;font-size:14px;outline:none}" +
+      "#ssb-send{border:0;background:" + c + ";color:#fff;padding:0 18px;cursor:pointer;font-size:16px}";
+    document.head.appendChild(style);
+  }
+
+  function build() {
+    injectStyles();
+    var bubble = document.createElement("button");
+    bubble.id = "ssb-bubble"; bubble.setAttribute("aria-label", "Abrir chat"); bubble.textContent = "💬";
+    var panel = document.createElement("div");
+    panel.id = "ssb-panel";
+    panel.innerHTML =
+      '<div id="ssb-head"></div><div id="ssb-msgs"></div>' +
+      '<form id="ssb-form"><input id="ssb-input" type="text" autocomplete="off" placeholder="Escribe aquí…" />' +
+      '<button id="ssb-send" type="submit" aria-label="Enviar">➤</button></form>';
+    document.body.appendChild(bubble);
+    document.body.appendChild(panel);
+    panel.querySelector("#ssb-head").textContent = cfg.brand_name;
+
+    var msgs = panel.querySelector("#ssb-msgs");
+    var form = panel.querySelector("#ssb-form");
+    var input = panel.querySelector("#ssb-input");
+    var greeted = false;
+
+    function addMsg(text, who) {
+      var el = document.createElement("div");
+      el.className = "ssb-msg " + (who === "user" ? "ssb-user" : "ssb-bot");
+      el.textContent = text; msgs.appendChild(el); msgs.scrollTop = msgs.scrollHeight; return el;
+    }
+    bubble.addEventListener("click", function () {
+      panel.classList.toggle("open");
+      if (panel.classList.contains("open")) {
+        if (!greeted) { addMsg(cfg.welcome, "bot"); greeted = true; }
+        input.focus();
+      }
+    });
+    form.addEventListener("submit", function (e) {
+      e.preventDefault();
+      var text = input.value.trim(); if (!text) return;
+      addMsg(text, "user"); input.value = "";
+      var typing = addMsg("…", "bot");
+      fetch(BACKEND + "/chat" + QS, {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message: text, session_id: getSessionId() })
+      })
+        .then(function (r) { return r.json(); })
+        .then(function (data) { setSessionId(data.session_id); typing.textContent = data.reply || "…"; msgs.scrollTop = msgs.scrollHeight; })
+        .catch(function () { typing.textContent = "Lo siento, ha habido un problema. Inténtalo de nuevo."; });
+    });
+  }
+
+  function start() {
+    fetch(BACKEND + "/widget-config" + QS)
+      .then(function (r) { return r.json(); })
+      .then(function (data) { if (data) cfg = Object.assign(cfg, data); })
+      .catch(function () {})
+      .then(function () {
+        if (document.body) build();
+        else document.addEventListener("DOMContentLoaded", build);
+      });
+  }
+
+  start();
+})();

app/store.py

@@ -0,0 +1,59 @@
+"""Small persistence helpers: sessions and runtime config (branding)."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import ChatSession, Config
+
+BRANDING_KEY = "branding"
+
+
+async def get_or_create_session(
+    db: AsyncSession, session_id: str | None, shop: str, *, tenant_id: int | None = None
+) -> ChatSession:
+    if session_id:
+        existing = await db.get(ChatSession, session_id)
+        # Scope by tenant: a session_id from one tenant can't be reused under another.
+        if existing is not None and (tenant_id is None or existing.tenant_id == tenant_id):
+            # Touch last_seen so active conversations aren't purged by retention
+            # (inserting child messages does not bump the parent's onupdate).
+            existing.last_seen = datetime.now(UTC)
+            return existing
+    session = ChatSession(shop=shop or "", tenant_id=tenant_id)
+    db.add(session)
+    await db.flush()
+    return session
+
+
+async def get_config(db: AsyncSession, key: str) -> dict[str, Any] | None:
+    row = (
+        await db.execute(select(Config).where(Config.key == key))
+    ).scalar_one_or_none()
+    return row.value if row else None
+
+
+async def upsert_config(db: AsyncSession, key: str, value: dict[str, Any]) -> dict[str, Any]:
+    row = (
+        await db.execute(select(Config).where(Config.key == key))
+    ).scalar_one_or_none()
+    if row is None:
+        row = Config(key=key, value=value)
+        db.add(row)
+    else:
+        merged = dict(row.value or {})
+        merged.update(value)
+        row.value = merged
+    await db.flush()
+    return row.value
+
+
+async def get_brand_name(db: AsyncSession, default: str) -> str:
+    branding = await get_config(db, BRANDING_KEY)
+    if branding and branding.get("brand_name"):
+        return branding["brand_name"]
+    return default

app/tenancy.py

@@ -0,0 +1,118 @@
+"""Tenant management + per-tenant Shopify client registry.
+
+One shared backend serves many merchants (tenants). Each tenant has its own
+branding, knowledge base, and (optional) Shopify credentials. The client's
+Shopify secret is encrypted at rest.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.crypto import decrypt, encrypt
+from app.models import Tenant
+from app.shopify.client import ShopifyGraphQLClient
+from app.shopify.token import ShopifyTokenManager
+
+DEFAULT_SLUG = "default"
+
+
+async def get_tenant_by_slug(db: AsyncSession, slug: str) -> Tenant | None:
+    return (
+        await db.execute(select(Tenant).where(Tenant.slug == slug))
+    ).scalar_one_or_none()
+
+
+async def list_tenants(db: AsyncSession) -> list[Tenant]:
+    return list((await db.execute(select(Tenant).order_by(Tenant.id))).scalars().all())
+
+
+async def ensure_default_tenant(db: AsyncSession) -> Tenant:
+    existing = await get_tenant_by_slug(db, DEFAULT_SLUG)
+    if existing is not None:
+        return existing
+    tenant = Tenant(slug=DEFAULT_SLUG, name="Default")
+    db.add(tenant)
+    await db.flush()
+    return tenant
+
+
+_SHOPIFY_FIELDS = {
+    "shopify_shop",
+    "shopify_client_id",
+    "shopify_api_version",
+    "read_all_orders",
+    "brand_name",
+    "brand_color",
+    "welcome",
+    "name",
+}
+
+
+async def create_tenant(
+    db: AsyncSession, slug: str, *, shopify_client_secret: str | None = None, **fields: Any
+) -> Tenant:
+    data = {k: v for k, v in fields.items() if k in _SHOPIFY_FIELDS and v is not None}
+    tenant = Tenant(slug=slug, **data)
+    if shopify_client_secret:
+        tenant.shopify_client_secret_enc = encrypt(shopify_client_secret)
+    db.add(tenant)
+    await db.flush()
+    _registry.invalidate(tenant.id)
+    return tenant
+
+
+async def update_tenant(
+    db: AsyncSession, tenant: Tenant, *, shopify_client_secret: str | None = None, **fields: Any
+) -> Tenant:
+    for k, v in fields.items():
+        if k in _SHOPIFY_FIELDS and v is not None:
+            setattr(tenant, k, v)
+    if shopify_client_secret is not None:
+        tenant.shopify_client_secret_enc = (
+            encrypt(shopify_client_secret) if shopify_client_secret else ""
+        )
+    await db.flush()
+    _registry.invalidate(tenant.id)
+    return tenant
+
+
+class _ShopifyRegistry:
+    """Caches one ShopifyGraphQLClient per tenant (keyed by creds fingerprint)."""
+
+    def __init__(self) -> None:
+        self._cache: dict[int, tuple[str, ShopifyGraphQLClient]] = {}
+
+    def invalidate(self, tenant_id: int | None) -> None:
+        if tenant_id is not None:
+            self._cache.pop(tenant_id, None)
+
+    def for_tenant(self, tenant: Tenant) -> ShopifyGraphQLClient | None:
+        secret = (
+            decrypt(tenant.shopify_client_secret_enc)
+            if tenant.shopify_client_secret_enc
+            else ""
+        )
+        if not (tenant.shopify_shop and tenant.shopify_client_id and secret):
+            return None
+        fingerprint = (
+            f"{tenant.shopify_shop}|{tenant.shopify_client_id}"
+            f"|{tenant.shopify_api_version}|{secret[:6]}"
+        )
+        cached = self._cache.get(tenant.id)
+        if cached and cached[0] == fingerprint:
+            return cached[1]
+        tm = ShopifyTokenManager(tenant.shopify_shop, tenant.shopify_client_id, secret)
+        client = ShopifyGraphQLClient(tenant.shopify_shop, tenant.shopify_api_version, tm)
+        self._cache[tenant.id] = (fingerprint, client)
+        return client
+
+
+_registry = _ShopifyRegistry()
+
+
+def tenant_shopify_client(tenant: Tenant) -> ShopifyGraphQLClient | None:
+    return _registry.for_tenant(tenant)

app/tools/escalate_tool.py

@@ -0,0 +1,34 @@
+"""Tool: escalate to a human by emailing the store."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from app.config import get_settings
+from app.escalation import create_escalation
+from app.mailer import default_sender
+
+if TYPE_CHECKING:
+    from app.tools.registry import ToolContext
+
+
+async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
+    email = (args.get("email") or "").strip()
+    question = (args.get("question") or "").strip()
+    if not email:
+        return {"status": "need_info", "need": ["email"]}
+
+    settings = get_settings()
+    support_email = ctx.support_email or settings.support_email
+    if not support_email:
+        return {"status": "unavailable"}
+
+    sender = ctx.escalation_sender or default_sender(settings)
+    result = await create_escalation(
+        email,
+        question,
+        session_id=ctx.session.id,
+        support_email=support_email,
+        sender=sender,
+    )
+    return {"status": "sent" if result["sent"] else "queued"}

app/tools/knowledge_tool.py

@@ -0,0 +1,27 @@
+"""Tool: search the knowledge base (RAG)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from app.rag import index
+
+if TYPE_CHECKING:
+    from app.tools.registry import ToolContext
+
+
+async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
+    query = (args.get("query") or "").strip()
+    if not query:
+        return {"context": "", "sources": [], "note": "empty query"}
+    results = await index.search(ctx.db, query, k=4, tenant_id=ctx.tenant_id)
+    if not results:
+        return {"context": "", "sources": [], "note": "no relevant information found"}
+    blocks = []
+    sources: list[str] = []
+    for chunk, _score in results:
+        name = (chunk.meta or {}).get("source_name", "fuente")
+        blocks.append(f"[{name}] {chunk.text}")
+        if name not in sources:
+            sources.append(name)
+    return {"context": "\n\n".join(blocks), "sources": sources}

app/tools/order_tool.py

@@ -0,0 +1,55 @@
+"""Tool: verified order status + tracking lookup."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from app.ratelimit import get_order_limiter
+from app.shopify.orders import (
+    find_orders_by_email,
+    normalize_order_number,
+    parse_tracking,
+)
+from app.verification import is_locked, verify
+
+if TYPE_CHECKING:
+    from app.tools.registry import ToolContext
+
+
+async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
+    if ctx.shopify is None:
+        return {"status": "unavailable"}
+
+    if is_locked(ctx.session, ctx.now):
+        return {"status": "locked"}
+
+    email = (args.get("email") or "").strip()
+    order_number = (args.get("order_number") or "").strip()
+    missing = [f for f in ("email", "order_number") if not (args.get(f) or "").strip()]
+    if missing:
+        return {"status": "need_info", "need": missing}
+
+    # Throttle per email (across sessions) so rotating session_id can't reset lockout.
+    limiter = get_order_limiter()
+    if not limiter.allow(email.lower(), ctx.now):
+        return {"status": "locked"}
+
+    try:
+        orders = await find_orders_by_email(ctx.shopify, email)
+    except ValueError:
+        # invalid email format — generic, no field-specific leak
+        return {"status": "not_found"}
+    result = verify(ctx.session, email, order_number, orders, now=ctx.now)
+    if result.locked:
+        return {"status": "locked"}
+    if not result.ok:
+        return {"status": "not_found"}
+
+    target = normalize_order_number(order_number)
+    matched = next(
+        (o for o in orders if normalize_order_number(o.get("name", "")) == target), None
+    )
+    if matched is None:  # defensive; verify() already confirmed a match
+        return {"status": "not_found"}
+    limiter.reset(email.lower())  # successful verification clears the throttle
+    return {"status": "verified", "tracking": parse_tracking(matched)}

app/tools/products_tool.py

@@ -0,0 +1,20 @@
+"""Tool: search the live Shopify product catalog."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from app.shopify.products import search_products
+
+if TYPE_CHECKING:
+    from app.tools.registry import ToolContext
+
+
+async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
+    if ctx.shopify is None:
+        return {"status": "unavailable", "products": []}
+    query = (args.get("query") or "").strip()
+    if not query:
+        return {"status": "ok", "products": []}
+    products = await search_products(ctx.shopify, query)
+    return {"status": "ok", "products": products}