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

hydraflow/__init__.py

@@ -3,6 +3,7 @@
 from hydraflow.core.context import chdir_artifact, log_run, start_run
 from hydraflow.core.io import (
     get_artifact_dir,
+    get_experiment_names,
     iter_artifact_paths,
     iter_artifacts_dirs,
     iter_experiment_dirs,
@@ -17,6 +18,7 @@ __all__ = [
     "RunCollection",
     "chdir_artifact",
     "get_artifact_dir",
+    "get_experiment_names",
     "iter_artifact_paths",
     "iter_artifacts_dirs",
     "iter_experiment_dirs",

hydraflow/core/context.py

@@ -38,11 +38,11 @@ def log_run(run: Run) -> Iterator[None]:
     import mlflow
 
     hc = HydraConfig.get()
-    hydra_dir = Path(hc.runtime.output_dir)
+    hydra_output_dir = Path(hc.runtime.output_dir)
 
     # Save '.hydra' config directory.
-    hydra_subdir = hydra_dir / (hc.output_subdir or "")
-    mlflow.log_artifacts(hydra_subdir.as_posix(), hc.output_subdir)
+    hydra_dir = hydra_output_dir / (hc.output_subdir or "")
+    mlflow.log_artifacts(hydra_dir.as_posix(), ".hydra")
 
     try:
         yield
@@ -53,7 +53,7 @@ def log_run(run: Run) -> Iterator[None]:
         raise
 
     finally:
-        log_text(run, hydra_dir)
+        log_text(run, hydra_output_dir)
 
 
 @contextmanager

hydraflow/core/io.py

@@ -107,6 +107,12 @@ def predicate_experiment_dir(
     return experiment_names(name)
 
 
+def get_experiment_names(tracking_dir: str | Path) -> list[str]:
+    """Get the experiment names from the tracking directory."""
+    names = [get_experiment_name(path) for path in Path(tracking_dir).iterdir()]
+    return [name for name in names if name is not None and name != "Default"]
+
+
 def iter_experiment_dirs(
     tracking_dir: str | Path,
     experiment_names: str | list[str] | Callable[[str], bool] | None = None,

hydraflow/core/main.py

@@ -36,7 +36,8 @@ Example:
 from __future__ import annotations
 
 from functools import wraps
-from typing import TYPE_CHECKING, TypeVar
+from pathlib import Path
+from typing import TYPE_CHECKING
 
 import hydra
 from hydra.core.config_store import ConfigStore
@@ -48,23 +49,20 @@ from hydraflow.core.io import file_uri_to_path
 
 if TYPE_CHECKING:
     from collections.abc import Callable
-    from pathlib import Path
     from typing import Any
 
     from mlflow.entities import Run
 
 
-T = TypeVar("T")
-
-
-def main(
-    node: T | type[T],
+def main[C](
+    node: C | type[C],
     config_name: str = "config",
     *,
     chdir: bool = False,
     force_new_run: bool = False,
     match_overrides: bool = False,
     rerun_finished: bool = False,
+    update: Callable[[C], C | None] | None = None,
 ):
     """Decorator for configuring and running MLflow experiments with Hydra.
 
@@ -83,6 +81,8 @@ def main(
             instead of full config. Defaults to False.
         rerun_finished: If True, allows rerunning completed runs. Defaults to
             False.
+        update: A function that takes a configuration and returns a new
+            configuration. Defaults to None.
 
     """
     import mlflow
@@ -90,21 +90,29 @@ def main(
 
     finished = RunStatus.to_string(RunStatus.FINISHED)
 
-    def decorator(app: Callable[[Run, T], None]) -> Callable[[], None]:
+    def decorator(app: Callable[[Run, C], None]) -> Callable[[], None]:
         ConfigStore.instance().store(config_name, node)
 
         @hydra.main(config_name=config_name, version_base=None)
         @wraps(app)
-        def inner_decorator(config: T) -> None:
+        def inner_decorator(cfg: C) -> None:
             hc = HydraConfig.get()
             experiment = mlflow.set_experiment(hc.job.name)
 
+            if update:
+                if cfg_ := update(cfg):
+                    cfg = cfg_
+
+                hydra_dir = Path(hc.runtime.output_dir) / (hc.output_subdir or "")
+                cfg_path = hydra_dir.joinpath("config.yaml")
+                OmegaConf.save(cfg, cfg_path)
+
             if force_new_run:
                 run_id = None
             else:
                 uri = experiment.artifact_location
                 overrides = hc.overrides.task if match_overrides else None
-                run_id = get_run_id(uri, config, overrides)
+                run_id = get_run_id(uri, cfg, overrides)
 
                 if run_id and not rerun_finished:
                     run = mlflow.get_run(run_id)
@@ -112,7 +120,7 @@ def main(
                         return
 
             with start_run(run_id=run_id, chdir=chdir) as run:
-                app(run, config)
+                app(run, cfg)
 
         return inner_decorator
 

hydraflow/core/run.py

@@ -229,6 +229,8 @@ class Run[C, I = None]:
         cfg: DictConfig = self.cfg  # type: ignore
 
         if isinstance(key, str):
+            key = key.replace("__", ".")
+
             if force or OmegaConf.select(cfg, key, default=MISSING) is MISSING:
                 v = value(self) if callable(value) else value  # type: ignore
                 OmegaConf.update(cfg, key, v, force_add=True)
@@ -246,32 +248,51 @@ class Run[C, I = None]:
             raise TypeError(msg)
 
         for k, v in zip(key, value, strict=True):
-            if force or OmegaConf.select(cfg, k, default=MISSING) is MISSING:
-                OmegaConf.update(cfg, k, v, force_add=True)
+            k_ = k.replace("__", ".")
+            if force or OmegaConf.select(cfg, k_, default=MISSING) is MISSING:
+                OmegaConf.update(cfg, k_, v, force_add=True)
 
-    def get(self, key: str) -> Any:
+    def get(self, key: str, default: Any | Callable[[Self], Any] = MISSING) -> Any:
         """Get a value from the information or configuration.
 
         Args:
-            key: The key to look for. Can use dot notation for nested keys
-                in configuration.
+            key: The key to look for. Can use dot notation for
+                nested keys in configuration.
+            default: Value to return if the key is not found.
+                If a callable, it will be called with the Run instance
+                and the value returned will be used as the default.
+                If not provided, AttributeError will be raised.
 
         Returns:
-            Any: The value associated with the key.
+            Any: The value associated with the key, or the
+            default value if the key is not found and a default
+            is provided.
 
         Raises:
-            AttributeError: If the key is not found in any of the components.
+            AttributeError: If the key is not found and
+                no default is provided.
 
         """
+        key = key.replace("__", ".")
+
         value = OmegaConf.select(self.cfg, key, default=MISSING)  # type: ignore
         if value is not MISSING:
             return value
 
+        if self.impl and hasattr(self.impl, key):
+            return getattr(self.impl, key)
+
         info = self.info.to_dict()
         if key in info:
             return info[key]
 
-        msg = f"Key not found: {key}"
+        if default is not MISSING:
+            if callable(default):
+                return default(self)
+
+            return default
+
+        msg = f"No such key: {key}"
         raise AttributeError(msg)
 
     def predicate(self, key: str, value: Any) -> bool:
@@ -298,32 +319,35 @@ class Run[C, I = None]:
 
         """
         attr = self.get(key)
+        return _predicate(attr, value)
 
-        if callable(value):
-            return bool(value(attr))
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the Run to a dictionary."""
+        info = self.info.to_dict()
+        cfg = OmegaConf.to_container(self.cfg)
+        return info | _flatten_dict(cfg)  # type: ignore
 
-        if isinstance(value, ListConfig):
-            value = list(value)
 
-        if isinstance(value, list | set) and not _is_iterable(attr):
-            return attr in value
+def _predicate(attr: Any, value: Any) -> bool:
+    if callable(value):
+        return bool(value(attr))
 
-        if isinstance(value, tuple) and len(value) == 2 and not _is_iterable(attr):
-            return value[0] <= attr <= value[1]
+    if isinstance(value, ListConfig):
+        value = list(value)
 
-        if _is_iterable(value):
-            value = list(value)
+    if isinstance(value, list | set) and not _is_iterable(attr):
+        return attr in value
 
-        if _is_iterable(attr):
-            attr = list(attr)
+    if isinstance(value, tuple) and len(value) == 2 and not _is_iterable(attr):
+        return value[0] <= attr <= value[1]
 
-        return attr == value
+    if _is_iterable(value):
+        value = list(value)
 
-    def to_dict(self) -> dict[str, Any]:
-        """Convert the Run to a dictionary."""
-        info = self.info.to_dict()
-        cfg = OmegaConf.to_container(self.cfg)
-        return info | _flatten_dict(cfg)  # type: ignore
+    if _is_iterable(attr):
+        attr = list(attr)
+
+    return attr == value
 
 
 def _is_iterable(value: Any) -> bool:

hydraflow/core/run_collection.py

@@ -38,12 +38,13 @@ Note:
 from __future__ import annotations
 
 from collections.abc import Hashable, Iterable, Sequence
+from dataclasses import MISSING
 from typing import TYPE_CHECKING, overload
 
 import numpy as np
 import polars as pl
 from omegaconf import OmegaConf
-from polars import DataFrame
+from polars import DataFrame, Series
 
 from .run import Run
 
@@ -139,6 +140,47 @@ class RunCollection[R: Run[Any, Any]](Sequence[R]):
         """
         return iter(self.runs)
 
+    def preload(
+        self,
+        *,
+        n_jobs: int = 0,
+        cfg: bool = True,
+        impl: bool = True,
+    ) -> Self:
+        """Pre-load configuration and implementation objects for all runs in parallel.
+
+        This method eagerly evaluates the cfg and impl properties of all runs
+        in the collection, potentially in parallel using joblib. This can
+        significantly improve performance for subsequent operations that
+        access these properties, as they will be already loaded in memory.
+
+        Args:
+            cfg (bool): Whether to preload the configuration objects
+            impl (bool): Whether to preload the implementation objects
+            n_jobs (int): Number of parallel jobs to run
+                (-1 means using all processors)
+
+        Returns:
+            Self: The same RunCollection instance with preloaded
+            configuration and implementation objects.
+
+        """
+
+        def load(run: R) -> None:
+            _ = cfg and run.cfg
+            _ = impl and run.impl
+
+        if n_jobs == 0:
+            for run in self:
+                load(run)
+            return self
+
+        from joblib import Parallel, delayed
+
+        parallel = Parallel(backend="threading", n_jobs=n_jobs)
+        parallel(delayed(load)(run) for run in self)
+        return self
+
     @overload
     def update(
         self,
@@ -334,56 +376,107 @@ class RunCollection[R: Run[Any, Any]](Sequence[R]):
 
         raise _value_error()
 
-    def to_list(self, key: str) -> list[Any]:
+    def to_list(
+        self,
+        key: str,
+        default: Any | Callable[[R], Any] = MISSING,
+    ) -> list[Any]:
         """Extract a list of values for a specific key from all runs.
 
         Args:
             key: The key to extract from each run.
+            default: The default value to return if the key is not found.
+                If a callable, it will be called with the Run instance
+                and the value returned will be used as the default.
 
         Returns:
             list[Any]: A list containing the values for the
             specified key from each run.
 
         """
-        return [run.get(key) for run in self]
+        return [run.get(key, default) for run in self]
 
-    def to_numpy(self, key: str) -> NDArray:
+    def to_numpy(
+        self,
+        key: str,
+        default: Any | Callable[[R], Any] = MISSING,
+    ) -> NDArray:
         """Extract values for a specific key from all runs as a NumPy array.
 
         Args:
             key: The key to extract from each run.
+            default: The default value to return if the key is not found.
+                If a callable, it will be called with the Run instance
+                and the value returned will be used as the default.
 
         Returns:
             NDArray: A NumPy array containing the values for the
             specified key from each run.
 
         """
-        return np.array(self.to_list(key))
+        return np.array(self.to_list(key, default))
 
-    def unique(self, key: str) -> NDArray:
+    def to_series(
+        self,
+        key: str,
+        default: Any | Callable[[R], Any] = MISSING,
+        *,
+        name: str | None = None,
+    ) -> Series:
+        """Extract values for a specific key from all runs as a Polars series.
+
+        Args:
+            key: The key to extract from each run.
+            default: The default value to return if the key is not found.
+                If a callable, it will be called with the Run instance
+                and the value returned will be used as the default.
+            name: The name of the series. If not provided, the key will be used.
+
+        Returns:
+            Series: A Polars series containing the values for the
+            specified key from each run.
+
+        """
+        return Series(name or key, self.to_list(key, default))
+
+    def unique(
+        self,
+        key: str,
+        default: Any | Callable[[R], Any] = MISSING,
+    ) -> NDArray:
         """Get the unique values for a specific key across all runs.
 
         Args:
             key: The key to extract unique values for.
+            default: The default value to return if the key is not found.
+                If a callable, it will be called with the Run instance
+                and the value returned will be used as the default.
 
         Returns:
             NDArray: A NumPy array containing the unique values for the
             specified key.
 
         """
-        return np.unique(self.to_numpy(key), axis=0)
+        return np.unique(self.to_numpy(key, default), axis=0)
 
-    def n_unique(self, key: str) -> int:
+    def n_unique(
+        self,
+        key: str,
+        default: Any | Callable[[R], Any] = MISSING,
+    ) -> int:
         """Count the number of unique values for a specific key across all runs.
 
         Args:
             key: The key to count unique values for.
+            default: The default value to return if the key is not found.
+                If a callable, it will be called with the Run instance
+                and the value returned will be used as the default.
 
         Returns:
             int: The number of unique values for the specified key.
 
         """
-        return len(self.unique(key))
+        return len(self.unique(key, default))
 
     def sort(self, *keys: str, reverse: bool = False) -> Self:
         """Sort runs based on one or more keys.
@@ -409,13 +502,22 @@ class RunCollection[R: Run[Any, Any]](Sequence[R]):
 
         return self[index]
 
-    def to_frame(self, *keys: str, **kwargs: Callable[[R], Any]) -> DataFrame:
+    def to_frame(
+        self,
+        *keys: str,
+        defaults: dict[str, Any | Callable[[R], Any]] | None = None,
+        **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.
+            defaults (dict[str, Any | Callable[[R], Any]] | None): Default
+                values for the keys. If a callable, it will be called with
+                the Run instance and the value returned will be used as the
+                default.
             **kwargs (Callable[[R], Any]): Additional columns to compute
                 using callables that take a Run and return a value.
 
@@ -424,15 +526,20 @@ class RunCollection[R: Run[Any, Any]](Sequence[R]):
             from the runs.
 
         """
+        if defaults is None:
+            defaults = {}
+
         if keys:
-            df = DataFrame({key: self.to_list(key) for key in keys})
+            df = DataFrame(
+                {key: self.to_list(key, defaults.get(key, MISSING)) 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()]
+        columns = [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]:

hydraflow/core/run_info.py

@@ -11,9 +11,12 @@ was created.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from functools import cached_property
+from functools import cache, cached_property
+from pathlib import Path
 from typing import TYPE_CHECKING
 
+from omegaconf import OmegaConf
+
 if TYPE_CHECKING:
     from pathlib import Path
     from typing import Any
@@ -47,7 +50,7 @@ class RunInfo:
         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)
+        return get_job_name(self.run_dir.parent)
 
     def to_dict(self) -> dict[str, Any]:
         """Convert the RunInfo to a dictionary."""
@@ -58,27 +61,23 @@ class RunInfo:
         }
 
 
-def get_job_name(run_dir: Path) -> str:
-    """Extract the Hydra job name from the Hydra configuration file.
+@cache
+def get_job_name(experiment_dir: Path) -> str:
+    """Get the job name from an experiment directory.
 
-    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).
+    Extracts the job name from the meta.yaml file. Returns an empty string
+    if the file does not exist or if the job name cannot be found.
 
     Args:
-        run_dir (Path): The directory where the run artifacts are stored.
+        experiment_dir: Path to the experiment directory containing the meta.yaml file
 
     Returns:
-        str: The Hydra job name, which was used as the MLflow Experiment name.
+        The job name as a string, or an empty string if the file does not exist
 
     """
-    hydra_file = run_dir / "artifacts/.hydra/hydra.yaml"
-
-    if not hydra_file.exists():
+    path = experiment_dir / "meta.yaml"
+    if not path.exists():
         return ""
 
-    text = hydra_file.read_text()
-    if "  job:\n    name: " in text:
-        return text.split("  job:\n    name: ")[1].split("\n")[0]
-
-    return ""
+    meta = OmegaConf.load(experiment_dir / "meta.yaml")
+    return OmegaConf.select(meta, "name")

hydraflow/executor/conf.py

@@ -4,10 +4,10 @@ from dataclasses import dataclass, field
 
 
 @dataclass
-class Step:
-    batch: str = ""
-    args: str = ""
-    with_: str = ""
+class Set:
+    each: str = ""
+    all: str = ""
+    add: str = ""
 
 
 @dataclass
@@ -16,8 +16,8 @@ class Job:
     run: str = ""
     call: str = ""
     submit: str = ""
-    with_: str = ""
-    steps: list[Step] = field(default_factory=list)
+    add: str = ""
+    sets: list[Set] = field(default_factory=list)
 
 
 @dataclass

hydraflow/executor/io.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from omegaconf import DictConfig, ListConfig, OmegaConf
+from omegaconf import DictConfig, OmegaConf
 
 from .conf import HydraflowConf
 
@@ -38,25 +38,9 @@ def load_config() -> HydraflowConf:
     if not isinstance(cfg, DictConfig):
         return schema
 
-    rename_with(cfg)
-
     return OmegaConf.merge(schema, cfg)  # type: ignore[return-value]
 
 
-def rename_with(cfg: DictConfig) -> None:
-    """Rename the `with` field to `with_`."""
-    if "with" in cfg:
-        cfg["with_"] = cfg.pop("with")
-
-    for key in list(cfg.keys()):
-        if isinstance(cfg[key], DictConfig):
-            rename_with(cfg[key])
-        elif isinstance(cfg[key], ListConfig):
-            for item in cfg[key]:
-                if isinstance(item, DictConfig):
-                    rename_with(item)
-
-
 def get_job(name: str) -> Job:
     """Get a job from the config."""
     cfg = load_config()

hydraflow/executor/job.py

@@ -2,7 +2,7 @@
 
 This module provides functionality for executing jobs in HydraFlow, including:
 
-- Argument parsing and expansion for job steps
+- Argument parsing and expansion for job parameter sets
 - Batch processing of Hydra configurations
 - Execution of jobs via shell commands or Python functions
 
@@ -11,8 +11,9 @@ The module supports two execution modes:
 1. Shell command execution
 2. Python function calls
 
-Each job can consist of multiple steps, and each step can have its own
-arguments and configurations that will be expanded into multiple runs.
+Each job can consist of multiple parameter sets, and each parameter
+set can have its own arguments and configurations that will be expanded
+into multiple runs.
 """
 
 from __future__ import annotations
@@ -39,24 +40,24 @@ if TYPE_CHECKING:
     from .conf import Job
 
 
-def iter_args(batch: str, args: str) -> Iterator[list[str]]:
+def iter_args(each: str, all_: str) -> Iterator[list[str]]:
     """Iterate over combinations generated from parsed arguments.
 
     Generate all possible combinations of arguments by parsing and
     expanding each one, yielding them as an iterator.
 
     Args:
-        batch (str): The batch to parse.
-        args (str): The arguments to parse.
+        each (str): The 'each' parameter to parse.
+        all_ (str): The 'all' parameter to parse.
 
     Yields:
         list[str]: a list of the parsed argument combinations.
 
     """
-    args_ = collect(args)
+    all_params = collect(all_)
 
-    for batch_ in expand(batch):
-        yield [*batch_, *args_]
+    for each_params in expand(each):
+        yield [*each_params, *all_params]
 
 
 def iter_batches(job: Job) -> Iterator[list[str]]:
@@ -74,14 +75,40 @@ def iter_batches(job: Job) -> Iterator[list[str]]:
 
     """
     job_name = f"hydra.job.name={job.name}"
-    job_configs = shlex.split(job.with_)
+    job_add = shlex.split(job.add)
 
-    for step in job.steps:
-        configs = shlex.split(step.with_) or job_configs
+    for set_ in job.sets:
+        add = merge_args(job_add, shlex.split(set_.add)) if set_.add else job_add
 
-        for args in iter_args(step.batch, step.args):
+        for args in iter_args(set_.each, set_.all):
             sweep_dir = f"hydra.sweep.dir=multirun/{ulid.ULID()}"
-            yield ["--multirun", *args, job_name, sweep_dir, *configs]
+            yield ["--multirun", *args, job_name, sweep_dir, *add]
+
+
+def merge_args(first: list[str], second: list[str]) -> list[str]:
+    """Merge two lists of arguments.
+
+    This function merges two lists of arguments by checking for conflicts
+    and resolving them by keeping the values from the second list.
+
+    Args:
+        first (list[str]): The first list of arguments.
+        second (list[str]): The second list of arguments.
+
+    Returns:
+        list[str]: A merged list of arguments.
+
+    """
+    merged = {}
+
+    for item in [*first, *second]:
+        if "=" in item:
+            key, value = item.split("=", 1)
+            merged[key] = value
+        else:
+            merged[item] = None
+
+    return [k if v is None else f"{k}={v}" for k, v in merged.items()]
 
 
 @dataclass

hydraflow/executor/parser.py

@@ -165,25 +165,26 @@ SUFFIX_EXPONENT = {
 
 
 def _get_range(arg: str) -> tuple[float, float, float]:
+    """Return a tuple of (start, stop, step)."""
     args = [to_number(x) for x in arg.split(":")]
 
     if len(args) == 2:
         if args[0] > args[1]:
             raise ValueError("start cannot be greater than stop")
 
-        return (args[0], 1, args[1])
+        return (args[0], args[1], 1)
 
-    if args[1] == 0:
+    if args[2] == 0:
         raise ValueError("step cannot be zero")
-    if args[1] > 0 and args[0] > args[2]:
+    if args[2] > 0 and args[0] > args[1]:
         raise ValueError("start cannot be greater than stop")
-    if args[1] < 0 and args[0] < args[2]:
+    if args[2] < 0 and args[0] < args[1]:
         raise ValueError("start cannot be less than stop")
 
     return args[0], args[1], args[2]
 
 
-def _arange(start: float, step: float, stop: float) -> list[float]:
+def _arange(start: float, stop: float, step: float) -> list[float]:
     """Generate a range of floating point numbers.
 
     This function generates a range of floating point numbers
@@ -191,8 +192,8 @@ def _arange(start: float, step: float, stop: float) -> list[float]:
 
     Args:
         start (float): The starting value.
-        step (float): The step size.
         stop (float): The end value (inclusive).
+        step (float): The step size.
 
     Returns:
         list[float]: A list of floating point numbers from start to stop
@@ -323,7 +324,7 @@ def collect_parentheses(arg: str) -> list[str]:
         list[str]: A list of the collected values.
 
     Examples:
-        >>> collect_parentheses("(1:3,5:2:9,20)k")
+        >>> collect_parentheses("(1:3,5:9:2,20)k")
         ['1e3', '2e3', '3e3', '5e3', '7e3', '9e3', '20e3']
         >>> collect_parentheses("2e(-1,-2,-3)")
         ['2e-1', '2e-2', '2e-3']
@@ -352,7 +353,7 @@ def collect_values(arg: str) -> list[str]:
     Examples:
         >>> collect_values("1:4")
         ['1', '2', '3', '4']
-        >>> collect_values("1.2:0.1:1.4:k")
+        >>> collect_values("1.2:1.4:0.1:k")
         ['1.2e3', '1.3e3', '1.4e3']
         >>> collect_values("0.1")
         ['0.1']

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hydraflow
-Version: 0.15.0
+Version: 0.16.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
@@ -51,7 +51,7 @@ Requires-Dist: ruff>=0.11
 Requires-Dist: typer>=0.15
 Description-Content-Type: text/markdown
 
-# Hydraflow
+# HydraFlow
 
 [![PyPI Version][pypi-v-image]][pypi-v-link]
 [![Build Status][GHAction-image]][GHAction-link]
@@ -60,6 +60,7 @@ Description-Content-Type: text/markdown
 [![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/
 [GHAction-image]: https://github.com/daizutabi/hydraflow/actions/workflows/ci.yaml/badge.svg?branch=main&event=push
@@ -73,117 +74,125 @@ Description-Content-Type: text/markdown
 
 ## Overview
 
-Hydraflow is a library designed to seamlessly integrate
-[Hydra](https://hydra.cc/) and [MLflow](https://mlflow.org/), making it easier to
-manage and track machine learning experiments. By combining the flexibility of
-Hydra's configuration management with the robust experiment tracking capabilities
-of MLflow, Hydraflow provides a comprehensive solution for managing complex
-machine learning workflows.
+HydraFlow seamlessly integrates [Hydra](https://hydra.cc/) and [MLflow](https://mlflow.org/) to streamline machine learning experiment workflows. By combining Hydra's powerful configuration management with MLflow's robust experiment tracking, HydraFlow provides a comprehensive solution for defining, executing, and analyzing machine learning experiments.
+
+## Design Principles
+
+HydraFlow is built on the following design principles:
+
+1. **Type Safety** - Utilizing Python dataclasses for configuration type checking and IDE support
+2. **Reproducibility** - Automatically tracking all experiment configurations for fully reproducible experiments
+3. **Analysis Capabilities** - Providing powerful APIs for easily analyzing experiment results
+4. **Workflow Integration** - Creating a cohesive workflow by integrating Hydra's configuration management with MLflow's experiment tracking
 
 ## Key Features
 
-- **Configuration Management**: Utilize Hydra's advanced configuration management
-  to handle complex parameter sweeps and experiment setups.
-- **Experiment Tracking**: Leverage MLflow's tracking capabilities to log parameters,
-  metrics, and artifacts for each run.
-- **Artifact Management**: Automatically log and manage artifacts, such as model
-  checkpoints and configuration files, with MLflow.
-- **Seamless Integration**: Easily integrate Hydra and MLflow in your machine learning
-  projects with minimal setup.
-- **Rich CLI Interface**: Command-line tools for managing experiments and viewing results.
-- **Cross-Platform Support**: Works consistently across different operating systems.
+- **Type-safe Configuration Management** - Define experiment parameters using Python dataclasses with full IDE support and validation
+- **Seamless Hydra-MLflow Integration** - Automatically register configurations with Hydra and track experiments with MLflow
+- **Advanced Parameter Sweeps** - Define complex parameter spaces using extended sweep syntax for numerical ranges, combinations, and SI prefixes
+- **Workflow Automation** - Create reusable experiment workflows with YAML-based job definitions
+- **Powerful Analysis Tools** - Filter, group, and analyze experiment results with type-aware APIs
+- **Custom Implementation Support** - Extend experiment analysis with domain-specific functionality
 
 ## Installation
 
-You can install Hydraflow via pip:
-
 ```bash
 pip install hydraflow
 ```
 
 **Requirements:** Python 3.13+
 
-## Quick Start
-
-Here is a simple example to get you started with Hydraflow:
+## Quick Example
 
 ```python
-from __future__ import annotations
-
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
-
+from mlflow.entities import Run
 import hydraflow
-import mlflow
 
-if TYPE_CHECKING:
-    from mlflow.entities import Run
+@dataclass
+class Config:
+    width: int = 1024
+    height: int = 768
 
+@hydraflow.main(Config)
+def app(run: Run, cfg: Config) -> None:
+    # Your experiment code here
+    print(f"Running with width={cfg.width}, height={cfg.height}")
+
+    # Log metrics
+    hydraflow.log_metric("area", cfg.width * cfg.height)
 
+if __name__ == "__main__":
+    app()
+```
+
+Execute a parameter sweep with:
+
+```bash
+python app.py -m width=800,1200 height=600,900
+```
+
+## Core Components
+
+HydraFlow consists of the following key components:
+
+### Configuration Management
+
+Define type-safe configurations using Python dataclasses:
+
+```python
 @dataclass
 class Config:
-    """Configuration for the ML training experiment."""
-    # Training hyperparameters
     learning_rate: float = 0.001
     batch_size: int = 32
     epochs: int = 10
+```
 
-    # Model architecture parameters
-    hidden_size: int = 128
-    dropout: float = 0.1
-
-    # Dataset parameters
-    train_size: float = 0.8
-    random_seed: int = 42
+### Main Decorator
 
+The `@hydraflow.main` decorator integrates Hydra and MLflow:
 
+```python
 @hydraflow.main(Config)
-def app(run: Run, cfg: Config):
-    """Train a model with the given configuration.
-
-    This example demonstrates how to:
+def train(run: Run, cfg: Config) -> None:
+    # Your experiment code
+```
 
-    1. Define a configuration using dataclasses
-    2. Use Hydraflow to integrate with MLflow
-    3. Track metrics and parameters automatically
+### Workflow Automation
 
-    Args:
-        run: MLflow run for the experiment corresponding to the Hydra app.
-            This `Run` instance is automatically created by Hydraflow.
-        cfg: Configuration for the experiment's run.
-            This `Config` instance is originally defined by Hydra, and then
-            automatically passed to the app by Hydraflow.
-    """
-    # Training loop
-    for epoch in range(cfg.epochs):
-        # Simulate training and validation
-        train_loss = 1.0 / (epoch + 1)
-        val_loss = 1.1 / (epoch + 1)
+Define reusable experiment workflows in YAML:
 
-        # Log metrics to MLflow
-        mlflow.log_metrics({
-            "train_loss": train_loss,
-            "val_loss": val_loss
-        }, step=epoch)
+```yaml
+jobs:
+  train_models:
+    run: python train.py
+    sets:
+      - each: model=small,medium,large
+        all: learning_rate=0.001,0.01,0.1
+```
 
-        print(f"Epoch {epoch}: train_loss={train_loss:.4f}, val_loss={val_loss:.4f}")
+### Analysis Tools
 
+Analyze experiment results with powerful APIs:
 
-if __name__ == "__main__":
-    app()
-```
+```python
+from hydraflow import Run, iter_run_dirs
 
-This example demonstrates:
+# Load runs
+runs = Run.load(iter_run_dirs("mlruns"))
 
-- Configuration management with Hydra
-- Automatic experiment tracking with MLflow
-- Parameter logging and metric tracking
-- Type-safe configuration with dataclasses
+# Filter and analyze
+best_runs = runs.filter(model_type="transformer").to_frame("learning_rate", "accuracy")
+```
 
 ## Documentation
 
-For detailed documentation, including advanced usage examples and API reference,
-visit our [documentation site](https://daizutabi.github.io/hydraflow/).
+For detailed documentation, visit our [documentation site](https://daizutabi.github.io/hydraflow/):
+
+- [Getting Started](https://daizutabi.github.io/hydraflow/getting-started/) - Installation and core concepts
+- [Practical Tutorials](https://daizutabi.github.io/hydraflow/practical-tutorials/) - Learn through hands-on examples
+- [User Guide](https://daizutabi.github.io/hydraflow/part1-applications/) - Detailed documentation of HydraFlow's capabilities
+- [API Reference](https://daizutabi.github.io/hydraflow/api/hydraflow/) - Complete API documentation
 
 ## Contributing
 
@@ -191,4 +200,4 @@ We welcome contributions! Please see our [contributing guide](CONTRIBUTING.md) f
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

hydraflow-0.16.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+hydraflow/__init__.py,sha256=8UraqH00Qp0In301ZUmQBRTIGbV1L5zSZACOUlIRPn8,727
+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=igE17oQESGjH-sBnICI8HkZbngY_crkHTgx2E-YkmEo,4155
+hydraflow/core/io.py,sha256=gIH3-Lzs4d5TL3b9y-Nb064Aya7cXQHAuc7EjgKzxII,4694
+hydraflow/core/main.py,sha256=mnYcm1SaCaJwpMCKLEm337LcjW6P5G5LMUjOf78ejkk,5574
+hydraflow/core/run.py,sha256=SugX6JLdBqsfz3JTrB66I3muo03rrmwDvITVZQaF48w,12685
+hydraflow/core/run_collection.py,sha256=cbaJO68WzE-QNlTc8NhOyQ1pHDNberJs-31qTY7P9Fo,19495
+hydraflow/core/run_info.py,sha256=DTuT2eYhOj1WEeIsesOLjY0yltCw6f3Y-5hhvIbDROQ,2518
+hydraflow/executor/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hydraflow/executor/aio.py,sha256=xXsmBPIPdBlopv_1h0FdtOvoKUcuW7PQeKCV2d_lN9I,2122
+hydraflow/executor/conf.py,sha256=8Xq4UAenRKJIl1NBgNbSfv6VUTJhdwPLayZIEAsiBR0,414
+hydraflow/executor/io.py,sha256=18wnHpCMQRGYL-oN2841h9W2aSW_X2SmO68Lx-3FIbU,1043
+hydraflow/executor/job.py,sha256=6QeJ18OMeocXeM04rCYL46GgArfX1SvZs9_4HTomTgE,5436
+hydraflow/executor/parser.py,sha256=RxP8qpDaJ8VLqZ51VlPFyVitWctObhkE_3iPIsY66Cs,14610
+hydraflow-0.16.0.dist-info/METADATA,sha256=g8PnKA-cAU6P0YCPg-hU9E-hpvljNk4v9tOgV3bT_dw,7691
+hydraflow-0.16.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+hydraflow-0.16.0.dist-info/entry_points.txt,sha256=XI0khPbpCIUo9UPqkNEpgh-kqK3Jy8T7L2VCWOdkbSM,48
+hydraflow-0.16.0.dist-info/licenses/LICENSE,sha256=IGdDrBPqz1O0v_UwCW-NJlbX9Hy9b3uJ11t28y2srmY,1062
+hydraflow-0.16.0.dist-info/RECORD,,

hydraflow-0.15.0.dist-info/RECORD

@@ -1,21 +0,0 @@
-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,,