Add CustomInteraction QTI model and graded Perseus item builder

Introduce a `CustomInteraction` element (`qti-custom-interaction`) and
`build_perseus_custom_interaction_item`, which wraps a raw Perseus question
in a schema-valid `qti-assessment-item` marked `data-type="perseus"`.

The Perseus renderer owns rendering and grading, reporting its result
through the RESPONSE variable as a record (fields: `correct` boolean,
`simpleAnswer` string, `answerState` object). RESPONSE is declared with
record cardinality and no schema, so each field carries its own base-type
at runtime and `answerState` need not be stringified. A SCORE outcome plus
inline response processing reads the record's `correct` field and sets SCORE
to 1/0, so the item grades as a complete QTI question. The response-
processing rule/expression models this needs are added alongside, and
ResponseDeclaration's base-type is made optional for record cardinality.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rtibblesbot

contentcuration/contentcuration/tests/utils/qti/test_convert.py

@@ -3,10 +3,17 @@
 
 from le_utils.constants import exercises
 
+from contentcuration.utils.assessment.qti.convert import (
+    build_perseus_custom_interaction_item,
+)
 from contentcuration.utils.assessment.qti.convert import (
     convert_legacy_assessment_item_to_qti,
 )
+from contentcuration.utils.assessment.qti.convert import hex_to_qti_id
 from contentcuration.utils.assessment.qti.convert import LegacyAssessmentItem
+from contentcuration.utils.assessment.qti.interaction_types.custom import (
+    CustomInteraction,
+)
 from contentcuration.utils.assessment.qti.validation import validate_qti_item
 
 
@@ -232,6 +239,65 @@ def test_free_response_with_maths(self):
         )
 
 
