rpx_benchmark.exceptions

  1"""Exception hierarchy for the RPX benchmark toolkit.
  2
  3Every error raised by ``rpx_benchmark`` public APIs is a subclass of
  4:class:`RPXError`, so callers can write::
  5
  6    import rpx_benchmark as rpx
  7
  8    try:
  9        result, report, _ = rpx.run_monocular_depth(cfg)
 10    except rpx.exceptions.ConfigError as e:
 11        # bad config: show the user what to fix
 12        print(f"[config] {e}")
 13    except rpx.exceptions.DownloadError:
 14        print("offline — re-run with --cache-dir pointing at a local mirror")
 15    except rpx.RPXError as e:
 16        # any other benchmark-specific failure
 17        print(f"[rpx] {e}")
 18
 19The hierarchy is deliberately narrow: library code raises the most
 20specific subclass that applies, and each subclass carries a
 21human-readable message explaining *what* went wrong and *what the user
 22can do* to fix it.
 23
 24Hierarchy
 25---------
 26
 27.. code-block:: text
 28
 29    RPXError
 30    ├── ConfigError          invalid MonocularDepthRunConfig / CLI flag
 31    ├── DatasetError
 32    │   ├── ManifestError    malformed or missing manifest file
 33    │   └── DownloadError    HuggingFace or network failure
 34    ├── ModelError
 35    │   └── AdapterError     input/output adapter or factory error
 36    └── MetricError          evaluator or metric calculation error
 37"""
 38
 39from __future__ import annotations
 40
 41from typing import Any, Optional
 42
 43
 44class RPXError(Exception):
 45    """Base exception for every error raised by the RPX benchmark toolkit.
 46
 47    All library code raises a subclass of this so user code can write a
 48    single ``except RPXError`` to catch all benchmark failures without
 49    accidentally swallowing unrelated exceptions.
 50
 51    Parameters
 52    ----------
 53    message : str
 54        Human-readable description of what failed. Should include a
 55        hint about what the user can do next.
 56    hint : str, optional
 57        Additional remediation advice rendered after the main message.
 58    details : dict, optional
 59        Structured context (e.g. offending field, expected value) that
 60        higher-level code may inspect.
 61
 62    Examples
 63    --------
 64    >>> from rpx_benchmark.exceptions import RPXError
 65    >>> raise RPXError("something went wrong", hint="check the cache dir")
 66    ... # doctest: +SKIP
 67    """
 68
 69    def __init__(
 70        self,
 71        message: str,
 72        *,
 73        hint: Optional[str] = None,
 74        details: Optional[dict[str, Any]] = None,
 75    ) -> None:
 76        self.message = message
 77        self.hint = hint
 78        self.details = dict(details) if details else {}
 79        full = message
 80        if hint:
 81            full = f"{message}\n  hint: {hint}"
 82        super().__init__(full)
 83
 84
 85# --------------------------------------------------------------------------- #
 86# Config-level errors
 87# --------------------------------------------------------------------------- #
 88
 89
 90class ConfigError(RPXError):
 91    """Raised when a user-supplied config is invalid.
 92
 93    Examples
 94    --------
 95    * ``MonocularDepthRunConfig`` built without a ``model``.
 96    * Unknown difficulty split.
 97    * ``batch_size < 1``.
 98    """
 99
100
101class ConfigTypeError(ConfigError, TypeError):
102    """Invalid configuration value type, catchable as RPXError or TypeError."""
103
104
105# --------------------------------------------------------------------------- #
106# Dataset-level errors
107# --------------------------------------------------------------------------- #
108
109
110class DatasetError(RPXError):
111    """Base class for dataset load / manifest / download failures."""
112
113
114class ManifestError(DatasetError):
115    """Manifest JSON is missing, malformed, or references missing files.
116
117    Raised by :class:`rpx_benchmark.loader.RPXDataset` when the loader
118    cannot resolve a sample from the manifest it was handed.
119
120    Examples
121    --------
122    * Manifest missing the ``task`` field.
123    * Sample lists ``rgb`` that does not exist on disk.
124    * Task value is not in :class:`rpx_benchmark.api.TaskType`.
125    """
126
127
128class DownloadError(DatasetError):
129    """HuggingFace download or cache lookup failed.
130
131    Raised by :mod:`rpx_benchmark.hub` when ``snapshot_download`` or
132    ``hf_hub_download`` fails (network issue, bad repo id, missing
133    revision, permission denied).
134    """
135
136
137# --------------------------------------------------------------------------- #
138# Model-level errors
139# --------------------------------------------------------------------------- #
140
141
142class ModelError(RPXError):
143    """Raised by model factories or the runner when a model misbehaves.
144
145    Examples
146    --------
147    * Model returned a different number of predictions than samples.
148    * Model's ``task`` attribute does not match the dataset task.
149    * Prediction dataclass has a wrong shape.
150    """
151
152
153class AdapterError(ModelError):
154    """Input or output adapter produced an invalid payload.
155
156    Examples
157    --------
158    * ``InputAdapter.prepare`` raised during preprocessing.
159    * ``OutputAdapter.finalize`` returned a non-``DepthPrediction`` for
160      the monocular depth task.
161    * HF processor's ``post_process_depth_estimation`` signature does
162      not accept the kwargs the adapter wants to pass.
163    """
164
165
166class UnverifiedAdapterError(ModelError):
167    """An adapter points at weights whose official-source lineage is
168    not verified, and the caller has not acknowledged the risk.
169
170    Some adapters in the canonical roster have no official HF / GitHub
171    release published by the paper authors today — only candidate
172    community uploads with empty READMEs. The adapter exists in the
173    codebase (so every roster slot is reachable via the CLI) but
174    refuses to run unless the caller explicitly passes
175    ``acknowledge_unverified=True`` to the constructor (or
176    ``--acknowledge-unverified`` to the CLI). The intent is to give
177    the team a working adapter to spike against without risking
178    accidental publication of numbers whose underlying weights might
179    not match the paper.
180
181    To clear this error: confirm with the paper authors that the
182    candidate weights match their published model, then either pass
183    the acknowledgement flag or rewrite the adapter to point at the
184    verified-official release path.
185    """
186
187
188# --------------------------------------------------------------------------- #
189# Metric-level errors
190# --------------------------------------------------------------------------- #
191
192
193class MetricError(RPXError):
194    """Raised when a metric calculator cannot compute a score.
195
196    Examples
197    --------
198    * Prediction dataclass is the wrong type for the task.
199    * Ground-truth shape does not match prediction shape.
200    * Unknown metric name requested from a registry.
201    """
202
203
204__all__ = [
205    "RPXError",
206    "ConfigError",
207    "ConfigTypeError",
208    "DatasetError",
209    "ManifestError",
210    "DownloadError",
211    "ModelError",
212    "AdapterError",
213    "UnverifiedAdapterError",
214    "MetricError",
215]