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

synapse_sdk/plugins/utils.py

@@ -1,50 +1,338 @@
-import json
+"""Plugin utilities for configuration parsing and action discovery."""
+
+from __future__ import annotations
+
+import re
 from pathlib import Path
+from typing import TYPE_CHECKING, Any, get_args, get_origin
+
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefined
+
+from synapse_sdk.plugins.enums import RunMethod
+from synapse_sdk.utils.file.requirements import read_requirements
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.config import PluginConfig
+
+
+def get_plugin_actions(config: dict | PluginConfig | Path | str) -> list[str]:
+    """Extract action names from plugin configuration.
+
+    Args:
+        config: Plugin config dict, PluginConfig instance, or path to config.yaml
+
+    Returns:
+        List of action names. Returns empty list on error.
+    """
+    from synapse_sdk.plugins.config import PluginConfig
+
+    if isinstance(config, (str, Path)):
+        config = _load_config_from_path(config)
+    if isinstance(config, PluginConfig):
+        return list(config.actions.keys())
+    if isinstance(config, dict):
+        return list(config.get('actions', {}).keys())
+    return []
+
+
+def get_action_method(config: dict | PluginConfig, action: str) -> RunMethod:
+    """Get the run method for an action from config.
+
+    Args:
+        config: Plugin config dict or PluginConfig instance
+        action: Action name
+
+    Returns:
+        RunMethod enum value. Defaults to TASK if not found.
+    """
+    from synapse_sdk.plugins.config import PluginConfig
+
+    if isinstance(config, PluginConfig):
+        action_config = config.actions.get(action)
+        if action_config:
+            return action_config.method
+    elif isinstance(config, dict):
+        actions = config.get('actions', {})
+        action_config = actions.get(action, {})
+        method = action_config.get('method', 'task')
+        return RunMethod(method)
+    return RunMethod.TASK
+
+
+def get_action_config(config: dict | PluginConfig, action: str) -> dict:
+    """Get the full configuration for a specific action.
+
+    Args:
+        config: Plugin config dict or PluginConfig instance
+        action: Action name
+
+    Returns:
+        Action configuration dictionary
+
+    Raises:
+        KeyError: If action not found
+        ValueError: If config type is invalid
+    """
+    from synapse_sdk.plugins.config import PluginConfig
+
+    if isinstance(config, PluginConfig):
+        action_cfg = config.actions.get(action)
+        if action_cfg:
+            return action_cfg.model_dump()
+        raise KeyError(f"Action '{action}' not found. Available: {list(config.actions.keys())}")
+    elif isinstance(config, dict):
+        actions = config.get('actions', {})
+        if action in actions:
+            return actions[action]
+        raise KeyError(f"Action '{action}' not found. Available: {list(actions.keys())}")
+    raise ValueError('Invalid config type')
+
+
+def _load_config_from_path(path: Path | str) -> dict:
+    """Load plugin config from YAML file.
+
+    Args:
+        path: Path to config.yaml or directory containing it
+
+    Returns:
+        Parsed config dictionary
+    """
+    import yaml
+
+    path = Path(path)
+    if path.is_dir():
+        path = path / 'config.yaml'
+    with path.open() as f:
+        return yaml.safe_load(f)
+
+
+# =============================================================================
+# UI Schema Generation
+# =============================================================================
+
+
+def _type_to_formkit(annotation: type | None) -> str:
+    """Convert Python type annotation to FormKit input type.
+
+    Args:
+        annotation: Python type annotation (int, float, str, bool, etc.)
+
+    Returns:
+        FormKit input type string
+    """
+    if annotation is None:
+        return 'text'
+
+    # Handle Optional types
+    origin = get_origin(annotation)
+    if origin is type(None):
+        return 'text'
+
+    # Unwrap Optional/Union types
+    if origin is not None:
+        args = get_args(annotation)
+        # Filter out NoneType for Optional[X]
+        non_none_args = [a for a in args if a is not type(None)]
+        if non_none_args:
+            annotation = non_none_args[0]
+
+    # Map Python types to FormKit types
+    type_map: dict[type, str] = {
+        int: 'number',
+        float: 'number',
+        str: 'text',
+        bool: 'checkbox',
+        list: 'checkbox',  # Multi-select
+    }
+
+    return type_map.get(annotation, 'text')  # type: ignore[arg-type]
+
+
+def _to_label(name: str) -> str:
+    """Convert snake_case field name to Title Case label.
+
+    Args:
+        name: Field name in snake_case (e.g., "batch_size")
+
+    Returns:
+        Human-readable label (e.g., "Batch Size")
+
+    Example:
+        >>> _to_label("batch_size")
+        "Batch Size"
+        >>> _to_label("learning_rate")
+        "Learning Rate"
+    """
+    return re.sub(r'_', ' ', name).title()
+
+
+def _extract_constraints(field_info: FieldInfo) -> dict[str, Any]:
+    """Extract validation constraints from Pydantic FieldInfo.
+
+    Converts Pydantic constraints (ge, le, gt, lt) to FormKit validation rules.
+
+    Args:
+        field_info: Pydantic FieldInfo object
+
+    Returns:
+        Dict with min, max, step if applicable
+    """
+    constraints: dict[str, Any] = {}
+
+    # Extract from metadata (Pydantic v2 style)
+    for meta in field_info.metadata:
+        meta_type = type(meta).__name__
+
+        if meta_type == 'Ge':  # Greater than or equal
+            constraints['min'] = meta.ge
+        elif meta_type == 'Le':  # Less than or equal
+            constraints['max'] = meta.le
+        elif meta_type == 'Gt':  # Greater than (use as min)
+            constraints['min'] = meta.gt
+        elif meta_type == 'Lt':  # Less than (use as max)
+            constraints['max'] = meta.lt
+        elif meta_type == 'MultipleOf':  # Step value
+            constraints['step'] = meta.multiple_of
+
+    return constraints
+
+
+def pydantic_to_ui_schema(model: type[BaseModel]) -> list[dict[str, Any]]:
+    """Convert a Pydantic model to FormKit UI schema format.
+
+    This generates a UI schema compatible with the legacy config.yaml format,
+    suitable for rendering forms in the frontend.
+
+    Args:
+        model: Pydantic BaseModel class with field definitions
+
+    Returns:
+        List of FormKit schema items, one per field
+
+    Example:
+        >>> from pydantic import BaseModel, Field
+        >>>
+        >>> class TrainParams(BaseModel):
+        ...     epochs: int = Field(default=50, ge=1, le=1000)
+        ...     batch_size: int = Field(default=8, ge=1, le=512)
+        ...     learning_rate: float = Field(default=0.001)
+        ...
+        >>> schema = pydantic_to_ui_schema(TrainParams)
+        >>> schema[0]
+        {
+            '$formkit': 'number',
+            'name': 'epochs',
+            'label': 'Epochs',
+            'value': 50,
+            'placeholder': 50,
+            'min': 1,
+            'max': 1000,
+            'number': True
+        }
+
+    Custom UI via json_schema_extra:
+        >>> class Params(BaseModel):
+        ...     model_size: str = Field(
+        ...         default="medium",
+        ...         json_schema_extra={
+        ...             "formkit": "select",
+        ...             "options": ["small", "medium", "large"],
+        ...             "help": "Model size selection"
+        ...         }
+        ...     )
+    """
+    schema: list[dict[str, Any]] = []
+
+    for name, field_info in model.model_fields.items():
+        # Start with basic item structure
+        item: dict[str, Any] = {
+            '$formkit': _type_to_formkit(field_info.annotation),
+            'name': name,
+            'label': _to_label(name),
+        }
+
+        # Add default value (check for PydanticUndefined)
+        if field_info.default is not PydanticUndefined and field_info.default is not None:
+            item['value'] = field_info.default
+            item['placeholder'] = field_info.default
+
+        # Add description as help text
+        if field_info.description:
+            item['help'] = field_info.description
+
+        # Check if field is required (no default)
+        if field_info.is_required():
+            item['required'] = True
+
+        # Add validation constraints
+        constraints = _extract_constraints(field_info)
+        item.update(constraints)
+
+        # Add number flag for numeric types
+        if item['$formkit'] == 'number':
+            item['number'] = True
+
+        # Apply custom overrides from json_schema_extra
+        if field_info.json_schema_extra:
+            extra = field_info.json_schema_extra
+            if callable(extra):
+                # Handle callable json_schema_extra
+                extra_dict: dict[str, Any] = {}
+                extra(extra_dict)
+                extra = extra_dict
 
