Deploy SQuADDS ML inference API

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.pyc

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.10-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --upgrade pip && pip install -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,26 @@
 ---
-title: Squadds Ml Inference Api
-emoji: 🌖
-colorFrom: purple
-colorTo: indigo
+title: SQuADDS ML Inference API
 sdk: docker
-pinned: false
+app_port: 7860
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# SQuADDS ML Inference API
+
+Auto-generated deployment bundle for serving ML_qubit_design models with a FastAPI app.
+
+## Endpoints
+
+- `GET /health`
+- `GET /models`
+- `POST /predict`
+
+## Included Models
+
+- `transmon_cross_hamiltonian_inverse`: Inverse model that predicts TransmonCross geometry parameters from target Hamiltonian values.
+
+## Skipped Models
+
+- `transmon_cross_cap_matrix_inverse`: No model checkpoint found. Expected one of: model/best_keras_model_one_hot_encoding.keras, model/best_keras_model_surrogate_defined_loss.keras, model/best_keras_model_model2_surrogate.keras
+- `coupler_ncap_cap_matrix_inverse`: No model checkpoint found. Expected one of: model/best_keras_model_one_hot_encoding.keras, model/best_keras_model_surrogate_defined_loss.keras, model/best_keras_model_model2_surrogate.keras
+- `cavity_claw_route_meander_inverse`: No model checkpoint found. Expected one of: model/best_keras_model_one_hot_encoding.keras, model/best_keras_model_surrogate.keras, model/best_keras_model_model2_surrogate.keras

app.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+from squadds_ml_api.api import create_app
+
+
+app = create_app(Path(__file__).resolve().parent)

artifacts/transmon_cross_hamiltonian_inverse/X_names

@@ -0,0 +1,2 @@
+qubit_frequency_GHz
+anharmonicity_MHz

deployment_manifest.json

@@ -0,0 +1,111 @@
+{
+  "generated_at": "2026-04-10T23:34:07.750772+00:00",
+  "space": {
+    "repo_id": "SQuADDS/squadds-ml-inference-api",
+    "title": "SQuADDS ML Inference API",
+    "sdk": "docker",
+    "app_port": 7860,
+    "license": "mit"
+  },
+  "models": [
+    {
+      "id": "transmon_cross_hamiltonian_inverse",
+      "display_name": "TransmonCross Hamiltonian to Geometry",
+      "description": "Inverse model that predicts TransmonCross geometry parameters from target Hamiltonian values.",
+      "artifact_dir": "artifacts/transmon_cross_hamiltonian_inverse",
+      "model_path": "model/best_inverse_model_surrogate_defined_loss.keras",
+      "input_names_path": "X_names",
+      "input_names_format": "text_lines",
+      "output_names_path": "y_columns.npy",
+      "output_names_format": "npy",
+      "x_scaler_pattern": "scalers/scaler_X_{name}.save",
+      "y_scaler_pattern": "scalers/scaler_y_{name}_one_hot_encoding.save",
+      "input_units": {
+        "qubit_frequency_GHz": "GHz",
+        "anharmonicity_MHz": "MHz"
+      },
+      "output_units": {
+        "design_options.connection_pads.readout.claw_length": "m",
+        "design_options.connection_pads.readout.ground_spacing": "m",
+        "design_options.cross_length": "m"
+      },
+      "status": "ready",
+      "status_detail": "",
+      "tags": [
+        "inverse-design",
+        "transmon",
+        "hamiltonian"
+      ],
+      "prediction_output_index": 0
+    },
+    {
+      "id": "transmon_cross_cap_matrix_inverse",
+      "display_name": "TransmonCross Cap Matrix to Geometry",
+      "description": "Inverse model that predicts TransmonCross geometry parameters from cap matrix targets.",
+      "artifact_dir": "",
+      "model_path": "",
+      "input_names_path": "X_names",
+      "input_names_format": "text_lines",
+      "output_names_path": "y_columns.npy",
+      "output_names_format": "npy",
+      "x_scaler_pattern": "scalers/scaler_X_{name}.save",
+      "y_scaler_pattern": "scalers/scaler_y_{name}_one_hot_encoding.save",
+      "input_units": {},
+      "output_units": {},
+      "status": "missing_model_artifact",
+      "status_detail": "No model checkpoint found. Expected one of: model/best_keras_model_one_hot_encoding.keras, model/best_keras_model_surrogate_defined_loss.keras, model/best_keras_model_model2_surrogate.keras",
+      "tags": [
+        "inverse-design",
+        "transmon",
+        "cap-matrix"
+      ],
+      "prediction_output_index": 0
+    },
+    {
+      "id": "coupler_ncap_cap_matrix_inverse",
+      "display_name": "NCap Coupler Cap Matrix to Geometry",
+      "description": "Inverse model that predicts NCap coupler geometry from cap matrix targets.",
+      "artifact_dir": "",
+      "model_path": "",
+      "input_names_path": "X_names",
+      "input_names_format": "text_lines",
+      "output_names_path": "y_columns.npy",
+      "output_names_format": "npy",
+      "x_scaler_pattern": "scalers/scaler_X_{name}.save",
+      "y_scaler_pattern": "scalers/scaler_y_{name}_one_hot_encoding.save",
+      "input_units": {},
+      "output_units": {},
+      "status": "missing_model_artifact",
+      "status_detail": "No model checkpoint found. Expected one of: model/best_keras_model_one_hot_encoding.keras, model/best_keras_model_surrogate_defined_loss.keras, model/best_keras_model_model2_surrogate.keras",
+      "tags": [
+        "inverse-design",
+        "coupler",
+        "cap-matrix"
+      ],
+      "prediction_output_index": 0
+    },
+    {
+      "id": "cavity_claw_route_meander_inverse",
+      "display_name": "Cavity Claw RouteMeander Targets to Geometry",
+      "description": "Inverse model that predicts cavity claw RouteMeander geometry from target cavity frequency and kappa.",
+      "artifact_dir": "",
+      "model_path": "",
+      "input_names_path": "X_names",
+      "input_names_format": "text_lines",
+      "output_names_path": "y_columns.npy",
+      "output_names_format": "npy",
+      "x_scaler_pattern": "scalers/scaler_X_{name}.save",
+      "y_scaler_pattern": "scalers/scaler_y_{name}_one_hot_encoding.save",
+      "input_units": {},
+      "output_units": {},
+      "status": "missing_model_artifact",
+      "status_detail": "No model checkpoint found. Expected one of: model/best_keras_model_one_hot_encoding.keras, model/best_keras_model_surrogate.keras, model/best_keras_model_model2_surrogate.keras",
+      "tags": [
+        "inverse-design",
+        "cavity",
+        "readout"
+      ],
+      "prediction_output_index": 0
+    }
+  ]
+}

