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, 8 collecteurs (lou-ka, immo-ka, food-ka, auto-ka, fabri-ka, resto-ka, sorti-ka, crea-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, SSE, boucle d'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 (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).

# Visite guidée

Accueil — le site de documentation de l'API (desktop)	Accueil — version mobile
Étape 1 · Explorez le site de documentation	Étape 2 · Parcourez l'API dans Swagger (/docs)
Étape 3 · Surveillez les collectes sur /stats

# Fonctionnalités

• 8 collecteurs quotidiens — un par plateforme Ka, 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.
• 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, boucle d'outils sur les données live des plateformes : logements, propriétés, véhicules, emplois, épicerie, produits, restos, sorties, créateurs, stats, état des services) + widget embarquable GET /ka-agent.js, CORS ouvert aux 13 domaines.
• SSO KA ID — GET /api/auth/ka/{login,callback}, session /api/auth/me, et échange de jeton pour l'app iOS native (POST /api/ios/auth/exchange, vérification HS256 aud=ka-ios).
• Stats & rapports — tableau de bord /stats, 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).
• 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) ; 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.

# 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/) : routes health, services, runs, monitoring, stats, search, agent, auth, iosauth + pages web et PDF (fpdf2).
• PostgreSQL via SQLAlchemy 2 (+ Alembic pour les migrations, psycopg2) : une table de données par service + journal collection_runs.
• Collecteurs (src/collectors/) : classe abstraite base_collector (fetch, validate, save, retry) + 8 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.
• anthropic SDK pour le KA Agent.

Collecteurs et cadence :

Processus PM2 sur le nœud :

Points de configuration notables (src/config.py, variables d'environnement — aucun secret dans le repo) : URL PostgreSQL, clé Anthropic du KA Agent, secret SSO partagé avec le hub KA ID, garde-fou de hostname (m3u96b).

# Structure du repo

/opt/api-ka
├── src/          # api/ (routes, web, PDF), collectors/ (8), scheduler/, database/, monitoring/, utils/, config.py
├── scripts/      # deploy_m3u96b.sh, start_ngrok.sh…
├── systemd/      # unités historiques (le déploiement actuel utilise PM2)
├── tests/        # pytest
├── data/         # backups/YYYY-MM-DD/ (rétention 90 jours)
├── logs/         # logs centralisés + alerts.log
├── docs/         # captures d'écran
└── 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).

# 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).

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

python -m src.database.db --init                 # initialiser la base
uvicorn src.api.main:app --reload --port 8000    # API en dev
python -m src.scheduler.daily_job --now          # collecte manuelle immédiate
python -m src.scheduler.backfill --date 2026-08-15
pytest tests/ -v

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).