Weaviate Personalization Agent

Technical Preview

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.

Nomenclature: User vs Developer

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:

Changelog 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.

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.

Basic Usage

Here is an overview of how to use the this Weaviate Agent. For more detailed information, refer to the Usage page.

Prerequisites

This Agent is available exclusively for use with a Weaviate Cloud instance, and a supported version of the Weaviate client library.

Example Usage

To use the Personalization Agent, instantiate it with the following inputs:

• An instance of the Weaviate client (e.g. the WeaviateClient object in Python), connected to a Weaviate Cloud instance.
• Name of the target collection to get personalized items from.
• A list of user properties to base the personalization on.

Python

from weaviate.agents.personalization import PersonalizationAgent
from weaviate.classes.config import DataType
# Instantiate a new agent object, and specify the collection to query
# The Personalization Agent will automatically also connect to the user data collection

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

  API docs

Then, add a persona, which will be used to personalize the recommendations.

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",
        },
    )
)

  API docs

Then you can add a set of interactions to that persona.

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)

  API docs

Once user data is added, the Personalization Agent can be used to get personalized recommendations from the Weaviate collection.

Python

response = pa.get_objects(persona_id)

for i, obj in enumerate(response.objects):
    print(obj.properties)

  API docs

Further Documentation

For more detailed information on how to use this Agent, refer to the Usage page.

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

• Technical questions
• Documentation feedback