synapse-sdk 1.0.0b12__py3-none-any.whl → 1.0.0b14__py3-none-any.whl

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.

synapse_sdk/devtools/docs/docs/configuration.md

@@ -0,0 +1,83 @@
+---
+id: configuration
+title: Configuration
+sidebar_position: 8
+---
+
+# Configuration
+
+Configure Synapse SDK for your environment and use cases.
+
+## Configuration Methods
+
+There are three ways to configure Synapse SDK:
+
+1. **Synapse CLI**
+2. **Environment variables**
+3. **Configuration file**
+
+## CLI
+
+The interactive configuration menu provides an easy way to configure your Synapse SDK:
+
+```bash
+$ synapse config
+```
+
+This will open an interactive menu where you can:
+- Configure backend host and API token
+- Select or manually configure an agent
+- View current configuration
+
+### Key Features:
+- **Plain text token display**: Tokens are shown in plain text for easy verification
+- **Connection testing**: After configuring backend or agent, the connection is automatically tested
+- **No startup delays**: Connection checks only happen when you configure settings, not on CLI startup
+
+## Configuration File
+
+Create a configuration file at `~/.synapse/config.json`:
+
+```json
+{
+  "backend": {
+    "host": "https://api.synapse.sh",
+    "token": "your-api-token"
+  },
+  "agent": {
+    "id": "agent-uuid-123",
+    "name": "My Development Agent",
+    "token": "your-agent-token"
+  }
+}
+```
+
+## Plugin Management
+
+The CLI provides an interactive plugin management interface:
+
+```bash
+$ synapse
+# Select "Plugin Management"
+```
+
+### Available Options:
+
+1. **Create new plugin**: Creates a new plugin from templates using cookiecutter
+2. **Run plugin locally**: Interactive interface to run plugins with configurable parameters
+3. **Publish plugin**: Publishes plugins to the configured backend with debug mode option
+
+### Plugin Publishing
+
+When publishing plugins:
+- **Debug mode**: Enabled by default for development
+- **Backend integration**: Uses your configured backend settings
+- **Connection testing**: Verifies backend connection before publishing
+- **Error handling**: Stops on errors and waits for user acknowledgment
+
+### Plugin Development Workflow
+
+1. **Create**: Use the CLI to create a new plugin template
+2. **Develop**: Write your plugin code following the generated structure
+3. **Test**: Run plugins locally through the interactive interface
+4. **Publish**: Deploy to your configured backend with debug options

synapse_sdk/devtools/docs/docs/contributing.md

