feat(cache): improve warning messages for async-only client usage

- Add concise warning messages when sync methods are called with async-only client
- Implement warning flag to prevent log spam (show warning only once per session)
- Add comprehensive test coverage for warning behavior
- Improve developer experience by providing clear guidance on method usage

The warnings now clearly indicate which async methods should be used instead
of sync methods when EmbeddingsCache is initialized with only an async client.
This helps prevent confusion when developers unintentionally use different
Redis connections than expected.

Author: bsbodden

redisvl/extensions/cache/embeddings/embeddings.py

@@ -14,6 +14,8 @@
 class EmbeddingsCache(BaseCache):
     """Embeddings Cache for storing embedding vectors with exact key matching."""
 
+    _warning_shown: bool = False  # Class-level flag to prevent warning spam
+
     def __init__(
         self,
         name: str = "embedcache",
@@ -168,11 +170,12 @@ def get_by_key(self, key: str) -> Optional[Dict[str, Any]]:
             embedding_data = cache.get_by_key("embedcache:1234567890abcdef")
         """
         if self._owns_redis_client is False and self._redis_client is None:
-            logger.warning(
-                "You are using redis_client but you had initialised the EmbeddingCache with an async_redis_client only. "
-                "If you intended to use async_redis_client, please use async aget(text, model_name) method of EmbeddingCache instead "
-                "of get(text, model_name)."
-            )
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (aget_by_key) instead of sync methods (get_by_key)."
+                )
+                EmbeddingsCache._warning_shown = True
 
         client = self._get_redis_client()
 
@@ -210,11 +213,12 @@ def mget_by_keys(self, keys: List[str]) -> List[Optional[Dict[str, Any]]]:
             return []
 
         if self._owns_redis_client is False and self._redis_client is None:
-            logger.warning(
-                "You are using redis_client but you had initialised the EmbeddingCache with an async_redis_client only. "
-                "If you intended to use async_redis_client, please use async amget(texts, model_name) method of EmbeddingCache instead "
-                "of mget(texts, model_name)."
-            )
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (amget_by_keys) instead of sync methods (mget_by_keys)."
+                )
+                EmbeddingsCache._warning_shown = True
 
         client = self._get_redis_client()
 
@@ -298,11 +302,12 @@ def set(
         )
 
         if self._owns_redis_client is False and self._redis_client is None:
-            logger.warning(
-                "You are using redis_client but you had initialised the EmbeddingCache with an async_redis_client only. "
-                "If you intended to use async_redis_client, please use async aset(text, model_name, embedding, metadata=None, ttl=None) "
-                "method of EmbeddingCache instead of set(text, model_name, embedding, metadata=None, ttl=None)."
-            )
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (aset) instead of sync methods (set)."
+                )
+                EmbeddingsCache._warning_shown = True
 
         # Store in Redis
         client = self._get_redis_client()
@@ -355,11 +360,12 @@ def mset(
             return []
 
         if self._owns_redis_client is False and self._redis_client is None:
-            logger.warning(
-                "You are using redis_client but you had initialised the EmbeddingCache with an async_redis_client only. "
-                "If you intended to use async_redis_client, please use async amset(items, ttl=None) method of EmbeddingCache instead "
-                "of mset(items, ttl=None)."
-            )
+            if not EmbeddingsCache._warning_shown:
+                logger.warning(
+                    "EmbeddingsCache initialized with async_redis_client only. "
+                    "Use async methods (amset) instead of sync methods (mset)."
+                )
+                EmbeddingsCache._warning_shown = True
 
         client = self._get_redis_client()
         keys = []

tests/integration/test_embedcache_warnings.py

@@ -0,0 +1,91 @@
+"""Test warning behavior when using sync methods with async-only client."""
+
+import asyncio
+import logging
+from unittest.mock import patch
+
+import pytest
+from redis import Redis
+
+from redisvl.extensions.cache.embeddings import EmbeddingsCache
+from redisvl.redis.connection import RedisConnectionFactory
+
+
+def test_sync_methods_warn_with_async_only_client(caplog):
+    """Test that sync methods warn when only async client is provided."""
+    # Reset the warning flag for testing
+    EmbeddingsCache._warning_shown = False
+
+    # Create async redis client
+    async_client = RedisConnectionFactory.get_async_redis_connection(
+        "redis://localhost:6379"
+    )
+
+    # Initialize EmbeddingsCache with only async_redis_client
+    cache = EmbeddingsCache(name="test_cache", async_redis_client=async_client)
+
+    # Capture log warnings
+    with caplog.at_level(logging.WARNING):
+        # First sync method call should warn
+        _ = cache.get_by_key("test_key")
+
+        # Check warning was logged
+        assert len(caplog.records) == 1
+        assert "initialized with async_redis_client only" in caplog.records[0].message
+        assert "Use async methods" in caplog.records[0].message
+
+        # Clear captured logs
+        caplog.clear()
+
+        # Second sync method call should NOT warn (flag prevents spam)
+        _ = cache.set(text="test", model_name="model", embedding=[0.1, 0.2])
+
+        # Should not have logged another warning
+        assert len(caplog.records) == 0
+
+
+def test_no_warning_with_sync_client():
+    """Test that no warning is shown when sync client is provided."""
+    # Reset the warning flag for testing
+    EmbeddingsCache._warning_shown = False
+
+    # Create sync redis client
+    sync_client = Redis.from_url("redis://localhost:6379")
+
+    # Initialize EmbeddingsCache with sync_redis_client
+    cache = EmbeddingsCache(name="test_cache", redis_client=sync_client)
+
+    with patch("redisvl.utils.log.get_logger") as mock_logger:
+        # Sync methods should not warn
+        _ = cache.get_by_key("test_key")
+        _ = cache.set(text="test", model_name="model", embedding=[0.1, 0.2])
+
+        # No warnings should have been logged
+        mock_logger.return_value.warning.assert_not_called()
+
+    sync_client.close()
+
+
+@pytest.mark.asyncio
+async def test_async_methods_no_warning():
+    """Test that async methods don't trigger warnings."""
+    # Reset the warning flag for testing
+    EmbeddingsCache._warning_shown = False
+
+    # Create async redis client
+    async_client = RedisConnectionFactory.get_async_redis_connection(
+        "redis://localhost:6379"
+    )
+
+    # Initialize EmbeddingsCache with only async_redis_client
+    cache = EmbeddingsCache(name="test_cache", async_redis_client=async_client)
+
+    with patch("redisvl.utils.log.get_logger") as mock_logger:
+        # Async methods should not warn
+        _ = await cache.aget_by_key("test_key")
+        _ = await cache.aset(text="test", model_name="model", embedding=[0.1, 0.2])
+
+        # No warnings should have been logged
+        mock_logger.return_value.warning.assert_not_called()
+
+    await async_client.aclose()