barbara-api-sdk 0.1.0__py3-none-any.whl

barbara/__init__.py

@@ -0,0 +1,28 @@
+"""Python SDK for the Barbara Edge AI API."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import AsyncBarbaraClient, BarbaraClient
+from .config import BarbaraConfig
+from .exceptions import (
+    BarbaraApiError,
+    BarbaraAuthError,
+    BarbaraNotFoundError,
+    BarbaraPermissionError,
+)
+
+try:
+    __version__ = version("barbara-api-sdk")
+except PackageNotFoundError:  # running from a source checkout, not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AsyncBarbaraClient",
+    "BarbaraApiError",
+    "BarbaraAuthError",
+    "BarbaraClient",
+    "BarbaraConfig",
+    "BarbaraNotFoundError",
+    "BarbaraPermissionError",
+    "__version__",
+]

barbara/_http.py

@@ -0,0 +1,42 @@
+"""Internal request/response plumbing shared by the sync and async clients.
+
+Not part of the public API — resources call ``client.request(...)``, not
+this module directly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import BarbaraApiError, BarbaraNotFoundError, BarbaraPermissionError
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    try:
+        body: Any = response.json()
+    except ValueError:
+        body = response.text
+    if response.status_code == 404:
+        raise BarbaraNotFoundError(f"Not found: {response.url}", status=404, body=body)
+    if response.status_code in (401, 403):
+        raise BarbaraPermissionError(
+            f"Permission denied ({response.status_code}): {response.url}",
+            status=response.status_code,
+            body=body,
+        )
+    raise BarbaraApiError(
+        f"Barbara API error {response.status_code}: {response.url}",
+        status=response.status_code,
+        body=body,
+    )
+
+
+def build_headers(token: str, extra: Optional[dict[str, str]] = None) -> dict[str, str]:
+    headers = {"Authorization": f"Bearer {token}"}
+    if extra:
+        headers.update(extra)
+    return headers

barbara/auth.py