examples/agent_tool_schema.json

@@ -0,0 +1,29 @@
+{
+  "name": "squadds_ml_predict",
+  "description": "Run inference against the SQuADDS ML Hugging Face Space to predict device geometry from target physics inputs.",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "model_id": {
+        "type": "string",
+        "description": "Model identifier returned by GET /models."
+      },
+      "inputs": {
+        "description": "Single input object or batch of input objects using the exact input keys for the selected model."
+      },
+      "options": {
+        "type": "object",
+        "properties": {
+          "include_scaled_outputs": {
+            "type": "boolean",
+            "default": false
+          }
+        }
+      }
+    },
+    "required": [
+      "model_id",
+      "inputs"
+    ]
+  }
+}

examples/predict_transmon_hamiltonian.json

@@ -0,0 +1,10 @@
+{
+  "model_id": "transmon_cross_hamiltonian_inverse",
+  "inputs": {
+    "qubit_frequency_GHz": 4.85,
+    "anharmonicity_MHz": -205.0
+  },
+  "options": {
+    "include_scaled_outputs": false
+  }
+}

requirements.txt

@@ -0,0 +1,5 @@
+fastapi==0.115.12
+uvicorn[standard]==0.34.0
+numpy==1.26.4
+joblib==1.4.2
+tensorflow-cpu==2.11.1

squadds_ml_api/__init__.py

@@ -0,0 +1,2 @@
+"""Runtime package for the SQuADDS ML Hugging Face Space."""
+

squadds_ml_api/api.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+from fastapi import FastAPI, HTTPException
+
+from .registry import BundleConfigError, ModelRegistry, RequestValidationError
+from .schemas import PredictionRequest
+
+
+def create_app(bundle_root: Path) -> FastAPI:
+    registry = ModelRegistry(bundle_root)
+
+    app = FastAPI(
+        title="SQuADDS ML Inference API",
+        version="0.1.0",
+        description=(
+            "HTTP API for running inference against ML models trained in "
+            "ML_qubit_design and packaged for the SQuADDS Hugging Face Space."
+        ),
+    )
+
+    @app.get("/")
+    def root() -> dict:
+        return {
+            "service": "SQuADDS ML Inference API",
+            "docs": "/docs",
+            "models_endpoint": "/models",
+            "predict_endpoint": "/predict",
+        }
+
+    @app.get("/health")
+    def health() -> dict:
+        return {
+            "status": "ok",
+            "available_models": registry.available_model_ids(),
+            "bundle_root": str(bundle_root),
+        }
+
+    @app.get("/models")
+    def list_models() -> dict:
+        return {"models": registry.describe_models()}
+
+    @app.post("/predict")
+    def predict(request: PredictionRequest) -> dict:
+        try:
+            payload = registry.predict(
+                model_id=request.model_id,
+                inputs=request.inputs,
+                include_scaled_outputs=request.options.include_scaled_outputs,
+            )
+        except RequestValidationError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except BundleConfigError as exc:
+            raise HTTPException(status_code=500, detail=str(exc)) from exc
+        return payload
+
+    return app

