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

> Learn to use hp.bool() for type-safe boolean flags in Hypster configurations. Easily declare and override boolean parameters with runtime dictionaries or key paths for flexible control.

- Repository: [Gilad Rubin/hypster](https://github.com/gilad-rubin/hypster)
- Tags: how-to-guide
- Published: 2026-03-02

---

**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`](https://github.com/gilad-rubin/hypster/blob/main/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.

```python

# 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`](https://github.com/gilad-rubin/hypster/blob/main/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`](https://github.com/gilad-rubin/hypster/blob/main/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`](https://github.com/gilad-rubin/hypster/blob/main/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.

```python

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

```python

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

```python

# 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`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp.py#L499-L509); validation is in [`src/hypster/hp_calls.py`](https://github.com/gilad-rubin/hypster/blob/main/src/hypster/hp_calls.py#L97-L104).
- **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`](https://github.com/gilad-rubin/hypster/blob/main/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`](https://github.com/gilad-rubin/hypster/blob/main/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`.