academy.exchange¶

academy/exchange/__init__.py

Exchange ¶

Bases: Protocol

Message exchange client protocol.

A message exchange hosts mailboxes for each entity (i.e., agent or client) in a multi-agent system. This protocol defines the client interface to an arbitrary exchange.

Warning

Exchange implementations should be efficiently pickleable so that agents and remote clients can establish client connections to the same exchange.

close ¶

close() -> None

Close the exchange client.

Note

This does not alter the state of the exchange.

Source code in academy/exchange/__init__.py

def close(self) -> None:
    """Close the exchange client.

    Note:
        This does not alter the state of the exchange.
    """
    ...

register_agent ¶

register_agent(
    behavior: type[BehaviorT],
    *,
    agent_id: AgentId[BehaviorT] | None = None,
    name: str | None = None
) -> AgentId[BehaviorT]

Create a new agent identifier and associated mailbox.

Parameters:

behavior (type[BehaviorT]) –

Behavior type of the agent.
agent_id (AgentId[BehaviorT] | None, default: None ) –

Specify the ID of the agent. Randomly generated default.
name (str | None, default: None ) –

Optional human-readable name for the agent. Ignored if agent_id is provided.

Returns:

AgentId[BehaviorT] –

Unique identifier for the agent's mailbox.

Source code in academy/exchange/__init__.py

def register_agent(
    self,
    behavior: type[BehaviorT],
    *,
    agent_id: AgentId[BehaviorT] | None = None,
    name: str | None = None,
) -> AgentId[BehaviorT]:
    """Create a new agent identifier and associated mailbox.

    Args:
        behavior: Behavior type of the agent.
        agent_id: Specify the ID of the agent. Randomly generated
            default.
        name: Optional human-readable name for the agent. Ignored if
            `agent_id` is provided.

    Returns:
        Unique identifier for the agent's mailbox.
    """
    ...

register_client ¶

register_client(*, name: str | None = None) -> ClientId

Create a new client identifier and associated mailbox.

Parameters:

name (str | None, default: None ) –

Optional human-readable name for the client.

Returns:

ClientId –

Unique identifier for the client's mailbox.

Source code in academy/exchange/__init__.py

def register_client(self, *, name: str | None = None) -> ClientId:
    """Create a new client identifier and associated mailbox.

    Args:
        name: Optional human-readable name for the client.

    Returns:
        Unique identifier for the client's mailbox.
    """
    ...

terminate ¶

terminate(uid: EntityId) -> None

Close the mailbox for an entity from the exchange.

Note

This method is a no-op if the mailbox does not exist.

Parameters:

uid (EntityId) –

Entity identifier of the mailbox to close.

Source code in academy/exchange/__init__.py

def terminate(self, uid: EntityId) -> None:
    """Close the mailbox for an entity from the exchange.

    Note:
        This method is a no-op if the mailbox does not exist.

    Args:
        uid: Entity identifier of the mailbox to close.
    """
    ...

discover ¶

discover(
    behavior: type[Behavior],
    *,
    allow_subclasses: bool = True
) -> tuple[AgentId[Any], ...]

Discover peer agents with a given behavior.

Parameters:

behavior (type[Behavior]) –

Behavior type of interest.
allow_subclasses (bool, default: True ) –

Return agents implementing subclasses of the behavior.

Returns:

tuple[AgentId[Any], ...] –

Tuple of agent IDs implementing the behavior.

Source code in academy/exchange/__init__.py

def discover(
    self,
    behavior: type[Behavior],
    *,
    allow_subclasses: bool = True,
) -> tuple[AgentId[Any], ...]:
    """Discover peer agents with a given behavior.

    Args:
        behavior: Behavior type of interest.
        allow_subclasses: Return agents implementing subclasses of the
            behavior.

    Returns:
        Tuple of agent IDs implementing the behavior.
    """
    ...

get_handle ¶

get_handle(
    aid: AgentId[BehaviorT],
) -> UnboundRemoteHandle[BehaviorT]

Create a new handle to an agent.

A handle enables a client to invoke actions on the agent.

Note

It is not possible to create a handle to a client since a handle is essentially a new client of a specific agent.

Parameters:

aid (AgentId[BehaviorT]) –

EntityId of the agent to create a handle to.

Returns:

UnboundRemoteHandle[BehaviorT] –

Handle to the agent.

Raises:

BadEntityIdError –

if a mailbox for aid does not exist.
TypeError –

if aid is not an instance of AgentId.

Source code in academy/exchange/__init__.py

def get_handle(
    self,
    aid: AgentId[BehaviorT],
) -> UnboundRemoteHandle[BehaviorT]:
    """Create a new handle to an agent.

    A handle enables a client to invoke actions on the agent.

    Note:
        It is not possible to create a handle to a client since a handle
        is essentially a new client of a specific agent.

    Args:
        aid: EntityId of the agent to create a handle to.

    Returns:
        Handle to the agent.

    Raises:
        BadEntityIdError: if a mailbox for `aid` does not exist.
        TypeError: if `aid` is not an instance of
            [`AgentId`][academy.identifier.AgentId].
    """
    ...