+class CustomInteractionTests(unittest.TestCase):
+    ASSESSMENT_ID = "2b1c3d4e5f60718293a4b5c6d7e8f900"
+
+    def _build_item(self):
+        return build_perseus_custom_interaction_item(
+            self.ASSESSMENT_ID,
+            f"perseus/{self.ASSESSMENT_ID}.json",
+            "Q 1",
+            "en",
+        )
+
+    def test_custom_interaction_element_and_attributes(self):
+        interaction = CustomInteraction(
+            response_identifier="RESPONSE",
+            data_type="perseus",
+            data_perseus_path="perseus/abc.json",
+        )
+
+        xml = interaction.to_xml_string()
+
+        self.assertEqual(
+            _normalize_xml(
+                '<qti-custom-interaction response-identifier="RESPONSE" '
+                'data-type="perseus" data-perseus-path="perseus/abc.json" />'
+            ),
+            _normalize_xml(xml),
+        )
+
+    def test_builder_identifier_and_validity(self):
+        result = self._build_item()
+
+        self.assertEqual(result.identifier, hex_to_qti_id(self.ASSESSMENT_ID))
+        self.assertEqual(result.file_dependencies, [])
+        self.assertTrue(validate_qti_item(result.xml.encode("utf-8")).is_valid)
+        self.assertIn('data-type="perseus"', result.xml)
+        self.assertIn(
+            f'data-perseus-path="perseus/{self.ASSESSMENT_ID}.json"', result.xml
+        )
+
+    def test_builder_grades_from_record_correct_field(self):
+        """
+        The Perseus renderer reports its result through a record RESPONSE, and
+        the item grades itself off that record's ``correct`` field.
+        """
+        result = self._build_item()
+
+        normalized = _normalize_xml(result.xml)
+        # RESPONSE is a record so it can carry correct/simpleAnswer/answerState.
+        self.assertIn(
+            '<qti-response-declaration identifier="RESPONSE" cardinality="record"',
+            normalized,
+        )
+        # SCORE outcome plus response processing that reads the correct field.
+        self.assertIn('<qti-outcome-declaration identifier="SCORE"', normalized)
+        self.assertIn('<qti-field-value field-identifier="correct">', normalized)
+        self.assertIn('<qti-variable identifier="RESPONSE"', normalized)
+        self.assertIn('<qti-set-outcome-value identifier="SCORE">', normalized)
+
+
 class UnsupportedTypeConversionTests(unittest.TestCase):
     def test_unsupported_type_raises(self):
         item = _make_item(

contentcuration/contentcuration/utils/assessment/qti/assessment_item.py

@@ -194,7 +194,9 @@ class ResponseDeclaration(QTIBase):
 
     identifier: QTIIdentifier
     cardinality: Cardinality
-    base_type: BaseType
+    # base-type is optional in the XSD and is omitted for record cardinality,
+    # whose fields each carry their own base-type at runtime.
+    base_type: Optional[BaseType] = None
     correct_response: Optional[CorrectResponse] = None
     mapping: Optional[Mapping] = None
     area_mapping: Optional[AreaMapping] = None
@@ -205,6 +207,57 @@ def validate_cardinality_compatibility(self):
         return self
 
 
+class BaseValue(QTIBase):
+    """A literal value of a given base-type (``qti-base-value`` expression)."""
+
+    base_type: BaseType
+    value: TextType
+
+
+class Variable(QTIBase):
+    """Look up the value of an item variable (``qti-variable`` expression)."""
+
+    identifier: QTIIdentifier
+
+
+class FieldValue(QTIBase):
+    """
+    Extract a named field from a record-cardinality expression
+    (``qti-field-value``). Used to read a single field, e.g. ``correct``, out of
+    a record response variable.
+    """
+
+    field_identifier: QTIIdentifier
+    variable: Variable
+
+
+class SetOutcomeValue(QTIBase):
+    """Assign an expression's value to an outcome variable."""
+
+    identifier: QTIIdentifier
+    base_value: BaseValue
+
+
+class ResponseIf(QTIBase):
+    """The 'if' branch of a response condition: a boolean expression plus a rule."""
+
+    field_value: FieldValue
+    set_outcome_value: SetOutcomeValue
+
+
+class ResponseElse(QTIBase):
+    """The 'else' branch of a response condition."""
+
+    set_outcome_value: SetOutcomeValue
+
+
+class ResponseCondition(QTIBase):
+    """An if/else response-processing rule (``qti-response-condition``)."""
+
+    response_if: ResponseIf
+    response_else: Optional[ResponseElse] = None
+
+
 class ResponseProcessing(QTIBase):
     """Represents response processing rules or template reference"""
 
@@ -213,7 +266,9 @@ class ResponseProcessing(QTIBase):
     # Optional URL that resolves to the template - we additionally enforce that this be local
     # although this is not required by the QTI spec
     template_location: Optional[LocalHrefPath] = None
-    # rules deliberately not implemented yet
+    # Inline response-processing rules, used when no standard template can express
+    # the grading (e.g. reading the correct/incorrect result out of a record).
+    children: List[ResponseCondition] = Field(default_factory=list)
 
 
 class AssessmentItem(QTIBase):

contentcuration/contentcuration/utils/assessment/qti/convert.py

@@ -12,12 +12,19 @@
 
 from contentcuration.utils.assessment.markdown import render_markdown
 from contentcuration.utils.assessment.qti.assessment_item import AssessmentItem
+from contentcuration.utils.assessment.qti.assessment_item import BaseValue
 from contentcuration.utils.assessment.qti.assessment_item import CorrectResponse
+from contentcuration.utils.assessment.qti.assessment_item import FieldValue
 from contentcuration.utils.assessment.qti.assessment_item import ItemBody
 from contentcuration.utils.assessment.qti.assessment_item import OutcomeDeclaration
+from contentcuration.utils.assessment.qti.assessment_item import ResponseCondition
 from contentcuration.utils.assessment.qti.assessment_item import ResponseDeclaration
+from contentcuration.utils.assessment.qti.assessment_item import ResponseElse
+from contentcuration.utils.assessment.qti.assessment_item import ResponseIf
 from contentcuration.utils.assessment.qti.assessment_item import ResponseProcessing
+from contentcuration.utils.assessment.qti.assessment_item import SetOutcomeValue
 from contentcuration.utils.assessment.qti.assessment_item import Value
+from contentcuration.utils.assessment.qti.assessment_item import Variable
 from contentcuration.utils.assessment.qti.base import ElementTreeBase
 from contentcuration.utils.assessment.qti.catalog import Card
 from contentcuration.utils.assessment.qti.catalog import Catalog
@@ -30,6 +37,9 @@
 from contentcuration.utils.assessment.qti.html import Div
 from contentcuration.utils.assessment.qti.html import FlowContentList
 from contentcuration.utils.assessment.qti.html import P
+from contentcuration.utils.assessment.qti.interaction_types.custom import (
+    CustomInteraction,
+)
 from contentcuration.utils.assessment.qti.interaction_types.simple import (
     ChoiceInteraction,
 )
@@ -208,6 +218,86 @@ def _create_text_entry_interaction_and_response(
     return interaction, response_declaration
 
 
+def build_perseus_custom_interaction_item(
+    assessment_id: str, perseus_path: str, title: str, language: str
+) -> QTIConversionResult:
+    """
+    Wrap a raw Perseus question in a schema-valid ``qti-assessment-item`` whose
+    body is a single ``qti-custom-interaction`` (``data-type="perseus"``).
+
+    The host's Perseus renderer owns rendering and grading, but the result is
+    handled as a complete QTI question. The renderer reports its outcome through
+    the ``RESPONSE`` variable as a record with fields ``correct`` (boolean),
+    ``simpleAnswer`` (string) and ``answerState`` (an arbitrary object). The
+    record declaration specifies no schema, so each field carries its own
+    base-type at runtime and ``answerState`` need not be stringified.
+    Response processing reads the ``correct`` field and sets
+    the ``SCORE`` outcome to 1 (correct) or 0 (incorrect) - the standard
+    correct/incorrect grading, expressed inline because no standard response
+    processing template can inspect a record field.
+
+    The Perseus JSON and its assets are declared as package files by the
+    generator, not tracked from this XML, so ``file_dependencies`` is empty.
+    """
+    identifier = hex_to_qti_id(assessment_id)
+
+    item = AssessmentItem(
+        identifier=identifier,
+        title=title,
+        language=language,
+        adaptive=False,
+        time_dependent=False,
+        response_declaration=[
+            ResponseDeclaration(
+                identifier="RESPONSE",
+                cardinality=Cardinality.RECORD,
+            )
+        ],
+        outcome_declaration=[
+            OutcomeDeclaration(
+                identifier="SCORE",
+                cardinality=Cardinality.SINGLE,
+                base_type=BaseType.FLOAT,
+            )
+        ],
+        item_body=ItemBody(
+            children=[
+                CustomInteraction(
+                    response_identifier="RESPONSE",
+                    data_type="perseus",
+                    data_perseus_path=perseus_path,
+                )
+            ]
+        ),
+        response_processing=ResponseProcessing(
+            children=[
+                ResponseCondition(
+                    response_if=ResponseIf(
+                        field_value=FieldValue(
+                            field_identifier="correct",
+                            variable=Variable(identifier="RESPONSE"),
+                        ),
+                        set_outcome_value=SetOutcomeValue(
+                            identifier="SCORE",
+                            base_value=BaseValue(base_type=BaseType.FLOAT, value="1"),
+                        ),
+                    ),
+                    response_else=ResponseElse(
+                        set_outcome_value=SetOutcomeValue(
+                            identifier="SCORE",
+                            base_value=BaseValue(base_type=BaseType.FLOAT, value="0"),
+                        ),
+                    ),
+                )
+            ]
+        ),
+    )
+
+    xml = f'<?xml version="1.0" encoding="UTF-8"?>\n{item.to_xml_string()}'
+
+    return QTIConversionResult(identifier=identifier, xml=xml, file_dependencies=[])
+
+
 def convert_legacy_assessment_item_to_qti(
     item: LegacyAssessmentItem,
 ) -> QTIConversionResult:

contentcuration/contentcuration/utils/assessment/qti/interaction_types/custom.py

@@ -0,0 +1,14 @@
+from contentcuration.utils.assessment.qti.interaction_types.base import BlockInteraction
+
+
+class CustomInteraction(BlockInteraction):
+    """
+    A delivery-engine-specific interaction (``qti-custom-interaction``).
+
+    Used to embed a raw Perseus question in a QTI package: the host's Perseus
+    renderer, keyed off ``data-type="perseus"``, owns rendering and grading and
+    reports correctness back through the QTI response.
+    """
+
+    data_type: str
+    data_perseus_path: str