Guide to the Tutor Message format (v4) > The Tutor Message format > <tutor_message>

2.6. <tutor_message>

Representing tutor response

2.6.1. Attributes of <tutor_message>
2.6.2. Child elements
2.6.2.1. <action_evaluation>
2.6.2.2. <skill>
2.6.2.3. <tutor_advice>
2.6.2.4. <interpretation>

A <tutor_message> commonly describes an evaluation of a student action. It is similar to a <tool_message>, but contains additional information about the correctness of the student action.

Construct a <tutor_message> whenever the application evaluates a student action.

Figure 14. Structure of a <tutor_message> element

Structure of a <tutor_message> element

2.6.1. Attributes of <tutor_message>

<tutor_message> has a single, required attribute: context_message_id. The value of this attribute must be the same for all tool and tutor messages described by the opening <context_message>, and it should be identical to the one specified in the <context_message>.

2.6.2. Child elements

Many child elements in a <tutor_message> are structurally identical to the same elements in a <tool_message>, but serve different purposes. For example, <event_descriptor> in a <tutor_message> should describe the desired action on the step. Similarly, <semantic_event> should describe the purpose of the tutor's response.

The elements described in <tool_message> that also appear in <tutor_message> are:

In addition, the following elements can appear in a tutor message:

2.6.2.1. <action_evaluation>
Optional. Maximum length of ≤ 30 characters.

An action evaluation is the result of the tutor's evaluation of a student's action. The evaluation value is expected as the text content of this element.

Zero or more <action_evaluation> elements are permissible; however, only one is expected and used/imported by DataShop.

Figure 15. Structure of an <action_evaluation> element

Structure of an <action_evaluation> element

DataShop expects the content of the <action_evaluation> element to be one of the values defined in Table 3, “Recommended values for the <action_evaluation> element”. Any other value will become "unknown" in the DataShop Error Report.

Table 3. Recommended values for the <action_evaluation> element

DescriptionPreferredOther common values 
Student's action was correctCORRECTOK
Student's action was incorrectINCORRECT
  • BUG

  • ERROR

Student requested a hintHINT
  • HELP

  • GLOSSARY_ITEM


Attributes of <action_evaluation>

<action_evaluation> has four attributes:

  • classification: the type of error (e.g., "sign error") or type of hint. Maximum length of ≤ 255 characters.

  • current_hint_number: only used if the <action_evaluation> is HINT

  • total_hints_available: only used if the <action_evaluation> is HINT

  • hint_id: a unique ID of the hint; only used if <action_evaluation> is HINT. Can be used to identify hints that are all the same but have different variables filled in depending on the problem.

2.6.2.2. <skill>
Optional.

The <skill> element is used to associate a knowledge component with a tutor response (and optionally, to provide updates to a knowledge-tracing system that tracks the probability of a student mastering a skill.)

Zero or more <skill> elements are allowed.

Figure 16. Structure of a <skill> element

Structure of a <skill> element

Attributes of <skill>

The <skill> element has two attributes:

  • probability: the probability that the student knows the skill

  • buggy: whether or not the skill associated with this tutor response is a "buggy" skill—this is a student misconception modeled or identified by the tutoring system. Can be true or false.

    [Caution]Caution

    DataShop does not import either of these attributes.

Child elements of <skill>
<skill><name>
Required. Maximum length of ≤ 65,535 characters.

The name of the skill (eg, "write-density").

[Note]Note

DataShop expects each skill name to be unique within a skill model (<model_name>).

<skill><category>
Optional. Maximum length of ≤ 50 characters.

A category that contains the skill (eg, "fraction-addition").

<skill><model_name>
Optional. Maximum length of ≤ 30 characters.

The name of a knowledge component model, which maps steps to knowledge components.

You can specify more than one model (multiple <model_name> elements), as the specified skill can exist in more than one model. Alternatively, you can create separate skill elements with the same skill name that specify different model names.

If <model_name> is empty or not defined, DataShop will use the value "Default".

2.6.2.3. <tutor_advice>
Optional. Maximum length of ≤ 65,535 characters.

This element captures the body of a hint, success, or error message shown to the student. It is generally a text value.

Figure 17. Structure of a <tutor_advice> element

Structure of a <tutor_advice> element

Example of <tutor_advice>
<tutor_message ...>
  ...
  <action_evaluation>INCORRECT</action_evaluation>
  <tutor_advice>Please work on the highlighted step.</tutor_advice>
</tutor_message>
2.6.2.4. <interpretation>

An interpretation is a tutor's plausible explanation for a student's action. It is an optional element. With some tutors, multiple interpretations exist for a single student action. These are competing explanations, and there should be only one "chosen" interpretation, signified via the chosen attribute.

[Caution]Caution

This element is likely to change in future versions of the Tutor Message format and should not be used.

Child elements

Its child elements are <correct_step_sequence> and <incorrect_step_sequence>, both of which have an attribute ordered, which can be either "true" or "false". When a tutor that provides interpretations evaluates a student action as correct, there is most likely a single interpretation with a <correct_step_sequence>. When that evaluation is of an incorrect action, there is likely to be both an <incorrect_step_sequence> and a <correct_step_sequence>.