# LLM Monitor - Product Requirements Document (PRD)

**Versione:** 1.0.0  
**Data:** Aprile 2024  
**Autore:** Luca Sacchi  
**Status:** Active Development

---

## 📋 Indice

1. [Executive Summary](#executive-summary)
2. [Vision & Obiettivi](#vision--obiettivi)
3. [Problema & Soluzione](#problema--soluzione)
4. [Utenti Target](#utenti-target)
5. [Feature Principali](#feature-principali)
6. [Requisiti Tecnici](#requisiti-tecnici)
7. [Architettura](#architettura)
8. [User Stories](#user-stories)
9. [Acceptance Criteria](#acceptance-criteria)
10. [Timeline & Roadmap](#timeline--roadmap)
11. [Success Metrics](#success-metrics)
12. [Constraints & Assumptions](#constraints--assumptions)

---

## 🎯 Executive Summary

**LLM Monitor** è una **dashboard web moderna** per il monitoraggio in tempo reale dei modelli LLM caricati in **Ollama**. L'applicazione fornisce una visualizzazione intuitiva dello stato dei modelli, delle risorse utilizzate e dell'accesso ai dati via API REST documentata con Swagger/OpenAPI.

### Highlights
- ✅ Dashboard reattiva senza page reload
- ✅ Web Worker per sincronizzazione dati in background
- ✅ localStorage per cache locale e offline support
- ✅ API REST completamente documentata
- ✅ Containerizzata con Docker
- ✅ Architettura server-client moderna

---

## 🚀 Vision & Obiettivi

### Vision
Fornire ai developer e ai DevOps una **visibilità completa e in tempo reale** dei modelli LLM disponibili in Ollama, eliminando la necessità di comandi CLI per il monitoraggio.

### Obiettivi Primari
1. **Visualizzare modelli** caricati in Ollama senza comandi CLI
2. **Monitorare risorse** (dimensione, memoria, stato)
3. **Accedere all'API** via dashboard intuitiva
4. **Documentare API** con Swagger per integrazioni esterne
5. **Deployare facilmente** con Docker/Docker Compose
6. **Aggiornamenti in tempo reale** senza page reload

### Obiettivi Secondari
1. Supporto offline via localStorage
2. Performance ottimale con Web Workers
3. UI moderna e responsive
4. Facilità di installazione e configurazione

---

## 🔍 Problema & Soluzione

### Problema
Attualmente, per verificare i modelli LLM in Ollama, è necessario:
- Usare comandi CLI (`ollama list`)
- Fare chiamate API manuali con curl/Postman
- Non c'è una dashboard visuale dedicata
- Difficile monitoraggio per non-developer

### Soluzione Proposta
**LLM Monitor** fornisce:
- ✅ Dashboard web intuitiva e moderna
- ✅ Aggiornamenti automatici ogni 30 secondi
- ✅ Nessun page reload grazie ai Web Workers
- ✅ API documentata e testabile direttamente
- ✅ Deployment semplice con Docker

---

## 👥 Utenti Target

### Primary Users
1. **DevOps Engineers** - Monitorare modelli in produzione
2. **ML Engineers** - Verificare disponibilità modelli
3. **Developers** - Integrazioni via API

### Secondary Users
1. **System Administrators** - Overview dell'infrastruttura
2. **Project Managers** - Status modelli disponibili

### Use Cases

#### UC1: Verificare Modelli Caricati
- **Actor:** Developer
- **Goal:** Vedere quali modelli sono disponibili
- **Flow:** Apri dashboard → visualizza elenco modelli con dettagli
- **Benefit:** Non usare CLI, visione immediata

#### UC2: Monitorare Spazio Disco
- **Actor:** DevOps
- **Goal:** Tracciare consumo spazio dei modelli
- **Flow:** Dashboard → visualizza spazio totale e per modello
- **Benefit:** Pianificare cleanup e capacity planning

#### UC3: Integrare via API
- **Actor:** Developer
- **Goal:** Automatizzare script che consumano dati modelli
- **Flow:** Consulta Swagger → crea script che chiama endpoint API
- **Benefit:** Automazione e integrazione con altri sistemi

#### UC4: Offline Mode
- **Actor:** Developer (senza connessione)
- **Goal:** Accedere ai dati modelli salvati
- **Flow:** localStorage fornisce ultimo stato noto
- **Benefit:** Accesso parziale anche offline

---

## ⚡ Feature Principali

### 1. Dashboard Principale
**Descrizione:** Homepage con overview dei modelli

**Componenti:**
- Header con logo e status Ollama
- Stat cards: Modelli caricati, Spazio totale, Status
- Lista modelli con:
  - Nome modello
  - Dimensione
  - Data ultimo aggiornamento
  - Digest (hash univoco)
- Pulsante refresh manuale

**Behavior:**
- Auto-refresh ogni 30 secondi
- Aggiorna solo elementi cambiati (no full re-render)
- Mostra loading state durante fetch
- Error handling con messaggi chiari

---

### 2. API REST Documentata

**Endpoints:**

#### `GET /api/v1/health`
Verifica lo stato dell'API e di Ollama

**Risposta:**
```json
{
  "status": "healthy",
  "ollama_status": "online",
  "timestamp": "2024-04-15T10:30:00Z"
}
```

#### `GET /api/v1/models`
Recupera elenco di tutti i modelli

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

#### `GET /api/v1/models/{model_name}`
Dettagli di un modello specifico

**Risposta:**
```json
{
  "name": "llama2",
  "digest": "abc123...",
  "size": 3825922048,
  "modified_at": "2024-04-15T10:30:00Z"
}
```

#### `POST /api/v1/models/{model_name}/pull`
Scarica/carica un modello

#### `DELETE /api/v1/models/{model_name}`
Elimina un modello

---

### 3. Web Worker per Sincronizzazione
**Descrizione:** Thread separato per aggiornamenti dati

**Feature:**
- Esegue richieste HTTP senza bloccare UI
- Aggiorna localStorage ogni 30 secondi
- Notifica main thread con nuovi dati
- Fallback per browser senza Web Worker support

**Vantaggi:**
- UI sempre responsiva (60 FPS)
- Niente lag durante fetch
- Scalabilità migliore

---

### 4. LocalStorage Persistence
**Descrizione:** Cache locale dei dati

**Dati Salvati:**
- `llm_monitor_health` - Status health
- `llm_monitor_models` - Elenco modelli

**Benefit:**
- Offline support
- Caricamento istantaneo
- Ripristino ultimo stato noto

---

### 5. Swagger/OpenAPI Documentation
**Descrizione:** Documentazione interattiva API

**URL:**
- Swagger UI: `/docs`
- ReDoc: `/redoc`

**Feature:**
- Testa endpoint direttamente
- Visualizza schemi
- Genera client code (curl, Python, JS, ecc.)

---

### 6. Docker Support
**Descrizione:** Containerizzazione dell'applicazione

**Componenti:**
- Dockerfile multi-stage ottimizzato
- docker-compose.yml con Ollama incluso
- Health checks configurati
- Sempre acceso fino all'arresto manuale

---

## 🏗️ Requisiti Tecnici

### Backend
- **Linguaggio:** Python 3.10+
- **Framework:** FastAPI
- **Server:** uVicorn
- **Validation:** Pydantic
- **HTTP Client:** requests/httpx

### Frontend
- **HTML5** - Template base
- **CSS:** TailwindCSS (utility-first)
- **JavaScript:** Vanilla JS (no frameworks)
- **Web APIs:**
  - Fetch API per HTTP
  - Web Workers per threading
  - localStorage per persistence

### DevOps
- **Container:** Docker
- **Orchestration:** Docker Compose
- **Network:** HTTP/HTTPS

### Database
- Nessuno (stateless)
- localStorage nel browser (client-side only)

---

## 🏛️ Architettura

### Componenti Principali

```
┌─────────────────────────────────────────────────────┐
│                    Client (Browser)                  │
│  ┌────────────────────────────────────────────────┐ │
│  │  index.html + app.js (Main Thread)             │ │
│  │  - Renderizza UI                               │ │
│  │  - Legge localStorage                          │ │
│  │  - Aggiorna DOM granularmente                  │ │
│  └────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────┐ │
│  │  data-sync.worker.js (Web Worker Thread)       │ │
│  │  - Fetch /api/v1/health                        │ │
│  │  - Fetch /api/v1/models                        │ │
│  │  - Aggiorna localStorage                       │ │
│  │  - Comunica con main thread                    │ │
│  └────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────┘
                         │ HTTP REST API
                         │
┌────────────────────────▼────────────────────────────┐
│              FastAPI Server (Python)                │
│  ┌────────────────────────────────────────────────┐ │
│  │  main.py (Entry Point)                         │ │
│  │  - CORS middleware                             │ │
│  │  - Route setup                                 │ │
│  └────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────┐ │
│  │  app/api/ (Endpoints)                          │ │
│  │  - health.py                                   │ │
│  │  - models.py                                   │ │
│  └────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────┐ │
│  │  app/services/ (Business Logic)                │ │
│  │  - ollama.py (OllamaClient)                    │ │
│  └────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────┘
                         │ HTTP API
                         │
┌────────────────────────▼────────────────────────────┐
│           Ollama Server (LLM Models)                │
│  - API Port: 11434                                  │
│  - Gestisce modelli LLM                             │
│  - Endpoint: /api/tags                              │
└─────────────────────────────────────────────────────┘
```

### Data Flow

1. **Inizializzazione:**
   - Main thread carica localStorage
   - Renderizza UI con dati cached
   - Avvia Web Worker

2. **Sincronizzazione Periodica (ogni 30s):**
   - Worker fetch `/api/v1/health`
   - Worker fetch `/api/v1/models`
   - Worker aggiorna localStorage
   - Worker invia messaggio a main thread

3. **Aggiornamento UI:**
   - Main thread riceve messaggio dal Worker
   - Confronta dati vecchi vs nuovi
   - Aggiorna solo elementi cambiati

4. **Refresh Manuale:**
   - Utente clicca pulsante 🔄
   - Main thread chiama `worker.postMessage({ type: "SYNC_NOW" })`
   - Worker esegue sincronizzazione immediata

---

## 👤 User Stories

### US1: Visualizzare Modelli Disponibili
```
Come: Developer
Voglio: Vedere lista di modelli caricati in Ollama
Affinché: Sapere quali modelli sono disponibili
  
Acceptance Criteria:
- Dashboard mostra elenco modelli
- Per ogni modello: nome, dimensione, data aggiornamento
- Totale modelli visualizzato in stat card
- Dati aggiornati ogni 30 secondi
```

### US2: Monitorare Consumo Spazio
```
Come: DevOps Engineer
Voglio: Verificare quanto spazio occupano i modelli
Affinché: Pianificare capacity planning e cleanup

Acceptance Criteria:
- Stat card mostra spazio totale
- Ogni modello mostra dimensione
- Formato leggibile (GB, MB, etc)
- Aggiornamenti automatici
```

### US3: Verificare Status Ollama
```
Come: System Admin
Voglio: Sapere se Ollama è online
Affinché: Identificare problemi rapidamente

Acceptance Criteria:
- Status indicator nel header (verde/rosso)
- Testo descrittivo ("Online/Offline")
- Health check ogni 30 secondi
```

### US4: Accedere alla API Documentata
```
Come: Developer
Voglio: Consultare documentazione API con esempi
Affinché: Integrare i dati in miei script/app

Acceptance Criteria:
- Swagger UI disponibile su /docs
- ReDoc disponibile su /redoc
- Tutti gli endpoint documentati
- Possibile testare endpoint dal browser
```

### US5: Usare Dashboard Offline
```
Come: Developer
Voglio: Visualizzare ultimi dati anche offline
Affinché: Accedere all'info anche senza connessione

Acceptance Criteria:
- localStorage persiste dati
- Dashboard carica senza server
- Mostra timestamp ultimo aggiornamento
- Warning se dati non aggiornati
```

### US6: Refresh Manuale
```
Come: User
Voglio: Aggiornare i dati immediatamente
Affinché: Ottenere le informazioni più recenti

Acceptance Criteria:
- Pulsante 🔄 presente nella dashboard
- Clicco aggiorna immediatamente i dati
- Loading state durante fetch
- Nessun page reload
```

---

## ✅ Acceptance Criteria

### Funzionalità

| # | Feature | Accettazione |
|---|---------|--------------|
| 1 | Dashboard carica modelli | ✅ Elenco visibile entro 2 secondi |
| 2 | Auto-refresh ogni 30s | ✅ Nessun page reload, solo DOM update |
| 3 | Status Ollama | ✅ Indicatore verde/rosso corretto |
| 4 | localStorage sincronizzato | ✅ Dati persistenti tra session |
| 5 | Web Worker attivo | ✅ Main thread mai bloccato |
| 6 | API Swagger disponibile | ✅ Endpoint testabili su /docs |
| 7 | Docker container | ✅ Avvia e rimane acceso |
| 8 | Offline mode | ✅ Carica con localStorage |

### Performance

| # | Metrica | Target |
|---|---------|--------|
| 1 | FCP (First Contentful Paint) | < 1s |
| 2 | LCP (Largest Contentful Paint) | < 2s |
| 3 | TTI (Time to Interactive) | < 3s |
| 4 | API response time | < 200ms |
| 5 | Dashboard refresh FPS | 60 FPS |
| 6 | Memory usage | < 50MB |

### Compatibilità Browser

| Browser | Versione Minima | Status |
|---------|-----------------|--------|
| Chrome | 70+ | ✅ Supportato |
| Firefox | 65+ | ✅ Supportato |
| Safari | 12+ | ✅ Supportato |
| Edge | 79+ | ✅ Supportato |
| Opera | 57+ | ✅ Supportato |
| IE11 | - | ❌ Non supportato (no Web Workers) |

---

## 📅 Timeline & Roadmap

### Phase 1: MVP (In Development - Completato ✅)
**Durata:** 2 settimane
**Feature:**
- [x] Dashboard base con elenco modelli
- [x] API REST con 3 endpoint
- [x] Swagger documentation
- [x] Docker setup
- [x] Web Worker architettura
- [x] localStorage integration

**Release:** v1.0.0

---

### Phase 2: Enhancement (Pianificato 🔄)
**Durata:** 2 settimane
**Feature:**
- [ ] Statistiche storiche (grafici)
- [ ] Ricerca e filtri modelli
- [ ] Dark/Light theme toggle
- [ ] Configurazione refresh rate
- [ ] Export dati (CSV/JSON)
- [ ] Notifiche cambio status

**Release:** v1.1.0

---

### Phase 3: Advanced (Futuro 🚀)
**Durata:** 3+ settimane
**Feature:**
- [ ] Multi-tenant support
- [ ] Authentication & Authorization
- [ ] User preferences storage
- [ ] Service Worker per PWA
- [ ] Real-time updates (WebSocket)
- [ ] Model versioning
- [ ] Pull/Delete confirmation modal
- [ ] Advanced error handling

**Release:** v2.0.0

---

### Phase 4: Production (Futuro 🏆)
**Durata:** Ongoing
**Feature:**
- [ ] Monitoring & Alerting
- [ ] Analytics dashboard
- [ ] Performance optimization
- [ ] Load testing & benchmarks
- [ ] Security audit
- [ ] GDPR compliance

**Release:** v2.1.0+

---

## 📊 Success Metrics

### Technical Metrics

| Metrica | Target | Misura |
|---------|--------|--------|
| Uptime | 99%+ | Monitoring |
| API latency | < 200ms | New Relic/DataDog |
| Error rate | < 0.1% | Logs |
| Test coverage | 80%+ | pytest coverage |
| Bundle size | < 100KB | webpack-bundle-analyzer |

### Business Metrics

| Metrica | Target | Misura |
|---------|--------|--------|
| Time to load | < 2s | Lighthouse |
| Page interactions/sec | 100+ | App metrics |
| User satisfaction | 4.5/5 | Feedback form |
| DevOps adoption | 70%+ | Usage analytics |
| Automation enabled | 50%+ | Script integrations |

### User Engagement

| Metrica | Target | Misura |
|---------|--------|--------|
| Monthly active users | 100+ | Analytics |
| Dashboard views/month | 1000+ | Google Analytics |
| API calls/day | 500+ | API logs |
| Feature usage rate | 80%+ | Telemetry |

---

## 🚫 Constraints & Assumptions

### Constraints

#### Tecnici
- Ollama deve essere in esecuzione (hard requirement)
- Python 3.10+ necessario
- Docker richiesto per containerizzazione
- Browser moderno necessario (Web Workers)

#### Organizzativi
- Team: 1-2 developer
- Budget: Open source (free)
- Timeline: Sprint 2 settimane

#### User
- Conoscenza base di Docker
- Accesso locale a Ollama
- Browser moderno

### Assumptions

#### Prodotto
- Ollama API rimane stabile
- Modelli LLM sono relativamente statici (cambiano meno di 24h)
- Refresh ogni 30s è adeguato

#### Tecnico
- Web Workers supportati dai browser target
- localStorage disponibile (non private mode)
- CORS enabled tra client e server

#### Market
- Ollama diventerà standard per LLM locali
- Interesse crescente in monitoring tools
- Community contribuirà improvement

---

## 📝 Note Implementative

### Dependencies
```
fastapi==0.104.1
uvicorn==0.24.0
pydantic==2.5.0
requests==2.31.0
jinja2==3.1.2
```

### Dev Dependencies
```
pytest==7.4.3
black==23.12.0
flake8==6.1.0
mypy==1.7.1
```

### File Structure
```
llm-monitor/
├── main.py                 # FastAPI entry point
├── app/
│   ├── config.py          # Configuration
│   ├── api/               # Endpoints
│   ├── services/          # Business logic
│   └── web/               # Frontend (HTML, JS, CSS)
├── tests/                 # Test suite
├── Dockerfile             # Container
└── docker-compose.yml     # Orchestration
```

---

## 🔗 Riferimenti

### Documentazione Esterna
- [FastAPI Docs](https://fastapi.tiangolo.com/)
- [Ollama API](https://github.com/ollama/ollama/blob/main/docs/api.md)
- [Web Workers MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API)
- [localStorage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)

### Repository
- [GitHub: llm-monitor](https://github.com/lucasacchiNet/llm-monitor)
- [Docker Hub: llm-monitor](https://hub.docker.com/r/lucasacchi/llm-monitor)

---

## ✍️ Changelog PRD

| Data | Versione | Autore | Cambiamenti |
|------|----------|--------|------------|
| 2024-04-24 | 1.0 | Luca Sacchi | Documento iniziale |
| 2024-04-25 | 1.1 | - | TBD |

---

**Documento approvato:** ✅  
**Revisore:** Product Team  
**Ultimo aggiornamento:** Aprile 2024  
**Prossima review:** Giugno 2024