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:

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:

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:

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

For Windows or other PyTorch setups, follow the PyTorch installation guide, 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 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

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:

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.

python -m tuning_demo --list-datasets

Compare a local reference scheduler

Local reference schedulers need no hyperopt.dev account:

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 before comparing results.

SDK integration

Authenticate interactively and request the next configuration to train:

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.

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.

Custom datasets and privacy

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

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.

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.