# Python SDK quickstart

Run a local training experiment with tuning suggestions from hyperopt.dev. The Python package is **tuning-client**, the import is `tuning_client`, and the demo modules are `tuning_demo` and `tuning_demo.stats`.

## 1. Create a virtual environment

Use Python 3.11 or newer. On Linux or macOS:

```sh
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
```

On Windows PowerShell, create the environment with `py -m venv .venv` and activate it with `.venv\Scripts\Activate.ps1`.

## 2. Install the demo

On Linux, install CPU PyTorch first to avoid downloading NVIDIA/CUDA dependencies. The demo trains on CPU:

```sh
python -m pip install 'torch>=2.5,<3' --index-url https://download.pytorch.org/whl/cpu
python -m pip install 'tuning-client[demo]'
```

On macOS, install the demo directly:

```sh
python -m pip install 'tuning-client[demo]'
```

For Windows or other PyTorch setups, follow the [PyTorch installation guide](https://pytorch.org/get-started/locally/), then install `tuning-client[demo]`. If you only need the SDK, use `python -m pip install tuning-client`.

## 3. Create and verify your account

[Create an account](https://hyperopt.dev/signup) and use the verification link sent to your email. The service demo prompts for your email and password. Keep credentials out of source code and shared notebooks.

## 4. Run the breast-cancer demo

```sh
python -m tuning_demo --api-url https://hyperopt.dev --dataset breast-cancer
```

The demo trains ten model configurations locally, reports validation losses, and saves results in `./results/`. Datasets are cached in `~/.cache/tuning-client/`.

To run two trials and summarize the results:

```sh
python -m tuning_demo.stats --api-url https://hyperopt.dev --datasets breast-cancer --runs 2
```

Use the hyphenated dataset name `breast-cancer`. The single-run module accepts `--dataset`; repeated statistics use `--datasets` and `--runs`.

```sh
python -m tuning_demo --list-datasets
```

## Compare a local reference scheduler

Local reference schedulers need no hyperopt.dev account:

```sh
python -m tuning_demo.stats --scheduler asha --datasets breast-cancer --runs 2 --workers 1
```

Available schedulers are `service`, `asha`, `median`, `flaml`, `pbt`, and `pb2`. Service benchmarks run sequentially. `--workers` controls local reference schedulers only. See the [benchmark methodology](https://hyperopt.dev/benchmarks) before comparing results.

## SDK integration

Authenticate interactively and request the next configuration to train:

```python
from getpass import getpass
from tuning_client import TuningClient

with TuningClient("https://hyperopt.dev") as api:
    api.login(input("Email: ").strip(), getpass("Password: "))
    session_id = api.create_session()
    try:
        stream = api.tuning_session(session_id)
        try:
            configs = [{"learning_rate": rate} for rate in
                       [0.001, 0.002, 0.003, 0.004, 0.005,
                        0.006, 0.007, 0.008, 0.009, 0.010]]
            stream.initialize(configs, max_steps=10, seed=42)
            suggestion = stream.suggest()
            print(suggestion)
            # Train that configuration locally, then report its validation loss:
            # stream.report(suggestion["idx"], validation_loss)
        finally:
            stream.close()
    finally:
        api.terminate_session(session_id)
```

This example requests one suggestion; it does not implement a training loop. Continue with `suggest()` and `report(idx, validation_loss)`, or `report_and_suggest(...)`, in your own loop. `status()` exposes progress and rankings. `max_steps` counts observations per model, not optimizer updates. See [how it works](https://hyperopt.dev/docs/how-it-works).

For automation, pass an existing access token to `TuningClient(..., access_token=...)`, or use the demo's `COMPUTE_ACCESS_TOKEN` environment variable. `COMPUTE_API_URL` sets the service URL; `COMPUTE_EMAIL` and `COMPUTE_PASSWORD` support noninteractive login. Use your environment's secret handling rather than hard-coding credentials.

## Session cleanup and errors

The demo releases sessions on completion or failure. `--keep-session` retains a session, and `--session-id ID` uses an existing unused session that you must release yourself. For SDK integrations, call `terminate_session(session_id)` in a `finally` block: closing a stream only disconnects it. `list_sessions()` and `wait_for_termination(session_id)` help inspect and wait for cleanup.

| Symptom | What to do |
| --- | --- |
| `externally-managed-environment` | Create and activate a virtual environment before installing. |
| `No module named tuning_demo` | Install `'tuning-client[demo]'` using the same Python interpreter that runs the command. |
| NVIDIA packages consume disk space | On Linux, install CPU PyTorch first, then the demo. |
| Invalid dataset or unknown arguments | Use `breast-cancer`; use `tuning_demo.stats` for `--datasets` and `--runs`. |
| Authentication fails | Check credentials and use the website's password reset if needed. |
| Email verification required | Open your verification email or request another at signup. |
| Session or request limit reached | Check existing sessions and [current beta limits](https://hyperopt.dev/pricing); respect any retry delay. |
| Partial results after a failed run | Inspect the saved results and resolve the reported error before retrying. |

## Custom datasets and privacy

CSV and Parquet support is available through `tuning-client[demo,custom]`:

```sh
python -m pip install 'tuning-client[demo,custom]'
python -m tuning_demo --api-url https://hyperopt.dev --custom-data ./data.csv --target label --task classification
```

Custom training and preprocessing happen locally. Remove leakage columns and choose an appropriate split for your task. Pass `--no-telemetry` to disable optional demo usage events. Read the [data flow and limitations](https://hyperopt.dev/docs/how-it-works).

Original SDK/demo code is MIT licensed, with included third-party license notices. It was generated with ChatGPT and human reviewed. Package releases and full notices are available on [PyPI](https://pypi.org/project/tuning-client/).