Soothe SDK
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,@subagentundersoothe_sdk.plugin - Lightweight: Only requires
pydanticandlangchain-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 undersoothe_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.
Links
1 maintainer
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.8.tar.gz
(97.9 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
soothe_sdk-1.0.8-py3-none-any.whl
(131.6 kB
view details)
File details
Details for the file soothe_sdk-1.0.8.tar.gz.
File metadata
- Download URL: soothe_sdk-1.0.8.tar.gz
- Upload date:
- Size: 97.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.17 {"installer":{"name":"uv","version":"0.11.17","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
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f1d3c228ec75dac87fd808a847842723466a2a8fb0bdf0742cfd29a64ea0dca3
|
|
| MD5 |
07f9f04d6fd012abe266cd9c90076d75
|
|
| BLAKE2b-256 |
80e90d1a2672b0977e03fe2c4bbec3994c5a4af6e50385fc7abbddbfaa2695e2
|
File details
Details for the file soothe_sdk-1.0.8-py3-none-any.whl.
File metadata
- Download URL: soothe_sdk-1.0.8-py3-none-any.whl
- Upload date:
- Size: 131.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.17 {"installer":{"name":"uv","version":"0.11.17","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
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
915b9d91864c38046378bfb1523bb72b61f15ba2d4feb9d049d7de91e740b45d
|
|
| MD5 |
8534b681819452bf4b95814967e0def0
|
|
| BLAKE2b-256 |
97fc06b73801b021629b9479e271186a545abde82f32cab385caf7be758a6515
|
