Migration of experimental ChatMessage to Haystack

[anakin87]

Summary and motivation

Plan

Tasks

Beta Give feedback

1. Haystack 2.8.0
2. ChatMessage - introduce text property #8587
   +0
   
3. Replace direct instantiation of ChatMessage with specific class methods - chore: use class methods to create ChatMessage #8581
4. core-integrations: Replace direct instantiation of ChatMessage with specific class methods -chore: use class methods to create ChatMessage haystack-core-integrations#1222
5. Between Haystack 2.8.0 and 2.9.0
6. core-integrations: Update all components to use text instead of content
7. materials: adapt all code examples to use text (instead of content) in docs, tutorials, cookbook, integration pages, blogposts?
8. Haystack 2.9.0
9. Replace the old ChatMessage with the new version: clear release notes + explicit error message if the instance is created using old params
10. function role/from_function class method: deprecate them; from_function should produce a tool message (with clear explanation for users)
11. messaging: release notes + migration guide (if possible/appropriate) + announcements on GitHub
12. Haystack 2.10.0
13. remove deprecated function role/from_function class method

[anakin87]

Motivation

During the Tools experiment, we have refactored the ChatMessage dataclass to make it more flexible and future-proof.

• extensible support for different types of content: text, tool calls, tool calls results (images in the future)
• full support for Tools
• attributes have been made internal; the preferred way for users to build messages is using specific class methods (ChatMessage.from_user, ChatMessage.from_assistant, …)

Existing Haystack dataclass; Experimental dataclass

Now, we plan to port these changes into Haystack.

My impression is that introducing the new dataclass without breaking changes is rather difficult. I would prefer to minimize breaking changes, but make it clear and transparent to users what is changing.

Breaking changes

Replacing the old dataclass with the new one will introduce the following breaking changes:

• Direct creation of ChatMessage instances
  ChatMessage(role=ChatRole.USER, content=”Hello!”)
• Deserialization of previously serialized pipelines
  Pipelines containing serialized ChatMessage instances will need to be recreated.

Existing class methods to create ChatMessage instances (ChatMessage.from_user, ...) won’t break.

Some breaking changes we can avoid/smoothly introduce

• Accessing the content attribute
  if an application/user is just a consumer of the ChatMessage instance, they are likely accessing the content attribute to retrieve textual content. Introducing a text property in version 2.8.0 that mirrors content and encouraging users to adopt it will ensure compatibility when the new dataclass is introduced in version 2.9.0.
• function role and from_function
  A less significant breaking change involves the function role: this role is outdated and removing it soon would simplify the management of Tools. Additionally, the ChatMessage.from_function sets the name attribute in ChatMessage , which will not exist in the new dataclass. However, I believe both that the transition can be made gradually and that not many people are still using this.

[sjrl]

@anakin87 out of curiosity do the changes discussed also allow for support of Image message types? For example, the Image type used by OpenAI https://github.com/openai/openai-python/blob/83f4774156dc3e29c7fe6be9ffd681df68534509/src/openai/types/image.py#L10

This would be needed to be able to pass images to ChatGenerators to run Visual QA.

[anakin87]

@sjrl we will not immediately introduce support for images with the changes in 2.9.0, but that is the idea: make content more flexible. Images will be just another type of content.