MoodMapper — AI Emotion & Sentiment Analyzer

Analizzatore di testo basato su AI che mappa emozioni e sentiment con statistiche storiche interattive, costruito con Python/Flask e la Groq API.

---

Cos'è

MoodMapper analizza qualsiasi testo scritto e restituisce in tempo reale:

• Sentiment: positivo, negativo o neutrale con punteggio di confidenza
• Emozione dominante: gioia, tristezza, rabbia, paura, sorpresa o disgusto con intensità
• Parole chiave: fino a 5 termini significativi estratti dal testo
• Sommario: una frase che cattura il tono generale

Casi d'uso concreti: analisi recensioni prodotto, journaling emotivo, monitoraggio tono di email/feedback clienti, analisi risposte a form aperti.

---

Perché queste scelte tecnologiche

Groq invece di Anthropic/OpenAI

• Tier gratuito reale: nessuna carta di credito, 30 richieste/minuto gratuite
• Latenza ultra-bassa: Groq usa hardware LPU (Language Processing Unit) proprietario, con velocità di inferenza molto superiori rispetto ai provider cloud tradizionali
• Zero costi operativi: ideale per portfolio project e prototipi

Llama 3.1-8b invece di GPT-4 o Claude

• Open source (Meta), nessun lock-in proprietario
• Ottimo rapporto qualità/velocità per task NLP strutturati: l'analisi del sentiment non richiede i modelli più grandi
• Context window 8192 token: più che sufficiente per testi brevi e medi

localStorage invece di un database

• L'app funziona senza infrastruttura backend aggiuntiva (nessun PostgreSQL, Redis, ecc.)
• Privacy by design: i dati vivono nel browser dell'utente
• Semplifica il deploy: bastano Flask + Groq, nessuna migrazione

Chart.js invece di D3.js API dichiarativa vs imperativa. Per donut e bar chart Chart.js è più veloce da usare e ha documentazione migliore. D3 è potente ma overkill per questo use case.

---

Architettura

Utente (browser)
     │ digita testo → click "Analizza"
     ▼
Frontend JavaScript (fetch POST)
     │ /api/analyze  {"text": "..."}
     ▼
Flask Backend (app.py)
     │ costruisce prompt strutturato in inglese
     ▼
Groq API (llama-3.1-8b-instant)
     │ risposta JSON pura
     ▼
Flask: parsing + validazione schema
     │ risposta HTTP 200
     ▼
Frontend JavaScript
  ├── renderResult() → aggiorna pannello UI con animazioni
  └── saveToHistory() → salva in localStorage
            └── renderDashboard() → Chart.js legge localStorage

---

Come funziona il codice

build_prompt(text) Il prompt è scritto in inglese perché i modelli Llama performano meglio in inglese, anche su testi in altre lingue. Viene specificato esplicitamente lo schema JSON atteso e si vieta al modello di usare markdown o backtick, che causano parsing failure.

parse_groq_response(content) Nonostante le istruzioni, il modello a volte aggiunge backtick markdown. La funzione li rimuove, parsa il JSON e valida la presenza di tutti i campi obbligatori. Se manca anche un solo campo, solleva ValueError.

Gestione errori (3 livelli) json.JSONDecodeError (risposta non JSON), ValueError (schema incompleto), Exception generico (rete, rate limit, autenticazione Groq). Ogni caso restituisce HTTP 500 con messaggio descrittivo.

Animazione barra intensità (frontend) Usa un doppio requestAnimationFrame per forzare il browser a fare prima un repaint con width=0, poi animare la transizione CSS alla percentuale corretta. Senza questo trick, il browser ottimizzerebbe i due state update in uno, rendendo invisibile la transizione.

XSS prevention Tutta l'output di testo utente passa per escapeHtml() prima di essere inserita nel DOM, creando un nodo di testo temporaneo invece di usare innerHTML direttamente.

---

Come ottenere la API key Groq

1. Vai su console.groq.com
2. Registrati con Google o GitHub (gratuito)
3. API Keys → Create API Key
4. Copia la chiave (formato gsk_...) e inseriscila nel file .env

Il tier gratuito include 30 richieste/minuto e 14.400 richieste/giorno — più che sufficiente per uso personale e portfolio.

---

Come avviare

cd moodmapper
cp .env.example .env
# Apri .env e inserisci: GROQ_API_KEY=gsk_tua_chiave_qui
pip install -r requirements.txt
python app.py

Apri il browser su http://localhost:5001.

---

Struttura del progetto

moodmapper/
├── app.py              ← Backend Flask + integrazione Groq API
├── requirements.txt
├── .env                ← API key (non committare!)
├── .env.example        ← Template
├── README.md
└── templates/
    └── index.html      ← Frontend completo (HTML + CSS + JS vanilla)