Soothe SDK

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

Version: 1.0.3 (stable). 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.

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-1.0.4.tar.gz (95.4 kB view details)

Uploaded Jul 21, 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-1.0.4-py3-none-any.whl (128.3 kB view details)

Uploaded Jul 21, 2026 Python 3

File details

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

File metadata

Download URL: soothe_sdk-1.0.4.tar.gz
Upload date: Jul 21, 2026
Size: 95.4 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for soothe_sdk-1.0.4.tar.gz
Algorithm	Hash digest
SHA256	`2996f6dc0dac4bd73d8ca0b201927f1d391917d1f4b5826d379d05c2653693c8`
MD5	`d5991999906f7e58a4b5423afe40512d`
BLAKE2b-256	`c9fa99e7f70d71b075fd68df3b25efed949542ca56b70806871d1e4867df1447`

See more details on using hashes here.

File details

Details for the file soothe_sdk-1.0.4-py3-none-any.whl.

File metadata

Download URL: soothe_sdk-1.0.4-py3-none-any.whl
Upload date: Jul 21, 2026
Size: 128.3 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for soothe_sdk-1.0.4-py3-none-any.whl
Algorithm	Hash digest
SHA256	`c2ea938d7c728abb78d678e63b2dc5a345d4d58256fdefd7af0142331f65f347`
MD5	`3b5233d4e8002ae316f761aeb9ed99c8`
BLAKE2b-256	`c6b65a30774c1fa0d4f39db5a1f05f39876b0d600395a596dca480cf81eff149`