ArgoFeed

Appearance

Getting Started ​

This guide will walk you through the basics of using the ArgoFeed SDK to build your personalized experience.

Key Concepts ​

Here are the key concepts you'll need to understand:

  • Items. These are the content pieces you want to recommend. They can be anything - products, articles, videos, songs, or any other content type. Each item has a unique ID and attributes like title, description, tags, etc.

  • Users. These represent the people using your app. Like items, users have unique IDs and can have attributes that help personalize their experience (e.g. interests, demographics).

  • Events. These capture how users interact with items in your app. Common events include views, clicks, likes, purchases, and shares. Events help build user preferences and improve recommendations.

Depending on your use case, you'll use one or more of these concepts in order to build your optimal user experience.

Examples ​

Once you have your API key, you can start using the SDK.

python
from argofeed import ArgoFeed

af = ArgoFeed(api_key="your-api-key")

Items ​

The Item class can be used to define items and set attributes ranging from text to photos and from categories to prices.

python
from argofeed import Item
from argofeed.types import Image, Text, Tag, MultiTag, Number

item = Item(id="item-1").with_attributes(
    Text(name="title").value("Blue T-Shirt"),
    Tag(name="color").value("blue"),
    MultiTag(name="categories").values(["clothing", "t-shirt"]),
    Number(name="price").value(29.99),
    Image(name="image_url").value("https://..."),
)
af.add(item)

At this point, you can already start generating non-personalized results. For example, you can search and filter for items:

python
results = af.search(
    query="blue t-shirt",
    limit=10,
    filters=[
        MultiTag(name="categories").contains("clothing"),
    ]
)
for item in results:
    print(f"{item.title} ({item.id})")

Or, given an existing item, you can find similar items to show users:

python
similar_items = af.similar_items(
    item_id="item-1",
    limit=10
)
for item in similar_items:
    print(f"{item.name} ({item.id})")

This can be used to power features such as Amazon's "More like this" section or Spotify's "You might also like" section.

Users ​

The User class can be used to define users and set a similar set of attributes as items.

python
from argofeed import User
from argofeed.types import Text, MultiTag, Number

user = User(id="user-1").with_attributes(
    Text(name="biography").value("I'm a software engineer who loves to code."),
    MultiTag(name="interests").values(["science", "technology"]),
    Number(name="age").value(25),
    Image(name="profile_picture").value("https://..."),
)
af.add_user(user)

Once a user is registered, you can start generating personalized results. For example, you can suggest items to a user:

python
recommendations = af.suggest(
    user_id="user-1",
    limit=10
)
for item in recommendations:
    print(f"{item.name} ({item.id})")

These recommendations are personalized based on the user's attributes and the items' attributes. For example, the user's biography states they like to code, so the recommendations will include items relevant to coding.

python
recommendations = af.suggest(
    user_id="user-1",
    limit=10
)
for item in recommendations:
    print(f"{item.name} ({item.id})")

But to take the personalized experience to the next level, you can also track user interactions.

Events ​

TIP

By default, all event types are considered positive (i.e. likes, views, clicks, etc.). You can configure the sign and weight of your event types in your project settings.

The Event class can be used to track user interactions with items.

python
from argofeed import Event

event = Event(
    user_id="user-1",
    item_id="item-1",
    event_type="view",
)
af.add_event(event)

As events are added, they are used to improve the recommendations to maximize positive interactions and minimize negative ones.

If you call suggest again, now that you've added an event, the recommendations will be personalized based not just on the user's attributes but also on their interactions.