# X For You Algorithm Documentation

> Technical reference for the X For You recommendation stack: Phoenix retrieval and ranking, Home Mixer orchestration, Thunder in-network storage, Grox content understanding, and the Candidate Pipeline framework.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c)
- [GitHub repository](https://github.com/xai-org/x-algorithm)

## Repository

- Repository: xai-org/x-algorithm

- Generated: 2026-08-13T19:56:12.136Z
- Updated: 2026-08-13T20:05:51.617Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 25

## Pages

- [Overview](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/01-overview.md): Public surfaces of the For You stack, who can run what from this checkout, and the first docs routes to follow.
- [Installation](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/02-installation.md): Python 3.11+, uv or pip, Git LFS for the Phoenix artifact archive, and the extract layout required before inference.
- [Quickstart](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/03-quickstart.md): Extract oss-phoenix-artifacts, run run_pipeline.py, and recognize the ranked table as the success signal.
- [Runtime boundaries](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/04-runtime-boundaries.md): What this checkout can execute locally versus production Home Mixer, Thunder, and Grox snapshots that depend on unpublished crates.
- [For You request lifecycle](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/05-for-you-request-lifecycle.md): CandidatePipeline.execute stages from query hydration through side effects, and how ForYouCandidatePipeline wraps PhoenixCandidatePipeline.
- [In-network and out-of-network](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/06-in-network-and-out-of-network.md): Thunder followed-author lookup versus Phoenix retrieval, enable predicates, and how in_network_only changes sourcing and served_type.
- [Candidate isolation](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/07-candidate-isolation.md): make_recsys_attn_mask rules: candidates attend to user and history plus self, never to other candidates, so scores stay batch-independent.
- [Hash embeddings](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/08-hash-embeddings.md): HashConfig, linear-congruential ID hashing, pad-offset unified tables, and how RecsysBatch hashes are looked up before the transformer.
- [Multi-action scoring](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/09-multi-action-scoring.md): Per-action logits, demo weighted sums in run_pipeline.py, and production WeightedScorer versus RankingScorer weight tables.
- [Run the inference pipeline](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/10-run-the-inference-pipeline.md): Load retrieval and ranker checkpoints, encode example_sequence.json, retrieve from sports_corpus.npz, and rank with the published action weights.
- [Customize a user sequence](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/11-customize-a-user-sequence.md): example_sequence.json fields, ActionName indices, history padding to history_seq_len, and --top_k_retrieval / --top_k_display knobs.
- [Assemble a Home Mixer request](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/12-assemble-a-home-mixer-request.md): HomeMixerServer CLI flags, QueryBuilder.viewer_id validation, ScoredPostsQuery construction, and For You versus ScoredPosts entry points.
- [Blend ads into the feed](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/13-blend-ads-into-the-feed.md): AdsSource intake, SafeGapAdsBlender versus PartitionOrganicAdsBlender, AdsBlenderType selection, and prompt / who-to-follow / push-to-home insertion.
- [Execute Grox content plans](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/14-execute-grox-content-plans.md): Engine, Dispatcher, and GrpcServer startup, PlanMaster fan-out, TaskEligibility gating, and merged TaskResult fields.
- [Add a pipeline component](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/15-add-a-pipeline-component.md): Source, Hydrator, Filter, Scorer, Selector, QueryHydrator, and SideEffect contracts, including length-match and no-drop rules.
- [Phoenix model configuration](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/16-phoenix-model-configuration.md): PhoenixModelConfig and PhoenixRetrievalModelConfig fields, TransformerConfig, RecsysBatch, RecsysEmbeddings, and published config.json keys.
- [Action indices](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/17-action-indices.md): ActionName indices used in example_sequence.json, run_pipeline.py IDX_* constants, runners.ACTIONS labels, and scorer weight keys.
- [ScoredPostsQuery and gRPC](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/18-scoredpostsquery-and-grpc.md): ScoredPostsQuery fields, QueryBuilder defaults, TEST_USER_IDS empty responses, and ScoredPost / ForYouFeed / URT response mapping.
- [Candidate sources](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/19-candidate-sources.md): PhoenixCandidatePipeline and ForYouCandidatePipeline sources, enable predicates, cluster resolution, and served_type assignment.
- [Filters and hydrators](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/20-filters-and-hydrators.md): Pre-score and post-selection filters, query hydrators that fill ScoredPostsQuery, and candidate hydrators that must preserve order and length.
- [Scorers and weights](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/21-scorers-and-weights.md): PhoenixScorer cluster and egress fallback, WeightedScorer and RankingScorer formulas, AuthorDiversityScorer decay, OON and VM rankers, TopKScoreSelector.
- [Thunder GetInNetworkPosts](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/22-thunder-getinnetworkposts.md): InNetworkPostsService RPC fields, PostStore timelines and retention, Kafka ingest, semaphore capacity, and Strato following-list fallback.
- [Grox plans and tasks](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/23-grox-plans-and-tasks.md): PlanMaster.ALL_PLANS, TaskEligibility values, DAG TASK_DEPENDENCIES, ContentClassifier, and TaskResult merge rules.
- [Test Phoenix](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/24-test-phoenix.md): uv run pytest targets, attention-mask and retrieval assertions, and the success criteria encoded in the Phoenix test modules.
- [Troubleshooting](https://grok-wiki.com/public/docs/xai-org-x-algorithm-23c09c39074c/pages/25-troubleshooting.md): LFS and artifact-path failures, viewer_id must be specified, TEST_USER_IDS empty feeds, Thunder RESOURCE_EXHAUSTED, missing retrieval_sequence, and unpublished Grox modules.

## Source Files

- `.gitattributes`
- `candidate-pipeline/candidate_pipeline.rs`
- `candidate-pipeline/filter.rs`
- `candidate-pipeline/hydrator.rs`
- `candidate-pipeline/lib.rs`
- `candidate-pipeline/query_hydrator.rs`
- `candidate-pipeline/scorer.rs`
- `candidate-pipeline/selector.rs`
- `candidate-pipeline/side_effect.rs`
- `candidate-pipeline/source.rs`
- `grox/classifiers/content/classifier.py`
- `grox/dispatcher.py`
- `grox/engine.py`
- `grox/main.py`
- `grox/plans/plan_master.py`
- `grox/plans/plan_post_safety.py`
- `grox/plans/plan.py`
- `grox/schedules/types.py`
- `grox/tasks/task.py`
- `home-mixer/ads/mod.rs`
- `home-mixer/ads/partition_organic_blender.rs`
- `home-mixer/ads/safe_gap_blender.rs`
- `home-mixer/ads/util.rs`
- `home-mixer/candidate_hydrators/ads_brand_safety_hydrator.rs`
- `home-mixer/candidate_hydrators/core_data_candidate_hydrator.rs`
- `home-mixer/candidate_hydrators/mod.rs`
- `home-mixer/candidate_pipeline/for_you_candidate_pipeline.rs`
- `home-mixer/candidate_pipeline/phoenix_candidate_pipeline.rs`
- `home-mixer/filters/age_filter.rs`
- `home-mixer/filters/mod.rs`
- `home-mixer/filters/vf_filter.rs`
- `home-mixer/for_you_server.rs`
- `home-mixer/lib.rs`
- `home-mixer/main.rs`
- `home-mixer/models/candidate.rs`
- `home-mixer/models/query.rs`
- `home-mixer/models/user_features.rs`
- `home-mixer/query_hydrators/mod.rs`
- `home-mixer/query_hydrators/retrieval_sequence_query_hydrator.rs`
- `home-mixer/query_hydrators/scoring_sequence_query_hydrator.rs`
- `home-mixer/scored_posts_server.rs`
- `home-mixer/scorers/author_diversity_scorer.rs`
- `home-mixer/scorers/mod.rs`
- `home-mixer/scorers/oon_scorer.rs`
- `home-mixer/scorers/phoenix_scorer.rs`
- `home-mixer/scorers/ranking_scorer.rs`
- `home-mixer/scorers/vm_ranker.rs`
- `home-mixer/scorers/weighted_scorer.rs`
- `home-mixer/selectors/blender_selector.rs`
- `home-mixer/selectors/top_k_score_selector.rs`
- `home-mixer/server.rs`
- `home-mixer/sources/ads_source.rs`
- `home-mixer/sources/cached_posts_source.rs`
- `home-mixer/sources/mod.rs`
- `home-mixer/sources/phoenix_moe_source.rs`
- `home-mixer/sources/phoenix_source.rs`
- `home-mixer/sources/phoenix_topics_source.rs`
- `home-mixer/sources/thunder_source.rs`
- `LICENSE`
- `phoenix/artifacts/oss-phoenix-artifacts.zip`
- `phoenix/grok.py`
- `phoenix/pyproject.toml`
- `phoenix/README.md`
- `phoenix/recsys_model.py`
- `phoenix/recsys_retrieval_model.py`
- `phoenix/run_pipeline.py`
- `phoenix/run_ranker.py`
- `phoenix/run_retrieval.py`
- `phoenix/runners.py`
- `phoenix/test_recsys_model.py`
- `phoenix/test_recsys_retrieval_model.py`
- `phoenix/uv.lock`
- `README.md`
- `thunder/kafka_utils.rs`
- `thunder/kafka/tweet_events_listener.rs`
- `thunder/lib.rs`
- `thunder/main.rs`
- `thunder/posts/post_store.rs`
- `thunder/thunder_service.rs`