Apps API¶

Apps are the building blocks of Meta Agents Research Environments simulations. They provide interactive functionality that agents can use as tools to accomplish tasks. This section documents the core App API and how to create custom applications.

Overview ¶

Apps in Meta Agents Research Environments function similarly to applications on your phone or computer. Each app:

Provides specific functionality (email, file system, calendar, etc.)
Exposes APIs that agents can call as tools
Maintains internal state that evolves during simulation
Generates events when actions are performed

Creating Custom Apps ¶

To create a custom app, inherit from the base App class and implement the required functionality:

Basic App Structure ¶

from are.simulation.apps.app import App
from are.simulation.tool_utils import app_tool

class MyCustomApp(App):
    def __init__(self, name: str = None):
        super().__init__(name)
        # Initialize app-specific state
        self.data = {}

    @app_tool
    def my_action(self, param: str) -> str:
        """
        Perform a custom action.

        Args:
            param: Input parameter

        Returns:
            Result of the action
        """
        # Implement your logic here
        result = f"Processed: {param}"
        self.data[param] = result
        return result

    def get_state(self) -> dict:
        """Return the current state of the app."""
        return {"data": self.data}

    def load_state(self, state: dict) -> None:
        """Load state into the app."""
        self.data = state.get("data", {})

Tool Decorators ¶

Meta Agents Research Environments provides several decorators for registering methods as tools:

from are.simulation.tool_utils import app_tool, user_tool, env_tool, data_tool

class MyApp(App):
    @app_tool # Available to agents as a tool
    def agent_action(self, param: str) -> str:
        """Available to agents as a tool."""
        pass

    @user_tool # Only available to the user
    def user_action(self, param: str) -> str:
        """Available for user interactions."""
        pass

    @env_tool # To be used for environment events
    def env_action(self, param: str) -> str:
        """Available for environment events."""
        pass

    @data_tool # To populate data
    def data_action(self, param: str) -> str:
        """Available for data operations."""
        pass

State Management ¶

Apps should implement proper state management for simulation consistency:

class StatefulApp(App):
    def __init__(self):
        super().__init__()
        self.items = []
        self.counter = 0

    def get_state(self) -> dict:
        """Serialize app state."""
        return {
            "items": self.items,
            "counter": self.counter
        }

    def load_state(self, state: dict) -> None:
        """Restore app state."""
        self.items = state.get("items", [])
        self.counter = state.get("counter", 0)

    def reset(self) -> None:
        """Reset app to initial state."""
        super().reset()
        self.items = []
        self.counter = 0

Event Integration ¶

Apps can generate events that affect the simulation:

from are.simulation.core.events import Event, Action

class EventGeneratingApp(App):
    @app_tool
    @event_registered(operation_type=OperationType.WRITE) # Register the event as a write action
    def send_message(self, message: str) -> str:
        """Action that sends a message."""
        self.elf._send_message(message, sender=self.name)

Protocol Implementation ¶

Apps can implement protocols to interact with other apps:

from are.simulation.apps.app import Protocol

class FileSystemApp(App):
    def get_implemented_protocols(self) -> list[Protocol]:
        """Declare which protocols this app implements."""
        return [Protocol.FILE_SYSTEM]

    @app_tool
    def read_file(self, path: str) -> str:
        """Read a file from the file system."""
        # Implementation here
        pass

class DocumentApp(App):
    def connect_to_protocols(self, protocols: dict[Protocol, Any]) -> None:
        """Connect to other apps via protocols."""
        if Protocol.FILE_SYSTEM in protocols:
            self.file_system = protocols[Protocol.FILE_SYSTEM]

    @app_tool
    def open_document(self, path: str) -> str:
        """Open a document using the file system."""
        content = self.file_system.read_file(path)
        return f"Opened document: {content}"

Best Practices ¶

App Design Guidelines ¶

Single Responsibility: Each app should have a clear, focused purpose
Realistic Behavior: Apps should behave like their real-world counterparts
Comprehensive APIs: Provide all necessary functionality for realistic scenarios
Error Handling: Handle edge cases and invalid inputs gracefully
Documentation: Include detailed docstrings for all agent methods

Performance Considerations ¶

State Efficiency: Keep state minimal and serializable
Tool Registration: Use lazy initialization for tool registries
Memory Management: Clean up resources in reset methods
Concurrency: Ensure thread-safety for multi-scenario execution

Testing Apps ¶

Unit Tests: Test individual app methods in isolation
Integration Tests: Test app behavior within scenarios
State Tests: Verify state serialization and restoration
Tool Tests: Ensure tools are properly registered and callable

For more examples of app implementation, see the built-in apps in the are.simulation.apps module.

Core App Class ¶

class are.simulation.apps.app.Protocol(value)[source]

Bases: Enum

An enumeration.

FILE_SYSTEM = 'FILE_SYSTEM'

class are.simulation.apps.app.ToolType(value)[source]

Bases: Enum

An enumeration.

APP = 1

USER = 2

ENV = 3

DATA = 4

class are.simulation.apps.app.App(name=None, *args, **kwargs)[source]

Bases: ABC, SkippableDeepCopy

Base class for all applications in the Meta Agents Research Environments environment.

__init__(name=None, *args, **kwargs)[source]

register_time_manager(time_manager)[source]

set_seed(seed)[source]

Return type:: None

register_to_env(key, add_event)[source]

add_event(event)[source]

Return type:: None

get_implemented_protocols()[source]

App can provide protocols, e.g. FileSystem which could be used by other apps Returns a list of protocol names that the app implements.

Return type:: list[Protocol]

connect_to_protocols(protocols)[source]

App can connect to other apps via protocols.

Return type:: None

get_state()[source]

Return type:: dict[str, Any] | None

load_state(state_dict)[source]

reset()

app_name()[source]

Return type:: str

set_failure_probability(failure_probability)[source]

Return type:: None

get_tools_with_attribute(attribute, tool_type)[source]

Retrieves a list of tools that have a specific attribute from the class and its base classes.

Parameters:

attribute (ToolAttributeName) – The attribute to look for in the tools as a ToolAttributeName enum value.
tool_type (ToolType) – The type of tool being registered.

Returns:

A list of AppTool objects that have the specified attribute.

Return type:

list[AppTool]

get_tools()[source]

Retrieves the list of agent tools, initializing the tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for agents.

get_user_tools()[source]

Retrieves the list of user tools, initializing the user tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for users.

get_env_tools()[source]

Retrieves the list of environment tools, initializing the environment tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for the environment.

get_tool(tool_name)[source]

Retrieves a specific tool by name, searching through all tool types.

Parameters:: tool_name (str) – The name of the tool to retrieve.
Returns:: The AppTool object with the specified name, or None if not found.
Return type:: AppTool | None

get_data_tools()[source]

Retrieves the list of data tools, initializing the data tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for data.

pause_env()[source]

Return type:: None

resume_env()[source]

Return type:: None

are.simulation.apps.app.get_base_method_doc(cls, method)[source]

Retrieves the docstring of a method from its base class if it exists.

Parameters:

cls (type) – The class containing the method.
method (Callable) – The method whose docstring is being retrieved.

Return type:

str | None

Returns:

The docstring of the method, or None if it does not exist in the base class.

Key Methods ¶

Tool Registration

App.get_tools()[source]¶

Retrieves the list of agent tools, initializing the tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for agents.

App.get_user_tools()[source]¶

Retrieves the list of user tools, initializing the user tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for users.

App.get_env_tools()[source]¶

Retrieves the list of environment tools, initializing the environment tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for the environment.

App.get_data_tools()[source]¶

Retrieves the list of data tools, initializing the data tool registry if necessary.

Return type:: list[AppTool]
Returns:: A list of AppTool objects for data.

State Management

App.get_state()[source]¶

Return type:: dict[str, Any] | None

App.load_state(state_dict)[source]¶

App.reset()¶

Environment Integration

App.register_to_env(key, add_event)[source]¶

App.add_event(event)[source]¶

Return type:: None

Tool Utilities ¶

are.simulation.tool_utils.adapt_type(t)[source]

class are.simulation.tool_utils.AppToolArg(name, arg_type, description, has_default=False, default=None, example_value=None, type_obj=None)[source]

Bases: object

name: str

arg_type: str

description: str | None

has_default: bool = False

default: Optional[Any] = None

example_value: Optional[Any] = None

type_obj: Optional[Any] = None

class are.simulation.tool_utils.AppTool(class_name, app_name, name, function_description, args, return_type=None, return_description=None, function=None, class_instance=None, write_operation=None, _public_name=None, _public_description=None, failure_probability=None, failure_message_template='Calling {name} failed with error: Internal error - Retry again later', seed=None, rng=None)[source]

Bases: object

class_name: str

app_name: str

name: str

function_description: str | None

args: list[AppToolArg]

return_type: Optional[Any] = None

return_description: str | None = None

function: Optional[Callable] = None

class_instance: Optional[Any] = None

write_operation: bool | None = None

failure_probability: float | None = None

failure_message_template: str = 'Calling {name} failed with error: Internal error - Retry again later'

seed: int | None = None

rng: Random | None = None

property arg_descriptions: str

property func_name

static get_tool_for_function(func)[source]

Get the AppTool instance associated with a function.

Return type:: AppTool | None

to_metadata_dict()[source]: Returns a dictionary representation of the tool’s metadata. This is used for serialization and UI display.

to_open_ai()[source]

Convert the tool to OpenAI function calling format.

Example:

{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
    }
}

class are.simulation.tool_utils.OperationType(value)[source]

Bases: Enum

An enumeration.

READ = 'read'

WRITE = 'write'

class are.simulation.tool_utils.ToolAttributeName(value)[source]

Bases: Enum

Enum for tool attribute names used by decorators and tool registration.

APP = '_is_app_tool'

ENV = '_is_env_tool'

DATA = '_is_data_tool'

USER = '_is_user_tool'

are.simulation.tool_utils.tool_decorator(llm_formatter=None, attribute_name=ToolAttributeName.APP)[source]

Decorator to register a function as an app tool.

Parameters:

llm_formatter (Optional[Callable]) – a function to format the result of the tool before returning it to the LLM Agent, THIS IS ONLY USED WHEN the function is called as a tool (i.e. from AppTool call), not when called as a normal function
attribute_name (ToolAttributeName) – the attribute name to set on the function as a ToolAttributeName enum value

are.simulation.tool_utils.app_tool(llm_formatter=None)[source]

Decorator to register a function as an app tool.

Parameters:: llm_formatter (Optional[Callable]) – a function to format the result of the tool before returning it to the LLM Agent

are.simulation.tool_utils.env_tool(llm_formatter=None)[source]

Decorator to register a function as an environment tool.

Parameters:: llm_formatter (Optional[Callable]) – a function to format the result of the tool before returning it to the LLM Agent

are.simulation.tool_utils.data_tool(llm_formatter=None)[source]

Decorator to register a function as a data tool.

Parameters:: llm_formatter (Optional[Callable]) – a function to format the result of the tool before returning it to the LLM Agent

are.simulation.tool_utils.user_tool(llm_formatter=None)[source]

Decorator to register a function as a user tool.

Parameters:: llm_formatter (Optional[Callable]) – a function to format the result of the tool before returning it to the LLM Agent

are.simulation.tool_utils.format_type_name(type_obj)[source]

Helper function to format type names.

Return type:: str

are.simulation.tool_utils.build_tool(app, func, failure_probability=None)[source]

Return type:: AppTool

are.simulation.tool_utils.validate_argument_types(func, args_mapping)[source]

Validate the types of the provided arguments against the function’s signature.

Return type:: bool

are.simulation.tool_utils.parse_function_call_example(func, example_str)[source]

Parse the function call example and check the argument types.

Return type:: dict[str, Any]

are.simulation.tool_utils.get_example_from_docstring(func)[source]

Extract examples from a docstring.

Return type:: str | None

class are.simulation.tool_utils.AppToolAdapter(app_tool)[source]

Bases: Tool

forward(*args, **kwargs)[source]

Tool Classes ¶

Bases: object

class_name: str

app_name: str

name: str

function_description: str | None

args: list[AppToolArg]

return_type: Optional[Any] = None

return_description: str | None = None

function: Optional[Callable] = None

class_instance: Optional[Any] = None

write_operation: bool | None = None

failure_probability: float | None = None

failure_message_template: str = 'Calling {name} failed with error: Internal error - Retry again later'

seed: int | None = None

rng: Random | None = None

property arg_descriptions: str

property func_name

static get_tool_for_function(func)[source]

Get the AppTool instance associated with a function.

Return type:: AppTool | None

to_metadata_dict()[source]: Returns a dictionary representation of the tool’s metadata. This is used for serialization and UI display.

to_open_ai()[source]

Convert the tool to OpenAI function calling format.

Example:

{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"]
                }
            },
            "required": ["location"]
        }
    }
}

class are.simulation.tool_utils.ToolAttributeName(value)[source]

Bases: Enum

Enum for tool attribute names used by decorators and tool registration.

APP = '_is_app_tool'

ENV = '_is_env_tool'

DATA = '_is_data_tool'

USER = '_is_user_tool'

class are.simulation.tool_utils.OperationType(value)[source]

Bases: Enum

An enumeration.

READ = 'read'

WRITE = 'write'

class are.simulation.tool_utils.AppToolArg(name, arg_type, description, has_default=False, default=None, example_value=None, type_obj=None)[source]

Bases: object

name: str

arg_type: str

description: str | None

has_default: bool = False

default: Optional[Any] = None

example_value: Optional[Any] = None

type_obj: Optional[Any] = None

Enums and Types ¶

class are.simulation.apps.app.Protocol(value)[source]¶

Bases: Enum

An enumeration.

FILE_SYSTEM = 'FILE_SYSTEM'¶

class are.simulation.apps.app.ToolType(value)[source]¶

Bases: Enum

An enumeration.

APP = 1¶

USER = 2¶

ENV = 3¶

DATA = 4¶

