# MAS — MyAppify Support Agent

Assistente AI per il supporto clienti MyAppify. Analizza la richiesta, cerca tra documentazione e ticket risolti, e restituisce una risposta strutturata.

---

## Come funziona

L'agente elabora ogni richiesta attraverso un grafo multi-nodo ottimizzato per latenza e qualita della risposta.

```
  Richiesta del cliente
          │
          ▼
  ┌──────────────┐
  │ Normalizer   │  Pulisce e standardizza il testo in ingresso
  └──────┬───────┘
         │
    ┌────┴────┐          (esecuzione parallela)
    ▼         ▼
┌────────┐ ┌───────────┐
│ Router │ │ Retriever │  Classifica l'intent + cerca nella knowledge base
└───┬────┘ └─────┬─────┘
    ▼            │
┌──────────┐     │
│ ToolNode │     │  Cerca tra i ticket risolti per similarita
└────┬─────┘     │
     │           │
     ▼           ▼
  ┌────────────────┐
  │ Context Builder│  Unifica i risultati delle due ricerche
  └───────┬────────┘
          ▼
  ┌───────────┐
  │ Generator │  Genera la risposta basata sul contesto raccolto
  └─────┬─────┘
        ▼
  ┌───────────────┐
  │ Quality Check │  Verifica coerenza e completezza della risposta
  └───────┬───────┘
        ┌─┴──┐
        ▼    ▼
     ┌────┐ ┌────────────┐
     │ OK │ │ Escalation │  Se la qualita non e sufficiente,
     └──┬─┘ └─────┬──────┘  inoltra al team di supporto umano
        ▼         ▼
    Risposta   Email al team
```

### Scelte progettuali

| Scelta | Motivazione |
|--------|-------------|
| **Router e Retriever in parallelo** | Riduce la latenza: la classificazione dell'intent e la ricerca semantica avvengono contemporaneamente |
| **Ricerca su due canali** | Il Retriever cerca nella documentazione e FAQ; il ToolNode cerca tra i ticket gia risolti. Cosi l'agente copre sia la knowledge base ufficiale sia l'esperienza operativa |
| **Reranking con Cross-Encoder** | I risultati della ricerca vengono ri-ordinati da un modello neurale per massimizzare la rilevanza prima di generare la risposta |
| **Quality Check automatico** | Ogni risposta viene verificata prima di essere restituita. Se il livello di confidenza e basso, interviene un secondo modello LLM per validare |
| **Escalation automatica** | Se la richiesta non puo essere risolta con sufficiente qualita, viene inoltrata automaticamente via email al team di supporto |
| **Nessun dato personale nella ricerca** | I campi `client_id` e `store` non vengono mai usati per il retrieval — servono solo per le notifiche interne |

---

## Autenticazione

Tutte le chiamate API richiedono una chiave nel header `X-API-Key`.

```bash
curl -X POST https://api.modelvault.it/mas/ticket \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"question": "I prodotti non si sincronizzano"}'
```

Senza una chiave valida, il server restituisce `401 Unauthorized`.

La chiave API viene fornita al momento dell'attivazione del servizio.

---

## Documentazione interattiva

| URL | Descrizione |
|-----|-------------|
| [/mas/docs](https://api.modelvault.it/mas/docs) | Swagger UI — interfaccia interattiva per testare le API |
| [/mas/redoc](https://api.modelvault.it/mas/redoc) | ReDoc — documentazione in sola lettura |

Entrambe accessibili senza chiave API.

---

## Endpoint

### `POST /mas/ticket`

Invia una richiesta di supporto e ricevi una risposta generata dall'agente AI.

**Request:**
```json
{
  "question": "Non riesco a sincronizzare gli ordini con Easyfatt",
  "app_type": "easyfatt"
}
```

| Campo | Tipo | Obbligatorio | Descrizione |
|-------|------|:---:|-------------|
| `question` | string | Si | La domanda o il problema da risolvere |
| `app_type` | string | No | Tipo di applicazione (es. `"easyfatt"`, `"woocommerce"`). Default: `"generic"` |
| `client_id` | string | No | Identificativo cliente (solo per notifiche interne) |
| `store` | string | No | URL dello store (solo per notifiche interne) |
| `session_id` | string | No | ID sessione per tracciamento conversazione |

**Response:**
```json
{
  "response": "Per risolvere il problema di sincronizzazione...",
  "escalated": false,
  "intent": "troubleshooting",
  "confidence": 0.85,
  "quality_ok": true,
  "processing_ms": 12400,
  "sources_count": 6
}
```

| Campo | Tipo | Descrizione |
|-------|------|-------------|
| `response` | string | Risposta generata dall'agente |
| `escalated` | boolean | `true` se la richiesta richiede intervento umano |
| `intent` | string | Categoria della richiesta (es. `"troubleshooting"`, `"how_to"`, `"billing"`) |
| `confidence` | float | Livello di confidenza della risposta (0.0 – 1.0) |
| `quality_ok` | boolean | `true` se la risposta ha superato il controllo qualita |
| `processing_ms` | integer | Tempo di elaborazione in millisecondi |
| `sources_count` | integer | Numero di fonti utilizzate per generare la risposta |

### `GET /mas/health`

Verifica lo stato del servizio.

```json
{ "status": "ok", "service": "mas" }
```

---

## Note

- Il tempo medio di risposta e tra 8 e 15 secondi, a seconda della complessita della richiesta.
- Se `escalated` e `true`, la richiesta e stata inoltrata automaticamente al team di supporto via email.
- I campi `client_id` e `store` non influenzano la risposta — vengono usati solo per le notifiche interne al team.
- Se l'utente inserisce volontariamente dati nel corpo della richiesta, l'autore del software non garantisce la riservatezza, l'integrita o la protezione di tali informazioni e declina ogni responsabilita per qualsiasi trattamento, esposizione o utilizzo non previsto derivante dalla loro trasmissione.

---

## Supporto

Per richiedere una chiave API, segnalare un problema o richiedere assistenza:

**Email**: info@modelvault.it
**Web**: [www.modelvault.it](https://www.modelvault.it)