dex-demo / src /dex_studio /client.py
data-literate's picture
feat: add health, lineage, ML models, overview, and settings pages
a1efcaf
Raw History Blame Contribute Delete
7.7 kB
"""HTTP client for the DEX engine API.
Wraps ``httpx.AsyncClient`` with retry logic, timeout handling, and
structured error responses. All public methods return typed dicts or
raise ``DexAPIError``.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, cast
import httpx
from dex_studio.config import StudioConfig
__all__ = [
"DexAPIError",
"DexClient",
]
class DexAPIError(Exception):
"""Raised when a DEX engine API call fails."""
def __init__(self, status_code: int, message: str, url: str) -> None:
self.status_code = status_code
self.url = url
super().__init__(f"DEX API error {status_code} ({url}): {message}")
@dataclass(slots=True)
class DexClient:
"""Async HTTP client for the DEX engine REST API.
Usage::
client = DexClient(config)
await client.connect()
health = await client.health()
await client.close()
"""
config: StudioConfig
_client: httpx.AsyncClient | None = None
# ------------------------------------------------------------------
# Lifecycle
# ------------------------------------------------------------------
async def connect(self) -> None:
"""Create the underlying ``httpx.AsyncClient``."""
headers: dict[str, str] = {"Accept": "application/json"}
if self.config.api_token:
headers["Authorization"] = f"Bearer {self.config.api_token}"
self._client = httpx.AsyncClient(
base_url=self.config.api_url,
timeout=httpx.Timeout(self.config.timeout),
headers=headers,
)
async def close(self) -> None:
"""Shut down the HTTP client."""
if self._client is not None:
await self._client.aclose()
self._client = None
@property
def is_connected(self) -> bool:
return self._client is not None and not self._client.is_closed
# ------------------------------------------------------------------
# Internal helpers
# ------------------------------------------------------------------
async def _get(self, path: str, **params: Any) -> dict[str, Any]:
"""Issue a GET and return parsed JSON, raising ``DexAPIError`` on failure."""
if self._client is None:
msg = "Client not connected — call connect() first"
raise RuntimeError(msg)
try:
resp = await self._client.get(path, params=params or None)
except httpx.HTTPError as exc:
raise DexAPIError(
status_code=0,
message=f"Connection failed: {exc}",
url=f"{self.config.api_url}{path}",
) from exc
if resp.status_code >= 400:
body = resp.text[:500]
raise DexAPIError(
status_code=resp.status_code,
message=body,
url=str(resp.url),
)
return cast(dict[str, Any], resp.json())
async def _post(self, path: str, json: Any = None) -> dict[str, Any]:
"""Issue a POST and return parsed JSON."""
if self._client is None:
msg = "Client not connected — call connect() first"
raise RuntimeError(msg)
try:
resp = await self._client.post(path, json=json)
except httpx.HTTPError as exc:
raise DexAPIError(
status_code=0,
message=f"Connection failed: {exc}",
url=f"{self.config.api_url}{path}",
) from exc
if resp.status_code >= 400:
body = resp.text[:500]
raise DexAPIError(
status_code=resp.status_code,
message=body,
url=str(resp.url),
)
return cast(dict[str, Any], resp.json())
# ------------------------------------------------------------------
# Health & System
# ------------------------------------------------------------------
async def health(self) -> dict[str, Any]:
"""``GET /health``"""
return await self._get("/health")
async def readiness(self) -> dict[str, Any]:
"""``GET /ready``"""
return await self._get("/ready")
async def startup(self) -> dict[str, Any]:
"""``GET /startup``"""
return await self._get("/startup")
async def system_config(self) -> dict[str, Any]:
"""``GET /api/v1/system/config``"""
return await self._get("/api/v1/system/config")
async def root(self) -> dict[str, Any]:
"""``GET /`` — returns API name + version."""
return await self._get("/")
# ------------------------------------------------------------------
# Data Quality
# ------------------------------------------------------------------
async def data_sources(self, cursor: str | None = None, limit: int = 20) -> dict[str, Any]:
"""``GET /api/v1/data/sources``"""
params: dict[str, Any] = {"limit": limit}
if cursor:
params["cursor"] = cursor
return await self._get("/api/v1/data/sources", **params)
async def data_quality_summary(self) -> dict[str, Any]:
"""``GET /api/v1/data/quality``"""
return await self._get("/api/v1/data/quality")
async def data_quality_layer(self, layer: str, limit: int = 10) -> dict[str, Any]:
"""``GET /api/v1/data/quality/{layer}``"""
return await self._get(f"/api/v1/data/quality/{layer}", limit=limit)
# ------------------------------------------------------------------
# Warehouse / Lineage
# ------------------------------------------------------------------
async def warehouse_layers(self) -> dict[str, Any]:
"""``GET /api/v1/warehouse/layers``"""
return await self._get("/api/v1/warehouse/layers")
async def lineage(self, event_id: str) -> dict[str, Any]:
"""``GET /api/v1/warehouse/lineage/{event_id}``"""
return await self._get(f"/api/v1/warehouse/lineage/{event_id}")
# ------------------------------------------------------------------
# ML (requires ML router mounted on DEX engine)
# ------------------------------------------------------------------
async def list_models(self) -> dict[str, Any]:
"""``GET /api/v1/models``"""
return await self._get("/api/v1/models")
async def model_metadata(self, name: str, version: str | None = None) -> dict[str, Any]:
"""``GET /api/v1/models/{name}``"""
params: dict[str, Any] = {}
if version:
params["version"] = version
return await self._get(f"/api/v1/models/{name}", **params)
async def predict(
self,
model_name: str,
features: list[dict[str, Any]],
*,
version: str | None = None,
request_id: str | None = None,
) -> dict[str, Any]:
"""``POST /api/v1/predict``"""
payload: dict[str, Any] = {
"model_name": model_name,
"features": features,
}
if version:
payload["version"] = version
if request_id:
payload["request_id"] = request_id
return await self._post("/api/v1/predict", json=payload)
# ------------------------------------------------------------------
# Convenience
# ------------------------------------------------------------------
async def ping(self) -> bool:
"""Return ``True`` if DEX engine is reachable and healthy."""
try:
result = await self.health()
return result.get("status") == "alive"
except (DexAPIError, RuntimeError):
return False