# 🔮 Sibilla

> *L'oracolo AI che cerca nel web e risponde alle tue domande.*
> Self-hosted Perplexity-like search engine.

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

- 🧠 **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 → Query expansion → Degoog search → Fetch pagine → Gemini sintesi → Risposta con fonti
```

## Architettura

```
sibilla/
├── src/sibilla/
│   ├── 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 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

```bash
cd sibilla
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

### 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
```

Senza Degoog, Sibilla userà automaticamente SearXNG e DuckDuckGo come fallback.

## Uso

```bash
# Avvia la web app
sibilla
# → http://127.0.0.1:5000

# Avvia il server MCP (per agent AI esterni)
sibilla-mcp
```

## Sviluppo

```bash
pip install -e ".[dev,mcp]"
ruff check src tests
pytest
```

## Licenza

MIT