This repository contains the core recommendation system powering the "For You" feed on X. It combines in-network content (from accounts you follow) with out-of-network content (discovered through ML-based retrieval) and ranks everything using a Grok-based transformer model.

Note: The transformer implementation is ported from the Grok-1 open source release by xAI, adapted for recommendation system use cases.

Table of Contents

Updates — May 15th, 2026 Overview System Architecture Components

Home Mixer Thunder Phoenix Candidate Pipeline

How It Works

Pipeline Stages Scoring and Ranking Filtering

Key Design Decisions License

Updates — May 15th, 2026 This release updates the For You algorithm code, including a runnable end-to-end inference pipeline alongside new components for content understanding, ads, and candidate sourcing.

End-to-end inference pipeline: A new phoenix/run_pipeline.py replaces the separate run_ranker.py and run_retrieval.py scripts with a single entry point that runs retrieval → ranking from exported checkpoints, mirroring how the two stages are composed in production.

Pre-trained model artifacts: A pre-trained mini Phoenix model (256-dim embeddings, 4 attention heads, 2 transformer layers) is now packaged as a ~3 GB archive distributed via Git LFS, enabling out-of-the-box inference without training your own model first.

Grox content-understanding pipeline: A new grox/ service is included, providing classifiers, embedders, and a task-execution engine for content understanding workloads such as spam detection, post-category classification, and PTOS policy enforcement.

Ads blending system: Includes a new home-mixer/ads/ module that handles ad injection and positioning within the feed, including brand-safety tracking that respects sensitive content boundaries.

Query hydrators: Home mixer now hydrates user context including followed topics, starter packs, impression bloom filters, IP, mutual follow graphs, and served history.

Candidate hydrat