synapse-sdk 1.0.0a13__py3-none-any.whl → 2025.11.7__py3-none-any.whl

synapse_sdk/devtools/docs/docs/api/plugins/utils.md

@@ -0,0 +1,328 @@
+---
+id: utils
+title: Plugin Utilities
+sidebar_position: 3
+---
+
+# Plugin Utilities
+
+Comprehensive utility functions for plugin development, configuration management, and action handling.
+
+## Overview
+
+The plugin utilities module (`synapse_sdk.plugins.utils`) provides a collection of functions for working with plugin configurations, managing actions, and handling plugin metadata. The utilities are organized into focused modules for better maintainability.
+
+## Configuration Utilities
+
+### read_plugin_config()
+
+Read and parse plugin configuration from config.yaml file with enhanced error handling.
+
+```python
+from synapse_sdk.plugins.utils import read_plugin_config
+
+# Read from specific plugin directory
+config = read_plugin_config(plugin_path="./my-plugin")
+
+# Read from current directory
+config = read_plugin_config()
+```
+
+**Parameters:**
+
+- `plugin_path` (optional): Path to plugin directory containing config.yaml
+
+**Returns:** Dictionary containing parsed plugin configuration
+
+**Raises:**
+
+- `FileNotFoundError`: If config.yaml is not found
+- `ValueError`: If config.yaml contains invalid YAML
+
+### get_plugin_actions()
+
+Get list of action names defined in a plugin configuration.
+
+```python
+from synapse_sdk.plugins.utils import get_plugin_actions
+
+# From config dictionary
+config = {'actions': {'train': {...}, 'inference': {...}}}
+actions = get_plugin_actions(config=config)
+# Returns: ['train', 'inference']
+
+# From plugin path
+actions = get_plugin_actions(plugin_path="./my-plugin")
+
+# From current directory
+actions = get_plugin_actions()
+```
+
+**Parameters:**
+
+- `config` (optional): Plugin configuration dictionary
+- `plugin_path` (optional): Path to plugin directory
+
+**Returns:** List of action names
+
+### get_action_config()
+
+Retrieve configuration for a specific action within a plugin.
+
+```python
+from synapse_sdk.plugins.utils import get_action_config
+
+# Get specific action configuration
+action_config = get_action_config('train', plugin_path="./my-plugin")
+# Returns: {'entrypoint': 'plugin.train.TrainAction', 'method': 'job'}
+
+# With config dictionary
+config = {'actions': {'train': {'entrypoint': 'plugin.train.TrainAction'}}}
+action_config = get_action_config('train', config=config)
+```
+
+**Parameters:**
+
+- `action_name`: Name of the action to retrieve
+- `config` (optional): Plugin configuration dictionary
+- `plugin_path` (optional): Path to plugin directory
+
+**Returns:** Dictionary containing action configuration
+
+### validate_plugin_config()
+
+Validate plugin configuration structure and required fields.
+
+```python
+from synapse_sdk.plugins.utils import validate_plugin_config
+
+config = {
+    'name': 'My Plugin',
+    'code': 'my-plugin',
+    'version': '1.0.0',
+    'category': 'neural_net',
+    'actions': {'train': {'entrypoint': 'plugin.train.TrainAction'}}
+}
+
+is_valid = validate_plugin_config(config)  # Returns: True
+```
+
+**Validation Checks:**
+
+- Required fields: `name`, `code`, `version`, `category`, `actions`
+- Valid plugin category
+- Proper actions structure
+- Required entrypoints (except for REST API actions)
+
+### get_plugin_metadata()
+
+Extract metadata (name, version, description, etc.) from plugin configuration.
+
+```python
+from synapse_sdk.plugins.utils import get_plugin_metadata
+
+metadata = get_plugin_metadata(plugin_path="./my-plugin")
+# Returns: {
+#     'name': 'My Plugin',
+#     'code': 'my-plugin', 
+#     'version': '1.0.0',
+#     'category': 'neural_net',
+#     'description': 'A custom ML plugin'
+# }
+```
+
+## Action Utilities
+
+### get_action_class()
+
+Retrieve action class by category and action name from the registry.
+
+```python
+from synapse_sdk.plugins.utils import get_action_class
+
+# Get action class for instantiation
+TrainAction = get_action_class('neural_net', 'train')
+action_instance = TrainAction(params, config)
+```
+
+### get_available_actions()
+
+List all available actions for a specific plugin category.
+
+```python
+from synapse_sdk.plugins.utils import get_available_actions
+
+actions = get_available_actions('neural_net')
+# Returns: ['train', 'inference', 'test', 'deployment', 'gradio', 'tune']
+```
+
+### is_action_available()
+
+Check if a specific action is available in a category.
+
+```python
+from synapse_sdk.plugins.utils import is_action_available
+
+if is_action_available('neural_net', 'train'):
+    print("Training action is available")
+```
+
+### get_action()
+
+Create and configure a plugin action instance with parameters.
+
+```python
+from synapse_sdk.plugins.utils import get_action
+
+# With dictionary parameters
+params = {'dataset_path': '/data', 'epochs': 10}
+action = get_action('train', params, plugin_path="./my-plugin")
+
+# With JSON string parameters
+params_json = '{"dataset_path": "/data", "epochs": 10}'
+action = get_action('train', params_json, config=config)
+
+# With file parameters
+action = get_action('train', '/path/to/params.yaml')
+```
+
+## Registry Utilities
+
+### get_plugin_categories()
+
+Get list of all available plugin categories.
+
+```python
+from synapse_sdk.plugins.utils import get_plugin_categories
+
+categories = get_plugin_categories()
+# Returns: ['neural_net', 'export', 'upload', 'smart_tool', 
+#           'post_annotation', 'pre_annotation', 'data_validation']
+```
+
+### is_valid_category()
+
+Validate if a category name is valid.
+
+```python
+from synapse_sdk.plugins.utils import is_valid_category
+
+if is_valid_category('neural_net'):
+    print("Valid category")
+```
+
+### get_category_display_name()
+
+Get human-readable display name for a category.
+
+```python
+from synapse_sdk.plugins.utils import get_category_display_name
+
+display_name = get_category_display_name('neural_net')
+# Returns: "Neural Net"
+
+display_name = get_category_display_name('data_validation') 
+# Returns: "Data Validation"
+```
+
+## Error Handling
+
+All utility functions include comprehensive error handling with descriptive error messages:
+
+```python
+from synapse_sdk.plugins.utils import get_plugin_actions
+
+try:
+    actions = get_plugin_actions(plugin_path="./nonexistent")
+except FileNotFoundError as e:
+    print(f"Plugin config not found: {e}")
+except ValueError as e:
+    print(f"Invalid plugin config: {e}")
+except KeyError as e:
+    print(f"Missing required field: {e}")
+```
+
+## Usage Examples
+
+### Complete Plugin Workflow
+
+```python
+from synapse_sdk.plugins.utils import (
+    read_plugin_config,
+    get_plugin_actions,
+    get_action_config,
+    validate_plugin_config,
+    get_action_class
+)
+
+# 1. Read plugin configuration
+config = read_plugin_config("./my-neural-net-plugin")
+
+# 2. Validate configuration
+if validate_plugin_config(config):
+    print("✅ Plugin configuration is valid")
+
+# 3. List available actions
+actions = get_plugin_actions(config=config)
+print(f"Available actions: {actions}")
+
+# 4. Get specific action configuration
+train_config = get_action_config('train', config=config)
+print(f"Train entrypoint: {train_config['entrypoint']}")
+
+# 5. Create action instance
+TrainAction = get_action_class(config['category'], 'train')
+action = TrainAction(
+    params={'dataset_path': '/data', 'epochs': 10},
+    plugin_config=config
+)
+```
+
+### Plugin Development Helper
+
+```python
+from synapse_sdk.plugins.utils import (
+    get_plugin_categories,
+    get_available_actions,
+    is_action_available
+)
+
+# Check available categories
+categories = get_plugin_categories()
+print("Available plugin categories:")
+for category in categories:
+    print(f"  - {category}")
+    
+    # List actions for each category
+    actions = get_available_actions(category)
+    for action in actions:
+        print(f"    - {action}")
+
+# Verify action availability
+if is_action_available('neural_net', 'train'):
+    print("✅ Train action is available for neural_net plugins")
+```
+
+## Migration from Legacy API
+
+The new utilities maintain backward compatibility while providing enhanced functionality:
+
+```python
+# Legacy (still supported)
+from synapse_sdk.plugins.utils import read_plugin_config
+
+# New enhanced API (recommended)
+from synapse_sdk.plugins.utils import (
+    read_plugin_config,
+    get_plugin_actions,
+    validate_plugin_config
+)
+```
+
+## Best Practices
+
+1. **Error Handling**: Always wrap utility calls in try-catch blocks
+2. **Configuration Validation**: Validate configs before using them
+3. **Path Handling**: Use absolute paths when possible
+4. **Action Verification**: Check action availability before instantiation
+5. **Type Safety**: Use the provided type hints for better IDE support

