Skip to content

academy.message

Message module-attribute 

Message = Union[RequestMessage, ResponseMessage]

Message union type for type annotations.

Tip

This is a parameterized generic type meaning that this type cannot be used for [isinstance][builtins.isinstance] checks: 

isinstance(message, Message)  # Fails
Instead, use typing.get_args(): 
from typing import get_args

isinstance(message, get_args(Message))  # Works

BaseMessage pydantic-model

Bases: BaseModel

Base message type for messages between entities (agents or clients).

Note

The hash() of this type is a combination of the message type and message ID.

Config:

  • arbitrary_types_allowed: True
  • extra: forbid
  • frozen: False
  • use_enum_values: True
  • validate_default: True

Fields:

tag pydantic-field 

tag: UUID

Unique message tag used to match requests and responses.

src pydantic-field 

src: EntityId

Source mailbox address.

dest pydantic-field 

dest: EntityId

Destination mailbox address.

label pydantic-field 

label: Optional[UUID] = None

Optional label used to disambiguate response messages when multiple objects (i.e., handles) share the same mailbox. This is a different usage from the tag.

model_from_json classmethod 

model_from_json(data: str) -> Message

Reconstruct a specific message from a JSON dump.

Example 
from academy.message import BaseMessage, ActionRequest

message = ActionRequest(...)
dump = message.model_dump_json()
assert BaseMessage.model_from_json(dump) == message
Source code in academy/message.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def model_from_json(cls, data: str) -> Message:
    """Reconstruct a specific message from a JSON dump.

    Example:
        ```python
        from academy.message import BaseMessage, ActionRequest

        message = ActionRequest(...)
        dump = message.model_dump_json()
        assert BaseMessage.model_from_json(dump) == message
        ```
    """
    return TypeAdapter(Message).validate_json(data)

model_deserialize classmethod 

model_deserialize(data: bytes) -> Message

Deserialize a message.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@classmethod
def model_deserialize(cls, data: bytes) -> Message:
    """Deserialize a message.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    message = pickle.loads(data)
    if not isinstance(message, get_args(Message)):
        raise TypeError(
            'Deserialized message is not of type Message.',
        )
    return message

model_serialize 

model_serialize() -> bytes

Serialize a message to bytes.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
89
90
91
92
93
94
95
96
def model_serialize(self) -> bytes:
    """Serialize a message to bytes.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    return pickle.dumps(self)

ActionRequest pydantic-model

Bases: BaseMessage

Agent action request message.

When this message is dumped to a JSON string, the pargs and kargs are pickled and then base64 encoded to a string. This can have non-trivial time and space overheads for large arguments.

Fields:

Validators:

action pydantic-field 

action: str

Name of the requested action.

pargs pydantic-field 

pargs: tuple[Any, ...]

Positional arguments to the action method.

kargs pydantic-field 

kargs: dict[str, Any]

Keyword arguments to the action method.

tag pydantic-field 

tag: UUID

Unique message tag used to match requests and responses.

src pydantic-field 

src: EntityId

Source mailbox address.

dest pydantic-field 

dest: EntityId

Destination mailbox address.

label pydantic-field 

label: Optional[UUID] = None

Optional label used to disambiguate response messages when multiple objects (i.e., handles) share the same mailbox. This is a different usage from the tag.

error 

error(exception: Exception) -> ActionResponse

Construct an error response to action request.

Parameters:

  • exception (Exception) –

    Error of the action.

Source code in academy/message.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def error(self, exception: Exception) -> ActionResponse:
    """Construct an error response to action request.

    Args:
        exception: Error of the action.
    """
    return ActionResponse(
        tag=self.tag,
        src=self.dest,
        dest=self.src,
        label=self.label,
        action=self.action,
        result=None,
        exception=exception,
    )

response 

response(result: Any) -> ActionResponse

Construct a success response to action request.

Parameters:

  • result (Any) –

    Result of the action.

Source code in academy/message.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def response(self, result: Any) -> ActionResponse:
    """Construct a success response to action request.

    Args:
        result: Result of the action.
    """
    return ActionResponse(
        tag=self.tag,
        src=self.dest,
        dest=self.src,
        label=self.label,
        action=self.action,
        result=result,
        exception=None,
    )

