Merge remote-tracking branch 'refs/remotes/origin/main' into feat/RAAE-1240/multimodal-embeddings

# Conflicts:
#	docs/api/query.rst
#	docs/user_guide/11_advanced_queries.ipynb
#	redisvl/index/index.py
#	redisvl/query/hybrid.py
#	tests/integration/test_hybrid.py
#	tests/unit/test_hybrid_types.py
#	uv.lock

Author: vishal-bala

README.md

@@ -276,7 +276,7 @@ llmcache = SemanticCache(
     name="llmcache",
     ttl=360,
     redis_url="redis://localhost:6379",
-    distance_threshold=0.1
+    distance_threshold=0.1  # Redis COSINE distance [0-2], lower is stricter
 )
 
 # store user queries and LLM responses in the semantic cache

docs/api/query.rst

@@ -124,7 +124,7 @@ AggregateHybridQuery
    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.
+   :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**
@@ -139,15 +139,14 @@ AggregateHybridQuery
 
    .. code-block:: python
 
-      from redisvl.query.hybrid import HybridQuery
+      from redisvl.query import HybridQuery
 
       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,
@@ -171,7 +170,7 @@ HybridQuery
    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.
+   :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/user_guide/03_llmcache.ipynb

@@ -103,7 +103,7 @@
     "llmcache = SemanticCache(\n",
     "    name=\"llmcache\",                                          # underlying search index name\n",
     "    redis_url=\"redis://localhost:6379\",                       # redis connection url string\n",
-    "    distance_threshold=0.1,                                   # semantic cache distance threshold\n",
+    "    distance_threshold=0.1,                                   # semantic cache distance threshold (Redis COSINE [0-2], lower is stricter)\n",
     "    vectorizer=HFTextVectorizer(\"redis/langcache-embed-v1\"),  # embedding model\n",
     ")"
    ]
@@ -312,7 +312,9 @@
     "## Customize the Distance Threshold\n",
     "\n",
     "For most use cases, the right semantic similarity threshold is not a fixed quantity. Depending on the choice of embedding model,\n",
-    "the properties of the input query, and even business use case -- the threshold might need to change. \n",
+    "the properties of the input query, and even business use case -- the threshold might need to change.\n",
+    "\n",
+    "The distance threshold uses Redis COSINE distance units [0-2], where 0 means identical and 2 means completely different.\n",
     "\n",
     "Fortunately, you can seamlessly adjust the threshold at any point like below:"
    ]
@@ -323,7 +325,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Widen the semantic distance threshold\n",
+    "# Widen the semantic distance threshold (allow less similar matches)\n",
     "llmcache.set_threshold(0.5)"
    ]
   },
@@ -930,4 +932,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

docs/user_guide/07_message_history.ipynb

@@ -276,7 +276,7 @@
    "source": [
     "You can adjust the degree of semantic similarity needed to be included in your context.\n",
     "\n",
-    "Setting a distance threshold close to 0.0 will require an exact semantic match, while a distance threshold of 1.0 will include everything."
+    "Setting a distance threshold close to 0.0 will require an exact semantic match, while a distance threshold of 2.0 will include everything (Redis COSINE distance range is [0-2])."
    ]
   },
   {

docs/user_guide/08_semantic_router.ipynb

@@ -27,7 +27,7 @@
     "route. The incoming query from a user needs to be semantically similar to one or\n",
     "more of the references in order to \"match\" on the route.\n",
     "\n",
-    "Additionally, each route has a `distance_threshold` which determines the maximum distance between the query and the reference for the query to be routed to the route. This value is unique to each route."
+    "Additionally, each route has a `distance_threshold` which determines the maximum distance between the query and the reference for the query to be routed to the route. This value is unique to each route and uses Redis COSINE distance units (0-2], where lower values require stricter matching."
    ]
   },
   {