# Assistente Morse (preventivo)

## Presentazione del progetto

**Assistente Morse** è l'assistente digitale intelligente del progetto **Morse**, sviluppato per automatizzare la gestione degli ordini e delle consegne a domicilio, permettendo di delegare l'intero flusso di richieste a un agente **LLM**.

### Gestione clienti automatica

**Conversazioni WhatsApp intelligenti**: I clienti possono ordinare direttamente via **WhatsApp** utilizzando un linguaggio naturale, come se parlassero con un operatore umano. Il sistema riconosce i clienti abituali e ricorda le loro preferenze d'ordine. Il servizio garantisce una disponibilità 24/7 senza tempi di attesa, garantendo comunque in ogni momento la possibilità di passare la gestione della chat a un operatore umano.

### Organizzazione delle consegne

**Verifica automatica degli indirizzi**: Il sistema valida automaticamente che le consegne rientrino in un raggio parametrizzabile di *n* km dal corso centrale di Pontedera.

**Pianificazione ottimizzata**: Organizza le consegne in slot temporali precisi per garantire una gestione efficiente degli ordini.

**Integrazione Apple Calendar e Reminders**: Tutte le consegne vengono inserite automaticamente su **Apple Calendar**, mentre gli asporti sono gestiti su **Apple Reminders**. Le informazioni sull'ordine vengono riportate in un formato standardizzato e funzionale alla consultazione.

### Gestione menù e ordini

**Menu sempre aggiornato**: Prezzi, disponibilità e informazioni sui prodotti sono sincronizzati in tempo reale.

**Tracciamento completo**: Il sistema mantiene un registro storico completo di tutti gli ordini e delle vendite effettuate.

---

**Nota**: Il sistema è progettato per essere scalabile e all'occorrenza estensibile ad altre funzionalità. Per _occorrenza_ si intende:
a) richieste ulteriori da parte del cliente, con conseguente ridefinizione del preventivo;
b) eventuale richiesta ventura di nuovo preventivo per espansione del progetto.

---

## Overview progetto


### Flusso utente

Il cliente interagisce con l'assistente AI su **WhatsApp** tramite l'integrazione **Callbell**, che gestisce le comunicazioni in modo asincrono. L'agente intelligente elabora ogni richiesta coordinando le diverse funzionalità: validazione degli indirizzi, gestione del menu, logica di consegna e prenotazioni.

stateDiagram-v2
    [*] --> MessaggioUtente : Messaggio Whatsapp

    %% --- Caricamento memoria ---
    MessaggioUtente --> CaricaMemoria : Legge profilo da Supabase

    %% --- Verifica utente nuovo ---
    CaricaMemoria --> UtenteNuovo : Utente nuovo?
    UtenteNuovo --> RaccogliDati : Sì
    UtenteNuovo --> Menu : No
    RaccogliDati --> Menu : Inserisci indirizzo + preferenze

    %% --- Menu e scelta piatti ---
    Menu --> SceltaPiatti : Mostra menu personalizzato
    SceltaPiatti --> SceltaModalita : Asporto o Consegna

    %% --- Percorso asporto ---
    SceltaModalita --> Reminder : Asporto
    Reminder --> AggiornaMemoria
    AggiornaMemoria --> [*]

    %% --- Percorso consegna ---
    SceltaModalita --> OrarioStimato : Consegna
    OrarioStimato --> SlotDisponibili : Calcola slot disponibili
    SlotDisponibili --> SceltaSlot : Utente sceglie slot
    SceltaSlot --> Calendar : Aggiungi ordine su Calendar
    Calendar --> AggiornaMemoria
    AggiornaMemoria --> [*]

**Nota**: Il flusso standard prevede un'interazione completa; il percorso effettivo potrebbe subire lievi variazioni per ottimizzare le performance dell'AI.

### Cloud

Il *core* dell'applicazione risiede su **Vercel**, una piattaforma moderna che garantisce costi contenuti e un database sicuro.

