LangChain Message Conversion with tool_example_to_messages

When working with LLMs and chat models in LangChain, you might need to convert examples containing tool calls into a format that the model can understand. The tool_example_to_messages utility helps you transform tool examples into a sequence of chat messages that can be used for training or fine-tuning chat models.

What is tool_example_to_messages?

tool_example_to_messages is a utility function that converts a single example containing user input and tool calls into a structured sequence of chat messages. This is particularly useful when you need to:

• Convert extraction examples into chat format
• Prepare training data for chat models
• Create sequences of interactions involving tool calls

Reference

Here are the key parameters and return values for tool_example_to_messages:

Returns a list of BaseMessage objects containing:

1. HumanMessage with the original input
2. AIMessage with the extracted information
3. ToolMessage confirming the tool request

How to use tool_example_to_messages

Let's look at some practical examples of using this utility.

Basic Example with Person Information Extraction

Here's how to convert examples that extract person information into chat messages:

from typing import Optional
from pydantic import BaseModel, Field
from langchain_core.utils import tool_example_to_messages

# Define a Pydantic model for person information
class Person(BaseModel):
    name: Optional[str] = Field(None, description="The person's name")
    hair_color: Optional[str] = Field(None, description="The person's hair color")
    height_in_meters: Optional[str] = Field(None, description="Height in meters")

# Create example data
example_input = "Sarah has blonde hair and is 1.75 meters tall."
tool_call = Person(
    name="Sarah",
    hair_color="blonde",
    height_in_meters="1.75"
)

# Convert to messages
messages = tool_example_to_messages(example_input, [tool_call])

# Each message in the sequence represents a step in the conversation
for message in messages:
    print(f"Message type: {message.__class__.__name__}")
    print(f"Content: {message.content}")
    print("---")

Batch Processing Multiple Examples

You can also process multiple examples in batch:

# Define multiple examples
examples = [
    (
        "The ocean is vast and blue.",
        Person(name=None, height_in_meters=None, hair_color=None),
    ),
    (
        "John has brown hair.",
        Person(name="John", height_in_meters=None, hair_color="brown"),
    ),
]

# Process all examples
all_messages = []
for text, tool_call in examples:
    messages = tool_example_to_messages(text, [tool_call])
    all_messages.extend(messages)

Including Tool Outputs

You can optionally provide tool outputs when converting examples:

input_text = "Process information about Mark"
tool_call = Person(name="Mark", height_in_meters="1.80", hair_color=None)
tool_outputs = ["Successfully extracted information about Mark"]

messages = tool_example_to_messages(
    input_text,
    [tool_call],
    tool_outputs=tool_outputs
)

Use Cases and Best Practices

1. Training Data Preparation

   • Use this utility when preparing examples for fine-tuning chat models
   • Ensure your Pydantic models accurately represent the information you want to extract

2. Information Extraction

   • Useful for converting structured extraction tasks into chat format
   • Helps maintain consistency in message format across your application

3. Tool Call Processing

   • When working with tools or functions that need to be called by the model
   • Useful for creating examples of successful tool interactions

Remember that this utility is particularly helpful when working with chat models that are optimized for agent-like interactions, as it maintains the expected message structure these models expect.