@@ -0,0 +1,105 @@
+"""OAuth2 password-grant authentication against Barbara's Keycloak realm."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import httpx
+
+from .config import BarbaraConfig
+from .exceptions import BarbaraAuthError
+
+# Refresh a bit before actual expiry to avoid racing a 401 on a nearly-dead token.
+EXPIRY_SAFETY_MARGIN_SECONDS = 15
+
+
+@dataclass
+class Token:
+    access_token: str
+    expires_at: float
+
+    @property
+    def is_expired(self) -> bool:
+        return time.monotonic() >= self.expires_at
+
+
+def _token_request_body(config: BarbaraConfig) -> dict[str, str]:
+    body = {
+        "grant_type": "password",
+        "client_id": config.client_id,
+        "username": config.username,
+        "password": config.password,
+    }
+    if config.client_secret:
+        body["client_secret"] = config.client_secret
+    return body
+
+
+def _parse_token_response(data: dict[str, Any]) -> Token:
+    try:
+        expires_in = float(data["expires_in"])
+        access_token = data["access_token"]
+    except KeyError as exc:
+        raise BarbaraAuthError(f"Unexpected token response, missing {exc}", body=data) from exc
+    return Token(
+        access_token=access_token,
+        expires_at=time.monotonic() + expires_in - EXPIRY_SAFETY_MARGIN_SECONDS,
+    )
+
+
+class TokenManager:
+    """Sync token fetch/refresh. Not thread-safe by design (kept simple)."""
+
+    def __init__(self, config: BarbaraConfig, http_client: httpx.Client):
+        self._config = config
+        self._http = http_client
+        self._token: Optional[Token] = None
+
+    def get_token(self, *, force_refresh: bool = False) -> str:
+        if force_refresh or self._token is None or self._token.is_expired:
+            self._token = self._fetch()
+        return self._token.access_token
+
+    def _fetch(self) -> Token:
+        response = self._http.post(
+            self._config.token_url,
+            data=_token_request_body(self._config),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        if response.status_code >= 400:
+            raise BarbaraAuthError(
+                f"Authentication failed ({response.status_code})",
+                status=response.status_code,
+                body=response.text,
+            )
+        return _parse_token_response(response.json())
+
+
+class AsyncTokenManager:
+    """Async counterpart of :class:`TokenManager`."""
+
+    def __init__(self, config: BarbaraConfig, http_client: httpx.AsyncClient):
+        self._config = config
+        self._http = http_client
+        self._token: Optional[Token] = None
+
+    async def get_token(self, *, force_refresh: bool = False) -> str:
+        if force_refresh or self._token is None or self._token.is_expired:
+            self._token = await self._fetch()
+        return self._token.access_token
+
+    async def _fetch(self) -> Token:
+        response = await self._http.post(
+            self._config.token_url,
+            data=_token_request_body(self._config),
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+        )
+        if response.status_code >= 400:
+            raise BarbaraAuthError(
+                f"Authentication failed ({response.status_code})",
+                status=response.status_code,
+                body=response.text,
+            )
+        return _parse_token_response(response.json())

barbara/client.py

@@ -0,0 +1,135 @@
+"""Public entry points: :class:`BarbaraClient` and :class:`AsyncBarbaraClient`."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Optional, Type
+
+import httpx
+
+from ._http import build_headers, raise_for_status
+from .auth import AsyncTokenManager, TokenManager
+from .config import BarbaraConfig
+from .resources.alerts import AlertsResource, AsyncAlertsResource
+from .resources.appconfig import AppConfigResource, AsyncAppConfigResource
+from .resources.applications import ApplicationsResource, AsyncApplicationsResource
+from .resources.clusters import AsyncClustersResource, ClustersResource
+from .resources.devices import AsyncDevicesResource, DevicesResource
+from .resources.groups import AsyncGroupsResource, GroupsResource
+from .resources.models import AsyncModelsResource, ModelsResource
+from .resources.users import AsyncUsersResource, UsersResource
+from .utils import unwrap
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class BarbaraClient:
+    """Synchronous client. Use as a context manager to close the underlying session.
+
+    Example:
+        with BarbaraClient.from_env() as client:
+            devices = client.devices.list()
+    """
+
+    def __init__(self, config: BarbaraConfig, *, timeout: float = DEFAULT_TIMEOUT):
+        self.config = config
+        self._http = httpx.Client(
+            base_url=config.api_url, timeout=timeout, verify=config.verify_tls
+        )
+        self._auth_http = httpx.Client(timeout=timeout, verify=config.verify_tls)
+        self._tokens = TokenManager(config, self._auth_http)
+
+        self.devices = DevicesResource(self)
+        self.clusters = ClustersResource(self)
+        self.applications = ApplicationsResource(self)
+        self.models = ModelsResource(self)
+        self.appconfig = AppConfigResource(self)
+        self.groups = GroupsResource(self)
+        self.users = UsersResource(self)
+        self.alerts = AlertsResource(self)
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> BarbaraClient:
+        return cls(BarbaraConfig.from_env(), **kwargs)
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """Issue an authenticated request, retrying once on a 401 with a fresh token."""
+        token = self._tokens.get_token()
+        response = self._http.request(method, path, headers=build_headers(token), **kwargs)
+        if response.status_code == 401:
+            token = self._tokens.get_token(force_refresh=True)
+            response = self._http.request(method, path, headers=build_headers(token), **kwargs)
+        raise_for_status(response)
+        return response.json() if response.content else None
+
+    def api_version(self) -> Any:
+        return unwrap(self.request("GET", "/api/v1/apiversion"))
+
+    def close(self) -> None:
+        self._http.close()
+        self._auth_http.close()
+
+    def __enter__(self) -> BarbaraClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+
+class AsyncBarbaraClient:
+    """Async counterpart of :class:`BarbaraClient`, same resource surface."""
+
+    def __init__(self, config: BarbaraConfig, *, timeout: float = DEFAULT_TIMEOUT):
+        self.config = config
+        self._http = httpx.AsyncClient(
+            base_url=config.api_url, timeout=timeout, verify=config.verify_tls
+        )
+        self._auth_http = httpx.AsyncClient(timeout=timeout, verify=config.verify_tls)
+        self._tokens = AsyncTokenManager(config, self._auth_http)
+
+        self.devices = AsyncDevicesResource(self)
+        self.clusters = AsyncClustersResource(self)
+        self.applications = AsyncApplicationsResource(self)
+        self.models = AsyncModelsResource(self)
+        self.appconfig = AsyncAppConfigResource(self)
+        self.groups = AsyncGroupsResource(self)
+        self.users = AsyncUsersResource(self)
+        self.alerts = AsyncAlertsResource(self)
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> AsyncBarbaraClient:
+        return cls(BarbaraConfig.from_env(), **kwargs)
+
+    async def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        token = await self._tokens.get_token()
+        response = await self._http.request(method, path, headers=build_headers(token), **kwargs)
+        if response.status_code == 401:
+            token = await self._tokens.get_token(force_refresh=True)
+            response = await self._http.request(
+                method, path, headers=build_headers(token), **kwargs
+            )
+        raise_for_status(response)
+        return response.json() if response.content else None
+
+    async def api_version(self) -> Any:
+        return unwrap(await self.request("GET", "/api/v1/apiversion"))
+
+    async def close(self) -> None:
+        await self._http.aclose()
+        await self._auth_http.aclose()
+
+    async def __aenter__(self) -> AsyncBarbaraClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.close()