get_mailbox ¶

get_mailbox(uid: EntityId) -> Mailbox

Get a client to a specific mailbox.

Parameters:

uid (EntityId) –

EntityId of the mailbox.

Returns:

Mailbox –

Mailbox client.

Raises:

BadEntityIdError –

if a mailbox for uid does not exist.

Source code in academy/exchange/__init__.py

def get_mailbox(self, uid: EntityId) -> Mailbox:
    """Get a client to a specific mailbox.

    Args:
        uid: EntityId of the mailbox.

    Returns:
        Mailbox client.

    Raises:
        BadEntityIdError: if a mailbox for `uid` does not exist.
    """
    ...

send ¶

send(uid: EntityId, message: Message) -> None

Send a message to a mailbox.

Parameters:

uid (EntityId) –

Destination address of the message.
message (Message) –

Message to send.

Raises:

BadEntityIdError –

if a mailbox for uid does not exist.
MailboxClosedError –

if the mailbox was closed.

Source code in academy/exchange/__init__.py

def send(self, uid: EntityId, message: Message) -> None:
    """Send a message to a mailbox.

    Args:
        uid: Destination address of the message.
        message: Message to send.

    Raises:
        BadEntityIdError: if a mailbox for `uid` does not exist.
        MailboxClosedError: if the mailbox was closed.
    """
    ...

ExchangeMixin ¶

Mixin class that adds basic methods to an exchange implementation.

This adds a simple repr/str, context manager support, and the register_agent, register_client, and get_handle methods.

get_handle ¶

get_handle(
    aid: AgentId[BehaviorT],
) -> UnboundRemoteHandle[BehaviorT]

Create a new handle to an agent.

A handle enables a client to invoke actions on the agent.

Note

It is not possible to create a handle to a client since a handle is essentially a new client of a specific agent.

Parameters:

aid (AgentId[BehaviorT]) –

EntityId of the agent to create an handle to.

Returns:

UnboundRemoteHandle[BehaviorT] –

Handle to the agent.

Raises:

TypeError –

if aid is not an instance of AgentId.

Source code in academy/exchange/__init__.py

def get_handle(
    self: Exchange,
    aid: AgentId[BehaviorT],
) -> UnboundRemoteHandle[BehaviorT]:
    """Create a new handle to an agent.

    A handle enables a client to invoke actions on the agent.

    Note:
        It is not possible to create a handle to a client since a handle
        is essentially a new client of a specific agent.

    Args:
        aid: EntityId of the agent to create an handle to.

    Returns:
        Handle to the agent.

    Raises:
        TypeError: if `aid` is not an instance of
            [`AgentId`][academy.identifier.AgentId].
    """
    if not isinstance(aid, AgentId):
        raise TypeError(
            f'Handle must be created from an {AgentId.__name__} '
            f'but got identifier with type {type(aid).__name__}.',
        )
    return UnboundRemoteHandle(self, aid)

Mailbox ¶

Bases: Protocol

Client protocol that listens to incoming messages to a mailbox.

exchange `property` ¶

exchange: Exchange

Exchange client.

mailbox_id `property` ¶

mailbox_id: EntityId

Mailbox address/identifier.

close ¶

close() -> None

Close this mailbox client.

Warning

This does not close the mailbox in the exchange. I.e., the exchange will still accept new messages to this mailbox, but this client will no longer be listening for them.

Source code in academy/exchange/__init__.py

def close(self) -> None:
    """Close this mailbox client.

    Warning:
        This does not close the mailbox in the exchange. I.e., the exchange
        will still accept new messages to this mailbox, but this client
        will no longer be listening for them.
    """
    ...

recv ¶

recv(timeout: float | None = None) -> Message

Receive the next message in the mailbox.

This blocks until the next message is received or the mailbox is closed.

Parameters:

timeout (float | None, default: None ) –

Optional timeout in seconds to wait for the next message. If None, the default, block forever until the next message or the mailbox is closed.

Raises:

MailboxClosedError –

if the mailbox was closed.
TimeoutError –

if a timeout was specified and exceeded.

Source code in academy/exchange/__init__.py

def recv(self, timeout: float | None = None) -> Message:
    """Receive the next message in the mailbox.

    This blocks until the next message is received or the mailbox
    is closed.

    Args:
        timeout: Optional timeout in seconds to wait for the next
            message. If `None`, the default, block forever until the
            next message or the mailbox is closed.

    Raises:
        MailboxClosedError: if the mailbox was closed.
        TimeoutError: if a `timeout` was specified and exceeded.
    """
    ...

academy.exchange¶

Exchange ¶

close ¶

register_agent ¶

register_client ¶

terminate ¶

discover ¶

get_handle ¶

get_mailbox ¶

send ¶

ExchangeMixin ¶

get_handle ¶

Mailbox ¶

exchange property ¶

mailbox_id property ¶

close ¶

recv ¶

exchange `property` ¶

mailbox_id `property` ¶