deprecate old retrieval classes

Author: maxjakob

libs/elasticsearch/langchain_elasticsearch/__init__.py

@@ -1,21 +1,40 @@
+from elasticsearch.helpers.vectorstore import (
+    BM25Strategy,
+    DenseVectorScriptScoreStrategy,
+    DenseVectorStrategy,
+    DistanceMetric,
+    RetrievalStrategy,
+    SparseVectorStrategy,
+)
+
 from langchain_elasticsearch.cache import ElasticsearchCache
 from langchain_elasticsearch.chat_history import ElasticsearchChatMessageHistory
 from langchain_elasticsearch.embeddings import ElasticsearchEmbeddings
 from langchain_elasticsearch.retrievers import ElasticsearchRetriever
 from langchain_elasticsearch.vectorstores import (
     ApproxRetrievalStrategy,
+    BM25RetrievalStrategy,
     ElasticsearchStore,
     ExactRetrievalStrategy,
     SparseRetrievalStrategy,
 )
 
 __all__ = [
-    "ApproxRetrievalStrategy",
     "ElasticsearchCache",
     "ElasticsearchChatMessageHistory",
     "ElasticsearchEmbeddings",
     "ElasticsearchRetriever",
     "ElasticsearchStore",
+    # retrieval strategies
+    "BM25Strategy",
+    "DenseVectorScriptScoreStrategy",
+    "DenseVectorStrategy",
+    "DistanceMetric",
+    "RetrievalStrategy",
+    "SparseVectorStrategy",
+    # deprecated retrieval strategies
+    "ApproxRetrievalStrategy",
+    "BM25RetrievalStrategy",
     "ExactRetrievalStrategy",
     "SparseRetrievalStrategy",
 ]

libs/elasticsearch/langchain_elasticsearch/vectorstores.py

@@ -24,6 +24,7 @@
 from elasticsearch.helpers.vectorstore import (
     VectorStore as EVectorStore,
 )
+from langchain_core._api.deprecation import deprecated
 from langchain_core.documents import Document
 from langchain_core.embeddings import Embeddings
 from langchain_core.vectorstores import VectorStore
@@ -39,6 +40,7 @@
 logger = logging.getLogger(__name__)
 
 
+@deprecated("0.1.4", alternative="RetrievalStrategy", pending=True)
 class BaseRetrievalStrategy(ABC):
     """Base class for `Elasticsearch` retrieval strategies."""
 
@@ -124,6 +126,7 @@ def require_inference(self) -> bool:
         return True
 
 
+@deprecated("0.1.4", alternative="DenseVectorStrategy", pending=True)
 class ApproxRetrievalStrategy(BaseRetrievalStrategy):
     """Approximate retrieval strategy using the `HNSW` algorithm."""
 
@@ -251,6 +254,7 @@ def index(
         }
 
 
+@deprecated("0.1.4", alternative="DenseVectorScriptScoreStrategy", pending=True)
 class ExactRetrievalStrategy(BaseRetrievalStrategy):
     """Exact retrieval strategy using the `script_score` query."""
 
@@ -319,6 +323,7 @@ def index(
         }
 
 
+@deprecated("0.1.4", alternative="SparseVectorStrategy", pending=True)
 class SparseRetrievalStrategy(BaseRetrievalStrategy):
     """Sparse retrieval strategy using the `text_expansion` processor."""
 
@@ -403,6 +408,7 @@ def require_inference(self) -> bool:
         return False
 
 
+@deprecated("0.1.4", alternative="BM25Strategy", pending=True)
 class BM25RetrievalStrategy(BaseRetrievalStrategy):
     """Retrieval strategy using the native BM25 algorithm of Elasticsearch."""
 
@@ -474,9 +480,14 @@ def require_inference(self) -> bool:
 
 
 def _convert_retrieval_strategy(
-    langchain_strategy: BaseRetrievalStrategy, distance: DistanceStrategy
+    langchain_strategy: BaseRetrievalStrategy,
+    distance: Optional[DistanceStrategy] = None,
 ) -> RetrievalStrategy:
     if isinstance(langchain_strategy, ApproxRetrievalStrategy):