barbara/config.py

@@ -0,0 +1,57 @@
+"""Configuration and credential loading.
+
+Credentials follow Barbara's "Barbara API Credentials" convention: four
+values prefixed ``BBR_API_`` (client id/secret + username/password). Other
+config (API/auth URLs, realm) uses the plain ``BBR_`` prefix.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+DEFAULT_API_URL = "https://prod.bap.barbara.tech"
+DEFAULT_AUTH_URL = "https://prod.auth.barbara.tech/auth"
+DEFAULT_REALM = "bbr_prod"
+
+
+@dataclass(frozen=True)
+class BarbaraConfig:
+    client_id: str
+    client_secret: Optional[str]
+    username: str
+    password: str
+    api_url: str = DEFAULT_API_URL
+    auth_url: str = DEFAULT_AUTH_URL
+    realm: str = DEFAULT_REALM
+    verify_tls: bool = True
+
+    @property
+    def token_url(self) -> str:
+        return f"{self.auth_url.rstrip('/')}/realms/{self.realm}/protocol/openid-connect/token"
+
+    @classmethod
+    def from_env(cls) -> BarbaraConfig:
+        """Build config from environment variables, raising on missing credentials."""
+        missing = [
+            name
+            for name in ("BBR_API_CLIENT_ID", "BBR_API_USERNAME", "BBR_API_PASSWORD")
+            if not os.environ.get(name)
+        ]
+        if missing:
+            raise ValueError(
+                "Missing required environment variable(s): "
+                + ", ".join(missing)
+                + ". See README for the Barbara API Credentials setup."
+            )
+        return cls(
+            client_id=os.environ["BBR_API_CLIENT_ID"],
+            client_secret=os.environ.get("BBR_API_CLIENT_SECRET"),
+            username=os.environ["BBR_API_USERNAME"],
+            password=os.environ["BBR_API_PASSWORD"],
+            api_url=os.environ.get("BBR_API_URL", DEFAULT_API_URL),
+            auth_url=os.environ.get("BBR_AUTH_URL", DEFAULT_AUTH_URL),
+            realm=os.environ.get("BBR_REALM", DEFAULT_REALM),
+            verify_tls=os.environ.get("BBR_VERIFY_TLS", "true").lower() != "false",
+        )

barbara/exceptions.py

@@ -0,0 +1,26 @@
+"""Exceptions raised by the Barbara SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BarbaraApiError(RuntimeError):
+    """Base error for any non-2xx response from the Barbara API."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class BarbaraAuthError(BarbaraApiError):
+    """Raised when authentication (token request or refresh) fails."""
+
+
+class BarbaraNotFoundError(BarbaraApiError):
+    """Raised on a 404, or when a lookup by name (e.g. deviceName) has no match."""
+
+
+class BarbaraPermissionError(BarbaraApiError):
+    """Raised on a 401/403 for a required (non-optional) resource."""

barbara/models.py

@@ -0,0 +1,211 @@
+"""Lightweight dataclasses for common Barbara API entities.
+
+These are intentionally partial: only fields the SDK actively relies on are
+declared. Unknown fields returned by the API are kept in ``.raw`` so nothing
+is ever silently dropped.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class Device:
+    id: str
+    device_name: str
+    status: Optional[str] = None
+    cluster_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> Device:
+        return cls(
+            id=data["_id"],
+            device_name=data.get("deviceName", ""),
+            status=data.get("status"),
+            cluster_id=data.get("clusterId"),
+            raw=data,
+        )
+
+
+@dataclass
+class Cluster:
+    id: str
+    name: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> Cluster:
+        return cls(id=data["_id"], name=data.get("name", ""), raw=data)
+
+
+@dataclass
+class Application:
+    id: str
+    name: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> Application:
+        return cls(id=data["_id"], name=data.get("name", ""), raw=data)
+
+
+@dataclass
+class MLModel:
+    id: str
+    name: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> MLModel:
+        return cls(id=data["_id"], name=data.get("name", ""), raw=data)
+
+
+@dataclass
+class AppConfig:
+    id: str
+    name: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> AppConfig:
+        return cls(id=data.get("_id", ""), name=data.get("name", ""), raw=data)
+
+
+@dataclass
+class Group:
+    id: str
+    name: str
+    device_ids: List[str] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> Group:
+        return cls(
+            id=data.get("_id", ""),
+            name=data.get("name", ""),
+            device_ids=data.get("devices", []),
+            raw=data,
+        )
+
+
+@dataclass
+class User:
+    id: str
+    email: str
+    main_role: Optional[str] = None
+    enabled: Optional[bool] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> User:
+        return cls(
+            id=data["_id"],
+            email=data.get("email", ""),
+            main_role=data.get("main_role"),
+            enabled=data.get("enabled"),
+            raw=data,
+        )
+
+
+@dataclass
+class Alert:
+    id: str
+    title: Optional[str]
+    severity: Optional[str]
+    active: Optional[bool]
+    device_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> Alert:
+        return cls(
+            id=data["_id"],
+            title=data.get("title"),
+            severity=data.get("severity"),
+            active=data.get("active"),
+            device_id=data.get("deviceId"),
+            raw=data,
+        )
+
+
+@dataclass
+class Workload:
+    """A device workload (``deviceSpace``). Unlike most entities, the API
+    doesn't return its own top-level id — it's the ``workloadId``/``spaceId``
+    the caller already knows, kept here for symmetry with the other
+    dataclasses.
+    """
+
+    id: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, workload_id: str, data: Dict[str, Any]) -> Workload:
+        return cls(id=workload_id, raw=data)
+
+
+@dataclass
+class Secret:
+    """A device or cluster secret reference (name only — value is never
+    returned unencrypted unless the caller has permission and asks for it).
+    """
+
+    id: str
+    name: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> Secret:
+        return cls(id=data.get("_id", ""), name=data.get("name", ""), raw=data)
+
+
+@dataclass
+class DockerCredential:
+    id: str
+    server: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> DockerCredential:
+        return cls(id=data.get("_id", ""), server=data.get("server"), raw=data)
+
+
+@dataclass
+class ModelVersion:
+    id: str
+    name: str
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> ModelVersion:
+        return cls(id=data.get("_id", ""), name=data.get("name", ""), raw=data)
+
+
+@dataclass
+class AlertEvent:
+    id: str
+    event_type: Optional[str]
+    device_id: Optional[str] = None
+    alert_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_api(cls, data: Dict[str, Any]) -> AlertEvent:
+        return cls(
+            id=data["_id"],
+            event_type=data.get("eventType"),
+            device_id=data.get("deviceId"),
+            alert_id=data.get("alertId"),
+            raw=data,
+        )
+
+
+@dataclass
+class Page:
+    """Generic page wrapper for list endpoints."""
+
+    items: List[Any]
+    total: Optional[int] = None

