Weaviate Personalization Agent
To be notified when this agent is released, sign up here for updates.
The Weaviate Personalization Agent is an agentic service designed to return personalized recommendations tailored to each user. The Personalization Agent uses data from the associated Weaviate Cloud instance to provide these recommendations.
The Personalization Agent is all about providing personalized recommendations tailored to a particular person. In this context, that person will be referred to as the user. The developer is the person who is using the Personalization Agent to provide these recommendations.
The developer would simply provide a user profile, and the Personalization Agent takes care of all intervening steps to provide a set of personalized recommendations from Weaviate. The resulting workflow for the developer looks as follows:
The official changelog for Weaviate Agents can be found here. If you have feedback, such as feature requests, bug reports or questions, please submit them here, where you will be able to see the status of your feedback and vote on others' feedback.
Architecture
The Personalization Agent is provided as a service on Weaviate Cloud.
When a user-specific recommendations request is made, the Personalization Agent analyses the user profile and any other known context to autonomously carry out the searches itself. The context may include data about the previous user interactions, information about the user themselves, and any other relevant information.
The Personalization Agent uses the contextual information to not only retrieve the most relevant recommendations, but also to rank them for the user.
Personalization Agent: visualized workflow
The Personalization Agent works as follows at a high level:
- Create a Weaviate-managed user collection, which will store each user's profiles & previous interactions for each user.
- When a request for personalized recommendations is made, the Personalization Agent fetches the user data, and analyze it to determine patterns and preferences.
- Perform initial searches in Weaviate based on the analysis to retrieve the most relevant recommendations.
- Use appropriate generative models to determine any additional search strategies, and to re-rank fetched data as required.
- Perform additional searches in Weaviate as needed to retrieve the final set of recommendations.
- Combine and rank the recommendations based on the user's profile and preferences.
Then, the Personalization Agent returns the user-specific recommendations in the response. The response will also include intermediate outputs, such as the underlying search results from Weaviate.
Let's dive into a little more detail about the Personalization Agent.
User profiles
The Personalization Agent uses user profiles to provide personalized recommendations. This information is stored in a collection in your Weaviate instance under a specific name. The user profile may include the user's preferences and previous interactions, such as their likes and dislikes.
As shown here, the user data collection can be updated over time. It can be updated with information about new users, or with new information about existing users.
This will help the Personalization Agent continue to learn and provide the most relevant, up-to-date recommendations to each user.
Recommendations
There are two major components to the Personalization Agent's recommendations, the searches it performs to retrieve the recommendations, and the ranking of the recommendations.
Searches
The Personalization Agent performs searches in Weaviate to retrieve the most relevant recommendations for the user from the specified collections.
The diagram depicts that the search process may be based on a number of factors:
- The user's profile and preferences, fetched from the user data collection.
- The user's previous interactions, fetched from the user data collection.
- The recommendation context, such as the type of recommendations requested or any other relevant information.
- Additional search strategies, as determined by the Personalization Agent.
The Personalization Agent may perform multiple searches in Weaviate to retrieve the most relevant recommendations, before combining and ranking them.
(Re-)Ranking
The Personalization Agent uses multiple factors to rank the recommendations it retrieves from Weaviate, so that the final result set is tailored to the user's preferences.
The rankings may be based on a number of factors:
- The user's profile and preferences, fetched from the user data collection.
- The user's previous interactions, fetched from the user data collection.
- The recommendation context, such as the type of recommendations requested or any other relevant information.
- Additional ranking strategies, as determined by the Personalization Agent.
This process ranks the combined result set as a whole, before serving them back in the response.
Usage
To be notified when this agent is released, sign up here for updates.
Prerequisites
The Personalization Agent is tightly integrated with Weaviate Cloud. As a result, the Personalization Agent is available exclusively for use with a Weaviate Cloud instance, and a supported version of the client library.
Connect to Personalization Agent
Provide the following to the Personalization Agent:
- Your Weaviate Cloud instance details (e.g. the
WeaviateClientobject in Python) to the Personalization Agent. - A list of the collections that the Personalization Agent may use to produce recommendations.
- Python
# [🚧 UNDER CONSTRUCTION 🚧] This Weaviate Agent is not available just yet.
# These snippets are indicative. The syntax may change when this Agent is released.
import os
import weaviate
from weaviate.classes.init import Auth
from weaviate.agents.personalization import PersonalizationAgent
# Provide your required API key(s), e.g. for the configured vectorizer(s)
headers = {
# Provide your required API key(s), e.g. Cohere, OpenAI, etc. for the configured vectorizer(s)
"X-INFERENCE-PROVIDER-API-KEY": os.environ.get("YOUR_INFERENCE_PROVIDER_KEY", ""),
}
client = weaviate.connect_to_weaviate_cloud(
cluster_url=os.environ.get("WCD_URL"),
auth_credentials=Auth.api_key(os.environ.get("WCD_API_KEY")),
headers=headers,
)
# Instantiate a new agent object, and specify the collections to query
# The Personalization Agent will automatically also connect to the user data collection
pa = PersonalizationAgent(
client=client, collections=["ecommerce"]
)
Obtain personalized recommendations
In the simplest form, provide a user profile to the Personalization Agent. The Personalization Agent will process the user profile, perform the necessary searches in Weaviate, and return the personalized recommendations.
- Python
# [🚧 UNDER CONSTRUCTION 🚧] This Weaviate Agent is not available just yet.
# These snippets are indicative. The syntax may change when this Agent is released.
# Perform a query
response = pa.recommndations.item.from_user(
user_id="cpierse_123"
)
# Print the response
for i in response.recommendations.items:
print(i)
Query with parameters
Additional parameters can be provided to the Personalization Agent to further tune the recommendations.
- Python
# [🚧 UNDER CONSTRUCTION 🚧] This Weaviate Agent is not available just yet.
# These snippets are indicative. The syntax may change when this Agent is released.
# Perform a query
response = pa.recommndations.item.from_user(
user_id="charlesp_123", limit=10, top_n_interactions=100
)
# Print the response
for i in response.recommendations.items:
print(i["product_id"])
print(i["category"])
print(i["title"])
Update user data
The Personalization Agent relies on each individual user's profile to provide personalized recommendations.
The API includes ways to provide this information when creating the agent. Additionally, you can update the user data collection with new information over time, so that the Personalization Agent can learn from the latest available data.
Add user properties
Fields for user properties can be added to the user data collection at any time.
- Python
# [🚧 UNDER CONSTRUCTION 🚧] This Weaviate Agent is not available just yet.
# These snippets are indicative. The syntax may change when this Agent is released.
from weaviate.classes.agents import UserProperty
from weaviate.classes.config import DataType
# Add user properties
response = pa.users.add_properties(
properties=[
UserProperty(name="age", data_type=DataType.INT),
UserProperty(name="hobbies", data_type=DataType.TEXT),
UserProperty(name="location", data_type=DataType.TEXT),
]
)
Add users
New users can be added to the user data collection at any time.
- Python
# [🚧 UNDER CONSTRUCTION 🚧] This Weaviate Agent is not available just yet.
# These snippets are indicative. The syntax may change when this Agent is released.
from weaviate.classes.agents import UserEntry
# Add new users to the user data collection
# Here, `user_data_list` is a list of dictionaries, each containing the user data
response = pa.users.add_users(
users=[
UserEntry(
name=user_data["name"],
user_id=user_data["user_id"],
properties={
"age": user_data["age"],
"hobbies": user_data["hobbies"],
"location": user_data["location"]
}
) for user_data in [user_data_list]
]
)
Update user interactions
Additional interactions can be added one at a time, or in bulk.
- Python
# [🚧 UNDER CONSTRUCTION 🚧] This Weaviate Agent is not available just yet.
# These snippets are indicative. The syntax may change when this Agent is released.
from weaviate.classes.agents import UserInteraction
# Add new interactions to the user data collection
response = pa.users.add_interaction(
interactions=[
UserInteraction(
user_id="charlesp_123",
item_id="product_581",
interaction_property_name="view",
weight=1.0
),
UserInteraction(
user_id="charlesp_123",
item_id="product_75",
interaction_property_name="like",
weight=1.0
),
UserInteraction(
user_id="bob_321",
item_id="product_812",
interaction_property_name="purchase",
weight=1.0
),
],
remove_previous_interactions=False
)
Questions and feedback
If you have any questions or feedback, let us know in the user forum.