Skip to main content

Reranking Candidate Items

While Shaped excels at retrieving and ranking items from your ingested catalog, there are scenarios where you may want to provide your own pre-selected candidate items for ranking. This can be useful for:

  • Integrating with external retrieval systems: You might already have a sophisticated retrieval mechanism in place and simply want to leverage Shaped's ranking capabilities.
  • Real-time reranking: For rapidly changing content, you can pre-filter items based on real-time signals and use Shaped to rerank them based on the latest user context.
  • Custom ranking logic: You can implement custom logic to generate candidate items and use Shaped to fine-tune the ranking based on user preferences.

Shaped offers two ways to rank your own candidate items:

1. Ranking by Item IDs: item_ids

Use the item_ids argument in the Rank API to provide a list of item IDs that you want to rank:

Install
npm install @shaped.ai/client
const shapedai = require('@shaped.ai/client');

async function trendingItems() {
const client = shapedai.Client('your_api_key');
const model_name = 'for_you_feed_v1';
const user_id = '1';
const item_ids= ['item1', 'item2', 'item3'];
const limit = 5;
const results = await client.rank({model_name, item_ids, limit});
console.log(results);
}

Shaped will:

  1. Retrieve Item Features: Fetch the corresponding features for each provided item ID from your integrated data sources.
  2. Score and Rank: Use your trained recommendation model to score the items based on their features and the user's context.
  3. Return Ranked List: Return the items in descending order of predicted relevance to the user.

This approach is efficient when you have a relatively small number of candidate items and their features are already stored within Shaped's item catalog.

2. Ranking by Item Features: item_features

For real-time reranking or scenarios where item features haven't been ingested into Shaped yet, use the item_features argument. This argument accepts a list of dictionaries, where each dictionary represents an item and its features:

item_features = [
{"item_id": "item999", "category": "news", "publish_date": "2023-10-27T12:00:00Z"},
{"item_id": "item888", "category": "sports", "publish_date": "2023-10-26T18:30:00Z"},
// ... more items and their features
]

shaped rank --model_name my_recommendation_model --user_id "XA123F2" \
--item_features "$item_features"

Note: In this example, we're passing the item_features variable as a stringified JSON object. Adapt this based on your CLI or API client requirements.

With item_features, Shaped directly uses the provided features for scoring and ranking, bypassing the need to fetch them from your data sources. This enables real-time ranking of items even before their features are fully integrated into Shaped.

Conclusion

By accepting both item_ids and item_features, Shaped offers flexibility and control over the candidate item selection process. This enables you to seamlessly integrate Shaped into various workflows, including those with external retrieval systems or requiring real-time reranking capabilities.