# Piano di Sviluppo per la Lambda "Pompeo"

Questo documento descrive il piano di analisi, progettazione, implementazione e deploy per la funzione AWS Lambda che funge da ponte tra la skill Alexa "Pompeo" e l'istanza n8n del progetto ALPHA_PROJECT.

## 1. Obiettivo

La funzione Lambda ha un unico scopo: agire come un "ponte" (bridge) ultra-leggero e veloce. Il suo compito è ricevere le richieste inviate dalla skill Alexa, inoltrarle in modo sicuro al webhook di n8n che contiene la logica dell'agente, e restituire ad Alexa la risposta testuale (TTS) generata da n8n.

---

## 2. Analisi e Requisiti

### Requisiti Funzionali

1.  **Ricezione Richiesta:** Deve essere in grado di ricevere e interpretare l'oggetto JSON inviato dal servizio Alexa.
2.  **Inoltro a n8n:** Deve inoltrare il corpo della richiesta Alexa a un webhook n8n predefinito.
3.  **Autenticazione (Opzionale ma Raccomandato):** La chiamata verso n8n dovrebbe includere un `secret token` per assicurare che solo la Lambda possa attivare il workflow.
4.  **Ricezione Risposta da n8n:** Deve attendere la risposta da n8n, che conterrà il testo da pronunciare.
5.  **Formattazione Risposta Alexa:** Deve costruire un oggetto JSON valido per Alexa, contenente la stringa TTS.
6.  **Gestione Errori:** Deve rispondere ad Alexa con un messaggio di errore cortese se n8n non è raggiungibile o restituisce un errore.

### Requisiti Non Funzionali

1.  **Costo Zero:** L'intera infrastruttura deve operare sotto la soglia del piano gratuito di AWS (AWS Free Tier).
    *   **AWS Lambda:** Il free tier include 1 milione di chiamate/mese e 400.000 GB-secondi, ampiamente sufficienti.
    *   **API Gateway (se usata):** Il free tier include 1 milione di chiamate API/mese.
2.  **Distribuzione Privata:** La skill Alexa non deve essere pubblicata sullo store pubblico. Deve rimanere in stato "In Sviluppo" (`development`), rendendola automaticamente disponibile solo sui dispositivi Echo associati all'account Amazon dello sviluppatore.
3.  **Bassa Latenza:** La funzione deve essere scritta in un linguaggio performante per I/O (es. Python, Node.js) e avere una logica minimale per non introdurre ritardi.
4.  **Sicurezza:** La comunicazione tra Lambda e n8n deve avvenire su HTTPS. L'URL del webhook e il secret token devono essere gestiti tramite environment variables della Lambda, non hardcodati nel codice.

---

## 3. Progettazione (Design)

### Architettura

```
+--------------+     1. Utente parla     +-----------------+     3. Inoltra richiesta     +---------------+
|              | ----------------------> |                 | --------------------------> |               |
|  Echo Device |                         |   AWS Lambda    |                             |  n8n Webhook  |
|              | <---------------------- |                 | <-------------------------  |               |
+--------------+    5. Risposta TTS      +-----------------+      4. Risposta TTS        +---------------+
                      (Text-to-Speech)
                               |
                               | 2. Trigger
                               |
                       +---------------------+
                       | Alexa Skills Kit    |
                       +---------------------+
```

### Dettagli Tecnici

*   **Runtime:** **Python 3.11**. È una scelta eccellente per task I/O-bound come questo, con un'ottima integrazione in ambiente AWS.
*   **Trigger:** Il trigger della Lambda sarà **"Alexa Skills Kit"**. Per sicurezza, verrà configurato per accettare chiamate solo dalla specifica Skill ID di "Pompeo".
*   **IAM Role:** Verrà creato un ruolo IAM con due policy:
    1.  **Trust Policy:** Permette al servizio `lambda.amazonaws.com` di assumere questo ruolo.
    2.  **Permissions Policy:** Si utilizzerà la policy gestita da AWS `AWSLambdaBasicExecutionRole`, che garantisce i permessi necessari per scrivere log su Amazon CloudWatch (`logs:CreateLogGroup`, `logs:CreateLogStream`, `logs:PutLogEvents`). Non sono necessari altri permessi.
*   **Logica del Codice (Python):**
    1.  La funzione `lambda_handler(event, context)` sarà il punto di ingresso.
    2.  Recupererà l'URL del webhook e il secret token dalle variabili d'ambiente (`os.environ.get('N8N_WEBHOOK_URL')`).
    3.  Eseguirà una richiesta HTTP POST (usando la libreria `requests` o `urllib3`) verso l'URL di n8n.
    4.  Il `body` della POST conterrà l'intero oggetto `event` ricevuto da Alexa. L'`header` conterrà il `secret token`.
    5.  Attenderà la risposta di n8n. Se la risposta è 200 OK e contiene un JSON con un campo `tts_response`, procederà.
    6.  Costruirà l'oggetto di risposta per Alexa, come da documentazione ufficiale.
*   **Gestione degli Errori:** In caso di timeout, codice di stato HTTP non-200, o JSON malformato da n8n, la Lambda costruirà una risposta di errore standard per Alexa (es. "Mi dispiace, si è verificato un problema. Riprova più tardi.").

---

## 4. Implementazione (Codice)

La Lambda richiederà un singolo file `index.py` e un file `requirements.txt` per le dipendenze.

**`requirements.txt`:**
```
requests
```

