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 20, 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 20, 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.2.tar.gz (93.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.2-py3-none-any.whl (126.4 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for soothe_sdk-1.0.2.tar.gz
Algorithm Hash digest
SHA256 c6f083f146115c4d67317f24b4d0bcc41bfb11ef711cd3454a3aedd9e9146393
MD5 8bf8fe516bbbae40818a08c3d5dc493c
BLAKE2b-256 9db0dab2a1869479ed72fa7900a05f164c609f4979994d9aa6689393be2a4261

See more details on using hashes here.

Provenance

The following attestation bundles were made for soothe_sdk-1.0.2.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.2-py3-none-any.whl.

File metadata

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

File hashes

Hashes for soothe_sdk-1.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 a69e37e1795ac28e1d7031c3f6c1892309b60f4e2923afddad43ab3ef5fc52be
MD5 22506de6bea4e6737ed6a4905b9d8269
BLAKE2b-256 a9859bda79b96e3f0b43dbd32f5ab5ce535d6d6eb48ed68a76a257263036cad2

See more details on using hashes here.

Provenance

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

This release

1.0.2 This release

2 files

1.0.1

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