From 831b41f4872998351c8126c3e265543784b25ebd Mon Sep 17 00:00:00 2001 From: Luca Sacchi Ricciardi Date: Sat, 25 Apr 2026 18:10:49 +0200 Subject: [PATCH] docs: aggiorna README e documentazione con feature attuali --- README.md | 82 +++++++++++++++++++++++++++++---------------- docs/DEVELOPMENT.md | 49 +++++++++++++++++++++++++-- docs/WEB_WORKERS.md | 24 ++++++++----- 3 files changed, 116 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 2bdc70f..0f5aa32 100644 --- a/README.md +++ b/README.md @@ -4,13 +4,16 @@ Una dashboard web moderna e intuitiva per monitorare e gestire i modelli LLM car ## 🎯 Caratteristiche -- ✨ **Dashboard intuitiva** - Visualizza in tempo reale i modelli caricati in Ollama +- ✨ **Dashboard intuitiva** - Visualizza in tempo reale i modelli disponibili e in esecuzione su Ollama - πŸ“Š **Monitoraggio modelli** - Dettagli completi di ogni modello (nome, dimensione, memoria, stato) -- 🧩 **Dettagli avanzati on click** - Clic su una card modello per visualizzare i dati Ollama `show` +- 🧩 **Dettagli accordion on click** - Clic su una card per esplorare i dati `ollama show` in pannelli collassabili (dettagli, parametri, template, modelfile, licenza) +- πŸ–₯️ **Multi-server** - Gestione di piΓΉ istanze Ollama con switch istantaneo (pagina `/servers`) +- πŸƒ **Modelli in esecuzione** - Pagina dedicata `/models-running` con VRAM, tempo rimanente e backend GPU/CPU +- πŸ“± **PWA** - Installabile come app desktop/mobile con Service Worker e cache offline - πŸ”Œ **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 +- 🎨 **UI moderna** - Interfaccia dark-mode realizzata con TailwindCSS +- 🐳 **Docker ready** - Container sempre acceso (restart: unless-stopped) +- ⚑ **Performance** - FastAPI + uVicorn, aggiornamenti ogni 30s via Web Worker senza bloccare l'UI - πŸ” **Configurazione flessibile** - File `.env` per personalizzazione ## πŸ“‹ Requisiti @@ -309,38 +312,59 @@ docker start llm-monitor 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 +β”œβ”€β”€ requirements-dev.txt # Dipendenze sviluppo (pytest, black, flake8…) +β”œβ”€β”€ env.example # Esempio di configurazione +β”œβ”€β”€ Dockerfile # Build multi-stage (Node CSS + Python runtime) +β”œβ”€β”€ docker-compose.yml # Composizione servizi +β”œβ”€β”€ package.json # Script Node (Tailwind, Playwright) +β”œβ”€β”€ tailwind.config.js # Configurazione TailwindCSS +β”œβ”€β”€ playwright.config.js # Configurazione test E2E +β”œβ”€β”€ Makefile # Comandi rapidi (dev, test, deploy…) +β”œβ”€β”€ README.md # Questo file +β”œβ”€β”€ CONTRIBUTING.md # Guida ai contributi β”‚ β”œβ”€β”€ app/ -β”‚ β”œβ”€β”€ __init__.py -β”‚ β”œβ”€β”€ config.py # Configurazione (variabili ambiente) -β”‚ β”œβ”€β”€ main.py # Inizializzazione FastAPI +β”‚ β”œβ”€β”€ config.py # Configurazione via variabili d'ambiente β”‚ β”‚ β”‚ β”œβ”€β”€ api/ -β”‚ β”‚ β”œβ”€β”€ __init__.py -β”‚ β”‚ β”œβ”€β”€ models.py # Endpoint modelli -β”‚ β”‚ β”œβ”€β”€ health.py # Endpoint health -β”‚ β”‚ └── v1/ -β”‚ β”‚ └── __init__.py +β”‚ β”‚ β”œβ”€β”€ models.py # Endpoint modelli (/api/v1/models) +β”‚ β”‚ └── health.py # Endpoint health (/api/v1/health) β”‚ β”‚ β”‚ β”œβ”€β”€ services/ -β”‚ β”‚ β”œβ”€β”€ __init__.py -β”‚ β”‚ β”œβ”€β”€ ollama.py # Client Ollama -β”‚ β”‚ └── cache.py # Cache in-memory (opzionale) +β”‚ β”‚ └── ollama.py # Client HTTP verso Ollama β”‚ β”‚ β”‚ └── web/ -β”‚ β”œβ”€β”€ __init__.py -β”‚ β”œβ”€β”€ static/ # Assets statici (CSS compilato TailwindCSS) -β”‚ └── templates/ # Template HTML +β”‚ β”œβ”€β”€ static/ +β”‚ β”‚ β”œβ”€β”€ css/ +β”‚ β”‚ β”‚ β”œβ”€β”€ input.css # Sorgente Tailwind +β”‚ β”‚ β”‚ └── output.css # CSS compilato (generato) +β”‚ β”‚ └── js/ +β”‚ β”‚ β”œβ”€β”€ app.js # App principale (dashboard modelli) +β”‚ β”‚ β”œβ”€β”€ servers.js # Pagina gestione server +β”‚ β”‚ β”œβ”€β”€ models-running.js # Pagina modelli in esecuzione +β”‚ β”‚ β”œβ”€β”€ data-sync.worker.js # Web Worker sincronizzazione dati +β”‚ β”‚ β”œβ”€β”€ server-config.js # UtilitΓ  multi-server e localStorage +β”‚ β”‚ β”œβ”€β”€ pwa-register.js # Registrazione Service Worker +β”‚ β”‚ └── service-worker.js # PWA Service Worker (cache-first) +β”‚ └── templates/ +β”‚ β”œβ”€β”€ index.html # Dashboard modelli disponibili +β”‚ β”œβ”€β”€ servers.html # Gestione istanze Ollama +β”‚ └── models_running.html # Modelli attualmente in esecuzione +β”‚ +β”œβ”€β”€ docs/ +β”‚ β”œβ”€β”€ PRD.md # Product Requirements Document +β”‚ β”œβ”€β”€ DEVELOPMENT.md # Guida al setup e sviluppo locale +β”‚ └── WEB_WORKERS.md # Architettura Web Worker e PWA +β”‚ +β”œβ”€β”€ scripts/ +β”‚ β”œβ”€β”€ deploy-no-cache.sh # Deploy Docker con rebuild forzato +β”‚ └── verify-tailwind-css.sh # Verifica CSS compilato in container β”‚ └── tests/ - β”œβ”€β”€ __init__.py - β”œβ”€β”€ test_api.py - └── test_ollama.py + β”œβ”€β”€ test_api.py # Unit test endpoint FastAPI + β”œβ”€β”€ test_ollama.py # Unit test client Ollama + └── e2e/ + └── cache-navigation.spec.js # Test E2E Playwright (cache/PWA) ``` ## πŸ› οΈ Sviluppo @@ -453,6 +477,6 @@ Per domande o segnalazioni di bug, apri un **Issue** nel repository. **Fatto con ❀️ da [LucaSacchi.Net](https://lucasacchi.net)** -**Versione**: 1.0.0 +**Versione**: 1.1.0 **Ultima modifica**: Aprile 2026 -**Status**: 🟒 In Development +**Status**: 🟒 Active diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index c57bcc6..0aac678 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -73,9 +73,11 @@ Accedi a: http://localhost:8000 ``` 3. **Modificare i file:** - - HTML: `app/web/templates/index.html` + - HTML: `app/web/templates/index.html`, `servers.html`, `models_running.html` - CSS input: `app/web/static/css/input.css` (raramente, usa classi Tailwind) - - JavaScript: `app/web/static/js/app.js` e `data-sync.worker.js` + - JavaScript: `app/web/static/js/app.js`, `servers.js`, `models-running.js`, `data-sync.worker.js` + + > ⚠️ **Classi Tailwind dinamiche**: Le classi generate dinamicamente via `innerHTML` (es. in accordion o card) **non** vengono rilevate dal JIT scanner. Usa stili inline (`style="..."`) o classi hardcoded nei template HTML per queste situazioni. 4. **Compilato automaticamente:** - Tailwind genera `app/web/static/css/output.css` automaticamente @@ -198,6 +200,49 @@ npm run tailwind:build - [ ] Eseguire `npm run tailwind:build` per minificare - [ ] Verificare che `output.css` sia generato +- [ ] Eseguire i test Python: `make test` +- [ ] Eseguire i test E2E: `npm run test:e2e` + +--- + +## πŸ§ͺ Testing + +### Unit Test (pytest) + +```bash +# Tutti i test +pytest tests/ -v + +# Con coverage +pytest tests/ --cov=app +``` + +### E2E Test (Playwright) + +I test E2E verificano il comportamento del browser (cache-first, navigazione, PWA). + +```bash +# Installare i browser Playwright (prima volta) +npx playwright install --with-deps + +# Eseguire i test E2E (richiede Ollama attivo) +OLLAMA_HOST=http://:11434 npm run test:e2e + +# Con report HTML +npm run test:e2e -- --reporter=html +``` + +I test si trovano in `tests/e2e/`. Il report viene generato in `playwright-report/` (gitignored). + +### Makefile + +```bash +make test # pytest +make lint # flake8 +make format # black +make dev # uvicorn --reload +make deploy-no-cache # Docker rebuild forzato +``` - [ ] Controllare che il container Docker usi il CSS compilato - [ ] Test performance con Lighthouse - [ ] Verifica bundle size `output.css` diff --git a/docs/WEB_WORKERS.md b/docs/WEB_WORKERS.md index f638d2e..ad6bf86 100644 --- a/docs/WEB_WORKERS.md +++ b/docs/WEB_WORKERS.md @@ -54,13 +54,17 @@ Template HTML con struttura base e caricamento di app.js ## πŸ’Ύ LocalStorage -### Chiavi memorizzate: -- `llm_monitor_health` - Dati health check (status, ollama_status, timestamp) -- `llm_monitor_models` - Dati modelli (lista, total, totalSize, timestamp) +I dati sono memorizzati **per server** con chiavi dinamiche: -### Struttura dati: +- `llm_monitor_health_` - Dati health check +- `llm_monitor_models_` - Dati modelli disponibili +- `llm_monitor_running_` - Modelli in esecuzione +- `llm_monitor_servers` - Lista istanze Ollama configurate +- `llm_monitor_active_server` - ID del server attivo -**Health:** +La funzione `getServerStorageKey(serverId, suffix)` in `server-config.js` costruisce le chiavi. + +### Struttura dati health: ```json { "status": "healthy", @@ -69,7 +73,7 @@ Template HTML con struttura base e caricamento di app.js } ``` -**Models:** +### Struttura dati models: ```json { "models": [ @@ -82,6 +86,9 @@ Template HTML con struttura base e caricamento di app.js ], "total": 1, "totalSize": "3.56 GB", + "showByModel": { + "llama2": { "details": {}, "model_info": {}, "parameters": "..." } + }, "timestamp": "2024-01-15T10:30:00.000Z" } ``` @@ -96,6 +103,8 @@ Template HTML con struttura base e caricamento di app.js ### βœ… Offline Support - I dati rimangono in **localStorage** anche se il server Γ¨ offline - La dashboard mostra l'ultimo stato noto +- Il **Service Worker** (`service-worker.js`) mette in cache l'app shell (HTML, CSS, JS) per navigazione offline +- Cache name corrente: `llm-monitor-v3` ### βœ… Efficienza di Rete - Una sola fetch ogni 30 secondi (dal Worker) @@ -149,7 +158,6 @@ JSON.parse(localStorage.getItem('llm_monitor_models')) ## πŸš€ Ottimizzazioni Future - [ ] IndexedDB per dati maggiori -- [ ] Service Worker per offline mode completo - [ ] Sincronizzazione tra tab (BroadcastChannel API) - [ ] Caching intelligente con TTL - [ ] Compressione dati (Zstandard/Brotli) @@ -179,4 +187,4 @@ JSON.parse(localStorage.getItem('llm_monitor_models')) --- -**Sviluppato per LLM Monitor v1.0.0** πŸ¦™ +**Sviluppato per LLM Monitor v1.1.0** πŸ¦™