⚠️ Refactoring of ChatMessage

[bilgeyucel]

Starting with version 2.9.0, the content attribute ChatMessage has been removed and replaced with a new text property for accessing the textual value of a ChatMessage. This change introduces a breaking change for existing implementations.

Additionally, the "function" role and the ChatMessage.from_function class method has been deprecated in 2.9.0 and will be removed in Haystack 2.10.0.

How to use the new ChatMessage

from haystack.dataclasses import ChatMessage, ChatRole

user_message = ChatMessage(role=ChatRole.USER, content="What is the capital of Australia?") ❌

user_message = ChatMessage.from_user("What is the capital of Australia?") ✅

print(user_message.content) ❌

print(user_message.text) ✅
>>> What is the capital of Australia?

tool_message = ChatMessage.from_function(content="temperature: 25°C", name="get_current_weather") ❌

tool_message = ChatMessage.from_tool(tool_result="temperature: 25°C", origin=tool_call, error=False) ✅

Additionally, if your pipeline includes a ChatPromptBuilder serialized with haystack-ai version earlier than 2.9.0, deserialization may fail due to the field change. To address this issue, refer to the Migrating From Legacy ChatMessage guide for the necessary migration steps.

Why are we doing this?

ChatMessage dataclass has been refactored to improve flexibility and compatibility. This change ensures future-proofing and better support for features like tool calls and their results

Let us know 🙌

If you have any questions or comments regarding this refactoring, feel free to comment on this post or message the #haystack channel on Discord.

[d-kleine]

As a user, I appreciate the changes you're introducing to future-proofing like tool support. However, I have some constructive feedback regarding the re-factorization:

The previous implementation with direct constructor usage:

user_message = ChatMessage(role=ChatRole.USER, content="What is the capital of Australia?")

feels more aligned with common API patterns in the ecosystem. Major providers like OpenAI and Ollama follow this convention for their API.

Two main concerns:

1. The shift from content to text seems to diverge from industry standards. The content attribute is widely used across platforms (OpenAI, Arize, etc.) and better represents the versatility of the output, which isn't always strictly textual - it could be code, numerical data, symbols, or other formats.

2. Regarding tool calls, integrating them as parameters in the original implementation style (similar to Ollama's approach with tool_calls) might offer a more straightforward and familiar developer experience.

[lambda-science]

100% agree, I'm a little bit confused as well how and why it diverge from the standard

[anakin87]

@d-kleine @lambda-science thank you for the feedback...

About using a format for ChatMessage that aligns with OpenAI, I actually had the same thought initially, but after some internal discussions, I shifted towards thinking about a more stable, provider-agnostic abstraction. If you look at how Anthropic and Google handle different types of content, there’s no universal standard (though I do agree OpenAI is pretty close to a standard).

In any case, we are also exposing some utility functions to convert from/to OpenAI format: from_openai_dict_format and to_openai_dict_format.

@d-kleine Could you explain your second point a bit more?

[d-kleine]

About using a format for ChatMessage that aligns with OpenAI, I actually had the same thought initially, but after some internal discussions, I shifted towards thinking about a more stable, provider-agnostic abstraction. If you look at how Anthropic and Google handle different types of content, there’s no universal standard (though I do agree OpenAI is pretty close to a standard).

I just looked into in ChatMessage docs, the setup looks okay to me (also the from_assistant with ToolCall example). My only concern is that it might be slightly different from what users are used to with the direct constructor, which could cause some minor complications in some cases. For instance, how would you go about creating a chat message that combines roles like 'system', 'assistant', and 'user' - as seen in this Antropic example? I'm thinking specifically of partially-filled responses.

On a separate note, I still think it'd be more intuitive to rename the chat message's property to content instead of text.

@d-kleine Could you explain your second point a bit more?

It's related to the direct constructor usage. Ollama uses tools as a parameter, see here for reference:

import ollama

response = ollama.chat(
  model='llama3.1',
  messages=[{'role': 'user', 'content': 'What is 10 + 10?'}],
  tools=[add_two_numbers], # Actual function reference
)

With tool_calls, you can then process and execute this function:

for tool in response.message.tool_calls or []:
    function_to_call = available_functions.get(tool.function.name)
    ...

This would be more straightforward for me.

In your current implementation, one more tiny suggestion I have is that the origin parameter in from_tool could benefit from a more descriptive name. Maybe something like tool_calls, just like in the from_assistant, to be consistent and being able to call multiple tools as a list.

• from_assistant:

from haystack.dataclasses import ChatMessage, ToolCall

tool_call = ToolCall(tool_name="weather_tool", arguments={"location": "Rome"})
assistant_message_w_tool_call = ChatMessage.from_assistant(tool_calls=[tool_call]) # uses 'tool_calls' param

• from_tool:

from haystack.dataclasses import ChatMessage, ToolCall

tool_call = ToolCall(tool_name="weather_tool", arguments={"location": "Rome"})
tool_message = ChatMessage.from_tool(tool_result="temperature: 25°C", origin=tool_call, error=False) # 'origin' -> 'tool_calls'?

[lambda-science]

For instance, how would you go about creating a chat message that combines roles like 'system', 'assistant', and 'user' - as seen in this Antropic example? I'm thinking specifically of partially-filled responses.

Not sure what you mean by that. You can feed ChatGenerator a list of chat message

messages: List[ChatMessage] = [
ChatMessage.from_system(...),
ChatMessage.from_user(...),
ChatMessage.from_assistant(...)
]

[d-kleine]

Yeah, I was looking for this, thanks! I think it would be super helpful if this could be included in the ChatMessage docs.