feat : adding a new Protocol for TextEmbedder (#9353)

* initial import

* removing unused imports

* adding an Embbeder Protocol

* adding tests

* adding tests

* adding release notes

* renaming dir

* removing dir

* cleaning

* adding clean tests

* dealing eith elipsis and pylint

* wip: extending tests

* cleaning extended tests

* adding an invalid TextEmbedder

Author: davidsbatista

haystack/components/embedders/types/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <[email protected]>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .protocol import TextEmbedder
+
+__all__ = ["TextEmbedder"]

haystack/components/embedders/types/protocol.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <[email protected]>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Any, Dict, Protocol, TypeVar
+
+T = TypeVar("T", bound="TextEmbedder")
+
+# See https://github.com/pylint-dev/pylint/issues/9319.
+# pylint: disable=unnecessary-ellipsis
+
+
+class TextEmbedder(Protocol):
+    """
+    Protocol for Text Embedders.
+    """
+
+    def run(self, text: str) -> Dict[str, Any]:
+        """
+        Generate embeddings for the input text.
+
+        Implementing classes may accept additional optional parameters in their run method.
+        For example: `def run (self, text: str, param_a="default", param_b="another_default")`.
+
+        :param text:
+            The input text to be embedded.
+        :returns:
+            A dictionary containing the keys:
+                - 'embedding', which is expected to be a List[float] representing the embedding.
+                - any optional keys such as 'metadata'.
+        """
+        ...

releasenotes/notes/adding-TextEmbedder-Protocol-948b31b005d798b9.yaml

@@ -0,0 +1,5 @@
+---
+enhancements:
+  - |
+    We now have a Protocol for TextEmbedder. The protocol makes it easier to create custom components or SuperComponents
+    that expect any TextEmbedder as init parameter.

test/components/embedders/types/test_protocol.py

@@ -0,0 +1,60 @@
+import inspect
+from typing import Any, Dict
+
+import pytest
+
+from haystack import component
+from haystack.components.embedders.types.protocol import TextEmbedder
+
+
+@component
+class MockTextEmbedder:
+    def run(self, text: str, param_a: str = "default", param_b: str = "another_default") -> Dict[str, Any]:
+        return {"embedding": [0.1, 0.2, 0.3], "metadata": {"text": text, "param_a": param_a, "param_b": param_b}}
+
+
+@component
+class MockInvalidTextEmbedder:
+    def run(self, something_else: float) -> dict[str, bool]:
+        return {"result": True}
+
+
+def test_protocol_implementation():
+    embedder: TextEmbedder = MockTextEmbedder()  # should not raise any type errors
+
+    # check if the run method has the correct signature
+    run_signature = inspect.signature(MockTextEmbedder.run)
+    assert "text" in run_signature.parameters
+    assert run_signature.parameters["text"].annotation == str
+    assert run_signature.return_annotation == Dict[str, Any]
+
+    result = embedder.run("test text")
+    assert isinstance(result, dict)
+    assert "embedding" in result
+    assert isinstance(result["embedding"], list)
+    assert all(isinstance(x, float) for x in result["embedding"])
+    assert isinstance(result["metadata"], dict)
+
+
+def test_protocol_optional_parameters():
+    embedder = MockTextEmbedder()
+
+    # default parameters
+    result1 = embedder.run("test text")
+
+    # with custom parameters
+    result2 = embedder.run("test text", param_a="custom_a", param_b="custom_b")
+
+    assert result1["metadata"]["param_a"] == "default"
+    assert result2["metadata"]["param_a"] == "custom_a"
+    assert result2["metadata"]["param_b"] == "custom_b"
+
+
+def test_protocol_invalid_implementation():
+    run_signature = inspect.signature(MockInvalidTextEmbedder.run)
+
+    with pytest.raises(AssertionError):
+        assert "text" in run_signature.parameters and run_signature.parameters["text"].annotation == str
+
+    with pytest.raises(AssertionError):
+        assert run_signature.return_annotation == Dict[str, Any]