hydraflow 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

hydraflow/runs.py

@@ -1,7 +1,7 @@
 """
-This module provides functionality for managing and interacting with MLflow runs.
-It includes the `RunCollection` class and various methods to filter runs,
-retrieve run information, log artifacts, and load configurations.
+This module provides functionality for managing and interacting with MLflow
+runs. It includes the `RunCollection` class and various methods to filter
+runs, retrieve run information, log artifacts, and load configurations.
 """
 
 from __future__ import annotations
@@ -37,34 +37,49 @@ def search_runs(
     """
     Search for Runs that fit the specified criteria.
 
-    This function wraps the `mlflow.search_runs` function and returns the results
-    as a `RunCollection` object. It allows for flexible searching of MLflow runs based on
-    various criteria.
+    This function wraps the `mlflow.search_runs` function and returns the
+    results as a `RunCollection` object. It allows for flexible searching of
+    MLflow runs based on various criteria.
 
     Note:
         The returned runs are sorted by their start time in ascending order.
 
     Args:
-        experiment_ids: List of experiment IDs. Search can work with experiment IDs or
-            experiment names, but not both in the same call. Values other than
-            ``None`` or ``[]`` will result in error if ``experiment_names`` is
-            also not ``None`` or ``[]``. ``None`` will default to the active
-            experiment if ``experiment_names`` is ``None`` or ``[]``.
-        filter_string: Filter query string, defaults to searching all runs.
-        run_view_type: one of enum values ``ACTIVE_ONLY``, ``DELETED_ONLY``, or ``ALL`` runs
-            defined in :py:class:`mlflow.entities.ViewType`.
-        max_results: The maximum number of runs to put in the dataframe. Default is 100,000
-            to avoid causing out-of-memory issues on the user's machine.
-        order_by: List of columns to order by (e.g., "metrics.rmse"). The ``order_by`` column
-            can contain an optional ``DESC`` or ``ASC`` value. The default is ``ASC``.
-            The default ordering is to sort by ``start_time DESC``, then ``run_id``.
-        search_all_experiments: Boolean specifying whether all experiments should be searched.
-            Only honored if ``experiment_ids`` is ``[]`` or ``None``.
-        experiment_names: List of experiment names. Search can work with experiment IDs or
-            experiment names, but not both in the same call. Values other
-            than ``None`` or ``[]`` will result in error if ``experiment_ids``
-            is also not ``None`` or ``[]``. ``None`` will default to the active
-            experiment if ``experiment_ids`` is ``None`` or ``[]``.
+        experiment_ids (list[str] | None): List of experiment IDs. Search can
+            work with experiment IDs or experiment names, but not both in the
+            same call. Values other than ``None`` or ``[]`` will result in
+            error if ``experiment_names`` is also not ``None`` or ``[]``.
+            ``None`` will default to the active experiment if ``experiment_names``
+            is ``None`` or ``[]``.
+        experiment_ids (list[str] | None): List of experiment IDs. Search can
+            work with experiment IDs or experiment names, but not both in the
+            same call. Values other than ``None`` or ``[]`` will result in
+            error if ``experiment_names`` is also not ``None`` or ``[]``.
+            ``experiment_names`` is also not ``None`` or ``[]``. ``None`` will
+            default to the active experiment if ``experiment_names`` is ``None``
+            or ``[]``.
+        filter_string (str): Filter query string, defaults to searching all
+            runs.
+        run_view_type (int): one of enum values ``ACTIVE_ONLY``, ``DELETED_ONLY``,
+            or ``ALL`` runs defined in :py:class:`mlflow.entities.ViewType`.
+        max_results (int): The maximum number of runs to put in the dataframe.
+            Default is 100,000 to avoid causing out-of-memory issues on the user's
+            machine.
+        order_by (list[str] | None): List of columns to order by (e.g.,
+            "metrics.rmse"). The ``order_by`` column can contain an optional
+            ``DESC`` or ``ASC`` value. The default is ``ASC``. The default
+            ordering is to sort by ``start_time DESC``, then ``run_id``.
+            ``start_time DESC``, then ``run_id``.
+        search_all_experiments (bool): Boolean specifying whether all
+            experiments should be searched. Only honored if ``experiment_ids``
+            is ``[]`` or ``None``.
+        experiment_names (list[str] | None): List of experiment names. Search
+            can work with experiment IDs or experiment names, but not both in
+            the same call. Values other than ``None`` or ``[]`` will result in
+            error if ``experiment_ids`` is also not ``None`` or ``[]``.
+            ``experiment_ids`` is also not ``None`` or ``[]``. ``None`` will
+            default to the active experiment if ``experiment_ids`` is ``None``
+            or ``[]``.
 
     Returns:
         A `RunCollection` object containing the search results.
@@ -97,10 +112,10 @@ def list_runs(experiment_names: list[str] | None = None) -> RunCollection:
         The returned runs are sorted by their start time in ascending order.
 
     Args:
-        experiment_names: List of experiment names to search for runs.
-        If None or an empty list is provided, the function will search
-        the currently active experiment or all experiments except the
-        "Default" experiment.
+        experiment_names (list[str] | None): List of experiment names to search
+            for runs. If None or an empty list is provided, the function will
+            search the currently active experiment or all experiments except
+            the "Default" experiment.
 
     Returns:
         A `RunCollection` object containing the runs for the specified experiments.
@@ -133,27 +148,93 @@ class RunCollection:
     def __len__(self) -> int:
         return len(self._runs)
 
+    def __iter__(self) -> Iterator[Run]:
+        return iter(self._runs)
+
+    def __getitem__(self, index: int) -> Run:
+        return self._runs[index]
+
+    def __contains__(self, run: Run) -> bool:
+        return run in self._runs
+
+    def sort(
+        self,
+        key: Callable[[Run], Any] | None = None,
+        reverse: bool = False,
+    ) -> None:
+        self._runs.sort(key=key or (lambda x: x.info.start_time), reverse=reverse)
+
+    def first(self) -> Run:
+        """
+        Get the first run in the collection.
+
+        Returns:
+            The first run object in the collection.
+
+        Raises:
+            ValueError: If the collection is empty.
+        """
+        if not self._runs:
+            raise ValueError("The collection is empty.")
+
+        return self._runs[0]
+
+    def try_first(self) -> Run | None:
+        """
+        Try to get the first run in the collection.
+
+        Returns:
+            The first run object in the collection, or None if the collection
+            is empty.
+        """
+        return self._runs[0] if self._runs else None
+
+    def last(self) -> Run:
+        """
+        Get the last run in the collection.
+
+        Returns:
+            The last run object in the collection.
+
+        Raises:
+            ValueError: If the collection is empty.
+        """
+        if not self._runs:
+            raise ValueError("The collection is empty.")
+
+        return self._runs[-1]
+
+    def try_last(self) -> Run | None:
+        """
+        Try to get the last run in the collection.
+
+        Returns:
+            The last run object in the collection, or None if the collection is
+            empty.
+        """
+        return self._runs[-1] if self._runs else None
+
     def filter(self, config: object | None = None, **kwargs) -> RunCollection:
         """
         Filter the runs based on the provided configuration.
 
         This method filters the runs in the collection according to the
-        specified configuration object and additional key-value pairs.
-        The configuration object and key-value pairs should contain
-        key-value pairs that correspond to the parameters of the runs.
-        Only the runs that match all the specified parameters will be
-        included in the returned `RunCollection` object.
+        specified configuration object and additional key-value pairs. The
+        configuration object and key-value pairs should contain key-value pairs
+        that correspond to the parameters of the runs. Only the runs that match
+        all the specified parameters will be included in the returned
+        `RunCollection` object.
 
         The filtering supports:
         - Exact matches for single values.
         - Membership checks for lists of values.
-        - Range checks for tuples of two values (inclusive of the lower bound and
-          exclusive of the upper bound).
+        - Range checks for tuples of two values (inclusive of the lower bound
+          and exclusive of the upper bound).
 
         Args:
-            config: The configuration object to filter the runs. This can be any
-                object that provides key-value pairs through the `iter_params`
-                function.
+            config (object | None): The configuration object to filter the runs.
+                This can be any object that provides key-value pairs through
+                the `iter_params` function.
             **kwargs: Additional key-value pairs to filter the runs.
 
         Returns:
@@ -161,80 +242,161 @@ class RunCollection:
         """
         return RunCollection(filter_runs(self._runs, config, **kwargs))
 
-    def find(self, config: object | None = None, **kwargs) -> Run | None:
+    def find(self, config: object | None = None, **kwargs) -> Run:
         """
         Find the first run based on the provided configuration.
 
         This method filters the runs in the collection according to the
         specified configuration object and returns the first run that matches
-        the provided parameters. If no run matches the criteria, None is returned.
+        the provided parameters. If no run matches the criteria, a `ValueError`
+        is raised.
 
         Args:
-            config: The configuration object to identify the run.
+            config (object | None): The configuration object to identify the run.
             **kwargs: Additional key-value pairs to filter the runs.
 
         Returns:
-            The first run object that matches the provided configuration, or None
-            if no runs match the criteria.
+            The first run object that matches the provided configuration.
+
+        Raises:
+            ValueError: If no run matches the criteria.
 
         See Also:
-            RunCollection.filter: The method that performs the actual filtering logic.
+            RunCollection.filter: The method that performs the actual filtering
+            logic.
         """
         return find_run(self._runs, config, **kwargs)
 
-    def find_last(self, config: object | None = None, **kwargs) -> Run | None:
+    def try_find(self, config: object | None = None, **kwargs) -> Run | None:
+        """
+        Find the first run based on the provided configuration.
+
+        This method filters the runs in the collection according to the
+        specified configuration object and returns the first run that matches
+        the provided parameters. If no run matches the criteria, None is
+        returned.
+
+        Args:
+            config (object | None): The configuration object to identify the run.
+            **kwargs: Additional key-value pairs to filter the runs.
+
+        Returns:
+            The first run object that matches the provided configuration, or
+            None if no runs match the criteria.
+
+        See Also:
+            RunCollection.filter: The method that performs the actual filtering
+            logic.
+        """
+        return try_find_run(self._runs, config, **kwargs)
+
+    def find_last(self, config: object | None = None, **kwargs) -> Run:
         """
         Find the last run based on the provided configuration.
 
         This method filters the runs in the collection according to the
         specified configuration object and returns the last run that matches
-        the provided parameters. If no run matches the criteria, None is returned.
+        the provided parameters. If no run matches the criteria, a `ValueError`
+        is raised.
 
         Args:
-            config: The configuration object to identify the run.
+            config (object | None): The configuration object to identify the run.
             **kwargs: Additional key-value pairs to filter the runs.
 
         Returns:
-            The last run object that matches the provided configuration, or None
-            if no runs match the criteria.
+            The last run object that matches the provided configuration.
+
+        Raises:
+            ValueError: If no run matches the criteria.
 
         See Also:
-            RunCollection.filter: The method that performs the actual filtering logic.
+            RunCollection.filter: The method that performs the actual filtering
+            logic.
         """
         return find_last_run(self._runs, config, **kwargs)
 
-    def get(self, config: object | None = None, **kwargs) -> Run | None:
+    def try_find_last(self, config: object | None = None, **kwargs) -> Run | None:
+        """
+        Find the last run based on the provided configuration.
+
+        This method filters the runs in the collection according to the
+        specified configuration object and returns the last run that matches
+        the provided parameters. If no run matches the criteria, None is
+        returned.
+
+        Args:
+            config (object | None): The configuration object to identify the run.
+            **kwargs: Additional key-value pairs to filter the runs.
+
+        Returns:
+            The last run object that matches the provided configuration, or
+            None if no runs match the criteria.
+
+        See Also:
+            RunCollection.filter: The method that performs the actual filtering
+            logic.
+        """
+        return try_find_last_run(self._runs, config, **kwargs)
+
+    def get(self, config: object | None = None, **kwargs) -> Run:
         """
         Retrieve a specific run based on the provided configuration.
 
         This method filters the runs in the collection according to the
-        specified configuration object and returns the run that matches
-        the provided parameters. If more than one run matches the criteria,
-        a `ValueError` is raised.
+        specified configuration object and returns the run that matches the
+        provided parameters. If no run matches the criteria, or if more than
+        one run matches the criteria, a `ValueError` is raised.
 
         Args:
-            config: The configuration object to identify the run.
+            config (object | None): The configuration object to identify the run.
             **kwargs: Additional key-value pairs to filter the runs.
 
         Returns:
-            The run object that matches the provided configuration, or None
-            if no runs match the criteria.
+            The run object that matches the provided configuration.
 
         Raises:
-            ValueError: If more than one run matches the criteria.
+            ValueError: If no run matches the criteria or if more than one run
+            matches the criteria.
 
         See Also:
-            RunCollection.filter: The method that performs the actual filtering logic.
+            RunCollection.filter: The method that performs the actual filtering
+            logic.
         """
         return get_run(self._runs, config, **kwargs)
 
+    def try_get(self, config: object | None = None, **kwargs) -> Run | None:
+        """
+        Retrieve a specific run based on the provided configuration.
+
+        This method filters the runs in the collection according to the
+        specified configuration object and returns the run that matches the
+        provided parameters. If no run matches the criteria, None is returned.
+        If more than one run matches the criteria, a `ValueError` is raised.
+
+        Args:
+            config (object | None): The configuration object to identify the run.
+            **kwargs: Additional key-value pairs to filter the runs.
+
+        Returns:
+            The run object that matches the provided configuration, or None if
+            no runs match the criteria.
+
+        Raises:
+            ValueError: If more than one run matches the criteria.
+
+        See Also:
+            RunCollection.filter: The method that performs the actual filtering
+            logic.
+        """
+        return try_get_run(self._runs, config, **kwargs)
+
     def get_param_names(self) -> list[str]:
         """
         Get the parameter names from the runs.
 
-        This method extracts the unique parameter names from the provided list of runs.
-        It iterates through each run and collects the parameter names into a set to
-        ensure uniqueness.
+        This method extracts the unique parameter names from the provided list
+        of runs. It iterates through each run and collects the parameter names
+        into a set to ensure uniqueness.
 
         Returns:
             A list of unique parameter names.
@@ -246,101 +408,95 @@ class RunCollection:
         Get the parameter dictionary from the list of runs.
 
         This method extracts the parameter names and their corresponding values
-        from the provided list of runs. It iterates through each run and collects
-        the parameter values into a dictionary where the keys are parameter names
-        and the values are lists of parameter values.
+        from the provided list of runs. It iterates through each run and
+        collects the parameter values into a dictionary where the keys are
+        parameter names and the values are lists of parameter values.
 
         Returns:
-            A dictionary where the keys are parameter names and the values are lists
-            of parameter values.
+            A dictionary where the keys are parameter names and the values are
+            lists of parameter values.
         """
         return get_param_dict(self._runs)
 
-    def first(self) -> Run | None:
-        """
-        Return the first run in the collection.
-
-        Returns:
-            The first Run object if the collection is not empty, otherwise None.
-        """
-        return self._runs[0] if self._runs else None
-
-    def last(self) -> Run | None:
-        """
-        Return the last run in the collection.
-
-        Returns:
-            The last Run object if the collection is not empty, otherwise None.
-        """
-        return self._runs[-1] if self._runs else None
-
     def map(self, func: Callable[[Run], T]) -> Iterator[T]:
         """
-        Apply a function to each run in the collection and return an iterator of results.
+        Apply a function to each run in the collection and return an iterator of
+        results.
 
         Args:
-            func: A function that takes a Run object and returns a result.
+            func (Callable[[Run], T]): A function that takes a run and returns a
+                result.
 
-        Returns:
-            An iterator of results obtained by applying the function to each run
-            in the collection.
+        Yields:
+            Results obtained by applying the function to each run in the
+            collection.
         """
         return (func(run) for run in self._runs)
 
     def map_run_id(self, func: Callable[[str], T]) -> Iterator[T]:
         """
-        Apply a function to each run id in the collection and return an iterator of results.
+        Apply a function to each run id in the collection and return an iterator
+        of results.
 
         Args:
-            func: A function that takes a run id and returns a result.
+            func (Callable[[str], T]): A function that takes a run id and returns a
+                result.
 
-        Returns:
-            An iterator of results obtained by applying the function to each run id
-            in the collection.
+        Yields:
+            Results obtained by applying the function to each run id in the
+            collection.
         """
         return (func(run.info.run_id) for run in self._runs)
 
     def map_config(self, func: Callable[[DictConfig], T]) -> Iterator[T]:
         """
-        Apply a function to each run config in the collection and return an iterator of results.
+        Apply a function to each run configuration in the collection and return
+        an iterator of results.
 
         Args:
-            func: A function that takes a run config and returns a result.
+            func (Callable[[DictConfig], T]): A function that takes a run
+                configuration and returns a result.
 
-        Returns:
-            An iterator of results obtained by applying the function to each run config
+        Yields:
+            Results obtained by applying the function to each run configuration
             in the collection.
         """
         return (func(load_config(run)) for run in self._runs)
 
     def map_uri(self, func: Callable[[str | None], T]) -> Iterator[T]:
         """
-        Apply a function to each artifact URI in the collection and return an iterator of results.
+        Apply a function to each artifact URI in the collection and return an
+        iterator of results.
 
-        This method iterates over each run in the collection, retrieves the artifact URI,
-        and applies the provided function to it. If a run does not have an artifact URI,
-        None is passed to the function.
+        This method iterates over each run in the collection, retrieves the
+        artifact URI, and applies the provided function to it. If a run does not
+        have an artifact URI, None is passed to the function.
 
         Args:
-            func: A function that takes an artifact URI (string or None) and returns a result.
+            func (Callable[[str | None], T]): A function that takes an
+            artifact URI (string or None) and returns a result.
 
         Yields:
-            The results obtained by applying the function to each artifact URI in the collection.
+            Results obtained by applying the function to each artifact URI in the
+            collection.
         """
         return (func(run.info.artifact_uri) for run in self._runs)
 
     def map_dir(self, func: Callable[[str], T]) -> Iterator[T]:
         """
-        Apply a function to each artifact directory in the collection and return an iterator of results.
+        Apply a function to each artifact directory in the collection and return
+        an iterator of results.
 
-        This method iterates over each run in the collection, downloads the artifact directory,
-        and applies the provided function to the directory path.
+        This method iterates over each run in the collection, downloads the
+        artifact directory, and applies the provided function to the directory
+        path.
 
         Args:
-            func: A function that takes an artifact directory path (string) and returns a result.
+            func (Callable[[str], T]): A function that takes an artifact directory
+                path (string) and returns a result.
 
-        Returns:
-            An iterator of results obtained by applying the function to each artifact directory
+        Yields:
+            Results obtained by applying the function to each artifact directory
             in the collection.
         """
         return (func(download_artifacts(run_id=run.info.run_id)) for run in self._runs)
@@ -350,25 +506,21 @@ def _param_matches(run: Run, key: str, value: Any) -> bool:
     """
     Check if the run's parameter matches the specified key-value pair.
 
-    This function checks if the run's parameters contain the specified key-value pair.
-    It handles different types of values, including lists and tuples.
+    This function checks if the run's parameters contain the specified
+    key-value pair. It handles different types of values, including lists
+    and tuples.
 
     Args:
-        run: The run object to check.
-        key: The parameter key to check.
-        value: The parameter value to check.
+        run (Run): The run object to check.
+        key (str): The parameter key to check.
+        value (Any): The parameter value to check.
 
     Returns:
-        True if the run's parameter matches the specified key-value pair, False otherwise.
+        True if the run's parameter matches the specified key-value pair,
+        False otherwise.
     """
     param = run.data.params.get(key, value)
 
-    # FIXME: This is a workaround to handle the case where the parameter value is a list
-    #        We need to improve the logic to handle different types of values
-    #        For now, we assume that if the parameter is a list, we should check if it contains the value
-    #        This is not ideal, but it works for the case where the parameter value is a list of strings
-    #        We should improve the logic to handle different types of values in the future
-
     if param is None:
         return False
 
@@ -392,8 +544,8 @@ def filter_runs(runs: list[Run], config: object | None = None, **kwargs) -> list
     specified configuration object and additional key-value pairs.
     The configuration object and key-value pairs should contain
     key-value pairs that correspond to the parameters of the runs.
-    Only the runs that match all the specified parameters will be
-    included in the returned list of runs.
+    Only the runs that match all the specified parameters will
+    be included in the returned list of runs.
 
     The filtering supports:
     - Exact matches for single values.
@@ -402,9 +554,10 @@ def filter_runs(runs: list[Run], config: object | None = None, **kwargs) -> list
       exclusive of the upper bound).
 
     Args:
-        runs: The list of runs to filter.
-        config: The configuration object to filter the runs. This can be any object that
-                provides key-value pairs through the `iter_params` function.
+        runs (list[Run]): The list of runs to filter.
+        config (object | None): The configuration object to filter the runs.
+            This can be any object that provides key-value pairs through the
+            `iter_params` function.
         **kwargs: Additional key-value pairs to filter the runs.
 
     Returns:
@@ -419,7 +572,38 @@ def filter_runs(runs: list[Run], config: object | None = None, **kwargs) -> list
     return runs
 
 
-def find_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | None:
+def find_run(runs: list[Run], config: object | None = None, **kwargs) -> Run:
+    """
+    Find the first run based on the provided configuration.
+
+    This method filters the runs in the collection according to the
+    specified configuration object and returns the first run that matches
+    the provided parameters. If no run matches the criteria, a `ValueError` is
+    raised.
+
+    Args:
+        runs (list[Run]): The runs to filter.
+        config (object | None): The configuration object to identify the run.
+        **kwargs: Additional key-value pairs to filter the runs.
+
+    Returns:
+        The first run object that matches the provided configuration.
+
+    Raises:
+        ValueError: If no run matches the criteria.
+
+    See Also:
+        RunCollection.filter: The method that performs the actual filtering logic.
+    """
+    filtered_runs = filter_runs(runs, config, **kwargs)
+
+    if len(filtered_runs) == 0:
+        raise ValueError("No run matches the provided configuration.")
+
+    return filtered_runs[0]
+
+
+def try_find_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | None:
     """
     Find the first run based on the provided configuration.
 
@@ -428,19 +612,55 @@ def find_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | N
     the provided parameters. If no run matches the criteria, None is returned.
 
     Args:
-        runs: The runs to filter.
-        config: The configuration object to identify the run.
+        runs (list[Run]): The runs to filter.
+        config (object | None): The configuration object to identify the run.
         **kwargs: Additional key-value pairs to filter the runs.
 
     Returns:
         The first run object that matches the provided configuration, or None
         if no runs match the criteria.
     """
-    runs = filter_runs(runs, config, **kwargs)
-    return runs[0] if runs else None
+    filtered_runs = filter_runs(runs, config, **kwargs)
+
+    if len(filtered_runs) == 0:
+        return None
+
+    return filtered_runs[0]
+
+
+def find_last_run(runs: list[Run], config: object | None = None, **kwargs) -> Run:
+    """
+    Find the last run based on the provided configuration.
+
+    This method filters the runs in the collection according to the
+    specified configuration object and returns the last run that matches
+    the provided parameters. If no run matches the criteria, a `ValueError`
+    is raised.
+
+    Args:
+        runs (list[Run]): The runs to filter.
+        config (object | None): The configuration object to identify the run.
+        **kwargs: Additional key-value pairs to filter the runs.
+
+    Returns:
+        The last run object that matches the provided configuration.
+
+    Raises:
+        ValueError: If no run matches the criteria.
+
+    See Also:
+        RunCollection.filter: The method that performs the actual filtering
+        logic.
+    """
+    filtered_runs = filter_runs(runs, config, **kwargs)
 
+    if len(filtered_runs) == 0:
+        raise ValueError("No run matches the provided configuration.")
 
-def find_last_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | None:
+    return filtered_runs[-1]
+
+
+def try_find_last_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | None:
     """
     Find the last run based on the provided configuration.
 
@@ -449,30 +669,74 @@ def find_last_run(runs: list[Run], config: object | None = None, **kwargs) -> Ru
     the provided parameters. If no run matches the criteria, None is returned.
 
     Args:
-        runs: The runs to filter.
-        config: The configuration object to identify the run.
+        runs (list[Run]): The runs to filter.
+        config (object | None): The configuration object to identify the run.
         **kwargs: Additional key-value pairs to filter the runs.
 
     Returns:
         The last run object that matches the provided configuration, or None
         if no runs match the criteria.
     """
-    runs = filter_runs(runs, config, **kwargs)
-    return runs[-1] if runs else None
+    filtered_runs = filter_runs(runs, config, **kwargs)
+
+    if len(filtered_runs) == 0:
+        return None
+
+    return filtered_runs[-1]
 
 
-def get_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | None:
+def get_run(runs: list[Run], config: object | None = None, **kwargs) -> Run:
     """
     Retrieve a specific run based on the provided configuration.
 
     This method filters the runs in the collection according to the
     specified configuration object and returns the run that matches
-    the provided parameters. If more than one run matches the criteria,
-    a `ValueError` is raised.
+    the provided parameters. If no run matches the criteria, or if more
+    than one run matches the criteria, a `ValueError` is raised.
 
     Args:
-        runs: The runs to filter.
-        config: The configuration object to identify the run.
+        runs (list[Run]): The runs to filter.
+        config (object | None): The configuration object to identify the run.
+        **kwargs: Additional key-value pairs to filter the runs.
+
+    Returns:
+        The run object that matches the provided configuration.
+
+    Raises:
+        ValueError: If no run matches the criteria or if more than one run
+        matches the criteria.
+
+    See Also:
+        RunCollection.filter: The method that performs the actual filtering
+        logic.
+    """
+    filtered_runs = filter_runs(runs, config, **kwargs)
+
+    if len(filtered_runs) == 0:
+        raise ValueError("No run matches the provided configuration.")
+
+    if len(filtered_runs) == 1:
+        return filtered_runs[0]
+
+    msg = (
+        f"Multiple runs were filtered. Expected number of runs is 1, "
+        f"but found {len(filtered_runs)} runs."
+    )
+    raise ValueError(msg)
+
+
+def try_get_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | None:
+    """
+    Retrieve a specific run based on the provided configuration.
+
+    This method filters the runs in the collection according to the
+    specified configuration object and returns the run that matches
+    the provided parameters. If no run matches the criteria, None is returned.
+    If more than one run matches the criteria, a `ValueError` is raised.
+
+    Args:
+        runs (list[Run]): The runs to filter.
+        config (object | None): The configuration object to identify the run.
         **kwargs: Additional key-value pairs to filter the runs.
 
     Returns:
@@ -481,16 +745,23 @@ def get_run(runs: list[Run], config: object | None = None, **kwargs) -> Run | No
 
     Raises:
         ValueError: If more than one run matches the criteria.
+
+    See Also:
+        RunCollection.filter: The method that performs the actual filtering
+        logic.
     """
-    runs = filter_runs(runs, config, **kwargs)
+    filtered_runs = filter_runs(runs, config, **kwargs)
 
-    if len(runs) == 0:
+    if len(filtered_runs) == 0:
         return None
 
-    if len(runs) == 1:
-        return runs[0]
+    if len(filtered_runs) == 1:
+        return filtered_runs[0]
 
-    msg = f"Multiple runs were filtered. Expected number of runs is 1, but found {len(runs)} runs."
+    msg = (
+        "Multiple runs were filtered. Expected number of runs is 1, "
+        f"but found {len(filtered_runs)} runs."
+    )
     raise ValueError(msg)
 
 
@@ -498,12 +769,12 @@ def get_param_names(runs: list[Run]) -> list[str]:
     """
     Get the parameter names from the runs.
 
-    This method extracts the unique parameter names from the provided list of runs.
-    It iterates through each run and collects the parameter names into a set to
-    ensure uniqueness.
+    This method extracts the unique parameter names from the provided list of
+    runs. It iterates through each run and collects the parameter names into a
+    set to ensure uniqueness.
 
     Args:
-        runs: The list of runs from which to extract parameter names.
+        runs (list[Run]): The list of runs from which to extract parameter names.
 
     Returns:
         A list of unique parameter names.
@@ -527,7 +798,8 @@ def get_param_dict(runs: list[Run]) -> dict[str, list[str]]:
     and the values are lists of parameter values.
 
     Args:
-        runs: The list of runs from which to extract parameter names and values.
+        runs (list[Run]): The list of runs from which to extract parameter names
+        and values.
 
     Returns:
         A dictionary where the keys are parameter names and the values are lists
@@ -552,7 +824,7 @@ def load_config(run: Run) -> DictConfig:
     `.hydra/config.yaml` is not found in the run's artifact directory.
 
     Args:
-        run: The Run instance for which to load the configuration.
+        run (Run): The Run instance for which to load the configuration.
 
     Returns:
         The loaded configuration as a DictConfig object. Returns an empty
@@ -570,37 +842,3 @@ def _load_config(run_id: str) -> DictConfig:
         return DictConfig({})
 
     return OmegaConf.load(path)  # type: ignore
-
-
-# def get_hydra_output_dir(run: Run_ | Series | str) -> Path:
-#     """
-#     Get the Hydra output directory.
-
-#     Args:
-#         run: The run object.
-
-#     Returns:
-#         Path: The Hydra output directory.
-#     """
-#     path = get_artifact_dir(run) / ".hydra/hydra.yaml"
-
-#     if path.exists():
-#         hc = OmegaConf.load(path)
-#         return Path(hc.hydra.runtime.output_dir)
-
-#     raise FileNotFoundError
-
-
-# def log_hydra_output_dir(run: Run_ | Series | str) -> None:
-#     """
-#     Log the Hydra output directory.
-
-#     Args:
-#         run: The run object.
-
-#     Returns:
-#         None
-#     """
-#     output_dir = get_hydra_output_dir(run)
-#     run_id = run if isinstance(run, str) else run.info.run_id
-#     mlflow.log_artifacts(output_dir.as_posix(), run_id=run_id)