fix: Rename index fields to chunk_index and tool_call_index for clarity

Author: Syed Shahmeer Ali

haystack/components/generators/chat/openai.py

@@ -541,8 +541,8 @@ def _convert_chat_completion_chunk_to_streaming_chunk(
         return StreamingChunk(
             content="",
             component_info=component_info,
-            # Index is None since it's only set to an int when a content block is present
-            index=None,
+            # chunk_index is None since it's only set to an int when a content block is present
+            chunk_index=None,
             finish_reason=None,
             meta={
                 "model": chunk.model,
@@ -560,7 +560,7 @@ def _convert_chat_completion_chunk_to_streaming_chunk(
             function = tool_call.function
             tool_calls_deltas.append(
                 ToolCallDelta(
-                    index=tool_call.index,
+                    tool_call_index=tool_call.index,
                     id=tool_call.id,
                     tool_name=function.name if function else None,
                     arguments=function.arguments if function and function.arguments else None,
@@ -569,14 +569,13 @@ def _convert_chat_completion_chunk_to_streaming_chunk(
         chunk_message = StreamingChunk(
             content=choice.delta.content or "",
             component_info=component_info,
-            # We adopt the first tool_calls_deltas.index as the overall index of the chunk.
-            index=tool_calls_deltas[0].index,
+            # We adopt the first tool_calls_deltas.tool_call_index as the overall chunk_index of the chunk.
+            chunk_index=tool_calls_deltas[0].tool_call_index,
             tool_calls=tool_calls_deltas,
             start=tool_calls_deltas[0].tool_name is not None,
             finish_reason=finish_reason_mapping.get(choice.finish_reason) if choice.finish_reason else None,
             meta={
                 "model": chunk.model,
-                "index": choice.index,
                 "tool_calls": choice.delta.tool_calls,
                 "finish_reason": choice.finish_reason,
                 "received_at": datetime.now().isoformat(),
@@ -598,14 +597,13 @@ def _convert_chat_completion_chunk_to_streaming_chunk(
     chunk_message = StreamingChunk(
         content=choice.delta.content or "",
         component_info=component_info,
-        index=resolved_index,
+        chunk_index=resolved_index,
         # The first chunk is always a start message chunk that only contains role information, so if we reach here
         # and previous_chunks is length 1 then this is the start of text content.
         start=len(previous_chunks) == 1,
         finish_reason=finish_reason_mapping.get(choice.finish_reason) if choice.finish_reason else None,
         meta={
             "model": chunk.model,
-            "index": choice.index,
             "tool_calls": choice.delta.tool_calls,
             "finish_reason": choice.finish_reason,
             "received_at": datetime.now().isoformat(),

haystack/components/generators/utils.py

@@ -25,7 +25,7 @@ def print_streaming_chunk(chunk: StreamingChunk) -> None:
     :param chunk: A chunk of streaming data containing content and optional metadata, such as tool calls and
         tool results.
     """
-    if chunk.start and chunk.index and chunk.index > 0:
+    if chunk.start and chunk.chunk_index and chunk.chunk_index > 0:
         # If this is the start of a new content block but not the first content block, print two new lines
         print("\n\n", flush=True, end="")
 
@@ -40,7 +40,7 @@ def print_streaming_chunk(chunk: StreamingChunk) -> None:
                 # If there is more than one tool call in the chunk, we print two new lines to separate them
                 # We know there is more than one tool call if the index of the tool call is greater than the index of
                 # the chunk.
-                if chunk.index and tool_call.index > chunk.index:
+                if chunk.chunk_index and tool_call.tool_call_index > chunk.chunk_index:
                     print("\n\n", flush=True, end="")
 
                 print(f"[TOOL CALL]\nTool: {tool_call.tool_name} \nArguments: ", flush=True, end="")
@@ -86,17 +86,17 @@ def _convert_streaming_chunks_to_chat_message(chunks: list[StreamingChunk]) -> C
             for tool_call in chunk.tool_calls:
                 # We use the index of the tool_call to track the tool call across chunks since the ID is not always
                 # provided
-                if tool_call.index not in tool_call_data:
-                    tool_call_data[tool_call.index] = {"id": "", "name": "", "arguments": ""}
+                if tool_call.tool_call_index not in tool_call_data:
+                    tool_call_data[tool_call.tool_call_index] = {"id": "", "name": "", "arguments": ""}
 
                 # Save the ID if present
                 if tool_call.id is not None:
-                    tool_call_data[tool_call.index]["id"] = tool_call.id
+                    tool_call_data[tool_call.tool_call_index]["id"] = tool_call.id
 
                 if tool_call.tool_name is not None:
-                    tool_call_data[tool_call.index]["name"] += tool_call.tool_name
+                    tool_call_data[tool_call.tool_call_index]["name"] += tool_call.tool_name
                 if tool_call.arguments is not None:
-                    tool_call_data[tool_call.index]["arguments"] += tool_call.arguments
+                    tool_call_data[tool_call.tool_call_index]["arguments"] += tool_call.arguments
 
     # Convert accumulated tool call data into ToolCall objects
     sorted_keys = sorted(tool_call_data.keys())
@@ -119,9 +119,16 @@ def _convert_streaming_chunks_to_chat_message(chunks: list[StreamingChunk]) -> C
     finish_reasons = [chunk.finish_reason for chunk in chunks if chunk.finish_reason]
     finish_reason = finish_reasons[-1] if finish_reasons else None
 
+    # Find the first chunk with a meaningful chunk_index (not None)
+    first_meaningful_chunk = None
+    for chunk in chunks:
+        if chunk.chunk_index is not None:
+            first_meaningful_chunk = chunk
+            break
+    
     meta = {
         "model": chunks[-1].meta.get("model"),
-        "index": 0,
+        "chunk_index": first_meaningful_chunk.chunk_index if first_meaningful_chunk else None,
         "finish_reason": finish_reason,
         "completion_start_time": chunks[0].meta.get("received_at"),  # first chunk received
         "usage": chunks[-1].meta.get("usage"),  # last chunk has the final usage data if available

haystack/dataclasses/streaming_chunk.py

@@ -19,13 +19,13 @@ class ToolCallDelta:
     """
     Represents a Tool call prepared by the model, usually contained in an assistant message.
 
-    :param index: The index of the Tool call in the list of Tool calls.
+    :param tool_call_index: The index of the Tool call in the list of Tool calls.
     :param tool_name: The name of the Tool to call.
     :param arguments: Either the full arguments in JSON format or a delta of the arguments.
     :param id: The ID of the Tool call.
     """
 
-    index: int
+    tool_call_index: int
     tool_name: Optional[str] = field(default=None)
     arguments: Optional[str] = field(default=None)
     id: Optional[str] = field(default=None)  # noqa: A003
@@ -34,7 +34,7 @@ def to_dict(self) -> dict[str, Any]:
         """
         Returns a dictionary representation of the ToolCallDelta.
 
-        :returns: A dictionary with keys 'index', 'tool_name', 'arguments', and 'id'.
+        :returns: A dictionary with keys 'tool_call_index', 'tool_name', 'arguments', and 'id'.
         """
         return asdict(self)
 
@@ -46,6 +46,9 @@ def from_dict(cls, data: dict[str, Any]) -> "ToolCallDelta":
         :param data: Dictionary containing ToolCallDelta's attributes.
         :returns: A ToolCallDelta instance.
         """
+        # Handle backward compatibility for old 'index' field
+        if 'index' in data and 'tool_call_index' not in data:
+            data['tool_call_index'] = data.pop('index')
         return ToolCallDelta(**data)
 
 
@@ -106,7 +109,7 @@ class StreamingChunk:
     :param meta: A dictionary containing metadata related to the message chunk.
     :param component_info: A `ComponentInfo` object containing information about the component that generated the chunk,
         such as the component name and type.
-    :param index: An optional integer index representing which content block this chunk belongs to.
+    :param chunk_index: An optional integer index representing which content block this chunk belongs to.
     :param tool_calls: An optional list of ToolCallDelta object representing a tool call associated with the message
         chunk.
     :param tool_call_result: An optional ToolCallResult object representing the result of a tool call.
@@ -119,7 +122,7 @@ class StreamingChunk:
     content: str
     meta: dict[str, Any] = field(default_factory=dict, hash=False)
     component_info: Optional[ComponentInfo] = field(default=None)
-    index: Optional[int] = field(default=None)
+    chunk_index: Optional[int] = field(default=None)
     tool_calls: Optional[list[ToolCallDelta]] = field(default=None)
     tool_call_result: Optional[ToolCallResult] = field(default=None)
     start: bool = field(default=False)
@@ -135,8 +138,8 @@ def __post_init__(self):
             )
 
         # NOTE: We don't enforce this for self.content otherwise it would be a breaking change
-        if (self.tool_calls or self.tool_call_result) and self.index is None:
-            raise ValueError("If `tool_call`, or `tool_call_result` is set, `index` must also be set.")
+        if (self.tool_calls or self.tool_call_result) and self.chunk_index is None:
+            raise ValueError("If `tool_call`, or `tool_call_result` is set, `chunk_index` must also be set.")
 
     def to_dict(self) -> dict[str, Any]:
         """
@@ -148,7 +151,7 @@ def to_dict(self) -> dict[str, Any]:
             "content": self.content,
             "meta": self.meta,
             "component_info": self.component_info.to_dict() if self.component_info else None,
-            "index": self.index,
+            "chunk_index": self.chunk_index,
             "tool_calls": [tc.to_dict() for tc in self.tool_calls] if self.tool_calls else None,
             "tool_call_result": self.tool_call_result.to_dict() if self.tool_call_result else None,
             "start": self.start,
@@ -166,11 +169,15 @@ def from_dict(cls, data: dict[str, Any]) -> "StreamingChunk":
         if "content" not in data:
             raise ValueError("Missing required field `content` in StreamingChunk deserialization.")
 
+        # Handle backward compatibility for old 'index' field
+        if 'index' in data and 'chunk_index' not in data:
+            data['chunk_index'] = data.pop('index')
+
         return StreamingChunk(
             content=data["content"],
             meta=data.get("meta", {}),
             component_info=ComponentInfo.from_dict(data["component_info"]) if data.get("component_info") else None,
-            index=data.get("index"),
+            chunk_index=data.get("chunk_index"),
             tool_calls=[ToolCallDelta.from_dict(tc) for tc in data["tool_calls"]] if data.get("tool_calls") else None,
             tool_call_result=ToolCallResult.from_dict(data["tool_call_result"])
             if data.get("tool_call_result")

test/components/builders/test_answer_builder.py

@@ -186,7 +186,7 @@ def test_run_with_chat_message_replies_without_pattern(self):
 
         message_meta = {
             "model": "gpt-4o-mini",
-            "index": 0,
+            "chunk_index": 0,
             "finish_reason": "stop",
             "usage": {"prompt_tokens": 32, "completion_tokens": 153, "total_tokens": 185},
         }
@@ -210,7 +210,7 @@ def test_run_with_chat_message_replies_with_pattern(self):
 
         message_meta = {
             "model": "gpt-4o-mini",
-            "index": 0,
+            "chunk_index": 0,
             "finish_reason": "stop",
             "usage": {"prompt_tokens": 32, "completion_tokens": 153, "total_tokens": 185},
         }
@@ -232,7 +232,7 @@ def test_run_with_chat_message_replies_with_documents(self):
         component = AnswerBuilder(reference_pattern="\\[(\\d+)\\]")
         message_meta = {
             "model": "gpt-4o-mini",
-            "index": 0,
+            "chunk_index": 0,
             "finish_reason": "stop",
             "usage": {"prompt_tokens": 32, "completion_tokens": 153, "total_tokens": 185},
         }
@@ -263,7 +263,7 @@ def test_run_with_chat_message_replies_with_pattern_set_at_runtime(self):
         component = AnswerBuilder(pattern="unused pattern")
         message_meta = {
             "model": "gpt-4o-mini",
-            "index": 0,
+            "chunk_index": 0,
             "finish_reason": "stop",
             "usage": {"prompt_tokens": 32, "completion_tokens": 153, "total_tokens": 185},
         }
@@ -286,7 +286,7 @@ def test_run_with_chat_message_replies_with_meta_set_at_run_time(self):
         component = AnswerBuilder()
         message_meta = {
             "model": "gpt-4o-mini",
-            "index": 0,
+            "chunk_index": 0,
             "finish_reason": "stop",
             "usage": {"prompt_tokens": 32, "completion_tokens": 153, "total_tokens": 185},
         }
@@ -300,7 +300,7 @@ def test_run_with_chat_message_replies_with_meta_set_at_run_time(self):
         # Check metadata excluding all_messages
         expected_meta = {
             "model": "gpt-4o-mini",
-            "index": 0,
+            "chunk_index": 0,
             "finish_reason": "stop",
             "usage": {"prompt_tokens": 32, "completion_tokens": 153, "total_tokens": 185},
             "test": "meta",

test/components/generators/chat/test_hugging_face_api.py

@@ -588,7 +588,7 @@ def test_run_with_tools(self, mock_check_valid_model, tools):
         assert response["replies"][0].tool_calls[0].id == "0"
         assert response["replies"][0].meta == {
             "finish_reason": "tool_calls",
-            "index": 0,
+            "chunk_index": 0,
             "model": "meta-llama/Llama-3.1-70B-Instruct",
             "usage": {"completion_tokens": 30, "prompt_tokens": 426},
         }
@@ -675,14 +675,12 @@ def test_convert_hfapi_tool_calls_invalid_type_arguments(self):
                     model="microsoft/Phi-3.5-mini-instruct",
                     system_fingerprint="3.2.1-sha-4d28897",
                 ),
-                StreamingChunk(
-                    content=" Paris",
+                StreamingChunk(content=" Paris",
                     meta={
                         "received_at": "2025-05-27T12:14:28.228852",
                         "model": "microsoft/Phi-3.5-mini-instruct",
                         "finish_reason": None,
-                    },
-                    index=0,
+                    },chunk_index=0,
                     start=True,
                 ),
                 [],
@@ -1041,7 +1039,7 @@ async def test_run_async_with_tools(self, tools, mock_check_valid_model):
         assert response["replies"][0].tool_calls[0].id == "0"
         assert response["replies"][0].meta == {
             "finish_reason": "tool_calls",
-            "index": 0,
+            "chunk_index": 0,
             "model": "meta-llama/Llama-3.1-70B-Instruct",
             "usage": {"completion_tokens": 30, "prompt_tokens": 426},
         }