deepx-client

deepx-client is the Python client for a DeepH-serve instance. It submits POSCAR files, watches asynchronous jobs and downloads the predicted Hamiltonian, band structure and DOS artifacts.

The client only speaks the public /v1 HTTP API. It does not import the server, JAX or DeepH-pack, so installing it is lightweight. It is a Python SDK; no console command is installed yet.

Install

From PyPI (after release):

pip install deepx-client

From this repository:

uv pip install -e "./client[dev]"
# or
pip install -e ./client

The import package is deepx_client. The old DeepHClient class name and the deeph_client import path remain available for compatibility; new code should use DeepXClient and deepx_client.

Python API

from deepx_client import DeepXClient

with DeepXClient("http://127.0.0.1:8000", api_key="...") as client:
    job = client.submit(
        open("POSCAR").read(),
        tasks=["hamiltonian", "band"],
        band={"npoints": 200, "energy_window": [-5, 5]},
    )
    job = client.wait(job.id, on_update=lambda item: print(item.stage, item.progress))
    paths = client.download_all(job.id, "./results")
    print(paths)

A complete runnable example is examples/python_client.py:

export DEEPH_SERVE_URL=http://127.0.0.1:8000
export DEEPH_SERVE_API_KEY=...
python examples/python_client.py POSCAR --tasks hamiltonian --out results

Configure

The server URL and API key can be supplied with environment variables:

export DEEPH_SERVE_URL=http://127.0.0.1:8000
export DEEPH_SERVE_API_KEY=...

or in ~/.config/deepx/client.toml:

default = "lab"

[profiles.lab]
server = "https://deeph.example.com"
api_key = "..."
timeout = 30.0
verify = true

The old ~/.config/deeph/client.toml path is still read when the new path does not exist. Precedence: explicitly passed values > environment > selected profile > defaults.

Python API reference

from deepx_client import DeepXClient

with DeepXClient("http://127.0.0.1:8000", api_key="...") as client:
    job = client.submit(
        open("POSCAR").read(),
        tasks=["hamiltonian", "band"],
        band={"npoints": 200, "energy_window": [-5, 5]},
    )
    job = client.wait(job.id)
    paths = client.download_all(job.id, "./results")

DeepXClient exposes health(), models(), submit(), submit_request(), submit_and_wait(), get(), list(), artifacts(), wait(), cancel(), delete(), download() and download_all().

Errors

• APIError: non-success response; carries status_code, code, details and request_id.
• JobFailedError: job ended as failed, canceled or expired.
• JobTimeoutError: local wait timeout elapsed.
• ArtifactVerificationError: downloaded file did not match the manifest sha256.
• ConfigError: invalid local profile or configuration.

All errors derive from DeepHClientError.

Compatibility aliases

The distribution deeph-client is a compatibility alias that depends on deepx-client. It keeps old imports working:

from deeph_client import DeepHClient

New code should use deepx_client and DeepXClient.

Development

cd client
uv venv .venv
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check src tests
.venv/bin/python -m black --check src tests

License

GPL-3.0-or-later, matching DeepH-serve. See LICENSE.