Weaviate Personalization Agent: Usage
Sign up here for notifications on Weaviate Agents, or visit this page to see the latest updates and provide feedback.
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:
This page describes how to use the Weaviate Personalization Agent to obtain personalized recommendations from your data stored in Weaviate.
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.
Prerequisites
Weaviate instance
This Agent is available exclusively for use with a Weaviate Cloud instance.
Refer to the Weaviate Cloud documentation for more information on how to set up a Weaviate Cloud instance.
You can try this Weaviate Agent with a free Sandbox instance on Weaviate Cloud.
Client library
At this time, this Agent is available only for Python. Support for other languages will be added in the future.
You can install the Weaviate client library with the optional agents extras to use Weaviate Agents. This will install the weaviate-agents package along with the weaviate-client package.
Install the client library using the following command:
- Python
pip install -U weaviate-client[agents]
Troubleshooting: Force pip to install the latest version
For existing installations, even pip install -U "weaviate-client[agents]" may not upgrade weaviate-agents to the latest version. If this occurs, additionally try to explicitly upgrade the weaviate-agents package:
pip install -U weaviate-agents
Or install a specific version:
pip install -U weaviate-agents==0.5.0
Usage
To use the Personalization Agent, follow the below high-level steps:
- Create or connect to a personalization agent
- Create or select a user persona
- Add interactions for the given persona
- Obtain personalized recommendations
Optionally, the personalization agent can:
- Perform reranking of the results
- With a further option of custom instructions for the reranking
Example usage is shown below.
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 Weaviate
You must connect to the Weaviate Cloud instance to use the Personalization Agent. Connect to the Weaviate Cloud instance using the Weaviate client library.
- Python
import os
import weaviate
from weaviate.classes.init import Auth
# 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("WEAVIATE_URL"),
auth_credentials=Auth.api_key(os.environ.get("WEAVIATE_API_KEY")),
headers=headers,
)
Create or connect to a personalization agent
Personalization Agents are stateful, with user persona data persisting in Weaviate. As a result, you can create a new Personalization Agent or connect to an existing one.
- Python
from weaviate.agents.personalization import PersonalizationAgent
from weaviate.classes.config import DataType
if PersonalizationAgent.exists(client, "Movies"):
pa = PersonalizationAgent.connect(client=client, reference_collection="Movies")
else:
pa = PersonalizationAgent.create(
client=client,
reference_collection="Movies",
user_properties={
"age": DataType.NUMBER,
"favorite_genres": DataType.TEXT_ARRAY,
"favorite_years": DataType.NUMBER_ARRAY,
"language": DataType.TEXT,
},
)
Create a user persona
The Personalization Agent is designed to provide personalized recommendations for a specific user.
You can do this through a Persona, which is a collection of user properties and interactions.
Each persona will include a user ID, a set of user properties, and a set of interactions.
To create a persona, specify a user ID and the set of user properties to be used for personalization.
- Python
from uuid import uuid4
persona_id = uuid4()
pa.add_persona(
Persona(
persona_id=persona_id,
properties={
"age": 30,
"favorite_genres": ["Action", "Adventure", "Sci-Fi", "Horror"],
"favorite_years": [1999, 1996, 2008, 2019],
"language": "English",
},
)
)
Add interactions
Interactions form the basis of the personalization process. They are the data points that the Personalization Agent uses to learn about the user and provide personalized recommendations.
To add interactions, select the user persona and provide the interaction details.
The available parameters are:
persona_id: ID of the user personaitem_id: ID of the item being interacted withweight: weight of the interaction (e.g. 1 for strongest like, -1 for strongest dislike)replace_previous_interaction: whether to replace the previous interaction with the same item IDcreated_at: timestamp of the interaction (affects how much weight the interaction has)
- Python
from weaviate.agents.classes import PersonaInteraction
interactions = [
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["Avatar 2"].uuid, weight=0.8
), # Strongly positive
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["Twister"].uuid, weight=0.5
), # Somewhat positive
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["The Howling"].uuid, weight=0.1
), # Almost neutral
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["Magic Mike"].uuid, weight=-0.3
), # Somewhat negative
PersonaInteraction(
persona_id=persona_id, item_id=movie_dict["The Emoji Movie"].uuid, weight=-1.0
), # Strongly negative
]
pa.add_interactions(interactions=interactions)
Perform a basic query
Once a user persona has been created, you can perform queries to obtain personalized recommendations.
As a minimum, simply provide the user ID to the Personalization Agent. The Personalization Agent will process the user ID, perform the necessary searches in Weaviate, and return the personalized recommendations.
- Python
response = pa.get_objects(persona_id)
for i, obj in enumerate(response.objects):
print(obj.properties)
Ranking options
The Personalization Agent uses a combination of vector search and LLM-based ranking to provide personalized recommendations. The vector search is based on our analysis of the set of interactions for the user persona. The LLM can optionally be used to rerank the results.
You can use it in one of three modes:
- Agent-based reranking: The Personalization Agent will first perform a vector search to retrieve a set of items, and then rerank them using an LLM, based on the user persona. This is the default mode.
- Agent-based reranking with custom instructions: If a custom instruction is provided, the Personalization Agent will use this instruction to rerank the results. This allows you to customize the ranking process based on your specific needs.
- Vector search only: If you retrieve results without using the agent ranking, the results will be based solely on the vector search.
Query options
There are a number of options available to customize the query.
limit: maximum number of items to returnrecent_interactions_count: number of recent interactions to consider for personalizationexclude_interacted_items: whether to exclude items that the user has already interacted withdecay_rate: decay rate for older interactions (1.0 = heavily discount older interactions; 0.0 = no discount)exclude_items: list of item IDs to exclude from the recommendationsuse_agent_ranking: whether to use the agent to rerank the resultsinstruction: custom instructions for the rerankingexplain_results: whether to include explanations for the results
- Python
response = pa.get_objects(
persona_id=persona_id,
limit=10,
recent_interactions_count=100,
exclude_interacted_items=False,
decay_rate=0.1,
exclude_items=[],
use_agent_ranking=True,
explain_results=True,
instruction=None,
)
for i, obj in enumerate(response.objects):
print(obj.properties)
Inspect results
The response from the Personalization Agent will include the personalized recommendations.
In addition to the response objects, the response may include the following information (depending on the options selected):
- Rationale for the recommendations
- For each object:
- Original rank of the item
- Personalized rank of the item
- Python
print(response.ranking_rationale)
for i, obj in enumerate(response.objects):
print(obj.properties)
print(f"original rank: {obj.original_rank}")
print(f"Personalized rank: {obj.personalized_rank}")
Limitations & Troubleshooting
Sign up here for notifications on Weaviate Agents, or visit this page to see the latest updates and provide feedback.
Usage limits
At this stage, there is a limit of 100 Personalization Agent queries per day per Weaviate Cloud organization where the agent-based reranking is used.
There are no limits on the number of queries per day for the vector search only (i.e. without the agent-based reranking).
This limit may change in future versions of the Personalization Agent.
Questions and feedback
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.
If you have any questions or feedback, let us know in the user forum.