DocumentationAPI Reference📓 Tutorials🧑‍🍳 Cookbook🤝 Integrations💜 Discord🎨 Studio
API Reference

Data Classes

Core classes that carry data through the system.

Module answer

ExtractedAnswer

ExtractedAnswer.to_dict

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

Serialize the object to a dictionary.

Returns:

Serialized dictionary representation of the object.

ExtractedAnswer.from_dict

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

Deserialize the object from a dictionary.

Arguments:

  • data: Dictionary representation of the object.

Returns:

Deserialized object.

ExtractedTableAnswer

ExtractedTableAnswer.to_dict

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

Serialize the object to a dictionary.

Returns:

Serialized dictionary representation of the object.

ExtractedTableAnswer.from_dict

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

Deserialize the object from a dictionary.

Arguments:

  • data: Dictionary representation of the object.

Returns:

Deserialized object.

GeneratedAnswer

GeneratedAnswer.to_dict

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

Serialize the object to a dictionary.

Returns:

Serialized dictionary representation of the object.

GeneratedAnswer.from_dict

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

Deserialize the object from a dictionary.

Arguments:

  • data: Dictionary representation of the object.

Returns:

Deserialized object.

Module byte_stream

ByteStream

Base data class representing a binary object in the Haystack API.

ByteStream.to_file

def to_file(destination_path: Path)

Write the ByteStream to a file. Note: the metadata will be lost.

Arguments:

  • destination_path: The path to write the ByteStream to.

ByteStream.from_file_path

@classmethod
def from_file_path(cls,
                   filepath: Path,
                   mime_type: Optional[str] = None,
                   meta: Optional[Dict[str, Any]] = None) -> "ByteStream"

Create a ByteStream from the contents read from a file.

Arguments:

  • filepath: A valid path to a file.
  • mime_type: The mime type of the file.
  • meta: Additional metadata to be stored with the ByteStream.

ByteStream.from_string

@classmethod
def from_string(cls,
                text: str,
                encoding: str = "utf-8",
                mime_type: Optional[str] = None,
                meta: Optional[Dict[str, Any]] = None) -> "ByteStream"

Create a ByteStream encoding a string.

Arguments:

  • text: The string to encode
  • encoding: The encoding used to convert the string into bytes
  • mime_type: The mime type of the file.
  • meta: Additional metadata to be stored with the ByteStream.

ByteStream.to_string

def to_string(encoding: str = "utf-8") -> str

Convert the ByteStream to a string, metadata will not be included.

Arguments:

  • encoding: The encoding used to convert the bytes to a string. Defaults to "utf-8".

Raises:

  • None: UnicodeDecodeError: If the ByteStream data cannot be decoded with the specified encoding.

Returns:

The string representation of the ByteStream.

ByteStream.__repr__

def __repr__() -> str

Return a string representation of the ByteStream, truncating the data to 100 bytes.

Module 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.

FUNCTION

The function role. Deprecated in favor of TOOL.

ChatRole.from_str

@staticmethod
def from_str(string: str) -> "ChatRole"

Convert a string to a ChatRole enum.

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.

Use the from_assistant, from_user, from_system, and from_tool class methods to create a ChatMessage.

ChatMessage.__new__

def __new__(cls, *args, **kwargs)

This method is reimplemented to make the changes to the ChatMessage dataclass more visible.

ChatMessage.__getattribute__

def __getattribute__(name)

This method is reimplemented to make the content attribute removal more visible.

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.name

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

Returns the name 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: Union[ChatRole, str]) -> 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,
              name: Optional[str] = None) -> "ChatMessage"

Create a message from the user.

Arguments:

  • text: The text content of the message.
  • meta: Additional metadata associated with the message.
  • name: An optional name for the participant. This field is only supported by OpenAI.

Returns:

A new ChatMessage instance.

ChatMessage.from_system

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

Create a message from the system.

Arguments:

  • text: The text content of the message.
  • meta: Additional metadata associated with the message.
  • name: An optional name for the participant. This field is only supported by OpenAI.