barbara/resources/alerts.py

@@ -0,0 +1,74 @@
+"""Alerts resource (``/v1/alerts`` and ``/v1/events``). Same pattern as :mod:`devices`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from ..models import Alert, AlertEvent
+from ..utils import unwrap
+
+if TYPE_CHECKING:
+    from ..client import AsyncBarbaraClient, BarbaraClient
+
+
+def _event_params(*, offset: int, size: int, device_id: Optional[str]) -> Dict[str, Any]:
+    params: Dict[str, Any] = {"from": offset, "size": size}
+    if device_id is not None:
+        params["deviceId"] = device_id
+    return params
+
+
+class AlertsResource:
+    def __init__(self, client: BarbaraClient):
+        self._client = client
+
+    def list(self) -> List[Alert]:
+        data = unwrap(self._client.request("GET", "/api/v1/alerts"))
+        return [Alert.from_api(item) for item in data]
+
+    def get(self, alert_id: str) -> Alert:
+        data = unwrap(self._client.request("GET", f"/api/v1/alerts/{alert_id}"))
+        return Alert.from_api(data)
+
+    def ack(self, alert_id: str) -> Alert:
+        data = unwrap(self._client.request("POST", f"/api/v1/alerts/{alert_id}/ack"))
+        return Alert.from_api(data)
+
+    def list_events(
+        self, *, offset: int = 0, size: int = 100, device_id: Optional[str] = None
+    ) -> List[AlertEvent]:
+        params = _event_params(offset=offset, size=size, device_id=device_id)
+        data = unwrap(self._client.request("GET", "/api/v1/events", params=params))
+        return [AlertEvent.from_api(item) for item in data]
+
+    def get_event(self, event_id: str) -> AlertEvent:
+        data = unwrap(self._client.request("GET", f"/api/v1/events/{event_id}"))
+        return AlertEvent.from_api(data)
+
+
+class AsyncAlertsResource:
+    def __init__(self, client: AsyncBarbaraClient):
+        self._client = client
+
+    async def list(self) -> List[Alert]:
+        data = unwrap(await self._client.request("GET", "/api/v1/alerts"))
+        return [Alert.from_api(item) for item in data]
+
+    async def get(self, alert_id: str) -> Alert:
+        data = unwrap(await self._client.request("GET", f"/api/v1/alerts/{alert_id}"))
+        return Alert.from_api(data)
+
+    async def ack(self, alert_id: str) -> Alert:
+        data = unwrap(await self._client.request("POST", f"/api/v1/alerts/{alert_id}/ack"))
+        return Alert.from_api(data)
+
+    async def list_events(
+        self, *, offset: int = 0, size: int = 100, device_id: Optional[str] = None
+    ) -> List[AlertEvent]:
+        params = _event_params(offset=offset, size=size, device_id=device_id)
+        data = unwrap(await self._client.request("GET", "/api/v1/events", params=params))
+        return [AlertEvent.from_api(item) for item in data]
+
+    async def get_event(self, event_id: str) -> AlertEvent:
+        data = unwrap(await self._client.request("GET", f"/api/v1/events/{event_id}"))
+        return AlertEvent.from_api(data)