crfm-helm 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

helm/benchmark/scenarios/vision_language/image2structure/webpage_scenario.py

@@ -0,0 +1,225 @@
+from typing import Dict, List, Any
+
+from helm.benchmark.scenarios.scenario import VALID_SPLIT
+from helm.benchmark.scenarios.vision_language.image2structure.image2structure_scenario import (
+    Image2StructureScenario,
+    PROCESSED,
+)
+from helm.benchmark.scenarios.vision_language.image2structure.webpage.jekyll_server import JekyllServer
+from helm.benchmark.scenarios.vision_language.image2structure.webpage.driver import (
+    save_random_screenshot,
+    ScreenshotOptions,
+)
+from helm.benchmark.scenarios.vision_language.image2structure.webpage.utils import convert_html_to_text
+from helm.common.general import ensure_directory_exists
+from helm.common.optional_dependencies import handle_module_not_found_error
+
+try:
+    from html2text import HTML2Text
+except ModuleNotFoundError as e:
+    handle_module_not_found_error(e, suggestions=["image2structure"])
+
+
+import base64
+import os
+import threading
+import tarfile
+import shutil
+import time
+import pickle
+
+
+def extract_repo(base64_encoding: str, repo_path: str) -> None:
+    # Decode the base64 string which corresponds to an archive
+    # and extract the files to the repo_path
+    try:
+        archive = base64.b64decode(base64_encoding)
+        # Write to .tar file
+        with open(os.path.join(repo_path, "repo.tar.gz"), "wb") as f:
+            f.write(archive)
+        # Extract
+        with tarfile.open(os.path.join(repo_path, "repo.tar.gz"), "r:gz") as tar:
+            tar.extractall(repo_path)
+    except Exception as e:
+        raise ValueError(f"Failed to decode and extract the base64 archive: {e}")
+
+
+def list_assets(repo_path: str, extensions: List[str]) -> List[str]:
+    asset_paths: List[str] = []
+    for root, _, files in os.walk(repo_path):
+        for file in files:
+            if file.split(".")[-1].lower() in extensions:
+                # Remove repo_path from the file path
+                # ignore paths that start with a dot or in _site
+                if not root.startswith(os.path.join(repo_path, "_site")) and not root.startswith(
+                    os.path.join(repo_path, ".")
+                ):
+                    asset_paths.append(os.path.relpath(os.path.join(root, file), repo_path))
+    return asset_paths
+
+
+def serve_and_take_screenshot(
+    repo_path: str,
+    destination_path: str,
+    screenshot_options: ScreenshotOptions = ScreenshotOptions(),
+    max_tries: int = 5,
+) -> Dict[str, Any]:
+    # Start the Jekyll server
+    # Select a unique port per thread
+    port: int = 4000 + int(threading.get_ident()) % 1000
+    server = JekyllServer(repo_path, port=port, verbose=False)
+    success: bool = server.start()
+    if not success:
+        # This runs on examples that are not expected to fail
+        server.stop()
+        raise ValueError(f"Jekyll server failed to start: {repo_path}")
+
+    # Take a screenshot of a random page
+    success = False
+    error: Exception
+    for _ in range(max_tries):
+        try:
+            infos: Dict[str, Any] = save_random_screenshot(destination_path, port=port, options=screenshot_options)
+            success = True
+            break
+        except Exception as e:
+            if "net::ERR_CONNECTION_REFUSED" in str(e):
+                error = e
+                server.stop()
+                time.sleep(0.5)
+                server.start()
+                time.sleep(0.5)
+            else:
+                # Do not retry
+                break
+    if not success:
+        raise ValueError(f"Failed to take a screenshot: {error}")
+
+    # Stop the server
+    server.stop()
+    time.sleep(0.1)
+
+    return infos
+
+
+class WebpageScenario(Image2StructureScenario):
+    BASE_PROMPT = (
+        "Please generate the source code to generate a webpage that looks like this image as much as feasibly possible.\n"  # noqa: E501
+        "You should output a json object associating each file name with its content.\n\n"
+        "Here is a simple example of the expected structure (that does not correspond to the image)."
+        " In this example, 3 files are created: index.html, style.css and script.js.\n"
+        "[\n"
+        "  {\n"
+        '    "filename": "index.html",\n'
+        '    "content": "<!DOCTYPE html>\\n<html>\\n<head>\\n<title>Title of the document</title>\\n</head>\\n<body>\\n\\n<p>Content of the document......</p>\\n\\n</body>\\n</html>"\n'  # noqa: E501
+        "  },\n"
+        "  {\n"
+        '    "filename": "style.css",\n'
+        '    "content": "body {\\n  background-color: lightblue;\\n}\\nh1 {\\n  color: white;\\n  text-align: center;\\n}"\n'  # noqa: E501
+        "  },\n"
+        "  {\n"
+        '    "filename": "script.js",\n'
+        '    "content": "document.getElementById(\\"demo\\").innerHTML = \\"Hello JavaScript!\\";"\n'
+        "  }\n"
+        "]\n"
+        "You do not have to create files with the same names. Create as many files as you need, you can even use directories if necessary,"  # noqa: E501
+        " they will be created for you automatically. Try to write some realistic code keeping in mind that is should"
+        " look like the image as much as feasibly possible."
+    )
+
+    HUGGINGFACE_DATASET_NAME = "stanford-crfm/i2s-webpage"
+    SUBSETS = ["css", "html", "javascript"]
+    MAX_TRIES: int = 5
+    ASSETS_EXTENSIONS: List[str] = ["png", "jpg", "jpeg", "gif", "svg", "webp", "ico", "bmp", "tiff"]
+
+    name = "image2webpage"
+    description = "Evaluate multimodal models on webpage generation to recreate a provided image"
+
+    def __init__(
+        self,
+        subset: str,
+        recompile_prompt: bool = True,
+        split: str = VALID_SPLIT,
+        screenshot_options: ScreenshotOptions = ScreenshotOptions(),
+    ):
+        super().__init__(subset, recompile_prompt, split)
+        self._screenshot_options = screenshot_options
+        self._html2text = HTML2Text()
+        self._html2text.ignore_links = True
+
+    def preprocess_row(self, row: Dict[str, Any], assets_path: str) -> Dict[str, Any]:
+        """Extract the base64 encoding of the repo from the row and return it."""
+        # No need to reprocess if the assets are already saved
+        assets_save_path: str = os.path.join(assets_path, str(row["uuid"].replace('"', "")))
+        if os.path.exists(assets_save_path):
+            try:
+                with open(os.path.join(assets_save_path, "assets_paths.pkl"), "rb") as f:
+                    row["assets_paths"] = pickle.load(f)
+                with open(os.path.join(assets_save_path, "assets_names.pkl"), "rb") as f:
+                    row["assets_names"] = pickle.load(f)
+                del row["assets"]
+                row["structure"] = PROCESSED
+                return row
+            except Exception:
+                # There was an issue when loading the assets, reprocess
+                shutil.rmtree(assets_save_path)
+        ensure_directory_exists(assets_save_path)
+
+        # Structure is a base64 encoding of the repo
+        if self._output_path is None:
+            raise ValueError("Output path not set")
+        repo_path = os.path.join(self._output_path, f"tmp{threading.get_ident()}_{self._subset}")
+        ensure_directory_exists(repo_path)
+
+        # Decode the base64 string which corresponds to an archive
+        # and extract the files to the repo_path
+        structure: str = row["structure"]
+        extract_repo(structure, repo_path)
+        row["structure"] = PROCESSED
+        row["repo_path"] = repo_path  # Stored for cleanup
+
+        # Process the assets
+        asset_paths: List[str] = list_assets(repo_path, self.ASSETS_EXTENSIONS)
+        del row["assets"]
+        row["assets_paths"] = []
+        row["assets_names"] = []
+        # Copy each asset to a unique persistent path
+        for i, asset_local_path in enumerate(asset_paths):
+            asset_name: str = asset_local_path
+            asset_dest_path = os.path.join(assets_save_path, f"{i}.{asset_local_path.split('.')[-1]}")
+            shutil.copyfile(os.path.join(row["repo_path"], asset_local_path), asset_dest_path)
+            row["assets_paths"].append(asset_dest_path)
+            row["assets_names"].append(asset_name)
+
+        # Save both assets_paths and assets_names as files than can be loaded
+        with open(os.path.join(assets_save_path, "assets_paths.pkl"), "wb") as f:
+            pickle.dump(row["assets_paths"], f)
+        with open(os.path.join(assets_save_path, "assets_names.pkl"), "wb") as f:
+            pickle.dump(row["assets_names"], f)
+
+        return row
+
+    def build_prompt(self, row: Dict[str, Any]) -> str:
+        prompt: str = self.BASE_PROMPT
+        assert "assets_paths" in row, "No assets paths in the row"
+        assert "assets_names" in row, "No assets names in the row"
+        assert len(row["assets_paths"]) == len(row["assets_names"])
+        if len(row["assets_names"]) > 0:
+            prompt += "\nYou have access to the following assets:\n"
+            for asset_local_path in row["assets_names"]:
+                prompt += f"- {asset_local_path}\n"
+        return prompt
+
+    def compile_and_save(self, structure: str, assets_path: str, destination_path: str) -> str:
+        # Structure is the path to the repo
+        # Serve and take screenshot
+        repo_path: str = structure
+        infos: Dict[str, Any] = serve_and_take_screenshot(repo_path, destination_path, self._screenshot_options)
+        text: str = convert_html_to_text(self._html2text, infos["html"])
+        return text
+
+    def finalize(self, row: Dict[str, Any]) -> None:
+        """Perform cleanup operations after the instance has been generated."""
+        if "repo_path" in row:
+            repo_path: str = row["repo_path"]
+            shutil.rmtree(repo_path)