Built-in Apps ¶

Meta Agents Research Environments includes a variety of pre-built apps for common use cases:

Communication Apps ¶

Email Client

class are.simulation.apps.email_client.EmailFolderName(value)[source]

Bases: Enum

An enumeration.

INBOX = 'INBOX'

SENT = 'SENT'

DRAFT = 'DRAFT'

TRASH = 'TRASH'

class are.simulation.apps.email_client.Email(sender='user@meta.com', recipients=<factory>, subject='', content='', email_id=<factory>, parent_id=None, cc=<factory>, attachments=<factory>, timestamp=<factory>, is_read=False)[source]

Bases: object

sender: str = 'user@meta.com'

recipients: list[str]

subject: str = ''

content: str = ''

email_id: str

parent_id: str | None = None

cc: list[str]

attachments: dict[str, bytes] | None

timestamp: float

is_read: bool = False

property summary

add_attachment(path)[source]

class are.simulation.apps.email_client.ReturnedEmails(emails, emails_range, total_returned_emails, total_emails)[source]

Bases: object

emails: list[Email]

emails_range: tuple[int, int]

total_returned_emails: int

total_emails: int

class are.simulation.apps.email_client.EmailFolder(folder_name)[source]

Bases: object

add_email(email)[source]

get_emails(offset=0, limit=5)[source]

Return type:: ReturnedEmails

get_email(idx=0)[source]

Return type:: Email

get_email_by_id(email_id)[source]

Return type:: Email

get_state()[source]

Return type:: dict[str, Any]

load_state(state_dict)[source]

class are.simulation.apps.email_client.EmailClientApp(name=None, view_limit=5, folders=<factory>, user_email='user@meta.com')[source]

Bases: App

An email client application that manages email operations and folder organization. This class provides comprehensive functionality for handling emails including sending, receiving, organizing, and managing email attachments.

The app maintains emails in different folders (INBOX, SENT, DRAFT, TRASH) and provides various operations for email manipulation and searching.

Key Features: - Email Management: Send, reply, move, and delete emails - Folder Organization: Maintains separate folders for different email categories - Attachment Support: Handle email attachments (upload and download) - Search Functionality: Search emails across folders with text-based queries - State Management: Save and load application state

Key Components: - Folders: Each EmailFolder instance (INBOX, SENT, DRAFT, TRASH) maintains its own collection of emails - Email Validation: Validates email addresses using regex pattern matching - View Limits: Configurable limit for email viewing and pagination - Event Registration: All operations are tracked through event registration

Notes: - Email IDs are automatically generated when creating new emails - Attachments are handled using base64 encoding - Search operations are case-insensitive - All email operations maintain folder integrity - Supports CC recipients and multiple attachments

name: str | None = None

view_limit: int = 5

folders: dict[EmailFolderName, EmailFolder]

user_email: str = 'user@meta.com'

get_state()[source]

Return type:: dict[str, Any] | None

load_state(state_dict)[source]

reset()[source]

add_email(email, folder_name=EmailFolderName.INBOX)[source]

Adds an email to the specified folder. :type email: Email :param email: The email to add. :type folder_name: EmailFolderName :param folder_name: The folder to add the email to.

Return type:: str

send_email_to_user(email)[source]

Return type:: str

send_email_to_user_only(sender, subject='', content='')[source]

Creates an email with the user as sole recipient and adds it to the user’s INBOX folder. :type sender: str :param sender: The sender of the email. :type subject: str :param subject: The subject of the email. :type content: str :param content: The content of the email. :rtype: str :returns: The id of the email just created.

Return type:: str

reply_to_email_from_user(sender, email_id, content='', attachment_paths=None)[source]

Creates a reply to an email from the user and adds it to the user’s INBOX folder. :type sender: str :param sender: The sender of the email. :type email_id: str :param email_id: The id of the email to reply to, the Id is specified in the email details. :type content: str :param content: The content of the reply. :type attachment_paths: Optional[list[str]] :param attachment_paths: The paths of the attachments to add to the reply. :rtype: str :returns: The id of the email just created and sent.

Example:: reply_to_email_from_user(”other_user@meta.com”, “1234567890abcdef”, “Hello, this is a reply to your email.”)
Return type:: str

create_and_add_email(sender, recipients=None, subject='', content='', folder_name='INBOX')[source]

Create and add an email to the specified folder. :type sender: str :param sender: The sender of the email. :type recipients: Optional[list[str]] :param recipients: The recipients of the email. :type subject: str :param subject: The subject of the email. :type content: str :param content: The content of the email. :type folder_name: str :param folder_name: The folder to add the email to. Can only be one of INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :rtype: str :returns: The id of the email just created.

Return type:: str

create_and_add_email_with_time(sender, recipients=None, subject='', content='', email_time='2025-09-23 19:17:52', folder_name='INBOX')[source]

Create and add an email to the specified folder. :type sender: str :param sender: The sender of the email. :type recipients: Optional[list[str]] :param recipients: The recipients of the email. :type subject: str :param subject: The subject of the email. :type content: str :param content: The content of the email. :type folder_name: str :param folder_name: The folder to add the email to. Can only be one of INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :type email_time: str :param email_time: The time of the email. Defaults to the current time. :rtype: str :returns: The id of the email just created.

Return type:: str

list_emails(folder_name='INBOX', offset=0, limit=10)[source]

Lists emails in the specified folder with a specified offset. :type folder_name: str :param folder_name: The folder to list emails from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :type offset: int :param offset: The offset of the first email to return. :type limit: int :param limit: The maximum number of emails to return. :rtype: ReturnedEmails :returns: Emails with additional metadata about the range of emails retrieved and total number of emails

Example:: list_emails(“INBOX”, 0, 10)
Return type:: ReturnedEmails

get_email_by_id(email_id, folder_name='INBOX')[source]

Reads an email from the specified folder, marking it as read. :type email_id: str :param email_id: The id of the email to read, the Id is specified in the email. :type folder_name: str :param folder_name: The folder to read the email from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :rtype: Email :returns: Email details if successful, otherwise raise IndexError.

Example:: get_email_by_id(“1234567890abcdef”)
Return type:: Email

get_email_by_index(idx, folder_name='INBOX')[source]

Reads an email from the specified folder, marking it as read. :type idx: int :param idx: The index of the email to read among the list of emails in the folder. :type folder_name: str :param folder_name: The folder to read the email from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :rtype: Email :returns: Email details if successful, otherwise raise IndexError.

Example:: get_email_by_index(0, “INBOX”)
Return type:: Email

send_email(recipients=None, subject='', content='', cc=None, attachment_paths=None)[source]

Sends an email to the specified recipients. :type recipients: Optional[list[str]] :param recipients: The recipients of the email. :type subject: str :param subject: The subject of the email. :type content: str :param content: The content of the email. :type cc: Optional[list[str]] :param cc: The cc of the email. :type attachment_paths: Optional[list[str]] :param attachment_paths: The paths of the attachments to add to the email. :rtype: str :returns: The id of the email just created.

Example:: send_email([”user1@meta.com”, “user2@meta.com”], “Hello”, “Hi there”, [”user3@meta.com”], [“tmp123/file1.txt”, “tmp234/file2.txt”])
Return type:: str

forward_email(email_id, recipients=None, folder_name='INBOX')[source]

Forwards an email to the specified recipients. :type email_id: str :param email_id: The id of the email to forward. :type recipients: Optional[list[str]] :param recipients: The recipients of the email. :type folder_name: str :param folder_name: The folder to forward the email from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :rtype: str :returns: The id of the email just created and sent.

Example:: forward_email(“1234567890abcdef”, [”user1@meta.com”, “user2@meta.com”], “INBOX”)
Return type:: str

download_attachments(email_id, folder_name='INBOX', path_to_save='Downloads/')[source]

Downloads attachments from an email. :type email_id: str :param email_id: The id of the email to download. :type folder_name: str :param folder_name: The folder to download the email from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :type path_to_save: str :param path_to_save: The path to save the attachments to. :rtype: list[str] :returns: The list of full path to the downloaded attachments.

Example:: download_attachments(“1234567890abcdef”, “INBOX”, “Downloads/”)
Return type:: list[str]

reply_to_email(email_id, folder_name='INBOX', content='', attachment_paths=None)[source]

Replies to an email. :type email_id: str :param email_id: The id of the email to reply to, the Id is specified in the email details. :type folder_name: str :param folder_name: The folder to reply to the email from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :type content: str :param content: The content of the reply. :type attachment_paths: Optional[list[str]] :param attachment_paths: The paths of the attachments to add to the reply. :rtype: str :returns: The id of the email just created and sent.

Example:: reply_to_email(“1234567890abcdef”, “INBOX”, “Hi there”, [“tmp123/file1.txt”, “tmp234/file2.txt”])
Return type:: str

move_email(email_id, source_folder_name='INBOX', dest_folder_name='DRAFT')[source]

Moves an email from one folder to another. :type email_id: str :param email_id: The id of the email to move. :type source_folder_name: str :param source_folder_name: The folder to move the email from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :type dest_folder_name: str :param dest_folder_name: The folder to move the email to: INBOX, SENT, DRAFT, TRASH. Defaults to DRAFT. :rtype: str :returns: The id of the email just moved, if successful, otherwise raise ValueError.

Example:: move_email(“1234567890abcdef”, “INBOX”, “DRAFT”)
Return type:: str

delete_email(email_id, folder_name='INBOX')[source]

Deletes an email from the specified folder. :type email_id: str :param email_id: The id of the email to delete. :type folder_name: str :param folder_name: The folder to delete the email from: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :rtype: str :returns: The id of the email just deleted, if successful, otherwise raise ValueError.

Example:: delete_email(“1234567890abcdef”, “INBOX”)
Return type:: str

search_emails(query, folder_name='INBOX')[source]

Searches for emails across all folders based on a query string. The search looks for partial matches in sender, recipients, subject, and content. :type query: str :param query: The search query string :type folder_name: str :param folder_name: The folder to search in: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :rtype: list[Email] :returns: A list of emails that match the query.

Example:: search_emails(“hello”, “INBOX”)
Return type:: list[Email]

delete_future_data(timestamp)[source]

class are.simulation.apps.email_client.Mail(name='Mail', view_limit=5, folders=<factory>, user_email='user@meta.com')[source]

Bases: EmailClientApp

The app maintains emails in different folders (INBOX, SENT, DRAFT, TRASH) and provides various operations for email manipulation and searching.

name: str | None = 'Mail'

class are.simulation.apps.email_client.EmailClientV2(name=None, view_limit=5, folders=<factory>, user_email='user@meta.com', internal_fs=None)[source]

Bases: EmailClientApp

internal_fs: SandboxLocalFileSystem | VirtualFileSystem | None = None

connect_to_protocols(protocols)[source]

App can connect to other apps via protocols.

Return type:: None

add_attachment(email, attachment_path)[source]

Adds an attachment to an email. :type email: Email :param email: The email to add the attachment to. :type attachment_path: str :param attachment_path: The path to the attachment to add. :param folder_name: The folder to add the attachment to: INBOX, SENT, DRAFT, TRASH. Defaults to INBOX. :rtype: None :returns: None

send_email(recipients=None, subject='', content='', cc=None, attachment_paths=None)[source]

Example:: send_email([”user1@meta.com”, “user2@meta.com”], “Hello”, “Hi there”, [”user3@meta.com”], [“tmp123/file1.txt”, “tmp234/file2.txt”])
Return type:: str

download_attachments(email_id, folder_name='INBOX', path_to_save='Downloads/')[source]

Example:: download_attachments(“1234567890abcdef”, “INBOX”, “Downloads/”)
Return type:: list[str]

reply_to_email(email_id, folder_name='INBOX', content='', attachment_paths=None)[source]

Example:: reply_to_email(“1234567890abcdef”, “INBOX”, “Hi there”, [“tmp123/file1.txt”, “tmp234/file2.txt”])
Return type:: str

reply_to_email_from_user(sender, email_id, content='', attachment_paths=None)[source]

Example:: reply_to_email_from_user(”other_user@meta.com”, “1234567890abcdef”, “Hello, this is a reply to your email.”)
Return type:: str

Bases: object

sender: str = 'user@meta.com'

recipients: list[str]

subject: str = ''

content: str = ''

email_id: str

parent_id: str | None = None

cc: list[str]

attachments: dict[str, bytes] | None

timestamp: float

is_read: bool = False

property summary

add_attachment(path)[source]

class are.simulation.apps.email_client.ReturnedEmails(emails, emails_range, total_returned_emails, total_emails)[source]

Bases: object

emails: list[Email]

emails_range: tuple[int, int]

total_returned_emails: int

total_emails: int

class are.simulation.apps.email_client.EmailFolder(folder_name)[source]

Bases: object

add_email(email)[source]

get_emails(offset=0, limit=5)[source]

Return type:: ReturnedEmails

get_email(idx=0)[source]

Return type:: Email

get_email_by_id(email_id)[source]

Return type:: Email

get_state()[source]

Return type:: dict[str, Any]

load_state(state_dict)[source]

class are.simulation.apps.email_client.EmailFolderName(value)[source]

Bases: Enum

An enumeration.

INBOX = 'INBOX'

SENT = 'SENT'

DRAFT = 'DRAFT'

TRASH = 'TRASH'

Messaging

class are.simulation.apps.messaging.Message(sender, message_id=<factory>, timestamp=<factory>, content='')[source]

Bases: object

sender: str

message_id: str

timestamp: float

content: str = ''

class are.simulation.apps.messaging.FileMessage(sender, message_id=<factory>, timestamp=<factory>, content='', attachment=None, attachment_name=None)[source]

Bases: Message

attachment: bytes | None = None

attachment_name: str | None = None

class are.simulation.apps.messaging.Conversation(participants, messages=<factory>, title='', conversation_id=<factory>, last_updated=<factory>)[source]

Bases: object

participants: list[str]

messages: list[Message]

title: str | None = ''

