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

synapse_sdk/cli/plugin/test.py

@@ -0,0 +1,200 @@
+"""Plugin local test command implementation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+from rich.console import Console
+
+
+@dataclass
+class TestResult:
+    """Result of plugin test execution."""
+
+    action: str
+    plugin: str
+    result: Any
+    mode: str
+    job_id: str | None = None
+
+
+def test_plugin(
+    action: str,
+    console: Console,
+    *,
+    path: Path,
+    params: dict[str, Any] | None = None,
+    mode: Literal['local', 'task', 'job'] = 'local',
+    ray_address: str = 'auto',
+    num_gpus: int | None = None,
+    num_cpus: int | None = None,
+    job_id: str | None = None,
+    env: dict[str, Any] | None = None,
+    include_sdk: bool = False,
+) -> TestResult:
+    """Execute plugin action for testing.
+
+    Args:
+        action: Action name to execute (e.g., test, train).
+        console: Rich console.
+        path: Plugin directory path.
+        params: Optional parameters to pass to the action.
+        mode: Execution mode:
+            - 'local': In-process execution (best for debugging)
+            - 'task': Ray Actor execution (no log streaming)
+            - 'job': Ray Jobs API with log streaming (recommended for remote)
+        ray_address: Ray cluster address (for 'task'/'job' modes).
+        num_gpus: Number of GPUs to request.
+        num_cpus: Number of CPUs to request.
+        job_id: Optional job identifier for tracking.
+        env: Environment variables to pass.
+
+    Returns:
+        TestResult with action result.
+
+    Raises:
+        ActionNotFoundError: If action doesn't exist.
+        ExecutionError: If execution fails.
+    """
+    import sys
+
+    from synapse_sdk.plugins.discovery import PluginDiscovery
+
+    # Add plugin directory to sys.path so entrypoints like 'plugin.test.TestAction' can be imported
+    path_str = str(path)
+    if path_str not in sys.path:
+        sys.path.insert(0, path_str)
+
+    # Discover plugin
+    discovery = PluginDiscovery.from_path(path)
+    config = discovery.config
+    plugin_code = config.code
+
+    # Merge env: CLI env takes precedence over config env
+    merged_env = {**config.env, **(env or {})}
+
+    console.print(f'[dim]Plugin:[/dim] {plugin_code}')
+    console.print(f'[dim]Action:[/dim] {action}')
+    console.print(f'[dim]Mode:[/dim] {mode}')
+
+    params = params or {}
+
+    if mode == 'local':
+        from synapse_sdk.plugins.executors.local import LocalExecutor
+
+        console.print()
+
+        # Get action class (local import works since we're in-process)
+        action_cls = discovery.get_action_class(action)
+
+        executor = LocalExecutor(env=merged_env, job_id=job_id)
+        result = executor.execute(action_cls, params)
+
+        return TestResult(
+            action=action,
+            plugin=plugin_code,
+            result=result,
+            mode=mode,
+        )
+
+    elif mode == 'task':
+        from synapse_sdk.plugins.executors.ray.task import RayActorExecutor
+
+        if num_gpus is not None:
+            console.print(f'[dim]GPUs:[/dim] {num_gpus}')
+        if num_cpus is not None:
+            console.print(f'[dim]CPUs:[/dim] {num_cpus}')
+        console.print()
+
+        # Get entrypoint string (don't load class locally - it runs on remote Ray worker)
+        entrypoint = discovery.get_action_entrypoint(action)
+
+        executor = RayActorExecutor(
+            working_dir=path,
+            ray_address=ray_address,
+            num_gpus=num_gpus,
+            num_cpus=num_cpus,
+            env=merged_env,
+            job_id=job_id,
+            include_sdk=include_sdk,
+            package_manager=config.package_manager,
+            package_manager_options=config.package_manager_options or None,
+            wheels_dir=config.wheels_dir,
+            runtime_env=config.runtime_env or None,
+        )
+
+        try:
+            result = executor.execute(entrypoint, params)
+        finally:
+            executor.shutdown()
+
+        return TestResult(
+            action=action,
+            plugin=plugin_code,
+            result=result,
+            mode=mode,
+        )
+
+    else:  # mode == 'job' (or 'jobs-api' alias)
+        from synapse_sdk.plugins.executors.ray.jobs_api import RayJobsApiExecutor
+
+        # Derive dashboard address from ray_address
+        if ray_address.startswith('ray://'):
+            from urllib.parse import urlparse
+
+            parsed = urlparse(ray_address)
+            dashboard_addr = f'http://{parsed.hostname}:8265'
+        else:
+            dashboard_addr = 'http://localhost:8265'
+
+        console.print(f'[dim]Dashboard:[/dim] {dashboard_addr}')
+        if num_gpus is not None:
+            console.print(f'[dim]GPUs:[/dim] {num_gpus}')
+        if num_cpus is not None:
+            console.print(f'[dim]CPUs:[/dim] {num_cpus}')
+        console.print()
+
+        # Get entrypoint string (don't load class locally - it runs on remote Ray worker)
+        entrypoint = discovery.get_action_entrypoint(action)
+
+        executor = RayJobsApiExecutor(
+            dashboard_address=dashboard_addr,
+            working_dir=path,
+            num_gpus=num_gpus,
+            num_cpus=num_cpus,
+            env=merged_env,
+            include_sdk=include_sdk,
+            package_manager=config.package_manager,
+            package_manager_options=config.package_manager_options or None,
+        )
+
+        # Submit job via Ray Jobs API
+        submitted_job_id = executor.submit(entrypoint, params, job_id=job_id)
+
+        console.print(f'[dim]Job submitted:[/dim] {submitted_job_id}')
+        console.print('[dim]Streaming logs (Ctrl+C to stop watching)...[/dim]')
+        console.print()
+
+        # Stream logs in real-time
+        try:
+            for log_line in executor.stream_logs(submitted_job_id):
+                console.print(log_line, end='')
+        except KeyboardInterrupt:
+            console.print('\n[dim]Stopped watching logs.[/dim]')
+
+        # Get final result
+        result = executor.get_result(submitted_job_id, timeout=30)
+        console.print('\n[dim]Status:[/dim] SUCCEEDED')
+
+        return TestResult(
+            action=action,
+            plugin=plugin_code,
+            result=result,
+            mode=mode,
+            job_id=submitted_job_id,
+        )
+
+
+__all__ = ['TestResult', 'test_plugin']

synapse_sdk/clients/README.md

@@ -0,0 +1,239 @@
+# Synapse SDK Clients
+
+HTTP client module providing both synchronous (sync) and asynchronous (async) API clients.
+
+## Architecture Overview
+
+```
+synapse_sdk/clients/
+├── __init__.py          # Public API exports
+├── base.py              # BaseClient, AsyncBaseClient
+├── protocols.py         # ClientProtocol, AsyncClientProtocol
+├── utils.py             # Shared utility functions
+├── validation.py        # ValidationMixin
+├── exceptions.py        # Exception re-exports
+├── _template.py         # New client template
+├── agent/               # Agent API clients
+│   ├── __init__.py      # AgentClient, AsyncAgentClient
+│   ├── ray.py           # RayClientMixin
+│   ├── async_ray.py     # AsyncRayClientMixin
+│   ├── container.py     # ContainerClientMixin
+│   └── plugin.py        # PluginClientMixin
+└── backend/             # Backend API clients
+    ├── __init__.py      # BackendClient
+    ├── annotation.py    # AnnotationClientMixin
+    ├── core.py          # CoreClientMixin
+    ├── data_collection.py
+    ├── hitl.py
+    ├── integration.py
+    ├── ml.py
+    └── models.py        # Pydantic models
+```
+
+## Module Structure
+
+### base.py
+
+- `BaseClient`: Synchronous HTTP client based on requests
+- `AsyncBaseClient`: Asynchronous HTTP client based on httpx
+- Inherits `ValidationMixin` for Pydantic validation support
+
+### protocols.py
+
+- `ClientProtocol`: Synchronous client protocol
+- `AsyncClientProtocol`: Asynchronous client protocol
+- `@runtime_checkable` decorator enables runtime type checking
+
+### utils.py
+
+- `build_url()`: URL composition utility
+- `extract_error_detail()`: Extract error details from response
+- `parse_json_response()`: Parse JSON response
+
+### validation.py
+
+- `ValidationMixin`: Provides Pydantic validation methods
+  - `_validate_response()`: Validate response data
+  - `_validate_request()`: Validate request data
+
+## Protocol-based Mixin Pattern
+
+Use `ClientProtocol` as the `self` type hint in mixin classes:
+
+```python
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synapse_sdk.clients.protocols import ClientProtocol
+
+class MyMixin:
+    def get_something(self: ClientProtocol) -> dict:
+        # IDE autocompletion supported
+        return self._get('something/')
+```
+
+### Why Use Protocol?
+
+1. **IDE Autocompletion**: Using `self: ClientProtocol` instead of `self: BaseClient` allows IDE to recognize methods like `_get`, `_post`, etc.
+2. **Avoid Circular Imports**: Import only within `TYPE_CHECKING` block to prevent runtime circular dependencies
+3. **Flexible Type Checking**: Supports structural typing without actual class inheritance
+
+## Exception Hierarchy
+
+```
+ClientError (base)
+├── ClientConnectionError  # Connection failure
+├── ClientTimeoutError     # Timeout
+├── HTTPError              # HTTP status code errors
+│   ├── AuthenticationError (401)
+│   ├── AuthorizationError (403)
+│   ├── NotFoundError (404)
+│   ├── ValidationError (400/422)
+│   ├── RateLimitError (429)
+│   └── ServerError (5xx)
+└── StreamError            # Streaming errors
+    ├── StreamLimitExceededError
+    └── WebSocketError
+```
+
+### Exception Usage Example
+
+```python
+from synapse_sdk.exceptions import (
+    ClientError,
+    NotFoundError,
+    AuthenticationError,
+)
+
+try:
+    result = client.get_resource(123)
+except NotFoundError:
+    print("Resource not found")
+except AuthenticationError:
+    print("Authentication failed")
+except ClientError as e:
+    print(f"Client error: {e.status_code}")
+```
+
+## Guide for Adding New Clients
+
+### 1. Copy Template
+
+Create a new client by referencing `_template.py`:
+
+```python
+from synapse_sdk.clients.base import BaseClient
+
+class MyApiClient(BaseClient):
+    name = 'MyAPI'
+
+    def __init__(self, base_url: str, api_key: str, **kwargs):
+        super().__init__(base_url, **kwargs)
+        self.api_key = api_key
+
+    def _get_headers(self) -> dict[str, str]:
+        return {'X-API-Key': self.api_key}
+
+    def get_resource(self, resource_id: int) -> dict:
+        return self._get(f'resources/{resource_id}/')
+```
+
+### 2. Use Mixin Pattern (Optional)
+
+For large APIs, separate functionality into mixins:
+
+```python
+# my_api/users.py
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synapse_sdk.clients.protocols import ClientProtocol
+
+class UsersMixin:
+    def list_users(self: ClientProtocol) -> list[dict]:
+        return self._get('users/')
+
+    def get_user(self: ClientProtocol, user_id: int) -> dict:
+        return self._get(f'users/{user_id}/')
+
+# my_api/__init__.py
+from synapse_sdk.clients.base import BaseClient
+from my_api.users import UsersMixin
+
+class MyApiClient(UsersMixin, BaseClient):
+    name = 'MyAPI'
+    # ...
+```
+
+### 3. Pydantic Model Validation
+
+Use Pydantic models for request/response validation:
+
+```python
+from pydantic import BaseModel
+
+class UserCreate(BaseModel):
+    name: str
+    email: str
+
+class UserResponse(BaseModel):
+    id: int
+    name: str
+    email: str
+
+class MyApiClient(BaseClient):
+    def create_user(self, data: dict) -> dict:
+        return self._post(
+            'users/',
+            request_model=UserCreate,
+            response_model=UserResponse,
+            data=data,
+        )
+```
+
+### 4. Async Client Implementation
+
+```python
+from synapse_sdk.clients.base import AsyncBaseClient
+
+class AsyncMyApiClient(AsyncBaseClient):
+    name = 'MyAPI'
+
+    def __init__(self, base_url: str, api_key: str, **kwargs):
+        super().__init__(base_url, **kwargs)
+        self.api_key = api_key
+
+    def _get_headers(self) -> dict[str, str]:
+        return {'X-API-Key': self.api_key}
+
+    async def get_resource(self, resource_id: int) -> dict:
+        return await self._get(f'resources/{resource_id}/')
+
+# Usage
+async with AsyncMyApiClient(base_url, api_key) as client:
+    result = await client.get_resource(123)
+```
+
+## Method Reference
+
+### BaseClient / AsyncBaseClient
+
+| Method                 | Description                  |
+| ---------------------- | ---------------------------- |
+| `_get(path, ...)`      | GET request                  |
+| `_post(path, ...)`     | POST request                 |
+| `_put(path, ...)`      | PUT request                  |
+| `_patch(path, ...)`    | PATCH request                |
+| `_delete(path, ...)`   | DELETE request               |
+| `_list(path, ...)`     | List with pagination support |
+| `_validate_response()` | Pydantic response validation |
+| `_validate_request()`  | Pydantic request validation  |
+
+### Utility Functions
+
+| Function                                | Description                    |
+| --------------------------------------- | ------------------------------ |
+| `build_url(base, path, trailing_slash)` | URL composition                |
+| `extract_error_detail(response)`        | Extract error details          |
+| `parse_json_response(response)`         | Parse JSON response            |
+| `raise_for_status(status_code, detail)` | Raise exception by status code |

synapse_sdk/clients/__init__.py

@@ -0,0 +1,5 @@
+from synapse_sdk.clients.agent import AgentClient
+from synapse_sdk.clients.base import BaseClient
+from synapse_sdk.clients.exceptions import ClientError
+
+__all__ = ['AgentClient', 'BaseClient', 'ClientError']

synapse_sdk/clients/_template.py

@@ -0,0 +1,266 @@
+"""Template for creating new HTTP clients.
+
+This module provides template classes for building new sync and async
+HTTP clients. Copy this file and modify it to create a new client.
+
+Usage:
+    1. Copy this file to a new module (e.g., my_api/__init__.py)
+    2. Rename TemplateClient and AsyncTemplateClient
+    3. Implement _get_headers() with your authentication
+    4. Add domain-specific methods
+
+Example:
+    >>> from synapse_sdk.clients.my_api import MyApiClient
+    >>> client = MyApiClient('https://api.example.com', api_key='secret')
+    >>> users = client.list_users()
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+from synapse_sdk.clients.base import AsyncBaseClient, BaseClient
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+
+class TemplateClient(BaseClient):
+    """Synchronous HTTP client template.
+
+    This template demonstrates how to create a new sync client by
+    extending BaseClient with custom authentication and methods.
+
+    Attributes:
+        name: Client name for error messages.
+        api_key: API key for authentication.
+    """
+
+    name = 'TemplateAPI'
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: dict[str, int] | None = None,
+    ):
+        """Initialize the template client.
+
+        Args:
+            base_url: The base URL for all API requests.
+            api_key: API key for authentication.
+            timeout: Optional timeout configuration.
+        """
+        super().__init__(base_url, timeout=timeout)
+        self.api_key = api_key
+
+    def _get_headers(self) -> dict[str, str]:
+        """Return authentication headers.
+
+        Override this method to implement your authentication scheme.
+        Common patterns include:
+        - API key: {'X-API-Key': self.api_key}
+        - Bearer token: {'Authorization': f'Bearer {self.token}'}
+        - Basic auth: {'Authorization': f'Basic {base64_credentials}'}
+        """
+        return {'X-API-Key': self.api_key}
+
+    # -------------------------------------------------------------------------
+    # Example API Methods
+    # -------------------------------------------------------------------------
+
+    def list_resources(
+        self,
+        params: dict[str, Any] | None = None,
+        *,
+        list_all: bool = False,
+    ) -> dict[str, Any] | tuple[Any, int]:
+        """List resources with optional pagination.
+
+        Args:
+            params: Query parameters for filtering.
+            list_all: If True, returns (generator, count).
+
+        Returns:
+            Paginated list or (generator, count).
+        """
+        return self._list('resources/', params=params, list_all=list_all)
+
+    def get_resource(self, resource_id: int) -> dict[str, Any]:
+        """Get a resource by ID.
+
+        Args:
+            resource_id: The resource ID.
+
+        Returns:
+            Resource data.
+        """
+        return self._get(f'resources/{resource_id}/')
+
+    def create_resource(
+        self,
+        data: dict[str, Any],
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new resource.
+
+        Args:
+            data: Resource data to create.
+            request_model: Optional Pydantic model for request validation.
+            response_model: Optional Pydantic model for response validation.
+
+        Returns:
+            Created resource data.
+        """
+        return self._post(
+            'resources/',
+            request_model=request_model,
+            response_model=response_model,
+            data=data,
+        )
+
+    def update_resource(
+        self,
+        resource_id: int,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Update a resource.
+
+        Args:
+            resource_id: The resource ID to update.
+            data: Fields to update.
+
+        Returns:
+            Updated resource data.
+        """
+        return self._patch(f'resources/{resource_id}/', data=data)
+
+    def delete_resource(self, resource_id: int) -> None:
+        """Delete a resource.
+
+        Args:
+            resource_id: The resource ID to delete.
+        """
+        self._delete(f'resources/{resource_id}/')
+
+
+class AsyncTemplateClient(AsyncBaseClient):
+    """Asynchronous HTTP client template.
+
+    This template demonstrates how to create a new async client by
+    extending AsyncBaseClient with custom authentication and methods.
+
+    Attributes:
+        name: Client name for error messages.
+        api_key: API key for authentication.
+    """
+
+    name = 'TemplateAPI'
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float | httpx.Timeout | None = None,
+    ):
+        """Initialize the async template client.
+
+        Args:
+            base_url: The base URL for all API requests.
+            api_key: API key for authentication.
+            timeout: Optional timeout configuration.
+        """
+        super().__init__(base_url, timeout=timeout)
+        self.api_key = api_key
+
+    def _get_headers(self) -> dict[str, str]:
+        """Return authentication headers."""
+        return {'X-API-Key': self.api_key}
+
+    # -------------------------------------------------------------------------
+    # Example API Methods (Async versions)
+    # -------------------------------------------------------------------------
+
+    async def list_resources(
+        self,
+        params: dict[str, Any] | None = None,
+        *,
+        list_all: bool = False,
+    ) -> dict[str, Any] | tuple[Any, int]:
+        """List resources with optional pagination.
+
+        Args:
+            params: Query parameters for filtering.
+            list_all: If True, returns (generator, count).
+
+        Returns:
+            Paginated list or (generator, count).
+        """
+        return await self._list('resources/', params=params, list_all=list_all)
+
+    async def get_resource(self, resource_id: int) -> dict[str, Any]:
+        """Get a resource by ID.
+
+        Args:
+            resource_id: The resource ID.
+
+        Returns:
+            Resource data.
+        """
+        return await self._get(f'resources/{resource_id}/')
+
+    async def create_resource(
+        self,
+        data: dict[str, Any],
+        request_model: type[BaseModel] | None = None,
+        response_model: type[BaseModel] | None = None,
+    ) -> dict[str, Any]:
+        """Create a new resource.
+
+        Args:
+            data: Resource data to create.
+            request_model: Optional Pydantic model for request validation.
+            response_model: Optional Pydantic model for response validation.
+
+        Returns:
+            Created resource data.
+        """
+        return await self._post(
+            'resources/',
+            request_model=request_model,
+            response_model=response_model,
+            json=data,
+        )
+
+    async def update_resource(
+        self,
+        resource_id: int,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Update a resource.
+
+        Args:
+            resource_id: The resource ID to update.
+            data: Fields to update.
+
+        Returns:
+            Updated resource data.
+        """
+        return await self._patch(f'resources/{resource_id}/', json=data)
+
+    async def delete_resource(self, resource_id: int) -> None:
+        """Delete a resource.
+
+        Args:
+            resource_id: The resource ID to delete.
+        """
+        await self._delete(f'resources/{resource_id}/')
+
+
+# Note: This file is a template. Do not import or use these classes directly.
+# Copy and modify them for your specific API client implementation.