hirundo 0.1.9__py3-none-any.whl → 0.1.18__py3-none-any.whl

hirundo/labeling.py

@@ -0,0 +1,140 @@
+import typing
+from abc import ABC
+
+from pydantic import BaseModel, Field
+
+from hirundo.dataset_enum import DatasetMetadataType
+
+if typing.TYPE_CHECKING:
+    from hirundo._urls import HirundoUrl
+
+
+class Metadata(BaseModel, ABC, frozen=True):
+    type: DatasetMetadataType
+
+
+class HirundoCSV(Metadata, frozen=True):
+    """
+    A dataset metadata file in the Hirundo CSV format
+    """
+
+    type: typing.Literal[DatasetMetadataType.HIRUNDO_CSV] = (
+        DatasetMetadataType.HIRUNDO_CSV
+    )
+    csv_url: "HirundoUrl"
+    """
+    The URL to access the dataset metadata CSV file.
+    e.g. `s3://my-bucket-name/my-folder/my-metadata.csv`, `gs://my-bucket-name/my-folder/my-metadata.csv`,
+    or `ssh://my-username@my-repo-name/my-folder/my-metadata.csv`
+    (or `file:///datasets/my-folder/my-metadata.csv` if using LOCAL storage type with on-premises installation)
+    """
+
+
+class COCO(Metadata, frozen=True):
+    """
+    A dataset metadata file in the COCO format
+    """
+
+    type: typing.Literal[DatasetMetadataType.COCO] = DatasetMetadataType.COCO
+    json_url: "HirundoUrl"
+    """
+    The URL to access the dataset metadata JSON file.
+    e.g. `s3://my-bucket-name/my-folder/my-metadata.json`, `gs://my-bucket-name/my-folder/my-metadata.json`,
+    or `ssh://my-username@my-repo-name/my-folder/my-metadata.json`
+    (or `file:///datasets/my-folder/my-metadata.json` if using LOCAL storage type with on-premises installation)
+    """
+
+
+class YOLO(Metadata, frozen=True):
+    type: typing.Literal[DatasetMetadataType.YOLO] = DatasetMetadataType.YOLO
+    data_yaml_url: "typing.Optional[HirundoUrl]" = None
+    labels_dir_url: "HirundoUrl"
+
+
+class KeylabsAuth(BaseModel):
+    username: str
+    password: str
+    instance: str
+
+
+class Keylabs(Metadata, frozen=True):
+    project_id: str
+    """
+    Keylabs project ID.
+    """
+
+    labels_dir_url: "HirundoUrl"
+    """
+    URL to the directory containing the Keylabs labels.
+    """
+
+    with_attributes: bool = True
+    """
+    Whether to include attributes in the class name.
+    """
+
+    project_name: typing.Optional[str] = None
+    """
+    Keylabs project name (optional; added to output CSV if provided).
+    """
+    keylabs_auth: typing.Optional[KeylabsAuth] = None
+    """
+    Keylabs authentication credentials (optional; if provided, used to provide links to each sample).
+    """
+
+
+class KeylabsObjDetImages(Keylabs, frozen=True):
+    type: typing.Literal[DatasetMetadataType.KeylabsObjDetImages] = (
+        DatasetMetadataType.KeylabsObjDetImages
+    )
+
+
+class KeylabsObjDetVideo(Keylabs, frozen=True):
+    type: typing.Literal[DatasetMetadataType.KeylabsObjDetVideo] = (
+        DatasetMetadataType.KeylabsObjDetVideo
+    )
+
+
+class KeylabsObjSegImages(Keylabs, frozen=True):
+    type: typing.Literal[DatasetMetadataType.KeylabsObjSegImages] = (
+        DatasetMetadataType.KeylabsObjSegImages
+    )
+
+
+class KeylabsObjSegVideo(Keylabs, frozen=True):
+    type: typing.Literal[DatasetMetadataType.KeylabsObjSegVideo] = (
+        DatasetMetadataType.KeylabsObjSegVideo
+    )
+
+
+KeylabsInfo = typing.Union[
+    KeylabsObjDetImages, KeylabsObjDetVideo, KeylabsObjSegImages, KeylabsObjSegVideo
+]
+"""
+The dataset labeling info for Keylabs. The dataset labeling info can be one of the following:
+- `DatasetMetadataType.KeylabsObjDetImages`: Indicates that the dataset metadata file is in the Keylabs object detection image format
+- `DatasetMetadataType.KeylabsObjDetVideo`: Indicates that the dataset metadata file is in the Keylabs object detection video format
+- `DatasetMetadataType.KeylabsObjSegImages`: Indicates that the dataset metadata file is in the Keylabs object segmentation image format
+- `DatasetMetadataType.KeylabsObjSegVideo`: Indicates that the dataset metadata file is in the Keylabs object segmentation video format
+"""
+LabelingInfo = typing.Annotated[
+    typing.Union[
+        HirundoCSV,
+        COCO,
+        YOLO,
+        KeylabsInfo,
+    ],
+    Field(discriminator="type"),
+]
+"""
+The dataset labeling info. The dataset labeling info can be one of the following:
+- `DatasetMetadataType.HirundoCSV`: Indicates that the dataset metadata file is a CSV file with the Hirundo format
+- `DatasetMetadataType.COCO`: Indicates that the dataset metadata file is a JSON file with the COCO format
+- `DatasetMetadataType.YOLO`: Indicates that the dataset metadata file is in the YOLO format
+- `DatasetMetadataType.KeylabsObjDetImages`: Indicates that the dataset metadata file is in the Keylabs object detection image format
+- `DatasetMetadataType.KeylabsObjDetVideo`: Indicates that the dataset metadata file is in the Keylabs object detection video format
+- `DatasetMetadataType.KeylabsObjSegImages`: Indicates that the dataset metadata file is in the Keylabs object segmentation image format
+- `DatasetMetadataType.KeylabsObjSegVideo`: Indicates that the dataset metadata file is in the Keylabs object segmentation video format
+
+Currently no other formats are supported. Future versions of `hirundo` may support additional formats.
+"""