conversation_id: str

last_updated: float

property summary

update_last_updated(timestamp)[source]

load_state(state_dict)[source]

get_messages_in_date_range(start_date, end_date)[source]

Return type:: list[Message]

class are.simulation.apps.messaging.MessagingApp(name=None, conversations=<factory>, messages_view_limit=10, conversation_view_limit=5)[source]

Bases: App

A messaging application that provides comprehensive functionality for managing conversations, messages, and file attachments. This class implements a chat system with support for individual and group conversations, message history, and file sharing capabilities.

The MessagingApp maintains conversations as a dictionary of Conversation objects, where each conversation has unique identifiers, participants, messages, and metadata. The system supports both text messages and file attachments with configurable view limits.

Key Features: - Conversation Management: Create, list, and search conversations - Messaging: Send text messages and file attachments - Participant Management: Add/remove participants to conversations - File Handling: Send and download file attachments - Search Functionality: Search across conversations, participants, and messages - View Limits: Configurable limits for messages and conversation listings - State Management: Save and load application state

Conversation Features: - Unique conversation IDs - Optional conversation titles - Participant management - Message history with timestamps - Last updated tracking - File attachment support

Notes: - The current user is automatically added as “Me” to all conversations - Messages are sorted by timestamp, most recent first - File attachments are handled using base64 encoding - Search operations are case-insensitive - Conversations maintain participant lists and message history - All operations are tracked through event registration - Messages can be paginated using offset and limit parameters

name: str | None = None

conversations: dict[str, Conversation]

messages_view_limit: int = 10

conversation_view_limit: int = 5

get_state()[source]

Return type:: dict[str, Any]

load_state(state_dict)[source]

load_conversations_from_dict(conversations_dict)[source]

reset()[source]

add_conversation(conversation)[source]

Add a conversation to the app. :type conversation: Conversation :param conversation: The conversation to add.

Return type:: None

add_conversations(conversations)[source]

Add a list of conversations to the app. :type conversations: list[Conversation] :param conversations: The conversations to add.

Return type:: None

create_conversation(participants, title=None)[source]

Create a new conversation with the given participants. If title is not provided, it will be set to the participants. :type participants: list[str] :param participants: List of participants in the conversation, these are the full names of the contacts. The current user is “Me” and will be added automatically. :type title: Optional[str] :param title: Optional title for the conversation :rtype: str :returns: Id of the created conversation

Example:: create_conversation([“John Doe”, “Jane Doe”, “Bob Roberts”], “My group chat”)
Return type:: str

apply_conversation_limits(conversations, offset_recent_messages_per_conversation, limit_recent_messages_per_conversation)[source]

Return type:: list[Conversation]

list_recent_conversations(offset=0, limit=5, offset_recent_messages_per_conversation=0, limit_recent_messages_per_conversation=5)[source]

List conversations ordered by the most recent modification, considering an offset and view limit. e.g. list_recent_conversations(0, 5) will list the 5 most recent conversations. :type offset: int :param offset: The starting index from which to list conversations :type limit: int :param limit: The number of conversations to list, this number needs to be small otherwise an error will be raised :type offset_recent_messages_per_conversation: int :param offset_recent_messages_per_conversation: The starting index from which to list messages in each conversation :type limit_recent_messages_per_conversation: int :param limit_recent_messages_per_conversation: The number of messages to list in each conversation, this number needs to :rtype: list[Conversation] :returns: List of Conversation details

Example:: list_recent_conversations(0, 5)
Return type:: list[Conversation]

list_conversations_by_participant(participant, offset=0, limit=5, offset_recent_messages_per_conversation=0, limit_recent_messages_per_conversation=5)[source]

List all the conversations with the given participant. :type participant: str :param participant: Participant name in the conversation :type offset: int :param offset: The starting index from which to list conversations :type limit: int :param limit: The number of conversations to list, this number needs to be small otherwise an error will be raised :type offset_recent_messages_per_conversation: int :param offset_recent_messages_per_conversation: The starting index from which to list messages in each conversation :type limit_recent_messages_per_conversation: int :param limit_recent_messages_per_conversation: The number of messages to list in each conversation, this number needs to be small otherwise an error will be raised :rtype: list[Conversation] :returns: List of Conversation details

Example:: list_conversations_by_participant(“John Doe”, 0, 5)
Return type:: list[Conversation]

send_message(conversation_id, content='')[source]

Send a message to the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id to send the message to :type content: str :param content: Message content :rtype: str :returns: Id of the sent message

Example:: send_message(“1234567890abcdef”, “Hello world!”)
Return type:: str

send_attachment(conversation_id, filepath)[source]

Send an attachment to the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type filepath: str :param filepath: Path to the attachment to send :rtype: str :returns: Message id of the sent attachment

Example:: send_attachment(“1234567890abcdef”, “/path/to/attachment.txt”)
Return type:: str

download_attachment(conversation_id, message_id, download_path='Downloads/')[source]

Download an attachment from the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type message_id: str :param message_id: Message id :type download_path: str :param download_path: Path to download the attachment to :rtype: str :returns: Full path to the downloaded attachment if successful, otherwise raise Exception

Example:: download_attachment(“1234567890abcdef”, “abcdef1234567890”, “Downloads/”)
Return type:: str

add_message(conversation_id, sender, content, timestamp=None)[source]

Send a message to the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type content: str :param content: Message content :rtype: None :returns: None

create_and_add_message(conversation_id, sender, content)[source]

Send a message to the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type sender: str :param sender: Sender of the message. If the sender is the user, it should be “Me” :type content: str :param content: Message content :rtype: str :return: conversation id if successful, otherwise raise Exception.

Return type:: str

add_message_with_time(conversation_id, sender, content, message_time='2025-09-23 19:17:53')[source]

Send a message to the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type sender: str :param sender: Sender of the message :type content: str :param content: Message content :type message_time: str :param message_time: Time of the message in YYYY-MM-DD HH:MM:SS format :rtype: str :return: conversation id if successful, otherwise raise Exception.

Return type:: str

delete_future_data(timestamp)[source]

Delete all messages with timestamp greater than the given timestamp. :type timestamp: float :param timestamp: Timestamp to delete messages after

Return type:: None

read_conversation(conversation_id, offset=0, limit=10)[source]

Example:: read_conversation(“1234567890abcdef”, 0, 10)
Return type:: dict

add_participant_to_conversation(conversation_id, participant)[source]

Add a participant to the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id to be updated :type participant: str :param participant: Full name of the participant to be added :rtype: str :returns: conversation_id of the conversation just updated, if successful, otherwise raise Exception.

Example:: add_participant_to_conversation(“1234567890abcdef”, “John Doe”)
Return type:: str

remove_participant_from_conversation(conversation_id, participant)[source]

Remove a participant from the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type participant: str :param participant: Full name of the participant to be removed :rtype: str :returns: conversation_id of the conversation just updated, if successful, otherwise raise Exception.

Example:: remove_participant_from_conversation(“1234567890abcdef”, “John Doe”)
Return type:: str

get_all_conversations()[source]

Get all conversations. :rtype: list[Conversation] :returns: List of Conversation objects

Return type:: list[Conversation]

search(query, min_date=None, max_date=None)[source]

Search for conversations that match the given query. The search is performed on conversation participants, titles, and message content. Returns the Ids of the matching conversations. :type query: str :param query: The search query string :type min_date: Optional[str] :param min_date: Minimum date of the messages to be searched (YYYY-MM-DD %H:%M:%S format). Defaults to None (no minimum date). :type max_date: Optional[str] :param max_date: Maximum date of the messages to be searched (YYYY-MM-DD %H:%M:%S format). Defaults to None (no maximum date). :rtype: list[str] :returns: List of matching Conversation Ids

Example:: search(“Taylor Swift”)
Return type:: list[str]

regex_search(query, min_date=None, max_date=None)[source]

Search for conversations that match the given regex query (case insensitive). The search is performed on conversation participants, titles, and message content. Returns the Ids of the matching conversations. :type query: str :param query: The search query string :type min_date: Optional[str] :param min_date: Minimum date of the messages to be searched (YYYY-MM-DD %H:%M:%S format). Defaults to None (no minimum date). :type max_date: Optional[str] :param max_date: Maximum date of the messages to be searched (YYYY-MM-DD %H:%M:%S format). Defaults to None (no maximum date). :rtype: list[str] :returns: List of matching Conversation Ids

Example:: regex_search(“Taylor Swift”)
Return type:: list[str]

class are.simulation.apps.messaging.Conversation(participants, messages=<factory>, title='', conversation_id=<factory>, last_updated=<factory>)[source]

Bases: object

participants: list[str]

messages: list[Message]

title: str | None = ''

conversation_id: str

last_updated: float

property summary

update_last_updated(timestamp)[source]

load_state(state_dict)[source]

get_messages_in_date_range(start_date, end_date)[source]

Return type:: list[Message]

class are.simulation.apps.messaging.Message(sender, message_id=<factory>, timestamp=<factory>, content='')[source]

Bases: object

sender: str

message_id: str

timestamp: float

content: str = ''

Messaging V2

class are.simulation.apps.messaging_v2.MessageV2(sender_id, message_id=<factory>, timestamp=<factory>, content='')[source]

Bases: object

sender_id: str

message_id: str

timestamp: float

content: str = ''

class are.simulation.apps.messaging_v2.FileMessageV2(sender_id, message_id=<factory>, timestamp=<factory>, content='', attachment=None, attachment_name=None)[source]

Bases: MessageV2

attachment: bytes | None = None

attachment_name: str | None = None

class are.simulation.apps.messaging_v2.ConversationV2(participant_ids, messages=<factory>, title=None, conversation_id=<factory>, last_updated=<factory>)[source]

Bases: object

participant_ids: list[str]

messages: list[MessageV2]

title: str | None = None

conversation_id: str

last_updated: float

property summary

update_last_updated(timestamp)[source]

load_state(state_dict)[source]

get_messages_in_date_range(start_date, end_date)[source]

Return type:: list[MessageV2]

class are.simulation.apps.messaging_v2.MessagingAppMode(value)[source]

Bases: Enum

Enum for MessagingApp modes

NAME = 'NAME'

PHONE_NUMBER = 'PHONE_NUMBER'

class are.simulation.apps.messaging_v2.MessagingAppV2(current_user_id=None, current_user_name=None, name=None, mode=MessagingAppMode.NAME, id_to_name=<factory>, name_to_id=<factory>, conversations=<factory>, messages_view_limit=10, conversation_view_limit=5, internal_fs=None)[source]

Bases: App

Conversation Features: - Unique conversation IDs - Optional conversation titles - Participant management - Message history with timestamps - Last updated tracking - File attachment support

current_user_id: str | None = None

current_user_name: str | None = None

name: str | None = None

mode: MessagingAppMode = 'NAME'

id_to_name: dict[str, str]

name_to_id: dict[str, str]

conversations: dict[str, ConversationV2]

messages_view_limit: int = 10

conversation_view_limit: int = 5

internal_fs: SandboxLocalFileSystem | VirtualFileSystem | None = None

connect_to_protocols(protocols)[source]

App can connect to other apps via protocols.

Return type:: None

get_state()[source]

Return type:: dict[str, Any]

load_state(state_dict)[source]

load_conversations_from_dict(conversations_dict)[source]

reset()[source]

add_users(user_names)[source]

add_contacts(contacts)[source]

get_user_id(user_name)[source]

Get the user id for a given user name, the name must match EXACTLY, otherwise this returns None. :type user_name: str :param user_name: user name :rtype: str | None :returns: user id

Return type:: str | None

get_user_ids(user_names)[source]

Return type:: list[str | None]

get_user_name_from_id(user_id)[source]

Get the user name for a given user id, the id must match EXACTLY, otherwise returns None. :type user_id: str :param user_id: user id :rtype: str | None :returns: user name

Return type:: str | None

get_user_names(user_ids)[source]

Return type:: list[str | None]

lookup_user_id(user_name)[source]

Lookup the user id for a given user name, this is an fuzzy string based search so what is returned might not be exactly the query returns Dictionary of user name to user id, for people names that are close enough to the query user_name. dictionary will be empty if no matches are found :type user_name: str :param user_name: user name to lookup :rtype: dict[str, str] :returns: Dictionary of user name to user id, for people names that are close enough to the query user_name

Return type:: dict[str, str]

add_conversation(conversation)[source]

Add a conversation to the app. :type conversation: ConversationV2 :param conversation: The conversation to add.

Return type:: None

add_conversations(conversations)[source]

Add a list of conversations to the app. :type conversations: list[ConversationV2] :param conversations: The conversations to add.

Return type:: None

send_message(user_id, content='', attachment_path=None)[source]

Send a message to the specified recipient, if an existing conversation with the same recipient exists, the message will be added to that conversation, otherwise a new conversation will be created. This is the only way to send a message to a single person.

Parameters:

user_id (str) – The recipient id to send the message to
content (str) – The message content.
attachment_path (Optional[str]) – Optional path to an attachment file to send with the message.

Return type:

str

Returns:

a str, “conversation_id”: Id of the conversation the message was sent to

send_message_to_group_conversation(conversation_id, content='', attachment_path=None)[source]

Send a message to an existing group conversation.

Parameters:

conversation_id (str) – The conversation id to send the message to
content (str) – The message content.
attachment_path (Optional[str]) – Optional path to an attachment file to send with the message.

Return type:

str

Returns:

a str, “conversation_id”: Id of the conversation the message was sent to

create_group_conversation(user_ids, title=None)[source]

Create a new group conversation with the given participants. There must be at least two participants participants other than the current user. If title is not provided, it will be set to the participant names. :type user_ids: list[str] :param user_ids: List of Ids of the participants in the conversation. The current user is automatically added. :type title: Optional[str] :param title: Optional title for the conversation :rtype: str :returns: Id of the created conversation

Return type:: str

get_existing_conversation_ids(user_ids)[source]