+        if distance is None:
+            raise ValueError(
+                "ApproxRetrievalStrategy requires a distance strategy to be provided."
+            )
         return DenseVectorStrategy(
             distance=DistanceMetric[distance],
             model_id=langchain_strategy.query_model_id,
@@ -488,6 +499,10 @@ def _convert_retrieval_strategy(
             rrf=False if langchain_strategy.rrf is None else langchain_strategy.rrf,
         )
     elif isinstance(langchain_strategy, ExactRetrievalStrategy):
+        if distance is None:
+            raise ValueError(
+                "ExactRetrievalStrategy requires a distance strategy to be provided."
+            )
         return DenseVectorScriptScoreStrategy(distance=DistanceMetric[distance])
     elif isinstance(langchain_strategy, SparseRetrievalStrategy):
         return SparseVectorStrategy(langchain_strategy.model_id)

libs/elasticsearch/tests/unit_tests/test_imports.py

@@ -1,12 +1,21 @@
 from langchain_elasticsearch import __all__
 
 EXPECTED_ALL = [
-    "ApproxRetrievalStrategy",
     "ElasticsearchCache",
     "ElasticsearchChatMessageHistory",
     "ElasticsearchEmbeddings",
     "ElasticsearchRetriever",
     "ElasticsearchStore",
+    # retrieval strategies
+    "BM25Strategy",
+    "DenseVectorScriptScoreStrategy",
+    "DenseVectorStrategy",
+    "DistanceMetric",
+    "RetrievalStrategy",
+    "SparseVectorStrategy",
+    # deprecated retrieval strategies
+    "ApproxRetrievalStrategy",
+    "BM25RetrievalStrategy",
     "ExactRetrievalStrategy",
     "SparseRetrievalStrategy",
 ]

libs/elasticsearch/tests/unit_tests/test_vectorstores.py

@@ -11,7 +11,17 @@
 from langchain_elasticsearch.embeddings import Embeddings, EmbeddingServiceAdapter
 from langchain_elasticsearch.vectorstores import (
     ApproxRetrievalStrategy,
+    BM25RetrievalStrategy,
+    BM25Strategy,
+    DenseVectorScriptScoreStrategy,
+    DenseVectorStrategy,
+    DistanceMetric,
+    DistanceStrategy,
     ElasticsearchStore,
+    ExactRetrievalStrategy,
+    SparseRetrievalStrategy,
+    SparseVectorStrategy,
+    _convert_retrieval_strategy,
     _hits_to_docs_scores,
 )
 
@@ -143,6 +153,39 @@ def test_doc_field_to_metadata(self) -> None:
         assert actual == expected
 
 
+class TestConvertStrategy:
+    def test_dense_approx(self) -> None:
+        actual = _convert_retrieval_strategy(
+            ApproxRetrievalStrategy(query_model_id="my model", hybrid=True, rrf=False),
+            distance=DistanceStrategy.DOT_PRODUCT,
+        )
+        assert isinstance(actual, DenseVectorStrategy)
+        assert actual.distance == DistanceMetric.DOT_PRODUCT
+        assert actual.model_id == "my model"
+        assert actual.hybrid is True
+        assert actual.rrf is False
+
+    def test_dense_exact(self) -> None:
+        actual = _convert_retrieval_strategy(
+            ExactRetrievalStrategy(), distance=DistanceStrategy.EUCLIDEAN_DISTANCE
+        )
+        assert isinstance(actual, DenseVectorScriptScoreStrategy)
+        assert actual.distance == DistanceMetric.EUCLIDEAN_DISTANCE
+
+    def test_sparse(self) -> None:
+        actual = _convert_retrieval_strategy(
+            SparseRetrievalStrategy(model_id="my model ID")
+        )
+        assert isinstance(actual, SparseVectorStrategy)
+        assert actual.model_id == "my model ID"
+
+    def test_bm25(self) -> None:
+        actual = _convert_retrieval_strategy(BM25RetrievalStrategy(k1=1.7, b=5.4))
+        assert isinstance(actual, BM25Strategy)
+        assert actual.k1 == 1.7
+        assert actual.b == 5.4
+
+
 class TestVectorStore:
     @pytest.fixture
     def embeddings(self) -> Embeddings: