core[minor]: Add utility code to create tool examples (#18602)

Co-authored-by: Chester Curme <chester.curme@gmail.com>

libs/core/tests/unit_tests/utils/test_function_calling.py

@@ -2,9 +2,13 @@ from typing import Any, Callable, Dict, List, Literal, Optional, Type
 
 import pytest
 
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
 from langchain_core.pydantic_v1 import BaseModel, Field
 from langchain_core.tools import BaseTool, tool
-from langchain_core.utils.function_calling import convert_to_openai_function
+from langchain_core.utils.function_calling import (
+    convert_to_openai_function,
+    tool_example_to_messages,
+)
 
 
 @pytest.fixture()
@@ -109,3 +113,74 @@ def test_function_optional_param() -> None:
     func = convert_to_openai_function(func5)
     req = func["parameters"]["required"]
     assert set(req) == {"b"}
+
+
+class FakeCall(BaseModel):
+    data: str
+
+
+def test_valid_example_conversion() -> None:
+    expected_messages = [
+        HumanMessage(content="This is a valid example"),
+        AIMessage(content="", additional_kwargs={"tool_calls": []}),
+    ]
+    assert (
+        tool_example_to_messages(input="This is a valid example", tool_calls=[])
+        == expected_messages
+    )
+
+
+def test_multiple_tool_calls() -> None:
+    messages = tool_example_to_messages(
+        input="This is an example",
+        tool_calls=[
+            FakeCall(data="ToolCall1"),
+            FakeCall(data="ToolCall2"),
+            FakeCall(data="ToolCall3"),
+        ],
+    )
+    assert len(messages) == 5
+    assert isinstance(messages[0], HumanMessage)
+    assert isinstance(messages[1], AIMessage)
+    assert isinstance(messages[2], ToolMessage)
+    assert isinstance(messages[3], ToolMessage)
+    assert isinstance(messages[4], ToolMessage)
+    assert messages[1].additional_kwargs["tool_calls"] == [
+        {
+            "id": messages[2].tool_call_id,
+            "type": "function",
+            "function": {"name": "FakeCall", "arguments": '{"data": "ToolCall1"}'},
+        },
+        {
+            "id": messages[3].tool_call_id,
+            "type": "function",
+            "function": {"name": "FakeCall", "arguments": '{"data": "ToolCall2"}'},
+        },
+        {
+            "id": messages[4].tool_call_id,
+            "type": "function",
+            "function": {"name": "FakeCall", "arguments": '{"data": "ToolCall3"}'},
+        },
+    ]
+
+
+def test_tool_outputs() -> None:
+    messages = tool_example_to_messages(
+        input="This is an example",
+        tool_calls=[
+            FakeCall(data="ToolCall1"),
+        ],
+        tool_outputs=["Output1"],
+    )
+    assert len(messages) == 3
+    assert isinstance(messages[0], HumanMessage)
+    assert isinstance(messages[1], AIMessage)
+    assert isinstance(messages[2], ToolMessage)
+    assert messages[1].additional_kwargs["tool_calls"] == [
+        {
+            "id": messages[2].tool_call_id,
+            "type": "function",
+            "function": {"name": "FakeCall", "arguments": '{"data": "ToolCall1"}'},
+        },
+    ]
+    assert messages[2].content == "Output1"