hirundo/storage.py

@@ -1,5 +1,4 @@
 import typing
-from enum import Enum
 from pathlib import Path
 
 import pydantic
@@ -7,11 +6,12 @@ import requests
 from pydantic import BaseModel, model_validator
 from pydantic_core import Url
 
-from hirundo._constraints import S3BucketUrl, StorageConfigName
 from hirundo._env import API_HOST
-from hirundo._headers import get_auth_headers, json_headers
+from hirundo._headers import get_headers
 from hirundo._http import raise_for_status_with_reason
 from hirundo._timeouts import MODIFY_TIMEOUT, READ_TIMEOUT
+from hirundo._urls import S3BucketUrl, StorageConfigName
+from hirundo.dataset_enum import StorageTypes
 from hirundo.git import GitRepo, GitRepoOut
 from hirundo.logger import get_logger
 
@@ -34,11 +34,11 @@ class StorageS3Base(BaseModel):
         Chains the bucket URL with the path, ensuring that the path is formatted correctly
 
         Args:
-            - path: The path to the file in the S3 bucket, e.g. `my-file.txt` or `/my-folder/my-file.txt`
+            path: The path to the file in the S3 bucket, e.g. :file:`my-file.txt` or :file:`/my-folder/my-file.txt`
 
         Returns:
