> For the complete documentation index, see [llms.txt](https://gilad-rubin.gitbook.io/hypster/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gilad-rubin.gitbook.io/hypster/in-depth/hp-call-types.md).

# HP Call Types

`HP` methods define the public parameters in a config function. Each call records a parameter path, validates overrides, and can be explored or replayed.

The examples in this reference sometimes return small dictionaries to keep the call behavior visible. In application code, prefer returning the initialized runtime object unless the mapping itself is the object your caller needs.

## Scalar Calls

| Call        | Use for                          | Notes                                                                                                  |
| ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `hp.int`    | Integer parameters               | Accepts integral floats by default, optional bounds, optional strict mode, optional `allow_none=True`. |
| `hp.float`  | Floating-point parameters        | Accepts integer values by default, optional bounds, optional strict mode, optional `allow_none=True`.  |
| `hp.text`   | Strings                          | Use for prompts, paths, IDs, and labels.                                                               |
| `hp.bool`   | Booleans                         | Requires actual `True` or `False`, not string values.                                                  |
| `hp.select` | One categorical choice           | Supports list options or dict-backed key-to-value mapping.                                             |
| `hp.rules`  | Declarative WHEN/THEN rule lists | Returns `Rule` objects and records JSON-friendly rule dictionaries for replay.                         |
| `hp.schema` | Typed field-definition lists     | Returns `SchemaField` objects; see [Schema](/hypster/in-depth/hp-call-types/schema.md).                |

## Multi-Value Calls

| Call              | Use for                     | Notes                                                                       |
| ----------------- | --------------------------- | --------------------------------------------------------------------------- |
| `hp.multi_int`    | List of integers            | Elements use the same safe coercion and strict-mode behavior as `hp.int`.   |
| `hp.multi_float`  | List of floats              | Elements use the same safe coercion and strict-mode behavior as `hp.float`. |
| `hp.multi_text`   | List of strings             | Useful for columns, tags, stop sequences, and feature names.                |
| `hp.multi_bool`   | List of booleans            | Useful when each position has meaning.                                      |
| `hp.multi_select` | List of categorical choices | Supports nullable choices with `allow_none=True`.                           |

Nullable elements are not supported for `multi_int`, `multi_float`, `multi_text`, or `multi_bool`. Use `multi_select(..., allow_none=True)` for nullable categorical lists.

## Composition Calls

| Call         | Use for                                                      |
| ------------ | ------------------------------------------------------------ |
| `hp.nest`    | Run another config function under a named scope.             |
| `hp.collect` | Collect selected local variables into a returned dictionary. |

For `hp.rules`, declare condition and payload fields with `hypster.field` and use [Rules](/hypster/in-depth/hp-call-types/rules.md) for the full pattern.

## Shared Rules

* `name=` is required for every `hp.*` parameter call.
* Names must be valid Python identifiers and cannot contain dots, spaces, or hyphens.
* `values=` may use dotted paths such as `optimizer.learning_rate`.
* Unknown or unreachable values raise by default.
* Dict-backed `select` is the right way to return complex objects while logging simple keys.
* Numeric parameters reject `True` and `False` even though Python treats `bool` as a subclass of `int`.

See [Public API](/hypster/reference/api.md) for exact signatures.

## Custom Metadata On A Basic Parameter

Every basic `hp.*` call accepts `metadata={...}` for opaque, JSON-compatible hints. `explore(..., return_schema=True)` carries them straight to that parameter's schema node, unread and unvalidated beyond JSON-compatibility:

{% code overflow="wrap" %}

```python
from hypster import HP, explore

def app_config(hp: HP) -> dict:
    tier = hp.select(
        ["basic", "advanced"],
        name="tier",
        default="basic",
        metadata={"ui_group": "advanced", "help_url": "https://example.com/docs/tier"},
    )
    return {"tier": tier}

schema = explore(app_config, return_schema=True)
param = schema.to_dict()["parameters"][0]

assert param["metadata"] == {"ui_group": "advanced", "help_url": "https://example.com/docs/tier"}
```

{% endcode %}

This is the same `metadata=` mechanism `hp.nest(..., metadata=...)` uses for a nested group's schema node — see [Nested Configurations](/hypster/in-depth/nest.md) for the group-level form.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gilad-rubin.gitbook.io/hypster/in-depth/hp-call-types.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.