canti/liturgia_strategy.md

Strategia di Suggerimento Canti Liturgici

Questo documento descrive l'approccio tecnico utilizzato per suggerire i canti attinenti alle letture del giorno nella PWA "CantiCristiani".

1. Algoritmo di Analisi (Keyword Matching)

Al momento non viene utilizzata un'Intelligenza Artificiale generativa (LLM) per due motivi principali:

• Performance: L'analisi avviene istantaneamente sul dispositivo dell'utente senza chiamate API esterne lente.
• Privacy e Offline: Il sistema può funzionare anche con una connettività limitata una volta scaricato il testo delle letture.

Fasi dell'Algoritmo:

1. Keyword Extraction:
   • Il testo di tutte le letture (Prima, Salmo, Seconda, Vangelo) viene normalizzato in minuscolo.
   • Vengono rimosse le "stop words" (parole comuni come articoli, preposizioni, congiunzioni).
   • Vengono estratte solo le parole con lunghezza superiore a 3 caratteri per evitare rumore.
2. Ponderazione e Scoring:
   • Ogni canto nel database viene analizzato cercando le keyword estratte.
   • Titolo (Peso 10): Se una parola chiave appare nel titolo, il punteggio del canto aumenta drasticamente.
   • Testo/Lyrics (Peso 1): Ogni occorrenza di una parola chiave nel testo del canto aggiunge 1 punto al punteggio totale.
3. Classificazione per Momento Liturgico:
   • I canti vengono raggruppati in base alle categorie liturgiche (Ingresso, Gloria, Offertorio, Comunione, ecc.) definite nel database.
   • Il sistema seleziona i migliori 3 canti per ogni categoria per offrire una scelta bilanciata.

2. Selezione della Data Predefinita

L'applicazione calcola automaticamente la prossima domenica come data di default. Questo perché la maggior parte degli utenti utilizza la funzione per preparare la liturgia festiva imminente.

3. Sviluppi Futuri: Ricerca Semantica (Embeddings)

Per superare i limiti del matching testuale, la strategia futura prevede l'integrazione di tecniche di Semantic Search che possono essere eseguite direttamente nella PWA:

Architettura Proposta:

• Pre-calcolo dei Vettori: Generazione dei vettori (embeddings) per l'intero database dei canti. Questi dati verrebbero inclusi in una versione estesa del file canti.json.
• Analisi On-Device: Utilizzo di librerie matematiche leggere (come similarity-js) per calcolare la "distanza del coseno" tra il vettore della lettura e quelli dei canti.
• Vantaggi: Il sistema identificherebbe correlazioni concettuali (es. "Luce" -> "Mondo", "Pane" -> "Eucarestia") anche in assenza di corrispondenze testuali esatte.

Implementazione Tecnica:

1. Integrazione di un modello di embedding (es. all-MiniLM-L6-v2) via Web Workers per non bloccare l'interfaccia.
2. Memorizzazione locale dei vettori tramite IndexedDB per garantire performance elevate dopo il primo caricamento.