recsys-pipeline-architect

¿Qué hace recsys-pipeline-architect?

Una skill de especificación y andamio para construir pipelines componibles de recomendación, ranking y feeds. Implementa el patrón de seis etapas — Fuente → Hidratador → Filtro → Puntuador → Selector → EfectoSecundario — popularizado por el algoritmo For You de código abierto de xAI (Apache 2.0). Esta skill es una reimplementación independiente del patrón (MIT) — no se ha copiado código del original.

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

Cuándo usarla

• El usuario quiere construir cualquier sistema que seleccione "los K mejores elementos para un usuario/contexto"
• El usuario pregunta "cómo debería rankear X" o describe un problema de feed/personalización
• El usuario tiene una función de puntuación y necesita la infraestructura del pipeline alrededor
• El usuario quiere migrar de una puntuación de relevancia única a predicción multiacción con pesos ajustables
• El usuario está envolviendo un puntuador LLM/ML y necesita filtros, hidratadores, efectos secundarios y un andamio ejecutable en su stack (TypeScript / Go / Python)
• Disparadores: "sistema de recomendación", "algoritmo de feed", "pipeline de ranking", "feed para ti", "pipeline de candidatos", "recomendador de contenido", "arquitectura de pipeline para recsys", "re-ranker de recuperación RAG"

Cuándo NO usarla

• Trabajo de arquitectura de modelos (diseño de transformers, recuperación de dos torres, entrenamiento de embeddings) — esta skill es la infraestructura alrededor del modelo, no el modelo en sí
• Pipelines de entrenamiento ML puro — la función de puntuación es responsabilidad del usuario
• Operar un pipeline desplegado (monitoreo, autoescalado) — fuera del alcance

El marco de seis etapas

#	Etapa	Trabajo	¿Paralelo?
1	Fuente	Obtener candidatos de uno o más orígenes	Sí — múltiples fuentes se ejecutan en paralelo
2	Hidratador	Enriquecer cada candidato con metadatos necesarios para el filtrado y la puntuación	Sí — hidratadores independientes se ejecutan en paralelo
3	Filtro	Descartar candidatos que nunca deberían mostrarse (bloqueados, caducados, duplicados, no elegibles)	Secuencial — cada filtro ve menos elementos
4	Puntuador	Asignar a cada candidato superviviente una o más puntuaciones	Secuencial — los puntuadores posteriores ven puntuaciones anteriores
5	Selector	Ordenar por puntuación final, devolver los K mejores	Operación única
6	EfectoSecundario	Cachear IDs servidos, registrar impresiones, emitir eventos, actualizar contadores	Asíncrono — nunca debe bloquear la respuesta

Por qué este orden exacto

• Fuentes antes de hidratación: saber qué candidatos existen antes de pagar para enriquecerlos
• Hidratación antes del filtrado: muchos filtros necesitan metadatos que la fuente no proporcionó
• Filtrado antes de la puntuación: la puntuación es la etapa costosa; descartar primero los no elegibles
• Cadena de puntuadores (no un solo puntuador): los sistemas reales combinan puntuación ML + re-ranking de diversidad + reglas de negocio
• Selector después de la puntuación: mantiene la puntuación determinista y cacheable
• Efectos secundarios al final y asíncronos: los efectos secundarios nunca deben bloquear la respuesta del usuario

Flujo de trabajo al invocar

Guiar al usuario a través de estos ocho pasos:

1. Aclarar el caso de uso (una ronda, tres preguntas): ¿elementos a rankear? ¿contexto de entrada? ¿idioma/entorno de ejecución?
2. Identificar las fuentes de candidatos: normalmente en-red (seguidos/poseídos/subscritos) + fuera-de-red (recuperación ML / tendencias / similar-a-gustado)
3. Listar las hidrataciones requeridas: para cada filtro y puntuador, ¿qué datos necesita que la fuente no proporcionó?
4. Listar los filtros: duplicado, propio, antigüedad, bloqueo/silencio, previamente-servido, elegibilidad. El orden importa — baratos antes que caros.
5. Diseñar la cadena de puntuadores: primario (ML) → combinador (multiacción con pesos) → diversidad → reglas de negocio
6. Selector: orden descendente por puntuación final, tomar los K mejores (o mezcla estratificada para en-red/fuera-de-red)
7. Efectos secundarios: cachear IDs servidos, emitir eventos de impresión, actualizar contadores, registrar analíticas — todo de tipo "disparar y olvidar"
8. Generar el andamio en el stack del usuario

