recsys-pipeline-architect

¿Qué hace recsys-pipeline-architect?

Un skill de especificación y andamiaje para construir pipelines de recomendación, clasificación y feeds componibles. Codifica el patrón de seis etapas — Source → Hydrator → Filter → Scorer → Selector → SideEffect — popularizado por el algoritmo For You de código abierto de xAI (Apache 2.0). Este 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 usar

• El usuario quiere construir cualquier sistema que seleccione "los top K elementos para un usuario/contexto"
• El usuario pregunta "cómo debería clasificar 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 única puntuación de relevancia a predicción multi-acción con pesos ajustables
• El usuario está envolviendo un puntuador de 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 clasificación", "feed para ti", "pipeline de candidatos", "recomendador de contenido", "arquitectura de pipeline para recsys", "reranker de recuperación RAG"

Cuándo NO usar

• Trabajo de arquitectura de modelos (diseño de transformers, recuperación de dos torres, entrenamiento de embeddings) — este skill es la infraestructura alrededor del modelo, no el modelo en sí
• Pipelines de entrenamiento de 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	Source	Obtener candidatos de uno o más orígenes	Sí — múltiples fuentes se ejecutan en paralelo
2	Hydrator	Enriquecer cada candidato con los metadatos necesarios para el filtrado y la puntuación	Sí — hidratadores independientes se ejecutan en paralelo
3	Filter	Descartar candidatos que nunca deberían mostrarse (bloqueados, caducados, duplicados, no elegibles)	Secuencial — cada filtro ve menos elementos
4	Scorer	Asignar a cada candidato superviviente una o más puntuaciones	Secuencial — los puntuadores posteriores ven las puntuaciones anteriores
5	Selector	Ordenar por puntuación final, devolver top K	Operación única
6	SideEffect	Almacenar en caché IDs servidos, registrar impresiones, emitir eventos, actualizar contadores	Asíncrono — nunca debe bloquear la respuesta

Por qué este orden exacto

• Sources antes de hydratación: saber qué candidatos existen antes de pagar por enriquecerlos
• Hydratació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 único puntuador): los sistemas reales combinan puntuación ML + reranking de diversidad + reglas de negocio
• Selector después de la puntuación: mantiene la puntuación determinista y almacenable en caché
• SideEffects al final y asíncronos: los efectos secundarios nunca deben bloquear la respuesta del usuario

Flujo de trabajo al invocarse

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

1. Aclarar el caso de uso (una ronda, tres preguntas): ¿elementos a clasificar? ¿contexto de entrada? ¿idioma/entorno de ejecución?
2. Identificar las fuentes de candidatos: normalmente dentro de la red (seguidos/propios/suscritos) + fuera de la red (recuperación ML / tendencias / similar-a-gustados)
3. Listar las hidrataciones necesarias: 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 (multi-acción con pesos) → diversidad → reglas de negocio
6. Selector: ordenar descendente por puntuación final, tomar top K (o mezcla estratificada para dentro de la red/fuera de la red)
7. SideEffects: almacenar en caché IDs servidos, emitir eventos de impresión, actualizar contadores, registrar analíticas — todo disparar y olvidar
8. Generar el andamio en el stack del usuario

Compensaciones clave a exponer (no establecer valores predeterminados en silencio)

1. Puntuación única vs predicción multi-acción

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

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

2. Aislamiento de candidatos en la puntuación

• Aislado: cada candidato puntuado de forma independiente. Determinista, almacenable en caché.
• 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. En línea vs fuera de línea

• En tiempo de solicitud (en línea): el pipeline se ejecuta en cada solicitud. Presupuesto de latencia: 100–300ms. Por defecto.
• Precomputado (lote fuera de línea): el pipeline se ejecuta periódicamente, resultados almacenados en caché. Menor latencia, menor frescura.
• Híbrido: recuperación de candidatos fuera de línea, clasificación en línea.

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 marca registrada. No nombrar el artefacto del usuario como "similar a X" o usar la marca "For You". El patrón es libre; la marca no lo es. Nombres sugeridos: "pipeline de candidatos", "pipeline de feed", "pipeline de clasificación", "pipeline de recsys".
4. Exponer compensaciones. Multi-acción vs única, aislado vs conjunto, en línea vs fuera de línea — nunca establecer valores predeterminados en silencio.
5. El andamio generado debe ejecutarse. No se acepta pseudocódigo que pase por 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 (goroutines / promesas sin await / tareas asyncio).

Anti-patrones

• Puntuación antes del filtrado (desperdicia cómputo en candidatos que serán descartados de todas formas)
• Efectos secundarios síncronos (escrituras en caché / emisiones de impresión bloqueando la respuesta)
• Una única puntuación de "relevancia" cuando el producto necesita ajustar múltiples objetivos (compromiso vs seguridad vs diversidad vs anuncios)
• Puntuación conjunta como predeterminada (no determinista, más difícil de almacenar en caché, no se compone con etapas de reranking)
• 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 completo con el flujo de trabajo de 8 pasos
• 5 documentos de referencia cargables bajo demanda: interfaces en 4 lenguajes (TS/Go/Python/Rust), patrón de puntuación multi-acció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 pasando su suite de pruebas:
  • 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)

Instalación mediante skills.sh: npx skills add mturac/recsys-pipeline-architect