ChatHistory Class

This class holds the history of chat messages from a chat conversation.

Note: the constructor takes a system_message parameter, which is not part of the class definition. This is to allow the system_message to be passed in as a keyword argument, but not be part of the class definition.

Initializes a new instance of the ChatHistory class.

Optionally incorporating a message and/or a system message at the beginning of the chat history.

This constructor allows for flexible initialization with chat messages and an optional messages or a system message. If both 'messages' (a list of ChatMessageContent instances) and 'system_message' are provided, the 'system_message' is prepended to the list of messages, ensuring it appears as the first message in the history. If only 'system_message' is provided without any 'messages', the chat history is initialized with the 'system_message' as its first item. If 'messages' are provided without a 'system_message', the chat history is initialized with the provided messages as is.

Note: The 'system_message' is not retained as part of the class's attributes; it's used during initialization and then discarded. The rest of the keyword arguments are passed to the superclass constructor and handled according to the Pydantic model's behavior.

Inheritance

KernelBaseModel

ChatHistory

Constructor

ChatHistory(*, messages: list[ChatMessageContent])

Parameters

Name	Description
**data Required	Arbitrary keyword arguments. The constructor looks for two optional keys: 'messages': Optional[List[ChatMessageContent]], a list of chat messages to include in the history. 'system_message' Optional[str]: An optional string representing a system-generated message to be included at the start of the chat history.

Keyword-Only Parameters

Name	Description
messages Required

Methods

add_assistant_message	Add an assistant message to the chat history.
add_assistant_message_list	Add an assistant message to the chat history.
add_assistant_message_str	Add an assistant message to the chat history.
add_message	Add a message to the history. This method accepts either a ChatMessageContent instance or a dictionary with the necessary information to construct a ChatMessageContent instance.
add_system_message	Add a system message to the chat history.
add_system_message_list	Add a system message to the chat history.
add_system_message_str	Add a system message to the chat history.
add_tool_message	Add a tool message to the chat history.
add_tool_message_list	Add a tool message to the chat history.
add_tool_message_str	Add a tool message to the chat history.
add_user_message	Add a user message to the chat history.
add_user_message_list	Add a user message to the chat history.
add_user_message_str	Add a user message to the chat history.
from_rendered_prompt	Create a ChatHistory instance from a rendered prompt.
load_chat_history_from_file	Loads the ChatHistory from a file.
remove_message	Remove a message from the history.
restore_chat_history	Restores a ChatHistory instance from a JSON string.
serialize	Serializes the ChatHistory instance to a JSON string.
store_chat_history_to_file	Stores the serialized ChatHistory to a file.
to_prompt	Return a string representation of the history.

add_assistant_message

Add an assistant message to the chat history.

add_assistant_message(content: str | list[KernelContent], **kwargs: Any) -> None

add_assistant_message_list

Add an assistant message to the chat history.

add_assistant_message_list(content: list[KernelContent], **kwargs: Any) -> None

Parameters

Name	Description
content Required

add_assistant_message_str

Add an assistant message to the chat history.

add_assistant_message_str(content: str, **kwargs: Any) -> None

Parameters

Name	Description
content Required

add_message

Add a message to the history.

This method accepts either a ChatMessageContent instance or a dictionary with the necessary information to construct a ChatMessageContent instance.

add_message(message: ChatMessageContent | dict[str, Any], encoding: str | None = None, metadata: dict[str, Any] | None = None) -> None

Parameters

Name	Description
message Required	<xref:Union>[<xref:ChatMessageContent>,dict] The message to add, either as a pre-constructed ChatMessageContent instance or a dictionary specifying 'role' and 'content'.
encoding	<xref:Optional>[str] The encoding of the message. Required if 'message' is a dict. Default value: None
metadata	<xref:Optional>[dict[str,<xref: Any>]] Any metadata to attach to the message. Required if 'message' is a dict. Default value: None

add_system_message

Add a system message to the chat history.

add_system_message(content: str | list[KernelContent], **kwargs) -> None

add_system_message_list

Add a system message to the chat history.

add_system_message_list(content: list[KernelContent], **kwargs: Any) -> None

Parameters

Name	Description
content Required

add_system_message_str

Add a system message to the chat history.

add_system_message_str(content: str, **kwargs: Any) -> None

Parameters

Name	Description
content Required

add_tool_message

Add a tool message to the chat history.

add_tool_message(content: str | list[KernelContent], **kwargs: Any) -> None

add_tool_message_list

Add a tool message to the chat history.

add_tool_message_list(content: list[KernelContent], **kwargs: Any) -> None

Parameters

Name	Description
content Required

add_tool_message_str

Add a tool message to the chat history.

add_tool_message_str(content: str, **kwargs: Any) -> None

Parameters

Name	Description
content Required

add_user_message

Add a user message to the chat history.

add_user_message(content: str | list[KernelContent], **kwargs: Any) -> None

add_user_message_list

Add a user message to the chat history.

add_user_message_list(content: list[KernelContent], **kwargs: Any) -> None

Parameters

Name	Description
content Required

add_user_message_str

Add a user message to the chat history.

add_user_message_str(content: str, **kwargs: Any) -> None

Parameters

Name	Description
content Required

from_rendered_prompt

Create a ChatHistory instance from a rendered prompt.

from_rendered_prompt(rendered_prompt: str) -> ChatHistory

Parameters

Name	Description
rendered_prompt Required	str The rendered prompt to convert to a ChatHistory instance.

Returns

Type	Description
ChatHistory	The ChatHistory instance created from the rendered prompt.

load_chat_history_from_file

Loads the ChatHistory from a file.

load_chat_history_from_file(file_path: str) -> ChatHistory

Parameters

Name	Description
file_path Required	str The path to the file from which to load the ChatHistory.

Returns

Type	Description
ChatHistory	The deserialized ChatHistory instance.

remove_message

Remove a message from the history.

remove_message(message: ChatMessageContent) -> bool

Parameters

Name	Description
message Required	<xref:semantic_kernel.contents.chat_history.ChatMessageContent> The message to remove.

Returns

Type	Description
bool	True if the message was removed, False if the message was not found.

restore_chat_history

Restores a ChatHistory instance from a JSON string.

restore_chat_history(chat_history_json: str) -> ChatHistory

Parameters

Name	Description
chat_history_json Required	str The JSON string to deserialize into a ChatHistory instance.

Returns

Type	Description
ChatHistory	The deserialized ChatHistory instance.

Exceptions

Type	Description
ValueError	If the JSON string is invalid or the deserialized data fails validation.

serialize

Serializes the ChatHistory instance to a JSON string.

serialize() -> str

Returns

Type	Description
str	A JSON string representation of the ChatHistory instance.

Exceptions

Type	Description
ValueError	If the ChatHistory instance cannot be serialized to JSON.

store_chat_history_to_file

Stores the serialized ChatHistory to a file.

store_chat_history_to_file(file_path: str) -> None

Parameters

Name	Description
file_path Required	str The path to the file where the serialized data will be stored.

to_prompt

Return a string representation of the history.

to_prompt() -> str

Attributes

model_computed_fields

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'populate_by_name': True, 'validate_assignment': True}

model_fields

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.fields from Pydantic V1.

model_fields: ClassVar[Dict[str, FieldInfo]] = {'messages': FieldInfo(annotation=list[ChatMessageContent], required=True)}

messages

The list of chat messages in the history.

messages: list[ChatMessageContent]