squadds_ml_api/registry.py

@@ -0,0 +1,235 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List
+
+import joblib
+import numpy as np
+from tensorflow.keras.models import load_model
+
+
+class BundleConfigError(RuntimeError):
+    """Raised when the deployed bundle is missing required files or config."""
+
+
+class RequestValidationError(ValueError):
+    """Raised when an inference request does not match the model contract."""
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    id: str
+    display_name: str
+    description: str
+    artifact_dir: str
+    model_path: str
+    input_names_path: str
+    input_names_format: str
+    output_names_path: str
+    output_names_format: str
+    x_scaler_pattern: str | None = None
+    y_scaler_pattern: str | None = None
+    input_units: Dict[str, str] = field(default_factory=dict)
+    output_units: Dict[str, str] = field(default_factory=dict)
+    status: str = "ready"
+    status_detail: str = ""
+    tags: List[str] = field(default_factory=list)
+    prediction_output_index: int = 0
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "ModelSpec":
+        return cls(**payload)
+
+
+def _read_names(path: Path, fmt: str) -> List[str]:
+    if fmt == "text_lines":
+        return [line.strip() for line in path.read_text().splitlines() if line.strip()]
+    if fmt == "csv_header":
+        first_line = path.read_text().splitlines()[0]
+        return [item.strip() for item in first_line.split(",") if item.strip()]
+    if fmt == "npy":
+        values = np.load(path, allow_pickle=True)
+        return [str(item) for item in values.tolist()]
+    raise BundleConfigError(f"Unsupported name file format: {fmt}")
+
+
+class EndpointModel:
+    def __init__(self, bundle_root: Path, spec: ModelSpec):
+        self.bundle_root = bundle_root
+        self.spec = spec
+        self.artifact_root = bundle_root / spec.artifact_dir
+
+        if not self.artifact_root.exists():
+            raise BundleConfigError(
+                f"Artifact directory for model '{spec.id}' is missing: {self.artifact_root}"
+            )
+
+        self.input_names = _read_names(
+            self.artifact_root / spec.input_names_path, spec.input_names_format
+        )
+        self.output_names = _read_names(
+            self.artifact_root / spec.output_names_path, spec.output_names_format
+        )
+
+        model_file = self.artifact_root / spec.model_path
+        if not model_file.exists():
+            raise BundleConfigError(
+                f"Model file for '{spec.id}' is missing: {model_file}"
+            )
+        self.model = load_model(model_file, compile=False)
+
+    def _load_scaler(self, pattern: str, name: str):
+        scaler_path = self.artifact_root / pattern.format(name=name)
+        if not scaler_path.exists():
+            raise BundleConfigError(
+                f"Required scaler for '{self.spec.id}' is missing: {scaler_path}"
+            )
+        return joblib.load(scaler_path)
+
+    def _normalize_rows(self, inputs: Dict[str, float] | List[Dict[str, float]]) -> List[Dict[str, float]]:
+        rows = inputs if isinstance(inputs, list) else [inputs]
+        normalized: List[Dict[str, float]] = []
+        for index, row in enumerate(rows):
+            if not isinstance(row, dict):
+                raise RequestValidationError(
+                    f"Each input row must be an object, got {type(row).__name__} at index {index}."
+                )
+
+            missing = [name for name in self.input_names if name not in row]
+            extras = [name for name in row if name not in self.input_names]
+            if missing or extras:
+                raise RequestValidationError(
+                    f"Model '{self.spec.id}' expects inputs {self.input_names}. "
+                    f"Missing: {missing or 'none'}. Extra: {extras or 'none'}."
+                )
+
+            normalized.append({name: float(row[name]) for name in self.input_names})
+        return normalized
+
+    def _scale_inputs(self, rows: List[Dict[str, float]]) -> np.ndarray:
+        matrix = np.zeros((len(rows), len(self.input_names)), dtype=np.float32)
+        for row_idx, row in enumerate(rows):
+            for col_idx, name in enumerate(self.input_names):
+                value = row[name]
+                if self.spec.x_scaler_pattern:
+                    scaler = self._load_scaler(self.spec.x_scaler_pattern, name)
+                    scaled = scaler.transform([[value]])[0][0]
+                else:
+                    scaled = value
+                matrix[row_idx, col_idx] = float(scaled)
+        return matrix
+
+    def _unscale_outputs(self, scaled_outputs: np.ndarray) -> np.ndarray:
+        matrix = np.asarray(scaled_outputs, dtype=np.float32).copy()
+        if not self.spec.y_scaler_pattern:
+            return matrix
+
+        for col_idx, name in enumerate(self.output_names):
+            scaler = self._load_scaler(self.spec.y_scaler_pattern, name)
+            column = matrix[:, col_idx].reshape(-1, 1)
+            matrix[:, col_idx] = scaler.inverse_transform(column).reshape(-1)
+        return matrix
+
+    def predict(
+        self,
+        inputs: Dict[str, float] | List[Dict[str, float]],
+        include_scaled_outputs: bool = False,
+    ) -> Dict[str, Any]:
+        rows = self._normalize_rows(inputs)
+        scaled_inputs = self._scale_inputs(rows)
+        raw_predictions = self.model.predict(scaled_inputs, verbose=0)
+
+        if isinstance(raw_predictions, list):
+            scaled_outputs = np.asarray(raw_predictions[self.spec.prediction_output_index])
+        else:
+            scaled_outputs = np.asarray(raw_predictions)
+
+        unscaled_outputs = self._unscale_outputs(scaled_outputs)
+
+        predictions = [
+            {
+                output_name: float(unscaled_outputs[row_idx, col_idx])
+                for col_idx, output_name in enumerate(self.output_names)
+            }
+            for row_idx in range(unscaled_outputs.shape[0])
+        ]
+
+        response: Dict[str, Any] = {
+            "model_id": self.spec.id,
+            "display_name": self.spec.display_name,
+            "predictions": predictions,
+            "metadata": {
+                "input_order": self.input_names,
+                "output_order": self.output_names,
+                "input_units": self.spec.input_units,
+                "output_units": self.spec.output_units,
+                "num_predictions": len(predictions),
+            },
+        }
+        if include_scaled_outputs:
+            response["scaled_predictions"] = [
+                {
+                    output_name: float(scaled_outputs[row_idx, col_idx])
+                    for col_idx, output_name in enumerate(self.output_names)
+                }
+                for row_idx in range(scaled_outputs.shape[0])
+            ]
+        return response
+
+
+class ModelRegistry:
+    def __init__(self, bundle_root: Path):
+        self.bundle_root = Path(bundle_root)
+        manifest_path = self.bundle_root / "deployment_manifest.json"
+        if not manifest_path.exists():
+            raise BundleConfigError(
+                f"Deployment manifest is missing from bundle: {manifest_path}"
+            )
+
+        payload = json.loads(manifest_path.read_text())
+        self.bundle_info = payload.get("space", {})
+        self.specs = [ModelSpec.from_dict(item) for item in payload.get("models", [])]
+        self._models: Dict[str, EndpointModel] = {}
+
+    def available_model_ids(self) -> List[str]:
+        return [spec.id for spec in self.specs if spec.status == "ready"]
+
+    def describe_models(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "id": spec.id,
+                "display_name": spec.display_name,
+                "description": spec.description,
+                "status": spec.status,
+                "status_detail": spec.status_detail,
+                "input_units": spec.input_units,
+                "output_units": spec.output_units,
+                "tags": spec.tags,
+            }
+            for spec in self.specs
+        ]
+
+    def _get_model(self, model_id: str) -> EndpointModel:
+        spec = next((item for item in self.specs if item.id == model_id), None)
+        if spec is None:
+            raise RequestValidationError(
+                f"Unknown model_id '{model_id}'. Available models: {self.available_model_ids()}."
+            )
+        if spec.status != "ready":
+            raise RequestValidationError(
+                f"Model '{model_id}' is not deployable in this bundle: {spec.status_detail or spec.status}."
+            )
+        if model_id not in self._models:
+            self._models[model_id] = EndpointModel(self.bundle_root, spec)
+        return self._models[model_id]
+
+    def predict(
+        self,
+        model_id: str,
+        inputs: Dict[str, float] | List[Dict[str, float]],
+        include_scaled_outputs: bool = False,
+    ) -> Dict[str, Any]:
+        model = self._get_model(model_id)
+        return model.predict(inputs=inputs, include_scaled_outputs=include_scaled_outputs)

squadds_ml_api/schemas.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import Dict, List, Union
+
+from pydantic import BaseModel, Field
+
+
+class PredictionOptions(BaseModel):
+    include_scaled_outputs: bool = Field(
+        default=False,
+        description="Include raw scaled model outputs alongside inverse-transformed values.",
+    )
+
+
+class PredictionRequest(BaseModel):
+    model_id: str = Field(..., description="The deployed model identifier.")
+    inputs: Union[Dict[str, float], List[Dict[str, float]]] = Field(
+        ...,
+        description="Either a single input object or a batch of input objects.",
+    )
+    options: PredictionOptions = Field(default_factory=PredictionOptions)