Get the list of conversation ids for the given participants. :type user_ids: list[str] :param user_ids: List of Ids of the participants in the conversation. The current user is automatically added. :rtype: list[str] :returns: List of Ids of the conversations

Return type:: list[str]

apply_conversation_limits(conversations, offset_recent_messages_per_conversation, limit_recent_messages_per_conversation)[source]

Return type:: list[ConversationV2]

list_recent_conversations(offset=0, limit=5, offset_recent_messages_per_conversation=0, limit_recent_messages_per_conversation=10)[source]

List conversations ordered by the most recent modification, considering an offset and view limit. e.g. list_recent_conversations(0, 5) will list the 5 most recent conversations. :type offset: int :param offset: The starting index from which to list conversations :type limit: int :param limit: The number of conversations to list, this number needs to be small otherwise an error will be raised :type offset_recent_messages_per_conversation: int :param offset_recent_messages_per_conversation: The starting index from which to list messages per conversation :type limit_recent_messages_per_conversation: int :param limit_recent_messages_per_conversation: The number of messages to list per conversation, this number needs to be small otherwise an error will be raised :rtype: list[ConversationV2] :returns: List of Conversation details

Example:: list_recent_conversations(0, 5)
Return type:: list[ConversationV2]

list_conversations_by_participant(user_id, offset=0, limit=5, offset_recent_messages_per_conversation=0, limit_recent_messages_per_conversation=5)[source]

List all the conversations with the given participant. :type user_id: str :param user_id: User Id of the participant in the conversation :type offset: int :param offset: The starting index from which to list conversations :type limit: int :param limit: The number of conversations to list, this number needs to be small otherwise an error will be raised :type offset_recent_messages_per_conversation: int :param offset_recent_messages_per_conversation: The starting index from which to list messages per conversation :type limit_recent_messages_per_conversation: int :param limit_recent_messages_per_conversation: The number of messages to list per conversation, this number needs to be small otherwise an error will be raised :rtype: list[ConversationV2] :returns: List of Conversation details

Example:: list_conversations_by_participant(“1234-abcde”, 0, 5)
Return type:: list[ConversationV2]

download_attachment(conversation_id, message_id, download_path='Downloads/')[source]

Example:: download_attachment(“1234567890abcdef”, “abcdef1234567890”, “Downloads/”)
Return type:: str

add_message(conversation_id, sender_id, content, timestamp=None)[source]

Send a message to the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type sender_id: str :param sender_id: Sender id :type content: str :param content: Message content :type timestamp: Optional[float] :param timestamp: Timestamp of the message, if not provided, will be set to current time :rtype: None :returns: None

create_and_add_message(conversation_id, sender_id, content)[source]

read_conversation(conversation_id, offset=0, limit=10, min_date=None, max_date=None)[source]

Read the conversation with the given conversation_id. Shows the last ‘limit’ messages after offset. Which means messages between offset and offset + limit will be shown. Messages are sorted by timestamp, most recent first. :type conversation_id: str :param conversation_id: Conversation id :type offset: int :param offset: Offset to shift the view window :type limit: int :param limit: Number of messages to show :type min_date: Optional[str] :param min_date: Minimum date of the messages to be shown (YYYY-MM-DD %H:%M:%S format). Default is None, which means no minimum date. :type max_date: Optional[str] :param max_date: Maximum date of the messages to be shown (YYYY-MM-DD %H:%M:%S format). Default is None, which means no maximum date. :rtype: dict :returns: Dict with messages and additional info

Example:: read_conversation(“1234567890abcdef”, 0, 10)
Return type:: dict

add_participant_to_conversation(conversation_id, user_id)[source]

Add a user to the conversation with the given conversation_id and updates the title if title is list of participants. :type conversation_id: str :param conversation_id: Conversation id to be updated :type user_id: str :param user_id: Id of the Participant to be added :rtype: str :returns: conversation_id of the conversation just updated, if successful, otherwise raise Exception.

Return type:: str

remove_participant_from_conversation(conversation_id, user_id)[source]

Remove a participant from the conversation with the given conversation_id and updates the title if title is list of participants. :type conversation_id: str :param conversation_id: Conversation id :type user_id: str :param user_id: Id of the Participant to be removed :rtype: str :returns: conversation_id of the conversation just updated, if successful, otherwise raise Exception.

Return type:: str

change_conversation_title(conversation_id, title)[source]

Change the title of the conversation with the given conversation_id. :type conversation_id: str :param conversation_id: Conversation id :type title: str :param title: New title for the conversation :rtype: str :returns: conversation_id of the conversation just updated, if successful, otherwise raise Exception.

Example:: change_conversation_title(“1234567890abcdef”, “My new title”)
Return type:: str

get_all_conversations()[source]

Get all conversations. :rtype: list[ConversationV2] :returns: List of Conversation objects

Return type:: list[ConversationV2]

get_default_title(user_ids)[source]

Get the default title for a conversation with the given participants. :type user_ids: list[str] :param user_ids: List of Ids of the participants in the conversation, these are the names of the contacts, current user is automatically added :rtype: str :returns: Default title for the conversation

Return type:: str

search(query, min_date=None, max_date=None)[source]

Example:: search(“Taylor Swift”)
Return type:: list[str]

regex_search(query, min_date=None, max_date=None)[source]

Example:: regex_search(“Taylor Swift”)
Return type:: list[str]

get_tools_with_attribute(attribute, tool_type)[source]

Here we add to the description of every tool that the Ids are Phone numbers for MessagingAppMode.PHONE_NUMBER and User Ids for MessagingAppMode.NAME

Return type:: list[AppTool]

class are.simulation.apps.messaging_v2.ConversationV2(participant_ids, messages=<factory>, title=None, conversation_id=<factory>, last_updated=<factory>)[source]

Bases: object

participant_ids: list[str]

messages: list[MessageV2]

title: str | None = None

conversation_id: str

last_updated: float

property summary

update_last_updated(timestamp)[source]

load_state(state_dict)[source]

get_messages_in_date_range(start_date, end_date)[source]

Return type:: list[MessageV2]

class are.simulation.apps.messaging_v2.MessageV2(sender_id, message_id=<factory>, timestamp=<factory>, content='')[source]

Bases: object

sender_id: str

message_id: str

timestamp: float

content: str = ''

Agent User Interface

class are.simulation.apps.agent_user_interface.Sender(value)[source]

Bases: Enum

An enumeration.

USER = 'User'

AGENT = 'Agent'

class are.simulation.apps.agent_user_interface.AUIMessage(sender, content, attachments=<factory>, timestamp=<factory>, time_read=None, id=None)[source]

Bases: object

sender: Sender

content: str

attachments: list[str]

timestamp: float

time_read: float | None = None

id: str | None = None

property already_read: bool

class are.simulation.apps.agent_user_interface.AgentUserInterface(user_proxy=None)[source]

Bases: App

The Agent User Interface (AUI) is a tool for facilitating interactions between a user and an agent. This interface provides methods to exchange messages, retrieve conversation history, and manage the flow of communication, including support for simulated user responses through a proxy.

The AgentUserInterface manages message exchanges in a list structure, storing messages from both the user and the agent, which can be accessed and filtered by various criteria. It allows for message persistence, tracking unread messages, and retrieving conversation history, along with environment control for CLI or GUI-based interactions.

Key Features:

Message Exchange: Send and retrieve messages from user and agent
User Proxy Support: Simulate user responses using an optional proxy for testing or automation
Unread Message Tracking: Retrieve unread messages from conversation history
Environment Control: Pause and resume environment during user-agent interactions
State Management: Access conversation state with methods to fetch and filter messages

Notes:

Messages are stored in a list and ordered chronologically
Supports CLI or GUI-based environments for real-time user input handling
The user proxy allows simulated responses for automated testing without real user input
Methods provide options to retrieve last messages or all messages by sender (user or agent)
State can be retrieved as a dictionary, preserving message history and interaction details

Initializes the Agent User Interface. :type user_proxy: Optional[UserProxy] :param user_proxy: The user proxy to use for simulating user responses.

set_wait_for_user_response(wait_for_user_response)[source]

get_state()[source]

Return type:: dict[str, Any]

reset()[source]

load_state(state_dict)[source]

set_cli(is_cli)[source]

add_message_to_user(content)[source]

Adds a message to be displayed to the user. This function does not generate an event, it just modifies the app state. This function is intended to be invoked from other app functions to display results from those events as user messages. :type content: str :param content: The message content to send to the user.

Return type:: None

send_message_to_user(content='')[source]

Sends a message to the User. This will end the Agent’s turn. :type content: str :param content: the content to send to the user :rtype: str | None :returns: The response from the user

Return type:: str | None

send_message_to_agent(content='', attachments=None, base64_utf8_encoded_attachment_contents=None)[source]

Sends a message to the Agent. :type content: str :param content: the content to send to the agent :type attachments: Optional[list[str]] :param attachments: optional; a list of attachments to send to the agent, each of them is a URL to a file :type base64_utf8_encoded_attachment_contents: Optional[list[dict[str, Any]]] :param base64_utf8_encoded_attachment_contents: optional; attachment contents corresponding to the attachments parameter. An entry may be an empty dict if an empty file was passed in. :rtype: str :return: The message ID that was generated for this message, can be used for tracking

Return type:: str

get_last_message_from_user()[source]

Retrieves the last message that was sent from the User to the Agent. :rtype: AUIMessage | None :returns: the last message from the user or None if no messages have been sent

Return type:: AUIMessage | None

get_last_unread_messages()[source]

Retrieves all unread messages from the User and Agent conversation. :rtype: list[AUIMessage] :returns: a list of all unread messages or an empty list if all messages have been read

Return type:: list[AUIMessage]

get_last_message_from_agent()[source]

Retrieves the last message that was sent from the Agent to the User. :rtype: AUIMessage | None :returns: the last message from the agent or None if no messages have been sent

Return type:: AUIMessage | None

get_all_messages()[source]

Retrieves all messages from the User and Agent conversation. :rtype: list[AUIMessage] :returns: a list of all messages

Return type:: list[AUIMessage]

send_user_message_to_agent(content, pause_func, wait_for_user_input_timeout=None)[source]

Send a user response to the agent. :type content: str :param content: the message content to be sent from the user to the agent :param environment_type: the environment type :type pause_func: Callable :param pause_func: the function to pause the environment :type wait_for_user_input_timeout: Optional[float] :param wait_for_user_input_timeout: optional; the maximum time in seconds to wait for user input. Specify 0 to not wait, or None to wait indefinitely :returns: None

get_all_messages_from_user()[source]

Retrieves all messages from the User. :rtype: list[AUIMessage] :returns: a list of all messages as strings

Return type:: list[AUIMessage]

get_all_messages_from_agent()[source]

Retrieves all messages from Agent. :rtype: list[AUIMessage] :returns: a list of all messages as strings

Return type:: list[AUIMessage]

get_last_message_content()[source]

Retrieves the last message content. :rtype: str :returns: the content of the last message

Return type:: str

get_last_message()[source]

Retrieves the last message. :rtype: AUIMessage | None :returns: the last message

Return type:: AUIMessage | None

pause_env()[source]: Pauses the environment, this is used to stop the environment from running while the user is interacting with the Agent.

resume_env()[source]: Resumes the environment, this is used to resume the environment after the user is done interacting with the Agent.

are.simulation.apps.agent_user_interface.countdown_input(prompt, timeout)[source]

System Apps ¶

File System

class are.simulation.apps.sandbox_file_system.Files(name=None, sandbox_dir=None)

Bases: SandboxLocalFileSystem

A sandboxed local file system that restricts operations to a temporary directory, providing an isolated and controlled environment for file and directory manipulations. This class offers functionality for creating, reading, updating, and deleting files and directories, as well as methods for saving and restoring file system states.

The Files ensures that all operations are confined to a designated temporary directory, preventing access outside the sandbox. It maintains compatibility with standard file system operations and integrates support for event logging and tool registration for enhanced tracking.

Key Features:

File and Directory Management: Create, open, list, move, and remove files and directories
Path Validation: Ensures operations remain within the designated sandbox directory
State Management: Save and load file system state for repeatability and restoration
Random Sampling: Retrieve random samples of files or folders within the sandbox
Permissions Management: Set permissions for files and directories
Event Logging: Integrated event tracking for operations

Notes:

The file system is non-cacheable to ensure isolated instances across parallel executions
Temporary directory paths are converted to absolute paths if necessary
Directories can be populated programmatically using specified population methods
Operations attempting to access paths outside the sandbox will raise a PermissionError
File system state can be saved and reloaded for scenario-based testing or persistence

class are.simulation.apps.sandbox_file_system.FinalMeta(name, bases, namespace, **kwargs): Bases: _Cached, ABCMeta

class are.simulation.apps.sandbox_file_system.SandboxLocalFileSystem(name=None, sandbox_dir=None, state_directory='hf://datasets/meta-agents-research-environments/gaia2_filesystem/demo_filesystem')

Bases: App, AbstractFileSystem

The SandboxLocalFileSystem ensures that all operations are confined to a designated temporary directory, preventing access outside the sandbox. It maintains compatibility with standard file system operations and integrates support for event logging and tool registration for enhanced tracking.

Key Features:

File and Directory Management: Create, open, list, move, and remove files and directories
Path Validation: Ensures operations remain within the designated sandbox directory
State Management: Save and load file system state for repeatability and restoration
Random Sampling: Retrieve random samples of files or folders within the sandbox
Permissions Management: Set permissions for files and directories
Event Logging: Integrated event tracking for operations

Notes:

The file system is non-cacheable to ensure isolated instances across parallel executions
Temporary directory paths are converted to absolute paths if necessary
Directories can be populated programmatically using specified population methods
Operations attempting to access paths outside the sandbox will raise a PermissionError
File system state can be saved and reloaded for scenario-based testing or persistence

cachable = False

cat(path, recursive=False, on_error='raise', **kwargs)

