@mcptoolshop/backpropagate 1.2.0 → 1.4.0

package/README.it.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>
 
-**Messa a punto di LLM senza interfaccia utente in 3 righe. Impostazioni predefinite intelligenti, dimensionamento automatico dei batch in base alla VRAM, addestramento SLAO multi-sessione e esportazione GGUF con un solo clic per Ollama.**
+# Addestra un adattatore. Inoltralo a Ollama. Finito
 
-*SLAO è Single LoRA Continual Learning via Asymmetric Merging: una tecnica di unione tra sessioni di addestramento che previene la perdita di informazioni durante le sessioni di messa a punto prolungate (articolo: [https://arxiv.org/abs/2512.23017]).*
+Backpropagate è una libreria Python per l'affinamento di modelli linguistici di grandi dimensioni su una singola GPU. Tre righe di codice addestrano un modello da 7 miliardi di parametri su una scheda da 16 GB. Un altro comando lo esporta in Ollama, così puoi eseguire il tuo modello affinato con `ollama run`. Funziona perfettamente anche su Windows.
 
-*Addestra modelli linguistici di grandi dimensioni con 3 righe di codice. Esportali su Ollama con un'altra riga.*
+```python
+from backpropagate import Trainer
 
-## Guida rapida
+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
+Ecco tutto. Non c'è bisogno di un file di configurazione YAML. Non c'è la "cerimonia" di `accelerate launch`. Non c'è un tutorial separato su come "convertirlo in GGUF". Se hai una GPU CUDA e un file JSONL con i tuoi dati di addestramento, sei a solo tre righe di codice dall'avere un modello affinato funzionante.
 
-trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")
-trainer.train("examples/quickstart.jsonl", steps=10)
-trainer.export("gguf", quantization="q4_k_m")  # Ready for Ollama
-```
+## Installazione
+
+```bash
+# Recommended: isolated Python install (no conflicts with system Python or other projects)
+pipx install backpropagate
 
-Il repository include un piccolo file `examples/quickstart.jsonl` (5 esempi in formato ShareGPT) in modo che lo snippet precedente possa essere eseguito completamente su un'installazione pulita. Per il tuo addestramento, consulta la sezione [Formato del dataset](#dataset-format) sottostante.
+# Or via uv (faster install, same isolation)
+uv tool install backpropagate
 
-### Percorso senza codice: Interfaccia web
+# Standard pip (if you manage your own virtualenv)
+pip install backpropagate
+```
 
-Preferisci un'interfaccia utente anziché una REPL Python? Installa gli extra necessari ed esegui:
+Se desideri le funzionalità opzionali, sostituisci l'installazione con una di queste:
 
 ```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.
 ```
 
-L'interfaccia Reflex (Radix UI) ti consente di puntare a un file JSONL, selezionare un modello, addestrare e esportare: non è richiesta alcuna conoscenza di Python. L'interfaccia utente è progettata per funzionare principalmente in locale; per l'accesso tramite internet, consulta la sezione [Interfaccia web](#web-ui) sottostante per il contratto di sicurezza `--share` + `--auth` e le opzioni di tunneling supportate (Cloudflare Tunnel, ngrok).
+Preferisci Docker? `docker pull ghcr.io/mcp-tool-shop-org/backpropagate:latest` funziona anche. Sono disponibili immagini per `linux/amd64` e `linux/arm64`, quindi gli utenti con Apple Silicon e ARM Linux hanno a disposizione un'immagine nativa. Un file `compose.yaml` standard per "UI in un container" si trova nella directory principale del repository: `docker compose up` avvia l'interfaccia web su `http://localhost:7860` con un volume persistente `~/.backpropagate` montato.
 
-## Formato del dataset
+## Dove si colloca Backpropagate
 
-Il tuo file di addestramento JSONL dovrebbe contenere un esempio per riga. Il formato più semplice è la chat ShareGPT:
+Esistono diverse buone librerie per l'affinamento di modelli linguistici di grandi dimensioni. Ognuna è eccellente per cose diverse:
 
-```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)** — se ti piacciono le configurazioni YAML e vuoi una comunità di ricette da cui prendere spunto.
+- **[LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory)** — se desideri un'interfaccia grafica web e un supporto integrato per DPO/PPO/RLHF.
+- **[Unsloth](https://github.com/unslothai/unsloth)** — se hai bisogno della formazione più veloce possibile e utilizzi una famiglia di modelli supportata.
+- **[torchtune](https://github.com/pytorch/torchtune)** — se desideri le ricette native di PyTorch di Meta che puoi modificare.
 
-Sono supportati anche i formati Alpaca (`instruction`/`output`), OpenAI chat (`messages`) e testo semplice. Consulta `examples/quickstart.jsonl` per un punto di partenza.
+Backpropagate è l'opzione mancante: **un'API Python di 3 righe per gli utenti singoli che utilizzano una singola GPU consumer e che desiderano addestrare un adattatore e distribuirlo.** Nessun YAML, nessuna interfaccia grafica, nessun DPO/PPO, nessuna configurazione multi-nodo. Solo il ciclo di lavoro di cui tutti hanno bisogno e la fase di esportazione che crea problemi.
 
-## Perché propagare il gradiente?
+Se hai provato una delle librerie sopra e ti sei sentito frustrato dalla "cerimonia" del file di configurazione, o hai riscontrato un problema con la famiglia di modelli, o volevi impostazioni predefinite per Windows — Backpropagate è quello che fa per te.
 
-| Problema | Soluzione |
-|---------|----------|
-| La messa a punto è complessa | 3 righe: caricamento, addestramento, salvataggio |
-| Windows è un incubo | Supporto completo per Windows |
-| La gestione della VRAM è difficile | Dimensionamento automatico dei batch, monitoraggio della GPU |
-| L'esportazione del modello è complicata | Esportazione GGUF con un solo clic + registrazione automatica con Ollama |
-| Le sessioni di addestramento prolungate causano la perdita di informazioni | Addestramento SLAO multi-sessione |
+## Cosa puoi affinare su una GPU consumer da 16 GB
 
-## Caratteristiche principali
+Ecco i limiti pratici su una scheda da 16 GB (RTX 4080 / 5080 / 4070 Ti Super):
 
-- **Senza interfaccia utente per design**: Progettato per pipeline CI/CD, flussi di lavoro automatizzati ed esecuzione programmatica.
-- **Impostazioni predefinite intelligenti**: Configura automaticamente gli iperparametri ottimali in base all'hardware e al dataset.
-- **Addestramento SLAO multi-sessione**: Strategie di addestramento avanzate per prevenire la perdita di informazioni durante le sessioni di addestramento prolungate.
-- **Supporto completo per Windows**: Testato e ottimizzato per gli ambienti Windows, evitando i problemi comuni di PyTorch/CUDA.
-- **Esportazione semplice**: Esportazione con un solo clic nel formato GGUF e registrazione automatica con Ollama.
-- **Architettura modulare**: Installa solo le dipendenze necessarie (ad esempio, `[unsloth]`, `[ui]`, `[export]`).
+| Modello | Metodo | Stato |
+|---|---|---|
+| Qwen-3.5-4B / Phi-4-mini-3.8B / SmolLM3-3B | LoRA / QLoRA / DoRA | Comodo. Lunghezza della sequenza completa, con spazio extra. |
+| Phi-4-mini-3.8B / Qwen-3.5-4B / SmolLM3-3B (limite massimo di 3 miliardi di parametri) | `mode="full"` (affinamento completo) | v1.4 — utilizzare l'opzione `--mode=full` con `backprop train` oppure `Trainer(..., mode="full")`. Il checkpointing del gradiente e l'utilizzo di Adam a 8 bit con paginazione mantengono la memoria delle attivazioni a sqrt(L). |
+| Qwen-2.5-7B / Llama-3.1-8B / Mistral-7B | QLoRA | Standard. Circa 7-8 GB. Impostazioni predefinite di Backpropagate. |
+| Llama-3 13B | QLoRA + sample packing | Limitato ma funzionante. Utilizza sequenze più corte. |
+| Mixtral 8x7B (47 miliardi di parametri totali) | AQLM 2-bit + LoRA | Previsto per la v1.5 — consultare il documento V1_5_BRIEF quando sarà disponibile. |
 
-## Installazione
+La quantizzazione AQLM a 2 bit (`quant_method="aqlm"`, opzione sperimentale per Mixtral-8x7B su 16GB) era prevista per la v1.4 ed è ora pianificata per la v1.5. La libreria `aqlm` è matura; nella versione 1.4, la priorità è stata data al supporto per l'affinamento completo per modelli con un massimo di 3 miliardi di parametri (`mode="full"`) piuttosto che all'aggiunta di un nuovo backend di quantizzazione. Consultare il documento V1_5_BRIEF quando sarà disponibile per il piano di implementazione della v1.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
-```
+Per i modelli da 3 miliardi di parametri in giù, l'affinamento completo (e non solo LoRA) è possibile su 16GB ed è ora disponibile nella v1.4 con `mode="full"`. Per abilitarlo, utilizzare `Trainer(..., mode="full")` oppure `backprop train --mode=full --model phi-4-mini-3.8b`. Un meccanismo di controllo impedisce l'utilizzo di questa modalità per modelli superiori a 3 miliardi di parametri, suggerendo LoRA e le configurazioni predefinite inferiori a 3 miliardi come alternative. Consultare la [pagina completa del manuale sull'affinamento completo](https://mcp-tool-shop-org.github.io/backpropagate/handbook/full-fine-tuning/) per i dettagli sulla configurazione e per il confronto della qualità tra Biderman 2024 e Thinking Machines 2025. Per i modelli da 7 miliardi di parametri in su, l'affinamento completo richiede una GPU da 24GB o superiore; si consiglia di utilizzare un servizio di cloud con una GPU A100 oppure di utilizzare LoRA, che, secondo recenti ricerche, offre una qualità equivalente all'affinamento completo nella maggior parte delle attività successive all'addestramento (vedere la [sezione "cosa Backpropagate non è"](#what-backpropagate-is-not-for) per le citazioni).
 
-| Extra | Descrizione | Dipendenze |
-|-------|-------------|--------------|
-| `unsloth` | Addestramento 2 volte più veloce, 50% di VRAM in meno | unsloth |
-| `ui` | Interfaccia web Reflex (Radix UI) | reflex>=0.9.2, fastapi>=0.115 |
-| `validation` | Validazione della configurazione Pydantic | pydantic, pydantic-settings |
-| `export` | Esportazione GGUF per Ollama | llama-cpp-python |
-| `monitoring` | WandB + monitoraggio del sistema (integrato automaticamente nel trainer dalla versione 1.1.0) | wandb, psutil |
-| `logging` | Logging strutturato | structlog |
-| `security` | Autenticazione JWT + generazione di token | PyJWT, cryptography |
-| `production` | unsloth + ui + validation + logging + security | (bundle) |
+## Cosa Backpropagate NON è
 
-**Requisiti:** Python 3.10+ · GPU CUDA (8GB+ di VRAM) · PyTorch 2.0+
+Se il vostro caso d'uso rientra nelle categorie seguenti, otterrete risultati migliori con un'altra libreria. Backpropagate non è la scelta giusta e cercare di farlo funzionare costerebbe più che utilizzare lo strumento appropriato. Leggere questa sezione prima di iniziare vi farà risparmiare tempo e tentativi.
 
-### Prerequisiti della piattaforma
+- **Affinamento completo dei parametri per modelli da 7 miliardi di parametri in su** — Backpropagate utilizza LoRA / QLoRA, che addestra un piccolo adattatore invece di aggiornare tutti i pesi. Per i modelli da 7 miliardi di parametri in su, l'affinamento completo richiede 24GB+ di memoria GPU e non è possibile su una scheda consumer da 16GB. Per i modelli da 3 miliardi di parametri in giù, l'affinamento completo è possibile su 16GB ed è disponibile nella v1.4 con `mode="full"` (utilizzare `Trainer(..., mode="full")` oppure `--mode=full` dalla riga di comando; un meccanismo di controllo impedisce l'utilizzo di questa modalità per modelli superiori a 3 miliardi di parametri, suggerendo LoRA e le configurazioni predefinite inferiori a 3 miliardi come alternative). In sintesi: recenti ricerche ([Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)) dimostrano che LoRA, con la configurazione corretta, offre una qualità equivalente all'affinamento completo nella maggior parte delle attività successive all'addestramento (istruzioni, adattamento al dominio, personalità/stile) con il 67% della potenza di calcolo; quindi, per il lavoro che la maggior parte degli operatori desidera svolgere, non si perde nulla utilizzando LoRA. `mode="full"` è disponibile per i casi in cui si è riscontrata una differenza di qualità e si è deciso di utilizzare una maggiore potenza di calcolo. Se è necessario affinare completamente un modello da 7 miliardi di parametri, utilizzare direttamente il modulo `transformers.Trainer` di HuggingFace su una scheda da 24GB o superiore.
+- **DPO / PPO / GRPO / ottimizzazione delle preferenze** — Backpropagate esegue solo l'affinamento supervisionato in una singola fase. Per l'apprendimento delle preferenze, utilizzare direttamente TRL o LLaMA-Factory.
+- **Addestramento multi-nodo** — supporta solo una GPU su una singola macchina. L'utilizzo di più GPU su una singola macchina è possibile (tramite `accelerate launch`) ma non è ufficialmente supportato.
+- **Addestramento su macOS** — Apple Silicon non dispone di CUDA, quindi l'addestramento deve essere eseguito su una macchina Linux o Windows con una GPU NVIDIA. È comunque possibile eseguire il modello addestrato su un Mac tramite Ollama.
+- **Qualsiasi modello al di fuori delle famiglie di modelli testate** — Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Altri modelli potrebbero funzionare, ma non sono inclusi nei test automatizzati.
 
-Backpropagate gestisce le peculiarità del runtime (multiprocessing, xformers su RTX 40/50, worker del dataloader su Windows). Non gestisce i problemi di installazione specifici della piattaforma: risolvili prima.
+Se avete bisogno di queste funzionalità, utilizzate una delle librerie elencate sopra. Sono più adatte per questo scopo.
 
-- **Versione del toolkit CUDA.** PyTorch viene distribuito in base alla versione di CUDA; scegliere la versione sbagliata installa silenziosamente solo la versione per CPU. Utilizzare lo strumento di selezione all'indirizzo <https://pytorch.org/get-started/locally/> per ottenere il comando `pip install torch ...` corretto per il proprio driver. Eseguire `nvidia-smi` per visualizzare la versione del driver/CUDA.
-- **Windows.** Sono necessari Visual Studio Build Tools (C++) e CMake per l'estensione `[export]` (la compilazione di `llama-cpp-python` avviene dal codice sorgente). La versione per Windows di `bitsandbytes` è ora disponibile nativamente (>= 0.43); le guide precedenti che menzionano `bitsandbytes-windows` sono obsolete.
-- **macOS.** L'addestramento con GPU **non è supportato**; non è disponibile CUDA. È possibile installare Backpropagate per eseguire l'inferenza su un file GGUF tramite Ollama, ma `trainer.train()` genera l'errore `DEP_GPU_NOT_AVAILABLE`. Utilizzare una macchina con GPU per l'addestramento.
-- **Linux.** La maggior parte delle distribuzioni funziona immediatamente. Se si utilizza la versione binaria distribuita tramite PyPI, si noti che la versione per Linux utilizza solo la versione per CPU di torch (per rimanere al di sotto del limite di 2 GB per gli asset di rilascio di GitHub); installare prima la versione CUDA corrispondente da pytorch.org.
+## Cosa offre Backpropagate:
 
-Per la risoluzione dei problemi di installazione, consultare [la pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/).
+Quattro cose, in un'unica installazione:
 
-## Configurazione
+**1. Un'API semplice, composta da sole 3 righe, che funziona senza un file di configurazione.**
+Lo snippet di codice all'inizio di questo file README viene eseguito completamente. Non è necessario `accelerate config`, né file YAML, né override di Hydra. Basta `Trainer(model).train(data)` e avrete un modello ottimizzato.
 
-Tutte le impostazioni possono essere sovrascritte tramite variabili d'ambiente utilizzando il prefisso `BACKPROPAGATE_` (ad esempio, `BACKPROPAGATE_LOG_LEVEL=debug`). Un file `.env` nella directory principale del progetto viene caricato automaticamente quando viene installata l'estensione `[validation]`.
+**2. Funzionalità che funzionano effettivamente su Windows.**
+La maggior parte delle librerie di machine learning trattano Windows come un'aggiunta secondaria. Backpropagate è stato testato in modo approfondito su Windows + RTX 5080. La libreria gestisce automaticamente le peculiarità del sistema operativo, ad esempio pre-tokenizzando i dati per evitare che il multiprocessing di Windows si blocchi, disabilitando automaticamente xformers su schede RTX 40/50 dove causerebbe problemi, e impostando le opzioni del dataloader in modo da evitare errori. Non è necessario conoscere questi dettagli; il sistema funziona semplicemente.
 
-Impostazioni comuni (vedere [il riferimento completo alle variabili d'ambiente](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/) per tutte le opzioni):
+**3. Progettato per l'esecuzione in background.**
+L'addestramento richiede ore. Non volete doverlo controllare costantemente. Backpropagate è progettato per essere lasciato in esecuzione:
 
-| Variabile | Valore predefinito | Note |
-|----------|---------|-------|
-| `BACKPROPAGATE_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
-| `BACKPROPAGATE_LOG_JSON` | auto | Forza i log in formato JSON (`true`) o nella console (`false`) |
-| `BACKPROPAGATE_LOG_FILE` | non impostato | Percorso per salvare i log |
-| `BACKPROPAGATE_DEFER_FEATURE_DETECTION` | non impostato | Salta il rilevamento delle dipendenze opzionali all'avvio per un avvio più rapido della CLI |
-| `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE` | `true` | Se impostato su `true`, rifiuta `backprop ui --share` senza l'opzione `--auth` |
-| `BACKPROPAGATE_UI__OUTPUT_DIR` | `~/.backpropagate/ui-outputs` | Directory di base per tutte le scritture del file system dell'interfaccia utente; con convalida della whitelist |
-| `BACKPROPAGATE_MODEL__NAME` | `Qwen/Qwen2.5-7B-Instruct` | Modello predefinito |
-| `BACKPROPAGATE_TRAINING__LEARNING_RATE` | `2e-4` | Learning rate (tasso di apprendimento) |
-| `BACKPROPAGATE_LORA__R` | `16` | LoRA rank (grado di LoRA) |
+- Se si esaurisce la memoria della GPU, riduce automaticamente la dimensione del batch e riprova, fino a tre volte. Non è necessario alcun intervento manuale.
+- Se la GPU si surriscalda, si interrompe fino a quando la temperatura non si abbassa e poi riprende.
+- Ogni checkpoint viene salvato in modo atomico: se il laptop si blocca durante il salvataggio, il checkpoint precedente rimane intatto.
+- Ogni esecuzione di addestramento riceve un ID univoco che viene aggiunto a ogni riga del log, a ogni checkpoint e a ogni voce di Weights & Biases. Se qualcosa va storto, un singolo ID consente a un manutentore di correlare tutti i dati.
+- Gli errori vengono segnalati con codici standard (`RUNTIME_GPU_OOM`, `DEP_OLLAMA_REGISTRATION_FAILED`, ecc.), in modo da poter cercare nei log e nella [guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) per trovare la soluzione. Gli errori specifici di CUDA hanno una [pagina dedicata alla risoluzione dei problemi di CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/).
 
-Le chiavi nidificate utilizzano il doppio underscore come delimitatore (convenzione `env_nested_delimiter` di Pydantic).
+**4. Un solo comando per passare dall'adattatore addestrato all'esecuzione con `ollama run`.**
+Molte librerie addestrano un modello. Pochi di essi semplificano l'utilizzo del modello una volta addestrato. Backpropagate esporta il modello nel formato GGUF (il formato utilizzato da Ollama) e registra un modello Ollama con un solo comando. Si passa dallo stato di "addestramento completato" allo stato di "posso chattare con il mio modello ottimizzato" in circa 30 secondi.
 
-## Utilizzo
+## Guida rapida
 
-### Addestramento di base
+Il repository include un piccolo set di dati di esempio, in modo che lo script all'inizio di questo file README possa essere eseguito con un'installazione pulita:
 
-```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")
+Questo addestra un adattatore Qwen 2.5 7B su 5 brevi conversazioni in formato ShareGPT, quindi esporta il risultato in formato GGUF. Per i tuoi dati, formatta il file JSONL con un esempio per riga:
+
+```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."}]}
+```
+
+Anche i formati Alpaca (`instruction` / `output`), OpenAI chat (`messages`) e testo semplice funzionano: Backpropagate rileva automaticamente il formato.
+
+Per flussi di lavoro più complessi (fine-tuning e pubblicazione su Hugging Face Hub, ripresa dopo errori di memoria, esecuzione multipla di SLAO su una campagna lunga, ecc.), consultare la [pagina delle ricette del manuale](https://mcp-tool-shop-org.github.io/backpropagate/handbook/recipes/).
+
+### Interfaccia web (opzionale)
+
+Se preferisci utilizzare un'interfaccia grafica invece di scrivere codice Python, installa il componente aggiuntivo dell'interfaccia utente e avvialo:
+
+```bash
+pipx install "backpropagate[ui]"
+backprop ui --port 7862
 ```
 
-`Qwen/Qwen2.5-7B-Instruct` è il valore predefinito; questo è il valore che `Trainer()` restituisce quando viene chiamato senza un argomento del modello (vedere [`config.py`](backpropagate/config.py) `ModelConfig.name`). Gli esempi precedenti utilizzavano `unsloth/Qwen2.5-7B-Instruct-bnb-4bit` (versione quantizzata), ma siamo passati ai pesi ufficiali di Qwen per una maggiore affidabilità ([CHANGELOG v1.1.0](CHANGELOG.md#110---2026-05-21)). Entrambi i modelli funzionano.
+Si apre un'interfaccia web locale all'indirizzo `http://localhost:7862`, dove puoi selezionare un set di dati, scegliere un modello, eseguire l'addestramento e l'esportazione. L'interfaccia utente è attiva solo localmente per impostazione predefinita. Per renderla accessibile da altri dispositivi, consulta la sezione [Interfaccia web](#web-ui) riportata di seguito per le opzioni `--share` e `--auth` relative alla sicurezza.
 
-### Addestramento multi-run SLAO
+## Addestramento multiplo
+
+Se desideri eseguire il fine-tuning in modo incrementale su più set di dati (ad esempio, ricevi nuovi dati di addestramento ogni settimana e desideri aggiungerli senza dimenticare ciò che hai imparato in precedenza), la modalità `multi_run` di Backpropagate è ciò che fa per te:
 
 ```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 (Single LoRA Continual Learning via Asymmetric Merging) implementa l'articolo [Merge before Forget](https://arxiv.org/abs/2512.23017): inizializzazione ortogonale della matrice A tramite decomposizione QR, gestione asimmetrica di A/B e scalatura dipendente dal tempo `λ(i) = 1/√i`. Il flag della CLI è `--samples` (il campo sottostante è `samples_per_run`).
-
-### Esportazione in 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
-```
+Questo esegue cinque cicli di addestramento, unendo l'adattatore tra un ciclo e l'altro in modo da preservare le conoscenze precedenti e incorporare nuovi esempi. Questa tecnica si basa su recenti ricerche sull'apprendimento continuo: consulta la sezione [Riferimenti](#references) in fondo a questo file README.
 
-### CLI
+La versione da riga di comando (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
-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
 ```
 
-Consultare [il riferimento della CLI](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/) per tutti i sottocomandi e i flag, oppure eseguire `backprop <sottocomando> --help`.
-
-### Ripresa da checkpoint (v1.1.0)
+## Ripresa da un checkpoint
 
-Un addestramento multi-run di 5 iterazioni che si interrompe all'iterazione 4 può ora essere ripreso. Ogni sessione di addestramento multi-run scrive il suo `run_id` sia in `run_history.json` che nel manifest del checkpoint su disco, quindi per riprendere da dove si era interrotto, è sufficiente un comando:
+Un addestramento di 5 cicli che si interrompe al quarto ciclo può essere ripreso. Ogni sessione di addestramento multiplo scrive l'ID del ciclo nel file di cronologia e nel manifest del checkpoint, quindi per riprendere da dove ti eri interrotto, è sufficiente 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
 ```
 
-Il comportamento predefinito di `backprop multi-run` (senza `--resume`) rileva automaticamente una sessione in corso per la stessa directory di output e la continua. Per forzare l'avvio di una nuova sessione, utilizzare `resume_from="off"` (API Python) oppure omettere `--resume` e specificare una nuova directory di output.
-
-Quando una sessione multi-run viene ripresa, il checkpoint più recente per quell'ID di esecuzione viene caricato nel modello, lo stato di fusione SLAO viene ripristinato dalla directory `slao/` accanto al checkpoint e il ciclo di esecuzione continua da `last_completed_run + 1`. Lo stato della voce nella cronologia viene riportato a `running`, quindi `backprop list-runs --status running` mostra la sessione attiva.
+Il comportamento predefinito di `backprop multi-run` (senza `--resume`) rileva automaticamente una sessione in corso nella stessa directory di output e la continua. Per forzare un nuovo inizio, indica una directory di output diversa.
 
-### Monitoraggio degli esperimenti (v1.1.0)
+## Cronologia dell'addestramento
 
-`Trainer` rileva automaticamente i sistemi di monitoraggio degli esperimenti installati (`wandb`, `tensorboard`, `mlflow`) e li integra con i parametri di training di `transformers`. Il valore predefinito `report_to="auto"` utilizza qualsiasi sistema importabile:
+Ogni invocazione di `backprop train` e `backprop multi-run` registra una riga in `<output>/run_history.json`, contenente informazioni sul modello utilizzato, il set di dati, gli iperparametri, lo stato, la perdita finale e la cronologia delle perdite. Puoi visualizzare e analizzare le esecuzioni precedenti:
 
 ```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)
 ```
 
-Per disabilitare esplicitamente queste funzionalità, utilizzare `Trainer(report_to=["wandb"])`, `Trainer(report_to=["tensorboard"])` oppure `Trainer(report_to="none")`. Per MLflow, installare `pip install mlflow`; per TensorBoard, installare `pip install tensorboard`. Il nome dell'esecuzione W&B è `backprop-<run_id_prefix>`, consentendo agli operatori di effettuare ricerche in W&B, nei log e in `run_history.json` utilizzando lo stesso identificatore.
-
-### Cronologia dell'addestramento
+## Monitoraggio degli esperimenti
 
-Ogni invocazione di `backprop train` e `backprop multi-run` registra una riga in `<output>/run_history.json` contenente l'ID dell'esecuzione, il modello, il dataset, gli iperparametri, lo stato, la perdita finale, la cronologia delle perdite e, per le esecuzioni multi-run, la cronologia della fusione SLAO. Per visualizzare le esecuzioni recenti, utilizzare:
+Backpropagate rileva automaticamente i sistemi di monitoraggio degli esperimenti installati (Weights & Biases, TensorBoard, MLflow) e li configura. Se `wandb` è installato e sei autenticato, ogni esecuzione registra automaticamente i dati su W&B con un nome che corrisponde all'ID del ciclo presente nel file di output, in modo da poter utilizzare un unico identificatore per cercare i dati su W&B, nei tuoi log e nel file `run_history.json`.
 
 ```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
 ```
 
-La cronologia delle esecuzioni viene mantenuta tra i processi: la scheda "Runs" nell'interfaccia web è una visualizzazione separata in memoria; la cronologia salvata su disco è la fonte di verità per `list-runs` / `show-run` / `resume`.
+Per disabilitare questa funzionalità, utilizza `Trainer(report_to=["wandb"])`, `Trainer(report_to=["tensorboard"])` oppure `Trainer(report_to="none")`.
 
-### Interfaccia web
+## Interfaccia web
 
-Per avviare l'interfaccia Reflex localmente:
+L'interfaccia web Reflex è opzionale: installala con `pipx install "backpropagate[ui]"` e avviala:
 
 ```bash
 backprop ui --port 7862
 ```
 
-Per rendere disponibile un URL accessibile da Internet, è necessario associare `--share` a `--auth`:
+L'interfaccia utente viene eseguita localmente all'indirizzo `http://localhost:7862`. Per renderla accessibile da altri dispositivi (altri utenti sulla tua rete, un URL pubblico, ecc.), devi combinare le opzioni `--share` (o `--host`) con `--auth`:
 
 ```bash
 backprop ui --share --auth alice:hunter2
 ```
 
-L'esecuzione del comando `backprop ui --share` senza l'opzione `--auth` genera un codice di errore `1` e il messaggio di errore strutturato `[RUNTIME_UI_AUTH_NOT_ENFORCED]`. La motivazione è che l'opzione `--share` rende disponibile un URL pubblico a cui chiunque su Internet può accedere, e senza autenticazione, ciò significa che chiunque può controllare il vostro processo di addestramento. Non è possibile disabilitare questa funzionalità; se non desiderate impostare le credenziali, utilizzate invece il port forwarding tramite SSH: `ssh -L 7860:localhost:7860 <host>`, quindi accedete a `http://localhost:7860` localmente. Consultare il documento [handbook/security.md](site/src/content/docs/handbook/security.md) per una descrizione completa del modello di rischio.
+`backprop ui --share` senza `--auth` genera un errore. Il motivo è che `--share` pubblica un URL a cui chiunque su Internet può accedere, e senza autenticazione ciò significa che chiunque può controllare la tua pipeline di addestramento e leggere il tuo token di Hugging Face. Non è possibile disabilitare questa funzionalità: se non desideri impostare le credenziali, utilizza il port-forwarding SSH.
+
+```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
+```
+
+Consulta il file [handbook/security.md](https://mcp-tool-shop-org.github.io/backpropagate/handbook/security/) per un'analisi completa dei rischi.
 
 Le operazioni di scrittura sul file system dall'interfaccia utente sono limitate a una singola directory:
 
-- Predefinito: `~/.backpropagate/ui-outputs`
-- Override: `BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own`
-- L'override è **validato tramite una lista di esclusione**: i percorsi di sistema/credenziali (`/etc`, `/var`, `~/.ssh`, `~/.aws`, `C:\Windows\System32`, ecc.) vengono rifiutati con l'errore `[UI_OUTPUT_DIR_FORBIDDEN]`.
+- Valore predefinito: `~/.backpropagate/ui-outputs`
+- Per sovrascrivere: impostare `BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own`
+- La sovrascrittura è validata tramite una lista di elementi non consentiti: i percorsi di sistema o di credenziali (`/etc`, `~/.ssh`, `~/.aws`, `C:\Windows\System32`, ecc.) non sono ammessi.
 
-## Supporto per Windows
+## Note sulla piattaforma
 
-Backpropagate è progettato per funzionare su Windows senza modifiche:
+**Requisiti:** Python 3.10+ · GPU CUDA (8GB+ di VRAM) · PyTorch 2.0+
 
-- Pre-tokenizzazione per evitare arresti anomali dovuti all'elaborazione parallela
-- Disabilitazione automatica di xformers per le serie RTX 40/50
-- Impostazioni del dataloader sicure
-- Testato su RTX 5080 (16GB VRAM)
+Python 3.10 raggiungerà la fine del suo ciclo di vita ufficiale nell'ottobre 2026, e Backpropagate prevede di rimuovere il supporto per la versione 3.10 nella versione 1.4. Per le nuove installazioni, è preferibile utilizzare Python 3.11 o 3.12; la versione 3.11 è quella più testata.
 
-## Modelli predefiniti
+Backpropagate gestisce le peculiarità dell'ambiente di runtime durante l'addestramento su diverse piattaforme, ma non può risolvere i problemi che si verificano durante l'installazione. I due problemi più comuni sono:
 
-| Modello | VRAM | Velocità | Qualità |
-|--------|------|-------|---------|
-| Qwen 2.5 7B | ~12GB | Media | Ottima |
-| Qwen 2.5 3B | ~8GB | Veloce | Buona |
-| Llama 3.2 3B | ~8GB | Veloce | Buona |
-| Llama 3.2 1B | ~6GB | Più veloce | Base |
-| Mistral 7B | ~12GB | Media | Buona |
+- **Driver CUDA errato.** PyTorch viene distribuito con una versione binaria per ogni versione di CUDA. Se si sceglie la versione errata, si ottiene silenziosamente una versione di PyTorch che utilizza solo la CPU, e l'addestramento diventa estremamente lento. Utilizzare lo strumento di selezione dei driver all'indirizzo <https://pytorch.org/get-started/locally/> per il proprio driver. Eseguire il comando `nvidia-smi` per visualizzare la versione del driver e di CUDA.
+- **Windows + esportazione GGUF.** L'opzione `[export]` compila `llama-cpp-python` dal codice sorgente, il che richiede Visual Studio Build Tools (componente C++) e CMake.
 
-## Architettura
+**macOS:** L'addestramento con GPU non è supportato (non è disponibile CUDA). È possibile eseguire l'adattatore addestrato su un Mac tramite Ollama, ma la funzione `trainer.train()` genera un errore `DEP_GPU_NOT_AVAILABLE`. Utilizzare una macchina Linux o Windows con CUDA per l'addestramento vero e proprio.
 
+Consultare la [pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/) per una guida completa alla risoluzione dei problemi di installazione, e la [pagina dedicata alla risoluzione dei problemi di CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/) per problemi relativi a driver, VRAM, xformers e bf16 rispetto a fp16.
+
+## CLI
+
+Ogni API Python ha un'interfaccia a riga di comando (CLI) corrispondente:
+
+```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)
-```
 
-L'implementazione di Gradio v1.0 (`ui_gradio_legacy.py` + `theme_gradio_legacy.py`) è stata mantenuta fino alla versione v1.1.x come riferimento ed è stata rimossa nella versione v1.2.0.
+La documentazione completa è disponibile nella [pagina della guida alla CLI](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/), oppure è possibile utilizzare il comando `backprop <sottocomando> --help`.
+
+## Configurazione
+
+Ogni impostazione può essere sovrascritta utilizzando una variabile d'ambiente, preceduta dal prefisso `BACKPROPAGATE_`:
+
+| Variabile | Valore predefinito | Note |
+|---|---|---|
+| `BACKPROPAGATE_LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
+| `BACKPROPAGATE_LOG_JSON` | auto | Forzare i log in formato JSON o nella console |
+| `BACKPROPAGATE_MODEL__NAME` | `Qwen/Qwen2.5-7B-Instruct` | Modello predefinito |
+| `BACKPROPAGATE_TRAINING__LEARNING_RATE` | `2e-4` | Learning rate (tasso di apprendimento) |
+| `BACKPROPAGATE_LORA__R` | `256` | Rango LoRA (valore predefinito nella versione 1.3; utilizzare l'opzione `--lora-preset=fast` per il valore predefinito della versione 1.2.x, che è 16) |
+| `BACKPROPAGATE_UI__OUTPUT_DIR` | `~/.backpropagate/ui-outputs` | Sandbox del file system dell'interfaccia utente |
+
+Le chiavi nidificate utilizzano il doppio underscore (`MODEL__NAME`, non `MODEL_NAME`). La documentazione completa è disponibile nella [pagina delle variabili d'ambiente](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/).
+
+## Modelli predefiniti
+
+| Modello | VRAM | Licenza | Note |
+|---|---|---|---|
+| Qwen-3.5-4B | ~8GB | Apache 2.0 | Valore predefinito consigliato per modelli inferiori a 5 miliardi di parametri. Offre la migliore qualità a questa dimensione. |
+| Phi-4-mini-3.8B | ~8GB | MIT | Ottimo per ragionamento, matematica e programmazione. Licenza rigorosamente "clean". |
+| SmolLM3-3B | ~6GB | Apache 2.0 | Ricetta completamente aperta. Contesto nativo a 64K. |
+| Qwen 2.5 7B | ~12GB | Apache 2.0 | Valore predefinito esistente. Offre la migliore qualità tra i preset legacy da 7 miliardi di parametri. |
+| Qwen 2.5 3B | ~8GB | Qwen-Research | ⚠ licenza per la ricerca: consultare i termini della licenza Qwen prima di un utilizzo commerciale. |
+| Llama 3.2 3B | ~8GB | Llama Community | Un'alternativa valida a Qwen 3B, con alcune limitazioni. |
+| Llama 3.2 1B | ~6GB | Llama Community | Ideale per esperimenti rapidi su schede grafiche di piccole dimensioni. |
+| Mistral 7B | ~12GB | Apache 2.0 | Comparabile a Qwen 7B, con un diverso modello di conversazione. |
+
+Altri modelli potrebbero funzionare, ma solo questi otto sono inclusi nei test automatizzati. Utilizzare l'opzione `--lora-preset=quality` (predefinita) per ottenere un rango di 256 / target all-linear, come indicato da Biderman 2024 + Thinking Machines 2025, oppure l'opzione `--lora-preset=fast` per ottenere il footprint della versione 1.2.x, con un rango di 16 / target q+v, se necessario.
 
 ## Risoluzione dei problemi
 
-Un breve elenco dei problemi più comuni riscontrati all'avvio. L'indice completo è disponibile nella [pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/); ogni codice riportato di seguito è documentato nella sezione [codici di errore](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/).
+Un breve elenco dei problemi più comuni che si verificano durante la prima esecuzione. L'elenco completo è disponibile nella [pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/). Per un'analisi approfondita di driver, VRAM e precisione mista, consultare la [pagina dedicata alla risoluzione dei problemi di CUDA](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting-cuda/).
 
-| Sintomo | Codice | Soluzione |
-|---------|------|-----|
-| La GPU esaurisce la memoria durante l'addestramento. | `RUNTIME_GPU_OOM` | Il meccanismo di ripristino automatico OOM (B-002) riduce automaticamente la dimensione del batch fino a 3 volte. Per disabilitarlo: `Trainer(oom_recovery=False)`. Per forzare una dimensione inferiore: `--batch-size 1`. |
-| Il servizio HF Hub restituisce un errore 401 / "modello non trovato". | `DEP_MODEL_LOAD_FAILED` | Eseguire il comando `huggingface-cli login` e riprovare. In caso di errori di battitura, copiare l'ID esatto da <https://huggingface.co/models>. |
-| Errore nel nome del modello. | `INPUT_VALIDATION_FAILED` o `DEP_MODEL_LOAD_FAILED`. | Verificare l'identificatore `org/name` su <https://huggingface.co/models>. |
+| Sintomo | Codice di errore | Soluzione |
+|---|---|---|
+| La GPU esaurisce la memoria durante l'addestramento. | `RUNTIME_GPU_OOM` | Automatic — Backpropagate dimezza la dimensione del batch e riprova fino a 3 volte. Per disattivare questa funzione: `Trainer(oom_recovery=False)`. Per forzare l'utilizzo di un batch più piccolo: `--batch-size 1`. |
+| HuggingFace restituisce 401 / "modello non trovato" | `DEP_MODEL_LOAD_FAILED` | Eseguire il comando `huggingface-cli login` e riprovare. In caso di errori di battitura, copiare l'ID esatto da <https://huggingface.co/models>. |
 | Rifiuto della connessione `register_with_ollama`. | `DEP_OLLAMA_REGISTRATION_FAILED` | Avviare il demone: `ollama serve`. Installare da <https://ollama.com>. Operazione riprovabile. |
 | Disco pieno durante il salvataggio del checkpoint. | `STATE_CHECKPOINT_INVALID` | In caso di crash, vengono creati file `.partial`. È sicuro eliminarli. Il checkpoint precedente e valido è intatto. |
-| L'addestramento viene interrotto/annullato a causa del surriscaldamento della GPU. | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | B-003: il monitor si interrompe quando viene superata la soglia di temperatura NVML; riprende automaticamente quando la GPU si raffredda. Migliorare il flusso d'aria o ridurre il carico sostenuto. |
-| Richiesta di `backprop ui --share` rifiutata. | `INPUT_AUTH_REQUIRED` | Passare l'argomento `--auth user:password` oppure impostare `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false` per disabilitare la funzione (con un avviso). |
-| "Sovrapposizione" di esecuzioni multiple durante la validazione. | `CONFIG_INVALID` (backend Stage A B-001). | Ridurre il valore di `--samples` al di sotto della dimensione del pool di addestramento, aumentare le dimensioni del dataset o disabilitare la validazione. |
+| Addestramento interrotto a causa del surriscaldamento della GPU | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | Automatic — Backpropagate mette in pausa l'esecuzione quando viene superata la soglia di temperatura e riprende quando la GPU si raffredda. Migliorare il flusso d'aria se il problema si verifica frequentemente. |
+| Richiesta di `backprop ui --share` rifiutata. | `INPUT_AUTH_REQUIRED` | Utilizzare `--auth user:password` oppure utilizzare la reindirizzamento SSH (vedere [Interfaccia Web](#web-ui)). |
 | Esportazione GGUF non riuscita al primo tentativo. | `RUNTIME_GGUF_EXPORT_FAILED` | Eseguire `pip install backpropagate[export]`; su Windows è necessario anche Visual C++ Build Tools + CMake. |
 
 ## Segnalazione di bug
 
-Quando si verifica un errore, Backpropagate stampa una riga `run_started run_id=<uuid>` all'avvio e associa lo stesso ID ai manifest dei checkpoint, alla cronologia delle unioni SLAO e alle righe del log strutturato. Includere l'`run_id` in qualsiasi segnalazione di bug: questo consente all'amministratore di correlare ogni riga del log, ogni checkpoint e ogni unione per quella specifica esecuzione.
+Quando si verifica un errore, Backpropagate stampa una riga all'avvio, simile a `run_started run_id=<uuid>`, e associa lo stesso ID a ogni riga del log, a ogni checkpoint e a ogni voce di Weights & Biases. **Includere il `run_id` in qualsiasi segnalazione di bug**; questo permette al manutentore di correlare tutti gli elementi relativi a quella specifica esecuzione.
 
 Una segnalazione di bug efficace include:
 
-1. **`run_id`** — l'UUID stampato all'avvio (disponibile anche come `TrainingRun.run_id` e `RunResult.run_id`).
-2. **Il codice di errore** — la riga `[CODE_NAME]: message` nella sezione stderr; consultare la [sezione codici di errore](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) per l'elenco completo.
-3. **La riga di comando, opportunamente oscurata.** Nella modalità non dettagliata, la sezione stderr viene oscurata automaticamente (i token Bearer, `sk-*`, `hf_*`, le chiavi AWS, le coppie `password=/token=/api_key=` vengono rimosse); è quindi sicuro copiarla. Per ottenere il traceback completo e non oscurato, eseguire nuovamente il comando con l'opzione `--verbose`, ma esaminare il contenuto prima di pubblicarlo.
-4. **Versioni di Python / PyTorch, modello della GPU, sistema operativo.** Il comando `backprop info` stampa tutte queste informazioni in un'unica volta.
+1. **L'ID di esecuzione (`run_id`)**: l'UUID visualizzato all'avvio. Un singolo UUID consente a un amministratore di correlare ogni riga del log, ogni punto di controllo e ogni voce di Weights & Biases relativa a quella specifica esecuzione.
+2. **Il codice di errore**: la riga `[NOME_CODICE]: messaggio` presente nello standard error (stderr). Consultare [codici di errore](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) per l'elenco dei codici stabili.
+3. **La traccia dello stack (traceback) oscurata.** Lo standard error viene automaticamente oscurato in modalità non dettagliata (i token di autorizzazione, le stringhe `sk-*`, `hf_*`, le chiavi AWS, le coppie `password=` / `token=` / `api_key=` vengono eliminate) – è sicuro copiarla. Per visualizzare la traccia dello stack completa e non oscurata, eseguire nuovamente il comando con `BACKPROPAGATE_DEBUG=1` (o `--verbose`); esaminarla prima di pubblicarla.
+4. **L'output di `backprop info`**. Un singolo comando stampa informazioni su Python / PyTorch / CUDA / modello GPU / VRAM / sistema operativo / moduli aggiuntivi installati: tutto ciò di cui un amministratore ha bisogno per identificare una regressione specifica della piattaforma.
+
+Il [modello per la segnalazione di bug](https://github.com/mcp-tool-shop-org/backpropagate/issues/new?template=bug_report.yml) richiede esplicitamente queste informazioni, quindi la gestione delle segnalazioni è rapida. Domande, suggerimenti o discussioni del tipo "è un comportamento previsto?" devono essere pubblicate nelle [discussioni di GitHub](https://github.com/mcp-tool-shop-org/backpropagate/discussions). Le problematiche di sicurezza devono essere segnalate privatamente tramite il modulo [GitHub Security Advisory](https://github.com/mcp-tool-shop-org/backpropagate/security/advisories/new) – consultare il file [SECURITY.md](SECURITY.md) per le linee guida e i tempi di risposta.
 
 ## Privacy
 
 Tutto l'addestramento avviene localmente sulla GPU. Backpropagate non effettua richieste di rete, ad eccezione del download dei modelli da HuggingFace (che viene avviato dall'utente). Non sono presenti telemetrie né dipendenze dal cloud.
 
-## Valutazione
+## Riferimenti
 
-| Categoria | Punteggio | Note |
-|----------|-------|-------|
-| A. Sicurezza | 6/8 | SECURITY.md, modello affidabile, nessuna informazione sensibile/telemetria, safe_path(). Elementi MCP esclusi. |
-| B. Gestione degli errori | 5/7 | Struttura delle eccezioni (`codice`/`messaggio`/`suggerimento`/`causa`/`riprovabile`) tramite il registro ERROR_CODES; codici di uscita della CLI: 0/1/2/3; nessuna traccia dello stack non elaborata senza l'opzione `--verbose`; correlazione `run_id`; output di errore standard oscurato; controllo di accesso con `--share`+`--auth`. MCP/desktop/vscode esclusi. |
-| C. Documentazione per gli operatori | 4/7 | README, CHANGELOG, LICENZA, --help. Logging/MCP/funzionalità complesse esclusi. |
-| D. Igiene del rilascio | 6/9 | verify.sh, versione=tag, 5 scanner nell'integrazione continua, dependabot, python_requires, build pulito. |
-| E. Identità | 4/4 | Logo, traduzioni, pagina di destinazione, metadati. |
-| **Total** | **25/31** | 14 elementi esclusi con motivazione · `shipcheck audit` supera il 100% · Data dell'audit: 2026-05-21 (la riga B è stata riclassificata dopo la fase B + il lavoro sui codici di uscita della CLI). |
+Le impostazioni predefinite di Backpropagate e la modalità di addestramento multi-run si basano su recenti ricerche. Se si è interessati alle tecniche sottostanti:
 
-Storia del design e a cosa corrisponde ogni elemento: vedere [ROADMAP.md](ROADMAP.md) — tutti gli elementi delle settimane 1-4 sono inclusi nella versione 1.1.0.
+- **Hu et al. 2021.** *LoRA: Low-Rank Adaptation of Large Language Models.* [arXiv:2106.09685](https://arxiv.org/abs/2106.09685) — l'articolo fondamentale che introduce LoRA, la tecnica utilizzata da Backpropagate per addestrare gli adattatori in modo efficiente.
+- **Biderman et al. 2024.** *LoRA Learns Less and Forgets Less.* [arXiv:2405.09673](https://arxiv.org/abs/2405.09673) — evidenze empiriche che dimostrano che LoRA con un rank di 256 e target lineari raggiunge una qualità simile al fine-tuning completo nella maggior parte delle attività di post-addestramento, utilizzando il 67% della potenza di calcolo. Definisce la configurazione LoRA predefinita della versione 1.3 di Backpropagate.
+- **Thinking Machines 2025.** *LoRA Without Regret.* [thinkingmachines.ai/blog/lora](https://thinkingmachines.ai/blog/lora/) — un approfondimento pratico che identifica la correzione del fattore 10 nel learning rate rispetto al fine-tuning completo, necessaria per i rank LoRA elevati.
+- **Kirkpatrick et al. 2017.** *Overcoming catastrophic forgetting in neural networks.* [arXiv:1612.00796](https://arxiv.org/abs/1612.00796) — la caratterizzazione originale del motivo per cui le reti neurali "dimenticano" l'addestramento precedente quando vengono sottoposte a fine-tuning su nuovi dati (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 approccio precedente per utilizzare LoRA per l'apprendimento continuo, che vincola i nuovi adattatori a sottospazi ortogonali.
+- **Yadav et al. 2023.** *TIES-Merging: Resolving Interference When Merging Models.* [arXiv:2306.01708](https://arxiv.org/abs/2306.01708) — una tecnica fondamentale per unire più modelli sottoposti a fine-tuning senza interferenze.
+- **Qiao & Mahdavi 2025.** *Merge before Forget: A Single LoRA Continual Learning via Continual Merging.* [arXiv:2512.23017](https://arxiv.org/abs/2512.23017) — l'algoritmo specifico implementato dal modulo di unione multi-run di Backpropagate. Un preprint di dicembre 2025; Backpropagate è il primo utilizzatore a valle noto di questo articolo.
 
 ## Licenza
 
-MIT — vedere [LICENSE](LICENSE) per i dettagli.
+MIT — vedere [LICENSE](LICENSE).
 
 ---