Docs/fix distance threshold documentation issue 407 (#451)

Fix distance threshold documentation inconsistencies (Part of issue
[#407](#407))
Summary
Corrects documentation to accurately reflect that Redis COSINE distance
thresholds use the range [0-2], not [0-1]. The code validation was
already correct, but docstrings and examples were misleading.

Changes

- SemanticCache: Fixed `__init__` and `set_threshold` docstrings to
specify [0-2] range
- Message History: Corrected notebook stating max threshold is 2.0, not
1.0
- Examples: Added inline comments clarifying Redis COSINE distance scale
in README and notebooks

Author: nkanu17

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/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."
    ]
   },
   {

redisvl/extensions/cache/llm/semantic.py

@@ -61,8 +61,9 @@ def __init__(
         Args:
             name (str, optional): The name of the semantic cache search index.
                 Defaults to "llmcache".
-            distance_threshold (float, optional): Semantic threshold for the
-                cache. Defaults to 0.1.
+            distance_threshold (float, optional): Semantic distance threshold for the
+                cache in Redis COSINE units [0-2], where lower values indicate stricter
+                matching. Defaults to 0.1.
             ttl (Optional[int], optional): The time-to-live for records cached
                 in Redis. Defaults to None.
             vectorizer (Optional[BaseVectorizer], optional): The vectorizer for the cache.
@@ -80,7 +81,7 @@ def __init__(
         Raises:
             TypeError: If an invalid vectorizer is provided.
             TypeError: If the TTL value is not an int.
-            ValueError: If the threshold is not between 0 and 1.
+            ValueError: If the threshold is not between 0 and 2 (Redis COSINE distance).
             ValueError: If existing schema does not match new schema and overwrite is False.
         """
         # Call parent class with all shared parameters
@@ -243,7 +244,7 @@ def set_threshold(self, distance_threshold: float) -> None:
                 the cache.
 
         Raises:
-            ValueError: If the threshold is not between 0 and 1.
+            ValueError: If the threshold is not between 0 and 2 (Redis COSINE distance).
         """
         if not 0 <= float(distance_threshold) <= 2:
             raise ValueError(