recsys-pipeline-architect

Uma habilidade de especificação e "scaffold" para construir pipelines de recomendação, ranqueamento e feed compoíveis. Ela codifica o padrão de seis estágios — Fonte → Hidratador → Filtro → Pontuador → Seletor → Efeito Colateral — popularizado pelo algoritmo For You de código aberto da xAI (Apache 2.0). Esta habilidade é uma reimplementação independente do padrão (MIT) — nenhum código copiado do original.

Upstream: https://github.com/mturac/recsys-pipeline-architect

Quando Usar

• O usuário quer construir qualquer sistema que seleciona "os top K itens para um usuário/contexto"
• O usuário pergunta "como devo ranquear X" ou descreve um problema de feed/personalização
• O usuário tem uma função de pontuação e precisa da infraestrutura do pipeline em torno dela
• O usuário quer migrar de uma única pontuação de relevância para predição multi-ação com pesos ajustáveis
• O usuário está encapsulando um LLM/ML scorer e precisa de filtros, hidratadores, efeitos colaterais e um scaffold executável em sua stack (TypeScript / Go / Python)
• Gatilhos: "sistema de recomendação", "algoritmo de feed", "pipeline de ranqueamento", "feed para você", "pipeline de candidatos", "recomendador de conteúdo", "arquitetura de pipeline para recsys", "reranker de recuperação RAG"

Quando NÃO Usar

• Trabalho de arquitetura de modelo (design de transformer, recuperação two-tower, treinamento de embeddings) — esta habilidade é a infraestrutura em torno do modelo, não o modelo em si
• Pipelines de treinamento de ML puro — a função de pontuação é responsabilidade do usuário
• Operação de um pipeline implantado (monitoramento, autoescalonamento) — fora do escopo

O framework de seis estágios

Por que essa ordem exata

• Fontes antes da hidratação: saber quais candidatos existem antes de pagar para enriquecê-los
• Hidratação antes da filtragem: muitos filtros precisam de metadados que a fonte não forneceu
• Filtragem antes da pontuação: a pontuação é o estágio caro; descarte os inelegíveis primeiro
• Cadeia de pontuadores (não um único pontuador): sistemas reais compõem pontuação de ML + re-ranqueamento de diversidade + regras de negócio
• Seletor após a pontuação: mantém a pontuação determinística e cacheável
• Efeitos colaterais por último e assíncronos: efeitos colaterais nunca devem bloquear a resposta do usuário

Fluxo de trabalho ao ser invocado

Guie o usuário através destas oito etapas:

1. Clarificar o caso de uso (uma rodada, três perguntas): itens sendo ranqueados? contexto de entrada? idioma/runtime?
2. Identificar as fontes de candidatos: geralmente in-network (seguidos/possuídos/assinados) + out-of-network (recuperação ML / trending / similar-ao-gostado)
3. Listar as hidratações necessárias: para cada filtro e pontuador, quais dados ele precisa que a fonte não forneceu?
4. Listar os filtros: duplicado, próprio, idade, bloqueio/silenciamento, previamente servido, elegibilidade. A ordem importa — barato antes de caro.
5. Projetar a cadeia de pontuadores: primário (ML) → combinador (multi-ação com pesos) → diversidade → regras de negócio
6. Seletor: ordenar decrescente pelo score final, pegar os top K (ou mix estratificado para in-network/out-of-network)
7. Efeitos Colaterais: cache de IDs servidos, emitir eventos de impressão, atualizar contadores, log de análises — tudo "dispare e esqueça"
8. Gerar o scaffold na stack do usuário

Principais trade-offs a serem apresentados (não defina silenciosamente)

1. Score único vs. predição multi-ação

• Score único: treinar um modelo para prever relevância. Para mudar o comportamento → retreinar.
• Multi-ação: prever P(action) para muitas ações (ler, curtir, compartilhar, pular, reportar), combinar com pesos no momento do serviço. Para mudar o comportamento → mudar pesos. Sem retreinamento.

O sistema X For You usa multi-ação com pesos positivos e negativos. Recomende multi-ação quando o usuário espera ajustar com frequência.

2. Isolamento de candidatos na pontuação

• Isolado: cada candidato pontuado independentemente. Determinístico, cacheável.

…