helm/benchmark/scenarios/vision_language/mementos_scenario.py

@@ -0,0 +1,124 @@
+import os.path
+from typing import List
+
+from datasets import load_dataset
+from tqdm import tqdm
+
+from helm.benchmark.scenarios.scenario import (
+    CORRECT_TAG,
+    TEST_SPLIT,
+    TRAIN_SPLIT,
+    Input,
+    Instance,
+    Output,
+    Reference,
+    Scenario,
+)
+from helm.common.general import ensure_directory_exists, ensure_file_downloaded
+from helm.common.media_object import MediaObject, MultimediaObject
+
+
+class MementosScenario(Scenario):
+    """
+    Mementos: A Comprehensive Benchmark for Multimodal Large Language Model Reasoning over Image Sequences
+
+    We introduces Mementos, a new benchmark designed to assess MLLMs' sequential image reasoning abilities. Mementos
+    features 4,761 diverse image sequences with varying lengths.
+
+    @misc{wang2024mementos,
+    title={Mementos: A Comprehensive Benchmark for Multimodal Large Language Model Reasoning over Image Sequences},
+    author={Xiyao Wang and Yuhang Zhou and Xiaoyu Liu and Hongjin Lu and Yuancheng Xu and Feihong He and Jaehong Yoon
+    and Taixi Lu and Gedas Bertasius and Mohit Bansal and Huaxiu Yao and Furong Huang},
+    year={2024},
+    eprint={2401.10529},
+    archivePrefix={arXiv},
+    primaryClass={cs.CV}
+    }
+
+    Paper: https://arxiv.org/abs/2401.10529
+    """
+
+    MEMENTOS_HUGGINGFACE_DATASET_NAME: str = "shenmishajing/unofficial_mementos_dataset"
+
+    IMAGE_URL: str = (
+        "https://huggingface.co/datasets/shenmishajing/unofficial_mementos_dataset/resolve/main/"
+        + "{subject}/{split}/{file_name}?download=true"
+    )
+
+    DATA_FILES: str = "{subject}/{split}/metadata.csv"
+
+    QUESTION_PROMPT: str = (
+        "Write a description for the given image sequence in a single paragraph, what is happening in this episode?"
+    )
+
+    SUBJECTS: List[str] = ["comics", "dailylife", "robotics"]
+
+    name = "mementos"
+    description = (
+        "A Comprehensive Benchmark for Multimodal Large Language Model Reasoning over Image Sequences"
+        " ([paper](https://arxiv.org/abs/2401.10529))."
+    )
+    tags = ["vision-language"]
+
+    def __init__(self, subject: str):
+        super().__init__()
+        assert subject in self.SUBJECTS, f"Invalid subject: {subject}"
+        self._subject: str = subject
+
+    def get_instances(self, output_path: str) -> List[Instance]:
+        subject_output_path: str = os.path.join(output_path, self._subject)
+        ensure_directory_exists(subject_output_path)
+
+        data_files = {
+            split: self.DATA_FILES.format(subject=self._subject, split=split) for split in [TRAIN_SPLIT, TEST_SPLIT]
+        }
+        instances: List[Instance] = []
+
+        for split in [TRAIN_SPLIT, TEST_SPLIT]:
+            cur_output_path = os.path.join(subject_output_path, split)
+            ensure_directory_exists(cur_output_path)
+
+            # Process the test set
+            for row in tqdm(
+                load_dataset(
+                    self.MEMENTOS_HUGGINGFACE_DATASET_NAME.format(subject=self._subject),
+                    data_files=data_files,
+                    split=split,
+                    cache_dir=cur_output_path,
+                )
+            ):
+                # Download the image
+                file_name: str = row["file_name"]
+                local_image_path: str = os.path.join(cur_output_path, file_name)
+                ensure_file_downloaded(
+                    source_url=self.IMAGE_URL.format(subject=self._subject, split=split, file_name=file_name),
+                    target_path=local_image_path,
+                    unpack=False,
+                )
+
+                content: List[MediaObject] = [
+                    MediaObject(location=local_image_path, content_type="image/png"),
+                    MediaObject(text=self.QUESTION_PROMPT, content_type="text/plain"),
+                ]
+                answer: str = row["description"]
+                instances.append(
+                    Instance(
+                        Input(multimedia_content=MultimediaObject(content)),
+                        references=[Reference(Output(text=answer), tags=[CORRECT_TAG])],
+                        split=split,
+                    )
+                )
+
+            print()
+
+        return instances
+
+
+def main():
+    scenario = MementosScenario("robotics")
+    instances = scenario.get_instances("output")
+    print(instances)
+
+
+if __name__ == "__main__":
+    main()

