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:

JavaScript

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);
}

Python

Install

pip install shaped

import shaped

api_key = 'your_api_key' 
client = shaped.Client(api_key=api_key)

results = client.rank(
  model_name='for_you_feed_v1',
  user_id='1',
  item_ids=['item1', 'item2', 'item3']
  limit=5,
)

CLI

Install

pip install shaped

shaped rank --model_name for_you_feed_v1 --user_id 1 \
           --item_ids ["item1", "item2", "item3"] 

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.