🚀Defining of A Config Function

A Hypster configuration function is a regular Python function. It receives hp: HP as its first parameter and returns whatever your code needs (a dict, an object, etc.).

1

Imports

from hypster import HP, instantiate

This makes sure you have the HP class for the first parameter and instantiate(...) to execute your config.

2

Signature

def my_config(hp: HP):
    ...

• The first parameter must be named hp and typed as HP for IDE autocomplete and validation.

• You can add more parameters (e.g., knobs) as long as hp is first: def my_config(hp: HP, *, env: str = "dev").

3

Body

Define parameters using hp.* and return the values you need. Use normal Python control flow for conditionals.

from hypster import HP


def model_cfg(hp: HP):
    # Categorical choice (list form)
    model_name = hp.select(["gpt-5", "claude-sonnet-4-0", "gemini-2.5-flash"], name="model_name")

    # Numeric parameters
    temperature = hp.float(0.2, name="temperature", min=0.0, max=1.0)
    max_tokens = hp.int(256, name="max_tokens", min=0, max=4096)

    # Conditional logic
    if model_name == "gpt-5":
        # Extra knob only for gpt-5
        top_p = hp.float(1.0, name="top_p", min=0.1, max=1.0)
        return {"model_name": model_name, "temperature": temperature, "max_tokens": max_tokens, "top_p": top_p}

    return {"model_name": model_name, "temperature": temperature, "max_tokens": max_tokens}

Hypster comes with the following HP calls:

• hp.select() and hp.multi_select() for categorical choices

• hp.int() and hp.multi_int() for integer values

• hp.float() and hp.multi_float() for numeric values

• hp.text() and hp.multi_text() for string values

• hp.bool() and hp.multi_bool() for boolean values

• hp.nest() for nested configurations

Import libraries you need inside the function body when portability matters (so the config can be executed in isolation).

Return exactly what your downstream code needs. You can also gather outputs from locals using hp.collect(locals(), include=[...]).

4

Instantiation

Execute your configuration and override parameters using values=. See "Values & Overrides" for dotted vs nested overrides and precedence.

from hypster import instantiate

cfg = instantiate(
    model_cfg,
    values={
        "model_name": "gpt-5",
        "temperature": 0.5,
        "max_tokens": 1024,
    },
)
# cfg -> {"model_name": "gpt-5", "temperature": 0.5, "max_tokens": 1024}

Control unknown or unreachable values via on_unknown: "warn" (default), "raise", or "ignore".