API·Ka

La donnée de l'écosystème, par API

API·Ka (www.api-ka.com) est la plateforme de données centrale de l'écosystème Groupe KA. Chaque jour, 11 collecteurs (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-ka, job-ka, house-ka, rent-ka) sauvegardent les données des plateformes dans une base PostgreSQL unifiée (fetch → validation → checksum → insertion → backup → journal de run, retry 3× avec backoff 30 s → 2 min → 10 min), puis les exposent via une API FastAPI publique : données paginées, historiques par date, statistiques, rapports PDF.

Elle héberge aussi le KA Agent — l'assistant IA central du groupe (Claude Haiku 4.5, SSE, boucle de 34 outils branchés sur les API publiques des plateformes) servi en widget (/ka-agent.js) aux 13 domaines de l'écosystème — et sert de superviseur des connecteurs (~4 460 connecteurs suivis au 2026-08-28 : historique des collectes /api/v1/runs, santé par service, alertes). L'accès à l'API produit exige une authentification : session KA ID ou jeton personnel (kapi_, généré sur groupe-ka.com/compte).

# Chiffres live (au 2026-08-28)

Instantané de GET /api/stats et GET /health — les pastilles dynamiques ci-dessus restent à jour en continu.

Dernière collecte par service (2026-08-28) :

_{* creaka, restoka, autoka, foodka et houseka rapportaient 0 enregistrement pour la date du jour au moment de la capture (collectes différentielles / heure de passage) — le statut du run restait success. Les valeurs live sont sur /health.}

# Visite guidée

10 captures du 2026-08-28 (desktop 1440×900 · mobile 390×844), versionnées dans docs/screenshots/.

Accueil — « Toutes les données KA, centralisées chaque jour » Le héros de www.api-ka.com : badge « API opérationnelle · M3U96B », réponse live de GET /health (nœud, base, dernières collectes) et compteurs en direct.
Accueil · 01 — Sources Les services collectés en cartes : vocation, route /api/v1/{service}, enregistrements historisés et lien vers chaque plateforme Ka.	Accueil · 02 — Référence des endpoints Chaque endpoint documenté en place : description, paramètres, extraits curl / Python / JavaScript copiables et bouton « Essayer ».
Accueil — les endpoints d'historique /api/v1/{service}/latest et /api/v1/{service}/date/{YYYY-MM-DD} : paramètres requis/optionnels, pagination (limit max 500).	/stats — la supervision de la plateforme Appels API, latences moyenne et p95, taux d'erreur, collectes réussies/échouées, enregistrements — filtres de période et rapports PDF (complet, personnalisés).
/docs — l'API interactive (Swagger, OpenAPI 3.1) Tous les routeurs (health, auth, runs, monitoring, stats, services, agent…) avec schémas et essais en direct.	/doc — « Comment fonctionne API·Ka » Le guide public : vue d'ensemble (collecteurs quotidiens, retry 3× + backfill, backups 90 jours, KA Agent), téléchargeable en PDF.
/doc — la même page servie sur la route sans barre oblique finale Le guide reste accessible aux deux chemins (/doc et /doc/).	/contact — « Nous joindre » Les trois courriels officiels du Groupe KA (projets/partenariats, médias, légal & Loi 25) et le rappel que la connexion « Se connecter avec KA » est déléguée au hub KA ID.
Accueil — version mobile (390×844) Le même héros et le statut /health live, en colonne unique avec la nav mobile v2.

🗄️ Les captures du guide et du Swagger en WebP restent dans docs/screenshots/desktop/ et docs/screenshots/mobile/ ; les captures d'époque sont conservées dans docs/archive/.

# Nouveautés

• 2026-08-28 — Rent-Ka devient le 11ᵉ service : collecteur rentka (pagination offset/2000 comme lou-ka), table rentka_data, supervision des ~680 sources du connecteur au premier run (6c64acd).
• 2026-08-27 — House-Ka devient le 10ᵉ service : collecteur + modèle + CORS + supervision (17 sources) (eb543c9).
• KA Agent v3.2 — 34 outils (recherche fédérée, annuaires déménageurs/inspecteurs, agences immobilières, historique/coût réel/TAL logement, ValoPlex, KA Scores) ; cartes d'annonces construites côté serveur (afficher_cartes), lien public lien_fiche sur chaque résultat, reprise automatique après coupure max_tokens.
• Widget ka-agent v4 servi aux 13 domaines — cartes cliquables (ka-card) et choix en boutons (ka-choix).
• Monitoring des connecteurs — statut retired pour les sources désactivées ou disparues.
• Nav mobile v2 sur les pages web.

# Rôle central dans l'écosystème

API·Ka est le système nerveux du Groupe KA, avec trois missions :

