soothe-plugins 0.2.6__py3-none-any.whl

soothe_plugins/.plugin_template/PLUGIN_TEMPLATE.md

@@ -0,0 +1,40 @@
+# Plugin Template
+
+This directory serves as a template for creating new plugins in soothe-plugins.
+
+## Quick Start
+
+1. Copy this template:
+   ```bash
+   cp -r src/soothe_plugins/.plugin_template src/soothe_plugins/your_plugin
+   ```
+
+2. Rename files:
+   - `__init__.py.template` → `__init__.py`
+   - `events.py.template` → `events.py`
+   - `models.py.template` → `models.py`
+   - `state.py.template` → `state.py`
+   - `implementation.py.template` → `implementation.py`
+
+3. Update content:
+   - Replace `your_plugin` with your plugin name
+   - Replace `YourPlugin` with your class name
+   - Add your dependencies to `pyproject.toml`
+   - Register entry point in `pyproject.toml`
+
+4. Add tests in `tests/test_your_plugin/`
+
+5. Update documentation in your plugin's `README.md`
+
+## Template Files
+
+- `__init__.py.template` - Plugin class with decorators
+- `events.py.template` - Custom events
+- `models.py.template` - Data models
+- `state.py.template` - State definitions (for subagents)
+- `implementation.py.template` - Core logic
+- `README.md.template` - Plugin documentation
+
+## Example: PaperScout Plugin
+
+See `src/soothe_plugins/paperscout/` for a complete example.

soothe_plugins/.plugin_template/README.md.template