model_from_json classmethod 

model_from_json(data: str) -> Message

Reconstruct a specific message from a JSON dump.

Example 
from academy.message import BaseMessage, ActionRequest

message = ActionRequest(...)
dump = message.model_dump_json()
assert BaseMessage.model_from_json(dump) == message
Source code in academy/message.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def model_from_json(cls, data: str) -> Message:
    """Reconstruct a specific message from a JSON dump.

    Example:
        ```python
        from academy.message import BaseMessage, ActionRequest

        message = ActionRequest(...)
        dump = message.model_dump_json()
        assert BaseMessage.model_from_json(dump) == message
        ```
    """
    return TypeAdapter(Message).validate_json(data)

model_deserialize classmethod 

model_deserialize(data: bytes) -> Message

Deserialize a message.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@classmethod
def model_deserialize(cls, data: bytes) -> Message:
    """Deserialize a message.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    message = pickle.loads(data)
    if not isinstance(message, get_args(Message)):
        raise TypeError(
            'Deserialized message is not of type Message.',
        )
    return message

model_serialize 

model_serialize() -> bytes

Serialize a message to bytes.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
89
90
91
92
93
94
95
96
def model_serialize(self) -> bytes:
    """Serialize a message to bytes.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    return pickle.dumps(self)

ActionResponse pydantic-model

Bases: BaseMessage

Agent action response message.

Fields:

Validators:

action pydantic-field 

action: str

Name of the requested action.

result pydantic-field 

result: Any = None

Result of the action, if successful.

exception pydantic-field 

exception: Optional[Exception] = None

Exception of the action, if unsuccessful.

tag pydantic-field 

tag: UUID

Unique message tag used to match requests and responses.

src pydantic-field 

src: EntityId

Source mailbox address.

dest pydantic-field 

dest: EntityId

Destination mailbox address.

label pydantic-field 

label: Optional[UUID] = None

Optional label used to disambiguate response messages when multiple objects (i.e., handles) share the same mailbox. This is a different usage from the tag.

model_from_json classmethod 

model_from_json(data: str) -> Message

Reconstruct a specific message from a JSON dump.

Example 
from academy.message import BaseMessage, ActionRequest

message = ActionRequest(...)
dump = message.model_dump_json()
assert BaseMessage.model_from_json(dump) == message
Source code in academy/message.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def model_from_json(cls, data: str) -> Message:
    """Reconstruct a specific message from a JSON dump.

    Example:
        ```python
        from academy.message import BaseMessage, ActionRequest

        message = ActionRequest(...)
        dump = message.model_dump_json()
        assert BaseMessage.model_from_json(dump) == message
        ```
    """
    return TypeAdapter(Message).validate_json(data)

model_deserialize classmethod 

model_deserialize(data: bytes) -> Message

Deserialize a message.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@classmethod
def model_deserialize(cls, data: bytes) -> Message:
    """Deserialize a message.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    message = pickle.loads(data)
    if not isinstance(message, get_args(Message)):
        raise TypeError(
            'Deserialized message is not of type Message.',
        )
    return message

model_serialize 

model_serialize() -> bytes

Serialize a message to bytes.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
89
90
91
92
93
94
95
96
def model_serialize(self) -> bytes:
    """Serialize a message to bytes.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    return pickle.dumps(self)

PingRequest pydantic-model

Bases: BaseMessage

Ping request message.

Fields:

tag pydantic-field 

tag: UUID

Unique message tag used to match requests and responses.

src pydantic-field 

src: EntityId

Source mailbox address.

dest pydantic-field 

dest: EntityId

Destination mailbox address.

label pydantic-field 

label: Optional[UUID] = None

Optional label used to disambiguate response messages when multiple objects (i.e., handles) share the same mailbox. This is a different usage from the tag.

response 

response() -> PingResponse

Construct a ping response message.

Source code in academy/message.py 
220
221
222
223
224
225
226
227
228
def response(self) -> PingResponse:
    """Construct a ping response message."""
    return PingResponse(
        tag=self.tag,
        src=self.dest,
        dest=self.src,
        label=self.label,
        exception=None,
    )

error 

error(exception: Exception) -> PingResponse

Construct an error response to ping request.

