# ka2 — explorateur structuré du web québécois
### Édition légère · une plateforme du **Groupe KA**
**ka2** est un bot **scraper + recherche piloté par IA** qui cartographie le web québécois
sous forme de **graphe de connaissances** : entités (entreprises, organisations, personnes,
créateurs/influenceurs, agences, marques…), leurs **attributs** et leurs **relations typées**.
🌐 **Dashboard en direct : https://www.ka2.bot**
---
## ✨ Aperçu
| | |
|---|---|
|  |  |
| **Tableau de bord** temps réel (thème vert lime) | **Répertoire structuré** — graphe global interactif |
> Les captures ci-dessus utilisent `assets/ka2_dashboard.png` et `assets/ka2_explorer.png`.
---
## 🎯 Positionnement — Édition légère
Le Groupe KA opère trois bots jumeaux partageant le **même moteur**, à trois paliers :
| Bot | Palier | Contrôleur | Concurrence | Pages/jour | Thème |
|-----|--------|-----------|-------------|-----------|-------|
| ka2 | léger / économique | Haiku 4.5 | 6 | 800 | 🟢 vert lime |
| ka4 | agressif | Sonnet 5 | 10 | 3000 | 🔴 rouge |
| ka6 | **flagship** | Sonnet 5 | 16 | 9000 | 🟣 violet |
> **Ce dépôt = ka2** (Édition légère, thème vert lime).
---
## 🧠 Comment ça marche
```
┌──────────────────────────────────────────────┐
Missions ───────▶ │ Agent (Claude) — planifie, cherche, │
(dashboard) │ approfondit (deep_dive), pilote via outils │
└───────────────┬──────────────────────────────┘
│ outils
search_web / map_site / scrape_page / deep_dive / crawl_queue
│
┌─────────────────────────▼─────────────────────────┐
│ Firecrawl (principal) → Scrapfly (repli anti-bot) │
│ robots.txt + rate-limit + fail-fast + coupe-circuit│
└─────────────────────────┬─────────────────────────┘
│ markdown
┌────────────▼────────────┐
│ Extracteur (Haiku) │
│ → GRAPHE {entités, │
│ relations typées} │
└────────────┬────────────┘
│ résolution d'entités + provenance
┌────────────▼────────────┐
│ SQLite (WAL) │
│ entités · relations · │
│ liens sociaux · sources │
└────────────┬────────────┘
│ SSE temps réel
┌────────────▼────────────┐
│ Dashboard + Répertoire │
│ (FastAPI, 3 vues) │
└──────────────────────────┘
```
---
## 🚀 Fonctionnalités
- 🕸️ **Graphe de connaissances** — entités normalisées + **relations typées** (WORKS_AT, FOUNDER_OF,
REPRESENTED_BY, COLLABORATES_WITH, SPONSORED_BY, MEMBER_OF, PARTNER_OF…), avec rôle et provenance.
- 🧩 **Résolution d'entités / déduplication** (nom normalisé + domaine + région) et **régions QC canoniques**.
- 👤 **Modèle créateur/influenceur** — type `creator`/`agency`/`brand`, handle, plateforme, **abonnés**
(par plateforme), niche, langues.
- ⚡ **Crawling concurrent** (6 pages en parallèle) + **frontière agressive** (auto-découverte de liens).
- 🛟 **Robustesse** — timeouts fail-fast, **retries** par URL (dead-letter), **coupe-circuit** par domaine.
- 🧭 **Agent rigoureux** (plan → découverte → collecte → vérification) + **auto-compaction** du contexte.
- 🎛️ **Contrôles de mission** — arrêter la mission en cours, **lancer maintenant** (prioriser), supprimer.
- 🗄️ **Archives** — snapshot des données puis remise à zéro ; historique **restaurable / exportable**.
- 🖥️ **Dashboard temps réel (SSE)** — KPIs, flux d'activité, réglages en direct, thème vert lime, responsive.
- 🔎 **Répertoire structuré** — 3 vues : **Cartes**, **Tableau** triable, **Graphe global** (force-directed,
pan/zoom), facettes (type/secteur/région), recherche, **export CSV/JSON**.
- 🇶🇨 **Conforme** — robots.txt respecté, rate-limiting, note **Loi 25 (Québec) / LPRPDE**, données publiques.
---
## ⚙️ Configuration (`.env`)
| Variable | Rôle | Valeur (ka2) |
|---|---|---|
| `ANTHROPIC_API_KEY` | Clé Anthropic | — |
| `FIRECRAWL_API_KEY` | Clé Firecrawl | — |
| `SCRAPFLY_API_KEY` | Clé Scrapfly (repli) | — |
| `KA_BOT_MODEL` | Modèle contrôleur | `claude-haiku-4-5-20251001` |
| `KA_BOT_EXTRACT_MODEL` | Modèle extraction | `claude-haiku-4-5-20251001` |
| `KA_BOT_DB` | Base SQLite | `ka_bot.db` |
| `KA_BOT_CONCURRENCY` | Pages en parallèle | `6` |
| `KA_BOT_DELAY` | Délai entre requêtes (s) | `0.6` |
| `KA_BOT_MAX_PAGES` | Pages max / exécution | `120` |
| `KA_BOT_FRONTIER` | Liens auto-enfilés / page | `12–16` |
| `KA_BOT_MAX_ATTEMPTS` | Tentatives / URL | `2` |
| `KA_BOT_DOMAIN_FAILS` | Seuil coupe-circuit | `4` |
| `KA_BOT_AUTOSEED` | Pré-remplir des missions | `0` (off) |
> ⚠️ Le fichier `.env` (clés API) **n'est pas** versionné (`.gitignore`).
---
## 🏗️ Installation & exécution
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # renseigner les clés
# Dashboard (web)
uvicorn web.app:app --host 127.0.0.1 --port 8799
# Bot long terme (crawler)
python main.py run
# Modes ponctuels
python main.py pipeline --query "influenceurs beauté Québec"
python main.py agent --goal "Cartographier les agences d'influence de Montréal"
python main.py stats
python main.py export --out exports/entites.json
```
## ☁️ Déploiement (cluster MacLustr — node M4M36)
```bash
bash deploy/deploy.sh M4M36 8799 www.ka2.bot
```
Crée 3 services **launchd** résilients : `com.ka2.web`, `com.ka2.bot`, `com.ka2.ngrok`
(tunnel `--url=https://www.ka2.bot`, inspection ngrok sur `:4040` pour cohabiter avec les autres bots).
---
## 🔌 API principale
| Méthode | Route | Rôle |
|---|---|---|
| `GET` | `/health` | état du service |
| `GET` | `/api/stats` | compteurs + état session |
| `GET` | `/api/stream` | flux SSE (stats + événements) |
| `GET` | `/api/entities` | entités (filtres type/région/secteur, tri, pagination) |
| `GET` | `/api/entity/{id}` | fiche entité + relations |
| `GET` | `/api/graph` | nœuds + arêtes du graphe global |
| `GET` | `/api/export.{json,csv}` | export filtré |
| `POST` | `/api/missions` | ajouter une mission |
| `POST` | `/api/missions/{id}/{prioritize,delete}` | lancer maintenant / supprimer |
| `POST` | `/api/control/{pause,resume,skip,extend}` | contrôles bot |
| `POST` | `/api/archive` · `GET /api/archives` | archiver & vider · historique |
| `POST` | `/api/archive/{id}/{restore,delete}` | restaurer / supprimer archive |
---
## 🗃️ Modèle de données (SQLite)
`entities` (type, nom, canonical/norm, domaine, secteur, région, coordonnées, **niche/handle/plateforme/abonnés**,
provenance) · `relations` (from, to, type, rôle, source, confiance) · `social_links` (plateforme, url, abonnés) ·
`sources` · `entity_mentions` · `crawl_queue` · `missions` · `events` · `settings` · `archives`.
---
## ⚖️ Conformité & usage responsable
Données **publiques** uniquement · `robots.txt` respecté · rate-limiting · finalités légitimes (annuaire,
veille, recherche de marché). Encadré par la **Loi 25 (Québec)** et la **LPRPDE**. Ne pas constituer de
profils de personnes privées à des fins de surveillance ou de démarchage non sollicité.
---
**ka2** · une plateforme du **Groupe KA**
Auteur **Simon-Pierre Boucher** · ✉️ **contact@spboucher.ai**
*Zéro boîte noire — tout est automatisé, rien n'est inventé.*