llm-monitor/PRD.md

LLM Monitor - Product Requirements Document (PRD)

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

---

📋 Indice

1. Executive Summary
2. Vision & Obiettivi
3. Problema & Soluzione
4. Utenti Target
5. Feature Principali
6. Requisiti Tecnici
7. Architettura
8. User Stories
9. Acceptance Criteria
10. Timeline & Roadmap
11. Success Metrics
12. 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:

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

GET /api/v1/models

Recupera elenco di tutti i modelli

Risposta:

{
  "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:

{
  "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:

• Dashboard base con elenco modelli
• API REST con 3 endpoint
• Swagger documentation
• Docker setup
• Web Worker architettura
• 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
• Ollama API
• Web Workers MDN
• localStorage API

Repository

• GitHub: llm-monitor
• Docker Hub: 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