Compensaciones clave a mencionar (no silenciar por defecto)

1. Puntuación única vs predicción multiacción

• Puntuación única: entrenar un modelo para predecir relevancia. Para cambiar comportamiento → reentrenar.
• Multiacción: predecir P(acción) para muchas acciones (leer, gustar, compartir, saltar, reportar), combinar con pesos en tiempo de servicio. Para cambiar comportamiento → cambiar pesos. Sin reentrenamiento.

El sistema X For You usa multiacción con pesos tanto positivos como negativos. Recomendar multiacción cuando el usuario espera ajustar con frecuencia.

2. Aislamiento de candidatos en la puntuación

• Aislado: cada candidato puntuado de forma independiente. Determinista, cacheable.
• Conjunto: los candidatos se atienden entre sí durante la puntuación (ej., transformer sobre el lote). Más expresivo pero no determinista entre lotes.

Por defecto, aislado. Solo conjunto cuando hay una razón específica (ej., diversidad explícita consciente del lote).

3. Online vs offline

• En tiempo de solicitud (online): el pipeline se ejecuta en cada solicitud. Presupuesto de latencia: 100-300ms. Por defecto.
• Precomputado (offline por lotes): el pipeline se ejecuta periódicamente, resultados cacheados. Menor latencia, menor frescura.
• Híbrido: recuperación de candidatos offline, ranking online.

Reglas estrictas

1. No inventar números de referencia. "¿Cuánto más rápido?" → "depende de la carga de trabajo, pruébelo usted mismo."
2. Disciplina de atribución. Cuando se haga referencia al patrón, atribuir como "popularizado por el algoritmo For You de código abierto de xAI" / github.com/xai-org/x-algorithm (Apache 2.0).
3. Sin uso de marcas registradas. No nombrar el artefacto del usuario "como X" ni usar la marca "For You". El patrón es libre; la marca no. Nombres sugeridos: "pipeline de candidatos", "pipeline de feed", "pipeline de ranking", "pipeline de recsys".
4. Mencionar compensaciones. Multiacción vs única, aislamiento vs conjunto, online vs offline — nunca silenciar por defecto.
5. El andamio generado debe ejecutarse. No se acepta pseudocódigo como código.
6. El orden de los filtros importa. Baratos antes que caros. Universales antes que específicos del usuario.
7. Los efectos secundarios nunca bloquean. Envolver en patrones de "disparar y olvidar" (gorutinas / promesas sin await / tareas asyncio).

Anti-patrones

• Puntuación antes del filtrado (desperdicia cómputo en candidatos que se descartarán de todas formas)
• Efectos secundarios síncronos (escrituras de caché / emisiones de impresión bloqueando la respuesta)
• Una puntuación única de "relevancia" cuando el producto necesita ajustar múltiples objetivos (compromiso vs seguridad vs diversidad vs anuncios)
• Puntuación conjunta por defecto (no determinista, más difícil de cachear, no se compone con etapas de re-ranking)
• Generar pseudocódigo "para ilustración" — el andamio debe ejecutarse realmente

Contenido del repositorio upstream

El repositorio upstream en https://github.com/mturac/recsys-pipeline-architect incluye:

• SKILL.md completa con el flujo de trabajo completo de 8 pasos
• 5 documentos de referencia bajo demanda: interfaces en 4 idiomas (TS/Go/Python/Rust), patrón de puntuación multiacción, aislamiento de candidatos, recetario de filtros (12 patrones), recetario de puntuadores (suma ponderada, MMR, penalización de diversidad, desesgo de posición)
• 3 andamios de ejemplo ejecutables, todos con pruebas exitosas:
  • Plugin Strapi v5 (TypeScript / Jest — 3/3 pasan)
  • Pipeline compatible con Zentra (Go con genéricos — 3/3 pasan)
  • Priorizador de tareas PMAI (Python / FastAPI / pytest — 3/3 pasan)
• Versión v0.1.0 etiquetada
• Licencia MIT; patrón atribuido al algoritmo X For You de xAI (Apache 2.0)

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