fix: make HuggingFaceAPIChatGenerator convert Tool Call arguments from string (#9303)

* fix: sort imports in hugging_face_api.py

* fix: import logging in hugging_face_api.py

* fix: refactor HuggingFace API tool call handling for improved argument conversion

* Update haystack/components/generators/chat/hugging_face_api.py

Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com>

* refinements + tests + relnote

* simplify

---------

Co-authored-by: Stefano Fiorucci <stefanofiorucci@gmail.com>

Author: 2 people

haystack/components/generators/chat/hugging_face_api.py

@@ -2,10 +2,11 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import json
 from datetime import datetime
 from typing import Any, AsyncIterable, Dict, Iterable, List, Optional, Union
 
-from haystack import component, default_from_dict, default_to_dict
+from haystack import component, default_from_dict, default_to_dict, logging
 from haystack.dataclasses import ChatMessage, StreamingChunk, ToolCall, select_streaming_callback
 from haystack.dataclasses.streaming_chunk import StreamingCallbackT
 from haystack.lazy_imports import LazyImport
@@ -20,17 +21,65 @@
 from haystack.utils.hf import HFGenerationAPIType, HFModelType, check_valid_model, convert_message_to_hf_format
 from haystack.utils.url_validation import is_valid_http_url
 
+logger = logging.getLogger(__name__)
+
 with LazyImport(message="Run 'pip install \"huggingface_hub[inference]>=0.27.0\"'") as huggingface_hub_import:
     from huggingface_hub import (
         AsyncInferenceClient,
         ChatCompletionInputFunctionDefinition,
         ChatCompletionInputTool,
         ChatCompletionOutput,
+        ChatCompletionOutputToolCall,
         ChatCompletionStreamOutput,
         InferenceClient,
     )
 
 
+def _convert_hfapi_tool_calls(hfapi_tool_calls: Optional[List["ChatCompletionOutputToolCall"]]) -> List[ToolCall]:
+    """
+    Convert HuggingFace API tool calls to a list of Haystack ToolCall.
+
+    :param hfapi_tool_calls: The HuggingFace API tool calls to convert.
+    :returns: A list of ToolCall objects.
+
+    """
+    if not hfapi_tool_calls:
+        return []
+
+    tool_calls = []
+
+    for hfapi_tc in hfapi_tool_calls:
+        hf_arguments = hfapi_tc.function.arguments
+
+        arguments = None
+        if isinstance(hf_arguments, dict):
+            arguments = hf_arguments
+        elif isinstance(hf_arguments, str):
+            try:
+                arguments = json.loads(hf_arguments)
+            except json.JSONDecodeError:
+                logger.warning(
+                    "HuggingFace API returned a malformed JSON string for tool call arguments. This tool call "
+                    "will be skipped. Tool call ID: {_id}, Tool name: {_name}, Arguments: {_arguments}",
+                    _id=hfapi_tc.id,
+                    _name=hfapi_tc.function.name,
+                    _arguments=hf_arguments,
+                )
+        else:
+            logger.warning(
+                "HuggingFace API returned tool call arguments of type {_type}. Valid types are dict and str. This tool "
+                "call will be skipped. Tool call ID: {_id}, Tool name: {_name}, Arguments: {_arguments}",
+                _id=hfapi_tc.id,
+                _name=hfapi_tc.function.name,
+                _arguments=hf_arguments,
+            )
+
+        if arguments:
+            tool_calls.append(ToolCall(tool_name=hfapi_tc.function.name, arguments=arguments, id=hfapi_tc.id))
+
+    return tool_calls
+
+
 @component
 class HuggingFaceAPIChatGenerator:
     """
@@ -403,14 +452,8 @@ def _run_non_streaming(
         choice = api_chat_output.choices[0]
 
         text = choice.message.content
-        tool_calls = []
 
-        if hfapi_tool_calls := choice.message.tool_calls:
-            for hfapi_tc in hfapi_tool_calls:
-                tool_call = ToolCall(
-                    tool_name=hfapi_tc.function.name, arguments=hfapi_tc.function.arguments, id=hfapi_tc.id
-                )
-                tool_calls.append(tool_call)
+        tool_calls = _convert_hfapi_tool_calls(choice.message.tool_calls)
 
         meta: Dict[str, Any] = {
             "model": self._client.model,
@@ -486,14 +529,8 @@ async def _run_non_streaming_async(
         choice = api_chat_output.choices[0]
 
         text = choice.message.content
-        tool_calls = []
 
-        if hfapi_tool_calls := choice.message.tool_calls:
-            for hfapi_tc in hfapi_tool_calls:
-                tool_call = ToolCall(
-                    tool_name=hfapi_tc.function.name, arguments=hfapi_tc.function.arguments, id=hfapi_tc.id
-                )
-                tool_calls.append(tool_call)
+        tool_calls = _convert_hfapi_tool_calls(choice.message.tool_calls)
 
         meta: Dict[str, Any] = {
             "model": self._async_client.model,

releasenotes/notes/hfapichatgenerator-toolcall-str-args-b857e65073ba9f2b.yaml

@@ -0,0 +1,6 @@
+---
+fixes:
+  - |
+    The `HuggingFaceAPIChatGenerator` now checks the type of the `arguments` variable in the tool calls returned by the
+    Hugging Face API. If `arguments` is a JSON string, it is parsed into a dictionary.
+    Previously, the `arguments` type was not checked, which sometimes led to failures later in the tool workflow.

test/components/generators/chat/test_hugging_face_api.py

@@ -23,7 +23,7 @@
 )
 from huggingface_hub.utils import RepositoryNotFoundError
 
-from haystack.components.generators.chat.hugging_face_api import HuggingFaceAPIChatGenerator
+from haystack.components.generators.chat.hugging_face_api import HuggingFaceAPIChatGenerator, _convert_hfapi_tool_calls
 from haystack.tools import Tool
 from haystack.dataclasses import ChatMessage, ToolCall
 from haystack.tools.toolset import Toolset
@@ -573,6 +573,73 @@ def test_run_with_tools(self, mock_check_valid_model, tools):
             "usage": {"completion_tokens": 30, "prompt_tokens": 426},
         }
 
+    def test_convert_hfapi_tool_calls_empty(self):
+        hfapi_tool_calls = None
+        tool_calls = _convert_hfapi_tool_calls(hfapi_tool_calls)
+        assert len(tool_calls) == 0
+
+        hfapi_tool_calls = []
+        tool_calls = _convert_hfapi_tool_calls(hfapi_tool_calls)
+        assert len(tool_calls) == 0
+
+    def test_convert_hfapi_tool_calls_dict_arguments(self):
+        hfapi_tool_calls = [
+            ChatCompletionOutputToolCall(
+                function=ChatCompletionOutputFunctionDefinition(
+                    arguments={"city": "Paris"}, name="weather", description=None
+                ),
+                id="0",
+                type="function",
+            )
+        ]
+        tool_calls = _convert_hfapi_tool_calls(hfapi_tool_calls)
+        assert len(tool_calls) == 1
+        assert tool_calls[0].tool_name == "weather"
+        assert tool_calls[0].arguments == {"city": "Paris"}
+        assert tool_calls[0].id == "0"
+
+    def test_convert_hfapi_tool_calls_str_arguments(self):
+        hfapi_tool_calls = [
+            ChatCompletionOutputToolCall(
+                function=ChatCompletionOutputFunctionDefinition(
+                    arguments='{"city": "Paris"}', name="weather", description=None
+                ),
+                id="0",
+                type="function",
+            )
+        ]
+        tool_calls = _convert_hfapi_tool_calls(hfapi_tool_calls)
+        assert len(tool_calls) == 1
+        assert tool_calls[0].tool_name == "weather"
+        assert tool_calls[0].arguments == {"city": "Paris"}
+        assert tool_calls[0].id == "0"
+
+    def test_convert_hfapi_tool_calls_invalid_str_arguments(self):
+        hfapi_tool_calls = [
+            ChatCompletionOutputToolCall(
+                function=ChatCompletionOutputFunctionDefinition(
+                    arguments="not a valid JSON string", name="weather", description=None
+                ),
+                id="0",
+                type="function",
+            )
+        ]
+        tool_calls = _convert_hfapi_tool_calls(hfapi_tool_calls)
+        assert len(tool_calls) == 0
+
+    def test_convert_hfapi_tool_calls_invalid_type_arguments(self):
+        hfapi_tool_calls = [
+            ChatCompletionOutputToolCall(
+                function=ChatCompletionOutputFunctionDefinition(
+                    arguments=["this", "is", "a", "list"], name="weather", description=None
+                ),
+                id="0",
+                type="function",
+            )
+        ]
+        tool_calls = _convert_hfapi_tool_calls(hfapi_tool_calls)
+        assert len(tool_calls) == 0
+
     @pytest.mark.integration
     @pytest.mark.skipif(
         not os.environ.get("HF_API_TOKEN", None),
@@ -639,9 +706,6 @@ def test_live_run_serverless_streaming(self):
         not os.environ.get("HF_API_TOKEN", None),
         reason="Export an env var called HF_API_TOKEN containing the Hugging Face token to run this test.",
     )
-    @pytest.mark.xfail(
-        reason="The Hugging Face API can be unstable and this test may fail intermittently", strict=False
-    )
     def test_live_run_with_tools(self, tools):
         """
         We test the round trip: generate tool call, pass tool message, generate response.