feat!: HuggingFaceLocalChatGenerator unified support for tools

[vblagoje]

Why:

Adds universal tools support to HuggingFaceLocalChatGenerator

What:

• Introduced support for tool calls, allowing the generation model to prepare and parse tool interactions.
• Implemented a tool call parsing method that utilizes regex patterns or callables.

How can it be used:

The addition allows for parsing tool calls from generated text, identified by tool names and their arguments. This can be set up during initialization:

import torch

from haystack.dataclasses import ChatMessage
from haystack.tools import Tool
from haystack.components.generators.chat import HuggingFaceLocalChatGenerator
from haystack.utils import Secret

def weather(city: str):
    return f'The weather in {city} is sunny and 32°C'

# Define tool parameters
tool_parameters = {
    "type": "object",
    "properties": {"city": {"type": "string"}},
    "required": ["city"]
}

# Create weather tool
weather_tool = Tool(
    name="weather",
    description="useful to determine the weather in a given location",
    parameters=tool_parameters,
    function=weather
)
# Initialize generator with tool
client = HuggingFaceLocalChatGenerator(
    model="NousResearch/Hermes-2-Pro-Llama-3-8B",
    token=Secret.from_env_var("HF_TOKEN"),
    tools=[weather_tool],
    huggingface_pipeline_kwargs={"torch_dtype":torch.bfloat16, "device_map": "auto"}
)
client.warm_up()

# Run initial query
messages = [ChatMessage.from_user("What's the weather like in Paris?")]
results = client.run(messages=messages)

# Get tool call from response
tool_message = next(msg for msg in results["replies"] if msg.tool_call)
tool_call = tool_message.tool_call

# Execute tool and send result back
weather_result = weather(**tool_call.arguments)
new_messages = [
    messages[0],
    tool_message,
    ChatMessage.from_tool(tool_result=weather_result, origin=tool_call)
]

# Get final response
final_result = client.run(new_messages)
print(final_result["replies"][0].text)

>>> The weather in Paris is sunny and 32°C. Enjoy your day!

How did you test it:

• Added unit tests that mock generator run with specified tool patterns and tool lists
• Real test notebook

Notes for the reviewer:

• See https://huggingface.co/blog/unified-tool-use for more details about HF and tools
• Validate the regex pattern for tool call extraction.
• Ensure comprehensive testing of different tool call scenarios to guarantee robustness.

[coveralls]

Pull Request Test Coverage Report for Build 13200235309

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 23 unchanged lines in 1 file lost coverage.
• Overall coverage decreased (-0.07%) to 92.58%

---

Files with Coverage Reduction	New Missed Lines	%
components/generators/chat/hugging_face_local.py	23	84.46%

Totals
Change from base Build 13183889468:	-0.07%
Covered Lines:	9058
Relevant Lines:	9784

---

💛 - Coveralls

[vblagoje]

@davidsbatista asking @anakin87 for review here as he knows this code intimately 🙏

[anakin87]

Nice work! I particularly appreciated the notebook...

I left some comments about points we can improve.

[vblagoje]

Have a look at the updated run of the notebook as well @anakin87 🙏

[anakin87]

I left a small comment to address.

Plus, "feat!:" in the PR title indicates a breaking change, and this does not seem breaking.
If I am right, let's simply change this to "feat:"

Feel free to merge once these small aspects are fixed.

Good work!

[anakin87]

this generated_text is confusing. Please use something like "mock response. We don't use it"

[anakin87]

we are only extracting a single tool call, but this is clearly explained.
We can improve this in future if there are requests from the community.