[QTI] Publish mixed Perseus + QTI exercises as one QTI package

[rtibbles]

Overview

Let a single exercise node containing both raw Perseus questions and QTI questions publish together as one QTI package. Raw Perseus questions are wrapped in a custom QTI interaction that Kolibri's QTI Viewer renders via the Perseus renderer (Kolibri side: learningequality/kolibri#14892).

Complexity: High
Target branch: unstable

Context

• Today a node publishes either Perseus or QTI, never both. publish.py:370-374 picks QTIExerciseGenerator when any question is free-response and PerseusExerciseGenerator otherwise, one generator per node.
• Nodes mixing legacy Perseus with new QTI questions therefore have no publish path.
• The mixed package needs the Perseus renderer too, so its qti File sets the exercise bit in the included_presets bitmask (Publish a renderer-preset bitmask (File.included_presets) into the content database #6004).

The Change

• Relax the one-generator-per-node selection in publish.py (370-374) so a node whose questions include both raw Perseus and QTI items routes to QTIExerciseGenerator.
• Have QTIExerciseGenerator emit each raw Perseus question as the custom interaction defined below.
• Set the mixed qti File's included_presets to qti | exercise when it embeds ≥1 Perseus custom interaction.

Contract — Perseus-in-QTI custom interaction

Shared with the Kolibri renderer issue. Exact attribute validity is confirmed against the QTI 3.0 XSD under #6005.

• Each raw Perseus question is a qti-custom-interaction (the spec's delivery-engine-specific element — no JS module required) with a data-type="perseus" marker.
• The Perseus JSON is a resource file in the package, referenced by data-perseus-path.
• Every file that JSON references (images, graphie .svg/-data.json) is packaged and declared as a dependency of that resource in the manifest.
• The host's Perseus renderer, keyed off data-type="perseus", owns rendering and grading. It reports the resulting correct/incorrect back through the QTI response, with no QTI-native response-processing template.

<qti-custom-interaction
    response-identifier="RESPONSE"
    data-type="perseus"
    data-perseus-path="perseus/{assessment_id}.json"/>

Acceptance Criteria

• A mixed node yields one QTI package whose manifest lists both native QTI items and Perseus custom interactions
• Each Perseus custom interaction references its Perseus JSON and assets as package files (see Contract)
• The package validates against the QTI 3.0 XSD ([QTI] QTI 3.0 schema XML validation utilities #6005)
• The mixed qti File has included_presets = qti | exercise
• Native QTI questions in the same node are unaffected
• Tests cover a mixed node and assert both question kinds appear in the package

References

• Publish a renderer-preset bitmask (File.included_presets) into the content database #6004 — File.included_presets bitmask column and base population (blocks this issue)
• Allow Kolibri to render QTI assessments kolibri#11428 — Kolibri QTI rendering
• [QTI] Render embedded Perseus questions in the QTI viewer kolibri#14892 — Kolibri renderer counterpart (Perseus custom-interaction rendering)

AI usage

Claude mapped the existing publish and validation code, proposed the breakdown, and drafted this issue; the maintainer steered every decision and reviewed throughout.

[rtibblesbot]

Triage: blocking prerequisite not on the target branch

This issue targets unstable, and AC #4 ("mixed qti File has included_presets = qti | exercise") depends on #6004. #6004 is closed via #6040, but that PR merged into hotfixes, not unstable:

• File.included_presets (model + kolibri_content/kolibri_public migrations + publish population) exists on origin/hotfixes.
• It is absent from origin/unstable — a branch off unstable today cannot set included_presets.

The rest of the spec is implementable as written: the routing change (publish.py mixed node → QTIExerciseGenerator), the qti-custom-interaction data-type="perseus" contract, and asset packaging are clear, and the QTI 3.0 XSD (#6005) plus the ingest-side custom-interaction parsing are already present on unstable.

Need a decision before implementation:

1. Merge hotfixes (or just the feat: export included_presets renderable bitmask for content-schema import gating #6040 changes) into unstable first, then implement here; or
2. Retarget [QTI] Publish mixed Perseus + QTI exercises as one QTI package #6006 at hotfixes; or
3. Confirm [QTI] Publish mixed Perseus + QTI exercises as one QTI package #6006 should include re-adding the included_presets column on unstable (risks conflicting with the hotfixes version on the next integration).

Which path?

[rtibblesbot]

The bot has been waiting for a response for 2 hour(s). It will resume automatically when someone replies.

[rtibbles]

hotfixes has been merged into unstable now, so this should be unblocked.

[rtibblesbot]

Plan: Let one exercise node holding both raw Perseus questions and native QTI questions publish as a single QTI package, emitting each raw Perseus question as a qti-custom-interaction data-type="perseus" that Kolibri's Perseus renderer owns.

• CustomInteraction model + item builder
• Extract raw-Perseus asset writing into the base generator
• QTIExerciseGenerator embeds perseus_question items
• Phase 1 simplify pass
• Mixed-node generator selection in publish.py
• Stamp included_presets = qti | exercise on the mixed QTI file
• End-to-end acceptance test — mixed package contents
• Phase 2 simplify pass + full-suite verification

---

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

How was this generated?

• Implemented code following the pre-approved plan using test-driven development (red-green-refactor)
• Ran the project's full test suite and linter before committing
• For UI changes: captured live screenshots to verify rendering
• For backend changes: verified with example API/CLI output

[rtibblesbot]

The bot has been waiting for a response for 2 hour(s). It will resume automatically when someone replies.

[rtibblesbot]

The bot has been waiting for a response for 2 hour(s). It will resume automatically when someone replies.