Hypster Logo

chat with our AI docs

CI codecov PyPI version Python versions DeepWiki License: MIT CodSpeed

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
  • 🧩 Rules As Config: Define replayable WHEN/THEN rule lists with built-in notebook controls

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.

Project links

Data verified by PyPI on Jul 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for gilad_rubin from gravatar.com gilad_rubin

Credits

Author: Gilad Rubin

GitHub Statistics

Data verified by PyPI on Jul 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Provides Extra

optuna viz

Tags

ai configuration machine-learning

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hypster-0.9.1.tar.gz (44.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

hypster-0.9.1-py3-none-any.whl (44.1 kB view details)

Uploaded Python 3

File details

Details for the file hypster-0.9.1.tar.gz.

File metadata

  • Download URL: hypster-0.9.1.tar.gz
  • Upload date:
  • Size: 44.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for hypster-0.9.1.tar.gz
Algorithm Hash digest
SHA256 6796c27e42db21cb72d7889695070db95bf76bfeece9d90382056bc72ed8897f
MD5 d5abd34a7555b70625061a4bbc0cd724
BLAKE2b-256 d894d62a292428eeeda07a3d212240758784e5e43a54496ae4a75e8bcd49e190

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypster-0.9.1.tar.gz:

Publisher: release.yml on gilad-rubin/hypster

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hypster-0.9.1-py3-none-any.whl.

File metadata

  • Download URL: hypster-0.9.1-py3-none-any.whl
  • Upload date:
  • Size: 44.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for hypster-0.9.1-py3-none-any.whl
Algorithm Hash digest
SHA256 f7e280f2e0bc0527af6b0f396684eb1d1ecc642067864d97f4e7944f90ccd422
MD5 e6489219877709f10881fd8b398a5910
BLAKE2b-256 fef229895aa29239e581b5986bf9e0749271ffc216d3e91b2c284dcf40fbc212

See more details on using hashes here.

Provenance

The following attestation bundles were made for hypster-0.9.1-py3-none-any.whl:

Publisher: release.yml on gilad-rubin/hypster

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.9.1 This release

2 files

0.9.0

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.3

2 files

0.5.2

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.2

2 files

0.2.34

2 files

0.2.33

2 files

0.2.32

2 files

0.2.31

2 files

0.2.30

2 files

0.2.29

2 files

0.2.28

2 files

0.2.27

2 files

0.2.26

2 files

0.2.25

2 files

0.2.24

2 files

0.2.23

2 files

0.2.22

2 files

0.2.21

2 files

0.2.20

2 files

0.2.19

2 files

0.2.18

2 files

0.2.17

2 files

0.2.16

2 files

0.2.15

2 files

0.2.14

2 files

0.2.13

2 files

0.2.12

2 files

0.2.11

2 files

0.2.10

2 files

0.2.9

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.14

2 files

0.1.13

2 files

0.1.12

2 files

0.1.11

2 files

0.1.10

2 files

Pre-release

0.1.10a0

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

Pre-release

0.0.1a0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page