syfthub-sdk 0.1.0__py3-none-any.whl

syfthub_sdk/__init__.py

@@ -0,0 +1,152 @@
+"""SyftHub SDK - Python client for interacting with SyftHub API.
+
+Example usage:
+    from syfthub_sdk import SyftHubClient
+
+    client = SyftHubClient(base_url="https://hub.syft.com")
+    client.auth.login(username="john", password="secret123")
+
+    # Your endpoints
+    for endpoint in client.my_endpoints.list():
+        print(endpoint.name)
+
+    # Browse public endpoints
+    for endpoint in client.hub.browse():
+        print(f"{endpoint.path}: {endpoint.name}")
+
+    # Chat with RAG via aggregator
+    response = client.chat.complete(
+        prompt="What is machine learning?",
+        model="alice/gpt-model",
+        data_sources=["bob/ml-docs"],
+    )
+    print(response.response)
+
+    # Streaming chat
+    for event in client.chat.stream(prompt="...", model="..."):
+        if event.type == "token":
+            print(event.content, end="")
+"""
+
+from syfthub_sdk._pagination import PageIterator
+from syfthub_sdk.chat import (
+    ChatResource,
+    ChatStreamEvent,
+    DoneEvent,
+    ErrorEvent,
+    GenerationStartEvent,
+    RetrievalCompleteEvent,
+    RetrievalStartEvent,
+    SourceCompleteEvent,
+    TokenEvent,
+)
+from syfthub_sdk.client import SyftHubClient
+from syfthub_sdk.exceptions import (
+    AggregatorError,
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    ChatError,
+    ConfigurationError,
+    EndpointResolutionError,
+    GenerationError,
+    NetworkError,
+    NotFoundError,
+    RetrievalError,
+    SyftHubError,
+    UserAlreadyExistsError,
+    ValidationError,
+)
+from syfthub_sdk.models import (
+    AccountingCredentials,
+    AccountingUser,
+    AuthTokens,
+    ChatMetadata,
+    ChatResponse,
+    Connection,
+    CreatorType,
+    Document,
+    DocumentSource,
+    Endpoint,
+    EndpointPublic,
+    EndpointRef,
+    EndpointType,
+    Message,
+    OrganizationRole,
+    Policy,
+    SatelliteTokenResponse,
+    SourceInfo,
+    SourceStatus,
+    TokenUsage,
+    Transaction,
+    TransactionStatus,
+    User,
+    UserRole,
+    Visibility,
+)
+from syfthub_sdk.syftai import SyftAIResource
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main client
+    "SyftHubClient",
+    # Core models
+    "User",
+    "UserRole",
+    "OrganizationRole",
+    "Endpoint",
+    "EndpointPublic",
+    "EndpointType",
+    "AuthTokens",
+    "SatelliteTokenResponse",
+    "Visibility",
+    "Policy",
+    "Connection",
+    # Chat models
+    "EndpointRef",
+    "Document",
+    "DocumentSource",
+    "SourceInfo",
+    "SourceStatus",
+    "ChatMetadata",
+    "ChatResponse",
+    "TokenUsage",
+    "Message",
+    # Chat streaming events
+    "ChatStreamEvent",
+    "RetrievalStartEvent",
+    "SourceCompleteEvent",
+    "RetrievalCompleteEvent",
+    "GenerationStartEvent",
+    "TokenEvent",
+    "DoneEvent",
+    "ErrorEvent",
+    # Resources (for type hints)
+    "ChatResource",
+    "SyftAIResource",
+    # Accounting models
+    "AccountingCredentials",
+    "AccountingUser",
+    "Transaction",
+    "TransactionStatus",
+    "CreatorType",
+    # Exceptions
+    "SyftHubError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "ValidationError",
+    "APIError",
+    "ConfigurationError",
+    "NetworkError",
+    "UserAlreadyExistsError",
+    # Chat exceptions
+    "ChatError",
+    "AggregatorError",
+    "RetrievalError",
+    "GenerationError",
+    "EndpointResolutionError",
+    # Utilities
+    "PageIterator",
+]

syfthub_sdk/_http.py

