synapse-action-development

# Synapse Action Development

Synapse SDK provides two patterns for plugin actions: **function-based** (simple, stateless) and **class-based** (complex, stateful).

## Quick Start: Function-Based Action

```python
from pydantic import BaseModel
from synapse_sdk.plugins.decorators import action
from synapse_sdk.plugins.context import RuntimeContext

class TrainParams(BaseModel):
    epochs: int = 10
    learning_rate: float = 0.001

@action(name='train', description='Train a model', params=TrainParams)
def train(params: TrainParams, ctx: RuntimeContext) -> dict:
    for epoch in range(params.epochs):
        ctx.set_progress(epoch + 1, params.epochs)
    return {'status': 'completed'}
```

## Quick Start: Class-Based Action

```python
from pydantic import BaseModel
from synapse_sdk.plugins.action import BaseAction

class InferParams(BaseModel):
    model_path: str
    threshold: float = 0.5

class InferAction(BaseAction[InferParams]):
    action_name = 'inference'

    def execute(self) -> dict:
        self.set_progress(0, 100)
        # Implementation here
        return {'predictions': []}
```

## When to Use Each Pattern

| Criteria | Function-Based | Class-Based |
|----------|----------------|-------------|
| Complexity | Simple, single-purpose | Complex, multi-step |
| State | Stateless | Can use helper methods |
| Semantic types | Limited | Full support |

**Recommendation**: Start with function-based. Use class-based when needing helper methods or semantic type declarations.

## @action Decorator Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `name` | No | Action name (defaults to function name) |
| `description` | No | Human-readable description |
| `params` | No | Pydantic model for parameter validation |
| `result` | No | Pydantic model for result validation |
| `category` | No | PluginCategory for grouping |

### Category Parameter Examples

```python
from synapse_sdk.plugins.decorators import action
from synap