Utilizziamo **LangChain** e **Mem0**, due framework all'avanguardia che permettono all'assistente AI di collegarsi a servizi esterni e gestire la memoria conversazionale. Per l'intelligenza artificiale ci affidiamo a **OpenRouter**, che offre accesso ai migliori modelli AI sul mercato a prezzi competitivi (attualmente consigliamo **Claude Sonnet 4.5** via **Gemini** per le sue capacità avanzate).

https://huggingface.co/spaces/gorilla-llm/berkeley-function-calling-leaderboard

I dati vengono archiviati in sicurezza su **Supabase**, che memorizza conversazioni, preferenze alimentari e anagrafiche utenti. Questo database assicura la continuità del dialogo con ogni cliente, ricordando le preferenze nel tempo.

Per la geolocalizzazione utilizziamo **LocationIQ** (basato su **OpenStreetMaps**) che offre 5.000 chiamate gratuite al giorno, volume più che sufficiente per le esigenze attuali. Gli indirizzi validati vengono memorizzati per evitare controlli ridondanti. Solo in caso di volumi eccezionali (oltre 1.000 ordini giornalieri) si valuterà il passaggio a **Google Maps** (costo stimato: circa 10€ mensili).

### Parte locale (Mac mini)

Per integrare **Apple Calendar**, **Apple Reminders** e **Apple Numbers** è necessario mantenere un server attivo sul **Mac mini**, poiché gli strumenti **Apple** richiedono un'esecuzione locale tramite **AppleScript**.

Abbiamo scelto di sviluppare un server **MCP** (Model Context Protocol) in un container **Docker**, tecnologia che garantisce l'isolamento e la sicurezza dei processi. Il server può operare come container persistente o come servizio di sistema all'avvio del **Mac mini**.

Il server locale espone le funzionalità **Apple** tramite protocollo **MCP** sulla porta 8277, gestendo:
- **Apple Calendar**: gestione delle consegne a domicilio.
- **Apple Numbers**: accesso alle informazioni del menù.
- **Apple Reminders**: gestione degli asporti.

**Nota importante**: Per consentire la comunicazione tra il sistema cloud e il server locale, il cliente dovrà richiedere un **indirizzo IP statico** al proprio provider internet (**Fastweb**, **Vodafone**, ecc.). Questo comporta un costo aggiuntivo di circa 1-5€ mensili. Sono disponibili due configurazioni: IP statico diretto o IP dinamico con tunneling (soluzione più flessibile ma tecnicamente più complessa).

### Architettura e comunicazione

Il sistema cloud e il server locale dialogano attraverso un canale protetto con protocollo **MCP**, permettendo all'assistente AI di gestire appuntamenti, promemoria e menu direttamente sulle app **Apple** già in uso. L'agente centrale orchestra tutte le operazioni: dalla validazione dell'indirizzo alla prenotazione finale, passando per la consultazione del menu e il completamento del flusso logistico.

---

## Costi di sviluppo

| Attività | Cosa significa per il cliente | Ore di lavoro stimate |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------- |
| **Inizializzazione Database** | Creazione dello spazio dove vengono salvati in modo sicuro tutti i dati del sistema. | **4 ore** |
| **Ambienti di sviluppo + documentazione** | Preparazione degli strumenti di lavoro e della documentazione per garantire stabilità e facilità di manutenzione. | **8 ore** |
| **Hosting, sicurezza e monitoraggio** | Pubblicazione online del servizio, configurazione dei domini, sicurezza e controllo automatico degli errori. | **12 ore** |
| **Agente AI e servizi collegati** | Sviluppo dell’intelligenza artificiale che dialoga con gli utenti e gestisce le funzionalità principali. | **12 ore** |
| **Servizio AI centralizzato** | Ottimizzazione dell’uso dell’AI per garantire prestazioni costanti e riduzione dei costi. | **8 ore** |
| **Costruzione dinamica delle risposte** | Creazione di risposte personalizzate e contestuali, adattate alle richieste dell’utente. | **16 ore** |
| **Recupero dati strutturato** | Organizzazione dei dati per garantire informazioni corrette e sempre aggiornate. | **8 ore** |
| **Gestione del menù** | Importazione e aggiornamento dei menù tramite file o fogli di calcolo, senza complessità tecniche. | **12 ore** |
| **Verifica posizione e distanza** | Controllo automatico della posizione dell’utente e calcolo delle distanze. | **8 ore** |
| **Memoria a lungo termine** | Memorizzazione delle preferenze degli utenti e dello storico delle conversazioni per un’esperienza personalizzata. | **16 ore** |
| **Algoritmo di prenotazione** | Gestione intelligente delle prenotazioni per ottimizzare disponibilità e richieste. | **16 ore** |
| **Integrazione ecosistema Apple** | Collegamento con servizi Apple per funzionalità aggiuntive o integrazioni future. | **12 ore** |
| **Integrazione Callbell** | Collegamento con Callbell per la gestione centralizzata delle conversazioni con i clienti. | **12 ore** |