synapse_sdk/devtools/docs/docs/cli-usage.md

@@ -0,0 +1,280 @@
+---
+id: cli-usage
+title: CLI Usage Guide
+sidebar_position: 4
+---
+
+# CLI Usage Guide
+
+The Synapse SDK provides a powerful interactive CLI for managing your development workflow, from configuration to plugin development and code editing.
+
+## Getting Started
+
+Launch the interactive CLI:
+
+```bash
+synapse
+```
+
+Or run specific commands directly:
+
+```bash
+# Start development tools immediately
+synapse --dev-tools
+
+# Show help
+synapse --help
+```
+
+## Main Menu Options
+
+When you run `synapse`, you'll see the main menu:
+
+```
+🚀 Synapse SDK
+Select an option:
+  🌐 Run Dev Tools
+  💻 Open Code-Server IDE
+  ⚙️  Configuration
+  🔌 Plugin Management
+  🚪 Exit
+```
+
+## 🌐 Run Dev Tools
+
+Launches the Synapse development tools dashboard with:
+
+- **Interactive UI**: Web-based dashboard for managing agents and jobs
+- **Real-time Monitoring**: Live view of agent status and job execution
+- **Plugin Management**: Upload, test, and manage plugins through the UI
+
+### Usage
+```bash
+# Launch dev tools from CLI menu
+synapse
+
+# Or start directly
+synapse --dev-tools
+```
+
+## 💻 Open Code-Server IDE
+
+Opens a web-based VS Code environment for plugin development. Supports both agent-based and local code-server instances.
+
+### Agent Code-Server
+
+Connect to a remote code-server running on an agent:
+
+- **Automatic Setup**: Synapse configures the workspace and installs dependencies
+- **Plugin Encryption**: Local plugin code is encrypted and securely transferred
+- **Workspace Sync**: Your local project is available in the agent environment
+
+### Local Code-Server
+
+Launch a local code-server instance:
+
+- **Port Detection**: Automatically reads port from `~/.config/code-server/config.yaml`
+- **Folder Parameter**: Opens with correct workspace directory
+- **Browser Integration**: Automatically opens browser with proper URL
+
+### Usage Examples
+
+```bash
+# Interactive menu (recommended)
+synapse
+# Select "💻 Open Code-Server IDE"
+
+# Direct command
+synapse code-server
+
+# With specific options
+synapse code-server --agent my-agent --workspace /path/to/project
+
+# Don't open browser automatically
+synapse code-server --no-open-browser
+```
+
+### Code-Server Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--agent` | Specific agent ID to use | Current agent or prompt |
+| `--workspace` | Project directory path | Current directory |
+| `--open-browser/--no-open-browser` | Open browser automatically | `--open-browser` |
+
+### Local Code-Server Installation
+
+If code-server isn't installed locally, the CLI provides installation instructions:
+
+```bash
+# Recommended: Install script
+curl -fsSL https://code-server.dev/install.sh | sh
+
+# Using npm
+npm install -g code-server
+
+# Using yarn
+yarn global add code-server
+```
+
+For more options, visit: https://coder.com/docs/code-server/latest/install
+
+## ⚙️ Configuration
+
+Interactive configuration wizard for setting up:
+
+- **Backend Connection**: Configure API endpoints and authentication
+- **Agent Selection**: Choose and configure development agents
+- **Token Management**: Manage access tokens and authentication
+
+### Configuration Files
+
+Synapse stores configuration in:
+- **Backend Config**: `~/.synapse/devtools.yaml`
+- **Agent Config**: `~/.synapse/devtools.yaml` (agent section)
+- **Code-Server Config**: `~/.config/code-server/config.yaml`
+
+## 🔌 Plugin Management
+
+Comprehensive plugin development and management tools:
+
+### Create New Plugin
+
+```bash
+synapse
+# Select "🔌 Plugin Management" → "Create new plugin"
+```
+
+Interactive wizard creates:
+- Plugin directory structure
+- Configuration files (`config.yaml`)
+- Example plugin code
+- Requirements and dependencies
+
+### Run Plugin Locally
+
+Test plugins in different environments:
+
+```bash
+# Script execution (local)
+synapse plugin run my_action '{"param": "value"}' --run-by script
+
+# Agent execution (remote)
+synapse plugin run my_action '{"param": "value"}' --run-by agent
+
+# Backend execution (cloud)
+synapse plugin run my_action '{"param": "value"}' --run-by backend
+```
+
+### Publish Plugin
+
+Deploy plugins to your Synapse backend:
+
+```bash
+synapse
+# Select "🔌 Plugin Management" → "Publish plugin"
+```
+
+Options:
+- **Debug Mode**: Test deployment with verbose logging
+- **Production Mode**: Deploy for live use
+
+## Command Reference
+
+### Main Commands
+
+```bash
+# Interactive CLI (main menu)
+synapse
+
+# Development tools
+synapse --dev-tools
+
+# Direct commands
+synapse config         # Configuration wizard
+synapse devtools       # Development dashboard
+synapse code-server    # Code editing environment
+synapse plugin         # Plugin management
+```
+
+### Code-Server Command
+
+```bash
+synapse code-server [OPTIONS]
+
+Options:
+  --agent TEXT                    Agent name or ID
+  --open-browser / --no-open-browser
+                                  Open in browser [default: open-browser]
+  --workspace TEXT                Workspace directory path (defaults to current directory)
+  --help                          Show this message and exit.
+```
+
+### Plugin Commands
+
+```bash
+# Create plugin
+synapse plugin create
+
+# Run plugin
+synapse plugin run ACTION PARAMS [OPTIONS]
+
+# Publish plugin  
+synapse plugin publish [OPTIONS]
+```
+
+## Tips & Best Practices
+
+### Code-Server Development
+
+1. **Plugin Detection**: When opening code-server, Synapse automatically detects if your workspace contains a plugin and encrypts it for secure transfer to agents.
+
+2. **Workspace Paths**: Agent workspaces typically use `/home/coder/workspace` - this is normal for containerized environments.
+
+3. **Port Configuration**: Local code-server port is read from your config file, defaulting to 8070 if not configured.
+
+### Configuration Management
+
+1. **Token Security**: Store API tokens securely and rotate them regularly
+2. **Agent Selection**: Use descriptive agent names to identify their purpose
+3. **Backend URLs**: Ensure backend URLs are accessible from your development environment
+
+### Plugin Development
+
+1. **Local Testing**: Always test plugins locally with `--run-by script` before deploying
+2. **Debug Mode**: Use debug mode for initial deployments to catch issues early
+3. **Version Control**: Use git to track plugin changes and manage versions
+
+## Troubleshooting
+
+### Code-Server Issues
+
+**Problem**: "Code-server is not available"
+- **Solution**: Ensure the agent has code-server support enabled
+
+**Problem**: Browser doesn't open automatically
+- **Solution**: Manually copy the provided URL to your browser
+
+**Problem**: Wrong port displayed
+- **Solution**: Check `~/.config/code-server/config.yaml` for correct port configuration
+
+### Configuration Issues
+
+**Problem**: "No backend configured"
+- **Solution**: Run `synapse config` to set up backend connection
+
+**Problem**: "Invalid token (401)"
+- **Solution**: Generate a new API token and update configuration
+
+**Problem**: "Connection timeout"
+- **Solution**: Check network connectivity and backend URL accessibility
+
+### Plugin Issues
+
+**Problem**: Plugin not detected in workspace
+- **Solution**: Ensure your directory has a valid `config.yaml` file
+
+**Problem**: Plugin execution fails
+- **Solution**: Check plugin dependencies and syntax, test locally first
+
+For more troubleshooting help, see the [Troubleshooting Guide](./troubleshooting.md).

synapse_sdk/devtools/docs/docs/concepts/index.md

@@ -0,0 +1,38 @@
+---
+id: index
+title: Core Concepts
+sidebar_position: 1
+---
+
+# Core Concepts
+
+Understanding the fundamental concepts of Synapse SDK.
+
+## Architecture
+
+Learn about the overall system architecture and design principles.
+
+## Plugin System
+
+Understanding how plugins work, categories, and execution methods.
+
+## Clients
+
+Different client types and their use cases:
+- BackendClient for API operations
+- AgentClient for distributed execution
+
+## Execution Methods
+
+Different ways to run plugins:
+- **JOB**: Long-running operations with monitoring
+- **TASK**: Quick, simple operations
+- **RESTAPI**: Serving models and APIs
+
+## Data Flow
+
+How data flows through the system from input to output.
+
+## Security
+
+Authentication, authorization, and security best practices.