@mcptoolshop/backpropagate 1.2.0 → 1.4.0

package/README.es.md

@@ -10,143 +10,155 @@
   <a href="https://github.com/mcp-tool-shop-org/backpropagate/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/backpropagate/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://pypi.org/project/backpropagate/"><img src="https://img.shields.io/pypi/v/backpropagate" alt="PyPI"></a>
   <a href="https://codecov.io/gh/mcp-tool-shop-org/backpropagate"><img src="https://img.shields.io/codecov/c/github/mcp-tool-shop-org/backpropagate" alt="Coverage"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/mcp-tool-shop-org/backpropagate"><img src="https://api.scorecard.dev/projects/github.com/mcp-tool-shop-org/backpropagate/badge" alt="OpenSSF Scorecard"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
   <a href="https://mcp-tool-shop-org.github.io/backpropagate/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
 </p>
 
-**Ajuste fino de LLM sin interfaz en 3 líneas. Configuraciones predeterminadas inteligentes, ajuste automático del tamaño del lote según la VRAM, entrenamiento SLAO en múltiples ejecuciones y exportación a GGUF con un solo clic para Ollama.**
+# Entrena un adaptador. Envíalo a Ollama. ¡Listo!
 
-*SLAO es el aprendizaje continuo de LoRA mediante una fusión asimétrica, una técnica que evita el olvido catastrófico durante las campañas de ajuste fino prolongadas ([artículo](https://arxiv.org/abs/2512.23017)).*
+Backpropagate es una biblioteca de Python para el ajuste fino de modelos de lenguaje grandes en una sola GPU. Tres líneas de código entrenan un modelo de 7B en una tarjeta de 16GB. Un comando más lo exporta a Ollama para que puedas ejecutar tu ajuste fino con `ollama run`. Funciona perfectamente en Windows.
 
-*Entrena LLM con 3 líneas de código. Exporte a Ollama con una línea más.*
+```python
+from backpropagate import Trainer
 
-## Cómo empezar
+trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")
+trainer.train("my_data.jsonl", steps=100)
+trainer.export("gguf", quantization="q4_k_m")
+```
 
 ```bash
-pip install backpropagate[standard]
+backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --ollama-name my-model
+ollama run my-model
 ```
 
-```python
-from backpropagate import Trainer
+Eso es todo. No hay un archivo de configuración YAML. No hay una "ceremonia" de `accelerate launch`. No hay un tutorial separado para "convertirlo a GGUF". Si tienes una GPU con CUDA y un archivo JSONL con tus datos de entrenamiento, estás a solo tres líneas de tener un ajuste fino funcional.
 
-trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")
-trainer.train("examples/quickstart.jsonl", steps=10)
-trainer.export("gguf", quantization="q4_k_m")  # Ready for Ollama
-```
+## Instalación
+
+```bash
+# Recommended: isolated Python install (no conflicts with system Python or other projects)
+pipx install backpropagate
 
-El repositorio incluye un pequeño archivo `examples/quickstart.jsonl` (5 ejemplos en formato ShareGPT) para que el fragmento de código anterior se ejecute de principio a fin en una instalación limpia. Para tu propio entrenamiento, consulta el formato de conjunto de datos [Dataset Format](#dataset-format) a continuación.
+# Or via uv (faster install, same isolation)
+uv tool install backpropagate
 
-### Opción sin código: Interfaz web
+# Standard pip (if you manage your own virtualenv)
+pip install backpropagate
+```
 
-¿Prefieres una interfaz gráfica en lugar de una terminal de Python? Instala los componentes adicionales y ejecuta:
+Si quieres las funciones opcionales, reemplaza la instalación con una de estas:
 
 ```bash
-pip install backpropagate[standard]
-backprop ui --port 7862
+pipx install "backpropagate[standard]"   # adds Unsloth (2x faster training) + the web UI
+pipx install "backpropagate[full]"       # adds everything: unsloth, ui, monitoring, export, etc.
 ```
 
-La interfaz de Reflex (Radix UI) te permite seleccionar un archivo JSONL, elegir un modelo, entrenar y exportar, sin necesidad de Python. La interfaz es local; para acceder desde Internet, consulta la sección [Web UI](#web-ui) a continuación, donde encontrarás el contrato de seguridad `--share` + `--auth` y las opciones de túnel admitidas (Cloudflare Tunnel, ngrok).
+¿Prefieres Docker? `docker pull ghcr.io/mcp-tool-shop-org/backpropagate:latest` también funciona. Las imágenes están disponibles para `linux/amd64` y `linux/arm64`, por lo que los usuarios de Apple Silicon y ARM Linux obtienen una imagen nativa. Un archivo `compose.yaml` canónico para "UI en un contenedor" se encuentra en la raíz del repositorio; `docker compose up` inicia la interfaz web en `http://localhost:7860` con un volumen persistente `~/.backpropagate` montado.
 
-## Formato del conjunto de datos
+## Dónde encaja Backpropagate
 
-Tu archivo de entrenamiento en formato JSONL debe tener un ejemplo por línea. El formato más sencillo es el chat de ShareGPT:
+Existen varias bibliotecas excelentes para el ajuste fino de LLM. Cada una es excelente para diferentes cosas:
 
-```jsonl
-{"conversations": [{"from": "human", "value": "What is Python?"}, {"from": "gpt", "value": "A programming language."}]}
-{"conversations": [{"from": "human", "value": "Explain recursion."}, {"from": "gpt", "value": "A function that calls itself."}]}
-```
+- **[Axolotl](https://github.com/OpenAccess-AI-Collective/axolotl)**: si te gustan las configuraciones YAML y quieres una comunidad de recetas para copiar.
+- **[LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory)**: si quieres una GUI web y soporte integrado para DPO/PPO/RLHF.
+- **[Unsloth](https://github.com/unslothai/unsloth)**: si necesitas el entrenamiento más rápido posible y estás utilizando una familia de modelos compatible.
+- **[torchtune](https://github.com/pytorch/torchtune)**: si quieres las recetas nativas de PyTorch de Meta que puedes editar.
 
-También se admiten formatos Alpaca (`instruction`/`output`), OpenAI chat (`messages`) y texto sin formato. Consulta `examples/quickstart.jsonl` para obtener un punto de partida que puedes copiar.
+Backpropagate es la opción que falta: **una API de Python de 3 líneas para usuarios individuales en una sola GPU de consumo que desean entrenar un adaptador y enviarlo.** Sin YAML, sin GUI, sin DPO/PPO, sin nodos múltiples. Solo el bucle que realmente necesita todo el mundo y el paso de exportación que dificulta las cosas.
 
-## ¿Por qué propagar hacia atrás?
+Si has probado alguna de las bibliotecas anteriores y te has sentido frustrado por la "ceremonia" del archivo de configuración, o has encontrado una limitación en la familia de modelos, o querías configuraciones predeterminadas para Windows: Backpropagate es para ti.
 
-| Problema | Solución |
-|---------|----------|
-| El ajuste fino es complejo | 3 líneas: cargar, entrenar, guardar |
-| Windows es un problema | Soporte completo para Windows |
-| La gestión de la VRAM es difícil | Ajuste automático del tamaño del lote, monitorización de la GPU |
-| La exportación de modelos es confusa | Exportación a GGUF con un solo clic + registro automático en Ollama |
-| Las ejecuciones largas provocan el olvido | Entrenamiento SLAO en múltiples ejecuciones |
+## Lo que puedes ajustar en una GPU de consumo de 16GB
 
-## Características principales
+Aquí tienes un rango práctico en una tarjeta de 16GB (RTX 4080 / 5080 / 4070 Ti Super):
 
-- **Diseñado para funcionar sin interfaz:** Ideal para pipelines de CI/CD, flujos de trabajo automatizados y ejecución programática.
-- **Configuraciones predeterminadas inteligentes:** Configura automáticamente los hiperparámetros óptimos según tu hardware y conjunto de datos.
-- **Entrenamiento SLAO en múltiples ejecuciones:** Estrategias de entrenamiento avanzadas para evitar el olvido catastrófico durante las ejecuciones prolongadas.
-- **Soporte completo para Windows:** Probado y optimizado para entornos Windows, evitando los problemas comunes de PyTorch/CUDA.
-- **Exportación sencilla:** Exportación con un solo clic al formato GGUF y registro automático en Ollama.
-- **Arquitectura modular:** Instala solo las dependencias que necesitas (por ejemplo, `[unsloth]`, `[ui]`, `[export]`).
+| Modelo | Método | Estado |
+|---|---|---|
+| Qwen-3.5-4B / Phi-4-mini-3.8B / SmolLM3-3B | LoRA / QLoRA / DoRA | Cómodo. Longitud de secuencia completa, con espacio de sobra. |
+| Phi-4-mini-3.8B / Qwen-3.5-4B / SmolLM3-3B (límite de 3B de parámetros) | `mode="full"` (ajuste fino completo) | v1.4: Use el parámetro `--mode=full` en `backprop train` o `Trainer(..., mode="full")`. El checkpointing de gradientes y el Adam de 8 bits con paginación mantienen la memoria de activación en sqrt(L). |
+| Qwen-2.5-7B / Llama-3.1-8B / Mistral-7B | QLoRA | Estándar. ~7-8 GB. Configuraciones predeterminadas de Backpropagate. |
+| Llama-3 13B | QLoRA + empaquetado de muestras | Apretado pero funciona. Usa secuencias más cortas. |
+| Mixtral 8x7B (47B de parámetros totales) | AQLM de 2 bits + LoRA | Planificado para v1.5: Consulte el documento V1_5_BRIEF cuando se publique. |
 
-## Instalación
+La cuantización AQLM de 2 bits (`quant_method="aqlm"`, opción experimental para Mixtral-8x7B en 16GB) estaba prevista para v1.4 y ahora está planificada para v1.5. La biblioteca `aqlm` está madura; en la versión 1.4, se priorizó el soporte para el ajuste fino completo de modelos de hasta 3B (`mode="full"`) en lugar de agregar un nuevo backend de cuantización. Consulte el documento V1_5_BRIEF cuando se publique para ver el plan de implementación de la versión 1.5.
 
-```bash
-pip install backpropagate              # Core only (minimal)
-pip install backpropagate[unsloth]     # + Unsloth 2x faster training
-pip install backpropagate[ui]          # + Reflex (Radix UI) web interface
-pip install backpropagate[standard]    # unsloth + ui (recommended)
-pip install backpropagate[full]        # Everything
-```
+Para modelos de 3B o menos, el ajuste fino completo (no solo LoRA) es posible en 16GB y ahora está disponible en la versión 1.4 como `mode="full"`. Utilice `Trainer(..., mode="full")` o `backprop train --mode=full --model phi-4-mini-3.8b` para habilitarlo. Un mecanismo de seguridad impide el uso de este modo para modelos mayores de 3B, mostrando el error `RUNTIME_FULL_FT_MODEL_TOO_LARGE` y sugiriendo LoRA y las configuraciones preestablecidas para modelos de menos de 3B como alternativas. Consulte la [página completa del manual de ajuste fino](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/) para obtener información sobre la configuración y la comparación de calidad de Biderman 2024 / Thinking Machines 2025. Para modelos de 7B o más, el ajuste fino completo requiere una GPU de 24GB o más; considere alquilar una GPU A100 en la nube, o utilice LoRA, que, según investigaciones recientes, ofrece una calidad comparable al ajuste fino completo en la mayoría de las tareas posteriores al entrenamiento (consulte la [sección de advertencias](#what-backpropagate-is-not-for) para obtener referencias).
 
-| Componentes adicionales | Descripción | Dependencias |
-|-------|-------------|--------------|
-| `unsloth` | Entrenamiento 2 veces más rápido, 50% menos de VRAM | unsloth |
-| `ui` | Interfaz web Reflex (Radix UI) | reflex>=0.9.2, fastapi>=0.115 |
-| `validation` | Validación de configuración de Pydantic | pydantic, pydantic-settings |
-| `export` | Exportación a GGUF para Ollama | llama-cpp-python |
-| `monitoring` | WandB + monitorización del sistema (integrado automáticamente en el entrenador en v1.1.0) | wandb, psutil |
-| `logging` | Registro estructurado | structlog |
-| `security` | Autenticación JWT + generación de tokens | PyJWT, cryptography |
-| `production` | unsloth + ui + validación + registro + seguridad | (paquete) |
+## Lo que Backpropagate NO es
 
-**Requisitos:** Python 3.10+ · GPU con CUDA (8GB+ de VRAM) · PyTorch 2.0+
+Si su caso de uso es diferente a los siguientes, obtendrá mejores resultados con otra biblioteca. Backpropagate no es la opción adecuada, e intentar que funcione le costará más que simplemente utilizar la herramienta correcta. Leer esta sección antes de comenzar le ahorrará el ciclo de instalación y prueba:
 
-### Requisitos de la plataforma
+- **Ajuste fino de todos los parámetros de modelos de 7B o más:** Backpropagate utiliza LoRA / QLoRA, que entrena un adaptador pequeño en lugar de actualizar cada peso. Para modelos de 7B o más, el ajuste fino completo requiere 24GB o más de memoria de GPU y no cabe en una tarjeta de consumo de 16GB. Para modelos de 3B o menos, el ajuste fino completo SÍ es posible en 16GB y está disponible en la versión 1.4 como `mode="full"` (utilice `Trainer(..., mode="full")` o `--mode=full` en la línea de comandos; un mecanismo de seguridad genera el error `RUNTIME_FULL_FT_MODEL_TOO_LARGE` para modelos mayores de 3B y sugiere LoRA y las configuraciones preestablecidas para modelos de menos de 3B como alternativas). En resumen: investigaciones recientes ([Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)) demuestran que LoRA, con la configuración correcta, ofrece una calidad comparable al ajuste fino completo en la mayoría de las tareas posteriores al entrenamiento (seguimiento de instrucciones, adaptación de dominio, personalidad/estilo) con un 67% menos de recursos computacionales; por lo tanto, para el trabajo que la mayoría de los usuarios desean realizar, no se pierde nada al utilizar LoRA. `mode="full"` existe para los casos en los que ha detectado una diferencia de calidad y ha decidido invertir recursos computacionales adicionales. Si realmente necesita realizar un ajuste fino completo de un modelo de 7B o más, utilice directamente el `Trainer` de HuggingFace `transformers` en una tarjeta de 24GB o más.
+- **DPO / PPO / GRPO / ajuste de preferencias:** Backpropagate solo realiza un ajuste fino supervisado de una sola etapa. Para el aprendizaje por preferencias, utilice TRL directamente o LLaMA-Factory.
+- **Entrenamiento en múltiples nodos:** Solo se admite una GPU en una sola máquina. El entrenamiento con varias GPU en una sola máquina funciona (a través de `accelerate launch`), pero no está oficialmente soportado.
+- **Entrenamiento en macOS:** Apple Silicon no tiene CUDA, por lo que el entrenamiento debe ejecutarse en un sistema Linux o Windows con una GPU NVIDIA. Aún puede ejecutar el modelo entrenado en un Mac a través de Ollama.
+- **Cualquier modelo que no pertenezca a las familias de modelos probadas:** Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Otros modelos a menudo funcionan, pero no están incluidos en las pruebas automatizadas.
 
-Backpropagate gestiona las peculiaridades del entorno de ejecución (multiproceso, xformers en RTX 40/50, trabajadores del cargador de datos en Windows). No gestiona los problemas de instalación de la plataforma; soluciona esos problemas primero:
+Si necesita alguna de estas funciones, utilice una de las bibliotecas mencionadas anteriormente. Son mejores en eso.
 
-- **Versión del kit de herramientas CUDA.** PyTorch se publica por versión de CUDA; elegir la versión incorrecta instala silenciosamente solo la versión de torch para CPU. Utilice el selector en <https://pytorch.org/get-started/locally/> para obtener el comando exacto `pip install torch ...` para su controlador. Ejecute `nvidia-smi` para ver la versión de su controlador/CUDA.
-- **Windows.** Visual Studio Build Tools (C++) y CMake son necesarios para el extra `[export]` (las compilaciones de `llama-cpp-python` se realizan desde el código fuente). El paquete `bitsandbytes` se publica ahora de forma nativa para Windows (>= 0.43); las guías anteriores que mencionan `bitsandbytes-windows` están desactualizadas.
-- **macOS.** El entrenamiento con GPU **no está soportado**; no hay CUDA. Puede instalar Backpropagate para ejecutar la *inferencia* en un archivo GGUF a través de Ollama, pero `trainer.train()` genera un error `DEP_GPU_NOT_AVAILABLE`. Utilice una máquina con CUDA para el entrenamiento.
-- **Linux.** La mayoría de las distribuciones funcionan sin problemas. Si está utilizando la versión binaria de PyPI, tenga en cuenta que la compilación de Linux utiliza solo la versión de torch para CPU (para mantenerse dentro del límite de 2 GB de archivos adjuntos de GitHub); instálela primero con el paquete CUDA correspondiente de pytorch.org.
+## Lo que Backpropagate le ofrece:
 
-Para la resolución de problemas de instalación, consulte [la página del manual de solución de problemas](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/).
+Cuatro cosas, en una sola instalación:
 
-## Configuración
+**1. Una API real de 3 líneas que funciona sin un archivo de configuración.**
+El fragmento de código que se encuentra al principio de este archivo README se ejecuta de principio a fin. No requiere `accelerate config`, ni YAML, ni anulaciones de Hydra. Simplemente `Trainer(model).train(data)` y tendrá un modelo ajustado.
 
-Todas las configuraciones se pueden sobrescribir con variables de entorno utilizando el prefijo `BACKPROPAGATE_` (por ejemplo, `BACKPROPAGATE_LOG_LEVEL=debug`). Un archivo `.env` en la raíz del proyecto se carga automáticamente cuando se instala el extra `[validation]`.
+**2. Funcionalidad que realmente funciona en Windows.**
+La mayoría de las bibliotecas de aprendizaje automático tratan a Windows como una opción secundaria. Backpropagate se prueba exhaustivamente en Windows + RTX 5080. La biblioteca se encarga de las peculiaridades del entorno de ejecución: sabe cómo pre-tokenizar sus datos para que el procesamiento multiproceso de Windows no se bloquee, desactiva automáticamente xformers en las tarjetas RTX 40/50 donde podría fallar, y selecciona la configuración del cargador de datos que no causa problemas. No tiene que saber nada de esto. Simplemente funciona.
 
-Parámetros comunes (consulte [la referencia completa de las variables de entorno](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/) para obtener información completa):
+**3. Diseñado para ejecuciones no supervisadas.**
+El entrenamiento lleva horas. No quiere tener que vigilarlo constantemente. Backpropagate está diseñado para que se pueda dejar funcionando:
 
-| Variable | Valor predeterminado | Notas |
-|----------|---------|-------|
-| `BACKPROPAGATE_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
-| `BACKPROPAGATE_LOG_JSON` | automático | Fuerza registros en formato JSON (`true`) o en la consola (`false`) |
-| `BACKPROPAGATE_LOG_FILE` | no definido | Ruta para copiar los registros |
-| `BACKPROPAGATE_DEFER_FEATURE_DETECTION` | no definido | Omite la detección de dependencias opcionales al inicio para un inicio más rápido de la interfaz de línea de comandos. |
-| `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE` | `true` | Si es `true`, rechaza `backprop ui --share` sin `--auth` |
-| `BACKPROPAGATE_UI__OUTPUT_DIR` | `~/.backpropagate/ui-outputs` | Directorio base para todas las escrituras del sistema de archivos de la interfaz de usuario; validado por denylist. |
-| `BACKPROPAGATE_MODEL__NAME` | `Qwen/Qwen2.5-7B-Instruct` | Modelo predeterminado |
-| `BACKPROPAGATE_TRAINING__LEARNING_RATE` | `2e-4` | Tasa de aprendizaje |
-| `BACKPROPAGATE_LORA__R` | `16` | Rango de LoRA |
+- Si se queda sin memoria de GPU, reduce automáticamente el tamaño del lote e intenta de nuevo, hasta tres veces. No requiere ajuste manual.
+- Si la GPU se calienta demasiado, se pausa hasta que se enfría y luego continúa.
+- Cada punto de control se guarda de forma atómica: si su computadora portátil se bloquea durante el guardado, el punto de control anterior y válido sigue intacto.
+- Cada ejecución de entrenamiento recibe un ID único que se imprime en cada línea de registro, cada punto de control y cada entrada de Weights & Biases. Si algo sale mal, un solo ID permite a un desarrollador correlacionar todo.
+- Los errores vienen con códigos estables (`RUNTIME_GPU_OOM`, `DEP_OLLAMA_REGISTRATION_FAILED`, etc.) para que pueda buscar en sus registros y en la [guía de solución de problemas](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) para encontrar la solución. Los fallos específicos de CUDA tienen una [página de solución de problemas de CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/) dedicada.
 
-Las claves anidadas utilizan el doble guion bajo como delimitador (convención de Pydantic `env_nested_delimiter`).
+**4. Un solo comando para pasar del adaptador entrenado a `ollama run`.**
+Muchas bibliotecas entrenan un modelo. Pocas de ellas le permiten continuar una vez que realmente quiere usarlo. Backpropagate exporta a GGUF (el formato que utiliza Ollama) y registra un modelo de Ollama con un solo comando. Pasa de "entrenamiento completado" a "puedo chatear con mi modelo ajustado" en aproximadamente 30 segundos.
 
-## Uso
+## Cómo empezar
 
-### Entrenamiento básico
+El repositorio incluye un conjunto de datos de ejemplo pequeño para que el fragmento de código que se muestra al principio de este archivo README se ejecute correctamente en una instalación limpia:
 
-```python
+```bash
+pipx install "backpropagate[standard]"
+
+python -c "
 from backpropagate import Trainer
+trainer = Trainer('Qwen/Qwen2.5-7B-Instruct')
+trainer.train('examples/quickstart.jsonl', steps=10)
+trainer.export('gguf', quantization='q4_k_m')
+"
+```
 
-trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")
-trainer.train("my_data.jsonl", steps=100)
-trainer.save("./my-model")
-trainer.export("gguf", quantization="q4_k_m")
+Esto entrena un adaptador Qwen 2.5 de 7B con 5 conversaciones cortas en formato ShareGPT, y luego exporta el resultado a GGUF. Para sus propios datos, formatee su archivo JSONL con un ejemplo por línea:
+
+```jsonl
+{"conversations": [{"from": "human", "value": "What is Python?"}, {"from": "gpt", "value": "A programming language."}]}
+{"conversations": [{"from": "human", "value": "Explain recursion."}, {"from": "gpt", "value": "A function that calls itself."}]}
+```
+
+También funcionan los formatos de Alpaca (`instruction` / `output`), OpenAI chat (`messages`) y texto sin formato; Backpropagate detecta automáticamente el formato.
+
+Para flujos de trabajo más completos (ajuste fino y publicación en Hugging Face Hub, reanudación después de errores de memoria, ejecuciones múltiples de SLAO durante una campaña larga, etc.), consulte la [página de recetas del manual](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/).
+
+### Interfaz web (opcional)
+
+Si prefiere hacer clic en lugar de escribir código Python, instale el paquete de la interfaz de usuario y ejecútelo:
+
+```bash
+pipx install "backpropagate[ui]"
+backprop ui --port 7862
 ```
 
-`Qwen/Qwen2.5-7B-Instruct` es el valor predeterminado canónico; el valor `Trainer()` se resuelve cuando se llama sin un argumento de modelo (consulte [`config.py`](backpropagate/config.py) `ModelConfig.name`). Los ejemplos anteriores utilizaban `unsloth/Qwen2.5-7B-Instruct-bnb-4bit` cuantizado; hemos cambiado el valor predeterminado a los pesos oficiales de Qwen para una mejor fiabilidad ([REGISTRO DE CAMBIOS v1.1.0](CHANGELOG.md#110---2026-05-21)). Puede utilizar cualquiera de los dos modelos.
+Se abre una interfaz web local en `http://localhost:7862`, donde puede seleccionar un conjunto de datos, elegir un modelo, entrenar y exportar. La interfaz de usuario solo funciona localmente de forma predeterminada. Para permitir el acceso desde otros dispositivos, consulte la sección [Interfaz web](#web-ui) a continuación para obtener información sobre el contrato de seguridad `--share` + `--auth`.
 
-### Entrenamiento multi-ejecución SLAO
+## Entrenamiento con múltiples ejecuciones
+
+Si desea realizar un ajuste fino incremental en varios conjuntos de datos, por ejemplo, si recibe nuevos datos de entrenamiento cada semana y desea agregarlos sin olvidar lo que aprendió antes, el modo `multi_run` de Backpropagate es para usted:
 
 ```python
 from backpropagate import Trainer
@@ -158,196 +170,196 @@ result = trainer.multi_run(
     num_runs=5,
     steps_per_run=100,
     samples_per_run=1000,
-    merge_mode="slao",  # Single LoRA Continual Learning via Asymmetric Merging
 )
 ```
 
-SLAO (Aprendizaje continuo de LoRA único mediante fusión asimétrica) implementa el artículo [Merge before Forget](https://arxiv.org/abs/2512.23017): inicialización ortogonal de la matriz A mediante descomposición QR, manejo asimétrico de A/B y escalado dependiente del tiempo `λ(i) = 1/√i`. La opción de la interfaz de línea de comandos es `--samples` (el campo subyacente es `samples_per_run`).
-
-### Exportación a Ollama
-
-```python
-# Export to GGUF
-result = trainer.export("gguf", quantization="q4_k_m")
-
-# Register with Ollama separately
-from backpropagate import register_with_ollama
-register_with_ollama(result.path, "my-finetuned-model")
-# ollama run my-finetuned-model
-```
+Esto realiza cinco pasadas de entrenamiento, fusionando el adaptador entre cada ejecución de una manera que preserva el conocimiento previo al tiempo que incorpora nuevos ejemplos. Esta técnica se basa en investigaciones recientes sobre aprendizaje continuo; consulte la sección [Referencias](#references) al final de este archivo README.
 
-### Interfaz de línea de comandos
+La versión de la línea de comandos:
 
 ```bash
-backprop train --data my_data.jsonl --model Qwen/Qwen2.5-7B-Instruct --steps 100
-backprop multi-run --data my_data.jsonl --runs 5 --steps 100
-backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --ollama-name my-model
-backprop ui --port 7862
-backprop info
-backprop list-runs                              # v1.1.0: query past training runs
-backprop show-run <run-id>                      # v1.1.0: detail view
-backprop resume <run-id>                        # v1.1.0: resume a crashed multi-run
-backprop push ./output/lora --repo me/my-model  # v1.1.0: push adapter to HF Hub
+backprop multi-run --data my_data.jsonl --runs 5 --steps 100 --samples 1000
 ```
 
-Consulte [la referencia de la interfaz de línea de comandos](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/) para cada subcomando y opción, o ejecute `backprop <subcomando> --help`.
-
-### Reanudación desde un punto de control (v1.1.0)
+## Reanudar desde un punto de control
 
-Una ejecución multi-ejecución de 5 ejecuciones que falla en la ejecución 4 ahora se puede recuperar. Cada sesión de ejecución multi-ejecución escribe su `run_id` tanto en `run_history.json` como en el manifiesto de punto de control en el disco, por lo que para reanudar donde lo dejó, solo necesita un comando:
+Una ejecución de entrenamiento de 5 pasadas que se interrumpe en la pasada 4 se puede recuperar. Cada sesión de entrenamiento con múltiples ejecuciones escribe su ID de ejecución en el historial y el manifiesto del punto de control almacenados en el disco, por lo que para reanudar desde donde lo dejó, solo necesita un comando:
 
 ```bash
-backprop resume <run-id>                       # picks up the in-progress session
-backprop multi-run --data ... --resume <run-id> # explicit form
-backprop train --data ... --resume <run-id>    # single-run resume (continues run_id)
+backprop resume <run-id>
+backprop multi-run --data ... --resume <run-id>
+backprop train --data ... --resume <run-id>     # single-run resume
 ```
 
-El comportamiento predeterminado de `backprop multi-run` (sin `--resume`) detecta automáticamente si existe una ejecución en curso para el mismo directorio de salida y la continúa. Para forzar una sesión limpia, use `resume_from="off"` (API de Python) o omita `--resume` y comience en un directorio de salida nuevo.
-
-Cuando se reanuda una ejecución multi-run, se carga el último checkpoint para ese `run_id` en el modelo, el estado de fusión SLAO se restaura desde el directorio `slao/` junto al checkpoint, y el bucle de ejecución continúa desde `last_completed_run + 1`. El estado de la entrada del historial cambia a `running`, por lo que `backprop list-runs --status running` muestra la sesión activa.
+El comportamiento predeterminado de `backprop multi-run` (sin `--resume`) detecta automáticamente una ejecución en curso en el mismo directorio de salida y la continúa. Para forzar un inicio limpio, especifique un directorio de salida nuevo.
 
-### Seguimiento de experimentos (v1.1.0)
+## Historial de entrenamiento
 
-`Trainer` detecta automáticamente los sistemas de seguimiento de experimentos instalados (`wandb`, `tensorboard`, `mlflow`) y los integra con los `transformers.TrainingArguments` subyacentes. El valor predeterminado `report_to="auto"` utiliza cualquier sistema que se pueda importar:
+Cada invocación de `backprop train` y `backprop multi-run` registra una fila en `<output>/run_history.json`, que incluye el modelo utilizado, el conjunto de datos, los hiperparámetros, el estado, la pérdida final y el historial de pérdidas. Puede enumerar e inspeccionar ejecuciones anteriores:
 
 ```bash
-pip install backpropagate[monitoring]  # installs wandb + psutil
-wandb login                            # one-time
-backprop train --data my_data.jsonl    # W&B run gets the same run_id prefix as the on-disk history
+backprop list-runs                         # last 20 runs
+backprop list-runs --status failed         # filter by status
+backprop list-runs --json --limit 100      # machine-readable
+backprop show-run abcd1234                 # detail view (partial ID is fine)
 ```
 
-Para desactivar explícitamente, use `Trainer(report_to=["wandb"])`, `Trainer(report_to=["tensorboard"])` o `Trainer(report_to="none")`. Para MLflow, instale `pip install mlflow`; para TensorBoard, instale `pip install tensorboard`. El nombre de la ejecución de W&B es `backprop-<run_id_prefix>`, lo que permite a un operador buscar en W&B, nuestros registros y `run_history.json` utilizando el mismo identificador.
-
-### Historial de entrenamiento
+## Seguimiento de experimentos
 
-Cada invocación de `backprop train` y `backprop multi-run` registra una fila en `<output>/run_history.json` con el `run_id`, el modelo, el conjunto de datos, los hiperparámetros, el estado, la pérdida final, el historial de pérdidas y, para las ejecuciones multi-run, la línea de tiempo de la fusión SLAO. Para ver las ejecuciones recientes:
+Backpropagate detecta automáticamente los sistemas de seguimiento de experimentos instalados (Weights & Biases, TensorBoard, MLflow) y los integra. Si `wandb` está instalado y ha iniciado sesión, cada ejecución se registra automáticamente en W&B con un nombre de ejecución que coincide con el ID de ejecución almacenado en el disco, lo que le permite buscar en W&B, sus registros y `run_history.json` utilizando un único identificador.
 
 ```bash
-backprop list-runs                         # most recent 20 runs, all statuses
-backprop list-runs --status failed         # filter
-backprop list-runs --json --limit 100      # machine-readable
-backprop show-run abcd1234                 # detail view (partial run_id ok)
+pip install backpropagate[monitoring]   # installs wandb + psutil
+wandb login                             # one-time setup
+backprop train --data my_data.jsonl
 ```
 
-El historial de ejecuciones persiste entre procesos; la pestaña "Runs" en la interfaz web es una vista en memoria; el historial en disco es la fuente de verdad para `list-runs` / `show-run` / `resume`.
+Puede anular este comportamiento con `Trainer(report_to=["wandb"])`, `Trainer(report_to=["tensorboard"])` o `Trainer(report_to="none")` para desactivarlo.
 
-### Interfaz web
+## Interfaz web
 
-Inicie la interfaz de Reflex localmente:
+La interfaz web de Reflex es opcional; instálela con `pipx install "backpropagate[ui]"` y ejecútela:
 
 ```bash
 backprop ui --port 7862
 ```
 
-Para exponer una URL accesible desde Internet, debe combinar `--share` con `--auth`:
+La interfaz de usuario se ejecuta localmente en `http://localhost:7862`. Para permitir el acceso desde otros dispositivos (otras personas en su red, una URL pública, etc.), debe combinar `--share` (o `--host`) con `--auth`:
 
 ```bash
 backprop ui --share --auth alice:hunter2
 ```
 
-El comando `backprop ui --share` sin la opción `--auth` finaliza con el código `1` y el siguiente mensaje de error estructurado: `[RUNTIME_UI_AUTH_NOT_ENFORCED]`. La razón es que la opción `--share` publica una URL pública a la que cualquier persona en internet puede acceder, y sin autenticación, esto significa que cualquiera puede controlar su proceso de entrenamiento. No existe una opción para desactivar esta característica; si no desea establecer credenciales, utilice el reenvío de puertos SSH en su lugar: `ssh -L 7860:localhost:7860 <host>`, y luego abra `http://localhost:7860` localmente. Consulte el documento [handbook/security.md](site/src/content/docs/handbook/security.md) para obtener información completa sobre el modelo de amenazas.
+`backprop ui --share` sin `--auth` genera un error. La razón es que `--share` publica una URL a la que cualquier persona en Internet puede acceder, y sin autenticación, eso significa que cualquier persona puede controlar su canal de entrenamiento y leer su token de Hugging Face. No hay forma de desactivar esta función; si no desea establecer credenciales, utilice el reenvío de puertos SSH en su lugar:
+
+```bash
+# On the client:
+ssh -L 7860:localhost:7860 <your-training-host>
+# On the server:
+backprop ui                             # no --share
+# Then open http://localhost:7860 in your local browser
+```
+
+Consulte [handbook/security.md](https://mcp-tool-shop-org.github.io/backpropagate/handbook/security/) para obtener información detallada sobre el modelo de amenazas.
 
 Las escrituras en el sistema de archivos desde la interfaz de usuario están restringidas a un solo directorio:
 
 - Predeterminado: `~/.backpropagate/ui-outputs`
-- Para sobrescribir: `BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own`
-- La sobrescritura está **validada mediante una lista de denegación**; las rutas del sistema/credenciales (`/etc`, `/var`, `~/.ssh`, `~/.aws`, `C:\Windows\System32`, etc.) se rechazan con `[UI_OUTPUT_DIR_FORBIDDEN]`.
+- Para sobrescribir: establezca `BACKPROPAGATE_UI__OUTPUT_DIR=/ruta/propia`
+- La sobrescritura se valida mediante una lista de denegación; se rechazan las rutas del sistema o de credenciales (`/etc`, `~/.ssh`, `~/.aws`, `C:\Windows\System32`, etc.).
 
-## Soporte para Windows
+## Notas sobre la plataforma
 
-Backpropagate está diseñado para funcionar en Windows de forma predeterminada:
+**Requisitos:** Python 3.10+ · GPU con CUDA (8GB+ de VRAM) · PyTorch 2.0+
 
-- Pre-tokenización para evitar fallos en el procesamiento paralelo
-- Desactivación automática de xformers para series RTX 40/50
-- Configuración segura del cargador de datos
-- Probado en RTX 5080 (16GB de VRAM)
+Python 3.10 llegará al final de su vida útil en octubre de 2026, y Backpropagate planea eliminar el soporte para 3.10 en la versión 1.4. Para nuevas instalaciones, prefiera Python 3.11 o 3.12; 3.11 es la versión más probada.
 
-## Preajustes de modelos
+Backpropagate gestiona las peculiaridades del entorno de ejecución al entrenar en diferentes plataformas, pero no puede solucionar problemas de instalación. Los dos problemas más comunes son:
 
-| Preajuste | VRAM | Velocidad | Calidad |
-|--------|------|-------|---------|
-| Qwen 2.5 7B | ~12GB | Media | Óptima |
-| Qwen 2.5 3B | ~8GB | Rápida | Buena |
-| Llama 3.2 3B | ~8GB | Rápida | Buena |
-| Llama 3.2 1B | ~6GB | La más rápida | Básica |
-| Mistral 7B | ~12GB | Media | Buena |
+- **Controlador CUDA incorrecto.** PyTorch se publica con un binario por cada versión de CUDA. Si elige el incorrecto, obtendrá una versión de PyTorch solo para CPU, y el entrenamiento será extremadamente lento. Utilice el selector de controladores en <https://pytorch.org/get-started/locally/> para su controlador. Ejecute `nvidia-smi` para ver la versión de su controlador/CUDA.
+- **Windows + exportación GGUF.** La opción `[export]` compila `llama-cpp-python` desde el código fuente, lo que requiere Visual Studio Build Tools (componente C++) y CMake.
 
-## Arquitectura
+**macOS:** El entrenamiento con GPU no está soportado (no hay CUDA). Puede ejecutar el adaptador entrenado en un Mac a través de Ollama, pero `trainer.train()` genera un error `DEP_GPU_NOT_AVAILABLE`. Utilice una máquina con Linux o Windows con CUDA para el entrenamiento.
 
+Consulte la [página del manual de solución de problemas](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) para obtener una guía completa sobre la solución de problemas de instalación, y la [página de solución de problemas de CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/) dedicada para problemas de controlador/VRAM/xformers/bf16-vs-fp16.
+
+## Interfaz de línea de comandos
+
+Cada API de Python tiene un equivalente de línea de comandos (CLI):
+
+```bash
+backprop train --data my_data.jsonl --model Qwen/Qwen2.5-7B-Instruct --steps 100
+backprop multi-run --data my_data.jsonl --runs 5 --steps 100
+backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --ollama-name my-model
+backprop ui --port 7862
+backprop info                          # environment + version snapshot
+backprop list-runs                     # past training runs
+backprop show-run <run-id>             # detail view
+backprop resume <run-id>               # resume a crashed run
+backprop push ./output/lora --repo me/my-model    # push adapter to HuggingFace Hub
+backprop diff-runs <run-a> <run-b>     # diff two runs side by side
+backprop replay <run-id>               # re-run with same config / dataset
+backprop export-runs --format jsonl    # bulk export run history
 ```
-backpropagate/
-├── trainer.py           # Core Trainer class
-├── multi_run.py         # Multi-run SLAO training
-├── slao.py              # SLAO LoRA merging algorithm
-├── datasets.py          # Dataset loading, filtering & curriculum
-├── export.py            # GGUF/Ollama export
-├── config.py            # Pydantic settings + training presets
-├── gpu_safety.py        # GPU monitoring & safety
-├── cli.py               # CLI entry point (backprop command)
-├── checkpoints.py       # Checkpoint management
-├── exceptions.py        # Structured error hierarchy
-├── feature_flags.py     # Optional feature detection
-├── security.py          # Path traversal & torch security
-├── logging_config.py    # Structured logging setup
-├── ui_theme.py          # Radix theme tokens + CSS (Reflex era)
-├── ui_state.py          # rx.State subclasses
-├── ui_app/              # Reflex web interface (Radix UI)
-│   ├── app.py           #   rx.App entry point
-│   ├── chrome.py        #   Header / LeftNav / SideRail / Footer
-│   ├── pages/           #   Train / Multi-Run / Export / Dataset
-│   └── components/      #   Bp* primitives (status pill, sparkline, event log…)
-└── ui_security.py       # Rate limiting, CSRF, file validation (framework-agnostic)
-```
 
-La implementación de Gradio de la versión 1.0 (`ui_gradio_legacy.py` + `theme_gradio_legacy.py`) se conservó hasta la versión 1.1.x como referencia y se eliminó en la versión 1.2.0.
+Consulte la referencia completa en [la página de referencia del CLI](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/), o `backprop <subcomando> --help`.
+
+## Configuración
+
+Cada configuración se puede sobrescribir con una variable de entorno utilizando el prefijo `BACKPROPAGATE_`:
+
+| Variable | Valor predeterminado | Notas |
+|---|---|---|
+| `BACKPROPAGATE_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
+| `BACKPROPAGATE_LOG_JSON` | automático | Forzar registros JSON o de consola |
+| `BACKPROPAGATE_MODEL__NAME` | `Qwen/Qwen2.5-7B-Instruct` | Modelo predeterminado |
+| `BACKPROPAGATE_TRAINING__LEARNING_RATE` | `2e-4` | Tasa de aprendizaje |
+| `BACKPROPAGATE_LORA__R` | `256` | Rango LoRA (valor predeterminado de la versión 1.3; use `--lora-preset=fast` para el valor predeterminado de la versión 1.2.x, que es 16) |
+| `BACKPROPAGATE_UI__OUTPUT_DIR` | `~/.backpropagate/ui-outputs` | Sistema de archivos de la interfaz de usuario (sandbox) |
+
+Las claves anidadas utilizan doble guion bajo (`MODEL__NAME`, no `MODEL_NAME`). La referencia completa se encuentra en [la página del manual de variables de entorno](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/).
+
+## Preajustes de modelos
+
+| Preajuste | VRAM | Licencia | Notas |
+|---|---|---|---|
+| Qwen-3.5-4B | ~8GB | Apache 2.0 | Valor predeterminado recomendado para modelos de menos de 5B. La mejor calidad para este tamaño. |
+| Phi-4-mini-3.8B | ~8GB | MIT | Excelente para razonamiento, matemáticas y código. Licencia limpia. |
+| SmolLM3-3B | ~6GB | Apache 2.0 | Receta completamente abierta. Contexto nativo de 64K. |
+| Qwen 2.5 7B | ~12GB | Apache 2.0 | Valor predeterminado existente. La mejor calidad de los modelos heredados de 7B. |
+| Qwen 2.5 3B | ~8GB | Qwen-Research | ⚠ licencia de investigación; consulte los términos de la licencia de Qwen antes de usarlo comercialmente. |
+| Llama 3.2 3B | ~8GB | Llama Community | Una alternativa sólida a Qwen 3B con algunas restricciones. |
+| Llama 3.2 1B | ~6GB | Llama Community | Ideal para experimentos rápidos en tarjetas pequeñas. |
+| Mistral 7B | ~12GB | Apache 2.0 | Comparable a Qwen 7B, pero con una plantilla de chat diferente. |
+
+Otros modelos pueden funcionar, pero solo estos ocho están incluidos en las pruebas automatizadas (CI). Utilice `--lora-preset=quality` (predeterminado) para obtener un rango de 256 / objetivos de línea recta, según Biderman 2024 + Thinking Machines 2025, o `--lora-preset=fast` para obtener el rango de 16 / objetivo q+v de la versión 1.2.x si necesita la huella de la versión 1.2.x.
 
 ## Resolución de problemas
 
-Un índice breve de los fallos más comunes al inicio. El índice inverso completo se encuentra en [la página del manual de solución de problemas](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/); cada código que se muestra a continuación está documentado en [códigos de error](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/).
+Un índice breve de los fallos más comunes al ejecutarlo por primera vez. El índice inverso completo se encuentra en [la página del manual de solución de problemas](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/). Para obtener información detallada sobre el controlador/VRAM/precisión mixta, consulte la [página de solución de problemas de CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/).
 
-| Síntoma | Código | Solución |
-|---------|------|-----|
-| La GPU se queda sin memoria durante el entrenamiento. | `RUNTIME_GPU_OOM` | La recuperación automática de errores de memoria (OOM) (B-002) reduce automáticamente el tamaño del lote hasta 3 veces. Para desactivar esta función: `Trainer(oom_recovery=False)`. Para forzar un tamaño de lote más pequeño: `--batch-size 1`. |
-| El centro de Hugging Face devuelve un error 401 / "modelo no encontrado". | `DEP_MODEL_LOAD_FAILED` | Ejecute `huggingface-cli login` e inténtelo de nuevo. Si hay errores tipográficos, copie el ID exacto de <https://huggingface.co/models>. |
-| Error tipográfico en el nombre del modelo. | `INPUT_VALIDATION_FAILED` o `DEP_MODEL_LOAD_FAILED`. | Verifique el identificador `org/name` en <https://huggingface.co/models>. |
+| Síntoma | Código de error | Solución |
+|---|---|---|
+| La GPU se queda sin memoria durante el entrenamiento. | `RUNTIME_GPU_OOM` | Automatic — Backpropagate reduce la mitad del tamaño del lote e intenta hasta 3 veces. Para desactivar esta función: `Trainer(oom_recovery=False)`. Para forzar un tamaño de lote más pequeño: `--batch-size 1`. |
+| HuggingFace devuelve 401 / "modelo no encontrado" | `DEP_MODEL_LOAD_FAILED` | Ejecute `huggingface-cli login` e inténtelo de nuevo. Si hay errores tipográficos, copie el ID exacto de <https://huggingface.co/models>. |
 | `register_with_ollama` rechaza la conexión. | `DEP_OLLAMA_REGISTRATION_FAILED` | Inicie el demonio: `ollama serve`. Instálelo desde <https://ollama.com>. Se puede volver a intentar. |
 | El disco se llena durante el guardado del punto de control. | `STATE_CHECKPOINT_INVALID` | Las escrituras atómicas dejan un directorio `.partial` en caso de fallo; es seguro eliminarlo. El punto de control anterior y válido está intacto. |
-| El entrenamiento se pausa/interrumpe debido al sobrecalentamiento de la GPU. | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | B-003: el monitor se pausa debido al umbral de temperatura de NVML; se reanuda automáticamente a medida que la GPU se enfría. Mejore el flujo de aire o reduzca la carga sostenida. |
-| `backprop ui --share` es rechazado. | `INPUT_AUTH_REQUIRED` | Pase `--auth user:password` o configure `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false` para desactivar esta función (con una advertencia). |
-| "Superposición de validación" en múltiples ejecuciones. | `CONFIG_INVALID` (Etapa A, backend B-001). | Reduzca `--samples` por debajo del tamaño del grupo de entrenamiento, aumente el conjunto de datos o desactive la validación. |
+| Entrenamiento pausado debido a sobrecalentamiento de la GPU. | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | Automatic — Backpropagate pausa cuando se alcanza el umbral de temperatura y reanuda cuando la GPU se enfría. Mejore el flujo de aire si esto ocurre con frecuencia. |
+| `backprop ui --share` es rechazado. | `INPUT_AUTH_REQUIRED` | Utilice `--auth user:password` o, en su lugar, use el reenvío de puertos SSH (consulte [Interfaz de usuario web](#web-ui)). |
 | La exportación a GGUF falló en el primer intento. | `RUNTIME_GGUF_EXPORT_FAILED` | `pip install backpropagate[export]`; en Windows, también necesita Visual C++ Build Tools + CMake. |
 
 ## Informar de errores
 
-Cuando algo falla, Backpropagate imprime una línea `run_started run_id=<uuid>` al inicio y asocia el mismo ID a los manifiestos de puntos de control, el historial de combinación de SLAO y las líneas de registro estructuradas. Incluya el `run_id` en cualquier informe de error; esto permite a un mantenedor correlacionar cada línea de registro, cada punto de control y cada combinación para esa ejecución específica.
+Cuando algo falla, Backpropagate imprime una línea al inicio, como `run_started run_id=<uuid>`, y asocia el mismo ID a cada línea de registro, a cada punto de control y a cada entrada de Weights & Biases. **Incluya el `run_id` en cualquier informe de error**; esto permite al responsable del mantenimiento correlacionar todo para esa ejecución específica.
 
 Un buen informe de error incluye:
 
-1. **`run_id`** — el UUID impreso al inicio (también disponible como `TrainingRun.run_id` y `RunResult.run_id`).
-2. **El código de error** — la línea `[CODE_NAME]: message` en stderr es lo que debe buscar; consulte [códigos de error](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) para ver el catálogo.
-3. **La línea de comandos con información sensible eliminada.** La salida de error en modo no detallado se elimina automáticamente (los tokens Bearer, `sk-*`, `hf_*`, las claves de AWS, los pares `password=/token=/api_key=` se eliminan); es seguro pegarla. Para obtener el rastreo completo y sin eliminar, vuelva a ejecutar con `--verbose`, pero revise antes de publicarlo.
-4. **Versiones de Python / PyTorch, modelo de GPU, sistema operativo.** `backprop info` imprime todo esto de una vez.
+1. **El `run_id`**: El UUID que se muestra al inicio. Un UUID permite al responsable del sistema correlacionar cada línea de registro, cada punto de control y cada entrada de Weights & Biases para esa ejecución específica.
+2. **El código de error**: La línea `[NOMBRE_DEL_CÓDIGO]: mensaje` que aparece en stderr. Consulte [códigos de error](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) para ver el catálogo de códigos estables.
+3. **El rastreo de errores (traceback) con información sensible eliminada.** En el modo no detallado, stderr se elimina automáticamente (los tokens Bearer, `sk-*`, `hf_*`, las claves de AWS, y las parejas `password=` / `token=` / `api_key=` se eliminan) — es seguro copiarlo. Para ver el rastreo de errores completo y sin información sensible eliminada, ejecute de nuevo con `BACKPROPAGATE_DEBUG=1` (o `--verbose`); revise antes de publicarlo.
+4. **La salida de `backprop info`**. Un comando imprime información sobre Python / PyTorch / CUDA / el modelo de la GPU / VRAM / el sistema operativo / los complementos instalados: todo lo que el responsable del sistema necesita para identificar la causa de una regresión específica de la plataforma.
+
+La [plantilla para informes de errores](https://github.com/mcp-tool-shop-org/backpropagate/issues/new?template=bug_report.yml) solicita explícitamente cada uno de estos elementos, lo que permite una resolución rápida de los problemas. Las preguntas, ideas o discusiones sobre si un comportamiento es esperado deben realizarse en [GitHub Discussions](https://github.com/mcp-tool-shop-org/backpropagate/discussions). Los problemas de seguridad deben informarse de forma privada a través del formulario de [GitHub Security Advisory](https://github.com/mcp-tool-shop-org/backpropagate/security/advisories/new); consulte el archivo [SECURITY.md](SECURITY.md) para conocer la política y los plazos de respuesta.
 
 ## Privacidad
 
 Todo el entrenamiento se realiza localmente en su GPU. Backpropagate no realiza solicitudes de red excepto para descargar modelos de HuggingFace (lo cual usted inicia). No hay telemetría, ni dependencia de la nube.
 
-## Tabla de puntuación
+## Referencias
 
-| Categoría | Puntuación | Notas |
-|----------|-------|-------|
-| A. Seguridad | 6/8 | SECURITY.md, modelo de confianza, sin secretos/telemetría, safe_path(). Se omiten los elementos de MCP. |
-| B. Manejo de errores | 5/7 | Estructura de excepciones (`código`/`mensaje`/`indicación`/`causa`/`reintentable`) a través del registro ERROR_CODES; códigos de salida de la CLI: 0/1/2/3; no se muestran rastreos de pila sin `--verbose`; correlación con `run_id`; salida de error estándar (stderr) censurada; bloqueo mediante `--share` + `--auth`. MCP/escritorio/VS Code omitidos. |
-| C. Documentación para operadores | 4/7 | README, CHANGELOG, LICENCIA, --help. Registro/MCP/elementos complejos omitidos. |
-| D. Higiene del proceso de entrega | 6/9 | verify.sh, versión=etiqueta, 5 analizadores en CI, dependabot, python_requires, compilación limpia. |
-| E. Identidad | 4/4 | Logotipo, traducciones, página de inicio, metadatos. |
-| **Total** | **25/31** | 14 elementos omitidos con justificación. `shipcheck audit` pasa el 100%. Fecha de auditoría: 2026-05-21 (La fila B fue reevaluada después de la etapa B y el trabajo de códigos de salida de la CLI). |
+Los valores predeterminados de Backpropagate y el modo de entrenamiento con múltiples ejecuciones se basan en investigaciones recientes. Si está interesado en las técnicas subyacentes:
 
-Historial de diseño y correspondencia de cada elemento: consulte [ROADMAP.md](ROADMAP.md). Todos los elementos de las semanas 1 a 4 se incluyen en la versión 1.1.0.
+- **Hu et al. 2021.** *LoRA: Low-Rank Adaptation of Large Language Models.* [arXiv:2106.09685](https://arxiv.org/abs/2106.09685) — el artículo fundamental que introduce LoRA, que es la forma en que Backpropagate entrena adaptadores de manera eficiente.
+- **Biderman et al. 2024.** *LoRA Learns Less and Forgets Less.* [arXiv:2405.09673](https://arxiv.org/abs/2405.09673) — evidencia empírica de que LoRA con un rango de 256 y objetivos totalmente lineales coincide con la calidad del ajuste fino completo en la mayoría de las tareas posteriores al entrenamiento, utilizando el 67% de la capacidad de cómputo. Define la configuración predeterminada de LoRA de la versión 1.3 de Backpropagate.
+- **Thinking Machines 2025.** *LoRA Without Regret.* [thinkingmachines.ai/blog/lora](https://thinkingmachines.ai/blog/lora/) — el seguimiento práctico que identifica la corrección de 10 veces la tasa de aprendizaje con respecto al ajuste fino completo necesaria para rangos LoRA altos.
+- **Kirkpatrick et al. 2017.** *Overcoming catastrophic forgetting in neural networks.* [arXiv:1612.00796](https://arxiv.org/abs/1612.00796) — la caracterización original de por qué las redes neuronales "olvidan" el entrenamiento anterior cuando se ajustan a nuevos datos (EWC — Elastic Weight Consolidation).
+- **Wang et al. 2023.** *Orthogonal Subspace Learning for Language Model Continual Learning.* [arXiv:2310.14152](https://arxiv.org/abs/2310.14152) — O-LoRA, un enfoque anterior para usar LoRA para el aprendizaje continuo, restringiendo los nuevos adaptadores a subespacios ortogonales.
+- **Yadav et al. 2023.** *TIES-Merging: Resolving Interference When Merging Models.* [arXiv:2306.01708](https://arxiv.org/abs/2306.01708) — una técnica fundamental para fusionar múltiples modelos ajustados sin interferencia.
+- **Qiao & Mahdavi 2025.** *Merge before Forget: A Single LoRA Continual Learning via Continual Merging.* [arXiv:2512.23017](https://arxiv.org/abs/2512.23017) — el algoritmo específico que implementa el fusionador de múltiples ejecuciones de Backpropagate. Un preprint de diciembre de 2025; Backpropagate es el primer adoptador conocido en un entorno de producción.
 
 ## Licencia
 
-MIT: Consulte [LICENSE](LICENSE) para obtener más detalles.
+MIT — consulte [LICENSE](LICENSE).
 
 ---