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
This commit is contained in:
Sibilla committed
1 parent
f3fe13c60e
commit
76bc667adf
20 files changed
+3385
-245
No files matched your search
@@ -0,0 +1,217 @@
|
||||
# 🤝 Sibilla — Guida alla Contribuzione
|
||||
|
||||
> **Versione:** 0.2.0
|
||||
> **Ultimo aggiornamento:** 18 Luglio 2026
|
||||
|
||||
---
|
||||
|
||||
Grazie per il tuo interesse a contribuire a Sibilla! 🎉
|
||||
|
||||
## Codice di Condotta
|
||||
|
||||
Sii rispettoso, costruttivo e inclusivo. Tratta gli altri come vorresti essere trattato.
|
||||
|
||||
---
|
||||
|
||||
## Come Contribuire
|
||||
|
||||
### 1. Segnala un Bug
|
||||
|
||||
Apri una **issue** su GitHub con:
|
||||
|
||||
- **Titolo descrittivo** (es. "Errore 502 quando Degoog è lento")
|
||||
- **Passi per riprodurre il bug**
|
||||
- **Comportamento atteso** vs **comportamento osservato**
|
||||
- **Log di errore** (se disponibili)
|
||||
- **Ambiente:** versione Python, OS, versione Sibilla
|
||||
|
||||
### 2. Proponi una Feature
|
||||
|
||||
Apri una issue con il tag `enhancement` descrivendo:
|
||||
|
||||
- **Problema che risolve**
|
||||
- **Soluzione proposta**
|
||||
- **Alternative considerate**
|
||||
- **Impatto sul codice esistente**
|
||||
|
||||
### 3. Invia una Pull Request
|
||||
|
||||
#### Setup sviluppo
|
||||
|
||||
```bash
|
||||
# 1. Forka il repository
|
||||
# 2. Clona il tuo fork
|
||||
git clone https://github.com/tuo-user/sibilla.git
|
||||
cd sibilla
|
||||
|
||||
# 3. Aggiungi l'upstream
|
||||
git remote add upstream https://github.com/original/sibilla.git
|
||||
|
||||
# 4. Crea ambiente virtuale
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 5. Installa dipendenze di sviluppo
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# 6. Configura .env
|
||||
cp .env.example .env
|
||||
nano .env # Inserisci GOOGLE_API_KEY
|
||||
```
|
||||
|
||||
#### Flusso di lavoro
|
||||
|
||||
```bash
|
||||
# 1. Sincronizza con upstream
|
||||
git fetch upstream
|
||||
git checkout master
|
||||
git merge upstream/master
|
||||
|
||||
# 2. Crea un branch
|
||||
git checkout -b feature/nome-feature
|
||||
# oppure
|
||||
git checkout -b fix/nome-bug
|
||||
|
||||
# 3. Sviluppa
|
||||
# ... scrivi codice ...
|
||||
|
||||
# 4. Testa
|
||||
pytest tests/ -v
|
||||
|
||||
# 5. Linta
|
||||
ruff check src tests
|
||||
|
||||
# 6. Committa con messaggi chiari
|
||||
git add .
|
||||
git commit -m "feat: aggiungi caching risposte con Redis"
|
||||
|
||||
# 7. Pusha
|
||||
git push origin feature/nome-feature
|
||||
|
||||
# 8. Apri Pull Request su GitHub
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Convenzioni del Codice
|
||||
|
||||
### Stile
|
||||
|
||||
- **Python 3.10+** con type hints
|
||||
- **Ruff** per linting e formattazione (`ruff check src tests`)
|
||||
- **Line length:** 100 caratteri
|
||||
- **Docstring:** stile Google (`"""Descrizione breve.` con `Args:`, `Returns:`, `Raises:`)
|
||||
|
||||
### Commit Messages
|
||||
|
||||
Usiamo [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
feat: aggiungi caching risposte con Redis
|
||||
fix: correggi race condition in PageFetcher
|
||||
docs: aggiorna README con esempi API v1
|
||||
refactor: estrai pipeline condivisa in helper
|
||||
test: aggiungi test per strip_markdown
|
||||
chore: aggiorna dipendenze
|
||||
```
|
||||
|
||||
### Struttura dei Branch
|
||||
|
||||
| Prefisso | Uso |
|
||||
|----------|-----|
|
||||
| `feature/` | Nuove funzionalità |
|
||||
| `fix/` | Bug fix |
|
||||
| `docs/` | Documentazione |
|
||||
| `refactor/` | Refactoring |
|
||||
| `test/` | Test |
|
||||
| `chore/` | Manutenzione |
|
||||
|
||||
---
|
||||
|
||||
## Test
|
||||
|
||||
### Esecuzione
|
||||
|
||||
```bash
|
||||
# Tutti i test
|
||||
pytest tests/ -v
|
||||
|
||||
# Test specifico
|
||||
pytest tests/test_app.py -v
|
||||
|
||||
# Con coverage
|
||||
pip install pytest-cov
|
||||
pytest tests/ --cov=src/sibilla --cov-report=html
|
||||
```
|
||||
|
||||
### Scrivere Test
|
||||
|
||||
- **Nuove feature = nuovi test.** Ogni endpoint, funzione pubblica e classe deve essere testata.
|
||||
- **Naming:** `test_<funzione>_<scenario>()` (es. `test_strip_markdown_with_images`)
|
||||
- **Fixtures:** usa `create_app(testing=True)` per testare senza `.env`
|
||||
|
||||
Esempio:
|
||||
|
||||
```python
|
||||
def test_api_v1_query_returns_speakable_text(client):
|
||||
"""Verifica che /api/v1/query includa speakable_text."""
|
||||
# Dato che Gemini non è configurato, verifica la risposta di errore
|
||||
resp = client.get("/api/v1/query?q=test")
|
||||
data = resp.get_json()
|
||||
assert "speakable_text" in data
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pipeline di Ricerca
|
||||
|
||||
Per aggiungere un nuovo passaggio alla pipeline:
|
||||
|
||||
1. **Identifica il punto di inserimento** in `_run_search_pipeline()` in `app.py`
|
||||
2. **Implementa la logica** in una funzione o classe separata
|
||||
3. **Aggiungi test** per il nuovo comportamento
|
||||
4. **Documenta** in `docs/ARCHITECTURE.md`
|
||||
|
||||
### Aggiungere un Search Engine
|
||||
|
||||
1. Crea una classe in `search.py` che implementi `search(query, num_results) → SearchResponse`
|
||||
2. Aggiungi il client in `_run_search_pipeline()` nella catena di fallback
|
||||
3. Aggiungi test in `tests/test_search.py`
|
||||
|
||||
```python
|
||||
class MySearchClient:
|
||||
def search(self, query: str, num_results: int = 8) -> SearchResponse:
|
||||
# ... implementazione ...
|
||||
return SearchResponse(query=query, results=results, engine="myengine")
|
||||
```
|
||||
|
||||
### Aggiungere un Endpoint API
|
||||
|
||||
1. Aggiungi una route in `app.py`
|
||||
2. Riutilizza `_run_search_pipeline()` per la logica condivisa
|
||||
3. Aggiungi test in `tests/test_app.py`
|
||||
|
||||
```python
|
||||
@app.route("/api/v2/custom", methods=["POST"])
|
||||
def api_v2_custom():
|
||||
# ... usa _run_search_pipeline() ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentazione
|
||||
|
||||
La documentazione vive in `docs/`. Quando modifichi una funzionalità, aggiorna:
|
||||
|
||||
- `docs/API.md` — se modifichi endpoint o formati di risposta
|
||||
- `docs/ARCHITECTURE.md` — se modifichi l'architettura
|
||||
- `docs/FLOW.md` — se modifichi la pipeline
|
||||
- `docs/WIKI.md` — per FAQ e roadmap
|
||||
|
||||
---
|
||||
|
||||
## Domande?
|
||||
|
||||
Apri una issue su GitHub o contatta i maintainer.
|
||||
|
||||
Grazie per contribuire a Sibilla! 🔮
|
||||
Reference in new issue
Block a user