recsys-pipeline-architect

O que recsys-pipeline-architect faz?

Um skill de especificação e geração de esqueletos para construir pipelines composáveis de recomendação, ranqueamento e feed. Ele codifica o padrão de seis estágios — Fonte → Hidratador → Filtro → Pontuador → Selecionador → EfeitoColateral — popularizado pelo algoritmo For You (Apache 2.0) de código aberto da xAI. Este 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 deseja construir qualquer sistema que escolha "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 de pipeline ao redor dela
• O usuário deseja migrar de uma pontuação de relevância única para predição multi-ação com pesos ajustáveis
• O usuário está encapsulando um pontuador de LLM/ML e precisa de filtros, hidratadores, efeitos colaterais e um esqueleto 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) — este skill é a infraestrutura ao redor do modelo, não o modelo em si
• Pipelines puros de treinamento de ML — a função de pontuação é responsabilidade do usuário
• Operação de um pipeline implantado (monitoramento, autoescalonamento) — fora do escopo

A estrutura de seis estágios

#	Estágio	Trabalho	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 essa ordem exata

• Fontes antes da hidratação: saiba 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 de ML + reranqueamento 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 invocado

Oriente o usuário por estas oito etapas:

1. Esclarecer o caso de uso (uma rodada, três perguntas): itens sendo ranqueados? contexto de entrada? idioma/runtime?
2. Identificar as fontes de candidatos: geralmente na rede (seguidos/possuídos/inscritos) + fora da rede (recuperação ML / tendências / semelhantes-ao-que-gostou)
3. Listar hidratações necessárias: para cada filtro e pontuador, de quais dados ele precisa que a fonte não forneceu?
4. Listar os filtros: duplicados, próprio, idade, bloqueio/silenciamento, previamente-servido, elegibilidade. A 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 mistura estratificada para dentro/fora da rede)
7. EfeitosColaterais: armazenar IDs servidos em cache, emitir eventos de impressão, atualizar contadores, registrar análises — todos do tipo "disparar e esquecer"
8. Gerar o esqueleto na stack do usuário

Principais trade-offs a serem explicitados (não assumir 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 do serviço. Para mudar comportamento → alterar 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 frequentemente.

2. Isolamento de candidatos na pontuação

• Isolado: cada candidato pontuado independentemente. Determinístico, armazenável em cache.
• Conjunto: candidatos atendem uns aos outros durante a pontuação (ex.: transformer sobre o lote). Mais expressivo, mas não determinístico entre lotes.

Padrão é isolamento. Conjunto apenas quando houver um motivo específico (ex.: diversidade explícita consciente do lote).

3. Online vs offline

• No momento da requisição (online): o pipeline executa a cada requisição. Orçamento de latência: 100–300ms. Padrão.
• Pré-computado (lote offline): o pipeline executa periodicamente, resultados em cache. Menor latência, menor atualização.
• 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 de código aberto da xAI" / github.com/xai-org/x-algorithm (Apache 2.0).
3. Nenhum uso de marca registrada. Não nomeie o artefato do usuário como "tipo X" ou use a marca "For You". O padrão é livre; a marca não é. Sugestão de nomenclatura: "pipeline de candidatos", "pipeline de feed", "pipeline de ranqueamento", "pipeline de recsys".
4. Explicite trade-offs. Multi-ação vs único, isolamento vs conjunto, online vs offline — nunca assuma por padrão silenciosamente.
5. O esqueleto gerado deve executar. Nada de pseudocódigo passando como código.
6. A 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 "disparar e esquecer" (goroutines / promises sem await / tarefas asyncio).

Anti-Padrõ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 / envio de impressão bloqueando a resposta)
• Uma pontuação única 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 reranqueamento)
• Gerar pseudocódigo "para ilustração" — o esqueleto deve realmente executar

Conteúdo do upstream

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

• SKILL.md completo com o fluxo de trabalho completo de 8 etapas
• 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, livro de receitas de filtros (12 padrões), livro de receitas de pontuadores (soma ponderada, MMR, penalidade de diversidade, desvio de posição)
• 3 esqueletos de exemplo executáveis, todos com testes verdes:
  • Plugin Strapi v5 (TypeScript / Jest — 3/3 aprovados)
  • Pipeline compatível com Zentra (Go com genéricos — 3/3 aprovados)
  • Priorizador de tarefas PMAI (Python / FastAPI / pytest — 3/3 aprovados)
• Versão v0.1.0 etiquetada
• Licença MIT; padrão atribuído ao algoritmo X For You da xAI (Apache 2.0)

Instale via skills.sh: npx skills add mturac/recsys-pipeline-architect