Initial commit: Sibilla — self-hosted Perplexity-like AI search engine

- Flask web app with Perplexity-style search + synthesis pipeline
- Degoog → SearXNG → DuckDuckGo cascading search backends
- Gemini LLM for query expansion + answer synthesis with citations
- MCP server exposing search tools via stdio
- 57 unit tests covering all modules

README.md

@@ -5,33 +5,46 @@
 
 **Sibilla** è un motore di ricerca AI self-hosted che combina:
 
-- 🧠 **Google Gemini API** — modelli linguistici avanzati con grounding su web search
-- 🔧 **MCP (Model Context Protocol)** — tool use per estendere le capacità dell'AI
-- 🔍 **Web search integrata** — ricerca e sintesi delle fonti in tempo reale
+- 🧠 **Google Gemini** — LLM per sintesi e query expansion
+- 🔍 **Degoog** — metasearch engine self-hosted (primary) con MCP nativo
+- 🔄 **SearXNG + DuckDuckGo** — fallback a cascata se Degoog non risponde
+- 🔧 **MCP (Model Context Protocol)** — server stdio per agent AI esterni
 - 🖥️ **Flask web app** — interfaccia pulita e reattiva
 
 ```
-Tu chiedi → Sibilla cerca nel web → Sintetizza le fonti → Ti risponde con citazioni
+Tu chiedi → Query expansion → Degoog search → Fetch pagine → Gemini sintesi → Risposta con fonti
 ```
 
-## Architettura (pianificata)
+## Architettura
 
 ```
 sibilla/
 ├── src/sibilla/
-│   ├── app.py          # Flask app factory
-│   ├── cli.py          # Entry point
-│   ├── search.py       # Web search + scraping
-│   ├── ai.py           # Google Gemini API client
-│   ├── mcp.py          # MCP tool integration
-│   └── prompts.py      # Prompt templates
+│   ├── app.py          # Flask app factory + pipeline /api/ask
+│   ├── cli.py          # Entry point server web
+│   ├── search.py       # DegoogClient, SearXNGClient, DuckDuckGoClient, PageFetcher
+│   ├── ai.py           # GeminiClient (sintesi + query rewriting)
+│   ├── mcp.py          # MCP server su stdio (per agent AI esterni)
+│   └── prompts.py      # System prompt stile Perplexity
 ├── templates/
 │   └── index.html      # Interfaccia di ricerca
 ├── static/
-│   ├── style.css       # Stili
+│   ├── style.css       # Stili dark theme
 │   └── app.js          # Logica frontend
 └── tests/
-    └── ...
+```
+
+## Pipeline di ricerca
+
+```
+POST /api/ask {query: "..."}
+  │
+  ├─ 1. Gemini riscrive la query in 3 varianti (query expansion)
+  ├─ 2. Multi-query search: Degoog → SearXNG → DuckDuckGo (cascading)
+  ├─ 3. PageFetcher scarica il contenuto completo delle top pagine
+  ├─ 4. Prompt assembly con fonti numerate
+  ├─ 5. Gemini sintesi con citazioni [1], [2], ...
+  └─ 6. JSON {answer, sources[], model, search_engine, tokens_used}
 ```
 
 ## Setup
@@ -43,30 +56,44 @@ source .venv/bin/activate
 pip install -e ".[dev]"
 ```
 
-Crea un file `.env` con la tua API key Google:
+### Prerequisiti
 
+1. **Google API Key** — [https://aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+2. **Degoog** (consigliato) — motore di ricerca primary:
+   ```bash
+   docker run -d --name degoog -p 4444:4444 ghcr.io/degoog-org/degoog:latest
+   ```
+3. **SearXNG** (opzionale, fallback) — se vuoi un secondo motore di backup:
+   ```bash
+   docker run -d -p 8080:8080 searxng/searxng
+   ```
+
+Crea un file `.env`:
+
+```env
+GOOGLE_API_KEY=la-tua-api-key
+DEGOOG_URL=http://localhost:4444
 ```
-GOOGLE_API_KEY=your-api-key-here
-```
+
+Senza Degoog, Sibilla userà automaticamente SearXNG e DuckDuckGo come fallback.
 
 ## Uso
 
 ```bash
-# Avvia il server
+# Avvia la web app
 sibilla
+# → http://127.0.0.1:5000
 
-# Oppure
-python -m sibilla
+# Avvia il server MCP (per agent AI esterni)
+sibilla-mcp
 ```
 
-Poi apri http://127.0.0.1:5000 nel browser.
-
 ## Sviluppo
 
 ```bash
-pip install -e ".[dev]"
-pytest
+pip install -e ".[dev,mcp]"
 ruff check src tests
+pytest
 ```
 
 ## Licenza