llm-monitor/README.md

# LLM Monitor - Dashboard Ollama

Una dashboard web moderna e intuitiva per monitorare e gestire i modelli LLM caricati in **Ollama**. Visualizza i modelli disponibili, i dettagli dei caricamenti e accedi ai dati via API Ollama direttamente da una web app elegante.

## 🎯 Caratteristiche

- ✨ **Dashboard intuitiva** - Visualizza in tempo reale i modelli caricati in Ollama
- 📊 **Monitoraggio modelli** - Dettagli completi di ogni modello (nome, dimensione, memoria, stato)
- 🔌 **API REST documentata** - Documentazione interattiva con Swagger/OpenAPI
- 🎨 **UI moderna** - Interfaccia elegante realizzata con TailwindCSS
- 🐳 **Docker ready** - Container sempre acceso (until stopped)
- ⚡ **Performance** - Costruito su FastAPI e uVicorn
- 🔐 **Configurazione flessibile** - File `.env` per personalizzazione

## 📋 Requisiti

- **Python** 3.10+
- **Ollama** installato e in esecuzione
- **Docker** (opzionale, per containerizzazione)
- **Docker Compose** (opzionale)

## 🚀 Installazione Rapida

### 1. Clonare il repository

```bash
git clone https://github.com/LucaSacchiNet/llm-monitor.git
cd llm-monitor
```

### 2. Configurare l'ambiente

Copia il file di esempio:

```bash
cp env.example .env
```

