# Welcome

<div data-full-width="false"><figure><picture><source srcset="/files/XElGRKvhdyH5unbX9hyH" media="(prefers-color-scheme: dark)"><img src="/files/csE2alh4veT3cwphvBrT" alt=""></picture><figcaption></figcaption></figure></div>

### Hypster is a lightweight configuration framework for managing and **optimizing AI & ML workflows**

> Hypster is in preview and is not ready for production use.
>
> We're working hard to make Hypster stable and feature-complete, but until then, expect to encounter bugs, missing features, and occasional breaking changes.

### Key Features

* :snake: **Pythonic API**: Intuitive & minimal syntax that feels natural to Python developers
* :nesting\_dolls: **Hierarchical, Conditional Configurations**: Support for nested and swappable configurations
* :triangular\_ruler: **Type Safety**: Built-in type hints and validation
* :mag: **Schema Exploration**: Inspect parameters, defaults, and active branches with `explore()`
* :test\_tube: **Hyperparameter Optimization Built-In**: Native, first-class optuna support

> Show your support by giving us a [star](https://github.com/gilad-rubin/hypster)! ⭐

### How Does it work?

{% stepper %}
{% step %}
**Install Hypster**

```bash
uv add hypster
```

Or using pip:

```bash
pip install hypster
```

{% endstep %}

{% step %}
**Define a configuration space**

```python
from hypster import HP


def llm_config(hp: HP):
    model_name = hp.select(["gpt-5", "claude-sonnet-4-0", "gemini-2.5-flash"], name="model_name")
    temperature = hp.float(0.0, name="temperature", min=0.0, max=1.0)
    return {"model_name": model_name, "temperature": temperature}
```

{% endstep %}

{% step %}
**Explore your configuration**

```python
from hypster import explore

explore(llm_config)
```

{% endstep %}

{% step %}
**Instantiate your configuration**

```python
from hypster import instantiate

cfg = instantiate(llm_config, values={"model_name": "gpt-5", "temperature": 0.7})
```

{% endstep %}

{% step %}
**Define an execution function**

```python
def generate(prompt: str, model_name: str, temperature: float) -> str:
    model = llm.get_model(model_name)
    response = model.prompt(prompt, temperature=temperature)
    return response
```

{% endstep %}

{% step %}
**Execute!**

```python
generate(prompt="What is Hypster?", **cfg)
```

{% endstep %}
{% endstepper %}

## Discover Hypster

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Getting Started</strong></td><td>How to create &#x26; instantiate Hypster configs</td><td></td><td><a href="/files/gvePptq2cRq2igl7WW6q">/files/gvePptq2cRq2igl7WW6q</a></td><td><a href="/pages/AOgX0cNsNavrnnfQlMx0">/pages/AOgX0cNsNavrnnfQlMx0</a></td></tr><tr><td><strong>Tutorials</strong></td><td>Step-by-step guides for ML &#x26; Generative AI use-cases</td><td></td><td><a href="/files/Nj5lJQCrmlAPCTmQbniQ">/files/Nj5lJQCrmlAPCTmQbniQ</a></td><td><a href="/pages/NX6OC0dRHDqRM4nDyrtg">/pages/NX6OC0dRHDqRM4nDyrtg</a></td></tr><tr><td><strong>Best Practices</strong></td><td>How to make the most out of Hypster</td><td></td><td><a href="/files/3HiBewQRJ2fliafwoYSY">/files/3HiBewQRJ2fliafwoYSY</a></td><td><a href="/pages/xpQxAIZEJ6Qsrj3Scmbh">/pages/xpQxAIZEJ6Qsrj3Scmbh</a></td></tr></tbody></table>

## Why Use Hypster?

In modern AI/ML development, we often need to handle **multiple configurations across different scenarios**. This is essential because:

1. We don't know in advance which **hyperparameters** will best optimize our performance metrics and satisfy our constraints.
2. We need to support multiple **"modes"** for different scenarios. For example:
   1. Local vs. Remote Environments, Development vs. Production Settings
   2. Different App Configurations for specific use-cases and populations

Hypster takes care of these challenges by providing a simple way to define configuration spaces and instantiate them into concrete workflows. This enables you to easily manage and optimize multiple configurations in your codebase.

## Additional Reading

* [Introducing Hypster](https://medium.com/@giladrubin/introducing-hypster-a-pythonic-framework-for-managing-configurations-to-build-highly-optimized-ai-5ee004dbd6a5) - A comprehensive introduction to Hypster's core concepts and design philosophy.
* [Implementing Modular RAG With Haystack & Hypster](https://towardsdatascience.com/implementing-modular-rag-with-haystack-and-hypster-d2f0ecc88b8f) - A practical guide to building modular, LEGO-like reconfigurable RAG systems.
* [5 Pillars for Hyper-Optimized AI Workflows](https://medium.com/@giladrubin/5-pillars-for-a-hyper-optimized-ai-workflow-21fcaefe48ca) - Key principles for designing optimized AI systems. The process behind this article gave rise to hypster's design.


---

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

```
GET https://gilad-rubin.gitbook.io/hypster/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.