Soothe SDK

PyPI - Version

A lightweight, decorator-based SDK for building Soothe plugins and shared contracts (events, wire codec, display/UX helpers, protocols).

The WebSocket transport client lives in soothe-client-python (soothe_client), not in this package.

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

        tools = [self.greet]
        agent = create_react_agent(model, tools)

        return {
            "name": "researcher",
            "description": "Research subagent",
            "runnable": agent,
        }

Features

Decorator-based API: @plugin, @tool, @subagent under soothe_sdk.plugin
Lightweight: Only requires pydantic and langchain-core
Type-safe: Full type hints and Pydantic validation
No runtime dependency: SDK is separate from Soothe runtime
Contracts, not transport: Wire codec under soothe_sdk.wire; paths under soothe_sdk.paths

Canonical imports (1.0.0+)

Root package exports version metadata only. Import from subpackages:

from soothe_sdk import __version__

from soothe_sdk.plugin import (
    plugin,
    tool,
    subagent,
    PluginManifest,
    PluginContext,
    PluginHealth,
    register_event,
    emit_progress,
)
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
from soothe_sdk.wire import messages_from_wire_dicts, ProtocolError
from soothe_sdk.paths import SOOTHE_HOME, SOOTHE_DATA_DIR
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.protocols import AsyncPersistStore, PolicyProtocol

Removed in 1.0.0

Removed	Use instead
`soothe_sdk.client.*`	`soothe_sdk.wire` / `soothe_sdk.paths` (transport: `soothe_client`)
`soothe_sdk.langchain_wire`	`soothe_sdk.wire.codec`
Root re-exports (`plugin`, `SOOTHE_HOME`, …)	Subpackage imports above
`Manifest` / `Context` / `Health` / `Depends`	`PluginManifest` / `PluginContext` / `PluginHealth` / `library`

API Reference

@plugin

from soothe_sdk.plugin import plugin

@plugin(
    name="my-plugin",
    version="1.0.0",
    description="My plugin",
    dependencies=["arxiv>=2.0.0"],
    trust_level="standard",
)
class MyPlugin:
    pass

@tool / @tool_group / @subagent

from soothe_sdk.plugin import plugin, tool, tool_group, subagent

@plugin(name="research", version="1.0.0", description="Research tools")
class ResearchPlugin:
    @tool(name="my-tool", description="What this tool does")
    def my_tool(self, arg: str) -> str:
        return f"Result: {arg}"

    @tool_group(name="search", description="Search tools")
    class SearchTools:
        @tool(name="arxiv")
        def search_arxiv(self, query: str) -> list:
            pass

    @subagent(name="researcher", description="Research subagent", model="openai:gpt-4o-mini")
    async def create_researcher(self, model, config, context):
        return {"name": "researcher", "description": "…", "runnable": agent}

PluginContext / PluginHealth

from soothe_sdk.plugin import PluginContext, PluginHealth

class MyPlugin:
    async def on_load(self, context: PluginContext):
        self.api_key = context.config.get("api_key")
        context.logger.info("Plugin loaded")

    async def health_check(self) -> PluginHealth:
        return PluginHealth(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 and install with pip install my-plugin

Architecture

soothe_sdk/
├── __init__.py              # __version__ only
├── core/                    # Events, exceptions, verbosity
├── plugin/                  # Decorators + PluginManifest/Context/Health
├── wire/                    # Protocol-1 codec + encode/decode
├── paths.py                 # SOOTHE_HOME / SOOTHE_DATA_DIR
├── ux/                      # Loop stream, classification, subagent progress
├── display/                 # Card binder, transcript helpers
├── tools/                   # Tool display metadata
├── protocols/               # PersistStore, VectorStore, Policy
└── utils/                   # Formatting, logging, parsing, serde

Development

pip install -e ".[dev]"
pytest tests/
ruff check src/soothe_sdk/
ruff format src/soothe_sdk/

License

MIT License — see LICENSE for details.

Metadata

Release files for soothe-sdk 1.0.13

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for soothe-sdk 1.0.13
File	Size	Uploaded
soothe_sdk-1.0.13.tar.gz	103.3 kB	Oct 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for soothe-sdk 1.0.13
File	Interpreter	ABI	Platform	Reset
soothe_sdk-1.0.13-py3-none-any.whl 135.5 kB Oct 12, 2026	Python 3	none	any	Details

Total release size: 238.8 kB

Release files / soothe_sdk-1.0.13.tar.gz

Download URL	soothe_sdk-1.0.13.tar.gz
Size	103.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`8e9358fbc2c09a61d1ea4e5f2d11e9e240c35d24446dd534ba6485f2c567a5f6`
BLAKE2b-256 checksum How to use checksums	`dab7f19fe8994545ecf1a13027218228d79f03ff4de33cc8d906f5d9d39bc66d`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mirasoth/soothe
Publishing commit: github.com/mirasoth/soothe/tree/6179b5f5aedc762363aaa1a5198a578ea0e73b9e

Workflow

Publishing configuration: github.com/mirasoth/soothe/blob/6179b5f5aedc762363aaa1a5198a578ea0e73b9e/.github/workflows/release.yml
Publishing logs: github.com/mirasoth/soothe/actions/runs/38199491431/attempts/1

Artifact

Subject: soothe_sdk-1.0.13.tar.gz
SHA-256 checksum: 8e9358fbc2c09a61d1ea4e5f2d11e9e240c35d24446dd534ba6485f2c567a5f6 Verifying attestations

Release files / soothe_sdk-1.0.13-py3-none-any.whl

Download URL	soothe_sdk-1.0.13-py3-none-any.whl
Size	135.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5f1ed0faf33ec07d1aa1700778c17f855f4374b30fb883a03b4eecbfa791ff01`
BLAKE2b-256 checksum How to use checksums	`3cce205151671b54b33c778254e53e80af44ae4dfcfaebbfceabc591523ce798`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mirasoth/soothe
Publishing commit: github.com/mirasoth/soothe/tree/6179b5f5aedc762363aaa1a5198a578ea0e73b9e

Workflow

Publishing configuration: github.com/mirasoth/soothe/blob/6179b5f5aedc762363aaa1a5198a578ea0e73b9e/.github/workflows/release.yml
Publishing logs: github.com/mirasoth/soothe/actions/runs/38199491431/attempts/1

Artifact

Subject: soothe_sdk-1.0.13-py3-none-any.whl
SHA-256 checksum: 5f1ed0faf33ec07d1aa1700778c17f855f4374b30fb883a03b4eecbfa791ff01 Verifying attestations