hydraflow 0.14.4__tar.gz → 0.15.1__tar.gz

{hydraflow-0.14.4 → hydraflow-0.15.1}/.github/workflows/ci.yaml

@@ -21,7 +21,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.13"]
 
     steps:
       - uses: actions/checkout@v4
@@ -36,7 +36,7 @@ jobs:
       - name: Ruff check
         run: ruff check
       - name: Run test
-        run: uv run pytest -v --junitxml=junit.xml
+        run: uv run pytest -v -n8 --junitxml=junit.xml
       - name: Upload Codecov Results
         if: success()
         uses: codecov/codecov-action@v4

{hydraflow-0.14.4 → hydraflow-0.15.1}/.gitignore

@@ -1,11 +1,11 @@
 *.db
+**/mlruns/
+**/multirun/
+**/outputs/
 .coverage*
 .env
 .venv/
 __pycache__/
 dist/
 lcov.info
-mlruns/
-multirun/
-outputs/
 uv.lock

{hydraflow-0.14.4 → hydraflow-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hydraflow
-Version: 0.14.4
+Version: 0.15.1
 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
@@ -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.14.4 → hydraflow-0.15.1}/README.md

@@ -1,22 +1,22 @@
 # 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
 
@@ -48,6 +48,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.1/docs/getting-started/concepts.md