-            The full URL to the file in the S3 bucket, e.g. `s3://my-bucket/my-file.txt` or `s3://my-bucket/my-folder/my-file.txt`,
-            where `s3://my-bucket` is the bucket URL provided in the S3 storage config
+            The full URL to the file in the S3 bucket, e.g. :file:`s3://my-bucket/my-file.txt` or :file:`s3://my-bucket/my-folder/my-file.txt`,
+            where :file:`s3://my-bucket` is the bucket URL provided in the S3 storage config
         """
         return Url(
             f"{S3_PREFIX}{self.bucket_url.removeprefix(S3_PREFIX).removesuffix('/')}/{str(path).removeprefix('/')}"
@@ -64,11 +64,11 @@ class StorageGCPBase(BaseModel):
         Chains the bucket URL with the path, ensuring that the path is formatted correctly
 
         Args:
-            - path: The path to the file in the GCP bucket, e.g. `my-file.txt` or `/my-folder/my-file.txt`
+            path: The path to the file in the GCP bucket, e.g. :file:`my-file.txt` or :file:`/my-folder/my-file.txt`
 
         Returns:
-            The full URL to the file in the GCP bucket, e.g. `gs://my-bucket/my-file.txt` or `gs://my-bucket/my-folder/my-file.txt`,
-            where `my-bucket` is the bucket name provided in the GCP storage config
+            The full URL to the file in the GCP bucket, e.g. :file:`gs://my-bucket/my-file.txt` or :file:`gs://my-bucket/my-folder/my-file.txt`,
+            where :file:`my-bucket` is the bucket name provided in the GCP storage config
         """
         return Url(f"gs://{self.bucket_name}/{str(path).removeprefix('/')}")
 
@@ -94,7 +94,7 @@ class StorageGCPOut(StorageGCPBase):
 #         Chains the container URL with the path, ensuring that the path is formatted correctly
 
 #         Args:
-#             - path: The path to the file in the Azure container, e.g. `my-file.txt` or `/my-folder/my-file.txt`
+#             path: The path to the file in the Azure container, e.g. :file:`my-file.txt` or :file:`/my-folder/my-file.txt`
 
 #         Returns:
 #             The full URL to the file in the Azure container
