Soothe SDK

A lightweight, decorator-based SDK for building Soothe plugins.

Installation

pip install soothe-sdk

Quick Start

from soothe_sdk.plugin 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.

@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.

@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.

@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.

@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.

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:

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.plugin import Health
        return Health(status="healthy")

Publishing Your Plugin

Create a Python package with your plugin class
Add the entry point in pyproject.toml:

[project.entry-points."soothe.plugins"]
my_plugin = "my_package:MyPlugin"

Publish to PyPI:

pip install build
python -m build
twine upload dist/*

Users can install and use your plugin:

pip install my-plugin

Development

# 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 with clear folder organization (v0.4.0+ structure, refactored in IG-259):

soothe_sdk/
├── __init__.py              # Version info
├── core/                    # Core domain concepts (NEW)
│   ├── events.py            # Event classes + 50+ type constants
│   ├── exceptions.py        # Exception hierarchy
│   ├── types.py             # VerbosityLevel (single definition)
│   └── verbosity.py         # VerbosityTier + should_show()
├── client/                  # Client utilities (WebSocket + wire)
│   ├── websocket.py         # WebSocketClient
│   ├── wire.py              # LangChain message normalization (NEW)
│   ├── config.py            # Config constants + types
│   ├── session.py           # Connection bootstrap
│   ├── helpers.py           # Daemon RPC helpers
│   ├── protocol.py          # IPC encode/decode
│   └ schemas.py             # Wire-safe schemas
├── plugin/                  # Plugin API (decorators + types)
│   ├── decorators.py        # @plugin, @tool, @tool_group, @subagent
│   ├── manifest.py          # PluginManifest (Manifest alias)
│   ├── context.py           # PluginContext (Context alias)
│   ├── health.py            # PluginHealth (Health alias)
│   ├── registry.py          # register_event() API
│   ├── emit.py              # emit_progress(), set_stream_writer()
│   └ depends.py             # library() helper
├── ux/                      # UX/display helpers
│   ├── loop_stream.py       # Loop ``messages`` + ``phase`` assistant output (RFC-614)
│   ├── classification.py    # classify_event_to_tier
│   ├── internal.py          # Internal content filtering
│   ├── subagent_progress.py # Subagent progress whitelist
│   └ types.py               # ESSENTIAL_EVENT_TYPES
├── tools/                   # Tool domain logic (NEW)
│   └── metadata.py          # Tool display registry (740 lines)
├── protocols/               # Protocol definitions (stable interfaces)
│   ├── persistence.py       # PersistStore protocol
│   ├── vector_store.py      # VectorStoreProtocol
│   └ policy.py              # PolicyProtocol + Permission classes
├── utils/                   # Shared utilities
│   ├── formatting.py        # CLI formatting (renamed from display.py)
│   ├── logging.py           # Logging setup + GlobalInputHistory
│   ├── parsing.py           # Goal/env parsing + PATH_ARG_PATTERN
│   ├── serde.py             # LangGraph checkpoint serde
│   └── workspace.py         # Workspace validation

Import Pattern (v0.4.0+ canonical paths):

# Core concepts - import from core package (NEW canonical)
from soothe_sdk.core.events import SootheEvent, OutputEvent
from soothe_sdk.core.exceptions import PluginError
from soothe_sdk.core.types import VerbosityLevel
from soothe_sdk.core.verbosity import VerbosityTier, should_show

# Purpose packages - import from subpackage
from soothe_sdk.plugin import plugin, tool, subagent, register_event
from soothe_sdk.client import WebSocketClient, VerbosityLevel
from soothe_sdk.client.wire import messages_from_wire_dicts
from soothe_sdk.ux.loop_stream import assistant_output_phase, LOOP_ASSISTANT_OUTPUT_PHASES
from soothe_sdk.tools.metadata import get_tool_meta, get_tool_display_name
from soothe_sdk.utils.formatting import format_cli_error, log_preview
from soothe_sdk.utils.parsing import PATH_ARG_PATTERN
from soothe_sdk.protocols import PersistStore, PolicyProtocol

Key Design Principles

Lightweight: Minimal dependencies (only pydantic and langchain-core)
Type-safe: Full type hints and Pydantic validation
Decorator-based: Simple, declarative plugin definition
Runtime-agnostic: No dependency on Soothe runtime
Extensible: Support for tools, subagents, and custom events

License

MIT License - see LICENSE for details.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

soothe_sdk-0.8.0.tar.gz (104.6 kB view details)

Uploaded Jul 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

soothe_sdk-0.8.0-py3-none-any.whl (131.8 kB view details)

Uploaded Jul 15, 2026 Python 3

File details

Details for the file soothe_sdk-0.8.0.tar.gz.

File metadata

Download URL: soothe_sdk-0.8.0.tar.gz
Upload date: Jul 15, 2026
Size: 104.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for soothe_sdk-0.8.0.tar.gz
Algorithm	Hash digest
SHA256	`97591f15986b376ec37c9c9637147611517e8a53f4c4bc802b1c2066a6b8bb11`
MD5	`0fe317f64b38302b6a1e7fb81176bd5c`
BLAKE2b-256	`9c0aaef62a9d7e0f8ca06467f7930dbca4f2d936d3effd9a58bca6044dc63deb`

See more details on using hashes here.

Provenance

The following attestation bundles were made for soothe_sdk-0.8.0.tar.gz:

Publisher: release.yml on mirasoth/soothe

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: soothe_sdk-0.8.0.tar.gz
- Subject digest: 97591f15986b376ec37c9c9637147611517e8a53f4c4bc802b1c2066a6b8bb11
- Sigstore transparency entry: 2172629033
- Sigstore integration time: Jul 15, 2026
Source repository:
- Permalink: mirasoth/soothe@5a7dc9e0e3ea4a302e28ac6551f8a3d82f470ffc
- Branch / Tag: refs/tags/v0.8.0
- Owner: https://github.com/mirasoth
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5a7dc9e0e3ea4a302e28ac6551f8a3d82f470ffc
- Trigger Event: release