@@ -0,0 +1,327 @@
+"""Internal HTTP client for SyftHub SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from syfthub_sdk.exceptions import (
+    AccountingAccountExistsError,
+    AccountingServiceUnavailableError,
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    InvalidAccountingPasswordError,
+    NetworkError,
+    NotFoundError,
+    SyftHubError,
+    ValidationError,
+)
+from syfthub_sdk.models import AuthTokens
+
+
+class HTTPClient:
+    """HTTP client with automatic token management."""
+
+    def __init__(
+        self,
+        base_url: str,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize HTTP client.
+
+        Args:
+            base_url: Base URL for the API (e.g., "https://hub.syft.com")
+            timeout: Request timeout in seconds
+        """
+        # Ensure base_url doesn't end with /
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+        # Token storage
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+
+        # HTTP client
+        self._client = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    @property
+    def is_authenticated(self) -> bool:
+        """Check if client has tokens set."""
+        return self._access_token is not None
+
+    def set_tokens(self, tokens: AuthTokens) -> None:
+        """Set authentication tokens.
+
+        Args:
+            tokens: AuthTokens with access_token and refresh_token
+        """
+        self._access_token = tokens.access_token
+        self._refresh_token = tokens.refresh_token
+
+    def get_tokens(self) -> AuthTokens | None:
+        """Get current authentication tokens.
+
+        Returns:
+            AuthTokens if authenticated, None otherwise
+        """
+        if self._access_token and self._refresh_token:
+            return AuthTokens(
+                access_token=self._access_token,
+                refresh_token=self._refresh_token,
+            )
+        return None
+
+    def clear_tokens(self) -> None:
+        """Clear authentication tokens."""
+        self._access_token = None
+        self._refresh_token = None
+
+    def _get_headers(self, include_auth: bool = True) -> dict[str, str]:
+        """Build request headers.
+
+        Args:
+            include_auth: Whether to include Authorization header
+
+        Returns:
+            Dictionary of headers
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if include_auth and self._access_token:
+            headers["Authorization"] = f"Bearer {self._access_token}"
+        return headers
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Convert HTTP errors to SDK exceptions.
+
+        Args:
+            response: HTTP response object
+
+        Raises:
+            SyftHubError: Appropriate exception based on status code
+        """
+        status = response.status_code
+        try:
+            detail = response.json()
+        except Exception:
+            detail = response.text
+
+        # Extract message from detail if it's a dict
+        # Handle both {"detail": {...}} and {"detail": "string"} formats
+        inner_detail = (
+            detail.get("detail", detail) if isinstance(detail, dict) else detail
+        )
+
+        if isinstance(inner_detail, dict):
+            message = inner_detail.get("message", str(inner_detail))
+            error_code = inner_detail.get("code")
+        else:
+            message = str(inner_detail)
+            error_code = None
+
+        # Check for accounting-specific errors based on error code
+        if isinstance(inner_detail, dict) and error_code:
+            if error_code == "ACCOUNTING_ACCOUNT_EXISTS":
+                raise AccountingAccountExistsError(message=message, detail=inner_detail)
+            elif error_code == "INVALID_ACCOUNTING_PASSWORD":
+                raise InvalidAccountingPasswordError(
+                    message=message, detail=inner_detail
+                )
+            elif error_code == "ACCOUNTING_SERVICE_UNAVAILABLE":
+                raise AccountingServiceUnavailableError(
+                    message=message, detail=inner_detail
+                )
+
+        # Standard error handling based on status code
+        if status == 401:
+            raise AuthenticationError(message=message, detail=detail)
+        elif status == 403:
+            raise AuthorizationError(message=message, detail=detail)
+        elif status == 404:
+            raise NotFoundError(message=message, detail=detail)
+        elif status == 422:
+            raise ValidationError(message=message, detail=detail)
+        else:
+            raise APIError(
+                message=message,
+                status_code=status,
+                detail=detail,
+            )
+
+    def _attempt_refresh(self) -> bool:
+        """Attempt to refresh the access token.
+
+        Returns:
+            True if refresh succeeded, False otherwise
+        """
+        if not self._refresh_token:
+            return False
+
+        try:
+            response = self._client.post(
+                f"{self.base_url}/api/v1/auth/refresh",
+                headers={"Content-Type": "application/json"},
+                json={"refresh_token": self._refresh_token},
+            )
+            if response.status_code == 200:
+                data = response.json()
+                self._access_token = data["access_token"]
+                self._refresh_token = data["refresh_token"]
+                return True
+        except Exception:
+            pass
+        return False
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        include_auth: bool = True,
+        retry_on_401: bool = True,
+    ) -> dict[str, Any] | list[Any]:
+        """Make an HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, PATCH, DELETE)
+            path: URL path (will be joined with base_url)
+            json: JSON body data
+            params: Query parameters
+            data: Form data (for login endpoint)
+            include_auth: Whether to include Authorization header
+            retry_on_401: Whether to retry with token refresh on 401
+
+        Returns:
+            Parsed JSON response
+
+        Raises:
+            SyftHubError: On API errors
+        """
+        url = f"{self.base_url}{path}"
+        headers = self._get_headers(include_auth=include_auth)
+
+        # For form data (OAuth2 login), adjust content type
+        if data is not None:
+            headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+        try:
+            response = self._client.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=json,
+                params=params,
+                data=data,
+            )
+        except httpx.TimeoutException as e:
+            raise NetworkError(
+                message="Request timed out",
+                cause=e,
+                detail=str(e),
+            ) from e
+        except httpx.RequestError as e:
+            raise NetworkError(
+                message=str(e) or "Network request failed",
+                cause=e,
+                detail=str(e),
+            ) from e
+        except Exception as e:
+            # Re-raise SyftHubErrors as-is
+            if isinstance(e, SyftHubError):
+                raise
+            raise NetworkError(
+                message="Unknown network error",
+                cause=e,
+                detail=str(e),
+            ) from e
+
+        # Handle 401 with token refresh
+        if (
+            response.status_code == 401
+            and retry_on_401
+            and include_auth
+            and self._attempt_refresh()
+        ):
+            # Retry with new token
+            return self.request(
+                method=method,
+                path=path,
+                json=json,
+                params=params,
+                data=data,
+                include_auth=include_auth,
+                retry_on_401=False,  # Don't retry again
+            )
+
+        # Handle errors
+        if response.status_code >= 400:
+            self._handle_error(response)
+
+        # Return parsed JSON (or empty dict for 204 No Content)
+        if response.status_code == 204:
+            return {}
+
+        return response.json()  # type: ignore[no-any-return]
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        include_auth: bool = True,
+    ) -> dict[str, Any] | list[Any]:
+        """Make a GET request."""
+        return self.request("GET", path, params=params, include_auth=include_auth)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        include_auth: bool = True,
+    ) -> dict[str, Any] | list[Any]:
+        """Make a POST request."""
+        return self.request(
+            "POST", path, json=json, data=data, include_auth=include_auth
+        )
+
+    def put(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        include_auth: bool = True,
+    ) -> dict[str, Any] | list[Any]:
+        """Make a PUT request."""
+        return self.request("PUT", path, json=json, include_auth=include_auth)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        include_auth: bool = True,
+    ) -> dict[str, Any] | list[Any]:
+        """Make a PATCH request."""
+        return self.request("PATCH", path, json=json, include_auth=include_auth)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        include_auth: bool = True,
+    ) -> dict[str, Any] | list[Any]:
+        """Make a DELETE request."""
+        return self.request("DELETE", path, include_auth=include_auth)

