optional HPO backend

Hypster is a lightweight configuration framework for managing and optimizing AI & ML workflows

Key Features

• 🐍 Pythonic API: Intuitive & minimal syntax that feels natural to Python developers
• 🪆 Hierarchical, Conditional Configurations: Support for nested and swappable configurations
• 📐 Type Safety: Built-in type hints and validation
• 🧪 Hyperparameter Optimization Built-In: Native, first-class optuna support

Installation

uv add hypster
# optional notebook visualization UI
uv add 'hypster[viz]'
# optional HPO backend
uv add 'hypster[optuna]'

See the installation guide for pip, optional extras, and development setup.

Quick Start

Define a configuration function and instantiate it with overrides:

from hypster import HP, explore, instantiate
from my_app.llms import LLMClient


def llm_config(hp: HP) -> LLMClient:
    model_name = hp.select(["gpt-5.5", "gpt-5.5-mini"], name="model_name")
    temperature = hp.float(0.7, name="temperature", min=0.0, max=1.0)
    max_tokens = hp.int(256, name="max_tokens", min=1, max=4096)

    return LLMClient(
        model_name=model_name,
        temperature=temperature,
        max_tokens=max_tokens,
    )

explore(llm_config)
# llm_config
# ├── model_name: select = "gpt-5.5"  (options: ["gpt-5.5", "gpt-5.5-mini"])
# ├── temperature: float = 0.7  (0.0-1.0)
# └── max_tokens: int = 256  (1-4096)

llm = instantiate(
    llm_config,
    values={"model_name": "gpt-5.5", "temperature": 0.2},
)

response = llm.invoke("How's your day going?")

Use explore(..., values=...) to inspect a specific conditional branch before you instantiate it, or explore(..., return_schema=True) to get a JSON-serializable schema object.

AI-readable docs

GitBook publishes an agent-friendly docs index at llms.txt and a full Markdown export at llms-full.txt.

HPO with Optuna

import optuna
from hypster import HP, instantiate
from hypster.hpo.optuna import suggest_values
from hypster.hpo.types import HpoFloat, HpoInt
from sklearn.base import ClassifierMixin
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression


def logistic_config(hp: HP) -> LogisticRegression:
    C = hp.float(1.0, name="C", min=1e-4, max=10.0, hpo_spec=HpoFloat(scale="log"))
    return LogisticRegression(C=C, max_iter=1000)


def forest_config(hp: HP) -> RandomForestClassifier:
    n_estimators = hp.int(
        200,
        name="n_estimators",
        min=50,
        max=1000,
        hpo_spec=HpoInt(step=50),
    )
    return RandomForestClassifier(n_estimators=n_estimators, random_state=42)


model_options = {"logistic": logistic_config, "forest": forest_config}


def model_cfg(hp: HP) -> ClassifierMixin:
    model_config = hp.select(model_options, name="model_family", default="forest", options_only=True)
    return hp.nest(model_config, name="model")


def objective(trial: optuna.Trial) -> float:
    values = suggest_values(trial, model_cfg)
    model = instantiate(model_cfg, values=values)
    return train_and_score(model)

study = optuna.create_study(direction="maximize")
study.optimize(objective, n_trials=30)

Inspiration

Hypster draws inspiration from Meta's hydra and hydra-zen framework. The API design is influenced by Optuna's "define-by-run" API.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.