spb/ka2 Public
ka2 — explorateur structuré du web québécois (édition légère, Groupe KA). Bot scraper+IA → graphe de connaissances. Claude Haiku + Firecrawl/Scrapfly.
Python 98.1%
Shell 1.9%
1<div align="center">23# ka2 — explorateur structuré du web québécois4### Édition légère · une plateforme du **Groupe KA**567891011121314151617181920**ka2** est un bot **scraper + recherche piloté par IA** qui cartographie le web québécois21sous forme de **graphe de connaissances** : entités (entreprises, organisations, personnes,22créateurs/influenceurs, agences, marques…), leurs **attributs** et leurs **relations typées**.2324🌐 **Dashboard en direct : https://www.ka2.bot**2526</div>2728---2930## ✨ Aperçu3132| | |33|---|---|34|  |  |35| **Tableau de bord** temps réel (thème vert lime) | **Répertoire structuré** — graphe global interactif |3637> Les captures ci-dessus utilisent `assets/ka2_dashboard.png` et `assets/ka2_explorer.png`.3839---4041## 🎯 Positionnement — Édition légère4243Le Groupe KA opère trois bots jumeaux partageant le **même moteur**, à trois paliers :4445| Bot | Palier | Contrôleur | Concurrence | Pages/jour | Thème |46|-----|--------|-----------|-------------|-----------|-------|47| ka2 | léger / économique | Haiku 4.5 | 6 | 800 | 🟢 vert lime |48| ka4 | agressif | Sonnet 5 | 10 | 3000 | 🔴 rouge |49| ka6 | **flagship** | Sonnet 5 | 16 | 9000 | 🟣 violet |5051> **Ce dépôt = ka2** (Édition légère, thème vert lime).5253---5455## 🧠 Comment ça marche5657```58 ┌──────────────────────────────────────────────┐59 Missions ───────▶ │ Agent (Claude) — planifie, cherche, │60 (dashboard) │ approfondit (deep_dive), pilote via outils │61 └───────────────┬──────────────────────────────┘62 │ outils63 search_web / map_site / scrape_page / deep_dive / crawl_queue64 │65 ┌─────────────────────────▼─────────────────────────┐66 │ Firecrawl (principal) → Scrapfly (repli anti-bot) │67 │ robots.txt + rate-limit + fail-fast + coupe-circuit│68 └─────────────────────────┬─────────────────────────┘69 │ markdown70 ┌────────────▼────────────┐71 │ Extracteur (Haiku) │72 │ → GRAPHE {entités, │73 │ relations typées} │74 └────────────┬────────────┘75 │ résolution d'entités + provenance76 ┌────────────▼────────────┐77 │ SQLite (WAL) │78 │ entités · relations · │79 │ liens sociaux · sources │80 └────────────┬────────────┘81 │ SSE temps réel82 ┌────────────▼────────────┐83 │ Dashboard + Répertoire │84 │ (FastAPI, 3 vues) │85 └──────────────────────────┘86```8788---8990## 🚀 Fonctionnalités9192- 🕸️ **Graphe de connaissances** — entités normalisées + **relations typées** (WORKS_AT, FOUNDER_OF,93 REPRESENTED_BY, COLLABORATES_WITH, SPONSORED_BY, MEMBER_OF, PARTNER_OF…), avec rôle et provenance.94- 🧩 **Résolution d'entités / déduplication** (nom normalisé + domaine + région) et **régions QC canoniques**.95- 👤 **Modèle créateur/influenceur** — type `creator`/`agency`/`brand`, handle, plateforme, **abonnés**96 (par plateforme), niche, langues.97- ⚡ **Crawling concurrent** (6 pages en parallèle) + **frontière agressive** (auto-découverte de liens).98- 🛟 **Robustesse** — timeouts fail-fast, **retries** par URL (dead-letter), **coupe-circuit** par domaine.99- 🧭 **Agent rigoureux** (plan → découverte → collecte → vérification) + **auto-compaction** du contexte.100- 🎛️ **Contrôles de mission** — arrêter la mission en cours, **lancer maintenant** (prioriser), supprimer.101- 🗄️ **Archives** — snapshot des données puis remise à zéro ; historique **restaurable / exportable**.102- 🖥️ **Dashboard temps réel (SSE)** — KPIs, flux d'activité, réglages en direct, thème vert lime, responsive.103- 🔎 **Répertoire structuré** — 3 vues : **Cartes**, **Tableau** triable, **Graphe global** (force-directed,104 pan/zoom), facettes (type/secteur/région), recherche, **export CSV/JSON**.105- 🇶🇨 **Conforme** — robots.txt respecté, rate-limiting, note **Loi 25 (Québec) / LPRPDE**, données publiques.106107---108109## ⚙️ Configuration (`.env`)110111| Variable | Rôle | Valeur (ka2) |112|---|---|---|113| `ANTHROPIC_API_KEY` | Clé Anthropic | — |114| `FIRECRAWL_API_KEY` | Clé Firecrawl | — |115| `SCRAPFLY_API_KEY` | Clé Scrapfly (repli) | — |116| `KA_BOT_MODEL` | Modèle contrôleur | `claude-haiku-4-5-20251001` |117| `KA_BOT_EXTRACT_MODEL` | Modèle extraction | `claude-haiku-4-5-20251001` |118| `KA_BOT_DB` | Base SQLite | `ka_bot.db` |119| `KA_BOT_CONCURRENCY` | Pages en parallèle | `6` |120| `KA_BOT_DELAY` | Délai entre requêtes (s) | `0.6` |121| `KA_BOT_MAX_PAGES` | Pages max / exécution | `120` |122| `KA_BOT_FRONTIER` | Liens auto-enfilés / page | `12–16` |123| `KA_BOT_MAX_ATTEMPTS` | Tentatives / URL | `2` |124| `KA_BOT_DOMAIN_FAILS` | Seuil coupe-circuit | `4` |125| `KA_BOT_AUTOSEED` | Pré-remplir des missions | `0` (off) |126127> ⚠️ Le fichier `.env` (clés API) **n'est pas** versionné (`.gitignore`).128129---130131## 🏗️ Installation & exécution132133```bash134python3 -m venv .venv && source .venv/bin/activate135pip install -r requirements.txt136cp .env.example .env # renseigner les clés137138# Dashboard (web)139uvicorn web.app:app --host 127.0.0.1 --port 8799140141# Bot long terme (crawler)142python main.py run143144# Modes ponctuels145python main.py pipeline --query "influenceurs beauté Québec"146python main.py agent --goal "Cartographier les agences d'influence de Montréal"147python main.py stats148python main.py export --out exports/entites.json149```150151## ☁️ Déploiement (cluster MacLustr — node M4M36)152153```bash154bash deploy/deploy.sh M4M36 8799 www.ka2.bot155```156157Crée 3 services **launchd** résilients : `com.ka2.web`, `com.ka2.bot`, `com.ka2.ngrok`158(tunnel `--url=https://www.ka2.bot`, inspection ngrok sur `:4040` pour cohabiter avec les autres bots).159160---161162## 🔌 API principale163164| Méthode | Route | Rôle |165|---|---|---|166| `GET` | `/health` | état du service |167| `GET` | `/api/stats` | compteurs + état session |168| `GET` | `/api/stream` | flux SSE (stats + événements) |169| `GET` | `/api/entities` | entités (filtres type/région/secteur, tri, pagination) |170| `GET` | `/api/entity/{id}` | fiche entité + relations |171| `GET` | `/api/graph` | nœuds + arêtes du graphe global |172| `GET` | `/api/export.{json,csv}` | export filtré |173| `POST` | `/api/missions` | ajouter une mission |174| `POST` | `/api/missions/{id}/{prioritize,delete}` | lancer maintenant / supprimer |175| `POST` | `/api/control/{pause,resume,skip,extend}` | contrôles bot |176| `POST` | `/api/archive` · `GET /api/archives` | archiver & vider · historique |177| `POST` | `/api/archive/{id}/{restore,delete}` | restaurer / supprimer archive |178179---180181## 🗃️ Modèle de données (SQLite)182183`entities` (type, nom, canonical/norm, domaine, secteur, région, coordonnées, **niche/handle/plateforme/abonnés**,184provenance) · `relations` (from, to, type, rôle, source, confiance) · `social_links` (plateforme, url, abonnés) ·185`sources` · `entity_mentions` · `crawl_queue` · `missions` · `events` · `settings` · `archives`.186187---188189## ⚖️ Conformité & usage responsable190191Données **publiques** uniquement · `robots.txt` respecté · rate-limiting · finalités légitimes (annuaire,192veille, recherche de marché). Encadré par la **Loi 25 (Québec)** et la **LPRPDE**. Ne pas constituer de193profils de personnes privées à des fins de surveillance ou de démarchage non sollicité.194195---196197<div align="center">198199**ka2** · une plateforme du **Groupe KA**200Auteur **Simon-Pierre Boucher** · ✉️ **contact@spboucher.ai**201*Zéro boîte noire — tout est automatisé, rien n'est inventé.*202203</div>204