Parameters:

  • exception (Exception) –

    Error of the action.

Source code in academy/message.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
def error(self, exception: Exception) -> PingResponse:
    """Construct an error response to ping request.

    Args:
        exception: Error of the action.
    """
    return PingResponse(
        tag=self.tag,
        src=self.dest,
        dest=self.src,
        label=self.label,
        exception=exception,
    )

model_from_json classmethod 

model_from_json(data: str) -> Message

Reconstruct a specific message from a JSON dump.

Example 
from academy.message import BaseMessage, ActionRequest

message = ActionRequest(...)
dump = message.model_dump_json()
assert BaseMessage.model_from_json(dump) == message
Source code in academy/message.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def model_from_json(cls, data: str) -> Message:
    """Reconstruct a specific message from a JSON dump.

    Example:
        ```python
        from academy.message import BaseMessage, ActionRequest

        message = ActionRequest(...)
        dump = message.model_dump_json()
        assert BaseMessage.model_from_json(dump) == message
        ```
    """
    return TypeAdapter(Message).validate_json(data)

model_deserialize classmethod 

model_deserialize(data: bytes) -> Message

Deserialize a message.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@classmethod
def model_deserialize(cls, data: bytes) -> Message:
    """Deserialize a message.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    message = pickle.loads(data)
    if not isinstance(message, get_args(Message)):
        raise TypeError(
            'Deserialized message is not of type Message.',
        )
    return message

model_serialize 

model_serialize() -> bytes

Serialize a message to bytes.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
89
90
91
92
93
94
95
96
def model_serialize(self) -> bytes:
    """Serialize a message to bytes.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    return pickle.dumps(self)

PingResponse pydantic-model

Bases: BaseMessage

Ping response message.

Fields:

Validators:

exception pydantic-field 

exception: Optional[Exception] = None

Exception of the ping, if unsuccessful.

tag pydantic-field 

tag: UUID

Unique message tag used to match requests and responses.

src pydantic-field 

src: EntityId

Source mailbox address.

dest pydantic-field 

dest: EntityId

Destination mailbox address.

label pydantic-field 

label: Optional[UUID] = None

Optional label used to disambiguate response messages when multiple objects (i.e., handles) share the same mailbox. This is a different usage from the tag.

model_from_json classmethod 

model_from_json(data: str) -> Message

Reconstruct a specific message from a JSON dump.

Example 
from academy.message import BaseMessage, ActionRequest

message = ActionRequest(...)
dump = message.model_dump_json()
assert BaseMessage.model_from_json(dump) == message
Source code in academy/message.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def model_from_json(cls, data: str) -> Message:
    """Reconstruct a specific message from a JSON dump.

    Example:
        ```python
        from academy.message import BaseMessage, ActionRequest

        message = ActionRequest(...)
        dump = message.model_dump_json()
        assert BaseMessage.model_from_json(dump) == message
        ```
    """
    return TypeAdapter(Message).validate_json(data)

model_deserialize classmethod 

model_deserialize(data: bytes) -> Message

Deserialize a message.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@classmethod
def model_deserialize(cls, data: bytes) -> Message:
    """Deserialize a message.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    message = pickle.loads(data)
    if not isinstance(message, get_args(Message)):
        raise TypeError(
            'Deserialized message is not of type Message.',
        )
    return message

model_serialize 

model_serialize() -> bytes

Serialize a message to bytes.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
89
90
91
92
93
94
95
96
def model_serialize(self) -> bytes:
    """Serialize a message to bytes.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    return pickle.dumps(self)

ShutdownRequest pydantic-model

Bases: BaseMessage

Agent shutdown request message.

Fields:

Validators:

  • _validate_agent → dest

tag pydantic-field 

tag: UUID

Unique message tag used to match requests and responses.

src pydantic-field 

src: EntityId

Source mailbox address.

dest pydantic-field 

dest: EntityId

Destination mailbox address.

label pydantic-field 

label: Optional[UUID] = None

Optional label used to disambiguate response messages when multiple objects (i.e., handles) share the same mailbox. This is a different usage from the tag.

response 

response() -> ShutdownResponse

Construct a shutdown response message.

