Metadata-Version: 2.3
Name: hydraflow
Version: 0.21.2
Summary: HydraFlow seamlessly integrates Hydra and MLflow to streamline ML experiment management, combining Hydra's configuration management with MLflow's tracking capabilities.
Keywords: machine-learning,mlflow,hydra,experiment-tracking,mlops,ai,deep-learning,research,data-science
Author: daizutabi
Author-email: daizutabi <daizutabi@gmail.com>
License: MIT License
         
         Copyright (c) 2024 Daizu
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: filelock>=3.12.2
Requires-Dist: hydra-core>=1.3
Requires-Dist: joblib>=1.4.0
Requires-Dist: mlflow>=3.6
Requires-Dist: omegaconf>=2.3
Requires-Dist: polars>=1.26
Requires-Dist: python-ulid>=3.0.0
Requires-Dist: rich>=14
Requires-Dist: typer>=0.16
Requires-Python: >=3.13
Project-URL: Documentation, https://daizutabi.github.io/hydraflow/
Project-URL: Issues, https://github.com/daizutabi/hydraflow/issues
Project-URL: Source, https://github.com/daizutabi/hydraflow
Description-Content-Type: text/markdown

# HydraFlow

[![PyPI Version][pypi-v-image]][pypi-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/
[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/graph/badge.svg?token=Yu6lAdVVnd
[codecov-link]: https://codecov.io/github/daizutabi/hydraflow?branch=main
[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

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

- **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

```bash
pip install hydraflow
```

**Requirements:** Python 3.13+

## Quick Example

```python
import hydraflow
from dataclasses import dataclass
from mlflow.entities import Run

@dataclass
class Config:
    width: int = 1024
    height: int = 768

@hydraflow.main(Config, tracking_uri="sqlite:///mlflow.db")
def app(run: Run, cfg: Config) -> None:
    # Your experiment code here
    print(f"Running with width={cfg.width}, height={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:
    learning_rate: float = 0.001
    batch_size: int = 32
    epochs: int = 10
```

### Main Decorator

The `@hydraflow.main` decorator integrates Hydra and MLflow:

```python
@hydraflow.main(Config)
def train(run: Run, cfg: Config) -> None:
    # Your experiment code
```

### Workflow Automation

Define reusable experiment workflows in YAML:

```yaml
jobs:
  train_models:
    run: python train.py
    sets:
      - each: model=small,medium,large
        all: learning_rate=0.001,0.01,0.1
```

### Analysis Tools

Analyze experiment results with powerful APIs:

```python
import mlflow
from hydraflow import Run, iter_run_dirs

# Load runs
mlflow.set_tracking_uri("sqlite:///mlflow.db")
runs = Run.load(iter_run_dirs())

# Filter and analyze
best_runs = runs.filter(model_type="transformer").to_frame("learning_rate", "accuracy")
```

## Documentation

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

## License

This project is licensed under the MIT License.
