Implement interface for unified hybrid search in Redis 8.4.0+ (#447)

This PR adds an interface for using the new
[`FT.HYBRID`](https://redis.io/docs/latest/commands/ft.hybrid) search
operation introduced in Redis Open Source 8.4.0.

## Changes

### `redisvl.query.hybrid`
This new module defines query constructors for working with the new
hybrid search operation. Attempting to import this module without having
`redis-py>=7.1.0` will raise an `ImportError`. It defines a
`HybridQuery` object which can be used to define a hybrid search
operation in a format largely similar to what `AggregateHybridQuery`
provides.

Under the hood, `redis-py` expects three separate configuration objects
to run hybrid search - one for the text+vector searches, one for the
score combination, and one for post-processing of the results (e.g.
aggregations, loading, limiting, etc.). The `HybridQuery` class manages
the definition of all three.

```python
# old
from redisvl.query.aggregate import AggregateHybridQuery

query = AggregateHybridQuery(
    text="medical professional",
    text_field_name="description",
    vector=[0.1, 0.1, 0.5, ...],
    vector_field_name="user_embedding",
    alpha=0.7,  # LINEAR only
    return_fields=["user", "job"]
)

results = index.query(query)

# new
from redisvl.query.hybrid import HybridQuery

query = HybridQuery(
    text="medical professional",
    text_field_name="description",
    vector=[0.1, 0.1, 0.5, ...],
    vector_field_name="user_embedding",
    combination_method="LINEAR",
    linear_alpha=0.3,  # NOTE: The linear combination is defined inconsistently between the two approaches
    return_fields=["user", "job"]
)

results = index.hybrid_search(query)
results = await async_index.hybrid_search(query)
```

### SearchIndex method
For `redis-py>=7.1.0`, the `SearchIndex` and `AsyncSearchIndex` classes
define a `hybrid_search` method that takes a `HybridQuery` instance as
an argument. For `redis-py<7.1.0` the method raises a
`NotImplementedError`. The method returns a list of retrieved
dictionaries.

### Additional Changes
- Fixed a typo in a test for `AggregateHybridQuery`
- `redis-py 7.0.0` introduced a change to the type of `Query._fields`,
changing it from a tuple to a list - a test had to be updated to
differentiate the expectation based on the redis-py version.

Author: vishal-bala

.github/workflows/test.yml

@@ -96,8 +96,8 @@ jobs:
       matrix:
         # 3.11 tests are run in the service-tests job
         python-version: ["3.9", "3.10", "3.12", "3.13"] 
-        redis-py-version: ["5.x", "6.x"]
-        redis-version: ["6.2.6-v9", "latest", "8.0.2"]
+        redis-py-version: ["5.x", "6.x", "7.x"]
+        redis-version: ["6.2.6-v9", "latest", "8.4.0"]
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
@@ -130,13 +130,15 @@ jobs:
           # Install right redis version based on redis py
           if [[ "${{ matrix.redis-py-version }}" == "5.x" ]]; then
             uv pip install "redis>=5,<6"
-          else
+          elif [[ "${{ matrix.redis-py-version }}" == "6.x" ]]; then
             uv pip install "redis>=6,<7"
+          else
+            uv pip install "redis>=7,<8"
           fi
 
       - name: Set Redis image name
         run: |
-          if [[ "${{ matrix.redis-version }}" == "8.0.2" ]]; then
+          if [[ "${{ matrix.redis-version }}" == "8.4.0" ]]; then
             echo "REDIS_IMAGE=redis:${{ matrix.redis-version }}" >> $GITHUB_ENV
           else
             echo "REDIS_IMAGE=redis/redis-stack-server:${{ matrix.redis-version }}" >> $GITHUB_ENV

docs/api/query.rst

@@ -105,47 +105,72 @@ VectorRangeQuery
           use_search_history='AUTO'  # SVS-VAMANA only
       )
 
-HybridQuery
+AggregateHybridQuery
 ================
 
 
 .. currentmodule:: redisvl.query
 
 
-.. autoclass:: HybridQuery
+.. autoclass:: AggregateHybridQuery
    :members:
    :inherited-members:
    :show-inheritance:
    :exclude-members: add_filter,get_args,highlight,return_field,summarize
 
 .. note::
-   The ``stopwords`` parameter in :class:`HybridQuery` (and :class:`AggregateHybridQuery`) controls query-time stopword filtering (client-side).
+   The ``stopwords`` parameter in :class:`AggregateHybridQuery` (and :class:`HybridQuery`) controls query-time stopword filtering (client-side).
    For index-level stopwords configuration (server-side), see :class:`redisvl.schema.IndexInfo.stopwords`.
    Using query-time stopwords with index-level ``STOPWORDS 0`` is counterproductive.
 
+.. note::
+   :class:`HybridQuery` and :class:`AggregateHybridQuery` apply linear combination inconsistently. :class:`HybridQuery` uses ``linear_alpha`` to weight the text score, while :class:`AggregateHybridQuery` uses ``alpha`` to weight the vector score. When switching between the two classes, take care to revise your ``alpha`` setting.
+
 .. note::
    **Runtime Parameters for Hybrid Queries**
 
    **Important:** AggregateHybridQuery uses FT.AGGREGATE commands which do NOT support runtime parameters.
    Runtime parameters (``ef_runtime``, ``search_window_size``, ``use_search_history``, ``search_buffer_capacity``)
    are only supported with FT.SEARCH commands.
 
-   For runtime parameter support, use :class:`VectorQuery` or :class:`VectorRangeQuery` instead of AggregateHybridQuery.
+   For runtime parameter support, use :class:`HybridQuery`, :class:`VectorQuery`, or :class:`VectorRangeQuery` instead of AggregateHybridQuery.
 
-   Example with VectorQuery (supports runtime parameters):
+   Example with HybridQuery (supports runtime parameters):
 
    .. code-block:: python
 
-      from redisvl.query import VectorQuery
+      from redisvl.query import HybridQuery
 
-      query = VectorQuery(
+      query = HybridQuery(
+          text="query string",
+          text_field_name="description",
           vector=[0.1, 0.2, 0.3],
           vector_field_name="embedding",
+          vector_search_method="KNN",
+          knn_ef_runtime=150,  # Runtime parameters work with HybridQuery
           return_fields=["description"],
           num_results=10,
-          ef_runtime=150  # Runtime parameters work with VectorQuery
       )
 
+HybridQuery
+================
+
+
+.. currentmodule:: redisvl.query.hybrid
+
+
+.. autoclass:: HybridQuery
+   :members:
+   :inherited-members:
+   :show-inheritance:
+
+.. note::
+   The ``stopwords`` parameter in :class:`HybridQuery` (and :class:`AggregateHybridQuery`) controls query-time stopword filtering (client-side).
+   For index-level stopwords configuration (server-side), see :class:`redisvl.schema.IndexInfo.stopwords`.
+   Using query-time stopwords with index-level ``STOPWORDS 0`` is counterproductive.
+
+.. note::
+   :class:`HybridQuery` and :class:`AggregateHybridQuery` apply linear combination inconsistently. :class:`HybridQuery` uses ``linear_alpha`` to weight the text score, while :class:`AggregateHybridQuery` uses ``alpha`` to weight the vector score. When switching between the two classes, take care to revise your ``alpha`` setting.
 
 TextQuery
 ================

docs/overview/installation.md

@@ -11,7 +11,7 @@ There are a few ways to install RedisVL. The easiest way is to use pip.
 
 ## Install RedisVL with Pip
 
-Install `redisvl` into your Python (>=3.8) environment using `pip`:
+Install `redisvl` into your Python (>=3.9) environment using `pip`:
 
 ```bash
 $ pip install -U redisvl