Source code in academy/message.py 
298
299
300
301
302
303
304
305
306
def response(self) -> ShutdownResponse:
    """Construct a shutdown response message."""
    return ShutdownResponse(
        tag=self.tag,
        src=self.dest,
        dest=self.src,
        label=self.label,
        exception=None,
    )

error 

error(exception: Exception) -> ShutdownResponse

Construct an error response to shutdown request.

Parameters:

  • exception (Exception) –

    Error of the action.

Source code in academy/message.py 
308
309
310
311
312
313
314
315
316
317
318
319
320
def error(self, exception: Exception) -> ShutdownResponse:
    """Construct an error response to shutdown request.

    Args:
        exception: Error of the action.
    """
    return ShutdownResponse(
        tag=self.tag,
        src=self.dest,
        dest=self.src,
        label=self.label,
        exception=exception,
    )

model_from_json classmethod 

model_from_json(data: str) -> Message

Reconstruct a specific message from a JSON dump.

Example 
from academy.message import BaseMessage, ActionRequest

message = ActionRequest(...)
dump = message.model_dump_json()
assert BaseMessage.model_from_json(dump) == message
Source code in academy/message.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def model_from_json(cls, data: str) -> Message:
    """Reconstruct a specific message from a JSON dump.

    Example:
        ```python
        from academy.message import BaseMessage, ActionRequest

        message = ActionRequest(...)
        dump = message.model_dump_json()
        assert BaseMessage.model_from_json(dump) == message
        ```
    """
    return TypeAdapter(Message).validate_json(data)

model_deserialize classmethod 

model_deserialize(data: bytes) -> Message

Deserialize a message.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@classmethod
def model_deserialize(cls, data: bytes) -> Message:
    """Deserialize a message.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    message = pickle.loads(data)
    if not isinstance(message, get_args(Message)):
        raise TypeError(
            'Deserialized message is not of type Message.',
        )
    return message

model_serialize 

model_serialize() -> bytes

Serialize a message to bytes.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
89
90
91
92
93
94
95
96
def model_serialize(self) -> bytes:
    """Serialize a message to bytes.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    return pickle.dumps(self)

ShutdownResponse pydantic-model

Bases: BaseMessage

Agent shutdown response message.

Fields:

Validators:

exception pydantic-field 

exception: Optional[Exception] = None

Exception of the request, if unsuccessful.

tag pydantic-field 

tag: UUID

Unique message tag used to match requests and responses.

src pydantic-field 

src: EntityId

Source mailbox address.

dest pydantic-field 

dest: EntityId

Destination mailbox address.

label pydantic-field 

label: Optional[UUID] = None

Optional label used to disambiguate response messages when multiple objects (i.e., handles) share the same mailbox. This is a different usage from the tag.

model_from_json classmethod 

model_from_json(data: str) -> Message

Reconstruct a specific message from a JSON dump.

Example 
from academy.message import BaseMessage, ActionRequest

message = ActionRequest(...)
dump = message.model_dump_json()
assert BaseMessage.model_from_json(dump) == message
Source code in academy/message.py 
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@classmethod
def model_from_json(cls, data: str) -> Message:
    """Reconstruct a specific message from a JSON dump.

    Example:
        ```python
        from academy.message import BaseMessage, ActionRequest

        message = ActionRequest(...)
        dump = message.model_dump_json()
        assert BaseMessage.model_from_json(dump) == message
        ```
    """
    return TypeAdapter(Message).validate_json(data)

model_deserialize classmethod 

model_deserialize(data: bytes) -> Message

Deserialize a message.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
@classmethod
def model_deserialize(cls, data: bytes) -> Message:
    """Deserialize a message.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    message = pickle.loads(data)
    if not isinstance(message, get_args(Message)):
        raise TypeError(
            'Deserialized message is not of type Message.',
        )
    return message

model_serialize 

model_serialize() -> bytes

Serialize a message to bytes.

Warning

This uses pickle and is therefore suceptible to all the typical pickle warnings about code injection.

Source code in academy/message.py 
89
90
91
92
93
94
95
96
def model_serialize(self) -> bytes:
    """Serialize a message to bytes.

    Warning:
        This uses pickle and is therefore suceptible to all the
        typical pickle warnings about code injection.
    """
    return pickle.dumps(self)