@@ -0,0 +1,306 @@
+---
+id: contributing
+title: Contributing
+sidebar_position: 12
+---
+
+# Contributing to Synapse SDK
+
+Thank you for your interest in contributing to Synapse SDK! This guide will help you get started with contributing to the project.
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.8 or higher
+- Git
+- Virtual environment tool (venv, conda, etc.)
+
+### Getting Started
+
+1. **Fork and Clone the Repository**
+   ```bash
+   git clone https://github.com/yourusername/synapse-sdk.git
+   cd synapse-sdk
+   ```
+
+2. **Create Virtual Environment**
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. **Install Dependencies**
+   ```bash
+   pip install -r requirements.txt
+   pip install -r requirements.test.txt
+   ```
+
+## Code Formatting and Quality
+
+### Ruff Formatting
+
+We use **Ruff** for code formatting and linting. All contributions must follow our formatting standards.
+
+#### Required Commands
+
+Before submitting any code changes, run these commands:
+
+```bash
+# Format all Python code
+ruff format .
+
+# Fix linting issues
+ruff check --fix .
+
+# Check for remaining issues
+ruff check .
+```
+
+#### Formatting Workflow
+
+1. **Make your changes** - Write or modify Python code
+2. **Format with Ruff** - Run `ruff format .` to apply consistent formatting
+3. **Fix linting issues** - Run `ruff check --fix .` to resolve code quality issues
+4. **Verify changes** - Review the formatted code to ensure correctness
+5. **Commit changes** - Create commits with properly formatted code
+
+#### IDE Integration
+
+Configure your IDE to run Ruff automatically:
+
+- **VS Code**: Install the Ruff extension
+- **PyCharm**: Configure Ruff as external tool
+- **Vim/Neovim**: Use ruff-lsp or similar plugins
+
+### Code Style Guidelines
+
+- **Line length**: Follow project-specific settings in `pyproject.toml`
+- **Import sorting**: Let Ruff handle import organization
+- **Type hints**: Use type annotations where appropriate
+- **Docstrings**: Follow Google-style docstring format
+- **Comments**: Write clear, concise comments for complex logic
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/plugins/utils/test_config.py
+
+# Run with coverage
+pytest --cov=synapse_sdk
+```
+
+### Writing Tests
+
+- Write tests for all new functionality
+- Use descriptive test names that explain the scenario
+- Include both positive and negative test cases
+- Mock external dependencies appropriately
+- Maintain high test coverage
+
+#### Test Structure
+
+```python
+class TestMyFeature:
+    """Test MyFeature functionality."""
+    
+    def test_feature_success_case(self):
+        """Test successful feature operation."""
+        # Arrange
+        input_data = {"key": "value"}
+        
+        # Act
+        result = my_feature(input_data)
+        
+        # Assert
+        assert result == expected_output
+    
+    def test_feature_error_case(self):
+        """Test feature error handling."""
+        with pytest.raises(ValueError, match="Expected error message"):
+            my_feature(invalid_input)
+```
+
+## Plugin Development
+
+### Creating New Plugin Utilities
+
+When adding new plugin utilities:
+
+1. **Add to appropriate module**:
+   - Configuration utilities → `synapse_sdk/plugins/utils/config.py`
+   - Action utilities → `synapse_sdk/plugins/utils/actions.py`
+   - Registry utilities → `synapse_sdk/plugins/utils/registry.py`
+
+2. **Include comprehensive docstrings**:
+   ```python
+   def my_utility_function(param: str) -> Dict[str, Any]:
+       """Brief description of the function.
+       
+       Args:
+           param: Description of the parameter.
+           
+       Returns:
+           Description of the return value.
+           
+       Raises:
+           ValueError: When input is invalid.
+           
+       Examples:
+           >>> my_utility_function("example")
+           {'result': 'processed'}
+       """
+   ```
+
+3. **Add to `__all__` exports**
+4. **Write comprehensive tests**
+5. **Update documentation**
+
+### Plugin Categories
+
+When working with plugin categories:
+
+- Use existing categories when possible
+- Follow naming conventions: `snake_case`
+- Add proper validation and error handling
+- Update category enums if adding new categories
+
+## Documentation
+
+### API Documentation
+
+- Update docstrings for all public functions
+- Include usage examples in docstrings
+- Add type hints for better IDE support
+- Document error conditions and exceptions
+
+### User Documentation
+
+Update relevant documentation files:
+
+- **API Reference**: `docs/api/plugins/utils.md`
+- **Feature Guides**: `docs/features/plugins/index.md`
+- **Changelog**: `docs/changelog.md`
+- **Examples**: Add practical usage examples
+
+### Documentation Format
+
+Use clear, concise language with:
+
+- Code examples for all functions
+- Parameter and return value descriptions
+- Error handling examples
+- Migration guides for breaking changes
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Run formatting and linting**:
+   ```bash
+   ruff format .
+   ruff check --fix .
+   ```
+
+2. **Run all tests**:
+   ```bash
+   pytest
+   ```
+
+3. **Update documentation** as needed
+
+4. **Add changelog entry** for significant changes
+
+### Pull Request Guidelines
+
+- **Clear title**: Describe what the PR accomplishes
+- **Detailed description**: Explain the changes and motivation
+- **Reference issues**: Link to relevant GitHub issues
+- **Test coverage**: Ensure new code is tested
+- **Documentation**: Update docs for user-facing changes
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+- [ ] Tests pass locally
+- [ ] New tests added for new functionality
+- [ ] Code formatted with Ruff
+
+## Documentation
+- [ ] API documentation updated
+- [ ] User guide updated if needed
+- [ ] Changelog entry added
+```
+
+## Code Review
+
+### Review Criteria
+
+- **Functionality**: Code works as intended
+- **Quality**: Follows coding standards and best practices
+- **Testing**: Adequate test coverage
+- **Documentation**: Clear documentation for public APIs
+- **Performance**: No obvious performance issues
+- **Security**: No security vulnerabilities
+
+### Responding to Feedback
+
+- Address all reviewer comments
+- Ask for clarification if feedback is unclear
+- Make requested changes promptly
+- Re-run formatting and tests after changes
+
+## Project Structure
+
+Understanding the project organization:
+
+```
+synapse_sdk/
+├── plugins/
+│   ├── utils/              # Plugin utilities (modular)
+│   │   ├── config.py       # Configuration utilities
+│   │   ├── actions.py      # Action management
+│   │   └── registry.py     # Registry utilities
+│   ├── categories/         # Plugin category implementations
+│   └── models.py          # Core plugin models
+├── clients/               # API clients
+├── utils/                 # General utilities
+└── devtools/             # Development tools
+
+tests/
+├── plugins/
+│   └── utils/            # Plugin utility tests
+└── ...                   # Other test modules
+
+docs/                     # Documentation
+├── api/                  # API reference
+├── features/             # Feature guides
+└── changelog.md          # Change log
+```
+
+## Getting Help
+
+- **GitHub Issues**: Report bugs or request features
+- **Discussions**: Ask questions or discuss ideas
+- **Documentation**: Check existing docs first
+- **Code Review**: Ask for clarification during review
+
+## License
+
+By contributing to Synapse SDK, you agree that your contributions will be licensed under the same license as the project (MIT License).