Skip to content

AI Interfaces

For end-users

This section is addressed to end-users who want to use the AI interfaces.

If you are a developer who wants to extend the AI interfaces, please refer to the Base AI interface section.

The AI interfaces are the classes that handle a conversation between the Agent and the LLM. Here, conversation can mean a single turn, or multiple turns. This abstracted away by the run and arun methods: you just need to pass a list of messages, and the AI interface will take care of the rest.

Ultimately, the AI interface will return an AIInterfacePayload object, which contains the response from the LLM, the cost, and the finish reason. Through its result attribute, it can also contain a specific structured output schema.

Why is this useful?

When we need to create an Agent that executes a Task in multiple steps, we need to use two different prompts. For instance, you might want to start by planning the steps of the task, and then execute them one by one. This requires two different prompts; this is where the AI interfaces come in handy.

In this section, we will see the pre-loaded AI interfaces that come with Conatus:

If you need to create your own AI interface, you can extend the BaseAIInterface class. For more information, see the Base AI interface API section, or the How-to on custom AI interfaces section.

conatus.agents.ai_interfaces.plain.PlainAIInterface 

PlainAIInterface(
    *,
    user_prompt: str,
    system_prompt: str | None = None,
    output_schema: type[Result] | None = None,
    task_config: ConsolidatedTaskConfig | None = None,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    interface_name: str | None = None,
    max_turns: int | None = None,
    actions: (
        Collection[Action]
        | Sequence[RawAction]
        | ActionStarterPack
        | None
    ) = None,
    stop_if_no_tool_calls: bool = True,
    **kwargs: ParamType
)

Bases: BaseAIInterface[Result]

An AI interface designed for very simple interactions.

The main distinction of this AI interface is that all it takes is a user_prompt and optionally a system_prompt. You can also pass an output_schema, which will be used to validate the output of the AI interface.

from dataclasses import dataclass
from conatus.agents.ai_interfaces.plain import PlainAIInterface

@dataclass
class Macros:
    calories: int
    protein: float
    carbs: float
    fat: float

food_items = ["slice of pizza", "pot of yogurt", "ounce of cheese"]
for item in food_items:
    ai_interface = PlainAIInterface(
        user_prompt=f"What are (roughly) the macros for {item}?",
        output_schema=Macros,
        model_type="reasoning",
    )
    payload = ai_interface.run()
    print(f"{item}: {payload.result}")
# > slice of pizza: Macros(calories=285, protein=12.0, carbs=36.0, fat=10.0)
# > pot of yogurt: Macros(calories=100, protein=6.0, carbs=12.0, fat=2.0)
# > ounce of cheese: Macros(calories=110, protein=7.0, carbs=1.0, fat=9.0)
PARAMETER DESCRIPTION
user_prompt

The user prompt for the AI interface.

TYPE: str

system_prompt

The system prompt for the AI interface.

TYPE: str | None DEFAULT: None

output_schema

The output schema for the AI interface.

TYPE: type[Result] | None DEFAULT: None

task_config

The task configuration for the AI interface.

TYPE: ConsolidatedTaskConfig | None DEFAULT: None

run_writer

The writer used to log run information.

TYPE: FileWriter | None DEFAULT: None

model_config

The configuration for the model.

TYPE: ModelConfig | ModelConfigTD | None DEFAULT: None

model_type

The type of model to use for the AI interface. If None, we will attempt to retrieve it from a class attribute.

TYPE: ModelType | None DEFAULT: None

interface_name

The name of the AI interface. Will otherwise be the snake case of the class name.

TYPE: str | None DEFAULT: None

actions

The actions to use for the AI interface.

TYPE: Collection[Action] | Sequence[RawAction] | ActionStarterPack | None DEFAULT: None

max_turns

The maximum number of turns the AI interface can take. Defaults to 1, but can be overridden by the subclass or the user in the constructor.

TYPE: int | None DEFAULT: None

stop_if_no_tool_calls

Whether to stop the run if no tool calls are made. Defaults to True.

TYPE: bool DEFAULT: True

kwargs

Additional parameters for the AI interface.

TYPE: ParamType DEFAULT: {}

