add documentation for MEssages (facebookresearch#2339)

docs/source/observations.rst → 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
 ----

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 <observations>` documentation goes into more detail about
+The :doc:`messages <messages>` documentation goes into more detail about
 each field, but the following table shows the basics.
 
 

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):