helm/benchmark/scenarios/vision_language/mme_scenario.py

@@ -0,0 +1,145 @@
+import os.path
+from typing import List
+
+from datasets import load_dataset
+from tqdm import tqdm
+
+from helm.benchmark.scenarios.scenario import (
+    CORRECT_TAG,
+    TEST_SPLIT,
+    Instance,
+    Input,
+    Output,
+    Reference,
+    Scenario,
+)
+from helm.common.media_object import MediaObject, MultimediaObject
+from helm.common.general import ensure_directory_exists
+
+
+class MMEScenario(Scenario):
+    """
+        MME: A Comprehensive Evaluation Benchmark for Multimodal Large Language Models
+
+        Multimodal Large Language Model (MLLM) relies on the powerful LLM to perform
+        multimodal tasks, showing amazing emergent abilities in recent studies. However,
+        it is difficult for these case studies to fully reflect the performance of MLLM,
+        lacking a comprehensive evaluation. In MME, we fill in this blank, presenting
+        the first comprehensive MLLM Evaluation benchmark MME. It measures both perception
+        and cognition abilities on a total of 14 subtasks. In order to avoid data leakage
+        that may arise from direct use of public datasets for evaluation, the annotations
+        of instruction-answer pairs are all manually designed. The concise instruction design
+        allows us to fairly compare MLLMs, instead of struggling in prompt engineering.
+        Besides, with such an instruction, we can also easily carry out quantitative
+        statistics. We rephrase the answer type of MME to multiple-choice question-answering.
+        We use the multiple-choice metrics for 14 different evaluation tasks.
+
+        @article{fu2023mme,
+        title={MME: A Comprehensive Evaluation Benchmark for Multimodal Large Language Models},
+        author={Fu, Chaoyou and Chen, Peixian and Shen, Yunhang and Qin, Yulei and
+        Zhang, Mengdan and Lin, Xu and Yang, Jinrui and Zheng, Xiawu and Li, Ke and
+        Sun, Xing and Wu, Yunsheng and Ji, Rongrong},
+        journal={arXiv preprint arXiv:2306.13394},
+        year={2023}
+    }
+
+        Paper: https://arxiv.org/abs/2306.13394
+    """
+
+    MME_HUGGINGFACE_DATASET_NAME: str = "lmms-lab/MME"
+
+    SUBJECTS: List[str] = [
+        "existence",
+        "scene",
+        "posters",
+        "color",
+        "OCR",
+        "position",
+        "celebrity",
+        "artwork",
+        "commonsense_reasoning",
+        "numerical_calculation",
+        "landmark",
+        "count",
+        "text_translation",
+        "code_reasoning",
+    ]
+
+    name = "mme"
+    description = "Evaluate multimodal models on  ([paper](https://arxiv.org/abs/2306.13394))."
+    tags = ["vision-language"]
+    options: List[str] = ["Yes", "No"]
+
+    def __init__(self, subject: str):
+        super().__init__()
+        assert subject in self.SUBJECTS, f"Invalid subject: {subject}"
+        self._subject: str = subject
+
+    def get_label_from_answer(self, answer: str):
+        label: str
+        if answer == "Yes":
+            label = "A"
+        elif answer == "No":
+            label = "B"
+        else:
+            raise NotImplementedError(f"Invalid answer: {answer}")
+        return label
+
+    def remove_question_suffix_for_mcqa(self, question: str):
+        return question.replace("Please answer yes or no.", "").strip()
+
+    def get_question_id(self, question_id: str):
+        return question_id.split(".")[0].replace("/", "-")
+
+    def get_instances(self, output_path: str) -> List[Instance]:
+        images_path: str = os.path.join(output_path, "images")
+        ensure_directory_exists(images_path)
+
+        # There is only the test split in Unicorn benchmark
+        instances: List[Instance] = []
+        # Process the test set
+        # Two open-ended generation instances and
+        # one multi-choice generation instance per row
+        for row in tqdm(
+            load_dataset(
+                self.MME_HUGGINGFACE_DATASET_NAME,
+                split=TEST_SPLIT,
+                cache_dir=output_path,
+            )
+        ):
+            if row["category"] != self._subject:
+                continue
+            question_id: str = self.get_question_id(row["question_id"])
+            # Save the image locally
+            image_path: str = os.path.join(images_path, f"{question_id}.png")
+            if not os.path.exists(image_path):
+                row["image"].save(image_path)
+
+            question: str = self.remove_question_suffix_for_mcqa(row["question"])
+            answer: str = row["answer"]
+            references: List[Reference] = []
+
+            answer = self.get_label_from_answer(answer)
+            # The given correct answer is a letter, but we need an index
+            correct_answer_index: int = ord(answer) - ord("A")
+            # The options are originally appended to the question
+
+            for i, option in enumerate(self.options):
+                reference: Reference
+                is_correct: bool = i == correct_answer_index
+                reference = Reference(Output(text=option), tags=[CORRECT_TAG] if is_correct else [])
+                references.append(reference)
+
+            content = [
+                MediaObject(location=image_path, content_type="image/png"),
+                MediaObject(text=question, content_type="text/plain"),
+            ]
+            instances.append(
+                Instance(
+                    Input(multimedia_content=MultimediaObject(content)),
+                    references=references,
+                    split=TEST_SPLIT,
+                )
+            )
+
+        return instances

