Welcome

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

Key Features

• 🐍 Pythonic API: Intuitive & minimal syntax that feels natural to Python developers
• 🪆 Hierarchical, Conditional Configurations: Support for nested and swappable configurations
• 📐 Type Safety: Built-in type hints and validation
• 🔍 Schema Exploration: Inspect parameters, defaults, and active branches with explore()
• 🧪 Hyperparameter Optimization Built-In: Native, first-class optuna support

Show your support by giving us a star! ⭐

How Does it work?

1

Install Hypster

uv add hypster

2

Define a configuration space

from hypster import HP
from my_app.llms import LLMClient


def llm_config(hp: HP) -> LLMClient:
    model_name = hp.select(["gpt-5.5", "gpt-5.5-mini"], name="model_name")
    temperature = hp.float(0.0, name="temperature", min=0.0, max=1.0)

    return LLMClient(model_name=model_name, temperature=temperature)

3

Explore your configuration

from hypster import explore

explore(llm_config)

4

Instantiate your runtime object

from hypster import instantiate

llm = instantiate(llm_config, values={"model_name": "gpt-5.5", "temperature": 0.7})

5

Execute!

llm.invoke("What is Hypster?")

Discover Hypster

Getting Started

How to create & instantiate Hypster configs

Tutorials

Step-by-step guides for ML & Generative AI use-cases

Best Practices

How to make the most out of Hypster

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 manage and optimize swappable runtime components in your codebase.

Core Workflow

• Define ordinary Python config functions whose first argument is hp: HP.
• Return the initialized object your application will use whenever that object is cheap and safe to construct.
• Choose swappable components with named option dictionaries that map simple keys to config functions.
• Explore the active parameter tree with explore(config) before running a branch.
• Instantiate with instantiate(config, values={...}) when you only need the returned object.
• Log params with instantiate_with_params(config, values={...}) when you need a stable replay record.

Design Notes

Hypster treats values= as a reproducibility surface. Unknown values and values for inactive branches raise by default, because silently accepting them can make an experiment impossible to replay. Use explore(config, values=...) to inspect a branch before instantiating it.

Because exploration and interactive controls execute the config function to discover the current branch, avoid doing work there that should happen only once or only after the user confirms a run. Build expensive clients, load indexes, write files, call paid APIs, and train models after instantiate() returns.

Additional Reading

• Introducing Hypster
• Implementing Modular RAG With Haystack & Hypster
• 5 Pillars for Hyper-Optimized AI Workflows

AI-Readable Docs

GitBook publishes Hypster's docs as an agent-friendly index at llms.txt and as a full Markdown export at llms-full.txt.