@mcptoolshop/backpropagate 1.1.1 → 1.3.0

package/README.it.md

@@ -10,144 +10,152 @@
   <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 modelli linguistici di grandi dimensioni (LLM) senza interfaccia grafica in 3 righe di codice. Impostazioni predefinite intelligenti, gestione automatica delle dimensioni 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 fusione 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](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 ollama register ./output/lora --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
 
-Il repository include un piccolo file `examples/quickstart.jsonl` (5 esempi in formato ShareGPT) in modo che lo snippet di codice precedente possa essere eseguito completamente su un'installazione pulita. Per il tuo addestramento, consulta la sezione [Formato del dataset](#dataset-format) qui sotto.
+```bash
+# Recommended: isolated Python install (no conflicts with system Python or other projects)
+pipx install backpropagate
+
+# Or via uv (faster install, same isolation)
+uv tool install backpropagate
 
-### Percorso senza codice: Interfaccia utente
+# 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 selezionare un file JSONL, scegliere 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 utente](#web-ui) qui sotto per le opzioni 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 in formato JSONL deve contenere un esempio per riga. Il formato più semplice è la conversazione 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 il file `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 l'errore?
+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 | Dimensioni dei batch automatiche, monitoraggio della GPU |
-| L'esportazione del modello è confusa | 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 grafica 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 semplificata**: 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. |
+| 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 | Sperimentale nella versione 1.4. Il modello più grande che puoi utilizzare su una scheda da 16 GB. |
 
-## Installazione
+Per i modelli da 3 miliardi di parametri e inferiori, l'affinamento completo (non solo LoRA) è possibile su 16 GB ed è previsto come opzione `mode="full"` nella versione 1.4. Per i modelli da 7 miliardi di parametri o superiori, l'affinamento completo richiede una GPU da 24 GB o superiore: considera un'istanza cloud A100 oppure utilizza LoRA, che, secondo recenti ricerche, offre una qualità equivalente all'affinamento completo nella maggior parte delle attività di post-addestramento (vedi la sezione "cosa Backpropagate non è" per le citazioni).
 
-```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
-```
+## Cosa Backpropagate NON è
 
-| Extra | Descrizione | Dipendenze |
-|-------|-------------|--------------|
-| `unsloth` | Addestramento 2 volte più veloce, 50% in meno di VRAM | unsloth |
-| `ui` | Interfaccia utente 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 |
-| `observability` | Tracciamento OpenTelemetry | opentelemetry-api, opentelemetry-sdk |
-| `logging` | Logging strutturato | structlog |
-| `security` | Autenticazione JWT + generazione di token | PyJWT, cryptography |
-| `production` | unsloth + ui + validation + logging + security | (bundle) |
+Essere onesti aiuta tutti. Backpropagate non fa queste cose, e cercare di farlo sarebbe un'esperienza peggiore rispetto a utilizzare lo strumento giusto:
 
-**Requisiti:** Python 3.10+ · GPU CUDA (8GB+ di VRAM) · PyTorch 2.0+
+- **Ottimizzazione completa dei parametri per modelli da 7B+** — Backpropagate utilizza LoRA / QLoRA, che addestra un piccolo adattatore invece di aggiornare ogni peso. Per i modelli da 7B e superiori, l'ottimizzazione completa richiede 24GB+ di memoria GPU e non è possibile eseguirla su una scheda consumer da 16GB. Per i modelli da 3B e inferiori, l'ottimizzazione completa è fattibile su 16GB; un'opzione `mode="full"` è prevista per la versione 1.4. In sintesi: ricerche recenti ([Biderman 2024](https://arxiv.org/abs/2405.09673), [Thinking Machines 2025](https://thinkingmachines.ai/blog/lora/)) mostrano che LoRA, con la configurazione corretta, raggiunge una qualità simile all'ottimizzazione completa nella maggior parte delle attività di post-addestramento (seguimento delle istruzioni, adattamento al dominio, personalità/stile) utilizzando il 67% delle risorse di calcolo; quindi, per il tipo di lavoro che la maggior parte degli utenti desidera, non si perde nulla utilizzando LoRA. Se è realmente necessario eseguire un'ottimizzazione completa di un modello da 7B+, utilizzare direttamente `transformers.Trainer` di HuggingFace su una scheda da 24GB+.
+- **DPO / PPO / GRPO / ottimizzazione delle preferenze** — Backpropagate esegue solo l'ottimizzazione supervisionata in una singola fase. Per l'apprendimento basato sulle preferenze, utilizzare direttamente TRL o LLaMA-Factory.
+- **Addestramento multi-nodo** — 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 supportate** — 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.
 
-### Prerequisiti della piattaforma
+Se avete bisogno di queste funzionalità, utilizzate una delle librerie elencate sopra. Sono più adatte per questo scopo.
 
-Backpropagate gestisce le problematiche specifiche dell'ambiente di esecuzione (multiprocessing, xformers su RTX 40/50, worker del dataloader su Windows). **Non** gestisce i problemi relativi all'installazione sulla piattaforma; risolvete prima quelli:
+## Cosa offre Backpropagate:
 
-- **Versione del toolkit CUDA.** PyTorch viene rilasciato in base alla versione di CUDA; scegliere la versione sbagliata installa silenziosamente solo la versione per CPU. Utilizzate lo strumento di selezione all'indirizzo <https://pytorch.org/get-started/locally/> per ottenere il comando `pip install torch ...` corretto per il vostro driver. Eseguite `nvidia-smi` per visualizzare la versione del vostro driver/CUDA.
-- **Windows.** Sono necessari Visual Studio Build Tools (C++) e CMake per l'extra `[export]` (costruzione di `llama-cpp-python` da sorgente). Il pacchetto `bitsandbytes` è ora disponibile nativamente per Windows (>= 0.43); le guide più vecchie 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 esportato tramite Ollama, ma `trainer.train()` genera un'eccezione `DEP_GPU_NOT_AVAILABLE`. Utilizzate una macchina con CUDA per l'addestramento.
-- **Linux.** La maggior parte delle distribuzioni funziona immediatamente. Se state utilizzando la versione binaria distribuita tramite PyPI, tenete presente che la build 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); installate prima la versione CUDA corrispondente da pytorch.org.
+Quattro cose, in un'unica installazione:
 
