🚀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:

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".

Last updated

Was this helpful?