params-proto
  1. Guides
  2. API Reference

Avoiding Hyperparameter Hell 🔥

params-proto v3 is a declarative hyperparameter management library for machine learning. Write your parameters once with type hints and inline comments to get automatic CLI parsing, help generation, and declarative parameter sweeps with explicit error messages.

  • Automatically parse type hints and inline comments into a CLI program
  • Your IDE will provide autocompletion and type checking for your parameters
  • As simple as a class namespace or a function, progressively build up to more complex programs.
  • Multiple override patterns: CLI, direct assignment, context managers, and yaml config files.

Here is a quick example: first install params-proto using uv or pip

shell
uv add params-proto==3.3.0  # or
pip install params-proto==3.3.0

Using with Claude Code? Install the params-proto plugin for better AI assistance:

bash
/plugin marketplace add geyang/params-proto
/plugin install params-proto@params-proto

Now you can convert this function into a CLI program:

python
from params_proto import proto


@proto.cli
def train_mnist(
  seed: int,  # Random seed
  batch_size: int = 128,  # Training batch size
  epochs: int = 10,  # Number of training epochs
):
  """Train an MLP on MNIST dataset."""

  print(f"yoooooo~ seed={seed}, batch_size={batch_size}")


if __name__ == "__main__":
  train_mnist()

Running python train_mnist.py --help gives you colorized output in the terminal:

usage: train_mnist.py [-h] [--seed INT] [--batch-size INT] [--epochs INT]

Train an MLP on MNIST dataset.

options:
  -h, --help           show this help message and exit
  --seed INT           Random seed (required)
  --batch-size INT     Training batch size (default: 128)
  --epochs INT         Number of training epochs (default: 10)

What is Parameter Hell 🔥? (and Other Anti-Patterns)

When is the last time you spent hours tracking down a config variable, jumping through layers of class inheritance and runtime values? Only to find out that the value you were looking for was never set?

Good code should be self-explanatory and statically resolvable. You should be able to take a look at the code and understand what value the parameter will take. A common anti-pattern that appears everywhere is to nest config classes, and pass a single config object to the constructure of the top-level class. This makes it difficult to connect config flags with where and how it is used. Take a look at the example below:

  • Nested Config Classes Without Type Hint: A common anti-pattern is to nest config classes, and pass a single config object to the constructor of the top-level class.

    python
    class Impala:
def __init__(self, config: Config):
    self.config = config

    # All of these uses the same config!
    self.critic = Critic(self.config)
    self.actor = Actor(self.config)
    # ...

class Critic:
def __init__(self, config: Config):
    self.config = config
    self.lr = config.lr
    self.ent_coef = config.critic.ent_coef
    self.discount = config.critic.discount
    # ...

def loss(self, x):
    if self.config.loss_type == "l2":
      return nn.l2_loss(x) # ...

    This tends to make it impossible to understand what parameter is used where.

Single-Source-Of-Truth HyperParameter Management with params-proto

For a simple MNIST example we can define the training parameters by the function signature of def train(lr: float...):, and def eval(batch_size: int...):. And for the overall training run parameters, we can have those defined by the entrypoint function def main(seed: int...):

This way, your IDE can provide definition/usage intellisense, and you can easily see what parameters are used where. The idea is to co-locate parameters with their usages throughout the codebase.

When is Centralized Configuration Useful?

It is helpful when we only need to look at one place to override default values, for example at the beginning of your training run. params-proto does so by keeping track of all configuration parameters in a single place. So to automatically override parameters, you can simply run

python
from params_proto import proto


@proto.cli
def train(
  lr: float = 0.001,  # Learning rate
  batch_size: int = 32,  # Training batch size
  n_epochs: int = 100,  # Number of training epochs
):
  """Train a neural network on CIFAR-10 dataset."""
  print(f"Training with lr={lr}, batch_size={batch_size}, n_epochs={n_epochs}")


proto.bind(lr=0.01, batch_size=256, n_epochs=10)

assert train.lr == 0.01, "this is now overridden."
assert train.batch_size == 256, "this is now overridden."
assert train.n_epochs == 10, "this is now overridden."
  • Track what parameters exist
  • Get IDE autocompletion and type checking
  • Change parameters from the command line
  • Maintain parameter documentation

params-proto solves this by providing a declarative way to define parameters that integrates seamlessly with Python IDEs and command-line interfaces.

Override parameters from the command line:

shell
$ python train_mnist.py --batch-size 256 --epochs 20
Training MNIST with batch_size=256

