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

synapse_sdk/clients/backend/integration.py

@@ -1,63 +1,391 @@
-from synapse_sdk.clients.base import BaseClient
+"""Integration client mixin for plugin, job, and storage operations."""
 
+from __future__ import annotations
 
-class IntegrationClientMixin(BaseClient):
-    def health_check_agent(self, token):
-        path = f'agents/{token}/connect/'
-        return self._post(path)
+from collections.abc import Generator
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
-    def get_plugin(self, pk):
-        path = f'plugins/{pk}/'
-        return self._get(path)
+from synapse_sdk.clients.backend.models import (
+    Agent,
+    PluginReleaseCreateRequest,
+    PluginRunRequest,
+    ServeApplicationCreateRequest,
+    Storage,
+    UpdateJobRequest,
+)
+from synapse_sdk.utils.file.io import convert_file_to_base64
 
-    def create_plugin(self, data):
-        path = 'plugins/'
-        return self._post(path, data=data)
+if TYPE_CHECKING:
+    from synapse_sdk.clients.protocols import ClientProtocol
 
-    def update_plugin(self, pk, data):
-        path = f'plugins/{pk}/'
-        return self._put(path, data=data)
 
-    def run_plugin(self, pk, data):
-        path = f'plugins/{pk}/run/'
-        return self._post(path, data=data)
+class IntegrationClientMixin:
+    """Mixin for integration-related API endpoints.
 
-    def get_plugin_release(self, pk, params=None):
-        path = f'plugin_releases/{pk}/'
-        return self._get(path, params=params)
+    Provides methods for managing plugins, jobs, logs, and serve applications.
+    """
 
-    def create_plugin_release(self, data):
-        path = 'plugin_releases/'
-        files = {'file': data.pop('file')}
-        return self._post(path, data=data, files=files)
+    # -------------------------------------------------------------------------
+    # Agent Operations
+    # -------------------------------------------------------------------------
 
-    def get_job(self, pk, params=None):
-        path = f'jobs/{pk}/'
-        return self._get(path, params=params)
+    def list_agents(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+    ) -> list[Agent]:
+        """List available agents.
 
-    def list_jobs(self, params=None):
-        path = 'jobs/'
-        return self._get(path, params=params)
+        Args:
+            params: Optional query parameters for filtering.
 
-    def update_job(self, pk, data):
-        path = f'jobs/{pk}/'
-        return self._patch(path, data=data)
+        Returns:
+            List of Agent objects.
+        """
+        response = self._get('agents/', params=params)
+        results = response.get('results', [])
+        agents = []
+        for item in results:
+            agent = Agent.model_validate(item)
+            # Extract token from node_install_script if not set
+            if not agent.token:
+                agent.token = agent.extract_token()
+            agents.append(agent)
+        return agents
 