@@ -0,0 +1,152 @@
+# Your Plugin Name
+
+Brief description of your plugin and what it does.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Installation
+
+```bash
+pip install soothe-community
+```
+
+## Configuration
+
+Add to your Soothe `config.yml`:
+
+```yaml
+subagents:
+  your_agent:
+    enabled: true
+    model: "openai:gpt-4o-mini"
+    config:
+      option1: value1
+      option2: value2
+      max_items: 100
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `option1` | str | "default_value" | Description of option1 |
+| `option2` | int | 10 | Description of option2 |
+| `max_items` | int | 100 | Maximum items to process |
+
+## Usage
+
+### As Subagent
+
+```bash
+# Via TUI (default)
+soothe "your query here" --subagent your_agent
+
+# Headless mode
+soothe "your query" --subagent your_agent --no-tui
+```
+
+### As Tool
+
+The plugin also provides tools that can be used directly:
+
+```python
+from soothe_community.your_plugin import YourPlugin
+
+plugin = YourPlugin()
+result = plugin.your_tool("input")
+```
+
+## Examples
+
+### Example 1: Basic Usage
+
+```bash
+soothe "process data" --subagent your_agent
+```
+
+### Example 2: Advanced Usage
+
+```bash
+soothe "complex operation with parameters" --subagent your_agent --config custom_config.yml
+```
+
+## Architecture
+
+Your plugin consists of:
+
+- **Plugin Class**: Main entry point with `@plugin` decorator
+- **Subagent**: Agent graph for complex workflows
+- **Tools**: Individual tools for simple operations
+- **Events**: Custom events for monitoring
+
+## Development
+
+### Setup
+
+```bash
+# Clone soothe-community
+git clone <repo>
+cd soothe-community
+
+# Install in dev mode
+pip install -e ".[dev]"
+```
+
+### Testing
+
+```bash
+pytest tests/test_your_plugin/
+```
+
+### Code Quality
+
+```bash
+# Format
+ruff format src/soothe_community/your_plugin/
+
+# Lint
+ruff check --fix src/soothe_community/your_plugin/
+```
+
+## API Reference
+
+### YourPlugin
+
+Main plugin class.
+
+#### Methods
+
+- `on_load(context)`: Initialize plugin
+- `create_subagent(model, config, context, **kwargs)`: Create subagent
+- `your_tool(arg)`: Tool function
+
+### YourConfig
+
+Configuration model.
+
+### YourState
+
+State model for subagent.
+
+## Dependencies
+
+- `soothe>=0.1.0` - Core framework
+- `langgraph>=0.2.0` - Graph orchestration
+- `required-package>=1.0.0` - Your dependency
+
+## License
+
+MIT
+
+## Support
+
+- **Issues**: GitHub Issues
+- **Documentation**: See `docs/` in soothe-community repo
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.

soothe_plugins/.plugin_template/__init__.py.template

@@ -0,0 +1,174 @@
+"""Your plugin description.
+
+Detailed description of what your plugin does, its features, and use cases.
+
+Installation:
+    pip install soothe-community
+
+Configuration (config.yml):
+    subagents:
+      your_agent:
+        enabled: true
+        model: "openai:gpt-4o-mini"
+        config:
+          option1: value1
+          option2: value2
+
+Usage:
+    soothe "your query" --subagent your_agent
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from soothe_sdk.core.exceptions import PluginError
+from soothe_sdk.plugin import plugin, subagent, tool
+
+__all__ = [
+    "YourPlugin",
+]
+
+logger = logging.getLogger(__name__)
+
+
+@plugin(
+    name="your_plugin",
+    version="1.0.0",
+    description="Brief description of your plugin",
+    dependencies=[
+        "required-package>=1.0.0",
+    ],
+    trust_level="standard",
+)
+class YourPlugin:
+    """Your plugin implementation.
+
+    This plugin provides:
+    - Feature 1
+    - Feature 2
+    - Feature 3
+    """
+
+    async def on_load(self, context: Any) -> None:
+        """Validate dependencies and initialize plugin.
+
+        Args:
+            context: Plugin context with config, logger, and utilities.
+
+        Raises:
+            PluginError: If required dependencies are not installed.
+        """
+        context.logger.info("Loading your_plugin...")
+
+        # Validate dependencies
+        missing_deps = []
+
+        try:
+            import required_package  # noqa: F401
+        except ImportError:
+            missing_deps.append("required-package>=1.0.0")
+
+        if missing_deps:
+            msg = (
+                f"Missing required dependencies: {', '.join(missing_deps)}. "
+                "Install with: pip install soothe-community"
+            )
+            raise PluginError(msg)
+
+        context.logger.info("your_plugin loaded successfully")
+
+    @subagent(
+        name="your_agent",
+        description=(
+            "Detailed description of what your agent does and when to use it. "
+            "This helps the orchestrator decide when to invoke your subagent."
+        ),
+        model="openai:gpt-4o-mini",
+    )
+    async def create_subagent(
+        self,
+        model: Any,
+        config: Any,
+        context: Any,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Create your subagent.
+
+        Args:
+            model: Resolved model (BaseChatModel or string).
+            config: Soothe configuration.
+            context: Plugin context.
+            **kwargs: Additional configuration (store, user_id, etc.).
+
+        Returns:
+            Subagent dict with name, description, and runnable.
+        """
+        from .implementation import create_your_subagent
+        from .state import YourConfig
+
+        # Get plugin configuration
+        plugin_config = None
+        if hasattr(config, "subagents") and "your_agent" in config.subagents:
+            subagent_config = config.subagents["your_agent"]
+            if subagent_config.enabled and subagent_config.config:
+                plugin_config = YourConfig(**subagent_config.config)
+
+        if not plugin_config:
+            plugin_config = YourConfig()
+
+        # AsyncPersistStore from plugin context (daemon injects persistence)
+        store = kwargs.get("store")
+        if not store and hasattr(config, "services"):
+            store = config.services.get("persistence")
+        if not store:
+            msg = "your_agent requires AsyncPersistStore (e.g. kwargs['store'] or config.services)"
+            raise ValueError(msg)
+
+        user_id = kwargs.get("user_id", "default")
+
+        # Create subagent
+        subagent_dict = create_your_subagent(
+            config=plugin_config,
+            store=store,
+            user_id=user_id,
+        )
+
+        context.logger.info(
+            f"Created your_agent subagent for user {user_id}"
+        )
+
+        return subagent_dict
+
+    @tool(
+        name="your_tool",
+        description="Brief description of what your tool does",
+    )
+    def your_tool(self, arg: str) -> str:
+        """Your tool implementation.
+
+        Args:
+            arg: Description of argument.
+
+        Returns:
+            Description of return value.
+        """
+        # Tool logic here
+        return f"Result: {arg}"
+
+    def get_subagents(self) -> list[Any]:
+        """Get list of subagent factory functions.
+
+        Returns:
+            List containing subagent factory methods.
+        """
+        return [self.create_subagent]
+
+    def get_tools(self) -> list[Any]:
+        """Get list of tool functions.
+
+        Returns:
+            List containing tool methods.
+        """
+        return [self.your_tool]

soothe_plugins/.plugin_template/events.py.template

@@ -0,0 +1,34 @@
+"""Custom events for your plugin.
+
+Register plugin-specific events that can be emitted during execution.
+"""
+
+from typing import Literal
+
+from pydantic import ConfigDict
+
+from soothe_sdk.core.events import SubagentEvent
+from soothe_sdk.core.verbosity import VerbosityTier
+from soothe_sdk.plugin.registry import register_event
+
+
+class YourCustomEvent(SubagentEvent):
+    """Custom event for your plugin.
+
+    Attributes:
+        type: Event type identifier.
+        data: Event data.
+    """
+
+    type: Literal["soothe.community.your_plugin.custom"] = "soothe.community.your_plugin.custom"
+    data: str = ""
+
+    model_config = ConfigDict(extra="allow")
+
+
+# Register events at module load time
+register_event(
+    YourCustomEvent,
+    verbosity=VerbosityTier.NORMAL,
+    summary_template="Your plugin event: {data}",
+)

soothe_plugins/.plugin_template/implementation.py.template

@@ -0,0 +1,112 @@
+"""Implementation of your plugin's core logic.
+
+This module contains the factory function to create your subagent
+and the node functions that make up your agent graph.
+"""
+
+from typing import Any
+
+from deepagents import CompiledSubAgent
+from langgraph.graph import END, StateGraph
+
+from .events import YourCustomEvent
+from .state import YourConfig, YourState
+
+
+def create_your_subagent(
+    config: YourConfig,
+    store: Any = None,
+    user_id: str = "default",
+) -> dict[str, Any]:
+    """Create and compile your subagent.
+
+    Args:
+        config: Plugin configuration.
+        store: Persistence store for state.
+        user_id: User identifier.
+
+    Returns:
+        Dict with name, description, and runnable (CompiledSubAgent).
+    """
+    # Create the graph
+    graph = StateGraph(YourState)
+
+    # Add nodes
+    graph.add_node("initialize", initialize_node)
+    graph.add_node("process", process_node)
+    graph.add_node("finalize", finalize_node)
+
+    # Define edges
+    graph.set_entry_point("initialize")
+    graph.add_edge("initialize", "process")
+    graph.add_edge("process", "finalize")
+    graph.add_edge("finalize", END)
+
+    # Compile the graph
+    compiled = graph.compile(
+        store=store,
+        checkpointer=None,  # Add checkpointer if needed
+    )
+
+    return {
+        "name": "your_agent",
+        "description": "What your agent does",
+        "runnable": compiled,
+    }
+
+
+async def initialize_node(state: YourState) -> dict[str, Any]:
+    """Initialize node: setup and validate input.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        State updates.
+    """
+    # Initialize processing
+    # Validate inputs
+    # Setup resources
+
+    return {
+        "results": [],
+        "errors": [],
+    }
+
+
+async def process_node(state: YourState) -> dict[str, Any]:
+    """Process node: main processing logic.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        State updates.
+    """
+    # Main processing logic
+    # Call external APIs
+    # Process data
+
+    # Emit custom event
+    event = YourCustomEvent(data="Processing complete")
+    # Note: Events are emitted via the event system
+
+    return {
+        "results": [result],
+    }
+
+
+async def finalize_node(state: YourState) -> dict[str, Any]:
+    """Finalize node: cleanup and summary.
+
+    Args:
+        state: Current state.
+
+    Returns:
+        State updates.
+    """
+    # Cleanup resources
+    # Generate summary
+    # Prepare output
+
+    return {}

soothe_plugins/.plugin_template/models.py.template

@@ -0,0 +1,39 @@
+"""Data models for your plugin.
+
+Define Pydantic models for structured data used by your plugin.
+"""
+
+from datetime import datetime
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+
+class YourDataModel(BaseModel):
+    """Sample data model.
+
+    Attributes:
+        id: Unique identifier.
+        name: Name or title.
+        created_at: Creation timestamp.
+        metadata: Optional metadata.
+    """
+
+    id: str
+    name: str
+    created_at: datetime = Field(default_factory=datetime.now)
+    metadata: Optional[dict[str, Any]] = None
+
+
+class YourResult(BaseModel):
+    """Result model for your plugin operations.
+
+    Attributes:
+        success: Whether operation succeeded.
+        data: Result data.
+        error: Error message if failed.
+    """
+
+    success: bool
+    data: Optional[YourDataModel] = None
+    error: Optional[str] = None

soothe_plugins/.plugin_template/state.py.template

@@ -0,0 +1,48 @@
+"""State definitions for your subagent.
+
+Define the state that flows through your agent's graph.
+"""
+
+from typing import Annotated, Any, Optional
+
+from langgraph.graph import add_messages
+from pydantic import BaseModel, Field
+
+
+class YourConfig(BaseModel):
+    """Configuration for your plugin.
+
+    Attributes:
+        option1: Configuration option 1.
+        option2: Configuration option 2.
+        max_items: Maximum number of items to process.
+    """
+
+    option1: str = "default_value"
+    option2: int = 10
+    max_items: int = 100
+
+
+class YourState(BaseModel):
+    """State for your subagent.
+
+    This state flows through the agent graph and is updated by nodes.
+
+    Attributes:
+        messages: Conversation messages (for LLM interactions).
+        input_data: Input data to process.
+        results: Processing results.
+        errors: Any errors encountered.
+        config: Plugin configuration.
+    """
+
+    # Messages for LLM interactions
+    messages: Annotated[list[Any], add_messages] = Field(default_factory=list)
+
+    # Plugin-specific state
+    input_data: Optional[Any] = None
+    results: list[Any] = Field(default_factory=list)
+    errors: list[str] = Field(default_factory=list)
+
+    # Configuration
+    config: YourConfig = Field(default_factory=YourConfig)