-from synapse_sdk.plugins.categories.registry import _REGISTERED_ACTIONS, register_actions
-from synapse_sdk.plugins.enums import PluginCategory
-from synapse_sdk.utils.file import get_dict_from_file
+            if isinstance(extra, dict):
+                # Override formkit type if specified
+                if 'formkit' in extra:
+                    item['$formkit'] = extra['formkit']
 
+                # Copy other properties
+                for key in ('options', 'help', 'required', 'step', 'min', 'max'):
+                    if key in extra:
+                        item[key] = extra[key]
 
-def get_action(action, params_data, *args, **kwargs):
-    if isinstance(params_data, str):
-        try:
-            params = json.loads(params_data)
-        except json.JSONDecodeError:
-            params = get_dict_from_file(params_data)
-    else:
-        params = params_data
+        schema.append(item)
 
-    config_data = kwargs.pop('config', False)
-    if config_data:
-        if isinstance(config_data, str):
-            config = read_plugin_config(plugin_path=config_data)
-        else:
-            config = config_data
-    else:
-        config = read_plugin_config()
-    category = config['category']
-    return get_action_class(category, action)(params, config, *args, **kwargs)
+    return schema
 
 
-def get_action_class(category, action):
-    register_actions()
-    return _REGISTERED_ACTIONS[category][action]
+def get_action_ui_schema(
+    model: type[BaseModel],
+    action_name: str | None = None,
+) -> dict[str, Any]:
+    """Get UI schema for an action's parameters.
 
+    Returns the schema in the format expected by the backend API.
 
-def get_available_actions(category):
-    register_actions()
-    return list(_REGISTERED_ACTIONS[category].keys())
+    Args:
+        model: Pydantic model class for action parameters
+        action_name: Optional action name for the response
 
+    Returns:
+        Dict with action name and ui_schemas list
 
-def get_plugin_categories():
-    return [plugin_category.value for plugin_category in PluginCategory]
+    Example:
+        >>> schema = get_action_ui_schema(TrainParams, 'train')
+        >>> schema
+        {
+            'action': 'train',
+            'ui_schemas': [...]
+        }
+    """
+    return {
+        'action': action_name,
+        'ui_schemas': pydantic_to_ui_schema(model),
+    }
 
 
-def read_plugin_config(plugin_path=None):
-    config_file_name = 'config.yaml'
-    if plugin_path:
-        config_path = Path(plugin_path) / config_file_name
-    else:
-        config_path = config_file_name
-    return get_dict_from_file(config_path)
+__all__ = [
+    'get_plugin_actions',
+    'get_action_method',
+    'get_action_config',
+    'read_requirements',
+    # Schema utilities
+    'pydantic_to_ui_schema',
+    'get_action_ui_schema',
+]