---

**Totale stimato di sviluppo:** 144 ore.

Data la natura del progetto e l'uso di tecnologie all'avanguardia, proponiamo un'**aggiunta del 20%** per gestire imprevisti e complessità tecniche non preventivabili.

**Ore totali:** 144 + 29 = **173 ore di sviluppo**.

**Tariffa oraria:** 20 €/h.

**Costo totale sviluppo:** **3.460 €**.

### Budget strumenti e servizi di sviluppo

Si propone un **budget iniziale di 100 €** da destinare a strumenti e servizi necessari per lo sviluppo e il miglioramento del progetto. Gli sviluppatori si impegnano a non superare questa spesa.

---

## Costi di mantenimento

I costi operativi mensili da sostenere sono:
- **Callbell**: per la gestione delle conversazioni **WhatsApp**.
- **OpenRouter**: per le chiamate al modello AI (costo variabile in base all'utilizzo).

**Stima dei costi in base all'uso:**
- **Basso volume / uso iniziale**: ~ 20–25 €/mese (**Callbell** ~14 € + **OpenRouter** ~5‑10 €).
- **Uso moderato / bot attivo con traffico regolare**: ~ 25–40 €/mese.
- **Uso intensivo / alto volume di conversazioni**: 40‑60 €/mese o più in caso di crescita significativa.

L'infrastruttura cloud (**Vercel**, **Supabase**, **LocationIQ**) ha costi irrisori grazie ai piani gratuiti generosi. Stimiamo al massimo **10 € mensili** solo per questi servizi con volumi di utilizzo significativi. Inizialmente, grazie ai piani free, questi costi saranno azzerati.

---

## Piano di pagamento _a tranche_

**Prima _tranche_ (40% = 1.384 €)** – da corrispondere all'avvio effettivo dello sviluppo e al rilascio delle seguenti funzionalità:
- Integrazione **WhatsApp** tramite **Callbell**.
- Sistema AI di base funzionante.
- Possibilità di testare il bot su **WhatsApp** durante lo sviluppo.
- Notifiche sugli aggiornamenti e progressi.

**Seconda _tranche_ (60% = 2.076 €)** – da corrispondere al completamento del sistema finale con tutte le funzionalità:
- Gestione completa del menu tramite **Apple Numbers**.
- Prenotazioni su **Apple Calendar** e **Apple Reminders**.
- Validazione indirizzi con **LocationIQ**.
- Deploy del server **MCP** sul **Mac mini**.
- Ottimizzazione dell'AI e test completi.
- Sistema pronto per la produzione.

---

## Tempistiche di sviluppo

Si stima che il **sistema funzionante e completo** sarà consegnato entro circa **1 mese / 1 mese e mezzo** dall'inizio dello sviluppo.

Le tempistiche potrebbero variare leggermente in base alle priorità degli sviluppatori, agli imprevisti tecnici e ai risultati dei test.

L'obiettivo principale è consegnare un prodotto **funzionante, stabile e affidabile**, che giustifichi pienamente l'investimento iniziale e possa crescere insieme al business del cliente.

Nel preventivo è contemplato un periodo di assistenza post-lancio, mirato alla risoluzione di anomalie o malfunzionamenti che possano manifestarsi in seguito allo sviluppo iniziale, nel perimetro dei requisiti stabiliti del prodotto.

---

**Firma**

Francesco Giuseppe Ziccolella

Data:
Luogo:

---

**Per accettazione:**

Il Cliente

---