Module: Immutable Conversation

class diskurs.immutable_conversation.ImmutableConversation

Bases: Conversation

__init__(metadata=None, chat=None, prompt_argument=None, system_prompt=None, user_prompt=None, active_agent=None, conversation_id=None, conversation_store=None, final_result=None, longterm_memory=None)

Initialize an immutable conversation object.

Parameters:

  • metadata (dict[str, str | Enum] | None) – Optional metadata dictionary.

  • chat (list[ChatMessage] | None) – Chat history.

  • prompt_argument (GenericPromptArg | None) – Current prompt argument.

  • system_prompt (ChatMessage | None) – System prompt.

  • user_prompt (ChatMessage | list[ChatMessage] | None) – User prompt.

  • active_agent (str | None) – Name of the active agent.

  • conversation_id (str | None) – Unique conversation ID.

  • conversation_store (ConversationStore | None) – Conversation store for persistence.

  • final_result (dict[str, Any] | None) – Optional final result dictionary.

  • longterm_memory (LongtermMemory | None) – Global longterm memory for the conversation.

property active_agent

Returns the name of the agent currently processing the conversation.

This property indicates which agent is currently responsible for handling the conversation, which is important for routing and processing decisions.

Returns:

The name of the active agent.

append(message, role='', name='')

Appends a new chat message and returns a new instance of Conversation.

Parameters:

  • message (ChatMessage | list[ChatMessage]) – The ChatMessage object to be added to the conversation, alternatively a string can be provided.

  • role (Role | None) – Only needed if message is str, the role (system, user, assistant)

  • name (str | None) – Only needed if message is str, name of the agent

Returns:

A new instance of Conversation with the appended message.

Return type:

ImmutableConversation

property chat: list[ChatMessage]

Returns a deep copy of the chat history.

The chat history consists of all messages exchanged during the conversation, including messages from users, assistants, and system messages.

Returns:

A deep copy of the chat message list.

property conversation_id: str
conversation_store: ConversationStore | None
property final_result: dict[str, Any]

Retrieves the final result of the conversation.

The final result is a dictionary containing the data representing the outcome of the conversation. It is typically generated by the conductor agent when the conversation reaches a final state.

Returns:

The final result of the conversation if available, otherwise None.

classmethod from_dict(data, agents, longterm_memory_class=None, conversation_store=None)

Creates a Conversation instance from a dictionary representation.

This factory method reconstructs a conversation from a serialized dictionary representation, typically used when loading conversations from storage.

Parameters:

  • data (dict[str, Any]) – Dictionary containing the serialized conversation.

  • agents (list) – List of agent instances needed for context reconstruction.

  • longterm_memory_class (LongtermMemory | None) – The class of the longterm memory..

  • conversation_store (ConversationStore | None) – Optional store for persistence operations.

Returns:

A new Conversation instance.

Return type:

ImmutableConversation

get_agent_longterm_memory(agent_name)

Returns the global longterm memory. This method is maintained for backward compatibility.

Parameters:

agent_name (str) – Ignored in the new implementation

Returns:

Copy of the global longterm memory

Return type:

LongtermMemory

has_pending_tool_call()

Checks if there is a pending tool call in the conversation.

This method determines whether the last message in the conversation contains a tool call that needs to be executed before the conversation can continue.

Returns:

True if a tool call is pending, False otherwise.

has_pending_tool_response()

Checks if the conversation is awaiting a tool response.

This method determines whether the last message was a tool call from the LLM that needs to be responded to before the conversation can continue.

Returns:

True if awaiting a tool response, False otherwise.

Return type:

bool

is_empty()

Checks if the conversation’s chat history is empty.

Returns:

True if the chat history contains no messages, False otherwise.

Return type:

bool

property last_message: ChatMessage

Returns the last message in the chat history.

This is a convenience property for accessing the most recent message, which is often needed to determine the current state of the conversation.

Returns:

The last message in the chat history.

Raises:

IndexError if the chat history is empty.

property longterm_memory: LongtermMemory

Returns a copy of the global longterm memory.

Returns:

Copy of the global longterm memory

async maybe_persist()

Persists the conversation if a persistent conversation store is available and a conversation ID is set.

Return type:

None

property metadata: dict[str, str | Enum]

Returns a deep copy of the conversation metadata.

Metadata provides additional context about the conversation that isn’t part of the core conversation flow, such as user identifiers, session information, or processing flags.

Returns:

A deep copy of the metadata dictionary.

property prompt_argument: GenericPromptArg

Returns the current prompt argument.

The prompt argument is a structured dataclass containing the information required to render templates and process the conversation. It serves as a shared data structure between agents.

Returns:

The current prompt argument if available, otherwise None.

render_chat(message_type=MessageType.CONVERSATION)

Returns a rendered view of the complete chat history.

This method assembles the full chat stream for sending to an LLM, including the system prompt, chat history, and user prompt. It can filter messages based on the specified message type.

Parameters:

message_type (MessageType) – Filter for messages to include (default: CONVERSATION).

Returns:

List of ChatMessage objects representing the complete rendered chat.

Return type:

list[ChatMessage]

property system_prompt: ChatMessage

Returns the current system prompt.

The system prompt provides context and instructions to the LLM about how to process and respond to the conversation. It’s typically updated by each agent that processes the conversation.

Returns:

The current system prompt if available, otherwise None.

to_dict()

Converts the Conversation instance to a dictionary representation.

This method serializes the conversation into a dictionary structure that can be stored or transmitted, typically used when persisting conversations.

Returns:

Dictionary representation of the Conversation.

Return type:

dict[str, Any]

update(chat=None, prompt_argument=None, system_prompt=None, user_prompt=None, longterm_memory=None, metadata=None, active_agent=None, conversation_id=None)

Creates a new conversation with updated fields.

This method creates a new Conversation instance with specified fields updated, while preserving immutability of the original instance.

Parameters:

  • kwargs – Key-value pairs of fields to update (chat, prompt_argument, system_prompt, user_prompt, longterm_memory, metadata, active_agent, conversation_id).

  • chat (list[ChatMessage] | None)

  • prompt_argument (GenericPromptArg | None)

  • system_prompt (ChatMessage | None)

  • user_prompt (ChatMessage | list[ChatMessage] | None)

  • longterm_memory (LongtermMemory | None)

  • metadata (dict[str, str | Enum] | None)

  • active_agent (str | None)

  • conversation_id (str | None)

Returns:

A new Conversation instance with the updated fields.

Return type:

ImmutableConversation

update_agent_longterm_memory(agent_name, longterm_memory)

Updates the global longterm memory. This method is maintained for backward compatibility.

Parameters:

  • agent_name (str) – Ignored in the new implementation

  • longterm_memory (LongtermMemory) – The new longterm memory

Returns:

A new ImmutableConversation with updated longterm memory

Return type:

ImmutableConversation

update_longterm_memory(prompt_argument)

Updates the global longterm memory using values from a PromptArgument. Only fields of type OutputField in the PromptArgument will be copied to the LongtermMemory if they have matching names.

Parameters:

prompt_argument (GenericPromptArg) – The prompt argument to extract output fields from

Returns:

A new ImmutableConversation with updated longterm memory

Return type:

ImmutableConversation

property user_prompt: ChatMessage | list[ChatMessage]

Returns the current user prompt.

The user prompt represents the immediate query or input that needs to be addressed by the LLM. It’s typically updated by each agent that processes the conversation.

Returns:

The current user prompt if available, otherwise None.