recsys-pipeline-architect

name	recsys-pipeline-architect
description	xAIがオープンソース化した「For You」アルゴリズムで普及した6ステージのSource→Hydrator→Filter→Scorer→Selector→SideEffectフレームワークを使用して、コンポーザブルな推薦・ランキング・フィードパイプラインを設計します。ユーザーがソーシャルフィード、コンテンツCMS、RAGリランカー、タスク優先順位付け、通知トリアージ、検索リランキング、広告ランキングなど「(ユーザー、コンテキスト)に対するトップKアイテムを選択する」システムを構築する場合に使用してください。
origin	community

recsys-pipeline-architect

コンポーザブルな推薦・ランキング・フィードパイプラインを構築するためのスペック・スキャフォールドスキル。xAIがオープンソース化したFor Youアルゴリズム（Apache 2.0）で普及した6ステージパターン — Source → Hydrator → Filter → Scorer → Selector → SideEffect — をエンコードしています。このスキルはパターンの独立した再実装（MIT）であり、元のコードはコピーされていません。

アップストリーム: https://github.com/mturac/recsys-pipeline-architect

使用タイミング

• ユーザーが「ユーザー/コンテキストに対するトップKアイテムを選択する」システムを構築したい場合
• ユーザーが「Xをどのようにランク付けすべきか」と尋ねるか、フィード/パーソナライゼーションの問題を説明する場合
• ユーザーがスコアリング関数を持ち、その周囲のパイプラインの配管が必要な場合
• ユーザーが単一の関連性スコアから調整可能な重みを持つマルチアクション予測に移行したい場合
• ユーザーがLLM/MLスコアラーをラップしており、フィルター、ハイドレーター、サイドエフェクト、および自分のスタック（TypeScript / Go / Python）で実行可能なスキャフォールドが必要な場合
• トリガー: 「レコメンデーションシステム」、「フィードアルゴリズム」、「ランキングパイプライン」、「for youフィード」、「候補パイプライン」、「コンテンツレコメンダー」、「recsysのパイプラインアーキテクチャ」、「RAG検索リランカー」

使用しないタイミング

• モデルアーキテクチャの作業（トランスフォーマー設計、2塔式検索、埋め込みトレーニング） — このスキルはモデル自体ではなく、モデルの周囲の配管です
• 純粋なMLトレーニングパイプライン — スコアリング関数はユーザーの責任です
• デプロイ済みパイプラインの運用（監視、オートスケーリング） — スコープ外

6ステージフレームワーク

#	ステージ	役割	並列?
1	Source	1つ以上の起点から候補を取得する	あり — 複数のソースは並列実行
2	Hydrator	フィルタリングとスコアリングに必要なメタデータで各候補を強化する	あり — 独立したハイドレーターは並列実行
3	Filter	表示すべきでない候補を除外する（ブロック済み、期限切れ、重複、対象外）	順次 — 各フィルターはより少ないアイテムを処理
4	Scorer	生き残った各候補に1つ以上のスコアを割り当てる	順次 — 後のスコアラーは前のスコアを参照
5	Selector	最終スコアでソートし、トップKを返す	単一操作
6	SideEffect	提供されたIDをキャッシュし、インプレッションをログに記録し、イベントを発行し、カウンターを更新する	非同期 — レスポンスをブロックしてはならない

この正確な順序の理由

• ハイドレーション前のソース: 強化にコストをかける前に候補が何かを知る
• フィルタリング前のハイドレーション: 多くのフィルターはソースが提供しなかったメタデータを必要とする
• スコアリング前のフィルタリング: スコアリングは高コストなステージ；まず対象外のものを除外する
• スコアラーチェーン（単一スコアラーではなく）: 実際のシステムはMLスコアリング + 多様性リランキング + ビジネスルールを組み合わせる
• スコアリング後のセレクター: スコアリングを決定論的かつキャッシュ可能に保つ
• SideEffectsは最後で非同期: サイドエフェクトはユーザーレスポンスをブロックしてはならない

呼び出し時のワークフロー

ユーザーをこの8つのステップに導いてください：

1. ユースケースの明確化（1ラウンド、3つの質問）: ランク付けするアイテムは？入力コンテキストは？言語/ランタイムは？
2. 候補ソースの特定: 通常、ネットワーク内（フォロー済み/所有/購読済み）+ ネットワーク外（ML検索 / トレンド / 類似アイテム）
3. 必要なハイドレーションのリスト: 各フィルターとスコアラーについて、ソースが提供しなかったデータは何が必要か？
4. フィルターのリスト: 重複、自己、年齢、ブロック/ミュート、提供済み、適格性。順序が重要 — 安価なものから高価なものへ。
5. スコアラーチェーンの設計: プライマリ（ML）→ コンバイナー（重み付きマルチアクション）→ 多様性 → ビジネスルール
6. セレクター: 最終スコアで降順ソートし、トップKを取得（またはネットワーク内/外の層別ミックス）
7. SideEffects: 提供されたIDをキャッシュし、インプレッションイベントを発行し、カウンターを更新し、分析をログに記録 — すべてfire-and-forget
8. ユーザーのスタックでスキャフォールドを生成する