@@ -114,11 +114,11 @@ def get_git_repo_url(
     Chains the repository URL with the path, ensuring that the path is formatted correctly
 
     Args:
-        - repo_url: The URL of the git repository, e.g. `https://my-git-repository.com`
-        - path: The path to the file in the git repository, e.g. `my-file.txt` or `/my-folder/my-file.txt`
+        repo_url: The URL of the git repository, e.g. :file:`https://my-git-repository.com`
+        path: The path to the file in the git repository, e.g. :file:`my-file.txt` or :file:`/my-folder/my-file.txt`
 
     Returns:
-        The full URL to the file in the git repository, e.g. `https://my-git-repository.com/my-file.txt` or `https://my-git-repository.com/my-folder/my-file.txt`
+        The full URL to the file in the git repository, e.g. :file:`https://my-git-repository.com/my-file.txt` or :file:`https://my-git-repository.com/my-folder/my-file.txt`
     """
     if not isinstance(repo_url, Url):
         repo_url = Url(repo_url)
@@ -131,12 +131,12 @@ class StorageGit(BaseModel):
     repo_id: typing.Optional[int] = None
     """
     The ID of the Git repository in the Hirundo system.
-    Either `repo_id` or `repo` must be provided.
+    Either :code:`repo_id` or :code:`repo` must be provided.
     """
     repo: typing.Optional[GitRepo] = None
     """
     The Git repository to link to.
-    Either `repo_id` or `repo` must be provided.
+    Either :code:`repo_id` or :code:`repo` must be provided.
     """
     branch: str
     """
@@ -156,11 +156,11 @@ class StorageGit(BaseModel):
         Chains the repository URL with the path, ensuring that the path is formatted correctly
 
         Args:
-            - path: The path to the file in the git repository, e.g. `my-file.txt` or `/my-folder/my-file.txt`
+            path: The path to the file in the git repository, e.g. :file:`my-file.txt` or :file:`/my-folder/my-file.txt`
 
         Returns:
-            The full URL to the file in the git repository, e.g. `https://my-git-repository.com/my-file.txt` or `https://my-git-repository.com/my-folder/my-file.txt`,
-            where `https://my-git-repository.com` is the repository URL provided in the git storage config's git repo
+            The full URL to the file in the git repository, e.g. :file:`https://my-git-repository.com/my-file.txt` or :file:`https://my-git-repository.com/my-folder/my-file.txt`,
+            where :file:`https://my-git-repository.com` is the repository URL provided in the git storage config's git repo
         """
         if not self.repo:
             raise ValueError("Repo must be provided to use `get_url`")
@@ -179,47 +179,31 @@ class StorageGitOut(BaseModel):
         Chains the repository URL with the path, ensuring that the path is formatted correctly
 
         Args:
-            - path: The path to the file in the git repository, e.g. `my-file.txt` or `/my-folder/my-file.txt`
+            path: The path to the file in the git repository, e.g. :file:`my-file.txt` or :file:`/my-folder/my-file.txt`
 
         Returns:
-            The full URL to the file in the git repository, e.g. `https://my-git-repository.com/my-file.txt` or `https://my-git-repository.com/my-folder/my-file.txt`,
-            where `https://my-git-repository.com` is the repository URL provided in the git storage config's git repo
+            The full URL to the file in the git repository, e.g. :file:`https://my-git-repository.com/my-file.txt` or :file:`https://my-git-repository.com/my-folder/my-file.txt`,
+            where :file:`https://my-git-repository.com` is the repository URL provided in the git storage config's git repo
         """
         repo_url = self.repo.repository_url
         return get_git_repo_url(repo_url, path)
 
 
-class StorageTypes(str, Enum):
-    """
-    Enum for the different types of storage configs.
-    Supported types are:
-    """
-
-    S3 = "S3"
-    GCP = "GCP"
-    # AZURE = "Azure"  TODO: Azure storage config is coming soon
-    GIT = "Git"
-    LOCAL = "Local"
-    """
-    Local storage config is only supported for on-premises installations.
-    """
-
-
 class StorageConfig(BaseModel):
     id: typing.Optional[int] = None
     """
-    The ID of the `StorageConfig` in the Hirundo system.
+    The ID of the :code:`StorageConfig` in the Hirundo system.
     """
 
     organization_id: typing.Optional[int] = None
     """
-    The ID of the organization that the `StorageConfig` belongs to.
+    The ID of the organization that the :code:`StorageConfig` belongs to.
     If not provided, it will be assigned to your default organization.
     """
 
     name: StorageConfigName
     """
-    A name to identify the `StorageConfig` in the Hirundo system.
+    A name to identify the :code:`StorageConfig` in the Hirundo system.
     """
     type: typing.Optional[StorageTypes] = pydantic.Field(
         examples=[
@@ -230,12 +214,12 @@ class StorageConfig(BaseModel):
         ]
     )
     """
-    The type of the `StorageConfig`.
+    The type of the :code:`StorageConfig`.
     Supported types are:
-    - `S3`
-    - `GCP`
-    - `Azure` (coming soon)
-    - `Git`
+    - :code:`S3`
+    - :code:`GCP`
+    - :code:`Azure` (coming soon)
+    - :code:`Git`
     """
     s3: typing.Optional[StorageS3] = pydantic.Field(
         default=None,
@@ -323,14 +307,14 @@ class StorageConfig(BaseModel):
     @staticmethod
     def get_by_id(storage_config_id: int) -> "ResponseStorageConfig":
         """
-        Retrieves a `StorageConfig` instance from the server by its ID
+        Retrieves a :code:`StorageConfig` instance from the server by its ID
 
         Args:
-            storage_config_id: The ID of the `StorageConfig` to retrieve
+            storage_config_id: The ID of the :code:`StorageConfig` to retrieve
         """
         storage_config = requests.get(
             f"{API_HOST}/storage-config/{storage_config_id}",
-            headers=get_auth_headers(),
+            headers=get_headers(),
             timeout=READ_TIMEOUT,
         )
         raise_for_status_with_reason(storage_config)
@@ -339,17 +323,17 @@ class StorageConfig(BaseModel):
     @staticmethod
     def get_by_name(name: str, storage_type: StorageTypes) -> "ResponseStorageConfig":
         """
-        Retrieves a `StorageConfig` instance from the server by its name
+        Retrieves a :code:`StorageConfig` instance from the server by its name
 
         Args:
-            name: The name of the `StorageConfig` to retrieve
-            storage_type: The type of the `StorageConfig` to retrieve
+            name: The name of the :code:`StorageConfig` to retrieve
+            storage_type: The type of the :code:`StorageConfig` to retrieve
 
             Note: The type is required because the name is not unique across different storage types
         """
         storage_config = requests.get(
             f"{API_HOST}/storage-config/by-name/{name}?storage_type={storage_type.value}",
-            headers=get_auth_headers(),
+            headers=get_headers(),
             timeout=READ_TIMEOUT,
         )
         raise_for_status_with_reason(storage_config)
@@ -360,17 +344,17 @@ class StorageConfig(BaseModel):
         organization_id: typing.Optional[int] = None,
     ) -> list["ResponseStorageConfig"]:
         """
-        Lists all the `StorageConfig`'s created by user's default organization
-        Note: The return type is `list[dict]` and not `list[StorageConfig]`
+        Lists all the :code:`StorageConfig`'s created by user's default organization
+        Note: The return type is :code:`list[dict]` and not :code:`list[StorageConfig]`
 
         Args:
-            organization_id: The ID of the organization to list `StorageConfig`'s for.
-            If not provided, it will list `StorageConfig`'s for the default organization.
+            organization_id: The ID of the organization to list :code:`StorageConfig`'s for.
+            If not provided, it will list :code:`StorageConfig`'s for the default organization.
         """
         storage_configs = requests.get(
             f"{API_HOST}/storage-config/",
             params={"storage_config_organization_id": organization_id},
-            headers=get_auth_headers(),
+            headers=get_headers(),
             timeout=READ_TIMEOUT,
         )
         raise_for_status_with_reason(storage_configs)
@@ -379,14 +363,14 @@ class StorageConfig(BaseModel):
     @staticmethod
     def delete_by_id(storage_config_id) -> None:
         """
-        Deletes a `StorageConfig` instance from the server by its ID
+        Deletes a :code:`StorageConfig` instance from the server by its ID
 
         Args:
-            storage_config_id: The ID of the `StorageConfig` to delete
+            storage_config_id: The ID of the :code:`StorageConfig` to delete
         """
         storage_config = requests.delete(
             f"{API_HOST}/storage-config/{storage_config_id}",
-            headers=get_auth_headers(),
+            headers=get_headers(),
             timeout=MODIFY_TIMEOUT,
         )
         raise_for_status_with_reason(storage_config)
@@ -394,7 +378,7 @@ class StorageConfig(BaseModel):
 
     def delete(self) -> None:
         """
-        Deletes the `StorageConfig` instance from the server
+        Deletes the :code:`StorageConfig` instance from the server
         """
         if not self.id:
             raise ValueError("No StorageConfig has been created")
@@ -402,10 +386,10 @@ class StorageConfig(BaseModel):
 
     def create(self, replace_if_exists: bool = False) -> int:
         """
-        Create a `StorageConfig` instance on the server
+        Create a :code:`StorageConfig` instance on the server
 
         Args:
-            replace_if_exists: If a `StorageConfig` with the same name and type already exists, replace it.
+            replace_if_exists: If a :code:`StorageConfig` with the same name and type already exists, replace it.
         """
         if self.git and self.git.repo:
             self.git.repo_id = self.git.repo.create(replace_if_exists=replace_if_exists)
@@ -415,10 +399,7 @@ class StorageConfig(BaseModel):
                 **self.model_dump(mode="json"),
                 "replace_if_exists": replace_if_exists,
             },
