Ecco una proposta di `README.md` strutturata secondo il tuo approccio **Spec-Driven** e orientata alla gestione professionale di un'infrastruttura LLM su **Linux ROCm**.

---

# Ollama Modelfiles - Sacchi Professional Suite

Repository di configurazione per la scuderia di modelli LLM ospitata sul server `llm` (192.168.254.115). La suite è progettata per interagire con **Claude Code Router (CCR)**, bilanciando potenza di calcolo (APU Radeon 780M) e ampiezza di contesto.

## 🧠 Filosofia di Progetto

Tutti i modelli sono configurati seguendo rigorosamente le **3 Regole di Sacchi**:
1. **Safety First**: Parametri di sistema ottimizzati per prevenire crash del driver ROCm.
2. **Little Often**: Modelli piccoli (Gemma 270M/1B) per task rapidi e frequenti.
3. **Double Check**: Validazione delle specifiche e del codice tramite modelli a largo contesto.

### Standard Implementati
* **Approccio Spec-Driven**: Definizione delle specifiche prima della generazione di codice.
* **Test-Driven Development (TDD)**: Priorità alla scrittura dei test.
* **Git Flow**: Messaggi in standard *Conventional Commits*.
* **Documentation**: Changelog mantenuti secondo lo standard *Common Changelog*.

---

## 🏗️ Struttura della Scuderia

| Modello | Ruolo | Context | File Base |
| :--- | :--- | :--- | :--- |
| **Nemotron Cascade 2** | Deep Thinking / Reasoning | 256k | `Modelfile-Nemotron-256k` |
| **GLM-4.7 Flash** | Long Context Analysis | 198k | `Modelfile-GLM-198k` |
| **Gemma 3 4B** | Full Stack Coding / Vision | 128k | `Modelfile-Gemma3-4b-128k` |
| **Gemma 3n e4b** | Main Coder (Balanced) | 32k | `Modelfile-Gemma3n-e4b-32k` |
| **Gemma 3n e2b** | Fast Coding / Debugging | 32k | `Modelfile-Gemma3n-e2b-32k` |
| **Gemma 3 1B** | Automazione / Scripting | 32k | `Modelfile-Gemma3-1B-32k` |
| **Gemma 3 270M** | Utility / Commit Generator | 32k | `Modelfile-Gemma3-270M-32k` |
| **FunctionGemma** | Tool Calling / Utility | 32k | `Modelfile-Gemma-Utility` |

---

## 📂 Organizzazione File

Ogni directory segue lo standard a due file per separare la logica di esecuzione dalla "persona" del modello:
* `Modelfile-*`: Contiene il riferimento `FROM` e i `PARAMETER` tecnici (context, temperature, gpu layers).
* `Modelfile-*.prompt`: Contiene il `SYSTEM PROMPT` specifico con le direttive Sacchi/Spec-Driven.

---

## 🚀 Setup & Installazione

### 1. Requisiti di Sistema (Ollama + ROCm)
Per garantire la stabilità sulla **Radeon 780M**, assicurarsi che l'override di sistema sia attivo in `/etc/systemd/system/ollama.service.d/override.conf`:

```ini
[Service]
Environment="HSA_OVERRIDE_GFX_VERSION=11.0.0"
Environment="HSA_ENABLE_SDMA=0"
Environment="OLLAMA_HOST=0.0.0.0"
```

### 2. Creazione dei Modelli
Per registrare un modello, combinare il file di configurazione con il relativo prompt di sistema:

```bash
# Esempio per Gemma 3 4B
cd gemma3:4b
ollama create gemma3-128k -f Modelfile-Gemma3-4b-128k
# Nota: Il comando aggiungerà il system prompt definito nel file .prompt se concatenato
```

---

## 🛠️ Utilizzo con Claude Code Router (CCR)

Puntare il router sulla VM `devs` all'istanza remota:

```json
"Providers": [
  {
    "name": "ollama-remote",
    "api_base_url": "http://192.168.254.115:11434/v1/chat/completions",
    "api_key": "ollama",
    "models": ["nemotron-pro-256k", "gemma3-128k", "gemma3-utility-32k"]
  }
]
```

---

## 📝 Manutenzione
* **Logs**: Monitorare `journalctl -u ollama -f` per eventuali errori MES o timeout GPU.
* **Updates**: Verificare periodicamente le nuove versioni dei modelli base tramite `ollama pull`.

---
*Creato da Luca Sacchi - Approccio Sistemistico alla Generazione AI.*