feat: v0.2.0 — API REST, TTS support, documentazione completa e UI mobile-first

✨ Nuove funzionalità: - Nuovo endpoint API REST /api/v1/query (GET+POST) per consumo programmatico - Campo speakable_text ottimizzato per sintesi vocale (Alexa, Google Home) - Funzione strip_markdown() per conversione Markdown → plain text TTS - Supporto CORS per accesso cross-origin - UI responsive mobile-first con micro-interazioni e stati - Nuovo pulsante 'Nuova ricerca' e metadata bar 📚 Documentazione completa: - docs/ARCHITECTURE.md — architettura di sistema, stack, componenti - docs/FLOW.md — diagrammi Mermaid della pipeline e flussi - docs/API.md — documentazione endpoint REST con esempi curl - docs/WIKI.md — FAQ, glossario, roadmap - docs/DEPLOYMENT.md — guida deployment (Gunicorn, Nginx, Docker, systemd) - docs/CONTRIBUTING.md — guida alla contribuzione 🔧 Migliorie tecniche: - Pipeline di ricerca condivisa in _run_search_pipeline() - Gestione errori Gemini migliorata con _clean_error() - Sanitizzazione HTML con allowlist per prevenzione XSS - .env.example completo con commenti 🧪 Test: 109/109 passati
2026-07-18 10:05:46 +00:00
1 parent f3fe13c60e
commit 76bc667adf
@@ -0,0 +1,143 @@
+# 📚 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%+
+```