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

synapse_sdk/clients/backend/annotation.py

@@ -1,29 +1,171 @@
-from synapse_sdk.clients.base import BaseClient
-from synapse_sdk.clients.utils import get_default_url_conversion
+"""Annotation client mixin for project and task operations."""
 
+from __future__ import annotations
 
-class AnnotationClientMixin(BaseClient):
-    def get_project(self, pk):
-        path = f'projects/{pk}/'
-        return self._get(path)
+from typing import TYPE_CHECKING, Any
 
-    def get_task_tag(self, pk):
-        path = f'task_tags/{pk}/'
-        return self._get(path)
+from synapse_sdk.clients.backend.models import SetTagsRequest, TaskCreateRequest
 
-    def list_task_tags(self, data):
-        path = 'task_tags/'
-        return self._list(path, data=data)
+if TYPE_CHECKING:
+    from synapse_sdk.clients.protocols import ClientProtocol
 
-    def list_tasks(self, data, url_conversion=None, list_all=False):
-        path = 'tasks/'
-        url_conversion = get_default_url_conversion(url_conversion, files_fields=['files'])
-        return self._list(path, data=data, url_conversion=url_conversion, list_all=list_all)
 
-    def create_tasks(self, data):
-        path = 'tasks/'
-        return self._post(path, data=data)
+class AnnotationClientMixin:
+    """Mixin for annotation-related API endpoints.
 
-    def set_tags_tasks(self, data, params=None):
-        path = 'tasks/set_tags/'
-        return self._post(path, data=data, params=params)
+    Provides methods for managing projects, tasks, and task tags.
+    """
+
+    def get_project(self: ClientProtocol, project_id: int) -> dict[str, Any]:
+        """Get project details by ID.
+
+        Args:
+            project_id: Project ID.
+
+        Returns:
+            Project data including configuration and statistics.
+        """
+        return self._get(f'projects/{project_id}/')
+
+    def get_task(
+        self: ClientProtocol,
+        task_id: int,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Get task details by ID.
+
+        Args:
+            task_id: Task ID.
+            params: Optional query parameters (e.g., expand, fields).
+
+        Returns:
+            Task data including annotations and metadata.
+        """
+        return self._get(f'tasks/{task_id}/', params=params)
+
+    def annotate_task_data(
+        self: ClientProtocol,
+        task_id: int,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Submit annotation data for a task.
+
+        Args:
+            task_id: Task ID to annotate.
+            data: Annotation data payload.
+
+        Returns:
+            Updated task data.
+        """
+        return self._put(f'tasks/{task_id}/annotate_task_data/', data=data)
+
+    def get_task_tag(self: ClientProtocol, tag_id: int) -> dict[str, Any]:
+        """Get task tag details by ID.
+
+        Args:
+            tag_id: Tag ID.
+
+        Returns:
+            Tag data including name and color.
+        """
+        return self._get(f'task_tags/{tag_id}/')
+
+    def list_task_tags(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """List available task tags.
+
+        Args:
+            params: Optional query parameters for filtering.
+
+        Returns:
+            Paginated list of task tags.
+        """
+        return self._get('task_tags/', params=params)
+
+    def list_tasks(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+        *,
+        url_conversion: dict[str, Any] | None = None,
+        list_all: bool = False,
+    ) -> dict[str, Any] | tuple[Any, int]:
+        """List tasks with optional pagination.
+
+        Args:
+            params: Query parameters for filtering (project, status, etc.).
+            url_conversion: URL-to-path conversion config for file fields.
+            list_all: If True, returns (generator, count) for all results.
+
+        Returns:
+            Paginated task list, or (generator, count) if list_all=True.
+
+        Example:
+            >>> # Get first page
+            >>> tasks = client.list_tasks({'project': 123})
+            >>> # Get all tasks as generator
+            >>> tasks_gen, count = client.list_tasks({'project': 123}, list_all=True)
+        """
+        if url_conversion is None:
+            url_conversion = {'files_fields': ['files']}
+
+        return self._list(
+            'sdk/tasks/',
+            params=params,
+            url_conversion=url_conversion,
+            list_all=list_all,
+        )
+
+    def create_tasks(
+        self: ClientProtocol,
+        data: dict[str, Any] | list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Create one or more annotation tasks.
+
+        Args:
+            data: Task data or list of task data.
+
+        Returns:
+            Created task(s) response.
+
+        Example:
+            >>> client.create_tasks({
+            ...     'project': 123,
+            ...     'data': [{'image': 'path/to/image.jpg'}]
+            ... })
+        """
+        return self._post('tasks/', request_model=TaskCreateRequest, data=data)
+
+    def set_tags_tasks(
+        self: ClientProtocol,
+        data: dict[str, Any],
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Set tags on multiple tasks.
+
+        Args:
+            data: Tag assignment data with 'ids', 'tags', and 'action'.
+            params: Optional query parameters.
+
+        Returns:
+            Operation result.
+
+        Example:
+            >>> client.set_tags_tasks({
+            ...     'ids': [1, 2, 3],
+            ...     'tags': [10, 20],
+            ...     'action': 'add'  # or 'remove'
+            ... })
+        """
+        return self._post(
+            'tasks/set_tags/',
+            request_model=SetTagsRequest,
+            data=data,
+            params=params,
+        )
+
+
+__all__ = ['AnnotationClientMixin']

synapse_sdk/clients/backend/core.py

@@ -0,0 +1,101 @@
+"""Core backend client mixin with chunked upload support."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from synapse_sdk.clients.backend.models import (
+    ChunkedUploadFinalizeResponse,
+    ChunkedUploadResponse,
+)
+from synapse_sdk.utils.file.io import DEFAULT_CHUNK_SIZE, read_file_in_chunks
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from synapse_sdk.clients.protocols import ClientProtocol
+
+
+class CoreClientMixin:
+    """Mixin providing chunked upload functionality.
+
+    Supports resumable uploads with MD5 integrity verification.
+    Files are uploaded in 50MB chunks by default.
+    """
+
+    def create_chunked_upload(
+        self: ClientProtocol,
+        file_path: str | Path,
+        *,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> dict[str, Any]:
+        """Upload a file in chunks with MD5 integrity verification.
+
+        Files are uploaded in configurable chunks (default 50MB) with
+        Content-Range headers for resumable uploads. MD5 hash is calculated
+        incrementally during upload and verified on finalization.
+
+        Args:
+            file_path: Path to the file to upload.
+            chunk_size: Size of each chunk in bytes (default 50MB).
+            on_progress: Optional callback(bytes_uploaded, total_bytes) for progress.
+
+        Returns:
+            Finalized upload response with file ID and checksum.
+
+        Raises:
+            FileNotFoundError: If file doesn't exist.
+            ClientError: If upload fails.
+
+        Example:
+            >>> def progress(uploaded, total):
+            ...     print(f'{uploaded}/{total} bytes')
+            >>> result = client.create_chunked_upload('/path/to/file.zip', on_progress=progress)
+            >>> result['id']
+            123
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f'File not found: {path}')
+
+        total_size = os.path.getsize(path)
+        hash_md5 = hashlib.md5()
+
+        # Initial upload URL
+        url = 'chunked_upload/'
+        offset = 0
+
+        # Upload each chunk
+        for chunk in read_file_in_chunks(path, chunk_size):
+            hash_md5.update(chunk)
+
+            response = self._put(
+                url,
+                data={'filename': path.name},
+                files={'file': ('chunk', chunk)},
+                headers={'Content-Range': f'bytes {offset}-{offset + len(chunk) - 1}/{total_size}'},
+            )
+
+            # Validate response
+            chunk_response = ChunkedUploadResponse.model_validate(response)
+            offset = chunk_response.offset
+            url = chunk_response.url
+
+            # Progress callback
+            if on_progress:
+                on_progress(offset, total_size)
+
+        # Finalize with MD5 checksum
+        result = self._post(url, data={'md5': hash_md5.hexdigest()})
+
+        # Validate final response
+        ChunkedUploadFinalizeResponse.model_validate(result)
+
+        return result
+
+
+__all__ = ['CoreClientMixin']

synapse_sdk/clients/backend/data_collection.py

@@ -0,0 +1,292 @@
+"""Data collection client mixin for dataset management."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from synapse_sdk.clients.backend.models import DataFileResponse, DataUnitCreateRequest
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from synapse_sdk.clients.protocols import ClientProtocol
+
+
+# Auto-use chunked upload for files larger than 50MB
+CHUNKED_UPLOAD_THRESHOLD = 1024 * 1024 * 50
+
+
+def _batch_list(items: list, batch_size: int) -> list[list]:
+    """Split a list into batches of specified size."""
+    return [items[i : i + batch_size] for i in range(0, len(items), batch_size)]
+
+
+class DataCollectionClientMixin:
+    """Mixin for data collection API endpoints.
+
+    Provides methods for managing data collections, files, and units.
+    """
+
+    def list_data_collections(self: ClientProtocol) -> dict[str, Any]:
+        """List all data collections.
+
+        Returns:
+            Paginated list of data collections.
+        """
+        return self._get('data_collections/')
+
+    def get_data_collection(
+        self: ClientProtocol,
+        collection_id: int,
+    ) -> dict[str, Any]:
+        """Get data collection details by ID.
+
+        Automatically expands file specifications.
+
+        Args:
+            collection_id: Data collection ID.
+
+        Returns:
+            Collection data including file specifications.
+        """
+        return self._get(
+            f'data_collections/{collection_id}/',
+            params={'expand': 'file_specifications'},
+        )
+
+    def create_data_file(
+        self: ClientProtocol,
+        file_path: str | Path,
+        *,
+        use_chunked_upload: bool | None = None,
+    ) -> dict[str, Any]:
+        """Upload a data file.
+
+        Automatically uses chunked upload for files >50MB unless
+        explicitly specified.
+
+        Args:
+            file_path: Path to the file to upload.
+            use_chunked_upload: Force chunked (True) or direct (False) upload.
+                None = auto-detect based on file size.
+
+        Returns:
+            File data with ID, checksum, and size.
+
+        Raises:
+            FileNotFoundError: If file doesn't exist.
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f'File not found: {path}')
+
+        # Auto-detect upload method based on file size
+        if use_chunked_upload is None:
+            use_chunked_upload = path.stat().st_size > CHUNKED_UPLOAD_THRESHOLD
+
+        if use_chunked_upload:
+            upload_result = self.create_chunked_upload(path)
+            response = self._post(
+                'data_files/',
+                data={'chunked_upload': upload_result['id']},
+            )
+        else:
+            response = self._post('data_files/', files={'file': path})
+
+        DataFileResponse.model_validate(response)
+        return response
+
+    def get_data_unit(
+        self: ClientProtocol,
+        unit_id: int,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Get data unit details by ID.
+
+        Args:
+            unit_id: Data unit ID.
+            params: Optional query parameters.
+
+        Returns:
+            Data unit with files and metadata.
+        """
+        return self._get(f'data_units/{unit_id}/', params=params)
+
+    def create_data_units(
+        self: ClientProtocol,
+        data: dict[str, Any] | list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Create data unit bindings.
+
+        Links uploaded files to a data collection.
+
+        Args:
+            data: Data unit(s) to create.
+
+        Returns:
+            Created data unit(s).
+        """
+        return self._post(
+            'data_units/',
+            request_model=DataUnitCreateRequest,
+            data=data,
+        )
+
+    def list_data_units(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+        *,
+        url_conversion: dict[str, Any] | None = None,
+        list_all: bool = False,
+        page_size: int = 100,
+        timeout: int = 60,
+    ) -> dict[str, Any] | tuple[Any, int]:
+        """List data units with optional pagination.
+
+        Args:
+            params: Query parameters for filtering.
+            url_conversion: URL-to-path conversion config.
+            list_all: If True, returns (generator, count).
+            page_size: Number of items per page. Default 100 (larger pages
+                reduce API calls; timeout increased to handle heavy payloads).
+            timeout: Read timeout in seconds. Default 60 (longer timeout
+                for large page sizes with heavy file metadata).
+
+        Returns:
+            Paginated list or (generator, count).
+        """
+        if url_conversion is None:
+            url_conversion = {'files_fields': ['files']}
+
+        if params is None:
+            params = {}
+        params.setdefault('page_size', page_size)
+
+        return self._list(
+            'data_units/',
+            params=params,
+            url_conversion=url_conversion,
+            list_all=list_all,
+            timeout=(5, timeout),  # (connect_timeout, read_timeout)
+        )
+
+    def verify_data_files_checksums(
+        self: ClientProtocol,
+        checksums: list[str],
+    ) -> dict[str, Any]:
+        """Verify if data files with given checksums exist.
+
+        Args:
+            checksums: List of MD5 checksums to verify.
+
+        Returns:
+            Verification result with existing checksums.
+        """
+        return self._post('data_files/verify_checksums/', data={'checksums': checksums})
+
+    def upload_data_file(
+        self: ClientProtocol,
+        data: dict[str, Any],
+        collection_id: int,
+        *,
+        use_chunked_upload: bool | None = None,
+    ) -> dict[str, Any]:
+        """Upload individual files for a data unit and return binding data.
+
+        Args:
+            data: Data unit definition with 'files' dict mapping names to paths.
+            collection_id: Target data collection ID.
+            use_chunked_upload: Force chunked (True) or direct (False) upload.
+
+        Returns:
+            Data ready for create_data_units() with checksums.
+
+        Example:
+            >>> result = client.upload_data_file(
+            ...     {'files': {'image': '/path/to/img.jpg'}, 'meta': {'label': 1}},
+            ...     collection_id=123
+            ... )
+            >>> # result['files']['image']['checksum'] is populated
+        """
+        files_data = {}
+
+        for name, file_path in data.get('files', {}).items():
+            if isinstance(file_path, str):
+                path = Path(file_path)
+            else:
+                path = file_path
+
+            upload_result = self.create_data_file(path, use_chunked_upload=use_chunked_upload)
+
+            files_data[name] = {
+                'checksum': upload_result['checksum'],
+                'path': str(path),
+            }
+
+        return {
+            'files': files_data,
+            'data_collection': collection_id,
+            'meta': data.get('meta', {}),
+        }
+
+    def upload_data_collection(
+        self: ClientProtocol,
+        collection_id: int,
+        data: list[dict[str, Any]],
+        *,
+        project_id: int | None = None,
+        batch_size: int = 1000,
+        max_workers: int = 10,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> None:
+        """Bulk upload data to a collection.
+
+        Uploads files in parallel using a thread pool, then creates
+        data units in batches. Optionally creates annotation tasks.
+
+        Args:
+            collection_id: Target data collection ID.
+            data: List of data unit definitions.
+            project_id: Optional project ID to create tasks for.
+            batch_size: Number of data units per batch (default 1000).
+            max_workers: Number of parallel upload threads (default 10).
+            on_progress: Optional callback(completed, total) for progress.
+
+        Example:
+            >>> data = [
+            ...     {'files': {'image': '/path/1.jpg'}, 'meta': {'label': 'cat'}},
+            ...     {'files': {'image': '/path/2.jpg'}, 'meta': {'label': 'dog'}},
+            ... ]
+            >>> client.upload_data_collection(123, data, project_id=456)
+        """
+        total = len(data)
+        completed = 0
+        upload_results: list[dict[str, Any]] = []
+
+        # Upload files in parallel
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {executor.submit(self.upload_data_file, item, collection_id): i for i, item in enumerate(data)}
+
+            for future in as_completed(futures):
+                result = future.result()
+                upload_results.append(result)
+                completed += 1
+
+                if on_progress:
+                    on_progress(completed, total)
+
+        # Create data units in batches
+        for batch in _batch_list(upload_results, batch_size):
+            created_units = self.create_data_units(batch)
+
+            # Optionally create tasks
+            if project_id is not None:
+                task_data = [{'data_unit': unit['id']} for unit in created_units.get('results', [created_units])]
+                if task_data:
+                    self._post('tasks/', data={'project': project_id, 'data': task_data})
+
+
+__all__ = ['DataCollectionClientMixin']

synapse_sdk/clients/backend/hitl.py

@@ -0,0 +1,87 @@
+"""HITL (Human-in-the-Loop) client mixin for assignment operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from synapse_sdk.clients.backend.models import SetTagsRequest
+
+if TYPE_CHECKING:
+    from synapse_sdk.clients.protocols import ClientProtocol
+
+
+class HITLClientMixin:
+    """Mixin for HITL-related API endpoints.
+
+    Provides methods for managing annotation assignments.
+    """
+
+    def get_assignment(self: ClientProtocol, assignment_id: int) -> dict[str, Any]:
+        """Get assignment details by ID.
+
+        Args:
+            assignment_id: Assignment ID.
+
+        Returns:
+            Assignment data including task and annotator info.
+        """
+        return self._get(f'assignments/{assignment_id}/')
+
+    def list_assignments(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+        *,
+        url_conversion: dict[str, Any] | None = None,
+        list_all: bool = False,
+    ) -> dict[str, Any] | tuple[Any, int]:
+        """List assignments with optional pagination.
+
+        Args:
+            params: Query parameters for filtering.
+            url_conversion: URL-to-path conversion config.
+            list_all: If True, returns (generator, count).
+
+        Returns:
+            Paginated list or (generator, count).
+        """
+        if url_conversion is None:
+            url_conversion = {'files_fields': ['files']}
+
+        return self._list(
+            'sdk/assignments/',
+            params=params,
+            url_conversion=url_conversion,
+            list_all=list_all,
+        )
+
+    def set_tags_assignments(
+        self: ClientProtocol,
+        data: dict[str, Any],
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Set tags on multiple assignments.
+
+        Args:
+            data: Tag assignment data with 'ids', 'tags', and 'action'.
+            params: Optional query parameters.
+
+        Returns:
+            Operation result.
+
+        Example:
+            >>> client.set_tags_assignments({
+            ...     'ids': [1, 2, 3],
+            ...     'tags': [10, 20],
+            ...     'action': 'add'  # or 'remove'
+            ... })
+        """
+        return self._post(
+            'assignments/set_tags/',
+            request_model=SetTagsRequest,
+            data=data,
+            params=params,
+        )
+
+
+__all__ = ['HITLClientMixin']