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

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/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).

synapse_sdk/devtools/docs/docs/examples/index.md

@@ -0,0 +1,29 @@
+---
+id: index
+title: Examples
+sidebar_position: 1
+---
+
+# Examples
+
+Practical examples and tutorials for using Synapse SDK.
+
+## Getting Started Examples
+
+Basic examples to help you get started quickly.
+
+## Plugin Examples
+
+Real-world plugin examples for different use cases.
+
+## Integration Examples
+
+Examples of integrating Synapse SDK with other tools and services.
+
+## Advanced Examples
+
+Complex workflows and advanced usage patterns.
+
+## Code Samples
+
+Ready-to-use code snippets for common operations.

synapse_sdk/devtools/docs/docs/faq.md

@@ -0,0 +1,179 @@
+---
+id: faq
+title: Frequently Asked Questions
+sidebar_position: 9
+---
+
+# Frequently Asked Questions
+
+Common questions and answers about Synapse SDK.
+
+## Installation & Setup
+
+### Q: What Python versions are supported?
+
+Synapse SDK requires **Python 3.10 or higher**.
+
+```bash
+pip install "synapse-sdk[all,devtools]"
+```
+
+### Q: How do I install code-server for local development?
+
+You have several options:
+
+```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 installation methods, visit: [code-server installation guide](https://coder.com/docs/code-server/latest/install)
+
+## CLI Usage
+
+### Q: How do I start the Synapse CLI?
+
+Simply run:
+
+```bash
+synapse
+```
+
+This opens the interactive menu where you can access all Synapse features.
+
+### Q: What's the difference between agent and local code-server?
+
+- **Agent Code-Server**: Runs on a remote agent with your project files synced. Includes plugin encryption and secure transfer.
+- **Local Code-Server**: Runs on your local machine. Faster startup, uses your local environment and settings.
+
+### Q: How do I configure the code-server port?
+
+Code-server port is automatically detected from `~/.config/code-server/config.yaml`. If no config exists, it defaults to port 8070.
+
+Example config:
+
+```yaml
+bind-addr: 127.0.0.1:8070
+auth: password
+password: your-password-here
+cert: false
+```
+
+### Q: Why does the agent workspace path differ from my local path?
+
+Agents run in containerized environments where your local project is mounted to `/home/coder/workspace`. This is normal and ensures consistent paths across different development environments.
+
+## Code-Server Troubleshooting
+
+### Q: Code-server shows "not available" error
+
+This usually means:
+
+1. The agent doesn't have code-server support enabled
+2. Network connectivity issues
+3. Agent is not properly configured
+
+**Solution**: Reinstall the agent with code-server support, or check agent configuration.
+
+### Q: Browser doesn't open automatically
+
+This happens in headless environments or when display is not available.
+
+**Solution**: Manually copy the provided URL (including the `?folder=` parameter) to your browser.
+
+### Q: Plugin not detected in workspace
+
+**Solution**: Ensure your directory contains a valid `config.yaml` file with plugin metadata:
+
+```yaml
+name: my-plugin
+version: 1.0.0
+description: My awesome plugin
+entry_point: main.py
+```
+
+### Q: How does plugin encryption work?
+
+When opening code-server with an agent, Synapse:
+
+1. Detects if your workspace contains a plugin
+2. Creates a ZIP archive of the plugin files
+3. Encrypts the archive using AES-256 encryption
+4. Securely transfers it to the agent
+5. Decrypts and extracts it in the agent workspace
+
+This ensures your plugin code is protected during transfer.
+
+## Configuration
+
+### Q: Where are configuration files stored?
+
+- **Synapse Config**: `~/.synapse/devtools.yaml`
+- **Code-Server Config**: `~/.config/code-server/config.yaml`
+
+### Q: How do I reset my configuration?
+
+```bash
+# Remove configuration files
+rm ~/.synapse/devtools.yaml
+rm ~/.config/code-server/config.yaml
+
+# Run configuration wizard
+synapse config
+```
+
+### Q: What if I get "Invalid token (401)" error?
+
+This means your API token is expired or invalid.
+
+**Solution**:
+
+1. Generate a new token from your Synapse backend
+2. Run `synapse config` to update the token
+3. Test connection with `synapse --dev-tools`
+
+## Plugin Development
+
+### Q: How do I create a new plugin?
+
+Use the interactive plugin creator:
+
+```bash
+synapse
+# Select "🔌 Plugin Management" → "Create new plugin"
+```
+
+This creates a complete plugin structure with examples and documentation.
+
+### Q: How do I test plugins locally?
+
+```bash
+# Test with local script execution
+synapse plugin run my_action '{"param": "value"}' --run-by script
+
+# Test with agent execution
+synapse plugin run my_action '{"param": "value"}' --run-by agent
+```
+
+Always test locally before publishing to ensure your plugin works correctly.
+
+### Q: Plugin publishing fails with errors
+
+Common issues:
+
+1. **Missing dependencies**: Ensure `requirements.txt` includes all needed packages
+2. **Syntax errors**: Test locally first with `--run-by script`
+3. **Configuration errors**: Check `config.yaml` format and required fields
+4. **Backend connectivity**: Ensure backend is accessible and token is valid
+
+**Solution**: Use debug mode for detailed error information:
+
+```bash
+synapse plugin publish --debug
+```