David Frassi
225 lines
7.2 KiB
Markdown
225 lines
7.2 KiB
Markdown
# 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
|