# Piano di Azione: Suggerimento Canti con AI (cantiletture.json) ## Obiettivo Generare automaticamente, una volta a settimana, un file JSON con i canti suggeriti per ogni messa della settimana, analizzati da Gemini Flash a partire dalle letture liturgiche. La PWA scarica questo file statico e mostra i suggerimenti istantaneamente, senza alcun calcolo lato client. --- ## Architettura ``` CRON Settimanale (Lunedì ore 6:00) │ ├─ 1. Fetch RSS liturgia.silvestrini.org/rss │ → Estrae le letture di tutta la settimana (7 giorni) │ ├─ 2. Fetch canti.json dal server │ → Carica il database completo dei canti con testi e momenti liturgici │ ├─ 3. Chiamata API Gemini Flash │ → Invia prompt strutturato con letture + lista canti │ → Riceve suggerimenti ragionati con score e motivazione │ └─ 4. Salva cantiletture.json → Upload sul server web (stessa posizione di canti.json) ``` --- ## Struttura del File cantiletture.json ```json { "generated_at": "2026-05-19T06:00:00Z", "week_start": "2026-05-17", "week_end": "2026-05-24", "masses": { "2026-05-17": { "title": "Ascensione del Signore", "day": "Domenica", "moments": { "Ingresso": [ { "id_canti": 42, "titolo": "Cristo è risorto veramente", "score": 95, "motivo": "Il tema dell'ascensione e della gloria di Cristo risorto è centrale in questo canto." }, { "id_canti": 118, "titolo": "Alleluia, è risorto", "score": 88, "motivo": "Il tono gioioso e la proclamazione pasquale si collegano al mistero celebrato." }, { "id_canti": 205, "titolo": "Canto di lode al Signore", "score": 82, "motivo": "Richiama il tema della lode che accompagna l'ascensione di Gesù." } ], "Offertorio": [ { "...": "3 canti suggeriti" } ], "Comunione": [ { "...": "3 canti suggeriti" } ], "Finale": [ { "...": "3 canti suggeriti" } ] } }, "2026-05-18": { "title": "Lunedì della VII settimana di Pasqua", "day": "Lunedì", "moments": { "...": "stessa struttura" } } } } ``` ### Campi per ogni canto suggerito: | Campo | Tipo | Descrizione | |-------|------|-------------| | `id_canti` | number | ID del canto nel database (per collegamento diretto al player) | | `titolo` | string | Titolo del canto (per visualizzazione rapida) | | `score` | number (0-100) | Grado di affinità/affidabilità del suggerimento | | `motivo` | string | Spiegazione testuale del perché il canto è adatto | --- ## Componenti da Sviluppare ### 1. Script di Generazione (`scripts/generate-cantiletture.ts`) Script Node.js/TypeScript che: - **Input**: RSS feed + canti.json - **Elaborazione**: 1. Parsing XML del feed RSS (estrazione letture per data) 2. Preparazione del prompt per Gemini con: testo letture + lista canti (id, titolo, testo, momenti liturgici) 3. Chiamata API Gemini Flash con output JSON strutturato 4. Validazione della risposta (verifica che gli ID canti esistano, score nel range) - **Output**: File `cantiletture.json` **Prompt di esempio per Gemini:** ``` Sei un esperto liturgista cattolico. Ti fornisco le letture della messa e un database di canti liturgici con i relativi momenti (Ingresso, Offertorio, Comunione, Finale, ecc.). Per ogni giorno della settimana e per ogni momento liturgico, suggerisci i 3 canti più adatti. Per ogni suggerimento indica: - L'ID del canto (id_canti) - Uno score da 0 a 100 che indica il grado di attinenza - Una breve motivazione (max 1 frase) Considera: temi teologici, periodo liturgico, tono emotivo, corrispondenze tra letture e testi dei canti. LETTURE DELLA SETTIMANA: [...testo letture...] DATABASE CANTI: [...lista canti con id, titolo, testo, momenti...] Rispondi SOLO con JSON valido nel formato specificato. ``` ### 2. Configurazione API Key - Ottenere API Key gratuita da [Google AI Studio](https://aistudio.google.com/apikey) - Salvarla come variabile d'ambiente `GEMINI_API_KEY` - Non committarla nel repository (usare `.env` in `.gitignore`) ### 3. Aggiornamento PWA #### 3.1 Nuovo Service: `CantiLettureService` ```typescript // Logica semplificata: // - Scarica cantiletture.json dal server (con cache) // - Espone i suggerimenti per data selezionata // - Fallback al keyword matching se il JSON non è disponibile ``` #### 3.2 Aggiornamento LiturgiaPage - Rimuovere il tasto "Analizza e Suggerisci Canti" (non serve più) - Rimuovere la sezione "Parole Chiave Rilevate" (non serve più) - Mostrare automaticamente i suggerimenti raggruppati per momento liturgico - Ogni card mostra: titolo, score (barra o badge), motivazione dell'AI - Click sulla card → apre il canto nel player #### 3.3 Fallback Se `cantiletture.json` non è disponibile o la data non è coperta: - Mostrare un messaggio "Suggerimenti AI non disponibili per questa data" - Opzionalmente, offrire il keyword matching come alternativa ### 4. Automazione (CRON) #### Opzione A: Script locale con crontab ```bash # Ogni lunedì alle 6:00 0 6 * * 1 cd /path/to/canti && node scripts/generate-cantiletture.js ``` #### Opzione B: GitHub Action (se il repo viene messo su GitHub) ```yaml # .github/workflows/generate-suggestions.yml name: Generate Canti Suggestions on: schedule: - cron: '0 6 * * 1' # Ogni lunedì alle 6:00 UTC workflow_dispatch: # Esecuzione manuale ``` #### Opzione C: Script manuale ```bash # Eseguibile a mano quando si vuole aggiornare ./scripts/generate-cantiletture.sh ``` --- ## Stima Costi | Voce | Valore | |------|--------| | Chiamate API/settimana | 1 (una sola chiamata copre tutta la settimana) | | Token input (letture + ~500 canti) | ~15.000 token | | Token output (JSON suggerimenti) | ~3.000 token | | Costo per chiamata (Gemini Flash) | ~0.001€ | | **Costo mensile stimato** | **< 0.01€** | | Rientra nell'abbonamento Google One | ✅ Sì | --- ## Piano di Esecuzione (Step by Step) ### Fase 1: Script di Generazione 1. [ ] Creare `scripts/generate-cantiletture.ts` 2. [ ] Implementare il parsing RSS 3. [ ] Implementare la chiamata Gemini con prompt ottimizzato 4. [ ] Testare con le letture della settimana corrente 5. [ ] Validare il JSON generato ### Fase 2: Integrazione PWA 6. [ ] Creare `CantiLettureService` che scarica e gestisce il JSON 7. [ ] Aggiornare `LiturgiaPage` per mostrare i suggerimenti AI 8. [ ] Implementare il fallback al keyword matching 9. [ ] Testare l'interfaccia completa ### Fase 3: Automazione 10. [ ] Configurare il cron/script di esecuzione automatica 11. [ ] Testare il ciclo completo (generazione → upload → visualizzazione) 12. [ ] Documentare la procedura nel README --- ## Note Tecniche - **Dimensione stimata del JSON**: ~50-100 KB per settimana (7 giorni × 4-5 momenti × 3 canti) - **Cache**: Il JSON viene cachato in localStorage con TTL di 24 ore - **Compatibilità**: Il file viene servito dallo stesso server HTTP della PWA, nessun problema CORS - **Retrocompatibilità**: Se il file non esiste, la PWA continua a funzionare con il keyword matching