**`index.py` (Esempio Boilerplate):**
```python
import os
import json
import requests

# Recupera le variabili d'ambiente
N8N_WEBHOOK_URL = os.environ.get('N8N_WEBHOOK_URL')
N8N_SECRET_TOKEN = os.environ.get('N8N_SECRET_TOKEN')

def build_alexa_response(text):
    """Costruisce la risposta JSON per Alexa."""
    return {
        'version': '1.0',
        'response': {
            'outputSpeech': {
                'type': 'PlainText',
                'text': text
            },
            'shouldEndSession': True
        }
    }

def lambda_handler(event, context):
    """Punto di ingresso della funzione Lambda."""
    print(f"Richiesta ricevuta da Alexa: {json.dumps(event)}")

    if not N8N_WEBHOOK_URL or not N8N_SECRET_TOKEN:
        print("Errore: Variabili d'ambiente non configurate.")
        return build_alexa_response("Errore di configurazione del server.")

    headers = {
        'Content-Type': 'application/json',
        'X-N8N-Webhook-Secret': N8N_SECRET_TOKEN
    }

    try:
        response = requests.post(
            N8N_WEBHOOK_URL,
            headers=headers,
            data=json.dumps(event),
            timeout=8  # Alexa attende max 10 secondi
        )
        response.raise_for_status()  # Solleva un'eccezione per status code non-2xx

        n8n_data = response.json()
        tts_text = n8n_data.get('tts_response', 'Nessuna risposta ricevuta da Pompeo.')

        print(f"Risposta da n8n: {tts_text}")
        return build_alexa_response(tts_text)

    except requests.exceptions.RequestException as e:
        print(f"Errore nella chiamata a n8n: {e}")
        return build_alexa_response("Mi dispiace, non riesco a contattare Pompeo in questo momento.")
    except Exception as e:
        print(f"Errore generico: {e}")
        return build_alexa_response("Si è verificato un errore inaspettato.")

```
Il codice andrà zippato insieme alla cartella delle dipendenze installate localmente (`pip install -r requirements.txt -t .`).

---

## 5. Procedura Burocratica di Deploy e Configurazione

Questa è la checklist passo-passo per mettere tutto in funzione.

### Passo 1: Creazione del Ruolo IAM

1.  Vai alla console AWS -> **IAM** -> **Roles**.
2.  Clicca su **Create role**.
3.  **Trusted entity type**: Seleziona **AWS service**.
4.  **Use case**: Seleziona **Lambda**, poi clicca **Next**.
5.  Nella pagina **Add permissions**, cerca e seleziona la policy `AWSLambdaBasicExecutionRole`. Clicca **Next**.
6.  **Role name**: Inserisci un nome, es. `PompeoAlexaLambdaRole`.
7.  Clicca **Create role**.

### Passo 2: Creazione della Funzione Lambda

1.  Prepara il pacchetto di deploy:
    *   Crea una cartella, es. `lambda_package`.
    *   Salva il codice Python come `index.py` in quella cartella.
    *   Salva `requirements.txt`.
    *   Da terminale, nella cartella, esegui: `pip install -r requirements.txt --target .`
    *   Zippa l'intero contenuto della cartella `lambda_package` (non la cartella stessa).
2.  Vai alla console AWS -> **Lambda**.
3.  Clicca **Create function**.
4.  Seleziona **Author from scratch**.
5.  **Function name**: `pompeo-alexa-bridge`.
6.  **Runtime**: Seleziona **Python 3.11**.
7.  **Architecture**: `x86_64`.
8.  **Permissions**: Espandi "Change default execution role", seleziona "Use an existing role" e scegli il ruolo `PompeoAlexaLambdaRole` creato prima.
9.  Clicca **Create function**.
10. Nella pagina della funzione, vai su **Code source** e clicca **Upload from -> .zip file**. Carica lo zip creato.
11. Vai in **Configuration -> Environment variables** e aggiungi:
    *   `N8N_WEBHOOK_URL`: L'URL del tuo webhook n8n.
    *   `N8N_SECRET_TOKEN`: Il token segreto che configurerai su n8n.

### Passo 3: Creazione della Skill Alexa "Pompeo"

1.  Vai su [Alexa Developer Console](https://developer.amazon.com/alexa/console/ask).
2.  Clicca **Create Skill**.
3.  **Skill name**: `Pompeo`.
4.  **Choose a model**: `Custom`.
5.  **Choose a method to host**: `Provision your own`.
6.  Clicca **Create skill**.
7.  Una volta nella dashboard della skill, vai nel menu a sinistra su **Endpoint**.
8.  **Copia il tuo Skill ID**. Sarà una stringa simile a `amzn1.ask.skill.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.

### Passo 4: Collegamento tra Skill e Lambda

1.  Torna alla pagina della funzione **Lambda** su AWS.
2.  Nella sezione **Function overview**, clicca **Add trigger**.
3.  Come sorgente, seleziona **Alexa Skills Kit**.
4.  Abilita **Skill ID verification** e incolla lo **Skill ID** copiato dal portale Alexa.
5.  Clicca **Add**.
6.  Ora, nella pagina della Lambda, in alto a destra, **copia l'ARN (Amazon Resource Name)** della funzione.
7.  Torna alla pagina **Endpoint** della skill nella Alexa Developer Console.
8.  Seleziona **AWS Lambda ARN** come Service Endpoint Type.
9.  Incolla l'ARN della Lambda nel campo **Default Region**.
10. Clicca **Save Endpoints** in alto.

### Passo 5: Test

1.  Nella Alexa Developer Console, vai alla tab **Test**.
2.  Nella casella di testo, scrivi "apri pompeo" o qualsiasi altra frase di avvio.
3.  Controlla i log della funzione Lambda su **AWS CloudWatch** per vedere la richiesta in arrivo e la risposta.
4.  La skill è ora attiva in modalità "Development" e funzionerà su tutti i dispositivi Echo associati al tuo account Amazon, rimanendo completamente privata.