soothe-sdk 0.1.0__tar.gz

soothe_sdk-0.1.0/.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_sdk-0.1.0/MANIFEST.md

@@ -0,0 +1,196 @@
+# Soothe SDK Package Structure
+
+This document describes the final polished structure of the soothe-sdk package.
+
+## Package Layout
+
+```
+soothe-sdk-pkg/
+├── .gitignore                    # Git ignore patterns
+├── MIGRATION.md                  # Migration guide for standalone repo
+├── README.md                     # Package overview and API reference
+├── pyproject.toml                # Package configuration
+├── src/
+│   └── soothe_sdk/
+│       ├── __init__.py          # Package initialization and public API
+│       ├── decorators/          # Decorator implementations
+│       │   ├── __init__.py
+│       │   ├── plugin.py        # @plugin decorator
+│       │   ├── subagent.py      # @subagent decorator
+│       │   └── tool.py          # @tool and @tool_group decorators
+│       ├── types/               # Type definitions
+│       │   ├── __init__.py
+│       │   ├── context.py       # PluginContext for lifecycle hooks
+│       │   ├── health.py        # PluginHealth status
+│       │   └── manifest.py      # PluginManifest metadata
+│       ├── exceptions.py        # SDK-specific exceptions
+│       └── depends.py           # Dependency utilities
+└── tests/
+    ├── conftest.py              # Shared test fixtures
+    ├── test_decorators.py       # Decorator functionality tests
+    ├── test_types.py            # Type definition tests
+    └── test_integration.py      # Plugin lifecycle integration tests
+```
+
+## Key Features
+
+### 1. Clean Package Structure
+- No nested directories
+- Proper `src/` layout following Python packaging best practices
+- Tests colocated with package
+
+### 2. Minimal Dependencies
+- Only `pydantic>=2.0.0` for data validation
+- Only `langchain-core>=1.2.0` for base types
+- No runtime dependency on Soothe itself
+
+### 3. Decorator-Based API
+- Simple, declarative plugin definition
+- Type-safe with Pydantic validation
+- Clear separation of concerns
+
+### 4. Comprehensive Testing
+- Unit tests for all decorators
+- Type validation tests
+- Integration tests for plugin lifecycle
+
+### 5. Documentation
+- **README.md**: Quick start and full API reference
+- **MIGRATION.md**: Standalone repository migration guide
+- Inline docstrings with Google-style formatting
+
+### 6. Build Configuration
+- Proper `pyproject.toml` with all metadata
+- Python 3.10-3.14 support
+- Development dependencies
+- Ruff configuration for code quality
+- MyPy configuration for type checking
+
+## Usage
+
+### Installation
+
+```bash
+pip install soothe-sdk
+```
+
+### Development Installation
+
+```bash
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Type Checking
+
+```bash
+mypy src/soothe_sdk/
+```
+
+### Code Quality
+
+```bash
+ruff format src/ tests/
+ruff check --fix src/ tests/
+```
+
+## API Components
+
+### Decorators
+
+1. **@plugin**: Define plugin metadata and class
+   - Required: name, version, description
+   - Optional: dependencies, trust_level
+
+2. **@tool**: Define a tool function
+   - Required: name, description
+   - Automatically wrapped as langchain tool
+
+3. **@tool_group**: Define a group of related tools
+   - Required: name, description
+   - Contains multiple @tool methods
+
+4. **@subagent**: Define a subagent factory
+   - Required: name, description
+   - Optional: default model
+   - Returns dict with name, description, runnable
+
+### Types
+
+1. **PluginManifest**: Plugin metadata
+   - name, version, description
+   - dependencies, trust_level
+   - Semantic version validation
+
+2. **PluginContext**: Lifecycle hook context
+   - config: Plugin-specific configuration
+   - soothe_config: Global Soothe configuration
+   - logger: Plugin logger
+   - emit_event: Event emission function
+
+3. **PluginHealth**: Health check status
+   - status: healthy, degraded, unhealthy
+   - details: Optional error information
+
+### Exceptions
+
+1. **PluginError**: Base exception for all SDK errors
+2. **DiscoveryError**: Plugin discovery failures
+3. **ValidationError**: Metadata validation failures
+4. **DependencyError**: Dependency resolution failures
+5. **InitializationError**: Plugin initialization failures
+6. **ToolCreationError**: Tool creation failures
+7. **SubagentCreationError**: Subagent creation failures
+
+## Extensibility Points
+
+The SDK is designed to support:
+
+1. **Plugin Discovery**: Entry points for automatic plugin loading
+2. **Type Safety**: Full type hints for IDE support
+3. **Validation**: Pydantic models for configuration validation
+4. **Lifecycle Management**: Optional hooks for initialization and cleanup
+5. **Health Monitoring**: Standardized health check interface
+
+## Design Principles
+
+1. **Lightweight**: Minimal dependencies for fast installation
+2. **Type-safe**: Full type hints and Pydantic validation
+3. **Decorator-based**: Simple, declarative plugin definition
+4. **Runtime-agnostic**: No dependency on Soothe runtime
+5. **Extensible**: Support for tools, subagents, and custom events
+
+## 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. **Integration**: Use in Soothe plugin development
+
+## Verification Checklist
+
+- [x] Clean directory structure
+- [x] Source files in `src/soothe_sdk/`
+- [x] Comprehensive test suite
+- [x] Python 3.10-3.14 support
+- [x] Updated README with full API reference
+- [x] Proper pyproject.toml configuration
+- [x] MIGRATION.md for standalone repository
+- [ ] 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. Publication to PyPI
+3. Use as dependency for Soothe plugins
+4. Migration to separate repository if desired

soothe_sdk-0.1.0/MIGRATION.md

@@ -0,0 +1,179 @@
+# Standalone Package Migration Guide
+
+This document describes how to migrate soothe_sdk to a standalone repository.
+
+## Current Status
+
+The `soothe-sdk` package is currently located in the Soothe monorepo at:
+- `soothe-sdk-pkg/` - Standalone package structure
+- `src/soothe_sdk/` - Original location (to be removed after migration)
+
+## Migration Steps
+
+### 1. Create Standalone Repository
+
+```bash
+# Create new repository on GitHub/GitLab
+# Repository: soothe-sdk
+
+# Clone the standalone package structure
+git clone <soothe-repo>
+cd soothe
+
+# Copy standalone package to new location
+cp -r soothe-sdk-pkg ../soothe-sdk/
+cd ../soothe-sdk
+git init
+git add .
+git commit -m "Initial commit: soothe-sdk standalone package"
+git remote add origin <soothe-sdk-repo-url>
+git push -u origin main
+```
+
+### 2. Remove from Soothe Monorepo
+
+After the standalone package is tested and working:
+
+```bash
+# In Soothe monorepo
+rm -rf src/soothe_sdk
+rm -rf soothe-sdk-pkg
+```
+
+### 3. Update Soothe Dependencies
+
+Update `pyproject.toml` in Soothe monorepo:
+
+```toml
+dependencies = [
+    # ... existing dependencies ...
+    "soothe-sdk>=0.1.0,<1.0.0",
+]
+```
+
+### 4. Update Soothe Documentation
+
+Add to Soothe's README.md:
+
+```markdown
+## Plugin Development
+
+To develop plugins for Soothe, use the soothe-sdk package:
+
+```bash
+pip install soothe-sdk
+```
+
+See [soothe-sdk](https://github.com/caesar0301/soothe-sdk) for details.
+```
+
+### 5. Publish to PyPI
+
+```bash
+# Build the package
+cd soothe-sdk
+python -m build
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+### 6. Verify Installation
+
+```bash
+# Install from PyPI
+pip install soothe-sdk
+
+# Verify import
+python -c "from soothe_sdk import plugin, tool, subagent; print('OK')"
+
+# Test with Soothe plugin
+python -c "from soothe.plugin.global_registry import load_plugins; print('OK')"
+```
+
+## Directory Structure
+
+```
+soothe-sdk/
+├── README.md
+├── pyproject.toml
+├── .gitignore
+├── src/
+│   └── soothe_sdk/
+│       ├── __init__.py
+│       ├── decorators/
+│       │   ├── __init__.py
+│       │   ├── plugin.py
+│       │   ├── subagent.py
+│       │   └── tool.py
+│       ├── types/
+│       │   ├── __init__.py
+│       │   ├── context.py
+│       │   ├── health.py
+│       │   └── manifest.py
+│       ├── exceptions.py
+│       └── depends.py
+└── tests/
+    ├── conftest.py
+    ├── test_decorators.py
+    ├── test_types.py
+    └── test_integration.py
+```
+
+## Usage
+
+After installing soothe-sdk:
+
+```python
+from soothe_sdk import plugin, tool, subagent
+
+@plugin(name="my-plugin", version="1.0.0", description="My plugin")
+class MyPlugin:
+    @tool(name="greet", description="Greet someone")
+    def greet(self, name: str) -> str:
+        return f"Hello, {name}!"
+```
+
+## Development
+
+For SDK development:
+
+```bash
+# Clone the repo
+git clone <soothe-sdk-repo>
+cd soothe-sdk
+
+# Install in dev mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Type checking
+mypy src/soothe_sdk/
+
+# Format and lint
+ruff format src/ tests/
+ruff check --fix src/ tests/
+```
+
+## Dependencies
+
+The SDK maintains minimal dependencies:
+
+- **pydantic>=2.0.0**: For data validation and settings management
+- **langchain-core>=1.2.0**: For tool and subagent base types
+
+## Version Compatibility
+
+The SDK declares compatibility with Soothe:
+
+```python
+__soothe_required_version__ = ">=0.1.0,<1.0.0"
+```
+
+## Support
+
+- **Issues**: <soothe-sdk-repo>/issues
+- **Documentation**: <soothe-sdk-repo>/README.md
+- **Soothe Docs**: <soothe-repo>/docs/

soothe_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,270 @@
+Metadata-Version: 2.4
+Name: soothe-sdk
+Version: 0.1.0
+Summary: SDK for building Soothe plugins with decorator-based API
+Project-URL: Homepage, https://github.com/caesar0301/soothe
+Project-URL: Documentation, https://soothe.readthedocs.io
+Project-URL: Repository, https://github.com/caesar0301/soothe
+License: MIT
+Keywords: agents,ai,llm,plugins,sdk,soothe
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.10
+Requires-Dist: langchain-core<2.0.0,>=1.2.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Soothe SDK
+
+A lightweight, decorator-based SDK for building Soothe plugins.
+
+## Installation
+
+```bash
+pip install soothe-sdk
+```
+
+## Quick Start
+
+```python
+from soothe_sdk import plugin, tool, subagent
+
+@plugin(
+    name="my-plugin",
+    version="1.0.0",
+    description="My awesome plugin",
+    dependencies=["langchain>=0.1.0"],
+)
+class MyPlugin:
+    """My custom plugin with tools and subagents."""
+
+    @tool(name="greet", description="Greet someone by name")
+    def greet(self, name: str) -> str:
+        """Greet a person."""
+        return f"Hello, {name}!"
+
+    @subagent(
+        name="researcher",
+        description="Research subagent with web search",
+        model="openai:gpt-4o-mini",
+    )
+    async def create_researcher(self, model, config, context):
+        """Create research subagent."""
+        from langgraph.prebuilt import create_react_agent
+
+        # Get tools
+        tools = [self.greet]
+
+        # Create agent
+        agent = create_react_agent(model, tools)
+
+        return {
+            "name": "researcher",
+            "description": "Research subagent",
+            "runnable": agent,
+        }
+```
+
+## Features
+
+- **Decorator-based API**: Simple `@plugin`, `@tool`, `@subagent` decorators
+- **Lightweight**: Only requires `pydantic` and `langchain-core`
+- **Type-safe**: Full type hints and Pydantic validation
+- **No runtime dependency**: SDK is separate from Soothe runtime
+
+## API Reference
+
+### @plugin
+
+Defines a Soothe plugin with metadata.
+
+```python
+@plugin(
+    name="my-plugin",           # Required: unique identifier
+    version="1.0.0",           # Required: semantic version
+    description="My plugin",   # Required: description
+    dependencies=["arxiv>=2.0.0"],  # Optional: library dependencies
+    trust_level="standard",    # Optional: built-in, trusted, standard, untrusted
+)
+class MyPlugin:
+    pass
+```
+
+### @tool
+
+Defines a tool that can be used by the agent.
+
+```python
+@tool(name="my-tool", description="What this tool does")
+def my_tool(self, arg: str) -> str:
+    return f"Result: {arg}"
+```
+
+### @tool_group
+
+Organizes multiple related tools.
+
+```python
+@tool_group(name="research", description="Research tools")
+class ResearchTools:
+    @tool(name="arxiv")
+    def search_arxiv(self, query: str) -> list:
+        pass
+
+    @tool(name="scholar")
+    def search_scholar(self, query: str) -> list:
+        pass
+```
+
+### @subagent
+
+Defines a subagent factory.
+
+```python
+@subagent(
+    name="researcher",
+    description="Research subagent",
+    model="openai:gpt-4o-mini",  # Optional default model
+)
+async def create_researcher(self, model, config, context):
+    # Create and return subagent
+    return {
+        "name": "researcher",
+        "description": "Research subagent",
+        "runnable": agent,
+    }
+```
+
+### PluginContext
+
+Provides access to Soothe internals in lifecycle hooks.
+
+```python
+class MyPlugin:
+    async def on_load(self, context: PluginContext):
+        # Plugin-specific config
+        self.api_key = context.config.get("api_key")
+
+        # Global Soothe config
+        self.model = context.soothe_config.resolve_model("default")
+
+        # Logging
+        context.logger.info("Plugin loaded")
+
+        # Events
+        context.emit_event("plugin.loaded", {"name": "my-plugin"})
+```
+
+## Plugin Lifecycle
+
+Plugins can implement optional lifecycle hooks:
+
+```python
+class MyPlugin:
+    async def on_load(self, context: PluginContext):
+        """Called when plugin is loaded. Initialize resources."""
+        pass
+
+    async def on_unload(self):
+        """Called when plugin is unloaded. Clean up resources."""
+        pass
+
+    async def health_check(self):
+        """Return plugin health status."""
+        from soothe_sdk.types import PluginHealth
+        return PluginHealth(status="healthy")
+```
+
+## Publishing Your Plugin
+
+1. Create a Python package with your plugin class
+2. Add the entry point in `pyproject.toml`:
+
+```toml
+[project.entry-points."soothe.plugins"]
+my_plugin = "my_package:MyPlugin"
+```
+
+3. Publish to PyPI:
+
+```bash
+pip install build
+python -m build
+twine upload dist/*
+```
+
+4. Users can install and use your plugin:
+
+```bash
+pip install my-plugin
+```
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Type checking
+mypy src/soothe_sdk/
+
+# Linting
+ruff check src/soothe_sdk/
+
+# Formatting
+ruff format src/soothe_sdk/
+```
+
+## Architecture
+
+The SDK provides decorator-based APIs for defining plugins:
+
+```
+soothe_sdk/
+├── decorators/
+│   ├── plugin.py      # @plugin decorator
+│   ├── tool.py        # @tool and @tool_group decorators
+│   └── subagent.py    # @subagent decorator
+├── types/
+│   ├── manifest.py    # PluginManifest metadata
+│   ├── context.py     # PluginContext for lifecycle hooks
+│   └── health.py      # PluginHealth status
+├── exceptions.py      # SDK-specific exceptions
+└── depends.py         # Dependency utilities
+```
+
+## Key Design Principles
+
+1. **Lightweight**: Minimal dependencies (only `pydantic` and `langchain-core`)
+2. **Type-safe**: Full type hints and Pydantic validation
+3. **Decorator-based**: Simple, declarative plugin definition
+4. **Runtime-agnostic**: No dependency on Soothe runtime
+5. **Extensible**: Support for tools, subagents, and custom events
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Soothe Documentation](https://soothe.readthedocs.io)
+- [Plugin Development Guide](https://soothe.readthedocs.io/plugins/)
+- [GitHub Repository](https://github.com/caesar0301/soothe)