How to Use Boolean Parameters (`hp.bool()`) in Hypster Configurations

Use hp.bool(default, name="param") to declare type-safe boolean flags that accept runtime overrides via dictionaries or dotted key paths.

Hypster treats every configuration value as a validated parameter resolved at call-time. In the gilad-rubin/hypster repository, the hp.bool() method provides a dedicated interface for boolean flags, enforcing strict type validation while supporting flexible override mechanisms for CLI inputs and nested configurations.

Declaring Boolean Parameters

Boolean parameters are instantiated through the HP._bool method, which is exposed publicly as hp.bool(). According to the source code in src/hypster/hp.py (lines 499–509), this constructor builds a SingleValueSpec containing the default value, the required parameter name, and a BoolValidator instance. It also registers the parameter as “called” to prevent duplicate definitions within the same configuration tree.

# config.py

def model_config(hp):
    # Declare a boolean flag with default True

    use_dropout = hp.bool(True, name="use_dropout")
    # The flag can now be used in the configuration logic

    dropout_rate = 0.5 if use_dropout else 0.0
    return {"dropout": dropout_rate}

The name argument is mandatory for overrides; omitting it triggers a validation error during execution.

Internal Validation Architecture

Parameter Specification in HP._bool

When hp.bool() is invoked, it delegates to HP._bool in src/hypster/hp.py. This internal method constructs the parameter specification and forwards it to the execution engine. The specification encapsulates the default boolean value and binds it to the BoolValidator class for later verification.

Runtime Type Validation via BoolValidator

The concrete validation logic resides in BoolValidator, defined in src/hypster/hp_calls.py (lines 97–104). At runtime, this validator checks that any supplied override is an instance of bool. If a user passes a non-boolean value such as "yes" or 1, the validator raises an HPCallError with the message:

Parameter 'use_dropout': expected boolean but got str (yes)

Value Resolution and Execution Pipeline

The execution flow is handled by _execute_single and _handle_single_value in src/hypster/hp.py (lines 23–52). This pipeline performs four critical steps:

1. Name validation – Ensures the name parameter was provided; otherwise raises:
   Parameter 'my_flag': requires 'name' for overrides. Example: hp.bool(True, name='my_flag')
2. Duplicate-call protection – Validates that the same fully-qualified path has not been defined earlier in the configuration tree.
3. Value lookup – Searches for overrides using exact keys, dotted names (e.g., "model.use_dropout"), or nested dictionary traversal.
4. Type coercion – Applies BoolValidator.validate_value to the resolved input, returning a plain Python bool or the default if no override exists.

Runtime Overrides and Nested Configurations

Boolean parameters support overrides via flat dictionaries or dotted-key notation for nested configs. When using hp.nest(), child configuration parameters are automatically prefixed with the parent's name.

# Overriding via a dict (e.g. from CLI or YAML)

values = {"use_dropout": False}
hp = HP(values)               # HP instance created by Hypster's instantiate()

cfg = model_config(hp)        # cfg == {"dropout": 0.0}

For nested structures, supply dotted keys that match the nested namespace:

# Nested configuration with a prefix

def trainer_config(hp):
    # Nest another config under the "model" namespace

    model_cfg = hp.nest(model_config, name="model")
    # Boolean flag can also be nested:

    # values = {"model.use_dropout": True}

    return {"model": model_cfg}

Error Handling and Constraints

Hypster enforces strict contracts for boolean parameters. The two most common validation failures are missing names and type mismatches:

# Triggering validation errors

values = {"use_dropout": "yes"}          # invalid type

HP(values)                               # raises HPCallError:

# Parameter 'use_dropout': expected boolean but got str (yes)

Attempting to define the same parameter name twice within a single configuration execution triggers a duplicate-call error from _validate_name_not_called, preventing silent overwrites.

Summary

• Use hp.bool(default, name="...") to declare validated boolean flags in gilad-rubin/hypster configurations.
• Source locations: HP._bool logic is in src/hypster/hp.py; validation is in src/hypster/hp_calls.py.
• Name requirement: The name parameter is mandatory for runtime overrides; omission raises a clear configuration error.
• Type safety: BoolValidator strictly enforces isinstance(value, bool), rejecting strings, integers, or other truthy values.
• Override paths: Support flat dictionary keys or dotted notation (e.g., "model.use_dropout") for nested configuration hierarchies.

Frequently Asked Questions

What happens if I omit the name parameter in hp.bool()?

Omitting the name parameter causes Hypster to raise an HPCallError during execution with the message: Parameter 'my_flag': requires 'name' for overrides. Example: hp.bool(True, name='my_flag'). This ensures every boolean parameter can be uniquely identified for runtime overrides.

Can I override boolean parameters using nested dictionary keys?

Yes. When using hp.nest(), you can override nested boolean parameters using dotted key notation such as "model.use_dropout": True. The execution pipeline in src/hypster/hp.py (lines 23–52) resolves these dotted paths by walking the nested dictionary structure or matching fully-qualified keys.

How does Hypster handle non-boolean values passed to a boolean parameter?

If a non-boolean value (e.g., "yes", 1, or None) is supplied, the BoolValidator in src/hypster/hp_calls.py raises an HPCallError stating: Parameter 'param_name': expected boolean but got <type> (<value>). This strict validation prevents implicit type coercion and ensures configuration integrity.

Are boolean parameters validated during configuration definition or at runtime?

Validation occurs at runtime when the configuration function is called with an HP instance. The hp.bool() call only registers the parameter specification; the BoolValidator checks the actual value against the isinstance(value, bool) contract during the execution phase managed by _handle_single_value.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}