sibilla/README.md

🔮 Sibilla — L'Oracolo AI

Self-hosted Perplexity-like AI search engine.
Chiedi, cerca, sintetizza — con fonti verificabili.

---

Sibilla è un motore di ricerca AI self-hosted che combina:

• 🧠 Google Gemini — LLM per sintesi con citazioni inline [1], [2], ...
• 🔍 Degoog — metasearch engine self-hosted (primary) con API nativa
• 🔄 SearXNG + DuckDuckGo — fallback a cascata se il primary non risponde
• 🌐 Interfaccia web — UI responsive, dark theme, mobile-first
• 📡 API REST — endpoint per consumo programmatico e skill vocali (Alexa, Google Home)
• 🔧 MCP (Model Context Protocol) — server stdio per agent AI esterni
• 🗣️ TTS-ready — campo speakable_text ottimizzato per sintesi vocale

Tu chiedi → Query expansion → Ricerca multi-engine → Fetch pagine → Gemini sintesi → Risposta con fonti

---

📚 Documentazione

Documento	Descrizione
Architettura	🏗️ Visione d'insieme, stack tecnologico, componenti, modello dati
Diagramma di Flusso	🔄 Pipeline di ricerca, flusso richieste, macchina a stati (Mermaid)
API REST	📡 Documentazione completa degli endpoint /api/ask e /api/v1/query
Wiki	📚 FAQ, glossario, confronto con Perplexity, roadmap
Deployment	🚀 Guida al deployment in produzione (Gunicorn, Nginx, Docker, systemd)
Contributing	🤝 Guida per contribuire, convenzioni, test, struttura branch

---

🚀 Quick Start

# 1. Clona e installa
git clone https://github.com/tuo-user/sibilla.git
cd sibilla
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# 2. Avvia Degoog (motore di ricerca primary, opzionale ma consigliato)
docker run -d --name degoog -p 4444:4444 ghcr.io/degoog-org/degoog:latest

# 3. Configura
# Crea un file .env con la tua Google API Key:
#   GOOGLE_API_KEY=la-tua-api-key

# 4. Avvia
sibilla
# → http://127.0.0.1:5000

Prerequisiti minimi

• Python 3.10+
• Google API Key — ottienila gratis
• Almeno un motore di ricerca (Degoog, SearXNG, o DuckDuckGo automatico)

---

🔌 API

Ricerca via API (per skill Alexa, bot, app)

# GET — il più semplice
curl "http://localhost:5000/api/v1/query?q=ultimo+film+sull%27Odissea"

# POST — per query lunghe
curl -X POST http://localhost:5000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query": "quali sono i migliori ristoranti a Roma?"}'

# Estrai solo il testo per TTS
curl -s "http://localhost:5000/api/v1/query?q=raggi+cosmici" \
  | python -c "import sys,json; print(json.load(sys.stdin)['speakable_text'])"

Risposta:

{
    "query": "ultimo film sull'Odissea",
    "answer": "L'ultimo adattamento è **The Return** (2024)...",
    "speakable_text": "L'ultimo adattamento è The Return del 2024...",
    "sources": [{"index": 1, "title": "...", "url": "..."}],
    "model": "gemini-2.5-flash",
    "search_engine": "degoog",
    "tokens_used": 1847
}

Documentazione completa: docs/API.md

---

🏗️ Architettura

sibilla/
├── docs/                       # 📚 Documentazione
│   ├── ARCHITECTURE.md         # Architettura di sistema
│   ├── FLOW.md                 # Diagramma di flusso (Mermaid)
│   ├── API.md                  # Documentazione API REST
│   ├── WIKI.md                 # Wiki + FAQ
│   ├── DEPLOYMENT.md           # Guida al deployment
│   └── CONTRIBUTING.md         # Guida alla contribuzione
│
├── src/sibilla/                # 📦 Codice sorgente
│   ├── app.py                  # Flask app factory + pipeline condivisa
│   ├── search.py               # Degoog, SearXNG, DuckDuckGo, PageFetcher
│   ├── ai.py                   # GeminiClient (sintesi + query rewriting)
│   ├── markdown.py             # Markdown → HTML + strip per TTS
│   ├── prompts.py              # System prompt stile Perplexity
│   ├── mcp.py                  # MCP server stdio (per agent AI)
│   └── cli.py                  # Entry point server
│
├── templates/index.html        # Interfaccia web
├── static/                     # CSS, JS, favicon
├── tests/                      # Test (pytest, 109 test)
└── pyproject.toml              # Configurazione progetto

---

🔄 Pipeline di Ricerca

POST /api/ask {query: "..."}
  │
  ├─ 1. 🔮 Gemini riscrive la query in 3 varianti (query expansion)
  ├─ 2. 🔍 Multi-engine search: Degoog → SearXNG → DuckDuckGo (cascading)
  ├─ 3. 📥 PageFetcher scarica il contenuto completo delle top pagine
  ├─ 4. 📝 Prompt assembly con fonti numerate + data odierna
  ├─ 5. 🧠 Gemini sintesi con citazioni inline [1], [2], ...
  └─ 6. ✅ JSON {answer, html_answer, speakable_text, sources[], metadata}

---

🔧 MCP Server

Sibilla espone le sue capacità di ricerca come tool MCP (Model Context Protocol) su stdio:

sibilla-mcp

Tool disponibili:

• web_search(query, num_results) — ricerca web con fallback Degoog → SearXNG → DuckDuckGo
• fetch_page(url) — estrai contenuto testuale da una pagina web

Compatibile con client MCP come Claude Desktop, Gemini Desktop e altri agent AI.

---

🧪 Sviluppo

# Installa dipendenze dev
pip install -e ".[dev]"

# Lint
ruff check src tests

# Test
pytest tests/ -v

# Coverage
pip install pytest-cov
pytest tests/ --cov=src/sibilla --cov-report=html

---

🚀 Deployment

Per il deployment in produzione:

# Con Gunicorn
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 "sibilla.app:create_app()"

# Con Docker Compose (Sibilla + Degoog + SearXNG)
docker compose up -d

Guida completa: docs/DEPLOYMENT.md

---

📋 Configurazione

Crea un file .env:

GOOGLE_API_KEY=la-tua-api-key
SECRET_KEY=una-chiave-segreta-lunga-e-casuale
SIBILLA_HOST=127.0.0.1
SIBILLA_PORT=5000
SIBILLA_DEBUG=1
DEGOOG_URL=http://localhost:4444
SEARXNG_URL=http://localhost:8080
SIBILLA_DDG_FALLBACK=1

---

🤝 Contribuire

Contributi benvenuti! Vedi docs/CONTRIBUTING.md per:

• Setup dell'ambiente di sviluppo
• Convenzioni di codice e commit
• Come aggiungere search engine, endpoint, o tool MCP
• Struttura dei test

---

📄 Licenza

MIT — vedi il file LICENSE per i dettagli.

---

_{Fatto con 🔮 da Sibilla Team · Architettura · API · Deployment}