Distribución del corpus RAG vía Hub privado y horneado de modelos

Los libros con licencia (226 MB) y el índice LanceDB (70 MB) no pueden ir en
git. Viven en dos datasets PRIVADOS del Hub; scripts/hub.py los publica y los
descarga.

Se usa la API de Python de huggingface_hub y no el CLI `hf`: en la versión
instalada (1.16.1) el CLI devuelve código 1 aunque la operación vaya bien, por
una incompatibilidad typer/click, lo que abortaría cualquier Makefile o build.

Dockerfile:
- WITH_RAG pasa a 1 por defecto. Con 0, el retriever degradaba en silencio y
las interpretaciones salían sin fundamentar sin que nada lo indicara.
- Los modelos (bge-m3 + bge-reranker-v2-m3, ~6.4 GB) se hornean en /opt/hf y
se fija HF_HUB_OFFLINE=1 en runtime, para que un fallo de red sea ruidoso en
vez de degradar la recuperación a orden RRF sin avisar.
- Si instance/rag_index no está en el contexto de build, se descarga con
HF_TOKEN pasado como secreto de build (nunca --build-arg, que quedaría
grabado en el historial de capas).

NOTA: el Dockerfile no se ha podido construir ni verificar en este entorno.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.dockerignore

@@ -2,8 +2,12 @@
 .env
 *.env
 