Composing Configs from Multiple Locations

Use @proto.prefix to organize configuration across multiple namespaces:

python
from params_proto import proto


@proto.prefix
class Environment:
  """dm_control environment configuration."""
  domain: str = "cartpole"  # Domain name (e.g., cartpole, walker)
  task: str = "swingup"  # Task name within the domain
  time_limit: float = 10.0  # Episode time limit in seconds


@proto.prefix
class Agent:
  """SAC agent hyperparameters."""
  algorithm: str = "SAC"  # RL algorithm (SAC or PPO)
  buffer_size: int = 1000000  # Replay buffer capacity
  gamma: float = 0.99  # Discount factor
  tau: float = 0.005  # Target network update rate


@proto.cli
def train_rl(
  total_steps: int = 1000000,  # Total environment steps
  eval_freq: int = 5000,  # Evaluation frequency
  seed: int = 0,  # Random seed
):
  """Train RL agent on dm_control environment."""
  print(f"Training {Agent.algorithm} on {Environment.domain}-{Environment.task}")


if __name__ == "__main__":
  train_rl()

Running python train_rl.py --help shows grouped options:

usage: train_rl.py [-h] [--total-steps INT] [--eval-freq INT] [--seed INT] [OPTIONS]

Train RL agent on dm_control environment.

options:
  -h, --help                   show this help message and exit
  --total-steps INT            Total environment steps (default: 1000000)
  --eval-freq INT              Evaluation frequency (default: 5000)
  --seed INT                   Random seed (default: 0)

Environment options:
  dm_control environment configuration.

  --Environment.domain STR     Domain name (e.g., cartpole, walker) (default: cartpole)
  --Environment.task STR       Task name within the domain (default: swingup)
  --Environment.time-limit FLOAT  Episode time limit in seconds (default: 10.0)

Agent options:
  SAC agent hyperparameters.

  --Agent.algorithm STR        RL algorithm (SAC or PPO) (default: SAC)
  --Agent.buffer-size INT      Replay buffer capacity (default: 1000000)
  --Agent.gamma FLOAT          Discount factor (default: 0.99)
  --Agent.tau FLOAT            Target network update rate (default: 0.005)

Override any parameter:

shell
$ python train_rl.py --Environment.domain walker --Agent.gamma 0.95
Training SAC on walker-swingup

Environment Variables

Read configuration from environment variables with type-safe defaults:

python
from params_proto import proto, EnvVar


@proto.cli
def train_model(
  # Three ways to specify environment variables:
  batch_size: int = EnvVar @ "BATCH_SIZE",  # Read from env var
  learning_rate: float = EnvVar @ "LR" | 0.001,  # With default fallback
  db_url: str = EnvVar("DATABASE_URL", default="localhost"),  # Function syntax
  data_dir: str = EnvVar @ "$DATA_DIR/models",  # Template expansion
):
  """Train model with environment configuration."""
  print(f"Training with batch_size={batch_size}, lr={learning_rate}")


if __name__ == "__main__":
  train_model()

The pipe operator (|) provides clean syntax for fallback values:

python
# If LR env var is set, use it; otherwise use 0.001
learning_rate: float = EnvVar @ "LR" | 0.001

Environment variables are resolved at decoration time and automatically converted to the annotated type (int, float, bool, str).

See Environment Variables Guide for comprehensive documentation including template expansion, security considerations, and common patterns.

Learn More

The Quick Start covers the basics. For deeper understanding, see:

Building CLIs (related guides for creating command-line interfaces):

Documentation Contents

Why v3?

params-proto v3 is a complete redesign focused on simplicity, that maximally takes advantage of Python's new type hint system. This new API is in fact quite similar to params-proto v1, but at that time when I developed v1 (back in 2018), the python type hint system was still in its infancy. v2 was a rewrite from v1 that introduced the params_proto.hyper module, that allowed us to create and load hyperparameter sweeps.

v2 simply returns us to that, but with a modern, polished, and unified API for both decorator-based cli programs and the same powerful parameter sweeps.

Featurev1v2v3
API StyleDecoratorsClass inheritanceDecorators
Type HintsNot availableOptionalRequired
Inline DocsManualManualAutomatic
FunctionsFull supportNot supportedFull support
Union TypesNot supportedLimitedFull support
IDE SupportBasicBasicExcellent

See the Migration Guide for upgrading from v2.

GitHub Repository

The source code is available on GitHub.