Read the contents of a file. :type path: str :param path: path to the file to read :type recursive: bool :param recursive: If True, recursively read files in directories :type on_error: str :param on_error: What to do on error (‘raise’ or ‘omit’) :type kwargs: dict[str, Any] :param kwargs: additional arguments to pass to the file system :rtype: str | bytes :returns: contents of the file, read from with mode ‘rb’

Example:: cat(“/path/to/file.txt”)
Return type:: str | bytes

display(path)

Displays the file at the given path in the UI, but it will not be added to the agent context. :type path: str :param path: path to the file to display :rtype: bool :returns: True if the file exists, False if the file does not exist

Example:: display(“/path/to/file.txt”)
Return type:: bool

exists(path, **kwargs)

Check if a file or directory exists. :type path: str :param path: path to the file or directory to check :type kwargs: dict[str, Any] :param kwargs: additional arguments to pass to the file system :returns: True if the file or directory exists, False otherwise

Example:: exists(“/path/to/file.txt”)

get_file_content(path)

Read the contents of a file. :type path: str :param path: path to the file to read :rtype: bytes :returns: contents of the file

Return type:: bytes

get_file_paths_list()

This function returns a list of all files in the file system. :rtype: Iterable[str] :returns: list of file paths

Return type:: Iterable[str]

get_folder_paths_list()

This function returns the list of all folders in the file system. :rtype: Iterable[str] :returns: list of folder paths

Return type:: Iterable[str]

get_implemented_protocols()

App can provide protocols, e.g. FileSystem which could be used by other apps Returns a list of protocol names that the app implements.

Return type:: list[Protocol]

get_sample_files(k=1, seed=0)

This function returns a list of randomly selected files. :type k: int :param k: number of files to return :type seed: int :param seed: seed for random number generation :rtype: list[str] :returns: list of file paths (relative to sandbox root)

Return type:: list[str]

get_sample_folders(k=1, seed=0)

This function returns a list of randomly selected folders. :type k: int :param k: number of folders to return :type seed: int :param seed: seed for random number generation :rtype: list[str] :returns: list of folder paths

Return type:: list[str]

get_state()

Return type:: dict[str, Any]

info(path, **kwargs)

Get information about a file or directory. :type path: str :param path: path to the file or directory to get information about :type kwargs: dict[str, Any] :param kwargs: additional arguments to pass to the file system :rtype: dict[str, Any] :returns: information about the file or directory

Example:: info(“/path/to/file.txt”)
Return type:: dict[str, Any]

load_directory_from_path(from_dir, to_dir)

This function restores the file system from a given path. :param path: path to the directory containing the file system. :param target_dir: target directory to load the files to.

load_file_system_from_path(path)

This function restores the file system from a given path. :type path: str :param path: path to the directory containing the file system.

load_file_system_state(state_name)

This function restores the file system to the state saved with the save_file_system_state function. Uses lazy loading to avoid copying all files immediately. :type state_name: str :param state_name: name of the state to restore.

load_state(state_dict)

ls(path='.', detail=False, **kwargs)

List the contents of a directory. :type path: str :param path: path to list, defaults to ‘.’ :type detail: bool :param detail: if True, return detailed information about each file :type kwargs: dict[str, Any] :param kwargs: additional arguments to pass to the file system :rtype: list[str | dict[str, Any]] :returns: list of files and directories in the directory

Example:: ls(“/path/to/directory”, detail=True)
Return type:: list[str | dict[str, Any]]

makedirs(path, exist_ok=False)

Create a directory and any parent directories if they do not exist. :type path: str :param path: path to the directory to create :type exist_ok: bool :param exist_ok: if True, do not raise an exception if the directory already exists :rtype: None :returns: None

Example:: makedirs(“/path/to/nested/directory”, exist_ok=True)

mkdir(path, create_parents=True, **kwargs)

Create a directory. :type path: str :param path: path to the directory to create :type create_parents: bool :param create_parents: if True, create parent directories if they do not exist :type kwargs: dict[str, Any] :param kwargs: additional arguments to pass to the file system :rtype: None :returns: None

Example:: mkdir(“/path/to/directory”)

mv(path1, path2, recursive=False, maxdepth=None, **kwargs)

Move a file or directory. :type path1: str :param path1: path to the file or directory to move :type path2: str :param path2: path to the destination :type recursive: bool :param recursive: If True, move directories recursively :type maxdepth: Optional[int] :param maxdepth: Maximum depth to recurse when recursive=True :type kwargs: dict[str, Any] :param kwargs: additional arguments to pass to the file system :rtype: None :returns: None

Example:: mv(“/path/to/source.txt”, “/path/to/destination.txt”)

open(path, mode='rb', block_size=None, cache_options=None, compression=None, **kwargs)

Open a file for reading or writing. :type path: str :param path: path to the file to open :type mode: str :param mode: mode to open the file in :type block_size: Optional[int] :param block_size: Size of blocks to read/write :type cache_options: Optional[dict] :param cache_options: Cache options :type compression: Optional[str] :param compression: Compression format :type kwargs: dict[str, Any] :param kwargs: additional arguments to pass to the file system :returns: file handle to the opened file

Example:: open(“/path/to/file.txt”, “r”)

populate(pop_method)

read_document(file_path, max_lines=20)

Read and extract text content from various document types including PDFs, Word documents, Excel spreadsheets, PowerPoint presentations, HTML files, and more. Returns the content as structured text. Setting max_lines is highly recommended to avoid long documents and filling up your memory.

Parameters:

file_path (str) – The path to the document file to read
max_lines (int | None) – Maximum number of lines to return. If set to None/null, returns the entire document, default is 20.

Return type:

str

Returns:

The document content as structured text

Example:

read_document(“/Documents/report.pdf”) read_document(“/Documents/data.xlsx”, max_lines=50)

reset()

rm(path, recursive=False, maxdepth=None)

Remove a file or directory. :type path: str :param path: path to the file or directory to remove :type recursive: bool :param recursive: if True, remove the directory and all its contents :type maxdepth: Optional[int] :param maxdepth: Maximum depth to recurse when recursive=True :rtype: None :returns: None

Example:: rm(“/path/to/file.txt”, recursive=False)

rmdir(path)

Remove a directory, if empty

Return type:: None

save_file_system_state(state_name)

This function saves the current state of the file system as is to the shared data storage. :type state_name: str :param state_name: name under which the state will be saved. Reuse this state_name to restore the state.

set_permissions(path, permission)

tree(path='.')

Generate a string representing the directory and file structure in a tree format. :type path: str :param path: Path to start the tree view from, defaults to the root of the sandbox :rtype: str :returns: A string representing the directory tree

Example:: tree(“/path/to/directory”)
Return type:: str

Virtual File System

class are.simulation.apps.virtual_file_system.VirtualFileSystem(name=None)[source]

Bases: App

A proxy class that delegates file system operations to SandboxLocalFileSystem. This class maintains backward compatibility with the original VirtualFileSystem API while using the more comprehensive SandboxLocalFileSystem implementation.

get_implemented_protocols()[source]

App can provide protocols, e.g. FileSystem which could be used by other apps Returns a list of protocol names that the app implements.

Return type:: list[Protocol]

reset()[source]

open(path, mode='rb')[source]

Open a file for reading or writing. :type path: str :param path: path to the file to open :type mode: str :param mode: mode to open the file in :returns: file handle to the opened file

get_file_content(path)[source]

Read the contents of a file. :type path: str :param path: path to the file to read :rtype: bytes :returns: contents of the file

Return type:: bytes

cat(path)[source]

Read the contents of a file. :type path: str :param path: path to the file to read :rtype: bytes :returns: contents of the file as bytes

Return type:: bytes

mkdir(path, create_recursive=True)[source]

Create a directory. :type path: str :param path: path to the directory to create :type create_recursive: bool :param create_recursive: if True, create parent directories if they do not exist :returns: None

mv(path1, path2)[source]

Move a file or directory. :type path1: str :param path1: path to the file or directory to move :type path2: str :param path2: path to the destination :returns: None

ls(path='.', detail=False)[source]

rm(path, recursive=False)[source]

rmdir(path)[source]

Remove a directory. :type path: str :param path: path to the directory to remove :returns: None

exists(path)[source]

Check if a file or directory exists. :type path: str :param path: path to the file or directory to check :returns: True if the file or directory exists, False otherwise

info(path, **kwargs)[source]

tree(path='.')[source]

Return type:: str

load_file_system_from_path(path)[source]

Load file system from a path. :type path: str :param path: path to load the file system from

get_state()[source]

Get the current state of the file system in the original VirtualFileSystem format. This maintains backward compatibility with previously stored states. :rtype: dict[str, Any] :returns: dictionary representing the current state

Return type:: dict[str, Any]

load_state(state_dict)[source]

property tmpdir: str: Get the temporary directory path used by the sandbox file system. For backward compatibility with the SandboxLocalFileSystem API. :returns: path to the temporary directory

Calendar

class are.simulation.apps.calendar.CalendarEvent(event_id=<factory>, title='Event', start_datetime=<factory>, end_datetime=<factory>, tag=None, description=None, location=None, attendees=<factory>, start_strftime=None, end_strftime=None)[source]

Bases: object

event_id: str

title: str = 'Event'

start_datetime: float

end_datetime: float

tag: str | None = None

description: str | None = None

location: str | None = None

attendees: list[str]

start_strftime: str | None = None

end_strftime: str | None = None

property summary

class are.simulation.apps.calendar.CalendarEventsResult[source]

Bases: TypedDict

events: list[CalendarEvent]

range: tuple[int, int]

total: int

class are.simulation.apps.calendar.CalendarApp(name=None, events=<factory>)[source]

Bases: App

A calendar application that manages and manipulates calendar events. This class provides functionality for creating, reading, updating, and deleting calendar events, as well as various utility methods for searching and filtering events.

The CalendarApp maintains events in a dictionary where each event is identified by a unique event_id. All datetime inputs should be in the format “YYYY-MM-DD HH:MM:SS” and are handled in UTC timezone.

Key Features:

Event Management: Add, update, delete, and retrieve calendar events
Time-based Queries: Get events within specific time ranges
Tag Support: Organize and filter events using tags
Search Functionality: Search events across multiple fields
State Management: Save and load calendar state

Notes:

All datetime operations are performed in UTC timezone
Event IDs are automatically generated when creating new events
The class supports state persistence through save/load operations
Search operations are case-insensitive
Empty tags are not allowed when filtering by tag

name: str | None = None

events: dict[str, CalendarEvent]

get_state()[source]

Return type:: dict[str, Any]

load_state(state_dict)[source]

reset()[source]

load_calendar_events_from_file(path)[source]

load_calendar_events_from_dict(events)[source]

add_calendar_event(title='Event', start_datetime=None, end_datetime=None, tag=None, description=None, location=None, attendees=None)[source]

Add a calendar event to the calendar. Unless specified otherwise in the task, the default week starts on Monday and ends on Sunday. :type title: str :param title: Title of the event. :type start_datetime: Optional[str] :param start_datetime: Start datetime of the event in the format of YYYY-MM-DD HH:MM:SS. :type end_datetime: Optional[str] :param end_datetime: End datetime of the event in the format of YYYY-MM-DD HH:MM:SS. :type tag: Optional[str] :param tag: Tag of the event. Defaults to None. :type description: Optional[str] :param description: Description of the event. Defaults to None. :type location: Optional[str] :param location: Location of the event. Defaults to None. :type attendees: Optional[list[str]] :param attendees: List of attendees full names. Defaults to empty list. :rtype: str :returns: event_id: Id of the created event if successful.

Return type:: str

add_calendar_event_by_attendee(who_add, title='Event', start_datetime=None, end_datetime=None, tag=None, description=None, location=None, attendees=None)[source]

Add a calendar event to the calendar. Unless specified otherwise in the task, the default week starts on Monday and ends on Sunday. :type who_add: str :param who_add: Name of the attendee who is adding the event. :type title: str :param title: Title of the event. :type start_datetime: Optional[str] :param start_datetime: Start datetime of the event in the format of YYYY-MM-DD HH:MM:SS. :type end_datetime: Optional[str] :param end_datetime: End datetime of the event in the format of YYYY-MM-DD HH:MM:SS. :type tag: Optional[str] :param tag: Tag of the event. Defaults to None. :type description: Optional[str] :param description: Description of the event. Defaults to None. :type location: Optional[str] :param location: Location of the event. Defaults to None. :type attendees: Optional[list[str]] :param attendees: List of attendees full names. who_add is automatically added to the list if not already present. :rtype: str :returns: event_id: Id of the created event if successful.

Return type:: str

set_calendar_event(event)[source]

Set a calendar event to the calendar. :type event: CalendarEvent | dict[str, Any] :param event: (CalendarEvent | dict[str, Any]): Event to set. :rtype: None :returns: None

get_calendar_event(event_id)[source]

Read a calendar event from the calendar. :type event_id: str :param event_id: Id of the event to read. :rtype: CalendarEvent :returns: Calendar event details if successful, of type CalendarEvent, otherwise raise ValueError.

Return type:: CalendarEvent

delete_calendar_event_by_attendee(event_id, who_delete)[source]

Delete a calendar event from the calendar. :type event_id: str :param event_id: Id of the event to delete. :type who_delete: str :param who_delete: Name of the attendee who is deleting the event. :rtype: str :returns: Message if successful, otherwise raise ValueError.

Return type:: str

delete_calendar_event(event_id)[source]

Delete a calendar event from the calendar. :type event_id: str :param event_id: Id of the event to delete. :rtype: str :returns: Message if successful, otherwise raise ValueError.

Return type:: str

get_calendar_events_from_to(start_datetime, end_datetime, offset=0, limit=10)[source]