Source code in conatus/agents/ai_interfaces/plain.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
def __init__(  # noqa: PLR0913
    self,
    *,
    user_prompt: str,
    system_prompt: str | None = None,
    output_schema: type[Result] | None = None,
    task_config: ConsolidatedTaskConfig | None = None,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    interface_name: str | None = None,
    max_turns: int | None = None,
    actions: Collection[Action]
    | Sequence[RawAction]
    | ActionStarterPack
    | None = None,
    stop_if_no_tool_calls: bool = True,
    **kwargs: ParamType,
) -> None:
    """Initialize the AI interface.

    Args:
        user_prompt: The user prompt for the AI interface.
        system_prompt: The system prompt for the AI interface.
        output_schema: The output schema for the AI interface.
        task_config: The task configuration for the AI interface.
        run_writer: The writer used to log run information.
        model_config: The configuration for the model.
        model_type: The type of model to use for the AI interface. If
            `None`, we will attempt to retrieve it from a class attribute.
        interface_name: The name of the AI interface. Will otherwise be
            the snake case of the class name.
        actions: The actions to use for the AI interface.
        max_turns: The maximum number of turns the AI interface can take.
            Defaults to 1, but can be overridden by the subclass or the
            user in the constructor.
        stop_if_no_tool_calls: Whether to stop the run if no tool calls are
            made. Defaults to `True`.
        kwargs: Additional parameters for the AI interface.
    """
    super().__init__(
        task_config=task_config,
        run_writer=run_writer,
        model_config=model_config,
        model_type=model_type,
        interface_name=interface_name,
        max_turns=max_turns,
        runtime=None,
        actions=actions,
        computer_use_mode=None,
        only_keep_one_computer_use_environment=None,
        stop_if_no_tool_calls=stop_if_no_tool_calls,
        hide_runtime_from_ai=True,
        **kwargs,
    )
    self.user_prompt = user_prompt
    self.system_prompt = system_prompt
    self.output_schema = output_schema

arun async 

arun(
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None,
) -> AIInterfacePayload[Result]

Run the AI interface asynchronously.