-# SQLite database (will be created at runtime)
+# SQLite database (will be created at runtime). NUNCA hornear la BD de usuarios en la
+# imagen: sólo el índice RAG (instance/rag_index) debe copiarse. Excluye la BD del contexto
+# de build para que `COPY instance*` no la arrastre a la imagen distribuida.
 data/*.db
+instance/*.db
+instance/morphos.db
 
 # OS
 .DS_Store

Dockerfile

@@ -1,35 +1,89 @@
-FROM php:8.2-apache
-
-# Install extensions and enable Apache modules
-RUN apt-get update && apt-get install -y \
-    libpng-dev \
-    libjpeg-dev \
-    libfreetype6-dev \
-    libzip-dev \
-    libsqlite3-dev \
-    git \
-    unzip \
-    && docker-php-ext-install pdo pdo_mysql pdo_sqlite \
-    && docker-php-ext-enable pdo pdo_mysql pdo_sqlite \
-    && a2enmod rewrite deflate headers expires
-
-# Copy project
-COPY . /var/www/html/
-
-# Create data directory for SQLite and ensure permissions
-RUN mkdir -p /var/www/html/data \
-    && chown -R www-data:www-data /var/www/html \
-    && chmod -R 755 /var/www/html
-
-# Expose HF Spaces default port
-RUN sed -i 's/Listen 80/Listen 7860/' /etc/apache2/ports.conf \
-    && sed -i 's/:80/:7860/' /etc/apache2/sites-available/000-default.conf
+# syntax=docker/dockerfile:1
 
+# ---------- Stage 1: build del frontend (Vite + TS) ----------
+FROM node:22-slim AS frontend
+WORKDIR /build
+COPY frontend/package*.json frontend/
+RUN cd frontend && npm ci
+# Se necesita el HTML/CSS de la raíz y los datos para la build.
+COPY frontend/ frontend/
+COPY index.html ./
+COPY css/ css/
+COPY assets/ assets/
+COPY data/ data/
+RUN cd frontend && npm run build   # emite /build/dist
+
+# ---------- Stage 2: runtime backend (FastAPI + uv) ----------
+FROM python:3.12-slim AS runtime
+
+# uv desde su imagen oficial (rápido y reproducible).
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+WORKDIR /app
+
+# Instala dependencias con el lockfile (capa cacheable). RAG viene ACTIVADO por defecto: con
+# WITH_RAG=0 el retriever degrada en silencio y las interpretaciones salen sin fundamentar, que
+# es justo el fallo que no queremos que pase inadvertido en producción.
+ARG WITH_RAG=1
+COPY backend/pyproject.toml backend/uv.lock* backend/
+RUN cd backend && if [ "$WITH_RAG" = "1" ]; then \
+      uv sync --frozen --no-dev --group rag; \
+    else \
+      uv sync --frozen --no-dev; \
+    fi
+
+# Código del backend
+COPY backend/ backend/
+
+# Estáticos públicos: build del frontend + datos de referencia (servidos en /data)
+COPY --from=frontend /build/dist ./dist
+COPY data/ ./data/
+
+# Índice RAG horneado de sólo lectura. Vive en instance/ (fuera del webroot); no requiere
+# almacenamiento persistente. La BD de usuarios (instance/*.db) queda EXCLUIDA vía
+# .dockerignore: nunca se hornea.
+#
+# Dos vías: si instance/rag_index existe en el contexto de build se copia; si no (clon limpio,
+# CI), se descarga del dataset PRIVADO del Hub con HF_TOKEN pasado como secreto de build.
+COPY instance* ./instance/
+
+# Se usa la API de Python y NO el CLI `hf`: en huggingface_hub 1.16.1 el CLI devuelve código 1
+# aunque la operación vaya bien (incompatibilidad typer/click), lo que abortaría la build.
+ARG HF_INDEX_REPO=blackmistcode/morphos-rag-index
+RUN --mount=type=secret,id=hf_token,required=false \
+    if [ "$WITH_RAG" = "1" ] && [ ! -d /app/instance/rag_index ]; then \
+      if [ -f /run/secrets/hf_token ]; then \
+        HF_TOKEN="$(cat /run/secrets/hf_token)" backend/.venv/bin/python -c "\
+from huggingface_hub import snapshot_download; \
+snapshot_download(repo_id='$HF_INDEX_REPO', repo_type='dataset', local_dir='/app/instance/rag_index')"; \
+      else \
+        echo "AVISO: sin instance/rag_index y sin secreto hf_token; la imagen quedará SIN RAG." >&2; \
+      fi; \
+    fi
+
+# Modelos de embeddings y reranking horneados en la imagen (~6.4 GB). Sin esto, la primera
+# petición intentaría descargarlos de huggingface.co en caliente: lento en CPU-basic y, si la
+# red falla, el reranker cae en silencio a orden RRF. Con HF_HUB_OFFLINE=1 en runtime, una
+# descarga que faltase falla de forma ruidosa en vez de degradar sin avisar.
+ARG RAG_EMBED_MODEL=BAAI/bge-m3
+ARG RAG_RERANKER_MODEL=BAAI/bge-reranker-v2-m3
+ENV HF_HOME=/opt/hf
+RUN if [ "$WITH_RAG" = "1" ]; then \
+      backend/.venv/bin/python -c "\
+from sentence_transformers import SentenceTransformer, CrossEncoder; \
+SentenceTransformer('$RAG_EMBED_MODEL'); CrossEncoder('$RAG_RERANKER_MODEL')"; \
+    fi
+
+ENV MORPHOS_ENTORNO=prod \
+    MORPHOS_COOKIE_SECURE=true \
+    HF_HOME=/opt/hf \
+    HF_HUB_OFFLINE=1 \
+    PATH="/app/backend/.venv/bin:$PATH"
+
+# HF Spaces expone el 7860.
 EXPOSE 7860
 
-# Entrypoint handles runtime initialization
 COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh
-
 ENTRYPOINT ["docker-entrypoint.sh"]
-CMD ["apache2-foreground"]
+CMD ["uvicorn", "app.main:app", "--app-dir", "backend", "--host", "0.0.0.0", "--port", "7860"]

docker-entrypoint.sh

@@ -1,36 +1,16 @@
-#!/bin/bash
+#!/bin/sh
 set -e
 
-DATA_DIR="/var/www/html/data"
-DB_FILE="$DATA_DIR/morphos.db"
+# La BD de usuarios y el índice RAG viven en instance/ (fuera del webroot).
+# El backend crea el esquema al arrancar (lifespan). Aquí sólo garantizamos el
+# directorio y avisamos si falta configuración de producción crítica.
+mkdir -p /app/instance
 
-# Ensure data directory exists with correct ownership
-mkdir -p "$DATA_DIR"
-chown www-data:www-data "$DATA_DIR"
-
-# Ensure SQLite database file exists so PDO can connect
-touch "$DB_FILE"
-chown www-data:www-data "$DB_FILE"
-chmod 664 "$DB_FILE"
-
-# Initialize SQLite schema if the table does not exist
-php -r "
-\$dbPath = '$DB_FILE';
-try {
-    \$pdo = new PDO('sqlite:' . \$dbPath);
-    \$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
-    \$pdo->exec('CREATE TABLE IF NOT EXISTS usuarios (
-        id INTEGER PRIMARY KEY AUTOINCREMENT,
-        nombre TEXT NOT NULL,
-        apellido TEXT NOT NULL,
-        email TEXT NOT NULL UNIQUE,
-        password TEXT NOT NULL,
-        creado_en DATETIME DEFAULT CURRENT_TIMESTAMP
-    )');
-} catch (PDOException \$e) {
-    error_log('SQLite init error: ' . \$e->getMessage());
-    exit(1);
-}
-"
+if [ "${MORPHOS_ENTORNO}" = "prod" ]; then
+  if [ -z "${MORPHOS_SESSION_SECRET}" ]; then
+    echo "ERROR: MORPHOS_SESSION_SECRET no está definido en prod. Aborta." >&2
+    exit 1
+  fi
+fi
 
 exec "$@"

scripts/hub.py

@@ -0,0 +1,105 @@
+"""Publicación y descarga de los artefactos RAG en repos privados del Hub.
+
+Se usa la API de Python (`huggingface_hub`) y no el CLI `hf` a propósito: en la versión instalada
+(1.16.1) el CLI arrastra una incompatibilidad typer/click que hace que `ctx.exit()` propague un
+`click.exceptions.Exit(0)` como traceback y **devuelva código 1 aunque la operación haya ido
+bien**. Eso es inservible dentro de un Makefile, donde un exit≠0 aborta la cadena.
+
+Artefactos:
+  - índice  (~70 MB): derivado de libros con licencia, contiene su texto troceado → repo PRIVADO.
+  - libros (~226 MB): los PDF originales → repo PRIVADO, sólo necesarios para reingerir.
+
+Uso:
+    python scripts/hub.py publish-index
+    python scripts/hub.py fetch-index
+    python scripts/hub.py publish-books
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from huggingface_hub import HfApi, snapshot_download
+
+RAIZ = Path(__file__).resolve().parents[1]
+DIR_INDICE = RAIZ / "instance" / "rag_index"
+DIR_LIBROS = RAIZ / "books"
+
+REPO_INDICE = "blackmistcode/morphos-rag-index"
+REPO_LIBROS = "blackmistcode/morphos-books"
+
+
+def _asegurar_repo(api: HfApi, repo_id: str) -> None:
+    """Crea el repo si falta. `private=True` sólo aplica en la creación: si el repo ya existe
+    NO lo vuelve privado, así que se comprueba explícitamente y se aborta si es público."""
+    api.create_repo(repo_id=repo_id, repo_type="dataset", private=True, exist_ok=True)
+    if not api.dataset_info(repo_id).private:
+        sys.exit(
+            f"ABORTADO: {repo_id} es PÚBLICO. Contiene material con licencia; hazlo privado "
+            f"antes de subir nada."
+        )
+
+
+def publicar_indice() -> None:
+    if not DIR_INDICE.exists():
+        sys.exit(f"ERROR: no existe {DIR_INDICE}. Ejecuta 'make ingest' primero.")
+    manifiesto = json.loads((DIR_INDICE / "manifest.json").read_text(encoding="utf-8"))
+    hash_corpus = manifiesto.get("hash_corpus", "desconocido")
+    api = HfApi()
+    _asegurar_repo(api, REPO_INDICE)
+    api.upload_folder(
+        repo_id=REPO_INDICE,
+        repo_type="dataset",
+        folder_path=str(DIR_INDICE),
+        commit_message=f"Índice RAG · corpus {hash_corpus} · {manifiesto.get('n_fragmentos')} fragmentos",
+    )
+    print(f"OK: índice publicado en {REPO_INDICE} (corpus {hash_corpus})")
+
+
+def descargar_indice() -> None:
+    DIR_INDICE.mkdir(parents=True, exist_ok=True)
+    snapshot_download(
+        repo_id=REPO_INDICE,
+        repo_type="dataset",
+        local_dir=str(DIR_INDICE),
+    )
+    manifiesto = DIR_INDICE / "manifest.json"
+    if manifiesto.exists():
+        m = json.loads(manifiesto.read_text(encoding="utf-8"))
+        print(f"OK: índice descargado · corpus {m.get('hash_corpus')} · {m.get('n_fragmentos')} fragmentos")
+    else:
+        print("AVISO: descargado sin manifest.json; el índice puede estar incompleto.")
+
+
+def publicar_libros() -> None:
+    pdfs = sorted(DIR_LIBROS.glob("*.pdf"))
+    if not pdfs:
+        sys.exit(f"ERROR: no hay PDFs en {DIR_LIBROS}.")
+    api = HfApi()
+    _asegurar_repo(api, REPO_LIBROS)
+    api.upload_folder(
+        repo_id=REPO_LIBROS,
+        repo_type="dataset",
+        folder_path=str(DIR_LIBROS),
+        allow_patterns=["*.pdf"],
+        commit_message=f"Corpus veterinario con licencia ({len(pdfs)} PDF)",
+    )
+    print(f"OK: {len(pdfs)} libros publicados en {REPO_LIBROS}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("accion", choices=["publish-index", "fetch-index", "publish-books"])
+    args = parser.parse_args()
+    {
+        "publish-index": publicar_indice,
+        "fetch-index": descargar_indice,
+        "publish-books": publicar_libros,
+    }[args.accion]()
+
+
+if __name__ == "__main__":
+    main()