arquiteto-de-pipeline-recsys

O que arquiteto-de-pipeline-recsys faz?

Uma skill de especificação e scaffolding para construir pipelines de recomendação, ranqueamento e feed. Ela codifica o padrão de seis estágios — Fonte → Hidratador → Filtro → Pontuador → Selecionador → EfeitoColateral — popularizado pelo algoritmo For You open-source da xAI (Apache 2.0). Esta skill é 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 selecione "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 estrutura do pipeline ao redor 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 pontuador LLM/ML 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 transformers, recuperação two-tower, treinamento de embeddings) — esta skill cuida do encanamento ao redor do modelo, não do modelo em si
• Pipelines de treinamento de ML puro — a função de pontuação é responsabilidade do usuário
• Operação de um pipeline em produção (monitoramento, autoescalonamento) — fora do escopo

O framework de seis estágios

#	Estágio	Tarefa	Paralelo?
1	Fonte	Buscar candidatos de uma ou mais origens	Sim — múltiplas fontes executam em paralelo
2	Hidratador	Enriquecer cada candidato com metadados necessários para filtragem e pontuação	Sim — hidratadores independentes executam em paralelo
3	Filtro	Remover candidatos que nunca devem ser exibidos (bloqueados, expirados, duplicados, inelegíveis)	Sequencial — cada filtro vê menos itens
4	Pontuador	Atribuir a cada candidato sobrevivente uma ou mais pontuações	Sequencial — pontuadores posteriores veem pontuações anteriores
5	Selecionador	Ordenar pela pontuação final, retornar top K	Operação única
6	EfeitoColateral	Armazenar IDs servidos em cache, registrar impressões, emitir eventos, atualizar contadores	Assíncrono — nunca deve bloquear a resposta

Por que esta 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; remova os inelegíveis primeiro
• Cadeia de pontuadores (não um único pontuador): sistemas reais compõem pontuação ML + reranking de diversidade + regras de negócio
• Selecionador após a pontuação: mantém a pontuação determinística e armazenável em cache
• EfeitosColaterais por último e assíncronos: efeitos colaterais nunca devem bloquear a resposta do usuário

Fluxo de trabalho quando invocada

Oriente o usuário através destes oito passos:

1. Esclarecer o caso de uso (uma rodada, três perguntas): itens sendo ranqueados? contexto de entrada? linguagem/runtime?
2. Identificar as fontes de candidatos: geralmente intra-rede (seguidos/proprietários/inscritos) + extra-rede (recuperação ML / tendências / semelhantes-ao-curtido)
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: duplicata, próprio, idade, bloqueio/mute, previamente-servido, elegibilidade. Ordem importa — baratos antes de caros.
5. Projetar a cadeia de pontuadores: primário (ML) → combinador (multi-ação com pesos) → diversidade → regras de negócio
6. Selecionador: ordenar decrescente pela pontuação final, pegar top K (ou mix estratificado para intra-rede/extra-rede)
7. EfeitosColaterais: armazenar IDs servidos em cache, emitir eventos de impressão, atualizar contadores, registrar análises — todos "fire-and-forget"
8. Gerar o scaffold na stack do usuário

Principais compensações a destacar (não optar por padrão silenciosamente)

1. Pontuação única vs predição multi-ação

• Pontuação única: treinar um modelo para prever relevância. Para mudar comportamento → retreinar.
• Multi-ação: prever P(ação) para várias ações (ler, curtir, compartilhar, pular, denunciar), combinar com pesos no momento da exibição. Para mudar 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, armazenável em cache.
• Conjunto: candidatos interagem entre si durante a pontuação (ex.: transformer sobre lote). Mais expressivo, mas não determinístico entre lotes.

Padrão: isolado. Conjunto somente quando houver um motivo específico (ex.: diversidade explícita consciente de lote).

3. Online vs offline

• Em tempo de requisição (online): pipeline executa em cada requisição. Orçamento de latência: 100–300ms. Padrão.
• Pré-computado (lote offline): pipeline executa periodicamente, resultados armazenados em cache. Menor latência, menor frescor.
• Híbrido: recuperação de candidatos offline, ranqueamento online.

Regras rígidas

1. Não invente números de benchmark. "Quanto mais rápido?" → "depende da carga de trabalho, execute você mesmo."
2. Disciplina de atribuição. Quando o padrão for referenciado, atribua como "popularizado pelo algoritmo For You open-source da xAI" / github.com/xai-org/x-algorithm (Apache 2.0).
3. Sem uso de marca registrada. Não nomeie o artefato do usuário como "X-like" ou use a marca "For You". O padrão é livre; a marca não é. Nomes sugeridos: "pipeline de candidatos", "pipeline de feed", "pipeline de ranqueamento", "pipeline recsys".
4. Apresente compensações. Multi-ação vs única, isolamento vs conjunto, online vs offline — nunca opte por padrão silenciosamente.
5. O scaffold gerado deve executar. Nada de pseudocódigo passando como código.
6. Ordem dos filtros importa. Baratos antes de caros. Universais antes de específicos do usuário.
7. Efeitos colaterais nunca bloqueiam. Encapsule em padrões "fire-and-forget" (goroutines / promises sem await / tarefas asyncio).

Antipadrões

• Pontuação antes da filtragem (desperdiça computação em candidatos que serão descartados de qualquer forma)
• Efeitos colaterais síncronos (escritas em cache / emissão de impressão bloqueando a resposta)
• Uma única pontuação de "relevância" quando o produto precisa ajustar para múltiplos objetivos (engajamento vs segurança vs diversidade vs anúncios)
• Pontuação conjunta como padrão (não determinística, mais difícil de armazenar em cache, não compõe com estágios de reranking)
• Gerar pseudocódigo "para ilustração" — o scaffold deve realmente executar

Conteúdo do upstream

O repositório upstream em https://github.com/mturac/recsys-pipeline-architect inclui:

• SKILL.md completo com o fluxo de trabalho de 8 passos
• 5 documentos de referência carregados sob demanda: interfaces em 4 linguagens (TS/Go/Python/Rust), padrão de pontuação multi-ação, isolamento de candidatos, cookbook de filtros (12 padrões), cookbook de pontuadores (soma ponderada, MMR, penalidade por diversidade, viés de posição)
• 3 scaffolds de exemplo executáveis, todos verdes em sua suíte de testes:
  • Plugin Strapi v5 (TypeScript / Jest — 3/3 passam)
  • Pipeline compatível com Zentra (Go com genéricos — 3/3 passam)
  • Priorizador de tarefas PMAI (Python / FastAPI / pytest — 3/3 passam)
• Versão v0.1.0 tagueada
• Licença MIT; padrão atribuído ao algoritmo X For You da xAI (Apache 2.0)

Instalação via skills.sh: npx skills add mturac/recsys-pipeline-architect