For more information, see BaseAIInterface.run .

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The response from the AI interface.
Source code in conatus/agents/ai_interfaces/base.py 
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
async def arun(
    self,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface asynchronously.

    For more information, see [`BaseAIInterface.run`
    ][conatus.agents.ai_interfaces.base.BaseAIInterface.run].

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The response from the AI interface.
    """
    logger.debug("Running interface %s", self.interface_name)
    response: AIResponse[Result] | AIResponse | None = None
    prompt: AIPrompt[Result] | AIPrompt | None = None
    self.conversation_history = list(conversation_history)
    self.conversation_history_id = conversation_history_id
    self.system_message = conversation_history_system_message
    prompt, response = await self._run_first_turn(
        conversation_history=self.conversation_history,
        conversation_history_id=self.conversation_history_id,
        conversation_history_system_message=self.system_message,
    )
    while self.should_continue(response=response):
        new_messages = await self.make_new_messages(response=response)
        self.conversation_history.extend(new_messages)
        prompt, response = await self._run_new_turn(
            previous_response=response,
            new_messages=new_messages,
        )

    return AIInterfacePayload[Result](
        cost=self.cost,
        finish_reason=self.finish_reason,
        result=self.extract_result(
            latest_response=response,
            latest_prompt=prompt,
            finish_reason=self.finish_reason,
        ),
        response=response,
        state=self.runtime.state,
    )

run 

run(
    *,
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None
) -> AIInterfacePayload[Result]

Run the AI interface.

This method abstracts away the logic of interacting with the AI models, and returns a AIInterfacePayload from which the Agent can extract the result, the cost of the interactions, etc.

If the user wishes to include a previous conversation, they can provide a list of ConversationAIMessage objects, and / or a string that will identify the conversation.

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The payload of the run.
Source code in conatus/agents/ai_interfaces/base.py 
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def run(
    self,
    *,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface.

    This method abstracts away the logic of interacting with the
    [AI models][conatus.models.base.BaseAIModel], and returns a
    [`AIInterfacePayload`][conatus.agents.ai_interfaces.base.AIInterfacePayload]
    from which the [`Agent`][conatus.agents.base.Agent] can extract
    the result, the cost of the interactions, etc.

    If the user wishes to include a previous conversation, they can
    provide a list of [`ConversationAIMessage`
    ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
    objects, and / or a string that will identify the conversation.

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The payload of the run.
    """
    return run_async(
        self.arun(
            conversation_history,
            conversation_history_id,
            conversation_history_system_message,
        )
    )

conatus.agents.ai_interfaces.react.ReactAIInterface 

ReactAIInterface(
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool = False,
    only_keep_one_computer_use_environment: bool = True,
    interface_name: str | None = None,
    max_turns: int | None = None,
    instructions: str | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType
)

Bases: ExecutionAIInterface

Simple, ReAct-style AI interface.

It requires a Runtime object, a TaskDefinition and a TaskConfig object to be passed to the constructor.

One notable aspect of this AI interface is that it forces the Runtime object to hide variables from the AI. This means that (1) only actions with JSON-serializable arguments are supported, and (2) the AI will not be able to see the variables that are not part of the task.

PARAMETER DESCRIPTION
runtime

The runtime state of the agent.

TYPE: Runtime

task_definition

The task definition of the agent.

TYPE: TaskDefinition

task_config

The task configuration of the agent.

TYPE: ConsolidatedTaskConfig

run_writer

The writer used to log run information.

TYPE: FileWriter | None DEFAULT: None

model_config

The configuration for the model.

TYPE: ModelConfig | ModelConfigTD | None DEFAULT: None

model_type

The type of model to use for the AI interface. If None, we will attempt to retrieve it from a class attribute.

TYPE: ModelType | None DEFAULT: None

computer_use_mode

Whether to use computer use mode.

TYPE: bool DEFAULT: False

only_keep_one_computer_use_environment

Whether to only keep one computer use environment.

TYPE: bool DEFAULT: True

interface_name

The name of the AI interface. Will otherwise be the snake case of the class name.

TYPE: str | None DEFAULT: None

max_turns

The maximum number of turns the AI interface can take. Defaults to 1, but can be overridden by the subclass or the user in the constructor.

TYPE: int | None DEFAULT: None

instructions

The instructions for the AI interface.

TYPE: str | None DEFAULT: None

stop_if_no_tool_calls

Whether to stop the run if no tool calls are made. Defaults to False.

TYPE: bool DEFAULT: False

kwargs

Additional parameters for the AI interface.

TYPE: ParamType DEFAULT: {}

Source code in conatus/agents/ai_interfaces/react.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def __init__(  # noqa: PLR0913
    self,
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool = False,
    only_keep_one_computer_use_environment: bool = True,
    interface_name: str | None = None,
    max_turns: int | None = None,
    instructions: str | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType,
) -> None:
    """Initialize the AI interface.

    Args:
        runtime: The runtime state of the agent.
        task_definition: The task definition of the agent.
        task_config: The task configuration of the agent.
        run_writer: The writer used to log run information.
        model_config: The configuration for the model.
        model_type: The type of model to use for the AI interface. If
            `None`, we will attempt to retrieve it from a class attribute.
        computer_use_mode: Whether to use computer use mode.
        only_keep_one_computer_use_environment: Whether to only keep one
            computer use environment.
        interface_name: The name of the AI interface. Will otherwise be
            the snake case of the class name.
        max_turns: The maximum number of turns the AI interface can take.
            Defaults to 1, but can be overridden by the subclass or the
            user in the constructor.
        instructions: The instructions for the AI interface.
        stop_if_no_tool_calls: Whether to stop the run if no tool calls are
            made. Defaults to `False`.
        kwargs: Additional parameters for the AI interface.
    """
    runtime.hide_from_ai = True
    super().__init__(
        runtime=runtime,
        task_definition=task_definition,
        task_config=task_config,
        run_writer=run_writer,
        model_config=model_config,
        model_type=model_type,
        computer_use_mode=computer_use_mode,
        only_keep_one_computer_use_environment=only_keep_one_computer_use_environment,
        interface_name=interface_name,
        max_turns=max_turns,
        instructions=instructions,
        stop_if_no_tool_calls=stop_if_no_tool_calls,
        **kwargs,
    )

arun async 

arun(
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None,
) -> AIInterfacePayload[Result]

Run the AI interface asynchronously.

For more information, see BaseAIInterface.run .

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The response from the AI interface.
Source code in conatus/agents/ai_interfaces/base.py 
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
async def arun(
    self,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface asynchronously.

    For more information, see [`BaseAIInterface.run`
    ][conatus.agents.ai_interfaces.base.BaseAIInterface.run].

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The response from the AI interface.
    """
    logger.debug("Running interface %s", self.interface_name)
    response: AIResponse[Result] | AIResponse | None = None
    prompt: AIPrompt[Result] | AIPrompt | None = None
    self.conversation_history = list(conversation_history)
    self.conversation_history_id = conversation_history_id
    self.system_message = conversation_history_system_message
    prompt, response = await self._run_first_turn(
        conversation_history=self.conversation_history,
        conversation_history_id=self.conversation_history_id,
        conversation_history_system_message=self.system_message,
    )
    while self.should_continue(response=response):
        new_messages = await self.make_new_messages(response=response)
        self.conversation_history.extend(new_messages)
        prompt, response = await self._run_new_turn(
            previous_response=response,
            new_messages=new_messages,
        )

    return AIInterfacePayload[Result](
        cost=self.cost,
        finish_reason=self.finish_reason,
        result=self.extract_result(
            latest_response=response,
            latest_prompt=prompt,
            finish_reason=self.finish_reason,
        ),
        response=response,
        state=self.runtime.state,
    )

run 

run(
    *,
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None
) -> AIInterfacePayload[Result]

Run the AI interface.

This method abstracts away the logic of interacting with the AI models, and returns a AIInterfacePayload from which the Agent can extract the result, the cost of the interactions, etc.

If the user wishes to include a previous conversation, they can provide a list of ConversationAIMessage objects, and / or a string that will identify the conversation.

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The payload of the run.
Source code in conatus/agents/ai_interfaces/base.py 
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def run(
    self,
    *,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface.

    This method abstracts away the logic of interacting with the
    [AI models][conatus.models.base.BaseAIModel], and returns a
    [`AIInterfacePayload`][conatus.agents.ai_interfaces.base.AIInterfacePayload]
    from which the [`Agent`][conatus.agents.base.Agent] can extract
    the result, the cost of the interactions, etc.

    If the user wishes to include a previous conversation, they can
    provide a list of [`ConversationAIMessage`
    ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
    objects, and / or a string that will identify the conversation.

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The payload of the run.
    """
    return run_async(
        self.arun(
            conversation_history,
            conversation_history_id,
            conversation_history_system_message,
        )
    )

conatus.agents.ai_interfaces.planning.PlanningAIInterface 

PlanningAIInterface(
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool | None = None,
    only_keep_one_computer_use_environment: (
        bool | None
    ) = None,
    interface_name: str | None = None,
    max_turns: int | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType
)

Bases: BaseAIInterfaceWithTask

AI interface for planning a task.

The prompt asks the AI to plan the Task, and to give some instructions on how to execute it. These instructions can be used by the ExecutionAIInterface to execute the task.

A few notes:

  1. We will use, when possible, reasoning models to plan the task. For more information on which model is selected for each provider, see the default_model_name implementation for OpenAI , Anthropic , and Google .

  2. The prompt is assembled from the following elements:

    • The task definition.
    • The variables (which, for now, do not include images).
    • The action docstrings (since they will not be given as tool schemas).

  3. We do not expect any structured output from the AI, so the payload returned by the run method will have a string result.

from conatus import task, browsing_actions
from conatus.io.file import FileWriter
from conatus.agents.ai_interfaces.planning import PlanningAIInterface
from conatus.utils.callable_parsing.runtime import generate_state_and_runtime

@task(actions=[browsing_actions])
def get_hn_headlines_for_day(year: int, month: int, day: int) -> list[str]:
    """Get the Hacker News headlines for a given day."""
    pass

# Let's just create a runtime for this example
state, runtime = generate_state_and_runtime(
    task=get_hn_headlines_for_day,
    args=[2024, 10, 4],
)

# Let's create the AI interface
ai_interface = PlanningAIInterface(
    runtime=runtime,
    task_definition=get_hn_headlines_for_day.definition,
    task_config=get_hn_headlines_for_day.config,
    run_writer=FileWriter(),
)

# Let's run the AI interface
payload = ai_interface.run()
print(payload.result)
# > "1. PLAN A -- a. I would first start a browser..."
PARAMETER DESCRIPTION
runtime

The runtime state of the agent.

TYPE: Runtime

task_definition

The task definition of the agent.

TYPE: TaskDefinition

task_config

The task configuration of the agent.

TYPE: ConsolidatedTaskConfig

run_writer

The writer used to log run information. If None, no logging will be done.

TYPE: FileWriter | None DEFAULT: None

model_config

The configuration for the model.

TYPE: ModelConfig | ModelConfigTD | None DEFAULT: None

model_type

The type of model to use for the AI interface. If None, we will attempt to retrieve it from a class attribute.

TYPE: ModelType | None DEFAULT: None

computer_use_mode

Whether to use computer use mode. Defaults to False, unless a subclass overrides this.

TYPE: bool | None DEFAULT: None

only_keep_one_computer_use_environment

Whether to only keep one computer use environment. Defaults to True, unless a subclass overrides this.

TYPE: bool | None DEFAULT: None

interface_name

The name of the AI interface. Will otherwise be the snake case of the class name.

TYPE: str | None DEFAULT: None

max_turns

The maximum number of turns the AI interface can take. Defaults to 1, but can be overridden by the subclass or the user in the constructor.

TYPE: int | None DEFAULT: None

stop_if_no_tool_calls

Whether to stop the run if no tool calls are made. Defaults to False.

TYPE: bool DEFAULT: False

kwargs

Additional parameters for the AI interface.

TYPE: ParamType DEFAULT: {}

Source code in conatus/agents/ai_interfaces/base.py 
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
def __init__(  # noqa: PLR0913
    self,
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool | None = None,
    only_keep_one_computer_use_environment: bool | None = None,
    interface_name: str | None = None,
    max_turns: int | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType,
) -> None:
    """Initialize the AI interface.

    Args:
        runtime: The runtime state of the agent.
        task_definition: The task definition of the agent.
        task_config: The task configuration of the agent.
        run_writer: The writer used to log run information. If `None`,
            no logging will be done.
        model_config: The configuration for the model.
        model_type: The type of model to use for the AI interface. If
            `None`, we will attempt to retrieve it from a class attribute.
        computer_use_mode: Whether to use computer use mode. Defaults to
            `False`, unless a subclass overrides this.
        only_keep_one_computer_use_environment: Whether to only keep one
            computer use environment. Defaults to `True`, unless a subclass
            overrides this.
        interface_name: The name of the AI interface. Will otherwise be
            the snake case of the class name.
        max_turns: The maximum number of turns the AI interface can take.
            Defaults to 1, but can be overridden by the subclass or the
            user in the constructor.
        stop_if_no_tool_calls: Whether to stop the run if no tool calls are
            made. Defaults to `False`.
        kwargs: Additional parameters for the AI interface.
    """
    super().__init__(
        task_config=task_config,
        run_writer=run_writer,
        model_config=model_config,
        model_type=model_type,
        interface_name=interface_name,
        max_turns=max_turns,
        runtime=runtime,
        actions=None,
        computer_use_mode=computer_use_mode,
        only_keep_one_computer_use_environment=only_keep_one_computer_use_environment,
        stop_if_no_tool_calls=stop_if_no_tool_calls,
        hide_runtime_from_ai=False,
        **kwargs,
    )
    self.task_definition = task_definition
    self.task_config = task_config

arun async 

arun(
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None,
) -> AIInterfacePayload[Result]

Run the AI interface asynchronously.

For more information, see BaseAIInterface.run .

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The response from the AI interface.
Source code in conatus/agents/ai_interfaces/base.py 
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
async def arun(
    self,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface asynchronously.

    For more information, see [`BaseAIInterface.run`
    ][conatus.agents.ai_interfaces.base.BaseAIInterface.run].

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The response from the AI interface.
    """
    logger.debug("Running interface %s", self.interface_name)
    response: AIResponse[Result] | AIResponse | None = None
    prompt: AIPrompt[Result] | AIPrompt | None = None
    self.conversation_history = list(conversation_history)
    self.conversation_history_id = conversation_history_id
    self.system_message = conversation_history_system_message
    prompt, response = await self._run_first_turn(
        conversation_history=self.conversation_history,
        conversation_history_id=self.conversation_history_id,
        conversation_history_system_message=self.system_message,
    )
    while self.should_continue(response=response):
        new_messages = await self.make_new_messages(response=response)
        self.conversation_history.extend(new_messages)
        prompt, response = await self._run_new_turn(
            previous_response=response,
            new_messages=new_messages,
        )

    return AIInterfacePayload[Result](
        cost=self.cost,
        finish_reason=self.finish_reason,
        result=self.extract_result(
            latest_response=response,
            latest_prompt=prompt,
            finish_reason=self.finish_reason,
        ),
        response=response,
        state=self.runtime.state,
    )

run 

run(
    *,
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None
) -> AIInterfacePayload[Result]

Run the AI interface.

This method abstracts away the logic of interacting with the AI models, and returns a AIInterfacePayload from which the Agent can extract the result, the cost of the interactions, etc.

If the user wishes to include a previous conversation, they can provide a list of ConversationAIMessage objects, and / or a string that will identify the conversation.

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The payload of the run.
Source code in conatus/agents/ai_interfaces/base.py 
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def run(
    self,
    *,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface.

    This method abstracts away the logic of interacting with the
    [AI models][conatus.models.base.BaseAIModel], and returns a
    [`AIInterfacePayload`][conatus.agents.ai_interfaces.base.AIInterfacePayload]
    from which the [`Agent`][conatus.agents.base.Agent] can extract
    the result, the cost of the interactions, etc.

    If the user wishes to include a previous conversation, they can
    provide a list of [`ConversationAIMessage`
    ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
    objects, and / or a string that will identify the conversation.

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The payload of the run.
    """
    return run_async(
        self.arun(
            conversation_history,
            conversation_history_id,
            conversation_history_system_message,
        )
    )

conatus.agents.ai_interfaces.execution.ExecutionAIInterface 

ExecutionAIInterface(
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool = False,
    only_keep_one_computer_use_environment: bool = True,
    interface_name: str | None = None,
    max_turns: int | None = None,
    instructions: str | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType
)

Bases: BaseAIInterfaceWithTask

AI interface for execution.

This is the main AI interface for executing a Task . It allows the AI to respond with either code snippets or tool calls, and adds some preamble to help the AI understand the task.

One notable aspect of this AI interface is that you can pass instructions to the constructor. These instructions are used to help the AI understand the task. This is useful if you've already planned the steps of the task, and you want to give that information to the AI.

For more information, look at the agents/prompts/execution_dev_message.txt file, which contains the developer message that is added to the prompt.

PARAMETER DESCRIPTION
runtime

The runtime state of the agent.

TYPE: Runtime

task_definition

The task definition of the agent.

TYPE: TaskDefinition

task_config

The task configuration of the agent.

TYPE: ConsolidatedTaskConfig

run_writer

The writer used to log run information. If None, no logging will be done.

TYPE: FileWriter | None DEFAULT: None

model_config

The configuration for the model.

TYPE: ModelConfig | ModelConfigTD | None DEFAULT: None

model_type

The type of model to use for the AI interface. If None, we will attempt to retrieve it from a class attribute.

TYPE: ModelType | None DEFAULT: None

computer_use_mode

Whether to use computer use mode.

TYPE: bool DEFAULT: False

only_keep_one_computer_use_environment

Whether to only keep one computer use environment.

TYPE: bool DEFAULT: True

interface_name

The name of the AI interface. Will otherwise be the snake case of the class name.

TYPE: str | None DEFAULT: None

max_turns

The maximum number of turns the AI interface can take. Defaults to 1, but can be overridden by the subclass or the user in the constructor.

TYPE: int | None DEFAULT: None

instructions

The instructions for the AI interface.

TYPE: str | None DEFAULT: None

stop_if_no_tool_calls

Whether to stop the run if no tool calls are made. Defaults to False.

TYPE: bool DEFAULT: False

kwargs

Additional parameters for the AI interface.

TYPE: ParamType DEFAULT: {}

Source code in conatus/agents/ai_interfaces/execution.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def __init__(  # noqa: PLR0913
    self,
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool = False,
    only_keep_one_computer_use_environment: bool = True,
    interface_name: str | None = None,
    max_turns: int | None = None,
    instructions: str | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType,
) -> None:
    """Initialize the AI interface.

    Args:
        runtime: The runtime state of the agent.
        task_definition: The task definition of the agent.
        task_config: The task configuration of the agent.
        run_writer: The writer used to log run information. If `None`,
            no logging will be done.
        model_config: The configuration for the model.
        model_type: The type of model to use for the AI interface. If
            `None`, we will attempt to retrieve it from a class attribute.
        computer_use_mode: Whether to use computer use mode.
        only_keep_one_computer_use_environment: Whether to only keep one
            computer use environment.
        interface_name: The name of the AI interface. Will otherwise be
            the snake case of the class name.
        max_turns: The maximum number of turns the AI interface can take.
            Defaults to 1, but can be overridden by the subclass or the
            user in the constructor.
        instructions: The instructions for the AI interface.
        stop_if_no_tool_calls: Whether to stop the run if no tool calls are
            made. Defaults to `False`.
        kwargs: Additional parameters for the AI interface.
    """
    super().__init__(
        runtime=runtime,
        task_definition=task_definition,
        task_config=task_config,
        run_writer=run_writer,
        model_config=model_config,
        model_type=model_type,
        computer_use_mode=computer_use_mode,
        only_keep_one_computer_use_environment=only_keep_one_computer_use_environment,
        interface_name=interface_name,
        max_turns=max_turns or self.DEFAULT_MAX_TURNS,
        stop_if_no_tool_calls=stop_if_no_tool_calls,
        **kwargs,
    )
    self.instructions = instructions

instructions instance-attribute 

instructions: str | None = instructions

The instructions for the AI interface.

These instructions are optional, and are used to help the AI understand the Task. The PlanningAIInterface was designed with this in mind.

arun async 

arun(
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None,
) -> AIInterfacePayload[Result]

Run the AI interface asynchronously.

For more information, see BaseAIInterface.run .

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The response from the AI interface.
Source code in conatus/agents/ai_interfaces/base.py 
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
async def arun(
    self,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface asynchronously.

    For more information, see [`BaseAIInterface.run`
    ][conatus.agents.ai_interfaces.base.BaseAIInterface.run].

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The response from the AI interface.
    """
    logger.debug("Running interface %s", self.interface_name)
    response: AIResponse[Result] | AIResponse | None = None
    prompt: AIPrompt[Result] | AIPrompt | None = None
    self.conversation_history = list(conversation_history)
    self.conversation_history_id = conversation_history_id
    self.system_message = conversation_history_system_message
    prompt, response = await self._run_first_turn(
        conversation_history=self.conversation_history,
        conversation_history_id=self.conversation_history_id,
        conversation_history_system_message=self.system_message,
    )
    while self.should_continue(response=response):
        new_messages = await self.make_new_messages(response=response)
        self.conversation_history.extend(new_messages)
        prompt, response = await self._run_new_turn(
            previous_response=response,
            new_messages=new_messages,
        )

    return AIInterfacePayload[Result](
        cost=self.cost,
        finish_reason=self.finish_reason,
        result=self.extract_result(
            latest_response=response,
            latest_prompt=prompt,
            finish_reason=self.finish_reason,
        ),
        response=response,
        state=self.runtime.state,
    )

run 

run(
    *,
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None
) -> AIInterfacePayload[Result]

Run the AI interface.

This method abstracts away the logic of interacting with the AI models, and returns a AIInterfacePayload from which the Agent can extract the result, the cost of the interactions, etc.

If the user wishes to include a previous conversation, they can provide a list of ConversationAIMessage objects, and / or a string that will identify the conversation.

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The payload of the run.
Source code in conatus/agents/ai_interfaces/base.py 
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def run(
    self,
    *,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface.

    This method abstracts away the logic of interacting with the
    [AI models][conatus.models.base.BaseAIModel], and returns a
    [`AIInterfacePayload`][conatus.agents.ai_interfaces.base.AIInterfacePayload]
    from which the [`Agent`][conatus.agents.base.Agent] can extract
    the result, the cost of the interactions, etc.

    If the user wishes to include a previous conversation, they can
    provide a list of [`ConversationAIMessage`
    ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
    objects, and / or a string that will identify the conversation.

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The payload of the run.
    """
    return run_async(
        self.arun(
            conversation_history,
            conversation_history_id,
            conversation_history_system_message,
        )
    )

conatus.agents.ai_interfaces.computer_use.ComputerUseAIInterface 

ComputerUseAIInterface(
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool = False,
    only_keep_one_computer_use_environment: bool = True,
    interface_name: str | None = None,
    max_turns: int | None = None,
    instructions: str | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType
)

Bases: ExecutionAIInterface

AI interface using native computer use abilities.

PARAMETER DESCRIPTION
runtime

The runtime state of the agent.

TYPE: Runtime

task_definition

The task definition of the agent.

TYPE: TaskDefinition

task_config

The task configuration of the agent.

TYPE: ConsolidatedTaskConfig

run_writer

The writer used to log run information. If None, no logging will be done.

TYPE: FileWriter | None DEFAULT: None

model_config

The configuration for the model.

TYPE: ModelConfig | ModelConfigTD | None DEFAULT: None

model_type

The type of model to use for the AI interface. If None, we will attempt to retrieve it from a class attribute.

TYPE: ModelType | None DEFAULT: None

computer_use_mode

Whether to use computer use mode.

TYPE: bool DEFAULT: False

only_keep_one_computer_use_environment

Whether to only keep one computer use environment.

TYPE: bool DEFAULT: True

interface_name

The name of the AI interface. Will otherwise be the snake case of the class name.

TYPE: str | None DEFAULT: None

max_turns

The maximum number of turns the AI interface can take. Defaults to 1, but can be overridden by the subclass or the user in the constructor.

TYPE: int | None DEFAULT: None

instructions

The instructions for the AI interface.

TYPE: str | None DEFAULT: None

stop_if_no_tool_calls

Whether to stop the run if no tool calls are made. Defaults to False.

TYPE: bool DEFAULT: False

kwargs

Additional parameters for the AI interface.

TYPE: ParamType DEFAULT: {}

Source code in conatus/agents/ai_interfaces/execution.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def __init__(  # noqa: PLR0913
    self,
    *,
    runtime: Runtime,
    task_definition: TaskDefinition,
    task_config: ConsolidatedTaskConfig,
    run_writer: FileWriter | None = None,
    model_config: ModelConfig | ModelConfigTD | None = None,
    model_type: ModelType | None = None,
    computer_use_mode: bool = False,
    only_keep_one_computer_use_environment: bool = True,
    interface_name: str | None = None,
    max_turns: int | None = None,
    instructions: str | None = None,
    stop_if_no_tool_calls: bool = False,
    **kwargs: ParamType,
) -> None:
    """Initialize the AI interface.

    Args:
        runtime: The runtime state of the agent.
        task_definition: The task definition of the agent.
        task_config: The task configuration of the agent.
        run_writer: The writer used to log run information. If `None`,
            no logging will be done.
        model_config: The configuration for the model.
        model_type: The type of model to use for the AI interface. If
            `None`, we will attempt to retrieve it from a class attribute.
        computer_use_mode: Whether to use computer use mode.
        only_keep_one_computer_use_environment: Whether to only keep one
            computer use environment.
        interface_name: The name of the AI interface. Will otherwise be
            the snake case of the class name.
        max_turns: The maximum number of turns the AI interface can take.
            Defaults to 1, but can be overridden by the subclass or the
            user in the constructor.
        instructions: The instructions for the AI interface.
        stop_if_no_tool_calls: Whether to stop the run if no tool calls are
            made. Defaults to `False`.
        kwargs: Additional parameters for the AI interface.
    """
    super().__init__(
        runtime=runtime,
        task_definition=task_definition,
        task_config=task_config,
        run_writer=run_writer,
        model_config=model_config,
        model_type=model_type,
        computer_use_mode=computer_use_mode,
        only_keep_one_computer_use_environment=only_keep_one_computer_use_environment,
        interface_name=interface_name,
        max_turns=max_turns or self.DEFAULT_MAX_TURNS,
        stop_if_no_tool_calls=stop_if_no_tool_calls,
        **kwargs,
    )
    self.instructions = instructions

arun async 

arun(
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None,
) -> AIInterfacePayload[Result]

Run the AI interface asynchronously.

For more information, see BaseAIInterface.run .

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The response from the AI interface.
Source code in conatus/agents/ai_interfaces/base.py 
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
async def arun(
    self,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface asynchronously.

    For more information, see [`BaseAIInterface.run`
    ][conatus.agents.ai_interfaces.base.BaseAIInterface.run].

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The response from the AI interface.
    """
    logger.debug("Running interface %s", self.interface_name)
    response: AIResponse[Result] | AIResponse | None = None
    prompt: AIPrompt[Result] | AIPrompt | None = None
    self.conversation_history = list(conversation_history)
    self.conversation_history_id = conversation_history_id
    self.system_message = conversation_history_system_message
    prompt, response = await self._run_first_turn(
        conversation_history=self.conversation_history,
        conversation_history_id=self.conversation_history_id,
        conversation_history_system_message=self.system_message,
    )
    while self.should_continue(response=response):
        new_messages = await self.make_new_messages(response=response)
        self.conversation_history.extend(new_messages)
        prompt, response = await self._run_new_turn(
            previous_response=response,
            new_messages=new_messages,
        )

    return AIInterfacePayload[Result](
        cost=self.cost,
        finish_reason=self.finish_reason,
        result=self.extract_result(
            latest_response=response,
            latest_prompt=prompt,
            finish_reason=self.finish_reason,
        ),
        response=response,
        state=self.runtime.state,
    )

run 

run(
    *,
    conversation_history: Collection[
        ConversationAIMessage
    ] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: (
        SystemAIMessage | None
    ) = None
) -> AIInterfacePayload[Result]

Run the AI interface.

This method abstracts away the logic of interacting with the AI models, and returns a AIInterfacePayload from which the Agent can extract the result, the cost of the interactions, etc.

If the user wishes to include a previous conversation, they can provide a list of ConversationAIMessage objects, and / or a string that will identify the conversation.

PARAMETER DESCRIPTION
conversation_history

The conversation history, as a list of ConversationAIMessage objects.

TYPE: Collection[ConversationAIMessage] DEFAULT: ()

conversation_history_id

The ID of the conversation history. This should be used when dealing with stateful AI interfaces.

TYPE: str | None DEFAULT: None

conversation_history_system_message

The system message of the conversation history.

TYPE: SystemAIMessage | None DEFAULT: None

RETURNS DESCRIPTION
AIInterfacePayload[Result]

The payload of the run.
Source code in conatus/agents/ai_interfaces/base.py 
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def run(
    self,
    *,
    conversation_history: Collection[ConversationAIMessage] = (),
    conversation_history_id: str | None = None,
    conversation_history_system_message: SystemAIMessage | None = None,
) -> AIInterfacePayload[Result]:
    """Run the AI interface.

    This method abstracts away the logic of interacting with the
    [AI models][conatus.models.base.BaseAIModel], and returns a
    [`AIInterfacePayload`][conatus.agents.ai_interfaces.base.AIInterfacePayload]
    from which the [`Agent`][conatus.agents.base.Agent] can extract
    the result, the cost of the interactions, etc.

    If the user wishes to include a previous conversation, they can
    provide a list of [`ConversationAIMessage`
    ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
    objects, and / or a string that will identify the conversation.

    Args:
        conversation_history: The conversation history, as a list of
            [`ConversationAIMessage`
            ][conatus.models.inputs_outputs.messages.ConversationAIMessage]
            objects.
        conversation_history_id: The ID of the conversation history. This
            should be used when dealing with stateful AI interfaces.
        conversation_history_system_message: The system message of the
            conversation history.

    Returns:
        The payload of the run.
    """
    return run_async(
        self.arun(
            conversation_history,
            conversation_history_id,
            conversation_history_system_message,
        )
    )