Returns:

A new ChatMessage instance.

ChatMessage.from_assistant

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

Create a message from the assistant.

Arguments:

  • text: The text content of the message.
  • meta: Additional metadata associated with the message.
  • tool_calls: The Tool calls to include in the message.
  • name: An optional name for the participant. This field is only supported by OpenAI.

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.from_function

@classmethod
def from_function(cls, content: str, name: str) -> "ChatMessage"

Create a message from a function call. Deprecated in favor of from_tool.

Arguments:

  • content: The text content of the message.
  • name: The name of the function being called.

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.

ChatMessage.to_openai_dict_format

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

Convert a ChatMessage to the dictionary format expected by OpenAI's Chat API.

ChatMessage.from_openai_dict_format

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

Create a ChatMessage from a dictionary in the format expected by OpenAI's Chat API.

NOTE: While OpenAI's API requires tool_call_id in both tool calls and tool messages, this method accepts messages without it to support shallow OpenAI-compatible APIs. If you plan to use the resulting ChatMessage with OpenAI, you must include tool_call_id or you'll encounter validation errors.

Arguments:

  • message: The OpenAI dictionary to build the ChatMessage object.

Raises:

  • ValueError: If the message dictionary is missing required fields.

Returns:

The created ChatMessage object.

Module document

_BackwardCompatible

Metaclass that handles Document backward compatibility.

_BackwardCompatible.__call__

def __call__(cls, *args, **kwargs)

Called before Document.init, will remap legacy fields to new ones.

Also handles building a Document from a flattened dictionary.

Document

Base data class containing some data to be queried.

Can contain text snippets, tables, and file paths to images or audios. Documents can be sorted by score and saved to/from dictionary and JSON.

Arguments:

  • id: Unique identifier for the document. When not set, it's generated based on the Document fields' values.
  • content: Text of the document, if the document contains text.
  • dataframe: Pandas dataframe with the document's content, if the document contains tabular data.
  • blob: Binary data associated with the document, if the document has any binary data associated with it.
  • meta: Additional custom metadata for the document. Must be JSON-serializable.
  • score: Score of the document. Used for ranking, usually assigned by retrievers.
  • embedding: dense vector representation of the document.
  • sparse_embedding: sparse vector representation of the document.

Document.__eq__

def __eq__(other)

Compares Documents for equality.

Two Documents are considered equals if their dictionary representation is identical.

Document.__post_init__

def __post_init__()

Generate the ID based on the init parameters.

Document.to_dict

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

Converts Document into a dictionary.

dataframe and blob fields are converted to JSON-serializable types.

Arguments:

  • flatten: Whether to flatten meta field or not. Defaults to True to be backward-compatible with Haystack 1.x.

Document.from_dict

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

Creates a new Document object from a dictionary.

The dataframe and blob fields are converted to their original types.

Document.content_type

@property
def content_type()

Returns the type of the content for the document.

This is necessary to keep backward compatibility with 1.x.

Raises:

  • ValueError: If both text and dataframe fields are set or both are missing.

Module streaming_chunk

StreamingChunk

The StreamingChunk class encapsulates a segment of streamed content along with associated metadata.

This structure facilitates the handling and processing of streamed data in a systematic manner.

Arguments:

  • content: The content of the message chunk as a string.
  • meta: A dictionary containing metadata related to the message chunk.

Module sparse_embedding

SparseEmbedding

Class representing a sparse embedding.

Arguments:

  • indices: List of indices of non-zero elements in the embedding.
  • values: List of values of non-zero elements in the embedding.

SparseEmbedding.__post_init__

def __post_init__()

Checks if the indices and values lists are of the same length.

Raises a ValueError if they are not.

SparseEmbedding.to_dict

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

Convert the SparseEmbedding object to a dictionary.

Returns:

Serialized sparse embedding.

SparseEmbedding.from_dict

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

Deserializes the sparse embedding from a dictionary.

Arguments:

  • sparse_embedding_dict: Dictionary to deserialize from.

Returns:

Deserialized sparse embedding.