-Per la risoluzione dei problemi di installazione, consultate [la pagina della guida alla risoluzione dei problemi](https://mcp-tool-shop-org.github.io/backpropagate/handbook/troubleshooting/).
+**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.
 
-## Configurazione
+**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.
 
-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 installato l'extra `[validation]`.
+**3. Progettato per l'esecuzione in background.**
+L'addestramento richiede ore. Non volete doverlo controllare costantemente. Backpropagate è progettato per essere lasciato in esecuzione:
 
-Impostazioni comuni (consultate [il riferimento completo delle variabili d'ambiente](https://mcp-tool-shop-org.github.io/backpropagate/handbook/env-vars/) per tutti i dettagli):
+- 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/).
 
-| 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` | Quando 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 filesystem 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) |
+**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.
 
-Le chiavi nidificate utilizzano il doppio underscore come delimitatore (convenzione `env_nested_delimiter` di Pydantic).
+## Guida rapida
 
-## Utilizzo
+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:
 
-### Addestramento di base
+```bash
+pipx install "backpropagate[standard]"
 
-```python
+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."}]}
 ```
 
-`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` quantizzato; abbiamo modificato il valore predefinito per utilizzare i pesi ufficiali di Qwen per una maggiore affidabilità ([CHANGELOG v0.1.3](CHANGELOG.md)). È possibile utilizzare entrambi i modelli.
+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
+```
 
-### Addestramento SLAO multi-esecuzione
+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 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
@@ -159,198 +167,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
 ```
 
-Consultate [il riferimento della CLI](https://mcp-tool-shop-org.github.io/backpropagate/handbook/cli-reference/) per tutti i sottocomandi e i flag, oppure eseguite `backprop <sottocomando> --help`.
-
-### Ripresa da checkpoint (v1.1.0)
+## Ripresa da un checkpoint
 
-Un'esecuzione multi-run che si interrompe al run 4 è ora recuperabile. Ogni sessione multi-run scrive il suo `run_id` sia in `run_history.json` che nel manifest delle checkpoint salvate 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 un'esecuzione in corso per la stessa directory di output e la continua. Per forzare una nuova sessione, utilizzare `resume_from="off"` (API Python) oppure omettere `--resume` e avviare in una nuova directory di output.
+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.
 
-Quando una multi-run viene ripresa, l'ultima checkpoint per quel `run_id` viene caricata nel modello, lo stato del merger SLAO viene ripristinato dalla directory `slao/` accanto alla 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 in corso.
+## Cronologia dell'addestramento
 
-### Tracciamento degli esperimenti (v1.1.0)
-
-`Trainer` rileva automaticamente i tracker di esperimenti installati (`wandb`, `tensorboard`, `mlflow`) e li integra con i `transformers.TrainingArguments` sottostanti. Il valore predefinito `report_to="auto"` utilizza qualsiasi libreria 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, 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>`, quindi un operatore può utilizzare `grep` su W&B, i nostri log e `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` con il `run_id`, il modello, il dataset, gli iperparametri, lo stato, la perdita finale, la cronologia delle perdite e, per le multi-run, la cronologia del merger SLAO. Per visualizzare le esecuzioni recenti:
+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 anche 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
 
-Avviare l'interfaccia Reflex localmente:
+L'interfaccia web Reflex è opzionale: installala con `pipx install "backpropagate[ui]"` e avviala:
 
 ```bash
 backprop ui --port 7862
 ```
 
-Per esporre 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
 ```
 
-`backprop ui --share` senza `--auth` termina con il codice `1` e l'errore strutturato `[INPUT_AUTH_REQUIRED]`. La motivazione è che `--share` pubblica un URL `*.gradio.live` che chiunque su Internet può raggiungere, e senza autenticazione, ciò significa che chiunque può controllare la pipeline di addestramento.
+`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.
 
-Per disabilitare esplicitamente (ad esempio, in un ambiente di sviluppo interno), impostare la variabile d'ambiente `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false`. Verrà visualizzato un avviso ben visibile ad ogni avvio, e c'è un periodo di grazia di 5 secondi prima che l'interfaccia utente non autenticata venga caricata, quindi è possibile premere `Ctrl-C` se qualcosa non sembra corretto.
+```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
+```
 
-Le scritture sul file system dall'interfaccia utente sono limitate a una singola directory:
+Consulta il file [handbook/security.md](https://mcp-tool-shop-org.github.io/backpropagate/handbook/security/) per un'analisi completa dei rischi.
 
-- 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 `[UI_OUTPUT_DIR_FORBIDDEN]`.
+Le operazioni di scrittura sul file system dall'interfaccia utente sono limitate a una singola directory:
 
-## Supporto per Windows
+- 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.
 
-Backpropagate è progettato per funzionare su Windows senza modifiche:
+## Note sulla piattaforma
 
-- Pre-tokenizzazione per evitare crash dovuti all'uso di multiprocessing
-- Disabilitazione automatica di xformers per le serie RTX 40/50
-- Impostazioni del dataloader sicure
-- Testato su RTX 5080 (16GB di VRAM)
+**Requisiti:** Python 3.10+ · GPU CUDA (8GB+ di VRAM) · PyTorch 2.0+
 
-## Modelli predefiniti
+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.
 
-| 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 | Velocissimo | Base |
-| Mistral 7B | ~12GB | Media | Buona |
+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:
 
-## Architettura
+- **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.
 
+**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)
-├── ui_gradio_legacy.py  # DEPRECATED — preserved as v1.0 reference; removed in v1.2
-└── theme_gradio_legacy.py  # DEPRECATED — same
-```
+
+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 indice degli errori più comuni che si verificano all'avvio. L'indice completo è disponibile nella [pagina del manuale di 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/).
-
-| 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 `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>. |
-| Impossibile connettersi a `register_with_ollama`. | `DEP_OLLAMA_REGISTRATION_FAILED` | Avviare il demone: `ollama serve`. Installare da <https://ollama.com>. Operazione riprovare. |
-| Disco pieno durante il salvataggio del checkpoint. | `STATE_CHECKPOINT_INVALID` | In caso di crash, le scritture atomiche lasciano una directory `.partial` che può essere eliminata in sicurezza. Il checkpoint valido precedente è intatto. |
-| L'addestramento viene interrotto/annullato a causa del surriscaldamento della GPU. | `RUNTIME_GPU_TEMPERATURE_CRITICAL` | B-003: il monitor si interrompe quando si supera la soglia di temperatura NVML; riprende automaticamente quando la GPU si raffredda. Migliorare il flusso d'aria o ridurre il carico sostenuto. |
-| `backprop ui --share` viene rifiutato. | `INPUT_AUTH_REQUIRED` | Fornire `--auth user:password` oppure impostare `BACKPROPAGATE_SECURITY__REQUIRE_AUTH_FOR_SHARE=false` per disabilitare questa funzionalità (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. |
+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 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. |
+| 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 di unione 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` nell'output di errore standard (stderr); consultare la [sezione dei codici di errore](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) per l'elenco completo.
-3. **La riga di comando senza informazioni sensibili.** L'output di errore standard (stderr) viene automaticamente oscurato in modalità non dettagliata (i token di autorizzazione, le stringhe che iniziano con `sk-*`, `hf_*`, le chiavi AWS, le coppie `password=/token=/api_key=` vengono rimosse) e può essere incollata in sicurezza. Per ottenere la traccia completa e non oscurata, eseguire nuovamente il comando con l'opzione `--verbose`, ma esaminare l'output 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. **Il `run_id`**: l'UUID stampato all'avvio.
+2. **Il codice di errore**: la riga `[CODE_NAME]: message` presente nell'output di errore standard (stderr). Consultare [codici di errore](https://mcp-tool-shop-org.github.io/backpropagate/handbook/error-codes/) per l'elenco completo.
+3. **La riga di comando mascherata.** L'output di errore standard viene automaticamente mascherato (i token di autorizzazione, le stringhe `sk-*`, `hf_*`, le chiavi AWS, le coppie `password=` / `token=` vengono eliminate) e può essere tranquillamente incollata. Per visualizzare la traccia completa e non mascherata, eseguire nuovamente il comando con l'opzione `--verbose`, ma esaminarla prima di pubblicarla.
+4. **Versioni di Python / PyTorch, modello della GPU, sistema operativo.** `backprop info` stampa tutte queste informazioni in un'unica volta.
+
+Domande, suggerimenti o discussioni su "se questo è un comportamento previsto" devono essere poste nella sezione [GitHub Discussions](https://github.com/mcp-tool-shop-org/backpropagate/discussions). Le segnalazioni di problemi di sicurezza devono essere inviate privatamente tramite il modulo [GitHub Security Advisory](https://github.com/mcp-tool-shop-org/backpropagate/security/advisories/new) e consultare il file [SECURITY.md](SECURITY.md) per le relative policy.
 
 ## 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(). Gli elementi MCP sono 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 e 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).
 
 ---