1# -----------------------------------------------------------------------------2# Groupe KA — kaid.py : client KA ID v2 (personnalisation) pour les satellites.3# SOURCE CANONIQUE : ka-ui.git/kaid/kaid.py — copié dans le paquet backend de4# chaque app (louka/, jobka/, sortika/, …) par sync-kaid.sh. Ne pas diverger :5# corriger ICI puis redistribuer.6#7# Rôle : relier l'app au feature store du hub (groupe-ka.com) —8# · track() journal d'interactions (serveur, fil d'exécution dédié)9# · fetch_prefs() profil de préférences appris (cache 90 s, fail-open)10# · rerank() reclassement personnalisé APRÈS la pertinence de base11# · build_router() routes /api/kaid/* (événements client, masquage,12# recherches sauvegardées)13#14# Contrat s2s (identique à hubfav/hubprofile) : HMAC-SHA256 du secret SSO15# partagé — sig = HMAC(KA_SSO_SECRET, f"{CLIENT_ID}.{ka_id}.{ts}").16# Config .env : KA_SSO_SECRET (déjà présent), KA_HUB_URL (optionnel).17#18# Principes : la connexion n'est JAMAIS requise ; sans profil ou à la moindre19# erreur réseau → classement de base inchangé (fail-open). La personnalisation20# ne remplace pas la pertinence : elle reclasse (blend) et n'écrase jamais21# l'intention de la session (les dimensions explicitement filtrées par la22# requête courante sont ignorées dans le score).23# -----------------------------------------------------------------------------24from __future__ import annotations2526import hashlib27import hmac28import json29import os30import threading31import time3233import requests34from fastapi import APIRouter, HTTPException, Request35from pydantic import BaseModel3637KA_HUB_URL = os.environ.get("KA_HUB_URL", "https://www.groupe-ka.com").rstrip("/")38CLIENT_ID = os.environ.get("KA_CLIENT_ID", "") # fixé par init() dans web.py3940PREFS_TTL = 90 # secondes de cache du profil41TIMEOUT = 5 # secondes par appel hub42LOCATION_DIMS = {"city", "region", "sector", "quartier", "ville",43 "location", "neighborhood"}44LANGUAGE_DIMS = {"language", "langue"}45PRICE_DIMS = {"price", "rent", "salary", "salary_year", "price_min"}4647# Événements acceptés depuis le navigateur (le reste vient du serveur).48CLIENT_EVENT_TYPES = {49 "click", "impression", "detail_dwell", "scroll_depth", "return_visit",50 "share", "compare", "external_click", "map_open", "map_marker_click",51 "alert_open",52}5354_prefs_cache: dict[str, tuple[float, dict | None]] = {}55_seen_searches: dict[str, float] = {} # anti-doublon des recherches (120 s)56_lock = threading.Lock()575859def init(client_id: str) -> None:60 """À appeler une fois au démarrage de l'app (web.py)."""61 global CLIENT_ID62 CLIENT_ID = client_id636465def _sig(ka_id: str, ts: int) -> str | None:66 secret = os.environ.get("KA_SSO_SECRET")67 if not secret or not CLIENT_ID:68 return None69 return hmac.new(secret.encode(),70 f"{CLIENT_ID}.{ka_id}.{ts}".encode(),71 hashlib.sha256).hexdigest()727374def _signed_params(ka_id: str) -> dict | None:75 ts = int(time.time())76 sig = _sig(ka_id, ts)77 if not sig:78 return None79 return {"client_id": CLIENT_ID, "ka_id": ka_id, "ts": str(ts), "sig": sig}808182def _ka_id_of(user) -> str | None:83 """Extrait un ka_id exploitable d'un dict utilisateur (ou None)."""84 if not user:85 return None86 ka = (user.get("ka_id") or "").strip() if isinstance(user, dict) else ""87 return ka if ka.startswith("ka-") else None888990# ---------------------------------------------------------------- événements9192def _post_events(ka_id: str, events: list[dict]) -> None:93 p = _signed_params(ka_id)94 if not p:95 return96 try:97 requests.post(f"{KA_HUB_URL}/api/sso/events", timeout=TIMEOUT,98 json={**p, "events": events})99 except Exception:100 pass # best-effort : jamais bloquant, jamais fatal101102103def track(user, etype: str, *, entity_type: str | None = None,104 entity_id: str | None = None, query: str | None = None,105 filters: dict | None = None, position: int | None = None,106 features: dict | None = None, dwell_ms: int | None = None,107 session_id: str | None = None) -> None:108 """Journalise un événement au hub (fil dédié, zéro latence ajoutée).109 No-op si l'utilisateur n'est pas connecté via KA ID."""110 ka_id = _ka_id_of(user)111 if not ka_id:112 return113 if etype == "search":114 # anti-rafale : la même recherche (mêmes filtres) < 120 s n'est115 # journalisée qu'une fois — une SPA relance l'API à chaque frappe.116 key = ka_id + "|" + hashlib.sha1(117 json.dumps([query, filters], sort_keys=True, default=str).encode()118 ).hexdigest()119 now = time.time()120 with _lock:121 if now - _seen_searches.get(key, 0) < 120:122 return123 _seen_searches[key] = now124 if len(_seen_searches) > 2000:125 cutoff = now - 300126 for k in [k for k, t in _seen_searches.items() if t < cutoff]:127 del _seen_searches[k]128 ev: dict = {"type": etype}129 if entity_type: ev["entity_type"] = entity_type130 if entity_id: ev["entity_id"] = str(entity_id)131 if query: ev["query"] = str(query)[:200]132 if filters: ev["filters"] = filters133 if position is not None: ev["position"] = int(position)134 if features: ev["features"] = features135 if dwell_ms is not None: ev["dwell_ms"] = int(dwell_ms)136 if session_id: ev["session_id"] = str(session_id)[:60]137 threading.Thread(target=_post_events, args=(ka_id, [ev]), daemon=True).start()138139140# ------------------------------------------------------------------ profil141142def fetch_prefs(ka_id: str | None) -> dict | None:143 """Profil de personnalisation du membre (cache 90 s). None si non144 connecté, non configuré ou hub injoignable — l'appelant retombe alors145 sur le classement de base."""146 if not ka_id or not str(ka_id).startswith("ka-"):147 return None148 now = time.time()149 with _lock:150 hit = _prefs_cache.get(ka_id)151 if hit and now - hit[0] < PREFS_TTL:152 return hit[1]153 data: dict | None = None154 p = _signed_params(ka_id)155 if p:156 try:157 r = requests.get(f"{KA_HUB_URL}/api/sso/prefs", params=p,158 timeout=TIMEOUT)159 if r.status_code == 200:160 data = r.json()161 except Exception:162 data = None163 with _lock:164 _prefs_cache[ka_id] = (now, data)165 if len(_prefs_cache) > 500:166 for k in list(_prefs_cache)[:100]:167 del _prefs_cache[k]168 return data169170171def invalidate_prefs(ka_id: str | None) -> None:172 if not ka_id:173 return174 with _lock:175 _prefs_cache.pop(ka_id, None)176177178# ---------------------------------------------------------------- reranking179180def _norm(v) -> str:181 return str(v).strip().lower()182183184def personal_score(feats: dict, app_profile: dict, global_profile: dict,185 active_dims: set[str]) -> tuple[float | None, list[str]]:186 """Score personnel [0,1] d'une annonce, ou None si le profil ne couvre187 aucune de ses caractéristiques. `active_dims` = dimensions explicitement188 filtrées par la requête courante (intention de session > long terme)."""189 dims = app_profile.get("dims") or {}190 ranges = app_profile.get("ranges") or {}191 gl = (global_profile or {}).get("location") or {}192 num = 0.0193 den = 0.0194 reasons: list[str] = []195 for dim, val in (feats or {}).items():196 if val is None or dim in active_dims:197 continue198 if isinstance(val, bool):199 val = str(val)200 if isinstance(val, (int, float)):201 r = ranges.get(dim)202 if r and r.get("n", 0) >= 5:203 p25, p75 = r["p25"], r["p75"]204 iqr = max(p75 - p25, abs(r.get("p50", 0)) * 0.1, 1.0)205 if p25 <= val <= p75:206 aff = 1.0207 elif p25 - 1.5 * iqr <= val <= p75 + 1.5 * iqr:208 aff = 0.3209 else:210 aff = -0.4211 # poids réduit : une plage numérique seule (prix…) ne doit212 # jamais suffire à personnaliser (0.6 < seuil den 0.8) —213 # sinon tout item au « bon prix » score 1.0 et noie les214 # correspondances réelles (ville, marque, type).215 w = 0.6216 num += w * aff217 den += w218 if aff == 1.0:219 reasons.append("MATCH_PRICE_RANGE" if dim in PRICE_DIMS220 else f"MATCH_{dim.upper()}_RANGE")221 continue222 vals = val if isinstance(val, (list, tuple)) else [val]223 vals = [_norm(v) for v in vals if v not in (None, "")]224 if not vals:225 continue226 d = dims.get(dim)227 if d:228 vv = d.get("values") or {}229 affs = [vv[v] for v in vals if v in vv]230 if affs:231 aff = max(affs)232 w = float(d.get("conf") or 0.5)233 num += w * aff234 den += w235 if aff >= 0.6:236 reasons.append("MATCH_LOCATION" if dim in LOCATION_DIMS237 else f"MATCH_{dim.upper()}")238 if dim in LOCATION_DIMS:239 gv = gl.get("values") or {}240 affs = [gv[v] for v in vals if v in gv]241 if affs and max(affs) > 0:242 w = 0.6 * float(gl.get("conf") or 0.3)243 num += w * max(affs)244 den += w245 if max(affs) >= 0.6 and "MATCH_LOCATION" not in reasons:246 reasons.append("MATCH_LOCATION")247 if dim in LANGUAGE_DIMS:248 glang = (global_profile or {}).get("language") or {}249 gv = glang.get("values") or {}250 affs = [gv[v] for v in vals if v in gv]251 if affs and max(affs) > 0:252 w = 0.4 * float(glang.get("conf") or 0.3)253 num += w * max(affs)254 den += w255 if den < 0.8:256 return None, []257 score = (num / den + 1.0) / 2.0258 return max(0.0, min(1.0, score)), reasons[:4]259260261def rerank(items: list, user, *, features_of, uid_of=None,262 active_dims: set[str] | None = None, blend: float = 0.35,263 badge: float = 0.62, max_considered: int = 300,264 reco_key: str = "ka_reco") -> tuple[list, bool]:265 """Reclassement personnalisé APRÈS la pertinence de base.266 · items : liste (dicts) déjà triée par la pertinence de base267 · features_of : item -> dict de caractéristiques {dim: valeur}268 · uid_of : item -> identifiant canonique (défaut : item["uid"])269 · active_dims : dimensions filtrées par la requête (ignorées du score)270 Retourne (items, personnalisé?). Les annonces masquées (« Pas pour moi »)271 sont retirées. Annote item[reco_key] = {score, reasons} quand le score272 personnel est net (badge « Recommandé pour vous » — parcimonieux)."""273 if uid_of is None:274 uid_of = lambda it: (it.get("uid") if isinstance(it, dict) else None)275 ka_id = _ka_id_of(user)276 if not ka_id or not items:277 return items, False278 prefs = fetch_prefs(ka_id)279 if not prefs:280 return items, False281 hidden = set(prefs.get("hidden") or [])282 if hidden:283 items = [it for it in items if str(uid_of(it)) not in hidden]284 if not prefs.get("personalization"):285 return items, False286 profile = prefs.get("profile") or {}287 app_p = profile.get("app")288 if not app_p or not items:289 return items, False290291 head = items[:max_considered]292 tail = items[max_considered:]293 n = len(head)294 active = active_dims or set()295 # co-favoris des membres semblables (filtrage collaboratif du hub)296 similar = {str(s) for s in (app_p.get("similar") or [])}297 scored = []298 badged = 0299 for i, it in enumerate(head):300 base = 1.0 - i / max(n, 1)301 try:302 p, reasons = personal_score(features_of(it) or {}, app_p,303 profile.get("global") or {}, active)304 except Exception:305 p, reasons = None, []306 if similar and str(uid_of(it)) in similar:307 p = min(1.0, (p if p is not None else 0.55) + 0.25)308 reasons = (["SIMILAR_USERS"] + reasons)[:4]309 if p is None:310 final = (1.0 - blend) * base + blend * 0.5311 else:312 final = (1.0 - blend) * base + blend * p313 if p >= badge and reasons and badged < max(2, n // 8) \314 and isinstance(it, dict):315 it[reco_key] = {"score": round(p, 2), "reasons": reasons}316 badged += 1317 scored.append((final, i, it))318 scored.sort(key=lambda t: (-t[0], t[1])) # stable : départage par rang319 return [it for _, _, it in scored] + tail, True320321322# ------------------------------------------------------- proxys hub (s2s)323324def _hub_post(ka_id: str, path: str, payload: dict) -> dict:325 p = _signed_params(ka_id)326 if not p:327 raise HTTPException(503, "KA_SSO_SECRET manquant (voir .env)")328 try:329 r = requests.post(f"{KA_HUB_URL}{path}", timeout=TIMEOUT,330 json={**p, **payload})331 return r.json() if r.status_code == 200 else {"error": r.status_code}332 except Exception:333 raise HTTPException(502, "hub KA injoignable")334335336def _hub_get(ka_id: str, path: str) -> dict:337 p = _signed_params(ka_id)338 if not p:339 raise HTTPException(503, "KA_SSO_SECRET manquant (voir .env)")340 try:341 r = requests.get(f"{KA_HUB_URL}{path}", params=p, timeout=TIMEOUT)342 return r.json() if r.status_code == 200 else {"error": r.status_code}343 except Exception:344 raise HTTPException(502, "hub KA injoignable")345346347# ------------------------------------------------------------------ routeur348349class _EventsIn(BaseModel):350 events: list[dict]351352353class _HideIn(BaseModel):354 item_id: str355 on: bool = True356 features: dict | None = None357358359class _SearchIn(BaseModel):360 action: str = "add" # add | remove | alert | touch361 id: int | None = None362 label: str | None = None363 query: str | None = None364 filters: dict | None = None365 location: str | None = None366 url: str | None = None367 alert: bool = False368 frequency: str | None = None369370371def build_router(get_user) -> APIRouter:372 """Routes /api/kaid/* de l'app. `get_user(request)` = current_user de373 l'app (dict avec ka_id, ou None)."""374 router = APIRouter(prefix="/api/kaid")375376 def _require_ka(request: Request) -> tuple[dict, str]:377 user = get_user(request)378 ka_id = _ka_id_of(user)379 if not ka_id:380 raise HTTPException(401, "connexion KA ID requise")381 return user, ka_id382383 @router.get("/status")384 def status(request: Request):385 user = get_user(request)386 ka_id = _ka_id_of(user)387 if not ka_id:388 return {"connected": False}389 prefs = fetch_prefs(ka_id)390 return {391 "connected": True,392 "personalization": bool(prefs and prefs.get("personalization")),393 "monka_url": f"{KA_HUB_URL}/mon-ka",394 }395396 @router.post("/events")397 def client_events(request: Request, body: _EventsIn):398 user = get_user(request)399 ka_id = _ka_id_of(user)400 if not ka_id:401 return {"ok": True, "stored": 0}402 events = []403 for e in body.events[:20]:404 if e.get("type") in CLIENT_EVENT_TYPES:405 events.append({k: e[k] for k in406 ("type", "entity_type", "entity_id", "query",407 "filters", "position", "features", "dwell_ms",408 "session_id") if k in e})409 if events:410 threading.Thread(target=_post_events, args=(ka_id, events),411 daemon=True).start()412 return {"ok": True, "stored": len(events)}413414 @router.post("/hide")415 def hide(request: Request, body: _HideIn):416 _, ka_id = _require_ka(request)417 out = _hub_post(ka_id, "/api/sso/hide", {418 "item_id": body.item_id, "on": body.on,419 "features": body.features,420 })421 invalidate_prefs(ka_id)422 return out423424 @router.get("/saved-searches")425 def saved_list(request: Request):426 _, ka_id = _require_ka(request)427 return _hub_get(ka_id, "/api/sso/saved-searches")428429 @router.post("/saved-searches")430 def saved_post(request: Request, body: _SearchIn):431 _, ka_id = _require_ka(request)432 search: dict = {k: v for k, v in {433 "id": body.id, "label": body.label, "query": body.query,434 "filters": body.filters, "location": body.location,435 "url": body.url, "alert": body.alert,436 "frequency": body.frequency,437 }.items() if v is not None}438 out = _hub_post(ka_id, "/api/sso/saved-searches",439 {"action": body.action, "search": search})440 invalidate_prefs(ka_id)441 return out442443 return router444