Implement interface for unified hybrid search in Redis 8.4.0+

.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,73 @@ 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 and ``linear_beta`` to weight the vector score. :class:`AggregateHybridQuery` uses ``alpha`` to weight the vector score and ``beta`` to weight the text score.
+
 .. 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.hybrid 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_k=10,
+          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 and ``linear_beta`` to weight the vector score. :class:`AggregateHybridQuery` uses ``alpha`` to weight the vector score and ``beta`` to weight the text score.
 
 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