chore: deprecate to_openai_format and create similar utility functions (#8146)

* deprecate and add new specific functions

* reno

Author: anakin87

haystack/components/generators/chat/hugging_face_api.py

@@ -18,6 +18,22 @@
 logger = logging.getLogger(__name__)
 
 
+def _convert_message_to_hfapi_format(message: ChatMessage) -> Dict[str, str]:
+    """
+    Convert a message to the format expected by Hugging Face APIs.
+
+    :returns: A dictionary with the following keys:
+        - `role`
+        - `content`
+        - `name` (optional)
+    """
+    formatted_msg = {"role": message.role.value, "content": message.content}
+    if message.name:
+        formatted_msg["name"] = message.name
+
+    return formatted_msg
+
+
 @component
 class HuggingFaceAPIChatGenerator:
     """
@@ -204,7 +220,7 @@ def run(self, messages: List[ChatMessage], generation_kwargs: Optional[Dict[str,
         # update generation kwargs by merging with the default ones
         generation_kwargs = {**self.generation_kwargs, **(generation_kwargs or {})}
 
-        formatted_messages = [m.to_openai_format() for m in messages]
+        formatted_messages = [_convert_message_to_hfapi_format(message) for message in messages]
 
         if self.streaming_callback:
             return self._run_streaming(formatted_messages, generation_kwargs)

haystack/components/generators/chat/openai.py

@@ -13,6 +13,7 @@
 from openai.types.chat.chat_completion_chunk import Choice as ChunkChoice
 
 from haystack import component, default_from_dict, default_to_dict, logging
+from haystack.components.generators.openai_utils import _convert_message_to_openai_format
 from haystack.dataclasses import ChatMessage, StreamingChunk
 from haystack.utils import Secret, deserialize_callable, deserialize_secrets_inplace, serialize_callable
 
@@ -204,7 +205,7 @@ def run(
         streaming_callback = streaming_callback or self.streaming_callback
 
         # adapt ChatMessage(s) to the format expected by the OpenAI API
-        openai_formatted_messages = [message.to_openai_format() for message in messages]
+        openai_formatted_messages = [_convert_message_to_openai_format(message) for message in messages]
 
         chat_completion: Union[Stream[ChatCompletionChunk], ChatCompletion] = self.client.chat.completions.create(
             model=self.model,

haystack/components/generators/openai.py

@@ -9,6 +9,7 @@
 from openai.types.chat import ChatCompletion, ChatCompletionChunk
 
 from haystack import component, default_from_dict, default_to_dict, logging
+from haystack.components.generators.openai_utils import _convert_message_to_openai_format
 from haystack.dataclasses import ChatMessage, StreamingChunk
 from haystack.utils import Secret, deserialize_callable, deserialize_secrets_inplace, serialize_callable
 
@@ -200,7 +201,7 @@ def run(
         streaming_callback = streaming_callback or self.streaming_callback
 
         # adapt ChatMessage(s) to the format expected by the OpenAI API
-        openai_formatted_messages = [message.to_openai_format() for message in messages]
+        openai_formatted_messages = [_convert_message_to_openai_format(message) for message in messages]
 
         completion: Union[Stream[ChatCompletionChunk], ChatCompletion] = self.client.chat.completions.create(
             model=self.model,

haystack/components/generators/openai_utils.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <[email protected]>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Dict
+
+from haystack.dataclasses import ChatMessage
+
+
+def _convert_message_to_openai_format(message: ChatMessage) -> Dict[str, str]:
+    """
+    Convert a message to the format expected by OpenAI's Chat API.
+
+    See the [API reference](https://platform.openai.com/docs/api-reference/chat/create) for details.
+
+    :returns: A dictionary with the following key:
+        - `role`
+        - `content`
+        - `name` (optional)
+    """
+    openai_msg = {"role": message.role.value, "content": message.content}
+    if message.name:
+        openai_msg["name"] = message.name
+
+    return openai_msg

haystack/dataclasses/chat_message.py

@@ -5,6 +5,7 @@
 from dataclasses import asdict, dataclass, field
 from enum import Enum
 from typing import Any, Dict, Optional
+from warnings import warn
 
 
 class ChatRole(str, Enum):
@@ -43,6 +44,8 @@ def to_openai_format(self) -> Dict[str, Any]:
             - `content`
             - `name` (optional)
         """
+        warn("The `to_openai_format` method is deprecated and will be removed in Haystack 2.5.0.", DeprecationWarning)
+
         msg = {"role": self.role.value, "content": self.content}
         if self.name:
             msg["name"] = self.name

releasenotes/notes/deprecate-method-to-openai-format-fb2538cf3f610d2a.yaml

@@ -0,0 +1,7 @@
+---
+deprecations:
+  - |
+    Deprecate the method `to_openai_format` of the `ChatMessage` dataclass.
+    This method was never intended to be public and was only used internally.
+    Now, each Chat Generator will know internally how to convert the messages to
+    the format of their specific provider.

test/components/generators/chat/test_hugging_face_api.py

@@ -15,7 +15,10 @@
 )
 from huggingface_hub.utils import RepositoryNotFoundError
 
-from haystack.components.generators.chat import HuggingFaceAPIChatGenerator
+from haystack.components.generators.chat.hugging_face_api import (
+    HuggingFaceAPIChatGenerator,
+    _convert_message_to_hfapi_format,
+)
 from haystack.dataclasses import ChatMessage, StreamingChunk
 from haystack.utils.auth import Secret
 from haystack.utils.hf import HFGenerationAPIType
@@ -58,6 +61,21 @@ def streaming_callback_handler(x):
     return x
 
 
+def test_convert_message_to_hfapi_format():
+    message = ChatMessage.from_system("You are good assistant")
+    assert _convert_message_to_hfapi_format(message) == {"role": "system", "content": "You are good assistant"}
+
+    message = ChatMessage.from_user("I have a question")
+    assert _convert_message_to_hfapi_format(message) == {"role": "user", "content": "I have a question"}
+
+    message = ChatMessage.from_function("Function call", "function_name")
+    assert _convert_message_to_hfapi_format(message) == {
+        "role": "function",
+        "content": "Function call",
+        "name": "function_name",
+    }
+
+
 class TestHuggingFaceAPIGenerator:
     def test_init_invalid_api_type(self):
         with pytest.raises(ValueError):

test/components/generators/test_openai_utils.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2022-present deepset GmbH <[email protected]>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import pytest
+
+from haystack.dataclasses import ChatMessage
+from haystack.components.generators.openai_utils import _convert_message_to_openai_format
+
+
+def test_convert_message_to_openai_format():
+    message = ChatMessage.from_system("You are good assistant")
+    assert _convert_message_to_openai_format(message) == {"role": "system", "content": "You are good assistant"}
+
+    message = ChatMessage.from_user("I have a question")
+    assert _convert_message_to_openai_format(message) == {"role": "user", "content": "I have a question"}
+
+    message = ChatMessage.from_function("Function call", "function_name")
+    assert _convert_message_to_openai_format(message) == {
+        "role": "function",
+        "content": "Function call",
+        "name": "function_name",
+    }