Get calendar events that have any time overlap with the specified date range (excludes events that only touch at boundaries). Unless specified otherwise in the task, the default week starts on Monday and ends on Sunday. :type start_datetime: str :param start_datetime: Start datetime of the query range in the format of YYYY-MM-DD HH:MM:SS. :type end_datetime: str :param end_datetime: End datetime of the query range in the format of YYYY-MM-DD HH:MM:SS. :type offset: int :param offset: offset to start listing from, default is 0. :type limit: int :param limit: number of events to list, default is 10. :rtype: CalendarEventsResult :returns: List of calendar events details that overlap with the specified time range, limited to the specified offset and limit, with additional metadata about the range of events retrieved and total number of events.

Return type:: CalendarEventsResult

read_today_calendar_events()[source]

Read today’s calendar events from the calendar. :rtype: list[CalendarEvent] :returns: List of calendar events details.

Return type:: list[CalendarEvent]

get_all_tags()[source]

Get all tags from the calendar. :rtype: list[str] :returns: List of tags.

Return type:: list[str]

get_calendar_events_by_tag(tag)[source]

Get calendar events from the calendar by tag. :type tag: str :param tag: Tag for which to get the events. :rtype: list[CalendarEvent] :returns: List of calendar events details.

Return type:: list[CalendarEvent]

search_events(query)[source]

Searches for calendar events based on a query string. The search looks for partial matches in title, description, location, and attendees. :type query: str :param query: The search query string :rtype: list[CalendarEvent] :returns: A list of matching calendar details

Return type:: list[CalendarEvent]

class are.simulation.apps.calendar.Calendar(name='Calendar', events=<factory>)[source]

Bases: CalendarApp

Key Features:

Event Management: Add, update, delete, and retrieve calendar events
Time-based Queries: Get events within specific time ranges
Tag Support: Organize and filter events using tags
Search Functionality: Search events across multiple fields
State Management: Save and load calendar state

Notes:

All datetime operations are performed in UTC timezone
Event IDs are automatically generated when creating new events
The class supports state persistence through save/load operations
Search operations are case-insensitive
Empty tags are not allowed when filtering by tag

name: str | None = 'Calendar'

Bases: object

event_id: str

title: str = 'Event'

start_datetime: float

end_datetime: float

tag: str | None = None

description: str | None = None

location: str | None = None

attendees: list[str]

start_strftime: str | None = None

end_strftime: str | None = None

property summary

class are.simulation.apps.calendar.CalendarEventsResult[source]

Bases: TypedDict

events: list[CalendarEvent]

range: tuple[int, int]

total: int

Contact

class are.simulation.apps.contacts.Gender(value)[source]

Bases: Enum

An enumeration.

FEMALE = 'Female'

MALE = 'Male'

OTHER = 'Other'

UNKNOWN = 'Unknown'

class are.simulation.apps.contacts.Status(value)[source]

Bases: Enum

An enumeration.

STUDENT = 'Student'

EMPLOYED = 'Employed'

UNEMPLOYED = 'Unemployed'

RETIRED = 'Retired'

UNKNOWN = 'Unknown'

class are.simulation.apps.contacts.Contact(first_name, last_name, contact_id=<factory>, is_user=False, gender=Gender.UNKNOWN, age=None, nationality=None, city_living=None, country=None, status=Status.UNKNOWN, job=None, description=None, phone=None, email=None, address=None)[source]

Bases: object

first_name: str

last_name: str

contact_id: str

is_user: bool = False

gender: Gender = 'Unknown'

age: int | None = None

nationality: str | None = None

city_living: str | None = None

country: str | None = None

status: Status = 'Unknown'

job: str | None = None

description: str | None = None

phone: str | None = None

email: str | None = None

address: str | None = None

property summary

class are.simulation.apps.contacts.ContactsApp(name=None, view_limit=10, contacts=<factory>)[source]

Bases: App

A contacts management application that handles storage, retrieval, and manipulation of contact information. This class provides comprehensive functionality for managing a contact database with pagination support and search capabilities.

The ContactsApp stores contacts in a dictionary where each contact is identified by a unique contact_id. The application implements a view limit mechanism for paginated access to contacts.

Key Features:

Contact Management: Add, edit, delete, and retrieve contact information
Pagination: View contacts with offset and limit support
Search Functionality: Search contacts by name, phone, or email
Current User: Special handling for current user’s contact information
State Management: Save and load application state
Batch Operations: Support for adding multiple contacts at once

Notes:

Contact fields include: first/last name, gender, age, nationality, city, status, job, address etc.
Gender options: Male, Female, Other, Unknown (default)
Status options: Student, Employed, Unemployed, Retired, Unknown (default)
Search operations are case-insensitive
Contact IDs are automatically generated when creating new contacts
Edit operations maintain data integrity by rolling back failed updates

name: str | None = None

view_limit: int = 10

contacts: dict[str, Contact]

get_state()[source]

Return type:: dict[str, Any]

load_state(state_dict)[source]

load_contacts_from_dict(contacts_dict)[source]

reset()[source]

get_contacts(offset=0)[source]

Gets the list of contacts starting from a specified offset. There is a view limit. Use offset to scroll through the contacts. :type offset: int :param offset: starting point to retrieve contacts from, default is 0. :rtype: dict[str, Any] :returns: list of contacts, limited to the specified offset and limit view, with additional metadata about the range of contacts retrieved and total number of contacts

Return type:: dict[str, Any]

get_contact(contact_id)[source]

Gets a specific contact by contact_id. :type contact_id: str :param contact_id: ID of the contact to retrieve :rtype: Contact :returns: contact details, if contact_id exists, otherwise raise KeyError

Return type:: Contact

get_current_user_details()[source]

Gets the current user’s details including name, phone number, email address, nationality, country living. :rtype: Contact :returns: Contact details of the current user, if current user details exist in App, otherwise raise KeyError

Return type:: Contact

add_contact(contact)[source]

Adds a new contact to the contacts dictionary. :type contact: Contact :param contact: contact to add

Return type:: str

add_new_contact(first_name, last_name, gender=None, age=None, nationality=None, city_living=None, country=None, status=None, job=None, description=None, phone=None, email=None, address=None)[source]

Adds a new contact to the contacts app. :type first_name: str :param first_name: first name of the contact, required :type last_name: str :param last_name: last name of the contact, required :type gender: Optional[str] :param gender: gender of the contact (Male, Female, Other, Unknown), optional default is Unknown :type age: Optional[int] :param age: age of the contact, optional :type nationality: Optional[str] :param nationality: nationality of the contact, optional :type city_living: Optional[str] :param city_living: city where the contact is living, optional :type country: Optional[str] :param country: country where the contact is living, optional :type status: Optional[str] :param status: status of the contact (Student, Employed, Unemployed, Retired, Unknown), optional default is Unknown :type job: Optional[str] :param job: job of the contact, optional :type description: Optional[str] :param description: description of the contact, optional :type phone: Optional[str] :param phone: phone number of the contact, optional :type email: Optional[str] :param email: email address of the contact, optional :type address: Optional[str] :param address: address of the contact, optional :rtype: str :returns: contact_id of the newly added contact

Return type:: str

add_contacts(contacts)[source]

Adds new contacts to the contacts dictionary.

Return type:: None

edit_contact(contact_id, updates)[source]

Edits specific fields of a contact by contact_id. :type contact_id: str :param contact_id: ID of the contact to edit :type updates: dict[str, Any] :param updates: dictionary of updates to apply to the contact :rtype: str | None :returns: Success message if contact is edited successfully, otherwise raise KeyError or AttributeError

Return type:: str | None

delete_contact(contact_id)[source]

Deletes a specific contact by contact_id. :type contact_id: str :param contact_id: ID of the contact to delete :rtype: str :returns: Success message if contact is deleted successfully, otherwise raise KeyError

Return type:: str

search_contacts(query)[source]

Searches for contacts based on a query string. The search looks for partial matches in first name, last name, phone number, and email. :type query: str :param query: The search query string :rtype: list[Contact] :returns: A list of matching Contact objects

Return type:: list[Contact]

class are.simulation.apps.contacts.Contacts(name='Contacts', view_limit=10, contacts=<factory>)[source]

Bases: ContactsApp

The ContactsApp stores contacts in a dictionary where each contact is identified by a unique contact_id. The application implements a view limit mechanism for paginated access to contacts.

Key Features:

Contact Management: Add, edit, delete, and retrieve contact information
Pagination: View contacts with offset and limit support
Search Functionality: Search contacts by name, phone, or email
Current User: Special handling for current user’s contact information
State Management: Save and load application state
Batch Operations: Support for adding multiple contacts at once

Notes:

Contact fields include: first/last name, gender, age, nationality, city, status, job, address etc.
Gender options: Male, Female, Other, Unknown (default)
Status options: Student, Employed, Unemployed, Retired, Unknown (default)
Search operations are case-insensitive
Contact IDs are automatically generated when creating new contacts
Edit operations maintain data integrity by rolling back failed updates

name: str | None = 'Contacts'

class are.simulation.apps.contacts.InternalContacts(name='InternalContacts', view_limit=10, contacts=<factory>)[source]

Bases: ContactsApp

This is where the full set of personas of the universe and their contact information is stored. This is not visible to anntators but is part of the universe definition

name: str | None = 'InternalContacts'

Bases: object

first_name: str

last_name: str

contact_id: str

is_user: bool = False

gender: Gender = 'Unknown'

age: int | None = None

nationality: str | None = None

city_living: str | None = None

country: str | None = None

status: Status = 'Unknown'

job: str | None = None

description: str | None = None

phone: str | None = None

email: str | None = None

address: str | None = None

property summary

Utility Apps ¶

Shopping

class are.simulation.apps.shopping.ProductMetadata[source]

Bases: TypedDict

range: tuple[int, int]

total: int

class are.simulation.apps.shopping.ProductListResult[source]

Bases: TypedDict

products: dict[str, str]

metadata: ProductMetadata

class are.simulation.apps.shopping.Item(price, available=True, item_id=<factory>, options=<factory>)[source]

Bases: object

price: float

available: bool = True

item_id: str

options: dict[str, Any]

load_state(state_dict)[source]

class are.simulation.apps.shopping.Product(name, product_id=<factory>, variants=<factory>)[source]

Bases: object

name: str

product_id: str

variants: dict[str, Item]

load_state(state_dict)[source]

class are.simulation.apps.shopping.CartItem(item_id, quantity, price, available=True, options=<factory>)[source]

Bases: object

item_id: str

quantity: int

price: float

available: bool = True

options: dict[str, Any]

class are.simulation.apps.shopping.Order(order_status, order_date, order_total, order_id=<factory>, order_items=<factory>)[source]

Bases: object

order_status: str

order_date: Any

order_total: float

order_id: str

order_items: dict[str, CartItem]

load_state(state_dict)[source]

class are.simulation.apps.shopping.ShoppingApp(name=None, products=<factory>, cart=<factory>, orders=<factory>, discount_codes=<factory>)[source]

Bases: App

A shopping application that facilitates the management of a product catalog, user cart, and orders. This class provides core functionality for browsing products, adding items to a cart, applying discount codes, and managing orders. It also includes utility methods for loading data from files, saving application state, and restoring state as needed.

The ShoppingApp maintains a catalog of products, where each product can have multiple variants, and tracks each user’s cart and orders individually. Products and variants are identified by unique product IDs and item IDs, respectively.

Key Features:

Product Management: Load, browse, and retrieve detailed product information
Cart Management: Add, update, and remove items from the cart
Order Processing: Create, list, retrieve, and manage orders
Discount Codes: Apply discount codes to items in the cart and track their usage
State Management: Save and load application state from files and dictionaries

Notes:

All datetime operations are in UTC and managed by a global time manager
Unique IDs for products, items, and orders are generated automatically
Discount codes apply on a per-item basis and are checked for validity before use
Products in the cart are automatically removed upon successful checkout
Orders cannot be canceled if marked as “delivered” or “cancelled”

name: str | None = None

products: dict[str, Product]

cart: dict[str, CartItem]

orders: dict[str, Order]

discount_codes: dict[str, dict[str, float]]

get_state()[source]

Return type:: dict[str, Any] | None

load_state(state_dict)[source]

load_products_from_file(path)[source]

load_products_from_dict(products)[source]

load_discount_codes_from_dict(discount_codes)[source]

load_cart_from_dict(cart)[source]

load_orders_from_dict(orders)[source]

reset()[source]

add_product(name)[source]

Add a product to the catalog. The created product currently doesn’t have any items. Please add items to the product using the add_item_to_product tool. :type name: str :param name: name of the product :rtype: str :return: product id if successful, otherwise raise ValueError.

Return type:: str

add_item_to_product(product_id, price, options={}, available=True)[source]

Add an item variant to a product. :type product_id: str :param product_id: product id :type price: float :param price: price of the item :type options: dict[str, Any] :param options: characteristics of the item. Example: {“color”: “red”, “size”: “large”}. :type available: bool :param available: whether the item is available :rtype: str :return: item id if successful, otherwise raise ValueError.

Return type:: str

update_item(item_id, new_price=None, new_availability=None)[source]

Update an item in the catalog with new price and/or new availability :type item_id: str :param item_id: item id :type new_price: Optional[float] :param new_price: new price of the item :type new_availability: Optional[bool] :param new_availability: new availability of the item :rtype: str :return: item id if successful, otherwise raise ValueError.

Return type:: str

add_discount_code(item_id, discount_code)[source]

Add a discount code to the inventory. :type item_id: str :param item_id: item id of the item for which this discount code works :type discount_code: dict[str, float] :param discount_code: discount code is the dictionary with key being the code and value the discount percentage. :rtype: str :return: success message if successful, otherwise raise ValueError.

Return type:: str

add_order(order_id, order_status, order_date, order_total, item_id, quantity)[source]

Add an order to the orders. :type order_id: str :param order_id: order id to add to orders :type order_status: str :param order_status: order status to add to orders :type order_date: float :param order_date: date of the order :type order_total: float :param order_total: total price of the order :type item_id: str :param item_id: item id ordered :type quantity: int :param quantity: quantity of the item ordered :rtype: str :return: order id if successful, otherwise raise ValueError.

