lucasacchi/llm-monitor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
831b41f4872998351c8126c3e265543784b25ebd
llm-monitor/docs/PRD.md
T

683 lines
20 KiB
Markdown
Raw Blame History

# 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
- Pannello dettagli modello su click card
**Behavior:**
- Auto-refresh ogni 30 secondi
- Aggiorna solo elementi cambiati (no full re-render)
- Mostra loading state durante fetch
- Error handling con messaggi chiari
- Durante il refresh lista, chiama `show` per ogni modello e salva i dettagli in cache locale
- Click su card modello apre i dettagli `show` senza page reload
---
### 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"
}
```
#### `GET /api/v1/models/{model_name}/show`
Proxy dell'endpoint Ollama `POST /api/show` per ottenere informazioni estese sul modello
#### `POST /api/v1/models/{model_name}/pull`
Scarica/carica un modello (**disabilitato di default**)
#### `DELETE /api/v1/models/{model_name}`
Elimina un modello (**disabilitato di default**)
#### Policy endpoint R/W
- Gli endpoint `POST/DELETE` sono **non disponibili** per default.
- Si abilitano solo con variabile ambiente `ENABLE_MODEL_RW_API=true`.
- Se non abilitati, gli endpoint non sono esposti in Swagger e rispondono con `404`.
---
### 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 + mappa dettagli `showByModel`
**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 per la sola dashboard (Ollama esterno/remoto)
- 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
Reference in New Issue View Git Blame Copy Permalink