Recsys Pipeline Architect

Un skill spec-and-scaffold pour construire des pipelines de recommandation, ranking et feed composables. Encode le pattern à six étapes popularisé par l'algorithme For You open-sourcé par xAI (Apache 2.0) et l'applique à tout problème « top K pour (utilisateur, contexte) ».

Overview

La plupart des « systèmes de recommandation » en production ne sont pas du ML exotique — ce sont des pipelines : récupérer les candidats d'une ou plusieurs sources, les enrichir avec des métadonnées, éliminer les inéligibles, scorer le reste, trier et prendre les top K, puis déclencher des effets de bord asynchrones. Le pattern est universel. La fonction de scoring et les items changent ; la forme du pipeline ne change pas.

Ce skill est une réimplémentation indépendante du pattern (MIT) — aucun code copié de l'original.

Quand utiliser ce skill

• Construire n'importe quel système qui retourne « les K items les plus pertinents pour un utilisateur/contexte »
• Concevoir ou refactoriser un feed personnalisé (contenu, résultats de recherche, notifications)
• Envelopper un scorer LLM/ML dans une plomberie pipeline appropriée (sources, hydratation, filtres, effets de bord)
• Ajouter une prédiction multi-action avec poids ajustables (au lieu d'un seul score de pertinence)
• Construire un reranker de retrieval RAG (retrieval bon marché → rerank coûteux)
• Concevoir un prioritizer de tâches ou un système de triage des alertes

Le framework à six étapes

Pourquoi cet ordre exact

• Sources avant hydratation : savoir quels candidats existent avant de payer pour les enrichir
• Hydratation avant filtrage : beaucoup de filtres ont besoin des métadonnées que la source n'a pas fourni
• Filtrage avant scoring : le scoring est l'étape coûteuse — éliminer les inéligibles en premier
• Chaîne de scorers (pas un seul scorer) : les vrais systèmes composent le scoring ML + reranking de diversité + règles métier
• Selector après scoring : garde le scoring déterministe et cacheable
• SideEffects en dernier et asynchrones : les effets de bord ne doivent jamais bloquer la réponse de l'utilisateur

Workflow lors de l'invocation

Guider l'utilisateur à travers huit étapes :

1. Clarifier le cas d'usage (un round, trois questions seulement si manquantes) : items classés, contexte d'entrée, langage/runtime
2. Identifier les sources de candidats (généralement in-network + out-of-network, mais single-source valide aussi)
3. Lister les hydratations requises — pour chaque filtre et scorer, quelles données lui faut-il que la source n'a pas fourni ?
4. Lister les filtres — bon marché avant cher, universel avant user-spécifique (doublon, soi-même, âge, block/mute, précédemment-servi, éligibilité)
5. Concevoir la chaîne de scorers — ML/heuristique principal → combineur (multi-action avec poids) → diversité → règles métier
6. Selector — trier descendant par score final, prendre top K (ou mélange stratifié)
7. SideEffects — cache des IDs servis, émettre les événements d'impression, mettre à jour les compteurs, logger l'analytics ; tout fire-and-forget
8. Générer le scaffold dans la stack de l'utilisateur

Trade-offs clés à surfacer

Ne jamais défaillir silencieusement sur ceux-ci — ce sont des décisions produit déguisées en techniques.

1. Single score vs multi-action prediction

• Single score : entraîner un modèle pour prédire la pertinence. Pour changer le comportement → réentraîner.
• Multi-action : prédire P(action) pour plusieurs actions (P(read), P(like), P(share), P(skip), P(report)), combiner avec poids au serving time. Pour changer le comportement → changer les poids. Pas de réentraînement.

L'algorithme X For You utilise multi-action avec poids positifs et négatifs. Recommander multi-action quand l'utilisateur s'attend à un tuning fréquent.

2. Candidate isolation vs joint scoring

• Isolated : chaque candidat scoré indépendamment. Déterministe, cacheable.
• Joint : les candidats s'attendent mutuellement lors du scoring (p. ex., transformer sur tout le batch). Plus expressif mais non-déterministe entre les batches.

Par défaut, isolation. Joint seulement quand il y a une raison spécifique (p. ex., diversité explicitement batch-aware).

3. Online vs offline batch

• Request-time (online) : le pipeline s'exécute à chaque requête. Budget latence : 100–300ms.
• Pre-computed (offline batch) : le pipeline s'exécute périodiquement, résultats cachés. Latence plus basse, fraîcheur plus basse.
• Hybrid : retrieval offline, ranking online.

Hard Rules

1. Ne pas inventer de chiffres de benchmark. « Ça va à quelle vitesse ? » → « dépend de la charge de travail, lancez-le vous-même. »
2. Attribution discipline. Attribuer le pattern comme « popularisé par l'algorithme For You open-sourcé par xAI » / github.com/xai-org/x-algorithm (Apache 2.0).
3. Pas d'usage de marque. Ne pas nommer l'artefact de l'utilisateur « X-like » ou utiliser le branding « For You ». Utiliser des noms neutres : « candidate pipeline », « feed pipeline », « ranking pipeline ».
4. Surfacer les trade-offs. Multi-action vs single, isolation vs joint, online vs offline — ne jamais défaillir silencieusement.
5. Le scaffold généré doit s'exécuter. Pas de pseudocode passant pour du code.
6. L'ordre des filtres compte. Bon marché avant cher. Universel avant user-spécifique.
7. Les side effects ne bloquent jamais. Envelopper dans des patterns fire-and-forget (goroutines / promises without await / asyncio tasks).

Anti-Patterns

• ❌ Scoring avant filtrage (gaspille du compute sur les candidats qui seront éliminés)
• ❌ Side effects synchrones (écritures cache / émission d'impressions bloquant la réponse)
• ❌ Un seul score « pertinence » quand le produit a besoin d'ajustement multi-objectif
• ❌ Joint scoring par défaut (non-déterministe, uncacheable, ne compose pas avec le reranking)
• ❌ Pseudocode « pour illustration » — le scaffold doit réellement s'exécuter

Cas d'usage courants

Content feed (Strapi v5 plugin, TypeScript)

L'utilisateur a un CMS avec 50k articles, veut un feed « for you » personnalisé. Parcourir 8 étapes → générer un scaffold Strapi plugin avec scoring multi-action, diversité d'auteur, filtres standard, lane d'effets de bord asynchrone.

RAG retrieval reranker (Python async)

Le RAG de l'utilisateur retourne top-50 chunks d'une vector DB, veut reranker avec un scorer plus coûteux et retourner top-5. Pipeline single-source avec une chaîne de scorers (retrieval bon marché + rerank coûteux).

Task prioritizer (FastAPI service)

L'utilisateur a une queue de suggestions de tâches, veut les classer par « sur quoi cet utilisateur devrait-il travailler ensuite » en tenant compte de ses patterns passés. Items inversés (tasks au lieu de contenu), la même forme s'applique.

Notification triage (offline-batch job)

L'utilisateur veut un digest quotidien qui choisit les top 10 de la dernière queue de 24h. Pipeline offline-batch. Source = queue, filtres = age/dedup/éligibilité, scorer = urgence × affinité-utilisateur, selector = top 10, side effect = envoi email (toujours async).

Upstream

Ce skill est un adaptateur single-file pour le repository upstream, qui expédie 5 docs de référence load-on-demand et 3 scaffolds d'exemple runnable (Strapi v5 / Go / Python — chacun green sur sa suite de tests, 9/9 tests au total).

• Upstream : https://github.com/mturac/recsys-pipeline-architect
• Release : v0.1.0 (MIT)
• References : interfaces dans 4 langages (TS/Go/Python/Rust), scoring multi-action, candidate isolation, filter cookbook (12 patterns), scorer cookbook
• Cross-platform install : npx skills add mturac/recsys-pipeline-architect