Quick Start

Prerequisites

Before setting up the X For You algorithm, ensure your environment meets the following requirements:

• Python 3.10+: Required for the Phoenix (ML) models.
• Rust 1.75+: Required for the Home Mixer, Thunder, and Candidate Pipeline services.
• JAX with CUDA support: Recommended for running the Grok-based transformer models on GPU.
• Kafka: Required for the Thunder service to consume tweet events.

1. Environment Setup

Clone the repository and install the necessary dependencies for both the ML and service layers.

Python Environment

# Install Phoenix ranking and retrieval dependencies
pip install jax jaxlib dm-haiku
pip install git+https://github.com/xai-org/grok-1.git

Rust Services

# Build the orchestration and retrieval services
cargo build --release

2. Running the Phoenix Ranker (Python)

The Phoenix model is the core of the recommendation engine. You can initialize the Grok-based transformer to score candidates based on user history.

import jax
import jax.numpy as jnp
from grok import TransformerConfig
from phoenix.recsys_model import PhoenixRecsysModel, RecsysBatch

# 1. Configure the model (Grok-based architecture)
config = TransformerConfig(
    emb_size=128,
    num_layers=4,
    num_q_heads=4,
    num_kv_heads=4,
    widening_factor=4
)

# 2. Initialize model and dummy inputs
model = PhoenixRecsysModel(config=config, model=config.make())
batch = RecsysBatch(
    user_hashes=jnp.array([[123, 456]]),
    history_post_hashes=jnp.zeros((1, 128, 2), dtype=jnp.int32),
    # ... fill other batch fields
)

# 3. Perform scoring
# In practice, use hk.transform to manage JAX state

3. Launching the Data Pipeline (Rust)

The algorithm relies on Thunder for in-network content and Home Mixer for orchestration.

Start Thunder (In-Network Fetcher)

Thunder listens to Kafka for real-time tweet events and stores them in an in-memory PostStore.

./target/release/thunder \
    --grpc-port 50051 \
    --http-port 8080 \
    --post-retention-seconds 86400 \
    --kafka-group-id "for-you-consumer"

Start Home Mixer (The Orchestrator)

Home Mixer acts as the entry point, coordinating the retrieval of candidates and passing them to Phoenix for ranking.

./target/release/home-mixer \
    --grpc-port 50052 \
    --metrics-port 9090 \
    --chunk-size 100

4. Making Your First Request

Once the services are running, you can request a "For You" feed by calling the ScoredPostsService via gRPC.

The Home Mixer will:

1. Hydrate the Query: Look up the user's recent actions and features.
2. Retrieve Candidates: Fetch posts from Thunder (In-Network) and Phoenix (Out-of-Network).
3. Score and Rank: Use the Phoenix transformer to calculate engagement probabilities.
4. Filter: Apply safety and variety filters.

Example gRPC call (using grpcurl)

grpcurl -plaintext \
    -d '{"user_id": "12345", "count": 20}' \
    localhost:50052 \
    xai.home_mixer.pb.ScoredPostsService/GetScoredPosts

Next Steps

• Configure Ranking Weights: Adjust the engagement multipliers in the scoring layer to prioritize likes, replies, or shares.
• Custom Filtering: Modify candidate-pipeline/filter.rs to implement custom exclusion logic or community safety standards.
• Model Training: Refer to the Phoenix Retrieval Guide to learn how to train the two-tower retrieval model on your own interaction datasets.