-            headers={
-                **json_headers,
-                **get_auth_headers(),
-            },
+            headers=get_headers(),
             timeout=MODIFY_TIMEOUT,
         )
         raise_for_status_with_reason(storage_config)

hirundo/unzip.py

@@ -0,0 +1,247 @@
+import typing
+import zipfile
+from collections.abc import Mapping
+from pathlib import Path
+from typing import IO, cast
+
+import requests
+from pydantic_core import Url
+
+from hirundo._dataframe import (
+    float32,
+    has_pandas,
+    has_polars,
+    int32,
+    pd,
+    pl,
+    string,
+)
+from hirundo._env import API_HOST
+from hirundo._headers import _get_auth_headers
+from hirundo._timeouts import DOWNLOAD_READ_TIMEOUT
+from hirundo.dataset_optimization_results import (
+    DataFrameType,
+    DatasetOptimizationResults,
+)
+from hirundo.logger import get_logger
+
+ZIP_FILE_CHUNK_SIZE = 50 * 1024 * 1024  # 50 MB
+
+Dtype = typing.Union[type[int32], type[float32], type[string]]
+
+
+CUSTOMER_INTERCHANGE_DTYPES: Mapping[str, Dtype] = {
+    "image_path": string,
+    "label_path": string,
+    "segments_mask_path": string,
+    "segment_id": int32,
+    "label": string,
+    "bbox_id": string,
+    "xmin": float32,
+    "ymin": float32,
+    "xmax": float32,
+    "ymax": float32,
+    "suspect_level": float32,  # If exists, must be one of the values in the enum below
+    "suggested_label": string,
+    "suggested_label_conf": float32,
+    "status": string,
+    # ⬆️ If exists, must be one of the following:
+    # NO_LABELS/MISSING_IMAGE/INVALID_IMAGE/INVALID_BBOX/INVALID_BBOX_SIZE/INVALID_SEG/INVALID_SEG_SIZE
+}
+
+logger = get_logger(__name__)
+
+
+def _clean_df_index(df: "pd.DataFrame") -> "pd.DataFrame":
+    """
+    Clean the index of a DataFrame in case it has unnamed columns.
+
+    Args:
+        df (DataFrame): DataFrame to clean
+
+    Returns:
+        Cleaned Pandas DataFrame
+    """
+    index_cols = sorted(
+        [col for col in df.columns if col.startswith("Unnamed")], reverse=True
+    )
+    if len(index_cols) > 0:
+        df.set_index(index_cols.pop(), inplace=True)
+        df.rename_axis(index=None, columns=None, inplace=True)
+        if len(index_cols) > 0:
+            df.drop(columns=index_cols, inplace=True)
+
+    return df
+
+
+def load_df(
+    file: "typing.Union[str, IO[bytes]]",
+) -> "DataFrameType":
+    """
+    Load a DataFrame from a CSV file.
+
+    Args:
+        file_name: The name of the CSV file to load.
+        dtypes: The data types of the columns in the DataFrame.
+
+    Returns:
+        The loaded DataFrame or `None` if neither Polars nor Pandas is available.
+    """
+    if has_polars:
+        return pl.read_csv(file, schema_overrides=CUSTOMER_INTERCHANGE_DTYPES)
+    elif has_pandas:
+        if typing.TYPE_CHECKING:
+            from pandas._typing import DtypeArg
+
+        dtype = cast("DtypeArg", CUSTOMER_INTERCHANGE_DTYPES)
+        #  ⬆️ Casting since CUSTOMER_INTERCHANGE_DTYPES is a Mapping[str, Dtype] in this case
+        df = pd.read_csv(file, dtype=dtype)
+        return cast("DataFrameType", _clean_df_index(df))
+        #  ⬆️ Casting since the return type is pd.DataFrame, but this is what DataFrameType is in this case
+    else:
+        return None
+
+
+def get_mislabel_suspect_filename(filenames: list[str]):
+    mislabel_suspect_filename = "mislabel_suspects.csv"
+    if mislabel_suspect_filename not in filenames:
+        mislabel_suspect_filename = "image_mislabel_suspects.csv"
+    if mislabel_suspect_filename not in filenames:
+        mislabel_suspect_filename = "suspects.csv"
+    if mislabel_suspect_filename not in filenames:
+        raise ValueError(
+            "None of mislabel_suspects.csv, image_mislabel_suspects.csv or suspects.csv were found in the zip file"
+        )
+    return mislabel_suspect_filename
+
+
+def download_and_extract_zip(
+    run_id: str, zip_url: str
+) -> DatasetOptimizationResults[DataFrameType]:
+    """
+    Download and extract the zip file from the given URL.
+
+    Note: It will only extract the `mislabel_suspects.csv` (vision - classification)
+    or `image_mislabel_suspects.csv` & `object_mislabel_suspects.csv` (vision - OD)
+    or `suspects.csv` (STT)
+    and `warnings_and_errors.csv` files from the zip file.
+
+    Args:
+        run_id: The ID of the optimization run.
+        zip_url: The URL of the zip file to download.
+
+    Returns:
+        The dataset optimization results object.
+    """
+    # Define the local file path
+    cache_dir = Path.home() / ".hirundo" / "cache"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    zip_file_path = cache_dir / f"{run_id}.zip"
+
+    headers = None
+    if Url(zip_url).scheme == "file":
+        zip_url = (
+            f"{API_HOST}/dataset-optimization/run/local-download"
+            + zip_url.replace("file://", "")
+        )
+        headers = _get_auth_headers()
+    # Stream the zip file download
+    with requests.get(
+        zip_url,
+        headers=headers,
+        timeout=DOWNLOAD_READ_TIMEOUT,
+        stream=True,
+    ) as r:
+        r.raise_for_status()
+        with open(zip_file_path, "wb") as f:
+            for chunk in r.iter_content(chunk_size=ZIP_FILE_CHUNK_SIZE):
+                f.write(chunk)
+        logger.info(
+            "Successfully downloaded the result zip file for run ID %s to %s",
+            run_id,
+            zip_file_path,
+        )
+
+        with zipfile.ZipFile(zip_file_path, "r") as z:
+            # Extract suspects file
+            suspects_df = None
+            object_suspects_df = None
+            warnings_and_errors_df = None
+
+            filenames = []
+            try:
+                filenames = [file.filename for file in z.filelist]
+            except Exception as e:
+                logger.error("Failed to get filenames from ZIP", exc_info=e)
+
+            try:
+                mislabel_suspect_filename = get_mislabel_suspect_filename(filenames)
+                with z.open(mislabel_suspect_filename) as suspects_file:
+                    suspects_df = load_df(suspects_file)
+                logger.debug(
+                    "Successfully loaded mislabel suspects into DataFrame for run ID %s",
+                    run_id,
+                )
+            except Exception as e:
+                logger.error(
+                    "Failed to load mislabel suspects into DataFrame", exc_info=e
+                )
+
+            object_mislabel_suspects_filename = "object_mislabel_suspects.csv"
+            if object_mislabel_suspects_filename in filenames:
+                try:
+                    with z.open(
+                        object_mislabel_suspects_filename
+                    ) as object_suspects_file:
+                        object_suspects_df = load_df(object_suspects_file)
+                    logger.debug(
+                        "Successfully loaded object mislabel suspects into DataFrame for run ID %s",
+                        run_id,
+                    )
+                except Exception as e:
+                    logger.error(
+                        "Failed to load object mislabel suspects into DataFrame",
+                        exc_info=e,
+                    )
+
+            try:
+                # Extract warnings_and_errors file
+                with z.open("warnings_and_errors.csv") as warnings_file:
+                    warnings_and_errors_df = load_df(warnings_file)
+                logger.debug(
+                    "Successfully loaded warnings and errors into DataFrame for run ID %s",
+                    run_id,
+                )
+            except Exception as e:
+                logger.error(
+                    "Failed to load warnings and errors into DataFrame", exc_info=e
+                )
+
+            return DatasetOptimizationResults[DataFrameType](
+                cached_zip_path=zip_file_path,
+                suspects=suspects_df,
+                object_suspects=object_suspects_df,
+                warnings_and_errors=warnings_and_errors_df,
+            )
+
+
+def load_from_zip(
+    zip_path: Path, file_name: str
+) -> "typing.Union[pd.DataFrame, pl.DataFrame, None]":
+    """
+    Load a given file from a given zip file.
+
+    Args:
+        zip_path: The path to the zip file.
+        file_name: The name of the file to load.
+
+    Returns:
+        The loaded DataFrame or `None` if neither Polars nor Pandas is available.
+    """
+    with zipfile.ZipFile(zip_path, "r") as z:
+        try:
+            with z.open(file_name) as file:
+                return load_df(file)
+        except Exception as e:
+            logger.error("Failed to load %s from zip file", file_name, exc_info=e)
+    return None