2.6. <tutor_message>

Representing tutor response

2.6.1. Attributes of <tutor_message>

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

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:

meta
event_descriptor
semantic_event (required)
ui_event (unused by DataShop)
custom_field
replay (unused by DataShop)

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

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

Description	Preferred	Other common values
Student's action was correct	`CORRECT`	`OK`
Student's action was incorrect	`INCORRECT`	`BUG` `ERROR`
Student requested a hint	`HINT`	`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

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

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

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
	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>.

Prev	Up	Next
2.5. <tool_message>	Home	2.7. <message>

	Caution
	DataShop does not import either of these attributes.