Modifica `.env` con i tuoi parametri (vedi [Configurazione](#configurazione)):

```bash
nano .env
```

### 3. Installare le dipendenze

#### Opzione A: Ambiente virtuale (Sviluppo)

```bash
python3 -m venv venv
source venv/bin/activate  # Su Windows: venv\Scripts\activate
pip install -r requirements.txt
```

#### Opzione B: Docker (Produzione)

```bash
docker compose up -d
```

### 4. Avviare l'applicazione

#### Modalità sviluppo

```bash
python3 -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

#### Modalità produzione

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```

## ⚙️ Configurazione

Crea un file `.env` nella root del progetto (copia da `env.example`):

```env
# Ollama Configuration
OLLAMA_HOST=http://localhost:11434
OLLAMA_TIMEOUT=30

# API Configuration
API_HOST=0.0.0.0
API_PORT=8000
API_WORKERS=4

# CORS Configuration
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Logging
LOG_LEVEL=INFO

# Environment
ENVIRONMENT=development
```

### Variabili disponibili

| Variabile | Default | Descrizione |
|-----------|---------|-------------|
| `OLLAMA_HOST` | `http://localhost:11434` | URL della API Ollama |
| `OLLAMA_TIMEOUT` | `30` | Timeout (secondi) per le richieste |
| `API_HOST` | `0.0.0.0` | Host su cui esporre l'API |
| `API_PORT` | `8000` | Porta dell'API |
| `API_WORKERS` | `4` | Worker processes |
| `CORS_ORIGINS` | `http://localhost:3000` | Origini CORS consentite |
| `LOG_LEVEL` | `INFO` | Livello di logging |
| `ENVIRONMENT` | `development` | Ambiente (development/production) |

## 📚 API Swagger

La documentazione interattiva dell'API è disponibile automaticamente:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

### Endpoint principali

#### Recuperare modelli caricati

```bash
GET /api/v1/models
```

**Risposta:**

```json
{
  "models": [
    {
      "name": "llama2",
      "digest": "abc123...",
      "size": 3825922048,
      "modified_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

#### Dettagli di un modello specifico

```bash
GET /api/v1/models/{model_name}
```

#### Health check API Ollama

```bash
GET /api/v1/health
```

**Risposta:**

```json
{
  "status": "healthy",
  "ollama_version": "0.1.0",
  "uptime_seconds": 3600
}
```

### Test API con cURL

```bash
# Ottenere i modelli
curl http://localhost:8000/api/v1/models

# Ottenere info su un modello
curl http://localhost:8000/api/v1/models/llama2

# Health check
curl http://localhost:8000/api/v1/health
```

## 🐳 Docker

### Build dell'immagine

```bash
docker build -t llm-monitor:latest .
```

### Eseguire il container

```bash
docker run -d \
  --name llm-monitor \
  -p 8000:8000 \
  --env-file .env \
  --network host \
  llm-monitor:latest
```

> ⚠️ **Nota**: `--network host` consente al container di accedere a Ollama su localhost

### Docker Compose

Usa il file `docker-compose.yml` fornito:

```bash
# Avviare i servizi
docker compose up -d

# Visualizzare i log
docker compose logs -f llm-monitor

# Fermare i servizi
docker compose down

# Riavviare
docker compose restart llm-monitor
```

### Container sempre acceso

Il container Ollama rimarrà in esecuzione fino al suo arresto manuale:

```bash
# Fermare
docker compose stop ollama
# oppure
docker stop llm-monitor

# Riavviare
docker compose start ollama
# oppure
docker start llm-monitor
```

## 📁 Struttura del Progetto

```
llm-monitor/
├── main.py                 # Entry point dell'applicazione
├── requirements.txt        # Dipendenze Python
├── env.example            # Esempio di configurazione
├── Dockerfile             # Configurazione Docker
├── docker-compose.yml     # Composizione servizi
├── README.md              # Questo file
├── .gitignore
│
├── app/
│   ├── __init__.py
│   ├── config.py          # Configurazione (variabili ambiente)
│   ├── main.py            # Inizializzazione FastAPI
│   │
│   ├── api/
│   │   ├── __init__.py
│   │   ├── models.py      # Endpoint modelli
│   │   ├── health.py      # Endpoint health
│   │   └── v1/
│   │       └── __init__.py
│   │
│   ├── services/
│   │   ├── __init__.py
│   │   ├── ollama.py      # Client Ollama
│   │   └── cache.py       # Cache in-memory (opzionale)
│   │
│   └── web/
│       ├── __init__.py
│       ├── static/        # Assets statici (CSS compilato TailwindCSS)
│       └── templates/     # Template HTML
│
└── tests/
    ├── __init__.py
    ├── test_api.py
    └── test_ollama.py
```

## 🛠️ Sviluppo

### Setup locale

```bash
# Clonare il repo
git clone https://github.com/LucaSacchiNet/llm-monitor.git
cd llm-monitor

# Ambiente virtuale
python3 -m venv venv
source venv/bin/activate

# Installare dipendenze + dev
pip install -r requirements.txt
pip install -r requirements-dev.txt  # black, pytest, flake8, etc.
```

### Comandi utili

```bash
# Formattare codice
black app/ tests/ main.py

# Linting
flake8 app/ tests/ main.py

# Test
pytest tests/ -v

# Test con coverage
pytest tests/ --cov=app

# Hot reload durante sviluppo
uvicorn main:app --reload
```

### Compilare TailwindCSS

```bash
# Installare dipendenze Node (opzionale)
npm install

# Generare CSS in modalità développement
npm run tailwind:dev

# Build per produzione
npm run tailwind:build
```

## 🐛 Troubleshooting

### Errore: "Cannot connect to Ollama"

- Verificare che Ollama sia in esecuzione: `curl http://localhost:11434/api/tags`
- Controllare che l'indirizzo in `.env` sia corretto (`OLLAMA_HOST`)
- Se usi Docker, assicurati che il container abbia accesso a Ollama (vedi [Docker](#docker))

### Errore: "Port 8000 already in use"

```bash
# Cambiare la porta in .env
API_PORT=8001

# Oppure liberare la porta
lsof -ti :8000 | xargs kill -9
```

### Dashboard lenta

- Verificare lo stato di Ollama
- Aumentare `OLLAMA_TIMEOUT` in `.env`
- Controllare i log: `docker compose logs -f llm-monitor`

## 📄 Dipendenze Principali

- **FastAPI** - Framework web moderno
- **uVicorn** - Server ASGI ad alte prestazioni
- **Pydantic** - Validazione dati
- **Requests** - Client HTTP
- **Jinja2** - Template HTML
- **TailwindCSS** - Utility-first CSS

## 📜 Licenza

Questo progetto è distribuito sotto licenza **MIT**. Vedi il file `LICENSE` per dettagli.

## 🤝 Contribuire

Le pull request sono benvenute! Per cambiamenti importanti, apri prima un issue per discutere i cambiamenti proposti.

### Processo di contribuzione

1. Fork il repository
2. Crea un branch (`git checkout -b feature/amazing-feature`)
3. Commit i cambiamenti (`git commit -m 'Add amazing feature'`)
4. Push al branch (`git push origin feature/amazing-feature`)
5. Apri una Pull Request

## 📞 Supporto

Per domande o segnalazioni di bug, apri un **Issue** nel repository.

---

**Fatto con ❤️ da [LucaSacchi.Net](https://lucasacchi.net)**

**Versione**: 1.0.0  
**Ultima modifica**: Aprile 2026  
**Status**: 🟢 In Development