canti/cantiletture.md

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

{
  "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
• Salvarla come variabile d'ambiente GEMINI_API_KEY
• Non committarla nel repository (usare .env in .gitignore)

3. Aggiornamento PWA

3.1 Nuovo Service: CantiLettureService

// 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

# 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)

# .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

# 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