Return type:: str

list_all_products(offset=0, limit=10)[source]

List all products in the catalog. :type offset: int :param offset: offset to start listing from, default is 0. :type limit: int :param limit: number of products to list, default is 10. :rtype: ProductListResult :returns: product details, dictionary of name to product_id, limited to the specified offset and limit, with additional metadata about the range of products retrieved and total number of products.

Return type:: ProductListResult

get_product_details(product_id)[source]

Get product details for a given product id. :type product_id: str :param product_id: product id to get details for :rtype: Product :returns: product details

Return type:: Product

search_product(product_name, offset=0, limit=10)[source]

Search for a product in the inventory by its name. :type product_name: str :param product_name: Name of the product to search for. :type offset: int :param offset: offset to start listing from, default is 0. :type limit: int :param limit: number of products to list, default is 10. :rtype: list[Product] :returns: List of products with the given name, limited to the specified offset and limit.

Return type:: list[Product]

add_to_cart(item_id, quantity=1)[source]

Add item to cart. :type item_id: str :param item_id: item id to add to cart :type quantity: int :param quantity: quantity to add to cart, default is 1 :rtype: str :returns: item id of the added item if successful, otherwise raise Exception.

Return type:: str

remove_from_cart(item_id, quantity=1)[source]

Remove item from cart. :type item_id: str :param item_id: item id to remove from cart :type quantity: int :param quantity: quantity to remove from cart :rtype: str :returns: item id of the removed item if successful, otherwise raise Exception.

Return type:: str

list_cart()[source]

List cart contents. :rtype: dict[str, Any] :returns: cart contents

Return type:: dict[str, Any]

checkout(discount_code=None)[source]

Checkout the order and create a new order from the current cart contents.

IMPORTANT: If a discount code is provided, it MUST be valid for ALL items in the cart. The checkout will fail with a ValueError if ANY item in the cart does not support the provided discount code. This is a strict all-or-nothing discount policy.

Parameters:

discount_code (Optional[str]) – Optional discount code to apply to the entire order. If provided, this discount code must be available for every single item in the cart, otherwise the entire checkout will fail with an error. If you want to use a discount code, ensure all items in your cart support that specific code.

Return type:

str

Returns:

order id of the created order if successful, otherwise raise Exception.

Raises:

ValueError – If discount code is not valid for any item in the cart
Exception – If cart is empty

get_discount_code_info(discount_code='')[source]

Takes the discount code and returns the applicable items with their discount percentages. :type discount_code: str :param discount_code: discount code to check :rtype: dict[str, float] :returns: Dictionary mapping item_id to discount_percentage for items that support this discount code

Return type:: dict[str, float]

get_all_discount_codes()[source]

Returns all the discount codes that are available with the items they apply to. :rtype: dict[str, list[str]] :returns: Dictionary mapping discount codes to list of item IDs they apply to

Return type:: dict[str, list[str]]

list_orders()[source]

List all orders. :rtype: dict[str, Order] :returns: orders, dictionary of order_id to order details

Return type:: dict[str, Order]

get_order_details(order_id)[source]

Get order details. :type order_id: str :param order_id: order id to get details for :rtype: Order :returns: order details if successful, otherwise raise Exception.

Return type:: Order

update_order_status(order_id, status='shipped')[source]

Update order status. :type order_id: str :param order_id: order id to update status for :type status: str :param status: status to update to, default is “shipped”. Valid values are “processed”, “shipped”, “delivered”, “cancelled”. :rtype: None :returns: None if successful, otherwise raise Exception.

cancel_order(order_id)[source]

Cancel an order that is not yet delivered. :type order_id: str :param order_id: order id to cancel :rtype: str :returns: order id if successful, otherwise raise Exception.

Return type:: str

class are.simulation.apps.shopping.Shopping(name='Shopping', products=<factory>, cart=<factory>, orders=<factory>, discount_codes=<factory>)[source]

Bases: ShoppingApp

Key Features:

Product Management: Load, browse, and retrieve detailed product information
Cart Management: Add, update, and remove items from the cart
Order Processing: Create, list, retrieve, and manage orders
Discount Codes: Apply discount codes to items in the cart and track their usage
State Management: Save and load application state from files and dictionaries

Notes:

All datetime operations are in UTC and managed by a global time manager
Unique IDs for products, items, and orders are generated automatically
Discount codes apply on a per-item basis and are checked for validity before use
Products in the cart are automatically removed upon successful checkout
Orders cannot be canceled if marked as “delivered” or “cancelled”

name: str | None = 'Shopping'

class are.simulation.apps.shopping.Product(name, product_id=<factory>, variants=<factory>)[source]

Bases: object

name: str

product_id: str

variants: dict[str, Item]

load_state(state_dict)[source]

class are.simulation.apps.shopping.ProductListResult[source]

Bases: TypedDict

products: dict[str, str]

metadata: ProductMetadata

class are.simulation.apps.shopping.Order(order_status, order_date, order_total, order_id=<factory>, order_items=<factory>)[source]

Bases: object

order_status: str

order_date: Any

order_total: float

order_id: str

order_items: dict[str, CartItem]

load_state(state_dict)[source]

class are.simulation.apps.shopping.CartItem(item_id, quantity, price, available=True, options=<factory>)[source]

Bases: object

item_id: str

quantity: int

price: float

available: bool = True

options: dict[str, Any]

class are.simulation.apps.shopping.Item(price, available=True, item_id=<factory>, options=<factory>)[source]

Bases: object

price: float

available: bool = True

item_id: str

options: dict[str, Any]

load_state(state_dict)[source]

class are.simulation.apps.shopping.ProductMetadata[source]

Bases: TypedDict

range: tuple[int, int]

total: int

Cab Service

class are.simulation.apps.cab.Ride(ride_id=<factory>, status=None, service_type=None, start_location=None, end_location=None, price=None, duration=None, time_stamp=None, distance_km=None, delay=None, delay_history=<factory>)[source]

Bases: object

ride_id: str

status: str | None = None

service_type: str | None = None

start_location: str | None = None

end_location: str | None = None

price: float | None = None

duration: float | None = None

time_stamp: float | None = None

distance_km: float | None = None

delay: float | None = None

delay_history: list[dict]

set_booked()[source]

update_delay(current_time_stamp, rng)[source]

class are.simulation.apps.cab.RideHistory(name, rides)[source]

Bases: object

name: str

rides: list[Ride]

class are.simulation.apps.cab.OnGoingRide(name, ride=None)[source]

Bases: object

name: str

ride: Ride | None = None

class are.simulation.apps.cab.CabApp(name=None, quotation_history=<factory>, on_going_ride=None, ride_history=<factory>, MESSAGE_CANCEL='The ride has been cancelled. Sorry for the inconvenience.', d_service_config=<factory>)[source]

Bases: App

A cab service application that manages and facilitates ride requests and bookings. This class provides functionality for creating, reading, updating, and canceling rides, as well as calculating fares and handling ride history.

The CabApp maintains rides in a structured format, allowing users to book rides, view current ride status, and retrieve ride history. Each ride is represented by a unique Ride object, containing relevant details about the journey.

Key Features:

Ride Management: Create, book, cancel, and retrieve ride details
Quotation System: Calculate fare estimates based on distance, service type, and historical data
Ride History: Track past rides and access details for each ride
Delay Management: Update and record delays for ongoing rides
State Persistence: Save and load application state to retain ride and quotation history

Notes:

All ride attributes are expected to conform to specific data types (e.g., price as float, distance as float)
Ride IDs are automatically generated upon creation
The class allows for the cancellation of rides by both users and drivers
Fare calculations consider historical pricing trends and maximum service distances
The distance calculation is currently a mock function; integration with a real mapping API is recommended for accurate distance measurements

name: str | None = None

quotation_history: list[Ride]

on_going_ride: Ride | None = None

ride_history: list[Ride]

MESSAGE_CANCEL: str = 'The ride has been cancelled. Sorry for the inconvenience.'

d_service_config: dict[str, dict[str, float]]

get_state()[source]

Return type:: dict[str, Any]

load_state(state_dict)[source]

reset()[source]

calculate_price(start_location, end_location, distance_km, service_type, time_stamp)[source]

Return type:: float

add_new_ride(service_type, start_location, end_location, price, duration=0.0, time_stamp=0.0, distance_km=0.0)[source]

Add a new ride to the ride history. :type service_type: str :param service_type: type of service (Default, Premium, Van) :type start_location: str :param start_location: starting point of the ride :type end_location: str :param end_location: ending point of the ride :type price: float :param price: price of the ride :type duration: float :param duration: duration in minutes of the ride :type time_stamp: float :param time_stamp: time stamp of the ride :type distance_km: float :param distance_km: distance in kilometers of the ride :rtype: str :return: ride id of the added ride if successful, otherwise raise Exception.

Return type:: str

get_quotation(start_location, end_location, service_type, ride_time=None)[source]

Calculates the price and estimated delay for a ride. :type start_location: str :param start_location: starting point of the ride :type end_location: str :param end_location: ending point of the ride :type service_type: str :param service_type: type of service (Default, Premium, Van) :type ride_time: Optional[str] :param ride_time: the time of the ride in the format ‘YYYY-MM-DD HH:MM:SS’. If None, the current time is used. :rtype: Ride :returns: Ride with all the information: start_location, end_location, service_type, price, delay, distance, duration, the time_stamp.

Return type:: Ride

list_rides(start_location, end_location, ride_time=None)[source]

Lists all rides available between two locations. :type start_location: str :param start_location: starting point of the ride :type end_location: str :param end_location: ending point of the ride :type ride_time: Optional[str] :param ride_time: the time of the ride. If None, the current time is used. :rtype: list[Ride] :returns: list of Ride objects

Return type:: list[Ride]

order_ride(start_location, end_location, service_type, ride_time=None)[source]

Orders a ride and returns the ride details. :type start_location: str :param start_location: starting point of the ride :type end_location: str :param end_location: ending point of the ride :type service_type: str :param service_type: type of service (Default, Premium, Van) :type ride_time: Optional[str] :param ride_time: the time of the ride :rtype: Ride :returns: booked ride, represented by a Ride object

Return type:: Ride

cancel_ride(who_cancel='driver', message=None)[source]

The current ride is cancelled (by user or by driver). :type who_cancel: str :param who_cancel: who cancel the ride, either ‘driver’ or ‘user’ :type message: Optional[str] :param message: optional message to send to the user :rtype: str :returns: message

Return type:: str

user_cancel_ride()[source]: Cancel the current ride.

end_ride()[source]

End the current ride. :rtype: str :returns: “Ride has been completed.”

Return type:: str

update_ride_status(status, message=None)[source]

Update the status of the current ride. :type status: str :param status: new status of the ride. Must be one of “DELAYED”, “IN_PROGRESS”, “ARRIVED_AT_PICKUP”. :type message: Optional[str] :param message: optional message from the driver. :returns: new status of the ride

get_current_ride_status()[source]

Check the status for the current ride ordered. :rtype: Ride :returns: ride details, represented by a Ride object

Return type:: Ride

get_ride(idx)[source]

Gets a specific ride from the ride history. :type idx: int :param idx: index of the ride to retrieve :returns: ride details

get_ride_history(offset=0, limit=10)[source]

Gets a list of rides from the ride history starting from a specified offset. :type offset: int :param offset: starting point to retrieve rides from, default is 0. :type limit: int :param limit: maximum number of rides to retrieve, default is 10. :rtype: dict[str, Any] :returns: dictionary of ride details, where the key is the index of the ride in the ride history and the value is the ride details, with additional metadata about the range of rides retrieved and total number of rides.

Return type:: dict[str, Any]

get_ride_history_length()[source]

Gets the length of the ride history. :rtype: int :returns: length of the ride history

Return type:: int

get_distance_from_history(start_location, end_location)[source]

calculate_distance(start_location, end_location)[source]

Mock function to calculate the distance between two locations. :type start_location: str :param start_location: starting point of the ride :type end_location: str :param end_location: ending point of the ride :rtype: float :returns: distance in kilometers

Return type:: float

delete_future_data(timestamp)[source]: Delete all future data from the ride history. :type timestamp: :param timestamp: timestamp to delete data after

Bases: object

ride_id: str

status: str | None = None

service_type: str | None = None

start_location: str | None = None

end_location: str | None = None

price: float | None = None

duration: float | None = None

time_stamp: float | None = None

distance_km: float | None = None

delay: float | None = None

delay_history: list[dict]

set_booked()[source]

update_delay(current_time_stamp, rng)[source]

class are.simulation.apps.cab.RideHistory(name, rides)[source]

Bases: object

name: str

rides: list[Ride]

class are.simulation.apps.cab.OnGoingRide(name, ride=None)[source]

Bases: object

name: str

ride: Ride | None = None

Apartment Listing

class are.simulation.apps.apartment_listing.Apartment(name, location, zip_code, price, bedrooms, bathrooms, property_type, square_footage, furnished_status='', floor_level='', pet_policy='', lease_term='', apartment_id=<factory>, amenities=<factory>, saved=False)[source]

Bases: object

name: str

location: str

zip_code: str

price: float

bedrooms: int

bathrooms: int

property_type: str

square_footage: int

furnished_status: str | None = ''

floor_level: str | None = ''

pet_policy: str | None = ''

lease_term: str | None = ''

apartment_id: str

amenities: list[str] | None

saved: bool = False

class are.simulation.apps.apartment_listing.ApartmentListingApp(name=None, apartments=<factory>, saved_apartments=<factory>)[source]

Bases: App

A real estate application that manages and manipulates apartment listings. This class provides functionality for creating, reading, updating, and deleting apartment listings, as well as various utility methods for searching and filtering apartments based on multiple criteria.

The app maintains apartments in a dictionary where each apartment is identified by a unique apartment_id. All price-related inputs should be in float format, and the number of bedrooms and bathrooms should be integers.

Key Features:

