Source code for squadds.ml.client
"""Client of the SQuADDS ML API (the models hosted on the SQuADDS Hugging Face Space).
from squadds.ml import client
client.list_models()
client.get_model("transmon_cross_hamiltonian_inverse") # inputs, outputs, units, limits, example request
client.predict("transmon_cross_hamiltonian_inverse", inputs={"qubit_frequency_GHz": 4.85, "anharmonicity_MHz": -205.0})
client.predict("<file model id>", file="chip.gds", inputs={"ground_layer": "1/0"})
The base URL is ``SQUADDS_ML_API_URL`` when set, else ``DEFAULT_URL``. Gated models need a Hugging Face token of a member
of the SQuADDS organization (``token=`` or ``HF_TOKEN``).
"""
from __future__ import annotations
import json
import os
from pathlib import Path
DEFAULT_URL = "https://squadds-squadds-ml-inference-api.hf.space"
def _url(base_url: str | None) -> str:
return (base_url or os.environ.get("SQUADDS_ML_API_URL") or DEFAULT_URL).rstrip("/")
def _headers(token: str | None) -> dict:
token = token or os.environ.get("HF_TOKEN")
return {"Authorization": f"Bearer {token}"} if token else {}
def _json(r) -> dict:
try:
body = r.json()
except ValueError:
body = {"error": {"message": r.text}}
if r.status_code >= 400:
err = body.get("error") or body
raise RuntimeError(f"SQuADDS ML API {r.status_code}: {err}")
return body
[docs]
def list_models(base_url: str | None = None, token: str | None = None, timeout: float = 30) -> list[dict]:
import requests
return _json(requests.get(f"{_url(base_url)}/v1/models", headers=_headers(token), timeout=timeout))["models"]
[docs]
def get_model(model_id: str, base_url: str | None = None, token: str | None = None, timeout: float = 30) -> dict:
"""One model's listing entry and contract (``GET /v1/models/{model_id}``)."""
import requests
return _json(requests.get(f"{_url(base_url)}/v1/models/{model_id}", headers=_headers(token), timeout=timeout))
[docs]
def predict(
model_id: str,
inputs: dict | list | None = None,
file=None,
options: dict | None = None,
base_url: str | None = None,
token: str | None = None,
timeout: float = 600,
) -> dict:
"""The response envelope (``outputs``, ``metadata``, ``timing_s``, ``cached``). ``file``: a path or bytes (file models)."""
import requests
url = f"{_url(base_url)}/v1/models/{model_id}/predict"
if file is None:
r = requests.post(
url, json={"inputs": inputs or {}, "options": options or {}}, headers=_headers(token), timeout=timeout
)
else:
data = Path(file).read_bytes() if isinstance(file, (str, os.PathLike)) else bytes(file)
form = {"inputs": json.dumps(inputs or {}), "options": json.dumps(options or {})}
r = requests.post(
url, files={"file": ("layout.gds", data)}, data=form, headers=_headers(token), timeout=timeout
)
return _json(r)