feat: support FileContent in OpenAIResponsesChatGenerator (#10555)

* FileContent first draft

* progress + tests

* reduce to_openai_dict complexity

* more tests

* schema tests + relnote

* better err msg

* refinement

* draft

* feat: support FileContent in OpenAIResponsesChatGenerator

* lint

Author: anakin87

haystack/components/generators/chat/openai_responses.py

@@ -18,6 +18,7 @@
     AsyncStreamingCallbackT,
     ChatMessage,
     ComponentInfo,
+    FileContent,
     ImageContent,
     ReasoningContent,
     StreamingCallbackT,
@@ -804,7 +805,7 @@ def _convert_chat_message_to_responses_api_format(message: ChatMessage) -> list[
         If the message format is invalid.
     """
 
-    def serialize_part(part) -> dict[str, str]:
+    def convert_part(part) -> dict[str, str | None]:
         if isinstance(part, TextContent):
             return {"type": "input_text", "text": part.text}
         elif isinstance(part, ImageContent):
@@ -813,18 +814,25 @@ def serialize_part(part) -> dict[str, str]:
                 # If no MIME type is provided, default to JPEG. OpenAI API appears to tolerate MIME type mismatches.
                 "image_url": f"data:{part.mime_type or 'image/jpeg'};base64,{part.base64_image}",
             }
+        elif isinstance(part, FileContent):
+            return {
+                "type": "input_file",
+                "filename": part.filename,
+                "file_data": f"data:{part.mime_type or 'application/pdf'};base64,{part.base64_data}",
+            }
         raise ValueError(f"Unsupported content type: {type(part)}")
 
     text_contents = message.texts
     tool_calls = message.tool_calls
     tool_call_results = message.tool_call_results
     images = message.images
     reasonings = message.reasonings
+    files = message.files
 
-    if not text_contents and not tool_calls and not tool_call_results and not images and not reasonings:
+    if not any([text_contents, tool_calls, tool_call_results, images, reasonings, files]):
         raise ValueError(
             """A `ChatMessage` must contain at least one `TextContent`, `ToolCall`, `ToolCallResult`,
-              `ImageContent`, or `ReasoningContent`."""
+              `ImageContent`, `FileContent`, or `ReasoningContent`."""
         )
     if len(tool_call_results) > 0 and len(message._content) > 1:
         raise ValueError(
@@ -838,7 +846,7 @@ def serialize_part(part) -> dict[str, str]:
 
     # user message
     if message._role.value == "user":
-        content = [serialize_part(part) for part in message._content]
+        content = [convert_part(part) for part in message._content]
         openai_msg["content"] = content
         return [openai_msg]
 
@@ -849,7 +857,7 @@ def serialize_part(part) -> dict[str, str]:
             if result.origin.id is not None:
                 # Handle multimodal tool results (list of TextContent/ImageContent)
                 if isinstance(result.result, list):
-                    output_content = [serialize_part(part) for part in result.result]
+                    output_content = [convert_part(part) for part in result.result]
                 elif isinstance(result.result, str):
                     output_content = [{"type": "input_text", "text": result.result}]
                 else:

releasenotes/notes/file-content-responses-api-fac8d0323d27a4f3.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    Added support for Chat Messages that include files using the ``FileContent`` dataclass
+    to ``OpenAIResponsesChatGenerator`` and ``AzureOpenAIResponsesChatGenerator``.
+
+    Users can now pass files such as PDFs when using Haystack Chat Generators based on the Responses API.

test/components/generators/chat/test_openai_responses.py

@@ -15,7 +15,7 @@
 from haystack.components.agents import Agent
 from haystack.components.generators.chat.openai_responses import OpenAIResponsesChatGenerator
 from haystack.components.generators.utils import print_streaming_chunk
-from haystack.dataclasses import ChatMessage, ChatRole, ImageContent, StreamingChunk, TextContent, ToolCall
+from haystack.dataclasses import ChatMessage, ChatRole, FileContent, ImageContent, StreamingChunk, TextContent, ToolCall
 from haystack.tools import ComponentTool, Tool, Toolset, create_tool_from_function
 from haystack.utils import Secret
 
@@ -768,6 +768,28 @@ def test_live_run_multimodal(self, test_files_path):
         assert not message.tool_calls
         assert not message.tool_call_results
 
+    def test_live_run_with_file_content(self, test_files_path):
+        pdf_path = test_files_path / "pdf" / "sample_pdf_3.pdf"
+
+        file_content = FileContent.from_file_path(file_path=pdf_path)
+
+        chat_messages = [
+            ChatMessage.from_user(
+                content_parts=[file_content, "Is this document a paper about LLMs? Respond with 'yes' or 'no' only."]
+            )
+        ]
+
+        generator = OpenAIResponsesChatGenerator(model="gpt-4.1-nano")
+        results = generator.run(chat_messages)
+
+        assert len(results["replies"]) == 1
+        message: ChatMessage = results["replies"][0]
+
+        assert message.is_from(ChatRole.ASSISTANT)
+
+        assert message.text
+        assert "no" in message.text.lower()
+
     @pytest.mark.skip(reason="The tool calls time out resulting in failing")
     def test_live_run_with_openai_tools(self):
         """

test/components/generators/chat/test_openai_responses_conversion.py

@@ -37,6 +37,7 @@
 from haystack.dataclasses import (
     ChatMessage,
     ChatRole,
+    FileContent,
     ImageContent,
     ReasoningContent,
     StreamingChunk,
@@ -1266,6 +1267,23 @@ def test_convert_multimodal_user_message(self, base64_image_string):
             ],
         }
 
+    def test_convert_user_message_with_file_content(self, base64_pdf_string):
+        message = ChatMessage.from_user(
+            content_parts=[FileContent(base64_data=base64_pdf_string, mime_type="application/pdf", filename="test.pdf")]
+        )
+        assert _convert_chat_message_to_responses_api_format(message) == [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "input_file",
+                        "filename": "test.pdf",
+                        "file_data": f"data:application/pdf;base64,{base64_pdf_string}",
+                    }
+                ],
+            }
+        ]
+
     def test_convert_assistant_message(self):
         message = ChatMessage.from_assistant(text="I have an answer", meta={"finish_reason": "stop"})
         assert _convert_chat_message_to_responses_api_format(message) == [