> 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/how-to-guides/compose-nested-configs.md).

# Compose Nested Configs

Use this guide when one workflow should be assembled from reusable smaller config functions.

## Start With Child Configs

{% code overflow="wrap" %}

```python
from hypster import HP, explore, instantiate
from my_app.embeddings import BpeTokenizer, EmbeddingPipeline, Encoder, Tokenizer, WordPieceTokenizer

tokenizer_options = {
    "wordpiece": WordPieceTokenizer,
    "bpe": BpeTokenizer,
}

def tokenizer_config(hp: HP) -> Tokenizer:
    tokenizer_cls = hp.select(tokenizer_options, name="kind", default="bpe", options_only=True)
    lowercase = hp.bool(True, name="lowercase")
    return tokenizer_cls(lowercase=lowercase)

def encoder_config(hp: HP) -> Encoder:
    size = hp.select(["small", "base"], name="size", default="small", options_only=True)
    hidden_size = 384 if size == "small" else 768
    return Encoder(size=size, hidden_size=hidden_size)
```

{% endcode %}

Use this named-options shape when a parent config chooses between swappable children. The dictionary provides the stable keys Hypster logs, while the values can be classes, callables, or full child config functions.

## Nest Them In A Parent

{% code overflow="wrap" %}

```python
def embedding_pipeline(hp: HP) -> EmbeddingPipeline:
    tokenizer = hp.nest(tokenizer_config, name="tokenizer")
    encoder = hp.nest(encoder_config, name="encoder")
    normalize = hp.bool(True, name="normalize")
    return EmbeddingPipeline(tokenizer=tokenizer, encoder=encoder, normalize=normalize)
```

{% endcode %}

## Override Nested Values

{% code overflow="wrap" %}

```python
cfg = instantiate(
    embedding_pipeline,
    values={
        "tokenizer.kind": "wordpiece",
        "encoder.size": "base",
        "normalize": False,
    },
)

assert cfg.encoder.hidden_size == 768
```

{% endcode %}

Nested dictionaries are equivalent:

{% code overflow="wrap" %}

```python
cfg = instantiate(
    embedding_pipeline,
    values={
        "tokenizer": {"kind": "wordpiece"},
        "encoder": {"size": "base"},
        "normalize": False,
    },
)
```

{% endcode %}

The nested scope name is a prefix, not a leaf value. `values={"tokenizer": "wordpiece"}` raises as unknown because it does not target `tokenizer.kind`.

When you pass child-local values through `hp.nest(child, name="child", values=...)`, Hypster validates those explicit child values after the child runs. Typos and inactive child-branch keys raise instead of being ignored.

## Pass Execution Arguments To Children

{% code overflow="wrap" %}

```python
from my_app.training import BatchSampler, TrainingInputs

def sampler_config(hp: HP, default_batch_size: int) -> BatchSampler:
    batch_size = hp.int(default_batch_size, name="batch_size", min=1)
    shuffle = hp.bool(True, name="shuffle")
    return BatchSampler(batch_size=batch_size, shuffle=shuffle)

def training_config(hp: HP) -> TrainingInputs:
    train = hp.nest(sampler_config, name="train", default_batch_size=128)
    eval = hp.nest(sampler_config, name="eval", default_batch_size=256)
    return TrainingInputs(train=train, eval=eval)
```

{% endcode %}

## Inspect Branches Before Running

{% code overflow="wrap" %}

```python
explore(embedding_pipeline, values={"encoder.size": "base"})
```

{% endcode %}

If an override points at a parameter that is not reached on the active branch, Hypster raises by default. That keeps `values=` safe to log and replay.


---

# 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/how-to-guides/compose-nested-configs.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.