# Assistant data conversationnel

Questions métier en français sur les ventes (`bigquery-public-data.thelook_ecommerce`) → couche sémantique (`semantique.yaml`) → SQL paramétré, validé (dry-run, ≤ 1 Go, lecture seule, liste blanche) → résultat, graphique Vega-Lite, limites et questions de suite. Agent Google ADK, Gemini sur Vertex AI, interface FastAPI.

## Prérequis
Python 3.10+, `gcloud` connecté (`gcloud auth application-default login`), un projet Google Cloud avec BigQuery et Vertex AI activés. Docker pour `make cloud-up`.

## Premier usage
```bash
make setup          # .venv + dépendances + .env (renseignez GOOGLE_CLOUD_PROJECT)
make test           # 57 tests, sans clé ni réseau
make run            # http://localhost:8080
make e2e            # 20 questions de référence contre le vrai modèle et le vrai BigQuery
make cloud-up       # Cloud Run privé (compte de service dédié, dépôt d'images dédié)
make cloud-status
```

**Nettoyage : `make cloud-down` (supprime service, image, dépôt, compte de service et rôles, puis vérifie), puis `make reset`.**

## Coûts estimés
- `make e2e` : environ 60 appels Gemini 2.5 Flash et ~40 requêtes BigQuery de 10 à 40 Mo facturés chacune (minimum de 10 Mo par table lue). Moins d'un centime de BigQuery (et 0 dans le Tio gratuit mensuel), quelques centimes de Gemini.
- `make cloud-up` : Cloud Run sans instance minimale, facturé à l'usage ; quelques centimes pour un test, à condition de lancer `make cloud-down` ensuite. Artifact Registry : ~0,1 $/Go/mois de stockage tant que l'image existe.

## Sans `make` (Windows)
```powershell
python -m venv .venv; .venv\Scripts\pip install -r requirements.txt; copy .env.example .env
.venv\Scripts\python -m pytest                       # make test
.venv\Scripts\python -m uvicorn assistant.web:app --port 8080   # make run
.venv\Scripts\python -m eval.evaluer                 # make e2e
```
`cloud-up` / `cloud-down` sont des scripts bash (`infra/`) : utilisez Cloud Shell ou WSL.

## Arborescence
`semantique.yaml` (métriques, dimensions, jointures) · `assistant/` (compilateur, garde-fous, graphiques, agent, API) · `web/` (interface) · `eval/` (20 questions, SQL de référence écrit à la main) · `tests/` · `infra/` (déploiement, nettoyage) · `ci/` (GitHub Actions) · `linkedin/` (kit de publication).