# Welcome

<div data-full-width="false"><figure><picture><source srcset="https://112953062-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LxSFee2hkLDuwva3EYO%2Fuploads%2FKIbk1aqLoNUdOKo12iM6%2Fhypster_text_white_text.png?alt=media&#x26;token=703fce50-c660-4db5-8684-838f8566dd8f" media="(prefers-color-scheme: dark)"><img src="https://112953062-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LxSFee2hkLDuwva3EYO%2Fuploads%2Fgit-blob-6111f1b6469f2632cbd2ac0f2aa394c3cdcf4736%2Fhypster_with_text.png?alt=media" 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
* :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 %}
**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="https://112953062-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LxSFee2hkLDuwva3EYO%2Fuploads%2FrznsGvmZ8HmgS23OSDXK%2FGroup%204%20(5).png?alt=media&#x26;token=821a40a1-ef4a-44a0-9fd9-f2ac1c7ba085">Group 4 (5).png</a></td><td><a href="getting-started/installation">installation</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="https://112953062-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LxSFee2hkLDuwva3EYO%2Fuploads%2FpjFjJzVEBGIvYDMs8Mzw%2FGroup%2053.png?alt=media&#x26;token=37ab6762-777a-4b3a-8273-586ee42146e3">Group 53.png</a></td><td><a href="getting-started/usage-examples">usage-examples</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="https://112953062-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LxSFee2hkLDuwva3EYO%2Fuploads%2F4Yu96JEzByfIyBntHNqK%2FGroup%2026.png?alt=media&#x26;token=a9c8a43b-adfb-4b82-97be-50fb08718548">Group 26.png</a></td><td><a href="in-depth/basic-best-practices">basic-best-practices</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.
