0 Fork 0

Files

T

Sibilla 76bc667adf 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

5.4 KiB

Raw Blame History

📚 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:

Python 3.10+
Google API Key (per Gemini)
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)

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:

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%+

5.4 KiB Raw Blame History