Module: Heuristic Agent

class diskurs.heuristic_agent.HeuristicAgent

Bases: BaseAgent[HeuristicPrompt]

__init__(name, prompt, llm_client=None, topics=None, dispatcher=None, tools=None, tool_executor=None, max_trials=5, init_prompt_arguments_with_longterm_memory=True, render_prompt=True, final_properties=None)
Parameters:
async compute_tool_response(response)

Executes the tool calls in the response and returns the tool responses.

Parameters:

response (Conversation) – The conversation object containing the tool calls to execute.

Returns:

One or more ChatMessage objects containing the tool responses.

Return type:

list[ChatMessage]

classmethod create(name, prompt, **kwargs)
Parameters:
Return type:

Self

async generate_validated_response(conversation, message_type=MessageType.CONVERSATION)

Generates a validated response for the given conversation.

This method attempts to generate a valid response for the conversation by interacting with the LLM client and validating the response. It performs multiple trials if necessary, and handles tool calls and corrective messages.

Parameters:

  • conversation (Conversation) – The conversation object to generate a response for.

  • message_type (MessageType) – The type of message to render the user prompt as, defaults to MessageType.CONVERSATION.

Returns:

The updated conversation object with the validated response.

Return type:

Conversation

async handle_tool_call(conversation, response)

This method handles a tool call by executing the tool and updating the conversation with the tool response.

Parameters:

  • conversation – The conversation object to add the result to.

  • response – The response object containing the tool call to handle.

Returns:

The updated conversation object with the tool response.

async invoke(conversation, message_type=MessageType.CONVERSATION, reset_prompt=True)

Run the agent on a conversation.

This method processes the given conversation by invoking the agent’s logic. It takes a Conversation object representing the conversation and returns an updated Conversation object after processing.

Parameters:

  • conversation (Conversation) – The current state of the conversation, represented as a Conversation object

  • message_type – The type of message to use when rendering templates and processing the conversation

  • init_prompt – Whether to initialize the prompt before processing the conversation

Returns:

An updated Conversation object with the processed state.

Return type:

Conversation

name: str
async process_conversation(conversation)

Receives a conversation from the dispatcher, i.e. message bus, processes it and finally publishes a deep copy of the resulting conversation back to the dispatcher.

Parameters:

conversation (Conversation) – The conversation object to process.

Return type:

None

register_dispatcher(dispatcher)

Register a dispatcher with the agent.

Parameters:

dispatcher (ConversationDispatcher) – The dispatcher to register

Return type:

None

register_tools(tools)

Register tools with the agent.

Parameters:

tools (list[Callable] | Callable) – A list of callables or a single callable to register as tools

Return type:

None

return_fail_validation_message(response)

Returns a fail validation message when max trials are exhausted.

Parameters:

response – The conversation to add the fail message to

Returns:

The updated conversation with the fail message

property topics: list[str]
class diskurs.heuristic_agent.HeuristicAgentFinalizer

Bases: HeuristicAgent, FinalizerMixin

__init__(**kwargs)
async compute_tool_response(response)

Executes the tool calls in the response and returns the tool responses.

Parameters:

response (Conversation) – The conversation object containing the tool calls to execute.

Returns:

One or more ChatMessage objects containing the tool responses.

Return type:

list[ChatMessage]

classmethod create(name, prompt, **kwargs)
Parameters:
Return type:

Self

final_properties: list[str]
async finalize_conversation(conversation)

Finalize the conversation by invoking the agent and extracting final properties.

Parameters:

conversation (Conversation) – The conversation to finalize

Return type:

None

async generate_validated_response(conversation, message_type=MessageType.CONVERSATION)

Generates a validated response for the given conversation.

This method attempts to generate a valid response for the conversation by interacting with the LLM client and validating the response. It performs multiple trials if necessary, and handles tool calls and corrective messages.

Parameters:

  • conversation (Conversation) – The conversation object to generate a response for.

  • message_type (MessageType) – The type of message to render the user prompt as, defaults to MessageType.CONVERSATION.

Returns:

The updated conversation object with the validated response.

Return type:

Conversation

async handle_tool_call(conversation, response)

This method handles a tool call by executing the tool and updating the conversation with the tool response.

Parameters:

  • conversation – The conversation object to add the result to.

  • response – The response object containing the tool call to handle.

Returns:

The updated conversation object with the tool response.

async invoke(conversation, message_type=MessageType.CONVERSATION, reset_prompt=True)

Run the agent on a conversation.

This method processes the given conversation by invoking the agent’s logic. It takes a Conversation object representing the conversation and returns an updated Conversation object after processing.

Parameters:

  • conversation (Conversation) – The current state of the conversation, represented as a Conversation object

  • message_type – The type of message to use when rendering templates and processing the conversation

  • init_prompt – Whether to initialize the prompt before processing the conversation

Returns:

An updated Conversation object with the processed state.

Return type:

Conversation

name: str
async process_conversation(conversation)

Receives a conversation from the dispatcher, i.e. message bus, processes it and finally publishes a deep copy of the resulting conversation back to the dispatcher.

Parameters:

conversation (Conversation) – The conversation object to process.

Return type:

None

register_dispatcher(dispatcher)

Register a dispatcher with the agent.

Parameters:

dispatcher (ConversationDispatcher) – The dispatcher to register

Return type:

None

register_tools(tools)

Register tools with the agent.

Parameters:

tools (list[Callable] | Callable) – A list of callables or a single callable to register as tools

Return type:

None

return_fail_validation_message(response)

Returns a fail validation message when max trials are exhausted.

Parameters:

response – The conversation to add the fail message to

Returns:

The updated conversation with the fail message

property topics: list[str]