truetype/sibilla
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
sibilla/docs/WIKI.md
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 Permalink 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:

  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)

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%+
Reference in new issue View Git Blame Copy Permalink