mlip_bench

A typed Python client for the MLIP elemental benchmark structure→workflow API (https://api.mlip-bench.dev) — structures, typed workflow instances, ase.Atoms geometry, pandas leaderboard/parity DataFrames, bulk dataset download, and client-side point lookups into the API's hash-sorted geometry/corpus stores over plain HTTP Range reads (no server-side query route required for that last one).

Requires Python ≥ 3.10.

Install

Not yet on PyPI — install from this checkout:

pip install -e clients/python[pandas,datasets]

Extras:

The base install (no extras) already gets you Client, structure(), Structure.geometry() / .workflow(), client.gbseg_instance(), client.corpus_record(), and client.stores.lookup() — httpx, pyarrow, and ase are unconditional dependencies.

Credentials

Client() takes no required arguments — it resolves credentials through four sources, in this priority order (first fully-specified source wins; a source with only an id or only a secret is treated as absent):

1. Explicit constructor arguments:

   Client(client_id="...", client_secret="...")
   

2. Environment variables: MLIP_BENCH_CLIENT_ID / MLIP_BENCH_CLIENT_SECRET
3. ~/.config/mlip-bench.toml:

   [auth]
   client_id = "..."
   client_secret = "..."
   

4. ~/.config/mlip-bench.env (shell-style, export prefix optional):

   CF_CLIENT_ID=...
   CF_CLIENT_SECRET=...
   

If none of the four are found, Client() proceeds unauthenticated (with a UserWarning) rather than raising — pass anonymous=True to silence the warning when that's intentional.

Quickstart

See examples/quickstart.py for a fuller runnable tour (structure by mp-id, typed elastic instance, ase.Atoms geometry, leaderboard head, gbseg instance, corpus record, remote store lookup, dataset listing). The short version:

from mlip_bench import Client

client = Client()  # picks up credentials automatically, see above

structure = client.structure("mp-132")             # hash, mp_id, or alias
print(structure.record.element, structure.record.formula)

atoms = structure.geometry()                        # ase.Atoms

instance = structure.workflow("elastic:allegro_MP-L")  # typed WorkflowInstance
print(instance.units[0].outcomes["k_vrh"])

leaderboard = client.track("elastic").leaderboard()  # pandas.DataFrame
print(leaderboard.head())

entry_path = client.datasets.download("some_dataset.parquet", dest_dir="/tmp")

What's addressable

The API has four addressability tiers, each reached a different way:

Aliases (mp_ids like mp-132, or {namespace}:{structure_id} ids) resolve via a 302 redirect, transparently, wherever a hex atoms_hash is accepted.

Errors

All five are importable directly from the top-level package:

from mlip_bench import (
    NotFoundError, ApiError, GeometryUnavailable,
    ParityNotPublished, DataVersionMismatch,
)

Development

cd clients/python
pip install -e .[pandas,pymatgen,datasets]
python -m pytest tests/ -q          # fixture-server suite, no live credentials needed
python examples/quickstart.py       # live smoke against api.mlip-bench.dev (needs credentials)