synapse-sdk 1.0.0a11__py3-none-any.whl → 2026.1.1b2__py3-none-any.whl

synapse_sdk/clients/protocols.py

@@ -0,0 +1,178 @@
+"""Protocol definitions for HTTP clients.
+
+This module defines protocols for sync and async HTTP clients,
+enabling proper type hints in mixins with IDE autocompletion support.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+
+@runtime_checkable
+class ClientProtocol(Protocol):
+    """Protocol for synchronous HTTP clients.
+
+    This protocol enables proper type hints in mixin classes,
+    providing IDE autocompletion for client methods.
+
+    Attributes:
+        name: Client name for error messages.
+        base_url: Base URL for API requests.
+        page_size: Default page size for pagination.
+    """
+
+    name: str | None
+    base_url: str
+    page_size: int
+
+    def _get_headers(self) -> dict[str, str]:
+        """Return headers for requests."""
+        ...
+
+    def _get(
+        self,
+        path: str,
+        url_conversion: dict | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a GET request."""
+        ...
+
+    def _post(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a POST request."""
+        ...
+
+    def _put(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a PUT request."""
+        ...
+
+    def _patch(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a PATCH request."""
+        ...
+
+    def _delete(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a DELETE request."""
+        ...
+
+    def _list(
+        self,
+        path: str,
+        url_conversion: dict | None = None,
+        list_all: bool = False,
+        params: dict | None = None,
+        **kwargs,
+    ) -> dict | tuple[Any, int]:
+        """List resources from a paginated API endpoint."""
+        ...
+
+
+@runtime_checkable
+class AsyncClientProtocol(Protocol):
+    """Protocol for asynchronous HTTP clients.
+
+    This protocol enables proper type hints in async mixin classes,
+    providing IDE autocompletion for async client methods.
+
+    Attributes:
+        name: Client name for error messages.
+        base_url: Base URL for API requests.
+        page_size: Default page size for pagination.
+    """
+
+    name: str | None
+    base_url: str
+    page_size: int
+
+    def _get_headers(self) -> dict[str, str]:
+        """Return headers for requests."""
+        ...
+
+    async def _get(
+        self,
+        path: str,
+        url_conversion: dict | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a GET request."""
+        ...
+
+    async def _post(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a POST request."""
+        ...
+
+    async def _put(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a PUT request."""
+        ...
+
+    async def _patch(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a PATCH request."""
+        ...
+
+    async def _delete(
+        self,
+        path: str,
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+        **kwargs,
+    ) -> Any:
+        """Perform a DELETE request."""
+        ...
+
+    async def _list(
+        self,
+        path: str,
+        url_conversion: dict | None = None,
+        list_all: bool = False,
+        params: dict | None = None,
+        **kwargs,
+    ) -> dict | tuple[Any, int]:
+        """List resources from a paginated API endpoint."""
+        ...

synapse_sdk/clients/utils.py

@@ -1,10 +1,88 @@
-def get_default_url_conversion(url_conversion, **kwargs):
-    defaults = {'files_fields': [], 'coerce': None, 'is_list': True}
-    defaults.update(kwargs)
-    if url_conversion:
-        defaults.update(url_conversion)
-    return defaults
+"""Shared utility functions for HTTP clients.
 
+This module contains utility functions extracted from BaseClient
+and AsyncBaseClient to reduce code duplication.
+"""
 
-def get_batched_list(object_list, batch_size):
-    return [object_list[index : index + batch_size] for index in range(0, len(object_list), batch_size)]
+from __future__ import annotations
+
+import json
+from typing import Any, Union
+
+# Type alias for response objects (requests.Response or httpx.Response)
+ResponseType = Any
+
+
+def build_url(base_url: str, path: str, trailing_slash: bool = False) -> str:
+    """Construct a full URL from base URL and path.
+
+    Args:
+        base_url: The base URL (e.g., 'https://api.example.com').
+        path: The path to append (e.g., 'users/123').
+        trailing_slash: Whether to ensure the URL ends with a slash.
+
+    Returns:
+        The constructed URL.
+
+    Examples:
+        >>> build_url('https://api.example.com', 'users/123')
+        'https://api.example.com/users/123'
+        >>> build_url('https://api.example.com/', '/users/123/')
+        'https://api.example.com/users/123/'
+        >>> build_url('https://api.example.com', 'users', trailing_slash=True)
+        'https://api.example.com/users/'
+    """
+    # If path is already a full URL, use it directly
+    if path.startswith(('http://', 'https://')):
+        url = path
+    else:
+        # Normalize: strip trailing slash from base and leading slash from path
+        base = base_url.rstrip('/')
+        clean_path = path.lstrip('/')
+        url = f'{base}/{clean_path}'
+
+    # Handle trailing slash
+    if trailing_slash and not url.endswith('/'):
+        url += '/'
+
+    return url
+
+
+def extract_error_detail(response: ResponseType) -> Any:
+    """Extract error detail from response, preferring JSON.
+
+    Args:
+        response: A requests.Response or httpx.Response object.
+
+    Returns:
+        The parsed JSON response if available, otherwise the text content
+        or reason phrase.
+    """
+    try:
+        return response.json()
+    except (ValueError, json.JSONDecodeError):
+        # For requests.Response, use 'reason'; for httpx.Response, use 'reason_phrase'
+        text = getattr(response, 'text', '')
+        reason = getattr(response, 'reason', None) or getattr(response, 'reason_phrase', '')
+        return text or reason
+
+
+def parse_json_response(response: ResponseType) -> Union[dict, str, None]:
+    """Parse response, preferring JSON.
+
+    Args:
+        response: A requests.Response or httpx.Response object.
+
+    Returns:
+        The parsed JSON response if available, otherwise the text content.
+        Returns None for 204 No Content responses.
+    """
+    # Handle 204 No Content
+    status_code = getattr(response, 'status_code', None)
+    if status_code == 204:
+        return None
+
+    try:
+        return response.json()
+    except (ValueError, json.JSONDecodeError):
+        return response.text

synapse_sdk/clients/validation.py

@@ -0,0 +1,58 @@
+"""Shared validation mixin for HTTP clients.
+
+This module provides a mixin class with Pydantic validation methods
+that can be used by both sync and async HTTP clients.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+
+class ValidationMixin:
+    """Mixin providing Pydantic validation methods for HTTP clients.
+
+    This mixin provides shared validation functionality for both
+    BaseClient and AsyncBaseClient, reducing code duplication.
+    """
+
+    def _validate_response(self, response: Any, model: type[BaseModel]) -> Any:
+        """Validate response against a Pydantic model.
+
+        Args:
+            response: The response data to validate.
+            model: The Pydantic model to validate against.
+
+        Returns:
+            The original response if validation passes.
+
+        Raises:
+            TypeError: If the model is not a Pydantic model.
+            ValidationError: If the response doesn't match the model.
+        """
+        if not hasattr(model, 'model_validate'):
+            raise TypeError(f'{model.__name__} is not a Pydantic model')
+        model.model_validate(response)
+        return response
+
+    def _validate_request(self, data: dict, model: type[BaseModel]) -> dict:
+        """Validate request data against a Pydantic model.
+
+        Args:
+            data: The request data to validate.
+            model: The Pydantic model to validate against.
+
+        Returns:
+            A dictionary with validated data, excluding None values.
+
+        Raises:
+            TypeError: If the model is not a Pydantic model.
+            ValidationError: If the data doesn't match the model.
+        """
+        if not hasattr(model, 'model_validate'):
+            raise TypeError(f'{model.__name__} is not a Pydantic model')
+        instance = model.model_validate(data)
+        return {k: v for k, v in instance.model_dump().items() if v is not None}

synapse_sdk/enums.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+from synapse_sdk.utils.file import download_file, get_temp_path
+
+
+class FileField(str):
+    """Pydantic field type that automatically downloads files from URLs.
+
+    When used as a type annotation in a Pydantic model, URLs are automatically
+    downloaded during validation and replaced with local file paths.
+
+    The downloaded files are cached in /tmp/datamaker/media/ using a hash of
+    the URL as the filename, preventing redundant downloads.
+
+    Examples:
+        >>> from pydantic import BaseModel
+        >>> from synapse_sdk.enums import FileField
+        >>>
+        >>> class InferenceParams(BaseModel):
+        ...     input_file: FileField
+        ...     config_file: FileField | None = None
+        >>>
+        >>> # URL is automatically downloaded during validation
+        >>> params = InferenceParams(input_file="https://example.com/image.jpg")
+        >>> params.input_file  # "/tmp/datamaker/media/abc123def.jpg"
+
+    Note:
+        - Downloads happen synchronously during validation
+        - Files are cached by URL hash (same URL = same local path)
+        - The field value becomes a string path to the local file
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source_type: Any,
+        handler: GetCoreSchemaHandler,
+    ) -> CoreSchema:
+        return core_schema.with_info_before_validator_function(
+            cls._validate,
+            core_schema.str_schema(),
+        )
+
+    @classmethod
+    def _validate(cls, value: Any, info: core_schema.ValidationInfo) -> str:
+        """Download the file from URL and return local path.
+
+        Args:
+            value: The URL string to download from.
+            info: Pydantic validation context (unused but required by protocol).
+
+        Returns:
+            String path to the downloaded local file.
+
+        Raises:
+            requests.HTTPError: If download fails.
+            ValueError: If value is not a valid URL string.
+        """
+        if not isinstance(value, str):
+            raise ValueError(f'FileField expects a URL string, got {type(value).__name__}')
+
+        if not value:
+            raise ValueError('FileField URL cannot be empty')
+
+        path_download = get_temp_path('media')
+        path_download.mkdir(parents=True, exist_ok=True)
+
+        return str(download_file(value, path_download))
+
+
+__all__ = ['FileField']

synapse_sdk/exceptions.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class ClientError(Exception):
+    """Base exception for all HTTP client errors.
+
+    This is the root of the exception hierarchy for HTTP client operations.
+    All client-related exceptions inherit from this class, allowing for
+    both broad and granular error handling.
+
+    Exception Hierarchy::
+
+        ClientError (base)
+        ├── ClientConnectionError  # Network/connection failures
+        ├── ClientTimeoutError     # Request timeouts
+        ├── HTTPError              # HTTP status code errors
+        │   ├── AuthenticationError   # 401 Unauthorized
+        │   ├── AuthorizationError    # 403 Forbidden
+        │   ├── NotFoundError         # 404 Not Found
+        │   ├── ValidationError       # 400/422 Bad Request
+        │   ├── RateLimitError        # 429 Too Many Requests
+        │   └── ServerError           # 5xx Server Errors
+        └── StreamError            # Streaming/WebSocket errors
+            ├── StreamLimitExceededError
+            └── WebSocketError
+
+    Attributes:
+        status_code: HTTP status code if applicable, None for non-HTTP errors.
+        detail: Error details from the response or underlying exception.
+
+    Example:
+        >>> from synapse_sdk.exceptions import ClientError, NotFoundError
+        >>>
+        >>> try:
+        ...     result = client.get_resource(123)
+        ... except NotFoundError:
+        ...     print("Resource not found")
+        ... except ClientError as e:
+        ...     print(f"Client error: {e.status_code} - {e.detail}")
+    """
+
+    def __init__(self, status_code: int | None = None, detail: Any = None):
+        self.status_code = status_code
+        self.detail = detail
+        if status_code is not None:
+            super().__init__(f'{status_code}: {detail}')
+        else:
+            super().__init__(str(detail) if detail else '')
+
+    def __repr__(self) -> str:
+        return f'{self.__class__.__name__}(status_code={self.status_code}, detail={self.detail!r})'
+
+
+class ClientConnectionError(ClientError):
+    """Connection failed."""
+
+    def __init__(self, detail: Any = None):
+        super().__init__(status_code=None, detail=detail)
+
+
+class ClientTimeoutError(ClientError):
+    """Request timed out."""
+
+    def __init__(self, detail: Any = None):
+        super().__init__(status_code=408, detail=detail)
+
+
+class HTTPError(ClientError):
+    """HTTP status code error."""
+
+    pass
+
+
+class AuthenticationError(HTTPError):
+    """401 Unauthorized."""
+
+    def __init__(self, detail: Any = None):
+        super().__init__(status_code=401, detail=detail)
+
+
+class AuthorizationError(HTTPError):
+    """403 Forbidden."""
+
+    def __init__(self, detail: Any = None):
+        super().__init__(status_code=403, detail=detail)
+
+
+class NotFoundError(HTTPError):
+    """404 Not Found."""
+
+    def __init__(self, detail: Any = None):
+        super().__init__(status_code=404, detail=detail)
+
+
+class ValidationError(HTTPError):
+    """400/422 Bad Request or Unprocessable Entity."""
+
+    def __init__(self, status_code: int = 400, detail: Any = None):
+        super().__init__(status_code=status_code, detail=detail)
+
+
+class RateLimitError(HTTPError):
+    """429 Too Many Requests."""
+
+    def __init__(self, detail: Any = None):
+        super().__init__(status_code=429, detail=detail)
+
+
+class ServerError(HTTPError):
+    """5xx Server Error."""
+
+    def __init__(self, status_code: int = 500, detail: Any = None):
+        super().__init__(status_code=status_code, detail=detail)
+
+
+class StreamError(ClientError):
+    """Stream processing error."""
+
+    pass
+
+
+class StreamLimitExceededError(StreamError):
+    """Stream limit exceeded."""
+
+    pass
+
+
+class WebSocketError(StreamError):
+    """WebSocket connection error."""
+
+    pass
+
+
+def raise_for_status(status_code: int, detail: Any = None) -> None:
+    """Raise an appropriate exception based on HTTP status code.
+
+    Args:
+        status_code: HTTP status code.
+        detail: Error detail from response.
+
+    Raises:
+        AuthenticationError: For 401 status.
+        AuthorizationError: For 403 status.
+        NotFoundError: For 404 status.
+        ValidationError: For 400 or 422 status.
+        RateLimitError: For 429 status.
+        ServerError: For 5xx status.
+        HTTPError: For other error status codes.
+    """
+    if status_code < 400:
+        return
+
+    if status_code == 401:
+        raise AuthenticationError(detail)
+    elif status_code == 403:
+        raise AuthorizationError(detail)
+    elif status_code == 404:
+        raise NotFoundError(detail)
+    elif status_code in (400, 422):
+        raise ValidationError(status_code, detail)
+    elif status_code == 429:
+        raise RateLimitError(detail)
+    elif status_code >= 500:
+        raise ServerError(status_code, detail)
+    else:
+        raise HTTPError(status_code, detail)

synapse_sdk/integrations/__init__.py

@@ -0,0 +1,74 @@
+"""Framework integrations for automatic logging.
+
+This module provides automatic logging integrations for popular ML frameworks.
+Enable autolog to automatically capture training progress, metrics, and artifacts.
+
+Example:
+    >>> from synapse_sdk.plugins.actions.train import BaseTrainAction
+    >>> from ultralytics import YOLO
+    >>>
+    >>> class TrainAction(BaseTrainAction[TrainParams]):
+    ...     def execute(self):
+    ...         self.autolog('ultralytics')  # Enable autologging
+    ...
+    ...         model = YOLO('yolov8n.pt')   # Callbacks auto-attached
+    ...         model.train(epochs=100)       # Metrics logged automatically
+    ...
+    ...         return TrainResult(...)
+
+Supported frameworks:
+    - ultralytics: YOLO object detection models
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from synapse_sdk.integrations._base import get_integration, list_integrations
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.action import BaseAction
+
+# Import integrations to register them
+from synapse_sdk.integrations import ultralytics as _ultralytics  # noqa: F401
+
+
+def autolog(framework: str, action: BaseAction) -> None:
+    """Enable automatic logging for an ML framework.
+
+    Call this before creating model objects. The SDK will automatically
+    attach callbacks to log progress, metrics, and artifacts.
+
+    Args:
+        framework: Framework name (e.g., 'ultralytics').
+        action: The current action instance (typically `self` in execute()).
+
+    Raises:
+        ValueError: If framework is not recognized.
+        ImportError: If framework package is not installed.
+
+    Example:
+        >>> class TrainAction(BaseTrainAction[TrainParams]):
+        ...     def execute(self):
+        ...         autolog('ultralytics', self)
+        ...         model = YOLO('yolov8n.pt')
+        ...         model.train(epochs=100)
+    """
+    integration = get_integration(framework)
+    integration.enable(action)
+
+
+def disable_autolog(framework: str) -> None:
+    """Disable autologging for a framework.
+
+    Args:
+        framework: Framework name (e.g., 'ultralytics').
+
+    Raises:
+        ValueError: If framework is not recognized.
+    """
+    integration = get_integration(framework)
+    integration.disable()
+
+
+__all__ = ['autolog', 'disable_autolog', 'list_integrations']