Overview
Sources implement theSource trait which provides an asynchronous get_candidates method that returns a list of PostCandidate objects. Each source can optionally implement an enable method to conditionally activate based on query parameters.
ThunderSource
The Thunder source retrieves in-network posts from users that the viewer follows. It queries the Thunder service’s AMP cluster to fetch posts from the user’s following list.Implementation
Configuration
Client for communicating with the Thunder service clusters
The Thunder cluster to query (defaults to Amp cluster)
Maximum number of posts to retrieve from Thunder service (configured via
THUNDER_MAX_RESULTS)Request Parameters
When querying Thunder, the source constructs a request with:- user_id: The viewer’s user ID
- following_user_ids: List of user IDs the viewer follows
- max_results: Maximum posts to retrieve
- algorithm: Retrieval algorithm (defaults to “default”)
- exclude_tweet_ids: Posts to exclude from results
Output Fields
The unique identifier of the post
The user ID of the post author
If the post is a reply, the ID of the parent post
List of ancestor post IDs in the conversation thread. Includes the immediate parent and conversation root if different.
Set to
ForYouInNetwork to indicate this candidate came from the user’s networkCode Example
home-mixer/sources/thunder_source.rs
PhoenixSource
The Phoenix source retrieves out-of-network posts using the Phoenix retrieval service. It leverages the user’s action sequence to find relevant posts from outside their following graph.Implementation
Configuration
Client for communicating with the Phoenix retrieval service
Maximum number of posts to retrieve (configured via
PHOENIX_MAX_RESULTS)Conditional Activation
Phoenix source includes anenable method that checks query parameters:
home-mixer/sources/phoenix_source.rs
in_network_only is true, ensuring only Thunder results are used.
Requirements
Phoenix source requires theuser_action_sequence to be present in the query. This sequence captures the user’s recent interactions and is used by Phoenix to understand user preferences.
Output Fields
The unique identifier of the post
The user ID of the post author
If the post is a reply, the ID of the parent post
Set to
ForYouPhoenixRetrieval to indicate this candidate came from PhoenixCode Example
home-mixer/sources/phoenix_source.rs
Source Pipeline Integration
Both sources are typically used together in the Phoenix candidate pipeline. Thunder provides in-network candidates while Phoenix provides out-of-network candidates, creating a diverse feed that balances familiar content with discovery.Typical Flow
- Thunder Source queries the user’s following graph
- Phoenix Source (if enabled) retrieves out-of-network recommendations
- Candidates from both sources are merged
- Subsequent pipeline stages apply filters and scoring
Error Handling
Both sources returnResult<Vec<PostCandidate>, String>, allowing the pipeline to handle failures gracefully. Common error scenarios include:
- No available service channels
- Network timeouts
- Missing required query fields
- Service-level errors
Related Components
- Filters - Filter candidates after source retrieval
- Scorers - Score candidates for ranking
- Phoenix Scorer - Scores Phoenix candidates using ML predictions