# 📚 Sibilla — Wiki

> Wiki tecnica del progetto Sibilla — motore di ricerca AI self-hosted stile Perplexity.

---

## Cosa è Sibilla?

**Sibilla** è un'applicazione Python/Flask che implementa un motore di ricerca AI self-hosted, simile a Perplexity AI. Ti permette di:

- Fare domande in linguaggio naturale
- Ottenere risposte sintetizzate da Google Gemini basate su fonti web reali
- Visualizzare le fonti con link e citazioni inline
- Usare l'API REST per integrare Sibilla in altri servizi (skill Alexa, bot, app mobile)
- Esporre la ricerca web come tool via MCP (Model Context Protocol) per agent AI

---

## Perché si chiama Sibilla?

Le **Sibille** erano figure della mitologia greco-romana: profetesse che pronunciavano oracoli. Come l'oracolo, Sibilla "vede" nel web e "profetizza" risposte basate sulle fonti che consulta.

---

## Funzionalità

### ✅ Implementate

| Funzionalità | Descrizione |
|-------------|-------------|
| 🔍 **Multi-engine search** | Degoog → SearXNG → DuckDuckGo con fallback a cascata |
| 🧠 **Sintesi AI** | Google Gemini sintetizza risposte con citazioni [1], [2], ... |
| 📝 **Query expansion** | Gemini genera varianti di query per migliorare il recall |
| 📄 **Full content fetching** | Scarica e analizza il contenuto completo delle pagine |
| 🌐 **Interfaccia web** | UI responsive, dark theme, mobile-first |
| 📡 **API REST** | Endpoint `/api/ask` (web) e `/api/v1/query` (API) |
| 🗣️ **TTS-ready** | Campo `speakable_text` ottimizzato per sintesi vocale |
| 🔧 **MCP server** | Server Model Context Protocol per agent AI esterni |
| 🛡️ **XSS protection** | Sanitizzazione HTML con allowlist |
| 🔄 **CORS** | Header cross-origin per accesso da qualsiasi dominio |
| 📊 **Metadati** | Token count, modello usato, search engine usato |

### 🚧 In programma

| Funzionalità | Priorità |
|-------------|----------|
| Rate limiting API | Alta |
| Caching risposte (Redis) | Media |
| Multi-lingua (oltre IT/EN) | Media |
| Autenticazione API key | Media |
| Streaming risposta (SSE) | Bassa |
| Supporto immagini nei risultati | Bassa |
| Docker Compose (Sibilla + Degoog + SearXNG) | Bassa |

---

## Glossario

| Termine | Definizione |
|---------|------------|
| **Sintesi** | Processo con cui Gemini genera una risposta basata sulle fonti |
| **Query Expansion** | Generazione di varianti di una query per migliorare la ricerca |
| **Cascading Fallback** | Strategia di fallback a catena: prova A, poi B, poi C |
| **Full Content** | Contenuto testuale completo di una pagina web (dopo scraping) |
| **Sanitizzazione HTML** | Rimozione di tag/attributi pericolosi per prevenire XSS |
| **MCP** | Model Context Protocol — standard per esporre tool a LLM |
| **TTS** | Text-to-Speech — sintesi vocale (es. Alexa, Google Home) |
| **Degoog** | Metasearch engine self-hosted, alternativa leggera a SearXNG |

---

## Domande Frequenti (FAQ)

### Cosa serve per far funzionare Sibilla?

Come minimo:
1. **Python 3.10+**
2. **Google API Key** (per Gemini)
3. Almeno un motore di ricerca:
   - **Degoog** (consigliato) — `docker run -d -p 4444:4444 ghcr.io/degoog-org/degoog:latest`
   - **SearXNG** — `docker run -d -p 8080:8080 searxng/searxng`
   - **DuckDuckGo** — funziona senza server (fallback automatico)

### Posso usare Sibilla senza Degoog/SearXNG?

Sì! Sibilla userà automaticamente DuckDuckGo come fallback (scraping HTML, nessuna API key necessaria). Puoi disabilitarlo con `SIBILLA_DDG_FALLBACK=0`.

### Quanto costa?

- **Sibilla:** gratuito e open-source (MIT)
- **Degoog:** gratuito, self-hosted
- **SearXNG:** gratuito, self-hosted
- **Gemini API:** ha un tier gratuito (vedi [Google AI Studio](https://aistudio.google.com/apikey))

### Posso cambiare il modello LLM?

Sì! Modifica il parametro `model` quando crei `GeminiClient` o cambia il default in `ai.py`. Supporta qualsiasi modello Gemini (es. `gemini-2.5-pro`, `gemini-1.5-flash`).

### Sibilla supporta altre lingue?

Sì! I prompt sono in italiano ma Gemini risponde nella lingua della domanda. Puoi modificare i prompt in `prompts.py` per altre lingue.

### Come integro Sibilla con la mia app?

Usa l'endpoint `/api/v1/query`:

```bash
curl "http://localhost:5000/api/v1/query?q=tua+domanda"
```

Vedi `docs/API.md` per la documentazione completa.

### Sibilla funziona dietro un reverse proxy (nginx, Caddy)?

Sì! Sibilla è una normale app Flask/WSGI. Puoi usare `gunicorn` come server WSGI e nginx/Caddy come reverse proxy. Vedi `docs/DEPLOYMENT.md`.

---

## Confronto con Perplexity

| Caratteristica | Perplexity | Sibilla |
|---------------|-----------|---------|
| **Hosting** | Cloud (perplexity.ai) | Self-hosted |
| **Costo** | $20/mese (Pro) | Gratuito (+ costi API Gemini) |
| **Privacy** | Dati su server Perplexity | Dati sul tuo server |
| **Motori di ricerca** | Interni di Perplexity | Degoog, SearXNG, DuckDuckGo |
| **LLM** | Modelli proprietari | Google Gemini |
| **API** | Via perplexity.ai | Locale, REST/MCP |
| **Personalizzazione** | Limitata | Completa (open source) |
| **MCP** | No | Sì |
| **TTS support** | No | Sì (via `speakable_text`) |

---

## Roadmap

```
v0.1.0 ✅ — MVP: ricerca + sintesi con Degoog/SearXNG/DDG + Gemini
v0.2.0 ✅ — API v1, TTS, CORS, documentazione completa
v0.3.0 📋 — Rate limiting, caching, autenticazione API key
v0.4.0 📋 — Docker Compose, streaming SSE, multi-lingua
v1.0.0 📋 — Stable release, test coverage 90%+
```