-    def list_job_console_logs(self, pk):
-        path = f'jobs/{pk}/console_logs/'
-        return self._get(path)
+    def health_check_agent(self: ClientProtocol, agent_token: str) -> dict[str, Any]:
+        """Check agent health and connectivity.
 
-    def tail_job_console_logs(self, pk):
-        path = f'jobs/{pk}/tail_console_logs/'
+        Args:
+            agent_token: Agent authentication token.
 
-        url = self._get_url(path)
+        Returns:
+            Agent health status and metadata.
+        """
+        return self._post(f'agents/{agent_token}/connect/')
+
+    # -------------------------------------------------------------------------
+    # Plugin Operations
+    # -------------------------------------------------------------------------
+
+    def get_plugin(self: ClientProtocol, plugin_id: int) -> dict[str, Any]:
+        """Get plugin details by ID.
+
+        Args:
+            plugin_id: Plugin ID.
+
+        Returns:
+            Plugin data including configuration and releases.
+        """
+        return self._get(f'plugins/{plugin_id}/')
+
+    def create_plugin(self: ClientProtocol, data: dict[str, Any]) -> dict[str, Any]:
+        """Create a new plugin.
+
+        Args:
+            data: Plugin creation data (name, category, etc.).
+
+        Returns:
+            Created plugin data.
+        """
+        return self._post('plugins/', data=data)
+
+    def update_plugin(
+        self: ClientProtocol,
+        plugin_id: int,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Update an existing plugin.
+
+        Args:
+            plugin_id: Plugin ID to update.
+            data: Fields to update.
+
+        Returns:
+            Updated plugin data.
+        """
+        return self._put(f'plugins/{plugin_id}/', data=data)
+
+    def run_plugin(
+        self: ClientProtocol,
+        plugin: int | str,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Run a plugin action.
+
+        Args:
+            plugin: Plugin ID or code.
+            data: Run parameters including action, agent, and params.
+
+        Returns:
+            Job data or direct result.
+
+        Example:
+            >>> client.run_plugin('yolov8', {
+            ...     'agent': 1,
+            ...     'action': 'deployment',
+            ...     'params': {'num_cpus': 8},
+            ... })
+        """
+        return self._post(
+            f'plugins/{plugin}/run/',
+            request_model=PluginRunRequest,
+            data=data,
+        )
+
+    # -------------------------------------------------------------------------
+    # Plugin Release Operations
+    # -------------------------------------------------------------------------
+
+    def get_plugin_release(
+        self: ClientProtocol,
+        release_id: int,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Get plugin release details by ID.
+
+        Args:
+            release_id: Plugin release ID.
+            params: Optional query parameters.
+
+        Returns:
+            Plugin release data including config and requirements.
+        """
+        return self._get(f'plugin_releases/{release_id}/', params=params)
+
+    def create_plugin_release(
+        self: ClientProtocol,
+        data: dict[str, Any],
+        *,
+        file: str | Path | None = None,
+    ) -> dict[str, Any]:
+        """Create a new plugin release.
+
+        Args:
+            data: Release data (plugin, version, config, requirements).
+            file: Optional plugin archive file to upload.
+
+        Returns:
+            Created plugin release data.
+
+        Example:
+            >>> client.create_plugin_release(
+            ...     {'plugin': 123, 'version': '1.0.0'},
+            ...     file='/path/to/plugin.zip'
+            ... )
+        """
+        files = None
+        if file is not None:
+            files = {'file': file}
+
+        return self._post(
+            'plugin_releases/',
+            request_model=PluginReleaseCreateRequest,
+            data=data,
+            files=files,
+        )
+
+    # -------------------------------------------------------------------------
+    # Job Operations
+    # -------------------------------------------------------------------------
+
+    def get_job(
+        self: ClientProtocol,
+        job_id: int | str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Get job details by ID.
+
+        Args:
+            job_id: Job ID (integer or UUID string).
+            params: Optional query parameters.
+
+        Returns:
+            Job data including status and progress.
+        """
+        return self._get(f'jobs/{job_id}/', params=params)
+
+    def list_jobs(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """List jobs with optional filtering.
+
+        Args:
+            params: Query parameters (status, plugin, etc.).
+
+        Returns:
+            Paginated job list.
+        """
+        return self._get('jobs/', params=params)
+
+    def update_job(
+        self: ClientProtocol,
+        job_id: int,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Update job status and data.
+
+        Args:
+            job_id: Job ID to update.
+            data: Update payload (status, progress_record, metrics_record, etc.).
+
+        Returns:
+            Updated job data.
+
+        Example:
+            >>> client.update_job(123, {
+            ...     'status': 'running',
+            ...     'progress_record': {'step': 5, 'total': 100}
+            ... })
+        """
+        return self._patch(
+            f'jobs/{job_id}/',
+            request_model=UpdateJobRequest,
+            data=data,
+        )
+
+    def list_job_console_logs(self: ClientProtocol, job_id: int) -> dict[str, Any]:
+        """Get console logs for a job.
+
+        Args:
+            job_id: Job ID.
+
+        Returns:
+            Console log entries.
+        """
+        return self._get(f'jobs/{job_id}/console_logs/')
+
+    def tail_job_console_logs(
+        self: ClientProtocol,
+        job_id: int | str,
+    ) -> Generator[str, None, None]:
+        """Stream console logs for a running job.
+
+        Yields log lines as they become available.
+
+        Args:
+            job_id: Job ID (integer or UUID string) to tail.
+
+        Yields:
+            Log lines as strings.
+
+        Example:
+            >>> for line in client.tail_job_console_logs('abc-123'):
+            ...     print(line)
+        """
+        # Use async endpoint for streaming
+        # The async endpoint is at /async/jobs/{id}/tail_console_logs/
+        base = self.base_url.rstrip('/')
+        url = f'{base}/async/jobs/{job_id}/tail_console_logs/'
         headers = self._get_headers()
 
-        response = self.requests_session.get(url, headers=headers, stream=True)
-        for line in response.iter_lines(decode_unicode=True):
-            if line:
-                yield f'{line}\n'
+        response = self.requests_session.get(
+            url,
+            headers=headers,
+            stream=True,
+            timeout=(self.timeout['connect'], None),  # No read timeout for streaming
+        )
+        response.raise_for_status()
+
+        yield from response.iter_lines(decode_unicode=True)
+
+    # -------------------------------------------------------------------------
+    # Log Operations
+    # -------------------------------------------------------------------------
+
+    def create_logs(
+        self: ClientProtocol,
+        data: dict[str, Any] | list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Create log entries with optional file attachments.
+
+        File fields are automatically converted to base64 data URIs.
+
+        Args:
+            data: Single log entry or list of entries.
+
+        Returns:
+            Created log entries response.
+
+        Example:
+            >>> client.create_logs({
+            ...     'message': 'Training complete',
+            ...     'level': 'info',
+            ...     'file': '/path/to/result.png'  # Auto-converted to base64
+            ... })
+        """
+        # Normalize to list
+        items = data if isinstance(data, list) else [data]
+
+        # Convert file fields to base64
+        for item in items:
+            if 'file' in item and item['file']:
+                file_path = item['file']
+                if not isinstance(file_path, str) or not file_path.startswith('data:'):
+                    item['file'] = convert_file_to_base64(file_path)
+
+        return self._post('logs/', data=items if len(items) > 1 else items[0])
+
+    # -------------------------------------------------------------------------
+    # Serve Application Operations
+    # -------------------------------------------------------------------------
+
+    def create_serve_application(
+        self: ClientProtocol,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Create a Ray Serve application.
+
+        Args:
+            data: Application config (name, plugin_release, action, params).
+
+        Returns:
+            Created serve application data.
+        """
+        return self._post(
+            'serve_applications/',
+            request_model=ServeApplicationCreateRequest,
+            data=data,
+        )
+
+    def list_serve_applications(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+        *,
+        list_all: bool = False,
+    ) -> dict[str, Any] | tuple[Any, int]:
+        """List Ray Serve applications.
+
+        Args:
+            params: Query parameters for filtering.
+            list_all: If True, returns (generator, count).
+
+        Returns:
+            Paginated list or (generator, count).
+        """
+        return self._list('serve_applications/', params=params, list_all=list_all)
+
+    # -------------------------------------------------------------------------
+    # Storage Operations
+    # -------------------------------------------------------------------------
+
+    def get_storage(self: ClientProtocol, storage_id: int) -> Storage:
+        """Get storage configuration by ID.
+
+        Args:
+            storage_id: Storage ID.
+
+        Returns:
+            Storage model with provider configuration.
+        """
+        response = self._get(
+            f'storages/{storage_id}/',
+            params={'with_configuration': 'true'},
+        )
+        return Storage.model_validate(response)
+
 
-    def create_logs(self, data):
-        path = 'logs/'
-        return self._post(path, data=data)
+__all__ = ['IntegrationClientMixin']

synapse_sdk/clients/backend/ml.py

@@ -1,29 +1,141 @@
-from synapse_sdk.clients.base import BaseClient
-from synapse_sdk.clients.utils import get_default_url_conversion
+"""ML client mixin for model and ground truth operations."""
 
+from __future__ import annotations
 
-class MLClientMixin(BaseClient):
-    def list_models(self, params=None):
-        path = 'models/'
-        return self._get(path, params=params)
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
-    def get_model(self, pk, params=None, url_conversion=None):
-        path = f'models/{pk}/'
-        url_conversion = get_default_url_conversion(
-            url_conversion, files_fields=['files', 'parent.files'], is_list=False
+from synapse_sdk.clients.backend.models import ModelCreateRequest
+
+if TYPE_CHECKING:
+    from synapse_sdk.clients.protocols import ClientProtocol
+
+
+class MLClientMixin:
+    """Mixin for ML-related API endpoints.
+
+    Provides methods for managing models and ground truth data.
+    """
+
+    def list_models(
+        self: ClientProtocol,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """List models with optional filtering.
+
+        Args:
+            params: Query parameters for filtering.
+
+        Returns:
+            Paginated model list.
+        """
+        return self._get('models/', params=params)
+
+    def get_model(
+        self: ClientProtocol,
+        model_id: int,
+        *,
+        params: dict[str, Any] | None = None,
+        url_conversion: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Get model details by ID.
+
+        Args:
+            model_id: Model ID.
+            params: Optional query parameters.
+            url_conversion: URL-to-path conversion config.
+
+        Returns:
+            Model data including file URL and metadata.
+        """
+        if url_conversion is None:
+            url_conversion = {'files_fields': ['file'], 'is_list': False}
+
+        return self._get(
+            f'models/{model_id}/',
+            params=params,
+            url_conversion=url_conversion,
+        )
+
+    def create_model(
+        self: ClientProtocol,
+        data: dict[str, Any],
+        *,
+        file: str | Path | None = None,
+    ) -> dict[str, Any]:
+        """Create a new model with file upload.
+
+        Large files are automatically uploaded using chunked upload.
+
+        Args:
+            data: Model metadata (name, plugin, version, etc.).
+            file: Model file to upload (uses chunked upload).
+
+        Returns:
+            Created model data.
+
+        Example:
+            >>> client.create_model(
+            ...     {'name': 'My Model', 'plugin': 123},
+            ...     file='/path/to/model.pt'
+            ... )
+        """
+        # Handle file upload via chunked upload
+        if file is not None:
+            path = Path(file)
+            if not path.exists():
+                raise FileNotFoundError(f'Model file not found: {path}')
+
+            # Upload file in chunks
+            upload_result = self.create_chunked_upload(path)
+            data['chunked_upload'] = upload_result['id']
+
+        return self._post(
+            'models/',
+            request_model=ModelCreateRequest,
+            data=data,
         )
-        return self._get(path, params=params, url_conversion=url_conversion)
 
-    def create_model(self, data):
-        path = 'models/'
-        files = {'file': data.pop('file')}
-        return self._post(path, data=data, files=files)
+    def list_ground_truth_events(
+        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 ground truth events.
+
+        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/ground_truth_events/',
+            params=params,
+            url_conversion=url_conversion,
+            list_all=list_all,
+        )
+
+    def get_ground_truth_version(
+        self: ClientProtocol,
+        version_id: int,
+    ) -> dict[str, Any]:
+        """Get ground truth dataset version by ID.
+
+        Args:
+            version_id: Version ID.
+
+        Returns:
+            Version data including file manifest.
+        """
+        return self._get(f'ground_truth_dataset_versions/{version_id}/')
 
-    def create_serve_application(self, data):
-        path = 'serve_applications/'
-        return self._post(path, data=data)
 
-    def list_ground_truth_events(self, params=None, url_conversion=None, list_all=False):
-        path = 'ground_truth_events/'
-        url_conversion = get_default_url_conversion(url_conversion, files_fields=['files'])
-        return self._list(path, params=params, url_conversion=url_conversion, list_all=list_all)
+__all__ = ['MLClientMixin']