helm/benchmark/scenarios/vision_language/mmmu_scenario.py

@@ -0,0 +1,187 @@
+import os.path
+from typing import Dict, List
+
+from datasets import load_dataset
+from tqdm import tqdm
+
+from helm.benchmark.scenarios.scenario import (
+    CORRECT_TAG,
+    VALID_SPLIT,
+    Instance,
+    Input,
+    Output,
+    Reference,
+    Scenario,
+)
+from helm.common.media_object import MediaObject, MultimediaObject
+from helm.common.general import ensure_directory_exists
+
+
+class MMMUScenario(Scenario):
+    """
+    MMMU: A Massive Multi-discipline Multimodal Understanding and Reasoning Benchmark for Expert AGI
+
+    We introduce MMMU: a new benchmark designed to evaluate multimodal models on massive multi-discipline
+    tasks demanding college-level subject knowledge and deliberate reasoning. MMMU includes 11.5K meticulously
+    collected multimodal questions from college exams, quizzes, and textbooks, covering six core disciplines:
+    Art & Design, Business, Science, Health & Medicine, Humanities & Social Science, and Tech & Engineering.
+    These questions span 30 subjects and 183 subfields, comprising 30 highly heterogeneous image types, such
+    as charts, diagrams, maps, tables, music sheets, and chemical structures.
+
+      @article{yue2023mmmu,
+        title={MMMU: A Massive Multi-discipline Multimodal Understanding and Reasoning Benchmark for Expert AGI},
+        author={Xiang Yue and Yuansheng Ni and Kai Zhang and Tianyu Zheng and Ruoqi Liu and Ge Zhang and Samuel
+        Stevens and Dongfu Jiang and Weiming Ren and Yuxuan Sun and Cong Wei and Botao Yu and Ruibin Yuan and
+        Renliang Sun and Ming Yin and Boyuan Zheng and Zhenzhu Yang and Yibo Liu and Wenhao Huang and Huan Sun
+        and Yu Su and Wenhu Chen},
+        journal={arXiv preprint arXiv:2311.16502},
+        year={2023},
+      }
+
+    Paper: https://arxiv.org/abs/2311.16502
+    Website: https://mmmu-benchmark.github.io/
+    """
+
+    MMMU_HUGGINGFACE_DATASET_NAME: str = "MMMU/MMMU"
+    MAX_NUM_IMAGES: int = 7
+
+    SUBJECTS: List[str] = [
+        "Accounting",
+        "Agriculture",
+        "Architecture_and_Engineering",
+        "Art",
+        "Art_Theory",
+        "Basic_Medical_Science",
+        "Biology",
+        "Chemistry",
+        "Clinical_Medicine",
+        "Computer_Science",
+        "Design",
+        "Diagnostics_and_Laboratory_Medicine",
+        "Economics",
+        "Electronics",
+        "Energy_and_Power",
+        "Finance",
+        "Geography",
+        "History",
+        "Literature",
+        "Manage",
+        "Marketing",
+        "Materials",
+        "Math",
+        "Mechanical_Engineering",
+        "Music",
+        "Pharmacy",
+        "Physics",
+        "Psychology",
+        "Public_Health",
+        "Sociology",
+    ]
+
+    name = "mmmu"
+    description = (
+        "Evaluate multimodal models on massive multi-discipline tasks demanding college-level "
+        "subject knowledge and deliberate reasoning ([paper](https://arxiv.org/abs/2311.16502))."
+    )
+    tags = ["vision-language"]
+
+    def __init__(self, subject: str, question_type: str):
+        super().__init__()
+        assert subject in self.SUBJECTS, f"Invalid subject: {subject}"
+        self._subject: str = subject
+
+        assert question_type in ["multiple-choice", "open"], f"Invalid question type: {question_type}"
+        self._question_type: str = question_type
+
+    def get_instances(self, output_path: str) -> List[Instance]:
+        images_path: str = os.path.join(output_path, "images", self._subject)
+        ensure_directory_exists(images_path)
+
+        instances: List[Instance] = []
+
+        # Process the validation set
+        # There seems to be a dev set, but it's unavailable through load_dataset.
+        # When loading "dev", we get error: ValueError: Unknown split "dev". Should be one of ['test', 'validation'].
+        # The test set doesn't have answers, since the MMMU competition/leaderboard uses the test set
+        for row in tqdm(
+            load_dataset(self.MMMU_HUGGINGFACE_DATASET_NAME, self._subject, split="validation", cache_dir=output_path)
+        ):
+            # Skip questions that aren't in the subject we're interested in
+            if row["question_type"] != self._question_type:
+                continue
+
+            question_id: str = row["id"]
+            if self._subject not in question_id:
+                continue
+
+            question_template: str = row["question"]
+            options: List[str] = eval(row["options"])  # Convert the string to list of options
+            answer: str = row["answer"]
+
+            # Create the question. Questions can have text and images interleaved
+            question_template_to_image_path: Dict[str, str] = {}
+            content: List[MediaObject] = []
+            for img_number in range(1, self.MAX_NUM_IMAGES):
+                image_id: str = f"image_{img_number}"
+                if row[image_id] is None:
+                    # At this point, there are no more images for this question
+                    break
+
+                # Save the image locally
+                image_path: str = os.path.join(images_path, f"{question_id}_{image_id}.png")
+                if not os.path.exists(image_path):
+                    row[image_id].save(image_path)
+
+                image_template_tag: str = f"<image {img_number}>"
+                question_template_to_image_path[image_template_tag] = image_path
+
+                # There are cases when the image is included, but it is not used either in the
+                # question template or in the answer options
+                if image_template_tag not in question_template:
+                    # The image is not in the question template
+                    continue
+
+                head, question_template = question_template.split(image_template_tag, 1)
+                if head:
+                    content.append(MediaObject(text=head, content_type="text/plain"))
+                content.append(MediaObject(location=image_path, content_type="image/png"))
+
+            # Add the rest of the question template
+            if question_template:
+                content.append(MediaObject(text=question_template, content_type="text/plain"))
+
+            # Add the references
+            references: List[Reference] = []
+            if self._question_type == "multiple-choice":
+                # The given correct answer is a letter, but we need an index
+                correct_answer_index: int = ord(answer) - ord("A")
+
+                for i, option in enumerate(options):
+                    reference: Reference
+                    is_correct: bool = i == correct_answer_index
+
+                    if option in question_template_to_image_path:
+                        # Image answer choices
+                        image_path = question_template_to_image_path[option]
+                        image_choice = MediaObject(location=image_path, content_type="image/png")
+                        reference = Reference(
+                            Output(multimedia_content=MultimediaObject([image_choice])),
+                            tags=[CORRECT_TAG] if is_correct else [],
+                        )
+                    else:
+                        # Text answer choices
+                        reference = Reference(Output(text=option), tags=[CORRECT_TAG] if is_correct else [])
+
+                    references.append(reference)
+            else:
+                references.append(Reference(Output(text=answer), tags=[CORRECT_TAG]))
+
+            instances.append(
+                Instance(
+                    Input(multimedia_content=MultimediaObject(content)),
+                    references=references,
+                    split=VALID_SPLIT,
+                )
+            )
+
+        return instances