diff --git a/docs/source/observations.rst b/docs/source/messages.rst similarity index 94% rename from docs/source/observations.rst rename to docs/source/messages.rst index f79ab1b6687..517321e51a9 100644 --- a/docs/source/observations.rst +++ b/docs/source/messages.rst @@ -1,14 +1,15 @@ -observations +messages ============ .. image:: _static/img/act-obs-dict.png :width: 60 % The primary medium for information flow (messages between agents and the environment) -in ParlAI is a python ``dict`` containing the actions of an agent -(observable by other agents or the environment). +in ParlAI is a Message, a subclass of a python ``dict`` containing the actions of an agent +(observable by other agents or the environment). The Message object is defined at +``parlai/core/message.py``. -We generally refer to this as an observation dict. +We generally refer to these messages as observations or acts. One should be created by an agent's ``act()`` function, and it will be passed to another agent's ``observe()`` function as the sole argument. @@ -21,6 +22,10 @@ or even to multi-task. If necessary, teachers can include other data in this dict using other field names. See `extended fields`_ below. +The primary function of the ``Message`` object is to ensure that agents do not +unintentionally edit the fields within observations and actions. In order to edit +the field of a ``Message`` object, one must call ``message.force_set(key, new_value)``. + text ---- diff --git a/docs/source/tutorial_basic.rst b/docs/source/tutorial_basic.rst index a57eaccb062..995e137e087 100644 --- a/docs/source/tutorial_basic.rst +++ b/docs/source/tutorial_basic.rst @@ -58,14 +58,14 @@ and updates this agent's internal state accordingly. return the next batch of examples. For a neural net agent, this could be a train step or eval step. -Observations +Messages ^^^^^^^^^^^^ -Observations are what we call the objects returned by an agent's act function and are so named -because they are input to other agents' observe() functions. -This is the primary way messages are passed between agents and the environment in ParlAI. -Observations are usually in the form of python dictionaries containing different types of information. +Messages are what we call the objects both observed by an agent (observations) and returned by an agent's act function (actions). +These observations and actions are the primary way agents in ParlAI communicate with each other within their enviroment. +The Message object is a subclass of a python dict, whose key function is to prevent users from editing +fields in an action or observation unintentionally. -The :doc:`observations ` documentation goes into more detail about +The :doc:`messages ` documentation goes into more detail about each field, but the following table shows the basics. diff --git a/docs/source/tutorial_task.rst b/docs/source/tutorial_task.rst index fdb8a823f11..b11f03524ac 100644 --- a/docs/source/tutorial_task.rst +++ b/docs/source/tutorial_task.rst @@ -547,7 +547,10 @@ and we only have one question per episode, so we can reuse that definition. Next we need to implement the ``get()`` function. This has two arguments: which episode we want to pull from, and then the index within that episode of the specific example we want. Since every episode has only one entry in this dataset, -we provide a default for the keyword and ignore it. +we provide a default for the keyword and ignore it. Actions return from ``get()`` +should be wrapped in the ``Message`` class, defined at ``parlai/core/message.py``, +which ensures that the fields of the action are not unintentionally edited by +the agents that observe it. We also define the DefaultTeacher class to refer to this one. This task also includes another teacher which includes multiple choice candidates, @@ -571,7 +574,7 @@ but we don't include that in this tutorial. anno = self.annotation['annotations'][episode_idx] action['labels'] = [ans['answer'] for ans in anno['answers']] - return action + return Message(action) class DefaultTeacher(OeTeacher):