Soothe SDK

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

Version: 1.0.0 (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

  1. Create a Python package with your plugin class
  2. Add the entry point in pyproject.toml:
[project.entry-points."soothe.plugins"]
my_plugin = "my_package:MyPlugin"
  1. 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

Project links

Data verified by PyPI on Jul 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.12)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Xiaming.Chen from gravatar.com Xiaming.Chen

GitHub Statistics

Data verified by PyPI on Jul 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python <3.15, >=3.11

Provides Extra

dev

Tags

agents ai llm plugins protocols sdk soothe wire

Classifiers

Report project as malware

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

Uploaded Source

Built Distribution

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

soothe_sdk-1.0.1-py3-none-any.whl (98.7 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: soothe_sdk-1.0.1.tar.gz
  • Upload date:
  • Size: 75.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for soothe_sdk-1.0.1.tar.gz
Algorithm Hash digest
SHA256 bdb46796d8a8b53b30ca198504593875a9904941578e7916a8967a627937ab0d
MD5 3269fd225e955c5b3d70e87d5f0168eb
BLAKE2b-256 e718f19258367ccba39fc8dbca2202316beccced220dd51d73f9c7a192aa1f7c

See more details on using hashes here.

Provenance

The following attestation bundles were made for soothe_sdk-1.0.1.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.

File details

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

File metadata

  • Download URL: soothe_sdk-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 98.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for soothe_sdk-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 bd1b49b75881ee5f66f30f06e79c7f6477c92e811c146ef504595ef830f5e05f
MD5 b6bb5c439467bb0759b8aa3682484987
BLAKE2b-256 5cb4be0fcdad860095924842db76b18ba2d296c61eed6c7508d3db1b7a1a67b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for soothe_sdk-1.0.1-py3-none-any.whl:

Publisher: release.yml on mirasoth/soothe

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

Release history Release notifications | RSS feed

1.0.12

2 files

1.0.11

2 files

1.0.10

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

This release

1.0.1 This release

2 files

1.0.0

2 files

0.8.1

2 files

0.8.0

2 files

0.7.18

2 files

0.7.17

2 files

0.7.16

2 files

0.7.15

2 files

0.7.14

2 files

0.7.13

2 files

0.7.12

2 files

0.7.11

2 files

0.7.10

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.17

2 files

0.6.16

2 files

0.6.15

2 files

0.6.14

2 files

0.6.13

2 files

0.6.12

2 files

0.6.11

2 files

0.6.10

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.32

2 files

0.5.31

2 files

0.5.30

2 files

0.5.29

2 files

0.5.28

2 files

0.5.27

2 files

0.5.26

2 files

0.5.25

2 files

0.5.24

2 files

0.5.23

2 files

0.5.22

2 files

0.5.20

2 files

0.5.19

2 files

0.5.18

2 files

0.5.17

2 files

0.5.16

2 files

0.5.15

2 files

0.5.12

2 files

0.5.11

2 files

0.5.10

2 files

0.5.9

2 files

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.4

2 files

0.3.3

2 files

0.3.1

2 files

0.2.0

2 files

0.1.3

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page