Module haystack_experimental.dataclasses.chat_message

ChatRole

Enumeration representing the roles within a chat.

USER

The user role. A message from the user contains only text.

SYSTEM

The system role. A message from the system contains only text.

ASSISTANT

The assistant role. A message from the assistant can contain text and Tool calls. It can also store metadata.

TOOL

The tool role. A message from a tool contains the result of a Tool invocation.

ToolCall

Represents a Tool call prepared by the model, usually contained in an assistant message.

Arguments:

• id: The ID of the Tool call.
• tool_name: The name of the Tool to call.
• arguments: The arguments to call the Tool with.

id

noqa: A003

ToolCallResult

Represents the result of a Tool invocation.

Arguments:

• result: The result of the Tool invocation.
• origin: The Tool call that produced this result.
• error: Whether the Tool invocation resulted in an error.

TextContent

The textual content of a chat message.

Arguments:

• text: The text content of the message.

ChatMessage

Represents a message in a LLM chat conversation.

Arguments:

• content: The content of the message.
• role: The role of the entity sending the message.
• meta: Additional metadata associated with the message.

ChatMessage.role

@property
def role() -> ChatRole

Returns the role of the entity sending the message.

ChatMessage.meta

@property
def meta() -> Dict[str, Any]

Returns the metadata associated with the message.

ChatMessage.texts

@property
def texts() -> List[str]

Returns the list of all texts contained in the message.

ChatMessage.text

@property
def text() -> Optional[str]

Returns the first text contained in the message.

ChatMessage.tool_calls

@property
def tool_calls() -> List[ToolCall]

Returns the list of all Tool calls contained in the message.

ChatMessage.tool_call

@property
def tool_call() -> Optional[ToolCall]

Returns the first Tool call contained in the message.

ChatMessage.tool_call_results

@property
def tool_call_results() -> List[ToolCallResult]

Returns the list of all Tool call results contained in the message.

ChatMessage.tool_call_result

@property
def tool_call_result() -> Optional[ToolCallResult]

Returns the first Tool call result contained in the message.

ChatMessage.is_from

def is_from(role: ChatRole) -> bool

Check if the message is from a specific role.

Arguments:

• role: The role to check against.

Returns:

True if the message is from the specified role, False otherwise.

ChatMessage.from_user

@classmethod
def from_user(cls,
              text: str,
              meta: Optional[Dict[str, Any]] = None) -> "ChatMessage"

Create a message from the user.

Arguments:

• text: The text content of the message.
• meta: Additional metadata associated with the message.

Returns:

A new ChatMessage instance.

ChatMessage.from_system

@classmethod
def from_system(cls,
                text: str,
                meta: Optional[Dict[str, Any]] = None) -> "ChatMessage"

Create a message from the system.

Arguments:

• text: The text content of the message.
• meta: Additional metadata associated with the message.

Returns:

A new ChatMessage instance.

ChatMessage.from_assistant

@classmethod
def from_assistant(cls,
                   text: Optional[str] = None,
                   tool_calls: Optional[List[ToolCall]] = None,
                   meta: Optional[Dict[str, Any]] = None) -> "ChatMessage"

Create a message from the assistant.

Arguments:

• text: The text content of the message.
• tool_calls: The Tool calls to include in the message.
• meta: Additional metadata associated with the message.

Returns:

A new ChatMessage instance.

ChatMessage.from_tool

@classmethod
def from_tool(cls,
              tool_result: str,
              origin: ToolCall,
              error: bool = False,
              meta: Optional[Dict[str, Any]] = None) -> "ChatMessage"

Create a message from a Tool.

Arguments:

• tool_result: The result of the Tool invocation.
• origin: The Tool call that produced this result.
• error: Whether the Tool invocation resulted in an error.
• meta: Additional metadata associated with the message.

Returns:

A new ChatMessage instance.

ChatMessage.to_dict

def to_dict() -> Dict[str, Any]

Converts ChatMessage into a dictionary.

Returns:

Serialized version of the object.

ChatMessage.from_dict

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "ChatMessage"

Creates a new ChatMessage object from a dictionary.

Arguments:

• data: The dictionary to build the ChatMessage object.

Returns:

The created object.

Module haystack_experimental.dataclasses.tool

ToolInvocationError

Exception raised when a Tool invocation fails.

SchemaGenerationError

Exception raised when automatic schema generation fails.

Tool

Data class representing a tool for which Language Models can prepare a call.

Accurate definitions of the textual attributes such as name and description
are important for the Language Model to correctly prepare the call.

Arguments:

• name: Name of the tool.
• description: Description of the tool.
• parameters: A JSON schema defining the parameters expected by the tool.
• function: The function that will be invoked when the tool is called.

Tool.tool_spec

@property
def tool_spec() -> Dict[str, Any]

Return the tool specification to be used by the Language Model.

Tool.invoke

def invoke(**kwargs) -> Any

Invoke the tool with the provided keyword arguments.

Tool.to_dict

def to_dict() -> Dict[str, Any]

Serializes the Tool to a dictionary.

Returns:

Dictionary with serialized data.

Tool.from_dict

@classmethod
def from_dict(cls, data: Dict[str, Any]) -> "Tool"

Deserializes the Tool from a dictionary.

Arguments:

• data: Dictionary to deserialize from.

Returns:

Deserialized Tool.

Tool.from_function

@classmethod
def from_function(cls,
                  function: Callable,
                  name: Optional[str] = None,
                  description: Optional[str] = None) -> "Tool"

Create a Tool instance from a function.

Usage example:

from typing import Annotated, Literal
from haystack_experimental.dataclasses import Tool

def get_weather(
    city: Annotated[str, "the city for which to get the weather"] = "Munich",
    unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"):
    '''A simple function to get the current weather for a location.'''
    return f"Weather report for {city}: 20 {unit}, sunny"

tool = Tool.from_function(get_weather)

print(tool)
>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.',
>>> parameters={
>>> 'type': 'object',
>>> 'properties': {
>>>     'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'},
>>>     'unit': {
>>>         'type': 'string',
>>>         'enum': ['Celsius', 'Fahrenheit'],
>>>         'description': 'the unit for the temperature',
>>>         'default': 'Celsius',
>>>     },
>>>     }
>>> },
>>> function=<function get_weather at 0x7f7b3a8a9b80>)

Arguments:

• function: The function to be converted into a Tool.
  The function must include type hints for all parameters.
  If a parameter is annotated using typing.Annotated, its metadata will be used as parameter description.
• name: The name of the tool. If not provided, the name of the function will be used.
• description: The description of the tool. If not provided, the docstring of the function will be used.
  To intentionally leave the description empty, pass an empty string.

Raises:

• ValueError: If any parameter of the function lacks a type hint.
• SchemaGenerationError: If there is an error generating the JSON schema for the Tool.

Returns:

The Tool created from the function.

deserialize_tools_inplace

def deserialize_tools_inplace(data: Dict[str, Any], key: str = "tools")

Deserialize tools in a dictionary inplace.

Arguments:

• data: The dictionary with the serialized data.
• key: The key in the dictionary where the tools are stored.