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.
1 maintainer
Release files for hypster 0.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hypster-0.9.1.tar.gz | 44.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hypster-0.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 88.5 kB
Release files / hypster-0.9.1.tar.gz
| Download URL | hypster-0.9.1.tar.gz |
|---|---|
| Size | 44.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6796c27e42db21cb72d7889695070db95bf76bfeece9d90382056bc72ed8897f
|
|
BLAKE2b-256 checksum How to use checksums |
d894d62a292428eeeda07a3d212240758784e5e43a54496ae4a75e8bcd49e190
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 16, 2026.
Transparency logRelease files / hypster-0.9.1-py3-none-any.whl
| Download URL | hypster-0.9.1-py3-none-any.whl |
|---|---|
| Size | 44.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f7e280f2e0bc0527af6b0f396684eb1d1ecc642067864d97f4e7944f90ccd422
|
|
BLAKE2b-256 checksum How to use checksums |
fef229895aa29239e581b5986bf9e0749271ffc216d3e91b2c284dcf40fbc212
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 16, 2026.
Transparency log