Apartment Management: Add, update, delete, and retrieve apartment listings
Search Functionality: Filter apartments based on various criteria including location, price, size, and amenities
Favorites Management: Save and remove favorite apartments for quick access
State Management: Save and load application state to retain apartment listings and favorites

Notes:

All apartment attributes are expected to adhere to specific data types (e.g., price as float, bedrooms and bathrooms as integers)
Apartment IDs are automatically generated when creating new apartments
The class supports state persistence through save/load operations from a file
Search operations are case-insensitive for string comparisons
Amenities filtering checks if all specified amenities are present in the apartment’s amenities list

name: str | None = None

apartments: dict[str, Apartment]

saved_apartments: list[str]

get_state()[source]

Return type:: dict[str, Any] | None

load_state(state_dict)[source]

reset()[source]

load_apartments_from_file(path)[source]

load_apartments_from_dict(apartments)[source]

add_new_apartment(name, location, zip_code, price, number_of_bedrooms, number_of_bathrooms, square_footage, property_type='', furnished_status='', floor_level='', pet_policy='', lease_term='', amenities=None)[source]

Adds a new apartment to the apartment listing. :type name: str :param name: name of the apartment :type location: str :param location: desired location :type zip_code: str :param zip_code: zip code of the apartment location :type price: float :param price: price of the apartment :type number_of_bedrooms: int :param number_of_bedrooms: number of bedrooms :type number_of_bathrooms: int :param number_of_bathrooms: number of bathrooms :type property_type: str :param property_type: type of property (Apartment, Condo, etc.) :type square_footage: int :param square_footage: minimum square footage :type furnished_status: str :param furnished_status: Furnished, Unfurnished, or Semi-furnished :type floor_level: str :param floor_level: Ground floor, Upper floors, Penthouse, Basement :type pet_policy: str :param pet_policy: Pets allowed, No pets, Cats allowed, Dogs allowed :type lease_term: str :param lease_term: Month-to-month, 6 months, 1 year, Long term lease :type amenities: Optional[list[str]] :param amenities: list of desired amenities :rtype: str :returns: apartment_id of the apartment just added, if successful, otherwise raise Exception.

Return type:: str

update_apartment(apartment_id, new_price)[source]

Updates an existing apartment in the apartment listing. :type apartment_id: str :param apartment_id: apartment id to update :type new_price: float :param new_price: new price of the apartment :rtype: str :returns: apartment_id of the apartment just updated, if successful, otherwise raise Exception.

Return type:: str

delete_apartment(apartment_id)[source]

Deletes a specific apartment by apartment_id. :type apartment_id: str :param apartment_id: apartment id to delete :rtype: None :returns: apartment_id of the apartment just deleted, if successful, otherwise raise Exception.

list_all_apartments()[source]

List all apartments in the catalog. :rtype: dict[str, Any] :returns: apartment details

Return type:: dict[str, Any]

get_apartment_details(apartment_id)[source]

Get apartment details for a given apartment id. :type apartment_id: str :param apartment_id: apartment id to get details for :rtype: Apartment :returns: apartment details

Return type:: Apartment

save_apartment(apartment_id)[source]

Save an apartment to favorites if not already saved, otherwise do nothing. :type apartment_id: str :param apartment_id: apartment id to save

Return type:: None

remove_saved_apartment(apartment_id)[source]

Remove an apartment from favorites. :type apartment_id: str :param apartment_id: apartment id to remove

Return type:: None

list_saved_apartments()[source]

List apartments saved to favorites. :rtype: dict[str, Apartment] :returns: Dictionary of saved apartments: apartment_id -> apartment

Return type:: dict[str, Apartment]

search_apartments(name=None, location=None, zip_code=None, min_price=None, max_price=None, number_of_bedrooms=None, number_of_bathrooms=None, property_type=None, square_footage=None, furnished_status=None, floor_level=None, pet_policy=None, lease_term=None, amenities=None, saved_only=False)[source]

Search for apartments based on multiple filters. :type name: Optional[str] :param name: name of the apartment :type location: Optional[str] :param location: desired location :type zip_code: Optional[str] :param zip_code: zip code of the location :type min_price: Union[int, float, None] :param min_price: minimum price :type max_price: Union[int, float, None] :param max_price: maximum price :type number_of_bedrooms: Optional[int] :param number_of_bedrooms: number of bedrooms :type number_of_bathrooms: Optional[int] :param number_of_bathrooms: number of bathrooms :type property_type: Optional[str] :param property_type: type of property (Apartment, Condo, etc.) :type square_footage: Optional[int] :param square_footage: minimum square footage :type furnished_status: Optional[str] :param furnished_status: Furnished, Unfurnished, or Semi-furnished :type floor_level: Optional[str] :param floor_level: Ground floor, Upper floors, Penthouse, Basement :type pet_policy: Optional[str] :param pet_policy: Pets allowed, No pets, Cats allowed, Dogs allowed :type lease_term: Optional[str] :param lease_term: Month-to-month, 6 months, 1 year, Long term lease :type amenities: Optional[list[str]] :param amenities: list of desired amenities :type saved_only: bool :param saved_only: if True, search only saved apartments; if False, search all apartments (default) :rtype: dict[str, Apartment] :returns: filtered list of apartments, dictionary of apartment_id -> apartment

Return type:: dict[str, Apartment]

class are.simulation.apps.apartment_listing.RentAFlat(name='RentAFlat', apartments=<factory>, saved_apartments=<factory>)[source]

Bases: ApartmentListingApp

Key Features:

Apartment Management: Add, update, delete, and retrieve apartment listings
Search Functionality: Filter apartments based on various criteria including location, price, size, and amenities
Favorites Management: Save and remove favorite apartments for quick access
State Management: Save and load application state to retain apartment listings and favorites

Notes:

All apartment attributes are expected to adhere to specific data types (e.g., price as float, bedrooms and bathrooms as integers)
Apartment IDs are automatically generated when creating new apartments
The class supports state persistence through save/load operations from a file
Search operations are case-insensitive for string comparisons
Amenities filtering checks if all specified amenities are present in the apartment’s amenities list

name: str | None = 'RentAFlat'

Bases: object

name: str

location: str

zip_code: str

price: float

bedrooms: int

bathrooms: int

property_type: str

square_footage: int

furnished_status: str | None = ''

floor_level: str | None = ''

pet_policy: str | None = ''

lease_term: str | None = ''

apartment_id: str

amenities: list[str] | None

saved: bool = False

class are.simulation.apps.apartment_listing.RentAFlat(name='RentAFlat', apartments=<factory>, saved_apartments=<factory>)[source]

Bases: ApartmentListingApp

Key Features:

Apartment Management: Add, update, delete, and retrieve apartment listings
Search Functionality: Filter apartments based on various criteria including location, price, size, and amenities
Favorites Management: Save and remove favorite apartments for quick access
State Management: Save and load application state to retain apartment listings and favorites

Notes:

All apartment attributes are expected to adhere to specific data types (e.g., price as float, bedrooms and bathrooms as integers)
Apartment IDs are automatically generated when creating new apartments
The class supports state persistence through save/load operations from a file
Search operations are case-insensitive for string comparisons
Amenities filtering checks if all specified amenities are present in the apartment’s amenities list

name: str | None = 'RentAFlat'

apartments: dict[str, Apartment]

saved_apartments: list[str]

failure_probability: float | None

City Information

class are.simulation.apps.city.CrimeDataPoint(violent_crime, property_crime)[source]

Bases: object

violent_crime: float

property_crime: float

class are.simulation.apps.city.CityApp(name=None, api_call_count=0, api_call_limit=100, crime_data=<factory>, rate_limit_time=None, rate_limit_exceeded=False)[source]

Bases: App

A city information application that provides access to crime rate data for different zip codes. This class implements a rate-limited API service for retrieving crime statistics, with built-in tracking of API usage and enforcement of call limits.

The CityApp maintains crime data in a dictionary where each zip code is mapped to its corresponding crime statistics. The free version of the API has usage limitations that are strictly enforced.

Key Features:

Crime Data Access: Retrieve crime statistics for specific zip codes
Rate Limiting: Implements usage restrictions with 30-minute cooldown
API Usage Tracking: Monitors and manages API call counts
State Management: Save and load application state
Data Loading: Support for loading crime data from files or dictionaries

Notes:

Free version is limited to 100 API calls per 30-minute period
Rate limit reset requires a 30-minute waiting period
API calls are tracked and persist until manually reset
Attempting to exceed rate limits raises an exception
Invalid zip codes result in ValueError

name: str | None = None

api_call_count: int = 0

api_call_limit: int = 100

rate_limit_cooldown_seconds = 1800

crime_data: dict[str, CrimeDataPoint]

rate_limit_time: float | None = None

rate_limit_exceeded: bool = False

get_state()[source]

Return type:: dict[str, Any] | None

load_state(state_dict)[source]

reset()[source]

load_crime_data_from_dict(crime_data)[source]

add_crime_rate(zip_code, violent_crime_rate, property_crime_rate)[source]

Add crime rate for a given zip code. :type zip_code: str :param zip_code: zip code to add crime rate for :type violent_crime_rate: float :param violent_crime_rate: violent crime rate :type property_crime_rate: float :param property_crime_rate: property crime rate :rtype: str :return: Success message

Return type:: str

update_crime_rate(zip_code, new_violent_crime_rate=None, new_property_crime_rate=None)[source]

Update crime rate for a given zip code. :type zip_code: str :param zip_code: zip code to update crime rate for :type new_violent_crime_rate: Optional[float] :param new_violent_crime_rate: violent crime rate :type new_property_crime_rate: Optional[float] :param new_property_crime_rate: property crime rate :rtype: str :return: Success message

Return type:: str

get_crime_rate(zip_code)[source]

Get crime rate for a given zip code. This is a free version of the API, so it has a limit. This limit can be obtained by calling get_api_call_limit() method. If you exceed this limit, you have to wait for 30 minutes to make more calls. :type zip_code: str :param zip_code: zip code to get crime rate for :rtype: CrimeDataPoint :returns: crime rate details

Return type:: CrimeDataPoint

reset_api_call_count()[source]

Reset the API call count :rtype: None :returns: None

get_api_call_count()[source]

Get the current API call count for the service. :rtype: int :returns: API call count

Return type:: int

get_api_call_limit()[source]

Get the API call limit rate for the service. :rtype: int :returns: API call count

Return type:: int

class are.simulation.apps.city.CrimeDataPoint(violent_crime, property_crime)[source]

Bases: object

violent_crime: float

property_crime: float

Integration Apps ¶

Model Context Protocol (MCP)

For detailed documentation on MCPApp usage, configuration, and examples, see MCPApp - Model Context Protocol.

MCP Tools vs Meta Agents Research Environments Apps: Comparison and Integration ¶

The Model Context Protocol (MCP) and Meta Agents Research Environments Apps represent two different but complementary approaches to providing functionality to AI agents. Understanding their differences and similarities helps in choosing the right approach for your use case.

Conceptual Differences ¶

MCP Tools

MCP tools are individual, executable functions exposed by MCP servers to clients. They represent a function-centric approach where:

Each tool is a single, atomic operation
Tools are discovered dynamically through the MCP protocol
Tools are stateless from the protocol perspective
Tools are designed to be model-controlled (AI can invoke them automatically with human approval)
Tools focus on specific, well-defined operations

Meta Agents Research Environments Apps

Meta Agents Research Environments Apps represent an application-centric approach where:

Apps encapsulate related functionality as a cohesive unit
Apps maintain internal state throughout simulation lifecycle
Apps provide multiple related tools grouped by application domain
Apps model real-world applications (email, calendar, file system, etc.)
Apps can implement protocols for inter-app communication

Key Similarities ¶

Both MCP tools and Meta Agents Research Environments Apps share several important characteristics:

Tool Discovery: Both support dynamic discovery of available functionality
Structured Parameters: Both use JSON Schema for parameter definition and validation
Rich Descriptions: Both provide detailed descriptions to guide AI usage
Error Handling: Both implement structured error reporting
Extensibility: Both allow for custom implementations and extensions

Architectural Comparison ¶

Granularity

MCP Server                    Meta Agents Research Environments App
├── search_web               ├── BrowserApp
├── read_file                │   ├── navigate_to_url
├── write_file               │   ├── search_web
├── send_email               │   ├── click_element
└── get_weather              │   └── get_page_content
                             ├── FileSystemApp
                             │   ├── read_file
                             │   ├── write_file
                             │   └── list_directory
                             └── EmailApp
                                 ├── send_email
                                 ├── read_inbox
                                 └── delete_email

State Management

MCP Tools: Stateless at the protocol level; any state is managed internally by the server
Meta Agents Research Environments Apps: Explicit state management with serialization/deserialization for simulation consistency

Integration in Meta Agents Research Environments ¶

Meta Agents Research Environments provides bidirectional integration with MCP:

Using MCP Tools in Meta Agents Research Environments

The MCPApp - Model Context Protocol discusses connecting to external MCP servers and use their tools within Meta Agents Research Environments simulations. This allows you to leverage the growing ecosystem of MCP servers while maintaining Meta Agents Research Environments’s application-centric approach.

Exposing Meta Agents Research Environments as MCP Server

The MCP Server - Expose Scenarios allows you to expose Meta Agents Research Environments apps and scenarios as MCP servers, making them accessible to external agentic tools like Claude Desktop, Cursor, and other MCP-compatible clients.

Benefits of MCP Integration

Ecosystem Access: Leverage the growing ecosystem of MCP servers
Rapid Integration: Connect to external services without custom app development
Protocol Standardization: Benefit from MCP’s standardized communication protocol
Community Tools: Access community-developed MCP servers
Multi-Agent Testing: Test scenarios with different AI agents and tools

Meta Agents Research Environments App Advantages

Simulation Fidelity: Apps model real-world applications more accurately
State Consistency: Explicit state management ensures simulation reproducibility
Inter-App Communication: Apps can interact through protocols
Domain Modeling: Natural grouping of related functionality