1. API unifiée des plateformes — un seul point d'entrée versionné (/api/v1/{service}) pour les données quotidiennes historisées des 11 services : mêmes conventions de pagination, mêmes enveloppes JSON, mêmes checksums, quel que soit le service interrogé. C'est ce qui alimente l'app iOS KA, Ka·Stats, les rapports PDF et les intégrations internes.
2. Superviseur des connecteurs — la santé des ~4 460 connecteurs de collecte de tout l'écosystème (les sources de lou-ka, immo-ka, rent-ka, etc.) est agrégée ici (/api/v1/monitoring/connectors), avec statuts ok / degraded / broken / stale / retired, fenêtres de fraîcheur par service et alertes journalisées.
3. Agent conversationnel central — le KA Agent répond en langage naturel sur les 13 sites via un seul backend (SSE), en s'appuyant sur les données live des plateformes plutôt que sur la base historisée : ce que l'agent dit est ce que les sites affichent.

# Fonctionnalités

• 11 collecteurs quotidiens — un par plateforme Ka (Job-Ka intégré le 2026-08-18, House-Ka le 2026-08-27, Rent-Ka le 2026-08-28), avec validation, checksum, retry 3× (backoff exponentiel) et journal de run ; tout échec après 3 tentatives est loggé (collection_runs, logs/alerts.log).
• Scheduler APScheduler — job quotidien à 02:00 (collecteurs en parallèle et indépendants) + backfill automatique des dates manquées (7 derniers jours).
• API publique de données — GET /api/v1/{service} (pagination, limit max 500), /latest, /date/{YYYY-MM-DD}, /stats, /api/v1/runs (historique des collectes), pour {service} ∈ louka, immoka, foodka, autoka, fabrika, restoka, sortika, creaka, jobka, houseka, rentka.
• Authentification obligatoire sur l'API produit — session KA ID ou jeton Bearer kapi_ ; monitoring, stats et agent restent ouverts.
• KA Agent (IA) — POST /api/agent/chat en SSE (Claude Haiku 4.5, boucle de 34 outils sur les données live des plateformes : logements, propriétés, véhicules, rappels, emplois, épicerie et comparateur de prix, produits et boutiques QC, restos, plats, menus, inspections MAPAQ, sorties, créateurs, recherche web Québec, recherche globale fédérée, suggestions, facettes, fiches détail, estimateurs Vrai-Prix et ValoPlex, annuaires déménageurs/inspecteurs, agences immobilières, historique/coût réel/TAL logement, KA Scores, cartes d'annonces serveur, stats et état des services) + recherche floue en cascade + widget embarquable GET /ka-agent.js (v4 : bulle déplaçable, position mémorisée par site, cartes cliquables et boutons de choix), CORS ouvert aux 13 domaines.
• SSO KA ID — GET /api/auth/ka/{login,callback}, session /api/auth/me, et échange de jeton pour les apps natives (POST /api/ios/auth/exchange, vérification HS256, aud ∈ ka-ios, ka-android).
• Stats & rapports — tableau de bord /stats, GET /api/stats (KPI compact JSON), GET /api/stats/report (PDF de la plateforme) et GET /api/stats/ecosystem-report (rapport PDF consolidé de l'écosystème, liste dynamique via ecosystem.json) + rapports PDF personnalisés (catalogue + constructeur).
• Recherche transversale — GET /api/v1/search + GET /api/v1/suggest (proxy du moteur Trouve-Ka, pivot moteur de recherche Groupe KA).
• Backups quotidiens horodatés par service (data/backups/YYYY-MM-DD/, rétention 90 jours).
• Santé & supervision — GET /health (nœud, état DB, dernière collecte par service, compteurs de connecteurs) ; chaque service vérifie le hostname au démarrage et refuse de tourner en production ailleurs que sur m3u96b.
• SEO du site de doc — robots.txt, sitemap.xml, canonical/hreflang/JSON-LD.

# Authentification

Deux façons d'accéder à l'API produit — aucun secret n'est stocké dans ce repo :

• Session KA ID (SSO) — le bouton « Se connecter avec KA » délègue au hub groupe-ka.com (compte unique de l'écosystème) : GET /api/auth/ka/login → callback → session serveur, introspectable via GET /api/auth/me.
• Jeton personnel kapi_ — généré (et révocable) sur groupe-ka.com/compte, passé en en-tête Authorization: Bearer kapi_…. C'est la voie recommandée pour les scripts et intégrations.
• Endpoints exemptés (publics sans authentification) : GET /health, GET /api/stats, la supervision (/api/v1/runs, /api/v1/monitoring/*), les pages web et le KA Agent (/api/agent/chat, /ka-agent.js).
• Apps natives : POST /api/ios/auth/exchange échange le jeton du hub contre une session API (HS256, aud ka-ios / ka-android).
• Rate-limit global : 120 req/min.

# API (endpoints principaux)

Référence interactive complète : Swagger sur /docs. 🔒 = session KA ID ou jeton Bearer kapi_ requis.

# Architecture

• FastAPI + Uvicorn (src/api/) : 9 routeurs (health, auth, runs, monitoring, stats, search, services, agent, iosauth) + pages web et PDF (fpdf2).
• PostgreSQL via SQLAlchemy 2 (+ Alembic pour les migrations, psycopg2) : une table de données par service ({service}_data) + journal collection_runs.
• Collecteurs (src/collectors/) : classe abstraite base_collector (fetch, validate, save, retry) + 11 collecteurs concrets, httpx.
• Scheduler (src/scheduler/) : daily_job.py (02:00) + backfill.py.
• Utils (src/utils/) : backups quotidiens, rétention 90 jours ; src/monitoring/ pour la supervision (connector_health sonde les 11 apps).
• anthropic SDK pour le KA Agent.

Collecteurs et cadence :

Processus PM2 sur le nœud (commandes de start réelles) :

# Démarrage rapide

git clone gitsrv:api-ka.git && cd api-ka
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                             # puis remplir les valeurs

python -m src.database.db --init                 # initialiser la base PostgreSQL
uvicorn src.api.main:app --reload --port 8000    # API en dev → http://127.0.0.1:8000
python -m src.scheduler.daily_job --now          # collecte manuelle immédiate
python -m src.scheduler.backfill --date 2026-08-15
pytest tests/ -v                                 # modules de tests (api, collectors, retry, backfill, search, stats, connector_health)

# Variables d'environnement

Déclarées dans .env.example (copier vers .env, jamais commité — aucun secret dans le repo) :

# Données & conformité

• Provenance : les données proviennent exclusivement des API publiques des 11 plateformes Ka (aucun scraping tiers dans ce repo) ; chaque enregistrement passe par validation + checksum avant insertion.
• Cadence : resynchronisation quotidienne à 02:00 (collecteurs parallèles) + backfill automatique des 7 derniers jours ; backups quotidiens horodatés, rétention 90 jours.
• Accès : l'API produit exige une authentification (session KA ID ou jeton kapi_ révocable sur groupe-ka.com/compte) ; monitoring, stats et agent restent publics ; rate-limit 120 req/min.
• Traçabilité : chaque run de collecte est journalisé (collection_runs, exposé via /api/v1/runs) ; alertes dans logs/alerts.log.

# Structure du repo

/opt/api-ka
├── src/          # api/ (routes, web, PDF), collectors/ (11), scheduler/, database/, monitoring/, utils/, config.py
├── scripts/      # deploy_m3u96b.sh, healthcheck.sh, run_daily_backup.sh, start_ngrok.sh…
├── systemd/      # unités historiques (le déploiement actuel utilise PM2)
├── tests/        # pytest (api, backfill, collectors, connector_health, retry, search, stats)
├── data/         # backups/YYYY-MM-DD/ (rétention 90 jours)
├── logs/         # logs centralisés + alerts.log
├── docs/         # screenshots/ (visite guidée + desktop/mobile WebP) · archive/
└── alembic.ini · pyproject.toml · requirements.txt · CLAUDE.md

# Documentation

• Guide en ligne : www.api-ka.com/doc/ — à quoi sert la plateforme, le parcours en 3 étapes (site de doc → Swagger /docs → supervision /stats), d'où viennent les données, FAQ.
• Guide PDF : api-ka-documentation.pdf — la même documentation, téléchargeable.
• Swagger interactif : www.api-ka.com/docs — tous les endpoints, schémas et essais en direct.
• Les captures du guide sont versionnées dans src/api/web/doc/img/ (etape1 → etape3).

# Historique

# Développement (remote-first)

La source de vérité est le repo git sur le nœud M3U96b (/opt/api-ka) — on n'édite jamais les copies laptop. Toute modification se fait sur le nœud via SSH : édition, tests, pm2 restart, puis commit/push depuis le nœud.

• Remote origin = spbgit (git perso git.spboucher.ai, bare repos sur M3U96a). Pas GitHub.
• L'agent forwarding SSH est actif : le git push origin main fonctionne pendant une session SSH depuis le laptop.
• Chaque fichier du dépôt porte l'en-tête d'auteur obligatoire (voir CLAUDE.md).

pm2 restart apika-api                            # après un changement en production

# Déploiement

• Nœud : M3U96b (Mac Studio, cluster MacLustr) — répertoire /opt/api-ka (hostname vérifié au démarrage)
• Port : 8000 (API liée à 127.0.0.1, exposée uniquement via le tunnel)
• Processus PM2 : apika-api (API) + apika-scheduler (collectes) + apika-ngrok (tunnel)
• Domaine : https://www.api-ka.com (tunnel ngrok)

# Écosystème Groupe KA

# Contact

Simon-Pierre Boucher — fondateur, Groupe KA 📧 contact@spboucher.ai

© Groupe KA — Simon-Pierre Boucher · contact@spboucher.ai Ce repo vit sur spbgit (git.spboucher.ai).