Metadata-Version: 2.4
Name: evo-hp
Version: 0.1.0
Summary: Evolutionary Hyperparameter Optimizer — a scikit-learn-compatible hyperparameter tuner that evolves mixed (int/float/log-scale/categorical/conditional) search spaces with a Genetic Algorithm (evo-suite)
Author: Axel Skrauba
License: MIT
Project-URL: Homepage, https://github.com/AxelSkrauba/evo-suite
Project-URL: Documentation, https://evo-suite.readthedocs.io/
Project-URL: Repository, https://github.com/AxelSkrauba/evo-suite
Project-URL: Changelog, https://github.com/AxelSkrauba/evo-suite/blob/main/packages/evo-hp/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/AxelSkrauba/evo-suite/issues
Keywords: hyperparameter optimization,genetic algorithm,DEAP,machine learning,scikit-learn,evolutionary computation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5
Requires-Dist: scikit-learn>=1.6
Requires-Dist: deap>=1.4
Requires-Dist: scipy>=1.9
Provides-Extra: viz
Requires-Dist: matplotlib>=3.6; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: matplotlib>=3.6; extra == "dev"

# evo-hp - Evolutionary Hyperparameter Optimizer

[![PyPI](https://img.shields.io/pypi/v/evo-hp.svg)](https://pypi.org/project/evo-hp/)
[![Python versions](https://img.shields.io/pypi/pyversions/evo-hp.svg)](https://pypi.org/project/evo-hp/)
[![Docs](https://readthedocs.org/projects/evo-suite/badge/?version=latest)](https://evo-suite.readthedocs.io/en/latest/)
[![CI](https://github.com/AxelSkrauba/evo-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/AxelSkrauba/evo-suite/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)

A **scikit-learn-compatible** hyperparameter optimizer for tabular data,
powered by [DEAP](https://github.com/DEAP/deap). `evo-hp` tunes the
hyperparameters of any scikit-learn estimator with a Genetic Algorithm over
mixed search spaces (integers, floats, log-scale, categoricals, booleans and
conditional parameters), complementing [`evo-gafs`](../evo-gafs) (feature
selection) and [`evo-gpfe`](../evo-gpfe) (feature engineering) upstream, and
[`evo-ens`](../evo-ens) (ensemble construction) downstream.

Part of the [`evo-suite`](../../README.md) family (import name: `evo_hp`).
Documentation: <https://evo-suite.readthedocs.io/>

## Why evo-hp?

| Capability | evo-hp |
|------------|--------|
| **Mixed search spaces natively**: int, float (linear/log-scale), categorical, boolean, conditional | Yes |
| **Uniform `[0, 1]^n` gene representation**: standard DEAP operators (`cxUniform`, `mutGaussian`) across every type | Yes |
| **Evaluation cache** keyed on decoded hyperparameters — population convergence becomes cheap cache hits | Yes |
| Native scikit-learn `EvoHPClassifier` / `EvoHPRegressor`, usable in a `Pipeline` and tunable with `GridSearchCV` | Yes |
| **Multi-objective NSGA-II** mode exposing the full score/complexity Pareto front | Yes |
| 13 built-in predefined search spaces (RandomForest, GradientBoosting, SVC/SVR, LogisticRegression, Ridge, Lasso, ElasticNet, KNN, DecisionTree) | Yes |
| Built-in multi-estimator `EvoHPBenchmarkRunner` | Yes |

## Installation

```bash
pip install evo-hp            # core
pip install "evo-hp[viz]"     # + matplotlib for the plotting helpers
```

## Quickstart

```python
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from evo_hp import EvoHPClassifier, EvoHPConfig

X, y = load_breast_cancer(return_X_y=True, as_frame=True)

clf = EvoHPClassifier(
    estimator=RandomForestClassifier(random_state=42),
    param_space="rf_clf",
    config=EvoHPConfig(population_size=40, n_generations=30, verbose=False),
)
clf.fit(X, y)

print(clf.result_.summary())
print(clf.best_params_)
```

`EvoHPRegressor` follows the same API for regression targets, scoring
with R² by default. Define a custom search space with `Int`/`Float`/`Cat`/
`Bool`/`Cond` instead of a predefined name for full control:

```python
from sklearn.svm import SVC
from evo_hp import EvoHPClassifier, Float, Cat, Cond, Int

space = [
    Float("C", 0.001, 1000.0, log=True),
    Cat("kernel", ["rbf", "linear", "poly", "sigmoid"]),
    Float("gamma", 1e-5, 10.0, log=True),
    Cond("degree", Int("degree", 2, 5), "kernel", ["poly"], default=3),
]
clf = EvoHPClassifier(estimator=SVC(max_iter=10_000), param_space=space)
```

Since `evo-hp` does not transform `X`, it slots in naturally as the *final*
step of a `Pipeline` — including right after `evo-gafs`'s feature selector,
mirroring the suite's intended pipeline position
(`evoimp -> gpfe -> gafs -> evohp -> evoens`):

```python
from sklearn.pipeline import Pipeline
from evo_gafs import GAFeatureSelector
from evo_hp import EvoHPClassifier

pipe = Pipeline([
    ("select", GAFeatureSelector(estimator=RandomForestClassifier(random_state=42))),
    ("tune", EvoHPClassifier(estimator=RandomForestClassifier(random_state=42), param_space="rf_clf")),
])
pipe.fit(X, y)
```

## Documentation & examples

- **Full documentation** (user guide + API reference): <https://evo-suite.readthedocs.io/>
- **Runnable examples**: the repository's [`examples/evo-hp/`](../../examples/evo-hp) directory.

## Citation

```bibtex
@software{evo_hp,
  author    = {Skrauba, Axel},
  title     = {evo-hp: Evolutionary Hyperparameter Optimizer for tabular data},
  year      = {2026},
  version   = {0.1.0},
  url       = {https://github.com/AxelSkrauba/evo-suite}
}
```

## License

[MIT](../../LICENSE)
