hydraflow 0.14.3__py3-none-any.whl → 0.15.0__py3-none-any.whl

hydraflow/core/run_collection.py

@@ -0,0 +1,525 @@
+"""RunCollection module for HydraFlow.
+
+This module provides the RunCollection class, which represents a collection
+of MLflow Runs in HydraFlow. RunCollection offers functionality for filtering,
+sorting, grouping, and analyzing runs, as well as converting run data to
+various formats such as DataFrames.
+
+The RunCollection class implements the Sequence protocol, allowing it to be
+used like a standard Python list while providing specialized methods for
+working with Run instances.
+
+Example:
+    ```python
+    # Create a collection from a list of runs
+    runs = RunCollection([run1, run2, run3])
+
+    # Filter runs based on criteria
+    filtered = runs.filter(("metrics.accuracy", lambda acc: acc > 0.9))
+
+    # Sort runs by specific keys
+    sorted_runs = runs.sort("metrics.accuracy", reverse=True)
+
+    # Group runs by model type and compute aggregates
+    grouped = runs.group_by("model.type",
+                           avg_acc=lambda rc: sum(r.get("metrics.accuracy")
+                                                 for r in rc) / len(rc))
+
+    # Convert runs to a DataFrame for analysis
+    df = runs.to_frame("run_id", "model.type", "metrics.accuracy")
+    ```
+
+Note:
+    This module requires Polars and NumPy for DataFrame operations and
+    numerical computations.
+
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable, Iterable, Sequence
+from typing import TYPE_CHECKING, overload
+
+import numpy as np
+import polars as pl
+from omegaconf import OmegaConf
+from polars import DataFrame
+
+from .run import Run
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator
+    from typing import Any, Self
+
+    from numpy.typing import NDArray
+
+
+class RunCollection[R: Run[Any, Any]](Sequence[R]):
+    """A collection of Run instances that implements the Sequence protocol.
+
+    RunCollection provides methods for filtering, sorting, grouping, and analyzing
+    runs, as well as converting run data to various formats such as DataFrames.
+
+    Args:
+        runs (Iterable[Run]): An iterable of Run instances to include in
+            the collection.
+
+    """
+
+    runs: list[R]
+    """A list containing the Run instances in this collection."""
+
+    def __init__(self, runs: Iterable[R]) -> None:
+        self.runs = list(runs)
+
+    def __repr__(self) -> str:
+        """Return a string representation of the RunCollection."""
+        class_name = self.__class__.__name__
+        if not self:
+            return f"{class_name}(empty)"
+
+        type_name = repr(self[0])
+        if "(" in type_name:
+            type_name = type_name.split("(", 1)[0]
+        return f"{class_name}({type_name}, n={len(self)})"
+
+    def __len__(self) -> int:
+        """Return the number of Run instances in the collection.
+
+        Returns:
+            int: The number of runs.
+
+        """
+        return len(self.runs)
+
+    def __bool__(self) -> bool:
+        """Return whether the collection contains any Run instances.
+
+        Returns:
+            bool: True if the collection is not empty, False otherwise.
+
+        """
+        return bool(self.runs)
+
+    @overload
+    def __getitem__(self, index: int) -> R: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> Self: ...
+
+    @overload
+    def __getitem__(self, index: Iterable[int]) -> Self: ...
+
+    def __getitem__(self, index: int | slice | Iterable[int]) -> R | Self:
+        """Get a Run or a new RunCollection based on the provided index.
+
+        Args:
+            index: Can be one of:
+                - An integer to get a single Run
+                - A slice to get a subrange of Runs
+                - An iterable of integers to get specific Runs
+
+        Returns:
+            R | Self: A single Run if index is an integer, or a new
+            RunCollection if index is a slice or iterable of integers.
+
+        """
+        if isinstance(index, int):
+            return self.runs[index]
+        if isinstance(index, slice):
+            return self.__class__(self.runs[index])
+        return self.__class__([self.runs[i] for i in index])
+
+    def __iter__(self) -> Iterator[R]:
+        """Return an iterator over the Runs in the collection.
+
+        Returns:
+            Iterator[R]: An iterator yielding Run instances.
+
+        """
+        return iter(self.runs)
+
+    @overload
+    def update(
+        self,
+        key: str,
+        value: Any | Callable[[R], Any],
+        *,
+        force: bool = False,
+    ) -> None: ...
+
+    @overload
+    def update(
+        self,
+        key: tuple[str, ...],
+        value: Iterable[Any] | Callable[[R], Iterable[Any]],
+        *,
+        force: bool = False,
+    ) -> None: ...
+
+    def update(
+        self,
+        key: str | tuple[str, ...],
+        value: Any | Callable[[R], Any],
+        *,
+        force: bool = False,
+    ) -> None:
+        """Update configuration values for all runs in the collection.
+
+        This method calls the update method on each run in the collection.
+
+        Args:
+            key: Either a string representing a single configuration path
+                or a tuple of strings to set multiple configuration values.
+            value: The value(s) to set or a callable that returns such values.
+            force: Whether to force updates even if the keys already exist.
+
+        """
+        for run in self:
+            run.update(key, value, force=force)
+
+    def filter(
+        self,
+        *predicates: Callable[[R], bool] | tuple[str, Any],
+        **kwargs: Any,
+    ) -> Self:
+        """Filter runs based on predicates or key-value conditions.
+
+        This method allows filtering runs using various criteria:
+        - Callable predicates that take a Run and return a boolean
+        - Key-value tuples where the key is a string and the value
+          is compared using the Run.predicate method
+        - Keyword arguments, where the key is a string and the value
+          is compared using the Run.predicate method
+
+        Args:
+            *predicates: Callable predicates or (key, value) tuples
+                for filtering.
+            **kwargs: Additional key-value pairs for filtering.
+
+        Returns:
+            Self: A new RunCollection containing only the runs that
+            match all criteria.
+
+        """
+        runs = self.runs
+
+        for predicate in predicates:
+            if callable(predicate):
+                runs = [r for r in runs if predicate(r)]
+            else:
+                runs = [r for r in runs if r.predicate(*predicate)]
+
+        for key, value in kwargs.items():
+            runs = [r for r in runs if r.predicate(key, value)]
+
+        return self.__class__(runs)
+
+    def try_get(
+        self,
+        *predicates: Callable[[R], bool] | tuple[str, Any],
+        **kwargs: Any,
+    ) -> R | None:
+        """Try to get a single run matching the specified criteria.
+
+        This method applies filters and returns a single matching
+        run if exactly one is found, None if no runs are found,
+        or raises ValueError if multiple runs match.
+
+        Args:
+            *predicates: Callable predicates or (key, value) tuples
+                for filtering.
+            **kwargs: Additional key-value pairs for filtering.
+
+        Returns:
+            R | None: A single Run that matches the criteria, or None if
+            no matches are found.
+
+        Raises:
+            ValueError: If multiple runs match the criteria.
+
+        """
+        runs = self.filter(*predicates, **kwargs)
+
+        n = len(runs)
+        if n == 0:
+            return None
+
+        if n == 1:
+            return runs[0]
+
+        msg = f"Multiple Run ({n}) found matching the criteria, "
+        msg += "expected exactly one"
+        raise ValueError(msg)
+
+    def get(
+        self,
+        *predicates: Callable[[R], bool] | tuple[str, Any],
+        **kwargs: Any,
+    ) -> R:
+        """Get a single run matching the specified criteria.
+
+        This method applies filters and returns a single matching run,
+        or raises ValueError if no runs or multiple runs match.
+
+        Args:
+            *predicates: Callable predicates or (key, value) tuples
+                for filtering.
+            **kwargs: Additional key-value pairs for filtering.
+
+        Returns:
+            R: A single Run that matches the criteria.
+
+        Raises:
+            ValueError: If no runs match or if multiple runs match
+            the criteria.
+
+        """
+        if run := self.try_get(*predicates, **kwargs):
+            return run
+
+        raise _value_error()
+
+    def first(
+        self,
+        *predicates: Callable[[R], bool] | tuple[str, Any],
+        **kwargs: Any,
+    ) -> R:
+        """Get the first run matching the specified criteria.
+
+        This method applies filters and returns the first matching run,
+        or raises ValueError if no runs match.
+
+        Args:
+            *predicates: Callable predicates or (key, value) tuples
+                for filtering.
+            **kwargs: Additional key-value pairs for filtering.
+
+        Returns:
+            R: The first Run that matches the criteria.
+
+        Raises:
+            ValueError: If no runs match the criteria.
+
+        """
+        if runs := self.filter(*predicates, **kwargs):
+            return runs[0]
+
+        raise _value_error()
+
+    def last(
+        self,
+        *predicates: Callable[[R], bool] | tuple[str, Any],
+        **kwargs: Any,
+    ) -> R:
+        """Get the last run matching the specified criteria.
+
+        This method applies filters and returns the last matching run,
+        or raises ValueError if no runs match.
+
+        Args:
+            *predicates: Callable predicates or (key, value) tuples
+                for filtering.
+            **kwargs: Additional key-value pairs for filtering.
+
+        Returns:
+            R: The last Run that matches the criteria.
+
+        Raises:
+            ValueError: If no runs match the criteria.
+
+        """
+        if runs := self.filter(*predicates, **kwargs):
+            return runs[-1]
+
+        raise _value_error()
+
+    def to_list(self, key: str) -> list[Any]:
+        """Extract a list of values for a specific key from all runs.
+
+        Args:
+            key: The key to extract from each run.
+
+        Returns:
+            list[Any]: A list containing the values for the
+            specified key from each run.
+
+        """
+        return [run.get(key) for run in self]
+
+    def to_numpy(self, key: str) -> NDArray:
+        """Extract values for a specific key from all runs as a NumPy array.
+
+        Args:
+            key: The key to extract from each run.
+
+        Returns:
+            NDArray: A NumPy array containing the values for the
+            specified key from each run.
+
+        """
+        return np.array(self.to_list(key))
+
+    def unique(self, key: str) -> NDArray:
+        """Get the unique values for a specific key across all runs.
+
+        Args:
+            key: The key to extract unique values for.
+
+        Returns:
+            NDArray: A NumPy array containing the unique values for the
+            specified key.
+
+        """
+        return np.unique(self.to_numpy(key), axis=0)
+
+    def n_unique(self, key: str) -> int:
+        """Count the number of unique values for a specific key across all runs.
+
+        Args:
+            key: The key to count unique values for.
+
+        Returns:
+            int: The number of unique values for the specified key.
+
+        """
+        return len(self.unique(key))
+
+    def sort(self, *keys: str, reverse: bool = False) -> Self:
+        """Sort runs based on one or more keys.
+
+        Args:
+            *keys: The keys to sort by, in order of priority.
+            reverse: Whether to sort in descending order (default is
+                ascending).
+
+        Returns:
+            Self: A new RunCollection with the runs sorted according to
+            the specified keys.
+
+        """
+        if not keys:
+            return self
+
+        arrays = [self.to_numpy(key) for key in keys]
+        index = np.lexsort(arrays[::-1])
+
+        if reverse:
+            index = index[::-1]
+
+        return self[index]
+
+    def to_frame(self, *keys: str, **kwargs: Callable[[R], Any]) -> DataFrame:
+        """Convert the collection to a Polars DataFrame.
+
+        Args:
+            *keys (str): The keys to include as columns in the DataFrame.
+                If not provided, all keys from each run's to_dict() method
+                will be used.
+            **kwargs (Callable[[R], Any]): Additional columns to compute
+                using callables that take a Run and return a value.
+
+        Returns:
+            DataFrame: A Polars DataFrame containing the specified data
+            from the runs.
+
+        """
+        if keys:
+            df = DataFrame({key: self.to_list(key) for key in keys})
+        else:
+            df = DataFrame(r.to_dict() for r in self)
+
+        if not kwargs:
+            return df
+
+        columns = [pl.Series(k, [v(r) for r in self]) for k, v in kwargs.items()]
+        return df.with_columns(*columns)
+
+    def _group_by(self, *keys: str) -> dict[Any, Self]:
+        result: dict[Any, Self] = {}
+
+        for run in self:
+            keys_ = [to_hashable(run.get(key)) for key in keys]
+            key = keys_[0] if len(keys) == 1 else tuple(keys_)
+
+            if key not in result:
+                result[key] = self.__class__([])
+            result[key].runs.append(run)
+
+        return result
+
+    @overload
+    def group_by(self, *keys: str) -> dict[Any, Self]: ...
+
+    @overload
+    def group_by(
+        self,
+        *keys: str,
+        **kwargs: Callable[[Self | Sequence[R]], Any],
+    ) -> DataFrame: ...
+
+    def group_by(
+        self,
+        *keys: str,
+        **kwargs: Callable[[Self | Sequence[R]], Any],
+    ) -> dict[Any, Self] | DataFrame:
+        """Group runs by one or more keys.
+
+        This method can return either:
+        - A dictionary mapping group keys to RunCollections
+          (no kwargs provided)
+        - A Polars DataFrame with group keys and aggregated
+          values (kwargs provided)
+
+        Args:
+            *keys (str): The keys to group by.
+            **kwargs (Callable[[Self | Sequence[R]], Any]): Aggregation
+                functions to apply to each group. Each function should
+                accept a RunCollection or Sequence[Run] and return a value.
+
+        Returns:
+            dict[Any, Self] | DataFrame: Either a dictionary mapping
+            group keys to RunCollections, or a Polars DataFrame with
+            group keys and aggregated values.
+
+        """
+        gp = self._group_by(*keys)
+        if not kwargs:
+            return gp
+
+        if len(keys) == 1:
+            df = DataFrame({keys[0]: list(gp)})
+        else:
+            df = DataFrame(dict(zip(keys, k, strict=True)) for k in gp)
+        columns = [pl.Series(k, [v(r) for r in gp.values()]) for k, v in kwargs.items()]
+        return df.with_columns(*columns)
+
+
+def to_hashable(value: Any) -> Hashable:
+    """Convert a value to a hashable instance.
+
+    This function handles various types of values and converts them to
+    hashable equivalents for use in dictionaries and sets.
+
+    Args:
+        value: The value to convert to a hashable instance.
+
+    Returns:
+        A hashable version of the input value.
+
+    """
+    if OmegaConf.is_list(value):  # Is ListConfig hashable?
+        return tuple(value)
+    if isinstance(value, Hashable):
+        return value
+    if isinstance(value, np.ndarray):
+        return tuple(value.tolist())
+    try:
+        return tuple(value)
+    except TypeError:
+        return str(value)
+
+
+def _value_error() -> ValueError:
+    msg = "No Run found matching the specified criteria"
+    return ValueError(msg)

hydraflow/core/run_info.py

@@ -0,0 +1,84 @@
+"""RunInfo module for HydraFlow.
+
+This module provides the RunInfo class, which represents a
+MLflow Run in HydraFlow. RunInfo contains information about a run,
+such as the run directory, run ID, and job name.
+The job name is extracted from the Hydra configuration file and
+represents the MLflow Experiment name that was used when the run
+was created.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+    from typing import Any
+
+
+@dataclass
+class RunInfo:
+    """Information about a MLflow Run in HydraFlow.
+
+    This class represents a MLflow Run and contains information
+    such as the run directory, run ID, and job name.
+    The job name is extracted from the Hydra configuration file
+    and represents the MLflow Experiment name that was used when
+    the run was created.
+
+    """
+
+    run_dir: Path
+    """The MLflow Run directory, which contains metrics, parameters, and artifacts."""
+
+    @cached_property
+    def run_id(self) -> str:
+        """The MLflow run ID, which is the name of the run directory."""
+        return self.run_dir.name
+
+    @cached_property
+    def job_name(self) -> str:
+        """The Hydra job name, which was used as the MLflow Experiment name.
+
+        An empty string if the job name cannot be extracted from the
+        Hydra configuration file (e.g., if the file does not exist or does not
+        contain the expected format).
+        """
+        return get_job_name(self.run_dir)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the RunInfo to a dictionary."""
+        return {
+            "run_id": self.run_id,
+            "run_dir": self.run_dir.as_posix(),
+            "job_name": self.job_name,
+        }
+
+
+def get_job_name(run_dir: Path) -> str:
+    """Extract the Hydra job name from the Hydra configuration file.
+
+    Return an empty string if the job name cannot be extracted from the
+    Hydra configuration file (e.g., if the file does not exist or does not
+    contain the expected format).
+
+    Args:
+        run_dir (Path): The directory where the run artifacts are stored.
+
+    Returns:
+        str: The Hydra job name, which was used as the MLflow Experiment name.
+
+    """
+    hydra_file = run_dir / "artifacts/.hydra/hydra.yaml"
+
+    if not hydra_file.exists():
+        return ""
+
+    text = hydra_file.read_text()
+    if "  job:\n    name: " in text:
+        return text.split("  job:\n    name: ")[1].split("\n")[0]
+
+    return ""

{hydraflow-0.14.3.dist-info → hydraflow-0.15.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: hydraflow
-Version: 0.14.3
-Summary: HydraFlow seamlessly integrates Hydra and MLflow to streamline ML experiment management. It combines Hydra's configuration management with MLflow's tracking capabilities, offering automated experiment tracking, versioning, and a rich CLI interface. Perfect for ML researchers and teams who need reproducibility while scaling experiments.
+Version: 0.15.0
+Summary: HydraFlow seamlessly integrates Hydra and MLflow to streamline ML experiment management, combining Hydra's configuration management with MLflow's tracking capabilities.
 Project-URL: Documentation, https://daizutabi.github.io/hydraflow/
 Project-URL: Source, https://github.com/daizutabi/hydraflow
 Project-URL: Issues, https://github.com/daizutabi/hydraflow/issues
@@ -36,40 +36,40 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
+Requires-Python: >=3.13
 Requires-Dist: hydra-core>=1.3
+Requires-Dist: joblib>=1.4.0
 Requires-Dist: mlflow>=2.15
 Requires-Dist: omegaconf>=2.3
+Requires-Dist: polars>=1.26
 Requires-Dist: python-ulid>=3.0.0
 Requires-Dist: rich>=13.9
+Requires-Dist: ruff>=0.11
 Requires-Dist: typer>=0.15
 Description-Content-Type: text/markdown
 
 # Hydraflow
 
 [![PyPI Version][pypi-v-image]][pypi-v-link]
-[![Python Version][python-v-image]][python-v-link]
 [![Build Status][GHAction-image]][GHAction-link]
 [![Coverage Status][codecov-image]][codecov-link]
 [![Documentation Status][docs-image]][docs-link]
+[![Python Version][python-v-image]][python-v-link]
 
 <!-- Badges -->
 [pypi-v-image]: https://img.shields.io/pypi/v/hydraflow.svg
 [pypi-v-link]: https://pypi.org/project/hydraflow/
-[python-v-image]: https://img.shields.io/pypi/pyversions/hydraflow.svg
-[python-v-link]: https://pypi.org/project/hydraflow
 [GHAction-image]: https://github.com/daizutabi/hydraflow/actions/workflows/ci.yaml/badge.svg?branch=main&event=push
 [GHAction-link]: https://github.com/daizutabi/hydraflow/actions?query=event%3Apush+branch%3Amain
 [codecov-image]: https://codecov.io/github/daizutabi/hydraflow/coverage.svg?branch=main
 [codecov-link]: https://codecov.io/github/daizutabi/hydraflow?branch=main
-[docs-image]: https://readthedocs.org/projects/hydraflow/badge/?version=latest
+[docs-image]: https://img.shields.io/badge/docs-latest-blue.svg
 [docs-link]: https://daizutabi.github.io/hydraflow/
+[python-v-image]: https://img.shields.io/pypi/pyversions/hydraflow.svg
+[python-v-link]: https://pypi.org/project/hydraflow
 
 ## Overview
 
@@ -101,6 +101,8 @@ You can install Hydraflow via pip:
 pip install hydraflow
 ```
 
+**Requirements:** Python 3.13+
+
 ## Quick Start
 
 Here is a simple example to get you started with Hydraflow:

hydraflow-0.15.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+hydraflow/__init__.py,sha256=5ByA9ogtS5ZfIYIUSMUjMwAIpr6xGXEXmcABOu4O8RA,673
+hydraflow/cli.py,sha256=3rGr___wwp8KazjLGQ7JO_IgAMqLyMlcVSs_QJK7g0Y,3135
+hydraflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hydraflow/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hydraflow/core/context.py,sha256=LFPNJxmuJQ2VUt-WBU07MC3ySbjlY8rRZ8VxuAih4o4,4148
+hydraflow/core/io.py,sha256=ZBXIL_jlBUiCI0L_J6S5S4OwtBMvdVVMXnekzMuC_JA,4404
+hydraflow/core/main.py,sha256=b9o6Rpn3uoXfDB8o0XZdl-g1yX2SKkOT12-H7lB8Les,5158
+hydraflow/core/run.py,sha256=9JNk3axDdKLpttGx-BC9aqw3d7rosygn2cIzL-fxVlM,11876
+hydraflow/core/run_collection.py,sha256=pV3N83uBhmda9OeaNz1jqpF9z6A9j3jfUHtqy-uxCs4,15671
+hydraflow/core/run_info.py,sha256=3dW9GgWnZZNwbXwMrw-85AqQ956zlQddUi9irSNLR5g,2550
+hydraflow/executor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hydraflow/executor/aio.py,sha256=xXsmBPIPdBlopv_1h0FdtOvoKUcuW7PQeKCV2d_lN9I,2122
+hydraflow/executor/conf.py,sha256=icGbLDh86KgkyiGXwDoEkmZpgAP3X8Jmu_PYqJoTooY,423
+hydraflow/executor/io.py,sha256=yZMcBVmAbPZZ82cAXhgiJfj9p8WvHmzOCMBg_vtEVek,1509
+hydraflow/executor/job.py,sha256=JX6xX9ffvHB7IiAVIfzVRjjnWKaPDxBgqdZf4ZO14CY,4651
+hydraflow/executor/parser.py,sha256=_Rfund3FDgrXitTt_znsTpgEtMDqZ_ICynaB_Zje14Q,14561
+hydraflow-0.15.0.dist-info/METADATA,sha256=2OpqrXDfnVxQ_ZJkS5tEjQH0VTa3yx8jkfFOjbkCK50,7238
+hydraflow-0.15.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hydraflow-0.15.0.dist-info/entry_points.txt,sha256=XI0khPbpCIUo9UPqkNEpgh-kqK3Jy8T7L2VCWOdkbSM,48
+hydraflow-0.15.0.dist-info/licenses/LICENSE,sha256=IGdDrBPqz1O0v_UwCW-NJlbX9Hy9b3uJ11t28y2srmY,1062
+hydraflow-0.15.0.dist-info/RECORD,,