表面化すべき重要なトレードオフ（デフォルトで黙って決めない）

1. 単一スコア vs マルチアクション予測

• 単一スコア: 関連性を予測する1つのモデルをトレーニング。動作を変更する → 再トレーニングが必要。
• マルチアクション: 多くのアクション（読む、いいね、シェア、スキップ、報告）に対してP(アクション)を予測し、提供時に重みで組み合わせる。動作を変更する → 重みを変更するだけ。再トレーニング不要。

X For YouシステムはポジティブとネガティブBoth両方の重みを持つマルチアクションを使用しています。ユーザーが頻繁に調整することを期待する場合はマルチアクションを推奨してください。

2. スコアリングにおける候補の独立性

• 独立: 各候補を独立してスコアリング。決定論的でキャッシュ可能。
• ジョイント: 候補がスコアリング中に互いに参照する（例：バッチ上のトランスフォーマー）。より表現力が高いが、バッチ間で非決定論的。

デフォルトは独立性。ジョイントは特定の理由がある場合のみ（例：明示的なバッチ対応の多様性）。

3. オンライン vs オフライン

• リクエスト時（オンライン）: パイプラインが各リクエストで実行。レイテンシ予算: 100〜300ms。デフォルト。
• 事前計算（オフラインバッチ）: パイプラインが定期的に実行され、結果がキャッシュされる。低レイテンシ、低鮮度。
• ハイブリッド: 候補検索はオフライン、ランキングはオンライン。

厳守すべきルール

1. ベンチマーク数値を創作しない。「どれだけ速くなるか？」→「ワークロードに依存するため、自分で実行してください。」
2. 帰属の規律。 パターンが参照される場合は「xAIがオープンソース化したFor Youアルゴリズムで普及した」/ github.com/xai-org/x-algorithm（Apache 2.0）と帰属してください。
3. 商標の不使用。 ユーザーの成果物を「X風」と名付けたり、「For You」ブランドを使用したりしないでください。パターンは自由；ブランドはそうではありません。推奨命名: 「候補パイプライン」、「フィードパイプライン」、「ランキングパイプライン」、「recsysパイプライン」。
4. トレードオフを表面化する。 マルチアクション vs 単一、独立 vs ジョイント、オンライン vs オフライン — デフォルトで黙って決めない。
5. 生成されたスキャフォールドは実行可能でなければならない。 コードとして通用する疑似コードは不可。
6. フィルターの順序は重要。 安価なものから高価なものへ。普遍的なものからユーザー固有のものへ。
7. サイドエフェクトは絶対にブロックしない。 fire-and-forgetパターンでラップする（goroutines / awaitなしのpromises / asyncioタスク）。

アンチパターン

• フィルタリング前のスコアリング（後で除外される候補に対してコンピュートを無駄にする）
• 同期的なサイドエフェクト（キャッシュ書き込み / インプレッション発行がレスポンスをブロックする）
• 製品が複数の目標（エンゲージメント vs 安全性 vs 多様性 vs 広告）のために調整が必要なのに単一の「関連性」スコアを使用する
• デフォルトとしてジョイントスコアリング（非決定論的で、キャッシュが難しく、リランキングステージと組み合わせられない）
• 「説明のための」疑似コードの生成 — スキャフォールドは実際に実行可能でなければならない

アップストリームのコンテンツ

https://github.com/mturac/recsys-pipeline-architectのアップストリームリポジトリには以下が含まれます：

• 完全な8ステップワークフローを含む完全なSKILL.md
• オンデマンドロードの5つのリファレンスドキュメント：4言語（TS/Go/Python/Rust）のインターフェース、マルチアクションスコアリングパターン、候補の独立性、フィルタークックブック（12パターン）、スコアラークックブック（重み付き合計、MMR、多様性ペナルティ、位置デバイアシング）
• 3つの実行可能なスキャフォールド例（すべてテストスイートでグリーン）：
  • Strapi v5プラグイン（TypeScript / Jest — 3/3 pass）
  • Zentra互換パイプライン（ジェネリクスを使用したGo — 3/3 pass）
  • PMAIタスク優先順位付け（Python / FastAPI / pytest — 3/3 pass）
• v0.1.0リリースタグ済み
• MITライセンス；パターンはxAI X For Youアルゴリズムに帰属（Apache 2.0）

skills.sh経由でインストール: npx skills add mturac/recsys-pipeline-architect