perf: remove proactive module validation to reduce network calls (#370)

Remove MODULE LIST calls during connection initialization and index
creation. Operations now fail naturally when Redis modules are missing,
providing clear error messages at the point of failure.

Changes:
- Remove validate_modules() function and DEFAULT_REQUIRED_MODULES constant
- Remove required_modules parameter from all connection methods
- Remove proactive validation from SearchIndex and AsyncSearchIndex
- Remove validation from SemanticRouter.from_existing()
- Fix SemanticCache to use lazy client initialization
- Remove skip_if_module_version_error test helper
- Remove unused RedisModuleVersionError exception
- Add RediSearch module availability checks to skip tests when module not present
- Fix mocking strategy to patch instance methods instead of class methods
- Handle different Redis versions (6.2.6-v9, latest, 8.0.2) in CI environment
- Ensure tests work with both testcontainers (local) and provided Redis (CI)
- Ensures compatibility across different Redis Stack versions
- Support Redis 6.2.6-v9 returns 'dims' while other versions may return 'dim'.
- Handle multiple field name variations for vector attributes
- Support 'distance_metric' and 'metric' field names
- Support 'data_type', 'type', and 'datatype' field variations
- Safely handle missing or renamed fields across Redis versions

This ensures compatibility with Redis 6.2.6-v9 which may return
different field names compared to newer Redis Stack versions.

Author: bsbodden

redisvl/exceptions.py

@@ -11,12 +11,6 @@ class RedisVLError(Exception):
     pass
 
 
-class RedisModuleVersionError(RedisVLError):
-    """Error raised when required Redis modules are missing or have incompatible versions."""
-
-    pass
-
-
 class RedisSearchError(RedisVLError):
     """Error raised for Redis Search specific operations."""
 

redisvl/extensions/cache/llm/semantic.py

@@ -162,7 +162,7 @@ def __init__(
                 )
 
             existing_index = SearchIndex.from_existing(
-                name, redis_client=self._index.client
+                name, redis_client=self._index._redis_client
             )
             if existing_index.schema.to_dict() != self._index.schema.to_dict():
                 raise ValueError(

redisvl/extensions/router/semantic.py

@@ -7,7 +7,6 @@
 from redis.commands.search.aggregation import AggregateRequest, AggregateResult, Reducer
 from redis.exceptions import ResponseError
 
-from redisvl.exceptions import RedisModuleVersionError
 from redisvl.extensions.constants import ROUTE_VECTOR_FIELD_NAME
 from redisvl.extensions.router.schema import (
     DistanceAggregationMethod,
@@ -118,18 +117,14 @@ def from_existing(
         **kwargs,
     ) -> "SemanticRouter":
         """Return SemanticRouter instance from existing index."""
-        try:
-            if redis_url:
-                redis_client = RedisConnectionFactory.get_redis_connection(
-                    redis_url=redis_url,
-                    **kwargs,
-                )
-            elif redis_client:
-                RedisConnectionFactory.validate_sync_redis(redis_client)
-        except RedisModuleVersionError as e:
-            raise RedisModuleVersionError(
-                f"Loading from existing index failed. {str(e)}"
+        if redis_url:
+            redis_client = RedisConnectionFactory.get_redis_connection(
+                redis_url=redis_url,
+                **kwargs,
             )
+        elif redis_client:
+            # Just validate client type and set lib name
+            RedisConnectionFactory.validate_sync_redis(redis_client)
         if redis_client is None:
             raise ValueError(
                 "Creating Redis client failed. Please check the redis_url and connection_kwargs."

redisvl/index/index.py

@@ -67,7 +67,6 @@
 
 from redisvl.exceptions import (
     QueryValidationError,
-    RedisModuleVersionError,
     RedisSearchError,
     RedisVLError,
     SchemaValidationError,
@@ -439,23 +438,15 @@ def from_existing(
 
         Raises:
             ValueError: If redis_url or redis_client is not provided.
-            RedisModuleVersionError: If required Redis modules are not installed.
         """
-        try:
-            if redis_url:
-                redis_client = RedisConnectionFactory.get_redis_connection(
-                    redis_url=redis_url,
-                    required_modules=REQUIRED_MODULES_FOR_INTROSPECTION,
-                    **kwargs,
-                )
-            elif redis_client:
-                RedisConnectionFactory.validate_sync_redis(
-                    redis_client, required_modules=REQUIRED_MODULES_FOR_INTROSPECTION
-                )
-        except RedisModuleVersionError as e:
-            raise RedisModuleVersionError(
-                f"Loading from existing index failed. {str(e)}"
+        if redis_url:
+            redis_client = RedisConnectionFactory.get_redis_connection(
+                redis_url=redis_url,
+                **kwargs,
             )
+        elif redis_client:
+            # Validate client type and set lib name
+            RedisConnectionFactory.validate_sync_redis(redis_client)
 
         if not redis_client:
             raise ValueError("Must provide either a redis_url or redis_client")
@@ -481,11 +472,16 @@ def _redis_client(self) -> SyncRedisClient:
         if self.__redis_client is None:
             with self._lock:
                 if self.__redis_client is None:
+                    # Pass lib_name to connection factory
+                    kwargs = {**self._connection_kwargs}
+                    if self._lib_name:
+                        kwargs["lib_name"] = self._lib_name
                     self.__redis_client = RedisConnectionFactory.get_redis_connection(
                         redis_url=self._redis_url,
-                        **self._connection_kwargs,
+                        **kwargs,
                     )
-        if not self._validated_client:
+        if not self._validated_client and self._lib_name:
+            # Only set lib name for user-provided clients
             RedisConnectionFactory.validate_sync_redis(
                 self.__redis_client,
                 self._lib_name,
@@ -1193,21 +1189,14 @@ async def from_existing(
                 "Must provide either a redis_url or redis_client to fetch Redis index info."
             )
 
-        try:
-            if redis_url:
-                redis_client = await RedisConnectionFactory._get_aredis_connection(
-                    url=redis_url,
-                    required_modules=REQUIRED_MODULES_FOR_INTROSPECTION,
-                    **kwargs,
-                )
-            elif redis_client:
-                await RedisConnectionFactory.validate_async_redis(
-                    redis_client, required_modules=REQUIRED_MODULES_FOR_INTROSPECTION
-                )
-        except RedisModuleVersionError as e:
-            raise RedisModuleVersionError(
-                f"Loading from existing index failed. {str(e)}"
-            ) from e
+        if redis_url:
+            redis_client = await RedisConnectionFactory._get_aredis_connection(
+                url=redis_url,
+                **kwargs,
+            )
+        elif redis_client:
+            # Validate client type and set lib name
+            await RedisConnectionFactory.validate_async_redis(redis_client)
 
         if redis_client is None:
             raise ValueError(
@@ -1256,13 +1245,17 @@ async def _get_client(self) -> AsyncRedisClient:
             async with self._lock:
                 # Double-check to protect against concurrent access
                 if self._redis_client is None:
-                    kwargs = self._connection_kwargs
+                    # Pass lib_name to connection factory
+                    kwargs = {**self._connection_kwargs}
                     if self._redis_url:
                         kwargs["url"] = self._redis_url
+                    if self._lib_name:
+                        kwargs["lib_name"] = self._lib_name
                     self._redis_client = (
                         await RedisConnectionFactory._get_aredis_connection(**kwargs)
                     )
-        if not self._validated_client:
+        if not self._validated_client and self._lib_name:
+            # Set lib name for user-provided clients
             await RedisConnectionFactory.validate_async_redis(
                 self._redis_client,
                 self._lib_name,

redisvl/redis/connection.py

@@ -13,8 +13,7 @@
 from redis.exceptions import ResponseError
 
 from redisvl import __version__
-from redisvl.exceptions import RedisModuleVersionError
-from redisvl.redis.constants import DEFAULT_REQUIRED_MODULES, REDIS_URL_ENV_VAR
+from redisvl.redis.constants import REDIS_URL_ENV_VAR
 from redisvl.redis.utils import convert_bytes, is_cluster_url
 from redisvl.types import AsyncRedisClient, RedisClient, SyncRedisClient
 from redisvl.utils.utils import deprecated_function
@@ -93,10 +92,33 @@ def convert_index_info_to_schema(index_info: Dict[str, Any]) -> Dict[str, Any]:
 
     def parse_vector_attrs(attrs):
         vector_attrs = {attrs[i].lower(): attrs[i + 1] for i in range(6, len(attrs), 2)}
-        vector_attrs["dims"] = int(vector_attrs.pop("dim"))
-        vector_attrs["distance_metric"] = vector_attrs.pop("distance_metric").lower()
-        vector_attrs["algorithm"] = vector_attrs.pop("algorithm").lower()
-        vector_attrs["datatype"] = vector_attrs.pop("data_type").lower()
+
+        # Handle both "dim" and "dims" for compatibility across Redis versions
+        if "dim" in vector_attrs:
+            vector_attrs["dims"] = int(vector_attrs.pop("dim"))
+        elif "dims" in vector_attrs:
+            vector_attrs["dims"] = int(vector_attrs["dims"])
+
+        # Handle distance_metric with fallback for different field names
+        if "distance_metric" in vector_attrs:
+            vector_attrs["distance_metric"] = vector_attrs.pop(
+                "distance_metric"
+            ).lower()
+        elif "metric" in vector_attrs:
+            vector_attrs["distance_metric"] = vector_attrs.pop("metric").lower()
+
+        # Handle algorithm field
+        if "algorithm" in vector_attrs:
+            vector_attrs["algorithm"] = vector_attrs.pop("algorithm").lower()
+
+        # Handle data_type/datatype field variations
+        if "data_type" in vector_attrs:
+            vector_attrs["datatype"] = vector_attrs.pop("data_type").lower()
+        elif "type" in vector_attrs:
+            vector_attrs["datatype"] = vector_attrs.pop("type").lower()
+        elif "datatype" in vector_attrs:
+            vector_attrs["datatype"] = vector_attrs["datatype"].lower()
+
         return vector_attrs
 
     def parse_attrs(attrs):
@@ -155,40 +177,6 @@ def parse_attrs(attrs):
     }
 
 
-def validate_modules(
-    installed_modules: Dict[str, Any],
-    required_modules: Optional[List[Dict[str, Any]]] = None,
-) -> None:
-    """
-    Validates if required Redis modules are installed.
-
-    Args:
-        installed_modules: List of installed modules.
-        required_modules: List of required modules.
-
-    Raises:
-        RedisModuleVersionError: If required Redis modules are not installed.
-    """
-    required_modules = required_modules or DEFAULT_REQUIRED_MODULES
-
-    for required_module in required_modules:
-        if required_module["name"] in installed_modules:
-            installed_version = installed_modules[required_module["name"]]  # type: ignore
-            if int(installed_version) >= int(required_module["ver"]):  # type: ignore
-                return
-
-    # Build the error message dynamically
-    required_modules_str = " OR ".join(
-        [f'{module["name"]} >= {module["ver"]}' for module in required_modules]
-    )
-    error_message = (
-        f"Required Redis db module {required_modules_str} not installed. "
-        "See Redis Stack docs at https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/."
-    )
-
-    raise RedisModuleVersionError(error_message)
-
-
 class RedisConnectionFactory:
     """Builds connections to a Redis database, supporting both synchronous and
     asynchronous clients.
@@ -232,16 +220,13 @@ def connect(
     @staticmethod
     def get_redis_connection(
         redis_url: Optional[str] = None,
-        required_modules: Optional[List[Dict[str, Any]]] = None,
         **kwargs,
     ) -> SyncRedisClient:
         """Creates and returns a synchronous Redis client.
 
         Args:
             url (Optional[str]): The URL of the Redis server. If not provided,
                 the environment variable REDIS_URL is used.
-            required_modules (Optional[List[Dict[str, Any]]]): List of required
-                Redis modules with version requirements.
             **kwargs: Additional keyword arguments to be passed to the Redis
                 client constructor.
 
@@ -251,22 +236,26 @@ def get_redis_connection(
         Raises:
             ValueError: If url is not provided and REDIS_URL environment
                 variable is not set.
-            RedisModuleVersionError: If required Redis modules are not installed.
         """
         url = redis_url or get_address_from_env()
         if is_cluster_url(url, **kwargs):
             client = RedisCluster.from_url(url, **kwargs)
         else:
             client = Redis.from_url(url, **kwargs)
-        RedisConnectionFactory.validate_sync_redis(
-            client, required_modules=required_modules
-        )
+        # Module validation removed - operations will fail naturally if modules are missing
+        # Set client library name only
+        _lib_name = make_lib_name(kwargs.get("lib_name"))
+        try:
+            client.client_setinfo("LIB-NAME", _lib_name)
+        except ResponseError:
+            # Fall back to a simple log echo
+            if hasattr(client, "echo"):
+                client.echo(_lib_name)
         return client
 
     @staticmethod
     async def _get_aredis_connection(
         url: Optional[str] = None,
-        required_modules: Optional[List[Dict[str, Any]]] = None,
         **kwargs,
     ) -> AsyncRedisClient:
         """Creates and returns an asynchronous Redis client.
@@ -277,8 +266,6 @@ async def _get_aredis_connection(
         Args:
             url (Optional[str]): The URL of the Redis server. If not provided,
                 the environment variable REDIS_URL is used.
-            required_modules (Optional[List[Dict[str, Any]]]): List of required
-                Redis modules with version requirements.
             **kwargs: Additional keyword arguments to be passed to the async
                 Redis client constructor.
 
@@ -288,7 +275,6 @@ async def _get_aredis_connection(
         Raises:
             ValueError: If url is not provided and REDIS_URL environment
                 variable is not set.
-            RedisModuleVersionError: If required Redis modules are not installed.
         """
         url = url or get_address_from_env()
 
@@ -297,9 +283,15 @@ async def _get_aredis_connection(
         else:
             client = AsyncRedis.from_url(url, **kwargs)
 
-        await RedisConnectionFactory.validate_async_redis(
-            client, required_modules=required_modules
-        )
+        # Module validation removed - operations will fail naturally if modules are missing
+        # Set client library name only
+        _lib_name = make_lib_name(kwargs.get("lib_name"))
+        try:
+            await client.client_setinfo("LIB-NAME", _lib_name)
+        except ResponseError:
+            # Fall back to a simple log echo
+            if hasattr(client, "echo"):
+                await client.echo(_lib_name)
         return client
 
     @staticmethod
@@ -386,9 +378,12 @@ async def get_modules_async(client: AsyncRedisClient) -> Dict[str, Any]:
     def validate_sync_redis(
         redis_client: SyncRedisClient,
         lib_name: Optional[str] = None,
-        required_modules: Optional[List[Dict[str, Any]]] = None,
     ) -> None:
-        """Validates the sync Redis client."""
+        """Validates the sync Redis client.
+
+        Note: Module validation has been removed. This method now only validates
+        the client type and sets the library name.
+        """
         if not issubclass(type(redis_client), (Redis, RedisCluster)):
             raise TypeError(
                 "Invalid Redis client instance. Must be Redis or RedisCluster."
@@ -404,19 +399,18 @@ def validate_sync_redis(
             if hasattr(redis_client, "echo"):
                 redis_client.echo(_lib_name)
 
-        # Get list of modules
-        installed_modules = RedisConnectionFactory.get_modules(redis_client)
-
-        # Validate available modules
-        validate_modules(installed_modules, required_modules)
+        # Module validation removed - operations will fail naturally if modules are missing
 
     @staticmethod
     async def validate_async_redis(
         redis_client: AsyncRedisClient,
         lib_name: Optional[str] = None,
-        required_modules: Optional[List[Dict[str, Any]]] = None,
     ) -> None:
-        """Validates the async Redis client."""
+        """Validates the async Redis client.
+
+        Note: Module validation has been removed. This method now only validates
+        the client type and sets the library name.
+        """
         if not issubclass(type(redis_client), (AsyncRedis, AsyncRedisCluster)):
             raise TypeError(
                 "Invalid async Redis client instance. Must be async Redis or async RedisCluster."
@@ -427,12 +421,7 @@ async def validate_async_redis(
             await redis_client.client_setinfo("LIB-NAME", _lib_name)
         except ResponseError:
             # Fall back to a simple log echo
-            await redis_client.echo(_lib_name)
             if hasattr(redis_client, "echo"):
                 await redis_client.echo(_lib_name)
 
-        # Get list of modules
-        installed_modules = await RedisConnectionFactory.get_modules_async(redis_client)
-
-        # Validate available modules
-        validate_modules(installed_modules, required_modules)
+        # Module validation removed - operations will fail naturally if modules are missing