syfthub_sdk/_pagination.py

@@ -0,0 +1,133 @@
+"""Pagination utilities for SyftHub SDK."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+# Type alias for fetch functions
+FetchFn = Callable[[int, int], list[dict[str, object]]]
+
+
+class PageIterator(Generic[T]):
+    """Lazy pagination iterator that fetches pages on demand.
+
+    Example usage:
+        # Iterate through all items
+        for endpoint in client.hub.browse():
+            print(endpoint.name)
+
+        # Get just the first page
+        first_page = client.hub.browse().first_page()
+
+        # Get all items as a list
+        all_items = client.hub.browse().all()
+
+        # Get first 50 items
+        items = client.hub.browse().take(50)
+    """
+
+    def __init__(
+        self,
+        fetch_fn: FetchFn,
+        model_class: type[T],
+        page_size: int = 20,
+    ) -> None:
+        """Initialize the page iterator.
+
+        Args:
+            fetch_fn: Function that takes (skip, limit) and returns list of dicts
+            model_class: Pydantic model class to parse items into
+            page_size: Number of items per page (default 20)
+        """
+        self._fetch_fn = fetch_fn
+        self._model_class = model_class
+        self._page_size = page_size
+        self._reset()
+
+    def _reset(self) -> None:
+        """Reset iterator state for fresh iteration."""
+        self._buffer: list[T] = []
+        self._current_page = 0
+        self._exhausted = False
+        self._started = False
+
+    def _fetch_page(self, page: int) -> list[T]:
+        """Fetch a single page and convert to models."""
+        skip = page * self._page_size
+        raw_items = self._fetch_fn(skip, self._page_size)
+
+        # Convert dicts to model instances
+        items = [self._model_class.model_validate(item) for item in raw_items]
+
+        # Check if this is the last page
+        if len(items) < self._page_size:
+            self._exhausted = True
+
+        return items
+
+    def __iter__(self) -> Iterator[T]:
+        """Return iterator (resets state for fresh iteration)."""
+        self._reset()
+        return self
+
+    def __next__(self) -> T:
+        """Return next item, fetching pages as needed."""
+        # If we have items in buffer, return next one
+        if self._buffer:
+            return self._buffer.pop(0)
+
+        # If exhausted, stop iteration
+        if self._exhausted:
+            raise StopIteration
+
+        # Fetch next page
+        self._started = True
+        page_items = self._fetch_page(self._current_page)
+        self._current_page += 1
+
+        if not page_items:
+            self._exhausted = True
+            raise StopIteration
+
+        # Buffer all but first item
+        self._buffer = page_items[1:]
+        return page_items[0]
+
+    def first_page(self) -> list[T]:
+        """Get just the first page of results.
+
+        Returns:
+            List of items from the first page
+        """
+        return self._fetch_page(0)
+
+    def all(self) -> list[T]:
+        """Fetch all pages and return as a single list.
+
+        Warning: This loads all items into memory.
+
+        Returns:
+            List of all items across all pages
+        """
+        return list(self)
+
+    def take(self, n: int) -> list[T]:
+        """Get the first n items (may span multiple pages).
+
+        Args:
+            n: Maximum number of items to return
+
+        Returns:
+            List of up to n items
+        """
+        result: list[T] = []
+        for item in self:
+            result.append(item)
+            if len(result) >= n:
+                break
+        return result