soothe-plugins 0.2.6__tar.gz

soothe_plugins-0.2.6/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Run linting
+      run: |
+        uv run ruff check src/ tests/ --output-format=github
+        uv run ruff format --check src/ tests/
+
+    - name: Run tests
+      run: uv run pytest tests/ -v --tb=short
+
+    - name: Run tests with coverage
+      if: matrix.python-version == '3.12'
+      run: uv run pytest tests/ --cov=src/soothe_plugins --cov-report=xml --cov-report=term-missing
+
+    - name: Upload coverage report
+      if: matrix.python-version == '3.12'
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report
+        path: coverage.xml
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Build package
+      run: uv build
+
+    - name: Verify package
+      run: |
+        uv run twine check dist/*
+        echo "✅ Package built and verified"

soothe_plugins-0.2.6/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release soothe-plugins
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/soothe-plugins
+
+    steps:
+    - uses: actions/checkout@v5
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "latest"
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Get version
+      id: version
+      run: |
+        VERSION=$(grep '^version = "' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+    - name: Check if version exists on PyPI
+      id: check
+      run: |
+        VERSION="${{ steps.version.outputs.version }}"
+        echo "Checking if soothe-plugins $VERSION exists on PyPI..."
+        if pip index versions soothe-plugins 2>/dev/null | grep -q "$VERSION"; then
+          echo "exists=true" >> $GITHUB_OUTPUT
+          echo "⚠️ Version $VERSION already exists on PyPI, skipping publish"
+        else
+          echo "exists=false" >> $GITHUB_OUTPUT
+          echo "✓ Version $VERSION not found on PyPI, will publish"
+        fi
+
+    - name: Build package
+      if: steps.check.outputs.exists == 'false'
+      run: uv build
+
+    - name: Verify dist directory
+      if: steps.check.outputs.exists == 'false'
+      run: |
+        if [ ! -d "dist" ]; then
+          echo "❌ Error: dist directory not found"
+          exit 1
+        fi
+        if [ -z "$(ls -A dist)" ]; then
+          echo "❌ Error: dist directory is empty"
+          exit 1
+        fi
+        echo "✓ dist directory exists and contains packages"
+        ls -la dist/
+
+    - name: Publish to PyPI
+      if: steps.check.outputs.exists == 'false'
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        verbose: true
+        print-hash: true

soothe_plugins-0.2.6/.gitignore

@@ -0,0 +1,34 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+.vscode/
+.idea/
+*.swp
+*.swo
+.env
+.venv
+venv/
+ENV/
+env/

soothe_plugins-0.2.6/CONTRIBUTING.md

@@ -0,0 +1,328 @@
+# Contributing to Soothe Community Plugins
+
+Thank you for your interest in contributing to soothe-plugins! This guide will help you add new plugins, tools, and subagents.
+
+## Table of Contents
+
+- [Adding a New Plugin](#adding-a-new-plugin)
+- [Plugin Structure](#plugin-structure)
+- [Development Workflow](#development-workflow)
+- [Testing Guidelines](#testing-guidelines)
+- [Code Standards](#code-standards)
+
+## Adding a New Plugin
+
+### 1. Create Plugin Package
+
+Create a new package in `src/soothe_plugins/your_plugin/`:
+
+```
+src/soothe_plugins/
+├── __init__.py
+├── paperscout/
+│   └── ...
+└── your_plugin/
+    ├── __init__.py          # Plugin class with @plugin decorator
+    ├── events.py            # Custom events (optional)
+    ├── models.py            # Data models
+    ├── state.py             # State definitions (if subagent)
+    ├── implementation.py    # Core logic
+    └── README.md            # Plugin documentation
+```
+
+### 2. Define Plugin Class
+
+Create your plugin class in `__init__.py`:
+
+```python
+from soothe_sdk.plugin import plugin, subagent, tool
+
+@plugin(
+    name="your_plugin",
+    version="1.0.0",
+    description="Brief description of your plugin",
+    dependencies=[
+        "required-package>=1.0.0",
+    ],
+    trust_level="standard",  # or "trusted" for privileged plugins
+)
+class YourPlugin:
+    """Your plugin implementation."""
+
+    async def on_load(self, context):
+        """Called when plugin is loaded.
+
+        Args:
+            context: Plugin context with config, logger, and utilities.
+        """
+        # Validate dependencies
+        # Initialize resources
+        context.logger.info("Your plugin loaded")
+
+    @subagent(
+        name="your_agent",
+        description="What your agent does",
+        model="openai:gpt-4o-mini",
+    )
+    async def create_subagent(self, model, config, context, **kwargs):
+        """Create your subagent.
+
+        Returns:
+            Subagent dict with name, description, and runnable.
+        """
+        from .implementation import create_your_subagent
+
+        return create_your_subagent(config=config, **kwargs)
+
+    @tool(
+        name="your_tool",
+        description="What your tool does",
+    )
+    def your_tool(self, arg: str) -> str:
+        """Your tool implementation."""
+        return f"Result: {arg}"
+```
+
+### 3. Register Plugin
+
+Add entry point to `pyproject.toml`:
+
+```toml
+[project.entry-points."soothe.plugins"]
+your_plugin = "soothe_plugins.your_plugin:YourPlugin"
+```
+
+### 4. Add Dependencies
+
+Add required packages to `dependencies` in `pyproject.toml`:
+
+```toml
+dependencies = [
+    # ... existing dependencies ...
+    "your-required-package>=1.0.0",
+]
+```
+
+### 5. Create Tests
+
+Create test suite in `tests/test_your_plugin/`:
+
+```
+tests/
+├── conftest.py
+├── test_paperscout/
+│   └── ...
+└── test_your_plugin/
+    ├── conftest.py        # Plugin-specific fixtures
+    ├── test_events.py     # Event tests
+    ├── test_models.py     # Model tests
+    ├── test_plugin.py     # Plugin lifecycle tests
+    └── test_implementation.py  # Core logic tests
+```
+
+## Plugin Structure
+
+### Subagent Plugins
+
+For agent-based plugins:
+
+```python
+from langgraph.graph import StateGraph
+from deepagents import CompiledSubAgent
+
+def create_your_subagent(config, **kwargs) -> dict:
+    """Create and return a compiled subagent.
+
+    Returns:
+        Dict with 'name', 'description', and 'runnable' (CompiledSubAgent).
+    """
+    # Define state
+    # Create graph
+    # Add nodes and edges
+    # Compile subagent
+    return {
+        "name": "your_agent",
+        "description": "What it does",
+        "runnable": compiled_graph,
+    }
+```
+
+### Tool Plugins
+
+For simple tool-based plugins:
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def your_tool(arg: str) -> str:
+    """Tool description.
+
+    Args:
+        arg: Argument description.
+
+    Returns:
+        Result description.
+    """
+    # Tool implementation
+    return result
+```
+
+## Development Workflow
+
+### 1. Setup Development Environment
+
+```bash
+# Clone repository
+git clone <soothe-plugins-repo>
+cd soothe-plugins
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # or `source .venv/bin/activate.fish`
+
+# Install in development mode
+pip install -e ".[dev]"
+```
+
+### 2. Develop Your Plugin
+
+```bash
+# Create plugin package
+mkdir -p src/soothe_plugins/your_plugin
+
+# Implement plugin
+# Add tests
+
+# Run tests
+pytest tests/test_your_plugin/
+
+# Format code
+ruff format src/soothe_plugins/your_plugin/
+
+# Lint code
+ruff check --fix src/soothe_plugins/your_plugin/
+```
+
+### 3. Test Integration
+
+```bash
+# Test with Soothe
+pip install -e /path/to/soothe
+soothe checkhealth
+
+# Run your plugin
+soothe "test query" --subagent your_agent
+```
+
+## Testing Guidelines
+
+### Test Structure
+
+```python
+# tests/test_your_plugin/test_plugin.py
+
+import pytest
+from soothe_plugins.your_plugin import YourPlugin
+
+@pytest.fixture
+def plugin():
+    """Create plugin instance."""
+    return YourPlugin()
+
+@pytest.mark.asyncio
+async def test_plugin_load(plugin, mock_soothe_config):
+    """Test plugin can load."""
+    context = MagicMock()
+    context.logger = MagicMock()
+
+    await plugin.on_load(context)
+
+    # Verify initialization
+
+def test_plugin_metadata(plugin):
+    """Test plugin metadata."""
+    assert plugin.name == "your_plugin"
+    assert plugin.version == "1.0.0"
+```
+
+### Test Coverage
+
+- **Unit tests**: Test individual functions and classes
+- **Integration tests**: Test plugin with Soothe framework
+- **Event tests**: Test custom event emission
+- **Error handling**: Test error cases
+
+## Code Standards
+
+### Python Style
+
+- **Python >=3.11**
+- **Type hints** on all public functions
+- **Google-style docstrings**
+- **Ruff** for formatting and linting
+- **Line length**: 120 characters
+
+### Docstring Format
+
+```python
+def your_function(arg: str, optional: int = 0) -> dict:
+    """Brief description.
+
+    Args:
+        arg: Description of arg.
+        optional: Description of optional parameter.
+
+    Returns:
+        Description of return value.
+
+    Raises:
+        ValueError: When arg is invalid.
+    """
+    pass
+```
+
+### Event Registration
+
+Register custom events in `events.py`:
+
+```python
+from soothe.core.event_catalog import register_event
+from soothe.core.base_events import SootheEvent
+
+class YourCustomEvent(SootheEvent):
+    type: str = "soothe.community.your_plugin.custom"
+    data: str
+
+# Register at module load time
+register_event(
+    YourCustomEvent,
+    summary_template="Custom event: {data}",
+)
+```
+
+## Submitting Changes
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/your-plugin`)
+3. **Commit** changes (`git commit -m "Add your_plugin"`)
+4. **Push** to branch (`git push origin feature/your-plugin`)
+5. **Open** a Pull Request
+
+### PR Checklist
+
+- [ ] Code follows style guidelines
+- [ ] Tests added and passing
+- [ ] Documentation updated
+- [ ] Entry points registered
+- [ ] Dependencies added to `pyproject.toml`
+
+## Getting Help
+
+- **Issues**: Open an issue on GitHub
+- **Documentation**: See Soothe RFCs and implementation guides
+- **Examples**: Check `sample_echo/` for minimal reference implementation
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

soothe_plugins-0.2.6/MANIFEST.md

@@ -0,0 +1,154 @@
+# Soothe Community Package Structure
+
+This document describes the final polished structure of the soothe-plugins package.
+
+## Package Layout
+
+```
+soothe-plugins-pkg/
+├── .gitignore                    # Git ignore patterns
+├── CONTRIBUTING.md               # Guide for contributors
+├── MIGRATION.md                  # Migration guide for standalone repo
+├── README.md                     # Package overview
+├── pyproject.toml                # Package configuration
+├── src/
+│   └── soothe_plugins/
+│       ├── __init__.py          # Package initialization
+│       ├── paperscout/          # PaperScout plugin
+│       │   ├── __init__.py      # Plugin class
+│       │   ├── email.py         # Email functionality
+│       │   ├── events.py        # Custom events
+│       │   ├── gap_scanner.py   # Gap scanning
+│       │   ├── implementation.py # Subagent creation
+│       │   ├── models.py        # Data models
+│       │   ├── nodes.py         # Graph nodes
+│       │   ├── reranker.py      # Reranking logic
+│       │   └── state.py         # State definitions
+│       ├── .plugin_template/    # Template for new plugins
+│       │   ├── PLUGIN_TEMPLATE.md
+│       │   ├── __init__.py.template
+│       │   ├── events.py.template
+│       │   ├── models.py.template
+│       │   ├── state.py.template
+│       │   ├── implementation.py.template
+│       │   └── README.md.template
+│       └── README.md            # Package-level README
+└── tests/
+    ├── conftest.py              # Shared test fixtures
+    └── test_paperscout/         # PaperScout tests
+        ├── conftest.py
+        ├── test_email.py
+        ├── test_events.py
+        ├── test_models.py
+        ├── test_plugin.py
+        └── test_reranker.py
+```
+
+## Key Features
+
+### 1. Clean Package Structure
+- No nested directories
+- Proper `src/` layout following Python packaging best practices
+- Tests colocated with package
+
+### 2. Extensibility
+- Plugin template directory with all necessary files
+- Clear documentation for adding new plugins
+- CONTRIBUTING.md with detailed guidelines
+
+### 3. Testing
+- All tests moved from main Soothe project
+- Shared fixtures in `tests/conftest.py`
+- Plugin-specific fixtures in each test directory
+
+### 4. Documentation
+- **README.md**: Quick start and overview
+- **CONTRIBUTING.md**: How to contribute and add plugins
+- **MIGRATION.md**: Standalone repository migration guide
+- **Plugin READMEs**: Each plugin has its own documentation
+
+### 5. Build Configuration
+- Proper `pyproject.toml` with all metadata
+- Entry points for plugin discovery
+- Development dependencies
+- Ruff configuration for code quality
+
+## Usage
+
+### Installation
+
+```bash
+pip install soothe-plugins
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Adding a New Plugin
+
+1. Copy the template:
+   ```bash
+   cp -r src/soothe_plugins/.plugin_template src/soothe_plugins/your_plugin
+   ```
+
+2. Rename and update template files
+
+3. Register in `pyproject.toml`:
+   ```toml
+   [project.entry-points."soothe.plugins"]
+   your_plugin = "soothe_plugins.your_plugin:YourPlugin"
+   ```
+
+4. Add tests in `tests/test_your_plugin/`
+
+5. Update README with plugin documentation
+
+## Extensibility Points
+
+The package is designed to support:
+
+1. **Multiple Plugins**: Add new plugins without modifying existing code
+2. **Plugin Types**: Support subagents, tools, or hybrid plugins
+3. **Custom Events**: Each plugin can define its own events
+4. **Independent Testing**: Each plugin has isolated tests
+5. **Documentation**: Each plugin has its own README
+
+## Next Steps
+
+This package is ready for:
+
+1. **Testing**: Verify all tests pass
+2. **Distribution**: Publish to PyPI
+3. **Migration**: Move to standalone repository if desired
+4. **Extension**: Add new community plugins
+
+## Verification Checklist
+
+- [x] Clean directory structure (no nested soothe-plugins-pkg/)
+- [x] Source files in `src/soothe_plugins/`
+- [x] Tests moved from main Soothe project
+- [x] Plugin template created
+- [x] CONTRIBUTING.md with detailed guidelines
+- [x] Updated README with extensibility information
+- [x] Proper pyproject.toml configuration
+- [x] All template files created
+- [ ] Tests passing (requires pytest installation)
+- [ ] Package installable with `pip install -e .`
+
+## Success Metrics
+
+The package structure is complete and ready for:
+
+1. Independent development and testing
+2. Addition of new community plugins
+3. Distribution as a standalone package
+4. Migration to separate repository if desired