Weaviate Personalization Agent: Usage

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:

This page describes how to use the Weaviate Personalization Agent to obtain personalized recommendations from your data stored in Weaviate.

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.

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

Supported languages

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

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_ADMIN_API_KEY")),
    headers=headers,
)

  API docs

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, "Movie"):
    # Connect to an existing agent
    pa = PersonalizationAgent.connect(client=client, reference_collection="Movie")
else:
    # Instantiate a new agent, 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="Movie",
        user_properties={
            "age": DataType.NUMBER,
            "favorite_genres": DataType.TEXT_ARRAY,
            "favorite_years": DataType.NUMBER_ARRAY,
            "language": DataType.TEXT,
        },
    )

  API docs

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 weaviate.util import generate_uuid5
from uuid import uuid4  # If you want to generate a random UUID

persona_id = generate_uuid5("sebawita")  # To generate a deterministic UUID
# persona_id = uuid4()  # To generate a random UUID

pa.add_persona(
    Persona(
        persona_id=persona_id,
        properties={
            "age": 74,
            "favorite_genres": ["Action", "Horror", "Romance"],
            "favorite_years": [1979, 1981, 1984, 1985],
            "language": "Hungarian",
        },
    )
)

  API docs

Manage a user persona

You can delete or update an existing user persona, as well as to check if a user persona exists.

Delete a user persona

To delete a user persona, specify the user ID of the persona to be deleted.

Python

from weaviate.util import generate_uuid5

persona_id = generate_uuid5("sebawita")  # To generate a deterministic UUID

# Delete the persona
pa.delete_persona(persona_id)

  API docs

Update a user persona

To update a user persona, specify the user ID of the persona to be updated and the new set of user properties.

Python

from weaviate.util import generate_uuid5

persona_id = generate_uuid5("sebawita")  # To generate a deterministic UUID

# Update the persona
pa.update_persona(
    Persona(
        persona_id=persona_id,
        properties={
            "age": 35,
            "favorite_genres": ["Action", "Adventure", "Drama", "Sci-Fi"],
            "favorite_years": [1999, 2005, 2010, 2014, 2016],
            "language": "English",
        },
    ))

  API docs

Check if a user persona exists

To check if a user persona exists, specify the user ID of the persona to be checked.

Python

from weaviate.util import generate_uuid5

persona_id = generate_uuid5("sebawita")  # To generate a deterministic UUID

# Check if the persona exists
try:
    assert pa.has_persona(persona_id)
    print(f"Persona with ID {persona_id} exists.")
except AssertionError:
    print(f"Persona with ID {persona_id} does not exist.")

  API docs

Get a user persona

To get a user persona, specify the user ID of the persona to be retrieved.

Python

from weaviate.util import generate_uuid5

persona_id = generate_uuid5("sebawita")  # To generate a deterministic UUID

# Get the persona
persona = pa.get_persona(persona_id)
print(persona)

  API docs

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 persona
• item_id: ID of the item being interacted with
• weight: 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 ID
• created_at: timestamp of the interaction (affects how much weight the interaction has)

Python

from weaviate.agents.classes import PersonaInteraction
# Note: `movie_dict` is a dictionary of movie titles to their corresponding objects
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

Get personalized objects

Once a user persona has been created, you can get personalized objects.

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)

  API docs

Get objects: Available ranking strategies

When using get_objects, you can select a ranking strategy.

The Personalization Agent can use 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.

Get objects: Parameters

The available parameters for getting personalized objects are:

• limit: maximum number of items to return
• recent_interactions_count: number of recent interactions to consider for personalization
• exclude_interacted_items: whether to exclude items that the user has already interacted with
• decay_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 recommendations
• use_agent_ranking: whether to use the agent to rerank the results
• instruction: custom instructions for the reranking
• explain_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)

  API docs

Get objects: 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}")

  API docs

Personalized Weaviate queries

The Personalization Agent can also be used to perform personalized Weaviate queries.

In contrast to the get_objects method, a personalized query includes an additional Weaviate query.

Weaviate's near_text, bm25 and hybrid queries can be combined with the Personalization Agent to provide personalized results.

Python

personalized_query = pa.query(persona_id=persona_id, strength=0.95)

response = personalized_query.near_text(  # Or .bm25 / .hybrid
    query="A movie about a giant monster",
    limit=20,
    # Other normal `near_text` parameters can be added here
    # e.g. filter, auto_limit, distance, include_vector, include_metadata, etc.
)

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

  API docs

Use a personalized Weaviate query when you want to use the Personalization Agent to rerank the results of a Weaviate query.

The Personalization Agent will first perform the Weaviate query to retrieve a set of items, and then rerank them using an LLM, based on the user persona.

Personalized Weaviate query: Parameters

The available parameters for personalizing a Weaviate query can be specified upstream of the query method (near_text, bm25, hybrid).

• persona_id: ID of the user persona
• strength: strength of the personalization (0.0 = no personalization, 1.0 = complete personalization, disregard query results)
• overfetch_factor: number of objects to fetch before personalization
• recent_interactions_count: number of recent interactions to consider for personalization
• decay_rate: decay rate for older interactions (1.0 = heavily discount older interactions; 0.0 = no discount)

Python

personalized_query = pa.query(
    persona_id=persona_id,          # The ID of the persona to use for personalization
    strength=0.95,                  # The strength of the personalization (0.0 = none, 1.0 = full)
    overfetch_factor=2,             # The number of objects to fetch before personalization
    recent_interactions_count=50,   # The number of recent interactions to consider
    decay_rate=0.2                  # The decay rate for the interactions
)

response = personalized_query.hybrid(  # Or .near_text / .bm25
    query="A movie about a giant monster",
    limit=20,
    # Other normal `hybrid` parameters can be added here
)

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

  API docs

Limitations & Troubleshooting

Technical Preview

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.

Known issues

The combined Weaviate query and personalization agent query is not available for named vectors at this time. This is a known issue and will be addressed shortly.

Questions and feedback

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.

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

• Technical questions
• Documentation feedback