synapse_sdk/shared/__init__.py

@@ -0,0 +1,25 @@
+import os
+
+
+def needs_sentry_init():
+    return os.getenv('SENTRY_DSN') is not None
+
+
+def init_sentry():
+    import sentry_sdk
+    from sentry_sdk.integrations.ray import RayIntegration
+
+    dsn = os.getenv('SENTRY_DSN')
+    if dsn is None:
+        return
+
+    sentry_sdk.init(
+        dsn=dsn,
+        environment=os.getenv('DEPLOYMENT_TARGET', 'development'),
+        integrations=[RayIntegration()],
+        send_default_pii=True,
+    )
+
+
+def worker_process_setup_hook(*_, **__):
+    init_sentry()

synapse_sdk/utils/__init__.py

@@ -0,0 +1 @@
+"""Synapse SDK utilities."""

synapse_sdk/utils/auth.py

@@ -0,0 +1,74 @@
+"""Authentication utilities for SDK."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synapse_sdk.clients.backend import BackendClient
+
+# Environment variable names
+ENV_SYNAPSE_HOST = 'SYNAPSE_HOST'
+ENV_SYNAPSE_ACCESS_TOKEN = 'SYNAPSE_ACCESS_TOKEN'
+
+# Default host
+DEFAULT_HOST = 'https://api.synapse.sh'
+
+# Config file path
+CONFIG_FILE = Path.home() / '.synapse' / 'config.json'
+
+
+def load_credentials() -> tuple[str | None, str | None]:
+    """Load credentials from environment or config file.
+
+    Priority:
+    1. Environment variables (SYNAPSE_HOST, SYNAPSE_ACCESS_TOKEN)
+    2. Config file (~/.synapse/config.json)
+
+    Returns:
+        Tuple of (host, token). Either may be None if not found.
+    """
+    host = os.environ.get(ENV_SYNAPSE_HOST)
+    token = os.environ.get(ENV_SYNAPSE_ACCESS_TOKEN)
+
+    # Fall back to config.json
+    if not token and CONFIG_FILE.exists():
+        try:
+            config = json.loads(CONFIG_FILE.read_text())
+            if not host:
+                host = config.get('host')
+            if not token:
+                token = config.get('access_token')
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    return host, token
+
+
+def create_backend_client() -> BackendClient | None:
+    """Create a BackendClient from environment/credentials if available.
+
+    Returns:
+        BackendClient if credentials are available, None otherwise.
+    """
+    host, token = load_credentials()
+
+    if not token:
+        return None
+
+    from synapse_sdk.clients.backend import BackendClient
+
+    return BackendClient(base_url=host or DEFAULT_HOST, access_token=token)
+
+
+__all__ = [
+    'ENV_SYNAPSE_HOST',
+    'ENV_SYNAPSE_ACCESS_TOKEN',
+    'DEFAULT_HOST',
+    'CONFIG_FILE',
+    'load_credentials',
+    'create_backend_client',
+]

synapse_sdk/utils/file/__init__.py

@@ -0,0 +1,58 @@
+"""File utilities module."""
+
+from .archive import (
+    ArchiveFilter,
+    ProgressCallback,
+    create_archive,
+    create_archive_from_git,
+    extract_archive,
+    get_archive_size,
+    list_archive_contents,
+)
+from .checksum import (
+    HashAlgorithm,
+    calculate_checksum,
+    calculate_checksum_from_bytes,
+    calculate_checksum_from_file_object,
+    verify_checksum,
+)
+from .download import (
+    adownload_file,
+    afiles_url_to_path,
+    afiles_url_to_path_from_objs,
+    download_file,
+    files_url_to_path,
+    files_url_to_path_from_objs,
+)
+from .io import get_dict_from_file, get_temp_path
+from .requirements import read_requirements
+
+__all__ = [
+    # I/O
+    'get_temp_path',
+    'get_dict_from_file',
+    # Download (sync)
+    'download_file',
+    'files_url_to_path',
+    'files_url_to_path_from_objs',
+    # Download (async)
+    'adownload_file',
+    'afiles_url_to_path',
+    'afiles_url_to_path_from_objs',
+    # Requirements
+    'read_requirements',
+    # Checksum
+    'HashAlgorithm',
+    'calculate_checksum',
+    'calculate_checksum_from_bytes',
+    'calculate_checksum_from_file_object',
+    'verify_checksum',
+    # Archive
+    'ProgressCallback',
+    'ArchiveFilter',
+    'create_archive',
+    'create_archive_from_git',
+    'extract_archive',
+    'list_archive_contents',
+    'get_archive_size',
+]