Python: Fix RedisContextProvider for redisvl 0.14.0 HybridQuery API change

[Copilot]

Motivation and Context

redisvl 0.14.0 renamed the HybridQuery constructor parameter alpha to linear_alpha, breaking Redis hybrid search with:

TypeError: HybridQuery.__init__() got an unexpected keyword argument 'alpha'

Description

Core Fix

• Updated RedisContextProvider._redis_search() to pass linear_alpha instead of alpha to HybridQuery

Testing

• Added regression test verifying the correct parameter name is used when vectorizer is configured

The change is isolated to one parameter name in the HybridQuery instantiation:

query = HybridQuery(
    text=q,
    text_field_name="content",
    vector=vector,
    vector_field_name=self.vector_field_name,
    text_scorer=text_scorer,
    filter_expression=combined_filter,
    linear_alpha=alpha,  # Changed from: alpha=alpha
    dtype=self.redis_vectorizer.dtype,
    num_results=num_results,
    return_fields=return_fields,
    stopwords=None,
)

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• astral.sh
  • Triggering command: /usr/bin/curl curl -LsSf REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Python: RedisProvider._redis_search() incompatible with redisvl 0.14.0: 'alpha' renamed to 'linear_alpha' in HybridQuery</issue_title>
<issue_description>## Bug Report

Description

RedisProvider._redis_search() passes alpha to redisvl.query.HybridQuery, but redisvl v0.14.0 renamed this parameter to linear_alpha.

Error

TypeError: HybridQuery.__init__() got an unexpected keyword argument 'alpha'

Wrapped as:

agent_framework.exceptions.ServiceInvalidRequestError: Redis text search failed: HybridQuery.__init__() got an unexpected keyword argument 'alpha'

Location

agent_framework_redis/_provider.py, in _redis_search():

query = HybridQuery(
    text=q,
    text_field_name="content",
    vector=vector,
    vector_field_name=self.vector_field_name,
    text_scorer=text_scorer,
    filter_expression=combined_filter,
    alpha=alpha,  # <-- this parameter no longer exists in redisvl 0.14.0
    dtype=self.redis_vectorizer.dtype,
    num_results=num_results,
    return_fields=return_fields,
    stopwords=None,
)

Expected Fix

Replace alpha=alpha with linear_alpha=alpha to match the redisvl 0.14.0 API:

query = HybridQuery(
    ...
    linear_alpha=alpha,
    ...
)

The redisvl 0.14.0 HybridQuery signature expects linear_alpha: float = 0.3 instead of alpha.

Steps to Reproduce

1. Install agent-framework-redis (at commit 98cd72839e) which pulls redisvl>=0.14.0
2. Create a RedisProvider with a vectorizer configured (e.g., AzureOpenAITextVectorizer)
3. Run an agent with the provider — the first invoking() call triggers _redis_search() which fails

Environment

• agent-framework-redis at commit 98cd72839e
• redisvl==0.14.0
• Python 3.12</issue_description>

<agent_instructions>Fix the bug described in this issue. Run the pre-commit hooks and fix any errors. Add a unit test to prevent regression.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes Python: RedisProvider._redis_search() incompatible with redisvl 0.14.0: 'alpha' renamed to 'linear_alpha' in HybridQuery #3870

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR fixes a compatibility issue with redisvl 0.14.0, which renamed the HybridQuery constructor parameter from alpha to linear_alpha. The change prevents a TypeError when Redis hybrid search is used with a vectorizer configured.

Changes:

• Updated RedisContextProvider._redis_search() to pass linear_alpha instead of alpha to HybridQuery
• Added regression test to verify the correct parameter name is used

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
python/packages/redis/agent_framework_redis/_context_provider.py	Changed parameter name from alpha to linear_alpha in HybridQuery instantiation (line 376)
python/packages/redis/tests/test_providers.py	Added test class TestRedisContextProviderHybridQuery with test verifying linear_alpha parameter usage

[vishal-bala]

Hey there! I'm with the team at Redis that maintains RedisVL - since redisvl==0.13.0 there have been a couple of options for hybrid search, which is where the bug here originally stemmed from.

The integration imports and uses the HybridQuery class, which now points to Redis's native hybrid search functionality (available only with Redis 8.4.0+). To preserve the existing functionality as it previously was in this integration, the simpler fix would be to replace

from redisvl.query import HybridQuery

with

from redisvl.query import AggregateHybridQuery

and associated usages. The syntax that this integration currently expects is the syntax for AggregateHybridQuery and not the latest HybridQuery. Alternatively, setting a version constraint for redisvl<=0.13.0 would also work.

Switching the linear_alpha parameter name is also a gotcha because with the new Redis FT.HYBRID syntax (which HybridQuery wraps), alpha refers to the weight of the text query while in the original syntax it refers to the weight of the vector query (super confusing, I know).

Thanks for taking on the fix for this integration! Let me know if that context is helpful or if I can clarify anything.

[vishal-bala]

This is a misleading fix - see my comment on the main PR. As of redisvl>=0.13.0, the HybridQuery class wraps the native Redis FT.HYBRID search command. For this command, alpha refers to the weight of the text query in the score combination.

Prior to redisvl==0.13.0, the implementation used the FT.AGGREGATE operation, and RedisVL defined alpha as the weight of the vector query in the score combination. This legacy approach is still accessible via from redisvl.query import AggregateHybridQuery, which is what the syntax in this project is expecting.

Without care, simply switching alpha to linear_alpha would actually invert the weighting of the score components for existing implementations.