params-proto

# params-proto v3.1.0

Declarative hyperparameter management for ML experiments with automatic CLI generation.

## Installation

```bash
pip install params-proto==3.1.0
```

## Three Decorators

| Decorator | Purpose | Access Pattern |
|-----------|---------|----------------|
| `@proto.cli` | CLI entry point | Parses sys.argv automatically |
| `@proto.prefix` | Singleton config | `ClassName.attr` (class-level) |
| `@proto` | Multi-instance | `instance.attr` (object-level) |

## Quick Start

### Simple CLI Script

```python
from params_proto import proto

@proto.cli
def train(
    lr: float = 0.001,  # Learning rate (inline comment = help text)
    batch_size: int = 32,  # Batch size
    epochs: int = 100,  # Number of epochs
):
    """Train a model."""  # Docstring = CLI description
    print(f"Training with lr={lr}")

if __name__ == "__main__":
    train()
```

```bash
python train.py --lr 0.01 --batch-size 64
python train.py --help
```

### Multi-Namespace Configuration

```python
@proto.prefix
class Model:
    name: str = "resnet50"  # Architecture
    dropout: float = 0.5  # Dropout rate

@proto.prefix
class Training:
    lr: float = 0.001  # Learning rate
    epochs: int = 100  # Epochs

@proto.cli
def main(seed: int = 42):
    """Train with namespaced config."""
    print(f"Model: {Model.name}, LR: {Training.lr}")

# CLI: python train.py --model.name vit --training.lr 0.01
```

### Environment Variables

```python
from params_proto import proto, EnvVar

@proto.cli
def train(
    lr: float = EnvVar @ "LEARNING_RATE" | 0.001,  # Env var with default
    api_key: str = EnvVar @ "API_KEY",  # Required env var (no default)
    # OR operation: try multiple env vars in order
    token: str = EnvVar @ "API_TOKEN" @ "AUTH_TOKEN" | "default",
): ...
```

### Union Types (Subcommand Pattern)

```python
from dataclasses import dataclass

@dataclass
class Adam:
    lr: float = 0.001
    beta1: float = 0.9

@dataclass
class SGD:
    lr: float = 0.01
    momentum: float = 0.