Publish mixed Perseus + native QTI exercise nodes as one QTI package

[rtibblesbot]

Summary

• Mixed Perseus + native QTI nodes had no publish path — the publisher picked one generator, so a mixed node produced neither a complete package.
• Mixed nodes now route to the QTI generator; each raw Perseus question becomes a qti-custom-interaction data-type="perseus" (Perseus JSON + assets declared in the manifest) that Kolibri's Perseus renderer owns.
• The wrapper is a complete, gradable QTI question: a RESPONSE record variable holds the renderer's outcome and inline response processing maps its correct field to a 0/1 SCORE (expressed inline because no standard response-processing template can read a record field).
• The QTI_ZIP file sets included_presets = qti | exercise so older Kolibri also loads the Perseus renderer.

References

Closes #6006. Depends on #6004 (File.included_presets, landed on unstable via #6046). Renderer counterpart: learningequality/kolibri#14892.

Reviewer guidance

• utils/publish.py selection — confirm a Perseus-only node still routes to PerseusExerciseGenerator.
• utils/publish.py selection — confirm a native-QTI-only node's routing is unchanged.
• utils/publish.py — confirm the qti_embeds_perseus flag (raw Perseus and native QTI in the same node) is derived from the same assessment_mapping that selects the generator, and that create_associated_file_objects sets the exercise bit only on the QTI_ZIP file when that flag is set.
• utils/assessment/qti/archive.py _create_perseus_custom_interaction — check the {☣ LOCALPATH}/perseus/images/... rewrite matches how the Kolibri renderer resolves data-perseus-path-relative assets.
• utils/assessment/qti/convert.py build_perseus_custom_interaction_item — confirm the RESPONSE record and inline response processing (correct field → 0/1 SCORE) match the record fields the renderer reports back.

AI usage

Used Claude Code to implement the change against a pre-approved plan with test-driven development. Verified with the affected pytest suites (test_convert.py, test_exercise_creation.py, test_exportchannel.py), a makemigrations --check, and pre-commit lint.

---

@rtibblesbot's comments are generated by an LLM, and should be evaluated accordingly

How was this generated?

• Ran pre-flight CI checks (lint, format, tests) and verified all pass
• Rebased onto the target branch and resolved any conflicts
• Reorganized commit history into clean, logical commits
• Audited the diff to ensure only issue-relevant files are changed
• Built PR body from the repository's PR template with evidence blocks

🟡 Waiting for feedback Last updated: 2026-07-18 17:27 UTC

[rtibbles]

Mostly looking good, some questions of things I'm less sure about.

[rtibbles]

This test seems repetitive of the exercise creation tests?

[rtibblesbot]

Agreed — removed test_mixed_node_package_lists_both_question_kinds.

Its assertions (both item kinds present, Perseus JSON packaged, qti-custom-interaction with data-type="perseus") duplicate the generator-level test_perseus_custom_interaction_embedded_with_native_qti in tests/utils/test_exercise_creation.py, which covers the same package contents more thoroughly. The mixed-node publish path stays covered here by test_mixed_perseus_and_native_qti_routes_to_qti (routing) and test_mixed_qti_file_included_presets (the qti | exercise bit). Done in 3f7a67f.

[rtibbles]

Does this really need an additional query? Also, could there be an edge case where this is true, but the question itself did not publish, wasn't complete? etc?

Wouldn't it be easier just to set this as discovered during the generation process, so that we don't have to look for it again, and we ground it in what was actually generated?

[rtibblesbot]

Good call on both counts. Dropped the extra assessment_items.filter(type=PERSEUS_QUESTION).exists() query.

The mixed-node decision is already made during routing in recurse_nodes as any_perseus_question and any_native_qti — the exact condition that sends the node to QTIExerciseGenerator and embeds the Perseus custom interactions. I now capture it there as qti_embeds_perseus and thread it into create_associated_file_objects, so the included_presets |= exercise bit is grounded in the same decision that drives the embedding rather than re-derived.

That also closes the edge case you raised: the flag and the packaged contents now come from one source and cannot diverge. Done in b47f996.

[rtibbles]

This isn't going to quite work as is - we need to properly handle the response, and also do outcome processing, so that this gets handled completely as a QTI question.

[rtibbles]

The perseus renderer returns an object for its response, of this shape:

{
            correct,
            answerState,
            simpleAnswer,
          }

So, the response declaration will have to be of record cardinality, I think? correct is a boolean, simpleAnswer is a string. Unfortunately answerState is an arbitrary Javascript object, so I think we'll have to store it as a stringified JSON.

The outcome declaration will therefore be checking the correct property in order to mark correct/incorrect.

[rtibblesbot]

Done in 232b534. RESPONSE is now declared with record cardinality, and grading reads its correct field. On the field types: QTI record declarations do not enumerate their fields (records are open, each field carries its own base-type at runtime), so the correct (boolean) / simpleAnswer (string) / answerState (stringified JSON) shape is documented as the renderer contract in the builder docstring rather than declared. The item only needs to read correct to grade, which response processing now does.

[rtibbles]

As per below, this AssessmentItem needs an outcome declaration and a response processing template associated with it (which can be the default correct/incorrect template - we just need the special outcome declaration for checking the correct property.

[rtibblesbot]

Done in 232b534. The item now has a SCORE outcome declaration plus response processing that grades correct/incorrect.

One deviation worth flagging: I could not use the standard match_correct template. That template compares RESPONSE to a declared correctResponse, and there is no standard response-processing template that can inspect a single field of a record. So instead of a template=... reference I emit the equivalent grading inline:

<qti-response-processing>
  <qti-response-condition>
    <qti-response-if>
      <qti-field-value field-identifier="correct">
        <qti-variable identifier="RESPONSE"/>
      </qti-field-value>
      <qti-set-outcome-value identifier="SCORE">
        <qti-base-value base-type="float">1</qti-base-value>
      </qti-set-outcome-value>
    </qti-response-if>
    <qti-response-else>
      <qti-set-outcome-value identifier="SCORE">
        <qti-base-value base-type="float">0</qti-base-value>
      </qti-set-outcome-value>
    </qti-response-else>
  </qti-response-condition>
</qti-response-processing>

Same correct/incorrect (1/0) semantics as the default template, just reading the record's correct field. This required adding the minimal QTI rule/expression models (qti-response-condition, qti-response-if/else, qti-field-value, qti-variable, qti-set-outcome-value, qti-base-value). The full item validates against the QTI 3.0 XSD. Happy to switch to a template reference instead if you would rather the host own this grading step.

[rtibbles]

Just one small bit of cleanup, reversing something I said in the last review round. Let's also rationalize the commit history to be about where we have got to, not how we got here.

[rtibbles]

Actually, because we don't need to specify the schema for the record type, there's no need for answerState to be stringified - it can just be the plain object.

[rtibblesbot]

Done in 94f1a46. The docstring no longer describes answerState as stringified JSON — RESPONSE is a record declared with no schema, so each field carries its own base-type at runtime and answerState is just the plain object. Nothing in the builder ever stringified it (the item only reads correct to grade), so this is a documentation-only change.

Also rationalized the branch history as requested: the iteration commits (grade-completely, ground-the-exercise-bit, drop-redundant-test) are folded into four commits describing the final state rather than how it got there.

[rtibbles]

Changes make sense, and the Kolibri side issue has been updated with the additional details here, so we should have a secure contract.