@@ -0,0 +1,174 @@
+# Core Concepts
+
+This page introduces the fundamental concepts of HydraFlow that form the foundation of the framework.
+
+## 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. **Workflow Integration** - Creating a cohesive workflow by integrating Hydra's configuration management with MLflow's experiment tracking
+4. **Analysis Capabilities** - Providing powerful APIs for easily analyzing experiment results
+
+## Key Components
+
+HydraFlow consists of the following key components:
+
+### Configuration Management
+
+HydraFlow uses a hierarchical configuration system based on OmegaConf and Hydra. This provides:
+
+- Type-safe configuration using Python dataclasses
+- Schema validation to ensure configuration correctness
+- Configuration composition from multiple sources
+- Command-line overrides
+
+Example configuration:
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Config:
+    learning_rate: float = 0.001
+    batch_size: int = 32
+    epochs: int = 10
+```
+
+This configuration class defines the structure and default values for your experiment, enabling type checking and auto-completion.
+
+### Main Decorator
+
+The [`@hydraflow.main`][hydraflow.main] decorator defines the entry point for a HydraFlow application:
+
+```python
+import hydraflow
+from mlflow.entities import Run
+
+@hydraflow.main(Config)
+def train(run: Run, cfg: Config) -> None:
+    # Your experiment code
+    print(f"Training with lr={cfg.learning_rate}, batch_size={cfg.batch_size}")
+
+    # Log metrics
+    hydraflow.log_metric("accuracy", 0.95)
+```
+
+This decorator provides:
+
+- Automatic registration of your config class with Hydra's `ConfigStore`
+- Automatic setup of an MLflow experiment
+- Storage of Hydra configurations and logs as MLflow artifacts
+- Support for type-safe APIs and IDE integration
+
+### Workflow Automation
+
+HydraFlow allows you to automate experiment workflows using a YAML-based job definition system:
+
+```yaml
+jobs:
+  train_models:
+    run: python train.py
+    sets:
+      - each: model=small,medium,large
+        all: learning_rate=0.001,0.01,0.1
+```
+
+This enables:
+
+- Defining reusable experiment workflows
+- Efficient configuration of parameter sweeps
+- Organization of complex experiment campaigns
+
+You can also define more complex parameter spaces using extended sweep syntax:
+
+```bash
+# Ranges (start:end:step)
+python train.py -m "learning_rate=0.01:0.03:0.01"
+
+# SI prefixes
+python train.py -m "batch_size=1k,2k,4k"
+# 1000, 2000, 4000
+
+# Grid within a single parameter
+python train.py -m "model=(small,large)_(v1,v2)"
+# small_v1, small_v2, large_v1, large_v2
+```
+
+### Analysis Tools
+
+After running experiments, HydraFlow provides powerful tools for accessing and analyzing results. These tools help you track, compare, and derive insights from your experiments.
+
+#### Working with Individual Runs
+
+For individual experiment analysis, HydraFlow provides the `Run` class, which represents a single experiment run:
+
+```python
+from hydraflow import Run
+
+# Load an existing run
+run = Run.load("path/to/run")
+
+# Access configuration values
+learning_rate = run.get("learning_rate")
+```
+
+The `Run` class provides:
+
+- Access to experiment configurations used during the run
+- Methods for loading and analyzing experiment results
+- Support for custom implementations through the factory pattern
+- Type-safe access to configuration values
+
+You can use type parameters for more powerful IDE support:
+
+```python
+from dataclasses import dataclass
+from hydraflow import Run
+
+@dataclass
+class MyConfig:
+    learning_rate: float
+    batch_size: int
+
+# Load a Run with type information
+run = Run[MyConfig].load("path/to/run")
+print(run.cfg.learning_rate)  # IDE auto-completion works
+```
+
+#### Comparing Multiple Runs
+
+For comparing multiple runs, HydraFlow offers the `RunCollection` class, which enables efficient analysis across runs:
+
+```python
+# Load multiple runs
+runs = Run.load(["path/to/run1", "path/to/run2", "path/to/run3"])
+
+# Filter runs by parameter value
+filtered_runs = runs.filter(model_type="lstm")
+
+# Group runs by a parameter
+grouped_runs = runs.group_by("dataset_name")
+
+# Convert to DataFrame for analysis
+df = runs.to_frame("learning_rate", "batch_size", "accuracy")
+```
+
+Key features of experiment comparison:
+
+- Filtering runs based on configuration parameters
+- Grouping runs by common attributes
+- Aggregating data across runs
+- Converting to Polars DataFrames for advanced analysis
+
+## Summary
+
+These core concepts work together to provide a comprehensive framework for managing machine learning experiments:
+
+1. **Configuration Management** - Type-safe configuration with Python dataclasses
+2. **Main Decorator** - The entry point that integrates Hydra and MLflow
+3. **Workflow Automation** - Reusable experiment definitions and advanced parameter sweeps
+4. **Analysis Tools** - Access, filter, and analyze experiment results
+
+Understanding these fundamental concepts will help you leverage the full power of HydraFlow for your machine learning projects.

hydraflow-0.15.1/docs/getting-started/index.md

@@ -0,0 +1,80 @@
+# Getting Started with HydraFlow
+
+Welcome to HydraFlow, a framework designed to streamline machine learning
+workflows by integrating Hydra's configuration management with MLflow's
+experiment tracking capabilities.
+
+## Overview
+
+This section provides everything you need to begin using HydraFlow
+effectively:
+
+- [Installation](installation.md): Step-by-step instructions for installing
+  HydraFlow and its dependencies
+- [Core Concepts](concepts.md): An introduction to the fundamental concepts
+  that underpin HydraFlow's design and functionality
+
+## Why HydraFlow?
+
+Managing machine learning experiments involves numerous challenges, including:
+
+- **Configuration Management**: Tracking hyperparameters and settings across
+  multiple experiment runs
+- **Reproducibility**: Ensuring experiments can be reliably reproduced
+- **Result Analysis**: Efficiently comparing and analyzing experiment outcomes
+- **Workflow Automation**: Organizing and managing experiment workflows
+
+HydraFlow addresses these challenges by providing:
+
+1. **Type-safe Configuration**: Using Python's native dataclasses for
+   robust configuration management
+2. **Seamless Integration**: Bridging Hydra and MLflow to combine their
+   respective strengths
+3. **Analysis Tools**: Providing powerful APIs for filtering, grouping,
+   and analyzing results
+4. **Workflow Automation**: Simplifying the organization and execution of
+   machine learning experiments
+
+## Quick Example
+
+Here's a simple example to demonstrate HydraFlow's basic usage:
+
+```python
+from dataclasses import dataclass
+from mlflow.entities import Run
+import hydraflow
+
+@dataclass
+class Config:
+    learning_rate: float = 0.01
+    batch_size: int = 32
+    epochs: int = 10
+
+@hydraflow.main(Config)
+def train(run: Run, cfg: Config) -> None:
+    # Your training code here
+    print(f"Training with lr={cfg.learning_rate}, batch_size={cfg.batch_size}")
+
+    # Log metrics
+    hydraflow.log_metric("accuracy", 0.95)
+
+if __name__ == "__main__":
+    train()
+```
+
+Run this example with:
+
+```bash
+python train.py learning_rate=0.001 batch_size=64
+```
+
+## Next Steps
+
+After installing HydraFlow and understanding its core concepts, you're ready to:
+
+1. Follow our [Practical Tutorials](../practical-tutorials/index.md) to see HydraFlow in action
+2. Explore the detailed [User Guide](../part1-applications/index.md) to learn more about HydraFlow's capabilities
+3. Check the [API Reference](../api/hydraflow/README.md) for detailed documentation of HydraFlow's API
+
+Continue to the [Installation Guide](installation.md) to get started with
+HydraFlow.

hydraflow-0.15.1/docs/getting-started/installation.md

@@ -0,0 +1,83 @@
+# Installation
+
+This guide walks you through installing HydraFlow and its dependencies.
+
+## Requirements
+
+HydraFlow requires:
+
+- Python 3.13 or higher
+- A package manager (pip or uv)
+
+## Basic Installation
+
+You can install HydraFlow using your preferred package manager:
+
+### Using pip
+
+```bash
+pip install hydraflow
+```
+
+### Using uv
+
+[uv](https://github.com/astral-sh/uv) is a modern, fast Python package manager:
+
+```bash
+uv pip install hydraflow
+```
+
+These commands install the core framework with minimal dependencies.
+
+## Verifying Installation
+
+After installation, verify that HydraFlow is correctly installed by running
+the CLI command:
+
+```bash
+hydraflow --help
+```
+
+This should display the help message and available commands, confirming that
+HydraFlow is properly installed and accessible from your terminal.
+
+## Environment Setup
+
+While not required, we recommend using a virtual environment:
+
+### Using venv
+
+```bash
+python -m venv hydraflow-env
+source hydraflow-env/bin/activate  # On Windows: hydraflow-env\Scripts\activate
+pip install hydraflow  # or use uv pip
+```
+
+### Using uv
+
+```bash
+uv venv hydraflow-env
+source hydraflow-env/bin/activate  # On Windows: hydraflow-env\Scripts\activate
+uv pip install hydraflow
+```
+
+## Troubleshooting
+
+If you encounter issues during installation:
+
+1. Ensure your Python version is 3.13 or higher
+2. Update your package manager:
+   - For pip: `pip install --upgrade pip`
+   - For uv: `uv self update`
+3. If installing from source, ensure you have the necessary build tools
+   installed for your platform
+
+For persistent issues, please check the
+[GitHub issues](https://github.com/daizutabi/hydraflow/issues) or open a
+new issue with details about your environment and the error message.
+
+## Next Steps
+
+Now that you have installed HydraFlow, proceed to
+[Core Concepts](concepts.md) to understand the framework's fundamental
+principles.

hydraflow-0.15.1/docs/index.md

@@ -0,0 +1,91 @@
+# HydraFlow: Streamline ML Experiment Workflows
+
+<div class="grid cards" markdown>
+
+- 🚀 **Define and Run Experiments**
+  Combine Hydra's configuration management with MLflow's experiment
+  tracking for streamlined experiment workflows
+- 🔄 **Automate Workflows**
+  Define reusable experiment workflows with YAML configuration and
+  leverage extended sweep syntax for parameter exploration
+- 📊 **Collect and Analyze Results**
+  Gather, filter, and analyze experiment results with type-safe APIs
+  for comprehensive insights
+
+</div>
+
+## What is HydraFlow?
+
+HydraFlow seamlessly integrates [Hydra](https://hydra.cc/) and
+[MLflow](https://mlflow.org/) to create a comprehensive machine learning
+experiment management framework. It provides a complete workflow from defining
+experiments to execution and analysis, streamlining machine learning projects
+from research to production.
+
+### Key Integration Features
+
+- **Automatic Configuration Tracking**: Hydra configurations are automatically
+  saved as MLflow artifacts, ensuring complete reproducibility of experiments
+- **Type-safe Configuration**: Leverage Python dataclasses for type-safe
+  experiment configuration with full IDE support
+- **Unified Workflow**: Connect configuration management and experiment tracking
+  in a single, coherent workflow
+- **Powerful Analysis Tools**: Analyze and compare experiments using
+  configuration parameters captured from Hydra
+
+### Hydra + MLflow = More Than the Sum of Parts
+
+HydraFlow goes beyond simply using Hydra and MLflow side by side:
+
+- **Parameter Sweep Integration**: Run Hydra multi-run sweeps with automatic
+  MLflow experiment organization
+- **Configuration-Aware Analysis**: Filter and group experiment results using
+  Hydra configuration parameters
+- **Reproducible Experiments**: Ensure experiments can be reliably reproduced
+  with configuration-based definitions
+- **Implementation Support**: Extend experiment analysis with custom
+  domain-specific implementations
+
+## Quick Installation
+
+```bash
+pip install hydraflow
+```
+
+**Requirements:** Python 3.13+
+
+## Documentation Structure
+
+The HydraFlow documentation is organized as follows:
+
+<div class="grid cards" markdown>
+
+- :material-book-open-variant: [**Getting Started**](getting-started/index.md)
+  Install HydraFlow and learn core concepts
+- :material-school: [**Practical Tutorials**](practical-tutorials/index.md)
+  Learn through hands-on examples and real use cases
+- :material-rocket-launch: [**Part 1: Running Applications**](part1-applications/index.md)
+  Define and execute HydraFlow applications
+- :material-cogs: [**Part 2: Automating Workflows**](part2-advanced/index.md)
+  Build advanced experiment workflows
+- :material-magnify: [**Part 3: Analyzing Results**](part3-analysis/index.md)
+  Collect and analyze experiment results
+- :material-code-tags: [**API Reference**](api/hydraflow/README.md)
+  Detailed documentation of classes and methods
+
+</div>
+
+## Getting Started
+
+Begin your journey with HydraFlow through our introductory guides:
+
+<div class="grid cards" markdown>
+
+- :material-book-open-variant: [**Installation Guide**](getting-started/installation.md)
+  Install and set up HydraFlow
+- :material-school: [**Core Concepts**](getting-started/concepts.md)
+  Learn the key concepts and design principles of HydraFlow
+- :material-file-code: [**Practical Tutorials**](practical-tutorials/index.md)
+  Hands-on examples to understand HydraFlow in practice
+
+</div>

hydraflow-0.15.1/docs/part1-applications/configuration.md

@@ -0,0 +1,126 @@
+# Configuration Management
+
+HydraFlow uses a powerful configuration management system based on Python's
+dataclasses and Hydra's composition capabilities. This approach provides
+type safety, IDE auto-completion, and flexible parameter specification.
+
+## Basic Configuration
+
+The simplest way to define a configuration for a HydraFlow application is
+using a Python dataclass:
+
+```python
+from dataclasses import dataclass
+from mlflow.entities import Run
+import hydraflow
+
+@dataclass
+class Config:
+    learning_rate: float = 0.01
+    batch_size: int = 32
+    epochs: int = 10
+    model_name: str = "transformer"
+
+@hydraflow.main(Config)
+def train(run: Run, cfg: Config) -> None:
+    # Access configuration parameters
+    print(f"Training {cfg.model_name} for {cfg.epochs} epochs")
+    print(f"Learning rate: {cfg.learning_rate}, Batch size: {cfg.batch_size}")
+```
+
+## Type Hints
+
+Adding type hints to your configuration class provides several benefits:
+
+1. **Static Type Checking**: Tools like mypy can catch configuration errors
+   before runtime.
+2. **IDE Auto-completion**: Your IDE can provide suggestions as you work with
+   configuration objects.
+3. **Documentation**: Type hints serve as implicit documentation for your
+   configuration parameters.
+
+## Nested Configurations
+
+For more complex applications, you can use nested dataclasses to organize
+related parameters:
+
+```python
+@dataclass
+class ModelConfig:
+    name: str = "transformer"
+    hidden_size: int = 512
+    num_layers: int = 6
+    dropout: float = 0.1
+
+@dataclass
+class OptimizerConfig:
+    name: str = "adam"
+    learning_rate: float = 0.001
+    weight_decay: float = 0.0
+
+@dataclass
+class DataConfig:
+    batch_size: int = 32
+    num_workers: int = 4
+    train_path: str = "data/train"
+    val_path: str = "data/val"
+
+@dataclass
+class Config:
+    model: ModelConfig = ModelConfig()
+    optimizer: OptimizerConfig = OptimizerConfig()
+    data: DataConfig = DataConfig()
+    seed: int = 42
+    max_epochs: int = 10
+
+@hydraflow.main(Config)
+def train(run: Run, cfg: Config) -> None:
+    # Access nested configuration
+    model_name = cfg.model.name
+    lr = cfg.optimizer.learning_rate
+    batch_size = cfg.data.batch_size
+```
+
+## Hydra Integration
+
+HydraFlow integrates closely with Hydra for configuration management. For detailed explanations of Hydra's capabilities, please refer to the [Hydra documentation](https://hydra.cc/docs/intro/).
+
+HydraFlow leverages the following Hydra features, but does not modify their behavior:
+
+- **Configuration Files**: Organize configurations in YAML files
+- **Command-line Overrides**: Change parameters without modifying code
+- **Configuration Groups**: Swap entire configuration blocks
+- **Configuration Composition**: Combine configurations from multiple sources
+- **Interpolation**: Reference other configuration values
+- **Multi-run Sweeps**: Run experiments with different parameter combinations
+
+When using HydraFlow, remember that:
+
+1. Your configuration structure comes from your dataclass definitions
+2. HydraFlow automatically registers your top-level dataclass with Hydra
+3. `@hydraflow.main` sets up the connection between your dataclass and Hydra
+
+For advanced Hydra features and detailed usage examples, we recommend consulting the official Hydra documentation after you become familiar with the basic HydraFlow concepts.
+
+## Best Practices
+
+1. **Use Type Hints**: Always include type hints for all configuration parameters.
+
+2. **Set Sensible Defaults**: Provide reasonable default values to make your
+   application usable with minimal configuration.
+
+3. **Group Related Parameters**: Use nested dataclasses to organize related
+   parameters logically.
+
+4. **Document Parameters**: Add docstrings to your dataclasses and parameters
+   to explain their purpose and valid values.
+
+5. **Validate Configurations**: Add validation logic to catch invalid
+   configurations early.
+
+## Summary
+
+HydraFlow's configuration system combines the type safety of Python dataclasses
+with the flexibility of Hydra's composition and override capabilities. This
+approach makes your machine learning experiments more maintainable,
+reproducible, and easier to debug.