Update landmarkdiff/api_client.py to v0.3.2

landmarkdiff/api_client.py

@@ -34,6 +34,12 @@ import cv2
 import numpy as np
 
 
+class LandmarkDiffAPIError(Exception):
+    """Base exception for LandmarkDiff API errors."""
+
+    pass
+
+
 @dataclass
 class PredictionResult:
     """Result from a single prediction."""
@@ -69,17 +75,16 @@ class LandmarkDiffClient:
     def __init__(self, base_url: str = "http://localhost:8000", timeout: float = 60.0) -> None:
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
-        self._session: Any = None
+        self._session = None
 
     def _get_session(self) -> Any:
         """Lazy-initialize requests session."""
         if self._session is None:
             try:
                 import requests
-            except ImportError:
-                raise ImportError("requests required. Install with: pip install requests") from None
+            except ImportError as e:
+                raise ImportError("requests required. Install with: pip install requests") from e
             self._session = requests.Session()
-            self._session.timeout = self.timeout
         return self._session
 
     def _read_image(self, image_path: str | Path) -> bytes:
@@ -107,22 +112,58 @@ class LandmarkDiffClient:
 
         Returns:
             Dict with status and version info.
+
+        Raises:
+            LandmarkDiffAPIError: If server is unreachable or returns an error.
         """
         session = self._get_session()
-        resp = session.get(f"{self.base_url}/health")
-        resp.raise_for_status()
-        return resp.json()
+        try:
+            resp = session.get(f"{self.base_url}/health", timeout=self.timeout)
+            resp.raise_for_status()
+            return resp.json()
+        except Exception as e:
+            import requests
+
+            if isinstance(e, requests.ConnectionError):
+                raise LandmarkDiffAPIError(
+                    f"Cannot connect to LandmarkDiff server at {self.base_url}. "
+                    f"Make sure the server is running (python -m landmarkdiff serve)."
+                ) from None
+            elif isinstance(e, requests.HTTPError):
+                raise LandmarkDiffAPIError(
+                    f"Server returned error {e.response.status_code}: {e.response.text[:200]}"
+                ) from None
+            else:
+                raise
 
     def procedures(self) -> list[str]:
         """List available surgical procedures.
 
         Returns:
             List of procedure names.
+
+        Raises:
+            LandmarkDiffAPIError: If server is unreachable or returns an error.
         """
         session = self._get_session()
-        resp = session.get(f"{self.base_url}/procedures")
-        resp.raise_for_status()
-        return resp.json().get("procedures", [])
+        try:
+            resp = session.get(f"{self.base_url}/procedures", timeout=self.timeout)
+            resp.raise_for_status()
+            return resp.json().get("procedures", [])
+        except Exception as e:
+            import requests
+
+            if isinstance(e, requests.ConnectionError):
+                raise LandmarkDiffAPIError(
+                    f"Cannot connect to LandmarkDiff server at {self.base_url}. "
+                    f"Make sure the server is running (python -m landmarkdiff serve)."
+                ) from None
+            elif isinstance(e, requests.HTTPError):
+                raise LandmarkDiffAPIError(
+                    f"Server returned error {e.response.status_code}: {e.response.text[:200]}"
+                ) from None
+            else:
+                raise
 
     def predict(
         self,
@@ -152,21 +193,38 @@ class LandmarkDiffClient:
             "seed": str(seed),
         }
 
-        resp = session.post(f"{self.base_url}/predict", files=files, data=data)
-        resp.raise_for_status()
-        result = resp.json()
-
-        # Decode output image
-        output_img = self._decode_base64_image(result["output_image"])
-
-        return PredictionResult(
-            output_image=output_img,
-            procedure=procedure,
-            intensity=intensity,
-            confidence=result.get("confidence", 0.0),
-            metrics=result.get("metrics", {}),
-            metadata=result.get("metadata", {}),
+        resp = session.post(
+            f"{self.base_url}/predict", files=files, data=data, timeout=self.timeout
         )
+        try:
+            resp.raise_for_status()
+            result = resp.json()
+
+            # Decode output image
+            output_img = self._decode_base64_image(result["output_image"])
+
+            return PredictionResult(
+                output_image=output_img,
+                procedure=procedure,
+                intensity=intensity,
+                confidence=result.get("confidence", 0.0),
+                metrics=result.get("metrics", {}),
+                metadata=result.get("metadata", {}),
+            )
+        except Exception as e:
+            import requests
+
+            if isinstance(e, requests.ConnectionError):
+                raise LandmarkDiffAPIError(
+                    f"Cannot connect to LandmarkDiff server at {self.base_url}. "
+                    f"Make sure the server is running (python -m landmarkdiff serve)."
+                ) from None
+            elif isinstance(e, requests.HTTPError):
+                raise LandmarkDiffAPIError(
+                    f"Server returned error {e.response.status_code}: {e.response.text[:200]}"
+                ) from None
+            else:
+                raise
 
     def analyze(self, image_path: str | Path) -> dict[str, Any]:
         """Analyze a face image without generating a prediction.
@@ -178,14 +236,32 @@ class LandmarkDiffClient:
 
         Returns:
             Dict with analysis results.
+
+        Raises:
+            LandmarkDiffAPIError: If server is unreachable or returns an error.
         """
         session = self._get_session()
         image_bytes = self._read_image(image_path)
 
         files = {"image": ("image.png", image_bytes, "image/png")}
-        resp = session.post(f"{self.base_url}/analyze", files=files)
-        resp.raise_for_status()
-        return resp.json()
+        try:
+            resp = session.post(f"{self.base_url}/analyze", files=files, timeout=self.timeout)
+            resp.raise_for_status()
+            return resp.json()
+        except Exception as e:
+            import requests
+
+            if isinstance(e, requests.ConnectionError):
+                raise LandmarkDiffAPIError(
+                    f"Cannot connect to LandmarkDiff server at {self.base_url}. "
+                    f"Make sure the server is running (python -m landmarkdiff serve)."
+                ) from None
+            elif isinstance(e, requests.HTTPError):
+                raise LandmarkDiffAPIError(
+                    f"Server returned error {e.response.status_code}: {e.response.text[:200]}"
+                ) from None
+            else:
+                raise
 
     def batch_predict(
         self,