squadron-sdk 0.1.1__py3-none-any.whl

squadron_sdk/__init__.py

@@ -0,0 +1,29 @@
+"""squadron-sdk — Python SDK for writing Squadron tool plugins.
+
+Wire-compatible with the Go ``github.com/mlund01/squadron-sdk`` package: a host
+built against either SDK can launch plugins built against either SDK, in either
+language.
+
+The high-level API is :class:`Squadron`. Decorate functions with ``@app.tool``;
+the JSON Schema is derived from type hints, and arguments are validated by
+pydantic. Drop down to :class:`ToolProvider` if you need fully dynamic tools.
+"""
+from __future__ import annotations
+
+from .app import Squadron, ToolGroup
+from .handshake import HANDSHAKE
+from .interface import ToolInfo, ToolProvider
+from .plugin import PLUGIN_KEY, ToolClient, ToolPlugin
+from .server import serve
+
+__all__ = [
+    "HANDSHAKE",
+    "PLUGIN_KEY",
+    "Squadron",
+    "ToolClient",
+    "ToolGroup",
+    "ToolInfo",
+    "ToolPlugin",
+    "ToolProvider",
+    "serve",
+]

squadron_sdk/_generated/plugin_grpc.py

@@ -0,0 +1,88 @@
+# Generated by the Protocol Buffers compiler. DO NOT EDIT!
+# source: plugin.proto
+# plugin: grpclib.plugin.main
+import abc
+import typing
+
+import grpclib.const
+import grpclib.client
+if typing.TYPE_CHECKING:
+    import grpclib.server
+
+from . import plugin_pb2
+
+
+class ToolPluginBase(abc.ABC):
+
+    @abc.abstractmethod
+    async def Configure(self, stream: 'grpclib.server.Stream[plugin_pb2.ConfigureRequest, plugin_pb2.ConfigureResponse]') -> None:
+        pass
+
+    @abc.abstractmethod
+    async def Call(self, stream: 'grpclib.server.Stream[plugin_pb2.CallRequest, plugin_pb2.CallResponse]') -> None:
+        pass
+
+    @abc.abstractmethod
+    async def GetToolInfo(self, stream: 'grpclib.server.Stream[plugin_pb2.GetToolInfoRequest, plugin_pb2.GetToolInfoResponse]') -> None:
+        pass
+
+    @abc.abstractmethod
+    async def ListTools(self, stream: 'grpclib.server.Stream[plugin_pb2.ListToolsRequest, plugin_pb2.ListToolsResponse]') -> None:
+        pass
+
+    def __mapping__(self) -> typing.Dict[str, grpclib.const.Handler]:
+        return {
+            '/plugin.ToolPlugin/Configure': grpclib.const.Handler(
+                self.Configure,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                plugin_pb2.ConfigureRequest,
+                plugin_pb2.ConfigureResponse,
+            ),
+            '/plugin.ToolPlugin/Call': grpclib.const.Handler(
+                self.Call,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                plugin_pb2.CallRequest,
+                plugin_pb2.CallResponse,
+            ),
+            '/plugin.ToolPlugin/GetToolInfo': grpclib.const.Handler(
+                self.GetToolInfo,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                plugin_pb2.GetToolInfoRequest,
+                plugin_pb2.GetToolInfoResponse,
+            ),
+            '/plugin.ToolPlugin/ListTools': grpclib.const.Handler(
+                self.ListTools,
+                grpclib.const.Cardinality.UNARY_UNARY,
+                plugin_pb2.ListToolsRequest,
+                plugin_pb2.ListToolsResponse,
+            ),
+        }
+
+
+class ToolPluginStub:
+
+    def __init__(self, channel: grpclib.client.Channel) -> None:
+        self.Configure = grpclib.client.UnaryUnaryMethod(
+            channel,
+            '/plugin.ToolPlugin/Configure',
+            plugin_pb2.ConfigureRequest,
+            plugin_pb2.ConfigureResponse,
+        )
+        self.Call = grpclib.client.UnaryUnaryMethod(
+            channel,
+            '/plugin.ToolPlugin/Call',
+            plugin_pb2.CallRequest,
+            plugin_pb2.CallResponse,
+        )
+        self.GetToolInfo = grpclib.client.UnaryUnaryMethod(
+            channel,
+            '/plugin.ToolPlugin/GetToolInfo',
+            plugin_pb2.GetToolInfoRequest,
+            plugin_pb2.GetToolInfoResponse,
+        )
+        self.ListTools = grpclib.client.UnaryUnaryMethod(
+            channel,
+            '/plugin.ToolPlugin/ListTools',
+            plugin_pb2.ListToolsRequest,
+            plugin_pb2.ListToolsResponse,
+        )

squadron_sdk/_generated/plugin_pb2.py

@@ -0,0 +1,59 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: plugin.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'plugin.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0cplugin.proto\x12\x06plugin\"}\n\x10\x43onfigureRequest\x12\x38\n\x08settings\x18\x01 \x03(\x0b\x32&.plugin.ConfigureRequest.SettingsEntry\x1a/\n\rSettingsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"3\n\x11\x43onfigureResponse\x12\x0f\n\x07success\x18\x01 \x01(\x08\x12\r\n\x05\x65rror\x18\x02 \x01(\t\"1\n\x0b\x43\x61llRequest\x12\x11\n\ttool_name\x18\x01 \x01(\t\x12\x0f\n\x07payload\x18\x02 \x01(\t\"\x1e\n\x0c\x43\x61llResponse\x12\x0e\n\x06result\x18\x01 \x01(\t\"\'\n\x12GetToolInfoRequest\x12\x11\n\ttool_name\x18\x01 \x01(\t\"5\n\x13GetToolInfoResponse\x12\x1e\n\x04tool\x18\x01 \x01(\x0b\x32\x10.plugin.ToolInfo\"\x12\n\x10ListToolsRequest\"4\n\x11ListToolsResponse\x12\x1f\n\x05tools\x18\x01 \x03(\x0b\x32\x10.plugin.ToolInfo\"^\n\x08ToolInfo\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x02 \x01(\t\x12\x13\n\x0bschema_json\x18\x03 \x01(\t\x12\x1a\n\x12output_schema_json\x18\x04 \x01(\t2\x8b\x02\n\nToolPlugin\x12@\n\tConfigure\x12\x18.plugin.ConfigureRequest\x1a\x19.plugin.ConfigureResponse\x12\x31\n\x04\x43\x61ll\x12\x13.plugin.CallRequest\x1a\x14.plugin.CallResponse\x12\x46\n\x0bGetToolInfo\x12\x1a.plugin.GetToolInfoRequest\x1a\x1b.plugin.GetToolInfoResponse\x12@\n\tListTools\x12\x18.plugin.ListToolsRequest\x1a\x19.plugin.ListToolsResponseB\x14Z\x12squad/plugin/protob\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'plugin_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'Z\022squad/plugin/proto'
+  _globals['_CONFIGUREREQUEST_SETTINGSENTRY']._loaded_options = None
+  _globals['_CONFIGUREREQUEST_SETTINGSENTRY']._serialized_options = b'8\001'
+  _globals['_CONFIGUREREQUEST']._serialized_start=24
+  _globals['_CONFIGUREREQUEST']._serialized_end=149
+  _globals['_CONFIGUREREQUEST_SETTINGSENTRY']._serialized_start=102
+  _globals['_CONFIGUREREQUEST_SETTINGSENTRY']._serialized_end=149
+  _globals['_CONFIGURERESPONSE']._serialized_start=151
+  _globals['_CONFIGURERESPONSE']._serialized_end=202
+  _globals['_CALLREQUEST']._serialized_start=204
+  _globals['_CALLREQUEST']._serialized_end=253
+  _globals['_CALLRESPONSE']._serialized_start=255
+  _globals['_CALLRESPONSE']._serialized_end=285
+  _globals['_GETTOOLINFOREQUEST']._serialized_start=287
+  _globals['_GETTOOLINFOREQUEST']._serialized_end=326
+  _globals['_GETTOOLINFORESPONSE']._serialized_start=328
+  _globals['_GETTOOLINFORESPONSE']._serialized_end=381
+  _globals['_LISTTOOLSREQUEST']._serialized_start=383
+  _globals['_LISTTOOLSREQUEST']._serialized_end=401
+  _globals['_LISTTOOLSRESPONSE']._serialized_start=403
+  _globals['_LISTTOOLSRESPONSE']._serialized_end=455
+  _globals['_TOOLINFO']._serialized_start=457
+  _globals['_TOOLINFO']._serialized_end=551
+  _globals['_TOOLPLUGIN']._serialized_start=554
+  _globals['_TOOLPLUGIN']._serialized_end=821
+# @@protoc_insertion_point(module_scope)

squadron_sdk/app.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import inspect
+import json
+import typing
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+from pydantic import TypeAdapter, create_model
+
+from .interface import ToolInfo, ToolProvider
+
+ConfigureHandler = Callable[[dict[str, str]], None | Awaitable[None]]
+ToolFunc = Callable[..., Any]
+
+_ANY_ADAPTER: TypeAdapter[Any] = TypeAdapter(Any)
+
+
+@dataclass
+class _Tool:
+    name: str
+    description: str
+    fn: ToolFunc
+    args_model: type
+    return_adapter: TypeAdapter[Any]
+    return_is_str: bool
+    info: ToolInfo
+
+    async def invoke(self, payload: str) -> str:
+        params = json.loads(payload) if payload else {}
+        validated = self.args_model.model_validate(params)
+        kwargs = {k: getattr(validated, k) for k in self.args_model.model_fields}
+        result = self.fn(**kwargs)
+        if inspect.isawaitable(result):
+            result = await result
+        if self.return_is_str and isinstance(result, str):
+            return result
+        return self.return_adapter.dump_json(result).decode()
+
+
+def _build_args_model(name: str, fn: ToolFunc) -> type:
+    sig = inspect.signature(fn)
+    try:
+        hints = typing.get_type_hints(fn, include_extras=True)
+    except Exception:
+        hints = {}
+    fields: dict[str, tuple[Any, Any]] = {}
+    for pname, param in sig.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            raise TypeError(
+                f"@tool {name!r}: *args/**kwargs are not supported in tool signatures"
+            )
+        annotation = hints.get(pname, str)
+        default = ... if param.default is inspect.Parameter.empty else param.default
+        fields[pname] = (annotation, default)
+    return create_model(f"{name}_args", **fields)
+
+
+def _strip_titles(schema: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(schema, dict):
+        return schema
+    out = {k: v for k, v in schema.items() if k != "title"}
+    if "properties" in out and isinstance(out["properties"], dict):
+        out["properties"] = {k: _strip_titles(v) for k, v in out["properties"].items()}
+    if "items" in out:
+        out["items"] = _strip_titles(out["items"])
+    if "$defs" in out and isinstance(out["$defs"], dict):
+        out["$defs"] = {k: _strip_titles(v) for k, v in out["$defs"].items()}
+    return out
+
+
+def _build_tool(
+    fn: ToolFunc,
+    name: str | None,
+    description: str | None,
+) -> _Tool:
+    tool_name = name or fn.__name__
+    doc = (inspect.getdoc(fn) or "").strip()
+    tool_desc = description if description is not None else doc.split("\n\n")[0]
+    args_model = _build_args_model(tool_name, fn)
+    schema = _strip_titles(args_model.model_json_schema())
+
+    return_type, output_schema = _resolve_return_type(fn)
+    return_adapter: TypeAdapter[Any] = TypeAdapter(return_type)
+    return_is_str = return_type is str
+
+    return _Tool(
+        name=tool_name,
+        description=tool_desc,
+        fn=fn,
+        args_model=args_model,
+        return_adapter=return_adapter,
+        return_is_str=return_is_str,
+        info=ToolInfo(
+            name=tool_name,
+            description=tool_desc,
+            schema=schema,
+            output_schema=output_schema,
+        ),
+    )
+
+
+def _resolve_return_type(fn: ToolFunc) -> tuple[Any, dict[str, Any] | None]:
+    try:
+        hints = typing.get_type_hints(fn, include_extras=True)
+    except Exception:
+        return Any, None
+    rt = hints.get("return", Any)
+    if rt is None or rt is type(None):
+        return type(None), None
+    if rt is Any or rt is inspect.Signature.empty:
+        return Any, None
+    try:
+        adapter = TypeAdapter(rt)
+        schema = _strip_titles(adapter.json_schema())
+        return rt, schema
+    except Exception:
+        return rt, None
+
+
+class _ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, _Tool] = {}
+
+    def tool(
+        self,
+        fn: ToolFunc | None = None,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ToolFunc:
+        def decorator(f: ToolFunc) -> ToolFunc:
+            built = _build_tool(f, name, description)
+            if built.name in self._tools:
+                raise ValueError(f"tool {built.name!r} is already registered")
+            self._tools[built.name] = built
+            return f
+
+        if fn is not None and callable(fn):
+            return decorator(fn)
+        return decorator  # type: ignore[return-value]
+
+
+class ToolGroup(_ToolRegistry):
+    def __init__(self) -> None:
+        super().__init__()
+        self.app: Squadron | None = None
+
+
+class Squadron(_ToolRegistry):
+    def __init__(self) -> None:
+        super().__init__()
+        self._configure_handler: ConfigureHandler | None = None
+
+    def configure(self, fn: ConfigureHandler) -> ConfigureHandler:
+        self._configure_handler = fn
+        return fn
+
+    def include(self, group: ToolGroup, *, prefix: str = "") -> None:
+        if group.app is not None and group.app is not self:
+            raise ValueError("ToolGroup has already been included in a different Squadron app")
+        group.app = self
+        for tool in group._tools.values():
+            full_name = f"{prefix}{tool.name}"
+            if full_name in self._tools:
+                raise ValueError(f"tool {full_name!r} is already registered")
+            if prefix:
+                self._tools[full_name] = _Tool(
+                    name=full_name,
+                    description=tool.description,
+                    fn=tool.fn,
+                    args_model=tool.args_model,
+                    return_adapter=tool.return_adapter,
+                    return_is_str=tool.return_is_str,
+                    info=ToolInfo(
+                        name=full_name,
+                        description=tool.description,
+                        schema=tool.info.schema,
+                        output_schema=tool.info.output_schema,
+                    ),
+                )
+            else:
+                self._tools[full_name] = tool
+
+    def as_provider(self) -> ToolProvider:
+        return _SquadronProvider(self)
+
+    def serve(self) -> None:
+        from .server import serve
+
+        serve(self.as_provider())
+
+
+class _SquadronProvider(ToolProvider):
+    def __init__(self, app: Squadron) -> None:
+        self._app = app
+
+    async def configure(self, settings: dict[str, str]) -> None:
+        handler = self._app._configure_handler
+        if handler is None:
+            return
+        result = handler(settings)
+        if inspect.isawaitable(result):
+            await result
+
+    async def call(self, tool_name: str, payload: str) -> str:
+        tool = self._app._tools.get(tool_name)
+        if tool is None:
+            raise ValueError(f"unknown tool: {tool_name!r}")
+        return await tool.invoke(payload)
+
+    async def get_tool_info(self, tool_name: str) -> ToolInfo:
+        tool = self._app._tools.get(tool_name)
+        if tool is None:
+            raise ValueError(f"unknown tool: {tool_name!r}")
+        return tool.info
+
+    async def list_tools(self) -> list[ToolInfo]:
+        return [t.info for t in self._app._tools.values()]

squadron_sdk/handshake.py

@@ -0,0 +1,10 @@
+"""Handshake config — must match the Go squadron-sdk."""
+from __future__ import annotations
+
+from pyplugin import HandshakeConfig
+
+HANDSHAKE = HandshakeConfig(
+    protocol_version=1,
+    magic_cookie_key="SQUAD_PLUGIN",
+    magic_cookie_value="squadron-tool-plugin-v1",
+)

squadron_sdk/interface.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ToolInfo:
+    name: str
+    description: str = ""
+    schema: dict[str, Any] = field(
+        default_factory=lambda: {"type": "object", "properties": {}}
+    )
+    output_schema: dict[str, Any] | None = None
+
+
+class ToolProvider(abc.ABC):
+    @abc.abstractmethod
+    async def configure(self, settings: dict[str, str]) -> None: ...
+
+    @abc.abstractmethod
+    async def call(self, tool_name: str, payload: str) -> str: ...
+
+    @abc.abstractmethod
+    async def get_tool_info(self, tool_name: str) -> ToolInfo: ...
+
+    @abc.abstractmethod
+    async def list_tools(self) -> list[ToolInfo]: ...

squadron_sdk/plugin.py

@@ -0,0 +1,124 @@
+"""pyplugin glue: servicer, host-side stub, and the Plugin class."""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from grpclib.client import Channel
+from pyplugin import Plugin
+from pyplugin.broker import GRPCBroker
+
+from ._generated import plugin_grpc, plugin_pb2
+from .interface import ToolInfo, ToolProvider
+
+
+def _info_to_proto(info: ToolInfo) -> plugin_pb2.ToolInfo:
+    return plugin_pb2.ToolInfo(
+        name=info.name,
+        description=info.description,
+        schema_json=json.dumps(info.schema or {}),
+        output_schema_json=json.dumps(info.output_schema) if info.output_schema else "",
+    )
+
+
+def _info_from_proto(t: plugin_pb2.ToolInfo) -> ToolInfo:
+    schema = json.loads(t.schema_json) if t.schema_json else {}
+    output_schema = json.loads(t.output_schema_json) if t.output_schema_json else None
+    return ToolInfo(
+        name=t.name,
+        description=t.description,
+        schema=schema,
+        output_schema=output_schema,
+    )
+
+
+class _ToolPluginServicer(plugin_grpc.ToolPluginBase):
+    """Plugin-side servicer that delegates to a ``ToolProvider``."""
+
+    def __init__(self, impl: ToolProvider) -> None:
+        self._impl = impl
+
+    async def Configure(self, stream) -> None:
+        request = await stream.recv_message()
+        try:
+            await self._impl.configure(dict(request.settings))
+        except Exception as exc:
+            await stream.send_message(
+                plugin_pb2.ConfigureResponse(success=False, error=str(exc))
+            )
+            return
+        await stream.send_message(plugin_pb2.ConfigureResponse(success=True))
+
+    async def Call(self, stream) -> None:
+        request = await stream.recv_message()
+        result = await self._impl.call(request.tool_name, request.payload)
+        await stream.send_message(plugin_pb2.CallResponse(result=result))
+
+    async def GetToolInfo(self, stream) -> None:
+        request = await stream.recv_message()
+        info = await self._impl.get_tool_info(request.tool_name)
+        await stream.send_message(plugin_pb2.GetToolInfoResponse(tool=_info_to_proto(info)))
+
+    async def ListTools(self, stream) -> None:
+        await stream.recv_message()
+        tools = await self._impl.list_tools()
+        await stream.send_message(
+            plugin_pb2.ListToolsResponse(tools=[_info_to_proto(t) for t in tools])
+        )
+
+
+class ToolClient:
+    """Host-side wrapper around the generated grpclib stub.
+
+    Returned by ``Client.dispense("tool")``; presents a Pythonic API on top of
+    the raw protobuf calls.
+    """
+
+    def __init__(self, stub: plugin_grpc.ToolPluginStub) -> None:
+        self._stub = stub
+
+    async def configure(self, settings: dict[str, str]) -> None:
+        resp = await self._stub.Configure(plugin_pb2.ConfigureRequest(settings=settings))
+        if not resp.success:
+            raise RuntimeError(f"configure failed: {resp.error}")
+
+    async def call(self, tool_name: str, payload: str) -> str:
+        resp = await self._stub.Call(
+            plugin_pb2.CallRequest(tool_name=tool_name, payload=payload)
+        )
+        return resp.result
+
+    async def get_tool_info(self, tool_name: str) -> ToolInfo:
+        resp = await self._stub.GetToolInfo(
+            plugin_pb2.GetToolInfoRequest(tool_name=tool_name)
+        )
+        return _info_from_proto(resp.tool)
+
+    async def list_tools(self) -> list[ToolInfo]:
+        resp = await self._stub.ListTools(plugin_pb2.ListToolsRequest())
+        return [_info_from_proto(t) for t in resp.tools]
+
+
+class ToolPlugin(Plugin):
+    """The pyplugin ``Plugin`` glue for squadron tool plugins.
+
+    On the plugin side, ``servicers()`` is called with the broker and an
+    implementation must have been provided to the constructor. On the host
+    side, ``stub()`` returns a :class:`ToolClient` wrapping the generated stub.
+    """
+
+    def __init__(self, impl: ToolProvider | None = None) -> None:
+        self._impl = impl
+
+    def servicers(self, broker: GRPCBroker) -> list:
+        if self._impl is None:
+            raise RuntimeError(
+                "ToolPlugin used as a server but no ToolProvider was supplied"
+            )
+        return [_ToolPluginServicer(self._impl)]
+
+    def stub(self, broker: GRPCBroker, channel: Channel) -> Any:
+        return ToolClient(plugin_grpc.ToolPluginStub(channel))
+
+
+PLUGIN_KEY = "tool"

squadron_sdk/proto/plugin.proto

@@ -0,0 +1,59 @@
+syntax = "proto3";
+
+package plugin;
+
+option go_package = "squad/plugin/proto";
+
+// ToolPlugin is the service that all tool plugins must implement
+service ToolPlugin {
+    // Configure passes plugin settings from HCL config
+    rpc Configure(ConfigureRequest) returns (ConfigureResponse);
+
+    // Call invokes a tool on the plugin with the given payload
+    rpc Call(CallRequest) returns (CallResponse);
+
+    // GetToolInfo returns metadata about a specific tool
+    rpc GetToolInfo(GetToolInfoRequest) returns (GetToolInfoResponse);
+
+    // ListTools returns info for all tools this plugin provides
+    rpc ListTools(ListToolsRequest) returns (ListToolsResponse);
+}
+
+message ConfigureRequest {
+    map<string, string> settings = 1;
+}
+
+message ConfigureResponse {
+    bool success = 1;
+    string error = 2;
+}
+
+message CallRequest {
+    string tool_name = 1;
+    string payload = 2;
+}
+
+message CallResponse {
+    string result = 1;
+}
+
+message GetToolInfoRequest {
+    string tool_name = 1;
+}
+
+message GetToolInfoResponse {
+    ToolInfo tool = 1;
+}
+
+message ListToolsRequest {}
+
+message ListToolsResponse {
+    repeated ToolInfo tools = 1;
+}
+
+message ToolInfo {
+    string name = 1;
+    string description = 2;
+    string schema_json = 3;
+    string output_schema_json = 4;
+}

squadron_sdk/server.py

@@ -0,0 +1,45 @@
+"""Plugin entry point — mirrors squadron-sdk/serve.go."""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+
+from pyplugin import ServeConfig, serve as _pyplugin_serve
+
+from .handshake import HANDSHAKE
+from .interface import ToolProvider
+from .plugin import PLUGIN_KEY, ToolPlugin
+
+
+def _monitor_parent() -> None:
+    """Exit if the parent process dies, mirroring monitor_unix.go.
+
+    On Unix, a process whose parent dies is reparented to PID 1 (init/launchd).
+    Detect that and exit so we don't become an orphan.
+    """
+    if os.name == "nt":
+        return
+    initial = os.getppid()
+    while True:
+        time.sleep(5)
+        current = os.getppid()
+        if current != initial or current == 1:
+            os._exit(0)
+
+
+def serve(impl: ToolProvider) -> None:
+    """Start the plugin server with ``impl`` as the tool provider.
+
+    This is the main entry point for plugin binaries — call it from
+    ``if __name__ == "__main__":``.
+    """
+    threading.Thread(target=_monitor_parent, daemon=True).start()
+    _pyplugin_serve(ServeConfig(
+        handshake_config=HANDSHAKE,
+        plugins={PLUGIN_KEY: ToolPlugin(impl)},
+    ))
+
+
+__all__ = ["serve"]

squadron_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: squadron-sdk
+Version: 0.1.1
+Summary: Python SDK for writing Squadron tool plugins (wire-compatible with the Go squadron-sdk)
+Author: Max Lund
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: grpclib[protobuf]>=0.4.7
+Requires-Dist: protobuf>=4.25
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-plugin>=0.1.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# squadron-sdk (Python)
+
+Python SDK for writing [Squadron](https://github.com/mlund01/squadron) tool
+plugins. Wire-compatible with the Go
+[`squadron-sdk`](https://github.com/mlund01/squadron-sdk): a host built against
+either SDK can launch plugins built against either SDK, in either language.
+
+Built on [pyplugin](https://github.com/mlund01/py-plugin), the byte-for-byte
+Python port of HashiCorp's go-plugin (including AutoMTLS with ECDSA P-521).
+
+## Quick start
+
+```python
+# plugin.py
+from typing import Literal
+from pydantic import Field
+from squadron_sdk import Squadron
+
+app = Squadron()
+
+@app.configure
+def setup(settings: dict[str, str]) -> None:
+    app.prefix = settings.get("prefix", "")
+
+@app.tool
+async def echo(
+    message: str = Field(..., description="Text to echo back."),
+    repeat: int = Field(1, ge=1, le=100),
+) -> dict:
+    """Echo a message back, prefixed with the configured prefix."""
+    return {"echo": (app.prefix + message) * repeat}
+
+@app.tool
+def reverse(s: str, mode: Literal["chars", "words"] = "chars") -> str:
+    """Reverse a string by characters or words."""
+    return " ".join(reversed(s.split())) if mode == "words" else s[::-1]
+
+if __name__ == "__main__":
+    app.serve()
+```
+
+That's the whole plugin. The host gets:
+
+- a `ToolPlugin.ListTools` response with `echo` and `reverse`,
+- a JSON Schema derived from your type hints (including `Field(...)` metadata,
+  `Literal` enums, defaults, validators, nested pydantic models, …),
+- input validation on every `Call`,
+- automatic JSON serialization of return values.
+
+Sync and async tool functions both work. Tool name defaults to the function
+name and the description defaults to the docstring; override either with
+`@app.tool(name="...", description="...")`.
+
+## Typed returns
+
+The return type annotation is reflected into a JSON Schema and shipped as
+the tool's `output_schema` — same machinery as the input. Plain `str`
+returns pass through unwrapped (the LLM sees `hello` rather than
+`"hello"`); everything else is JSON-marshaled via pydantic, so `BaseModel`,
+dataclasses, `list[T]`, `dict[K, V]`, `Literal`, etc. all work.
+
+```python
+class Item(BaseModel):
+    name: str
+    count: int
+
+@app.tool
+def make_item(name: str) -> Item:
+    return Item(name=name, count=3)
+# wire: {"name":"x","count":3}
+# output_schema: {"type":"object","properties":{"name":{"type":"string"},"count":{"type":"integer"}},"required":["name","count"]}
+
+@app.tool
+def upper(s: str) -> str:
+    return s.upper()
+# wire: HI
+# output_schema: {"type":"string"}
+```
+
+The output schema flows over the wire and is available to LLM SDKs that
+support per-tool output schemas — symmetric with the input schema.
+
+## What gets generated
+
+For the `echo` tool above, the schema sent to the host looks like:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "message": {"type": "string", "description": "Text to echo back."},
+    "repeat":  {"type": "integer", "default": 1, "maximum": 100, "minimum": 1}
+  },
+  "required": ["message"]
+}
+```
+
+Nested pydantic models, `Literal[...]`, `list[T]`, `dict[K, V]`, `Annotated`,
+optional fields with defaults — all the usual pydantic conveniences are
+available because we go through `pydantic.create_model` and ship the
+schema verbatim.
+
+## Calling from a Python host
+
+```python
+import asyncio, sys
+from pyplugin import Client, ClientConfig
+from squadron_sdk import HANDSHAKE, PLUGIN_KEY, ToolPlugin
+
+async def main():
+    async with Client(ClientConfig(
+        handshake_config=HANDSHAKE,
+        plugins={PLUGIN_KEY: ToolPlugin()},
+        cmd=[sys.executable, "plugin.py"],
+    )) as client:
+        tool = client.dispense(PLUGIN_KEY)
+        await tool.configure({"prefix": "hi: "})
+        for info in await tool.list_tools():
+            print(info.name, info.description)
+        print(await tool.call("echo", '{"message":"world"}'))
+
+asyncio.run(main())
+```
+
+A complete runnable example lives in [`examples/echo/`](examples/echo/).
+
+## Splitting tools across files
+
+Two patterns work — pick whichever fits.
+
+### Shared app instance
+
+A standalone Python app that owns its own tools: just import the same `app`
+everywhere and decorate as you go.
+
+```python
+# myplugin/app.py
+from squadron_sdk import Squadron
+app = Squadron()
+
+# myplugin/tools/database.py
+from myplugin.app import app
+
+@app.tool
+async def query(sql: str) -> dict: ...
+
+# myplugin/main.py
+from myplugin.app import app
+from myplugin.tools import database  # registration happens at import time
+
+if __name__ == "__main__":
+    app.serve()
+```
+
+### Explicit `ToolGroup`
+
+Better when tools are a reusable unit (a library, a swappable bundle, or
+just clearly-bounded functionality). Tools in a group can read app-level
+state via `group.app`, which is set when you `include` the group:
+
+```python
+# myplugin/tools/text.py
+from squadron_sdk import ToolGroup
+
+text_tools = ToolGroup()
+
+@text_tools.tool
+def shout(s: str) -> str:
+    return text_tools.app.prefix + s.upper()
+
+# myplugin/main.py
+from squadron_sdk import Squadron
+from myplugin.tools.text import text_tools
+
+app = Squadron()
+
+@app.configure
+def setup(settings):
+    app.prefix = settings.get("prefix", "")
+
+app.include(text_tools)              # text_tools.app is now `app`
+app.include(text_tools, prefix="t_") # or namespace: t_shout
+app.serve()
+```
+
+`ToolGroup` is just a tool registry — same `@tool` decorator, no
+`@configure` or `.serve()`. Tool collisions raise on registration or
+`include`. A group can only be included into one app.
+
+## Low-level API
+
+If you need fully dynamic tools (e.g. discovered at runtime from a remote
+schema), implement [`ToolProvider`](src/squadron_sdk/interface.py) directly
+and call `serve(provider)`. `Squadron` is a thin layer over `ToolProvider`
+that handles the registration plumbing.
+
+## Wire compatibility
+
+Same handshake (`SQUAD_PLUGIN` / `squadron-tool-plugin-v1`, protocol
+version 1) and protobuf service (`plugin.ToolPlugin`) as the Go SDK. A Go
+Squadron host can launch a Python plugin built with this package, and a
+Python host built with `pyplugin` can launch a Go plugin built with the Go
+SDK.
+
+The proto file lives at
+[`src/squadron_sdk/proto/plugin.proto`](src/squadron_sdk/proto/plugin.proto)
+and is identical to the Go SDK's. Regenerate the stubs with:
+
+```bash
+python scripts/gen_protos.py
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+```
+
+## License
+
+MIT.

squadron_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+squadron_sdk/__init__.py,sha256=cUzPYw3VQf4xZMAMVOm4kSTTx9C4hvKmj-IgPIeluVs,876
+squadron_sdk/app.py,sha256=O9_aQ1VOhGWQzmonwfBPBMYV2TmoIR78VX8ya1NKxfw,7215
+squadron_sdk/handshake.py,sha256=RQxBsKZzbw7CqrjhCo0f0Hifozy4Y9L-ypeLs3dBXsg,275
+squadron_sdk/interface.py,sha256=ikYtxLIFYRhkuLKwmpcH7NydeUNa0WT6kg59yFM5PAg,726
+squadron_sdk/plugin.py,sha256=CM2C1zTbmB-BzKNXXqypxg2ZzC1BomR8JSokTFhgkNk,4366
+squadron_sdk/server.py,sha256=F1SHseC66UBXu73xnN_D8r59G5Z5y-CCwdR7OpUtMaE,1204
+squadron_sdk/_generated/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+squadron_sdk/_generated/plugin_grpc.py,sha256=YEGcFxJoJaieNIj-gAj3UE3tptOF52iL_L4NznQqINY,3026
+squadron_sdk/_generated/plugin_pb2.py,sha256=el2LH2wRkqv2KWxiCMY3Mn706K6MkvGnUmvDOsgoFCs,3830
+squadron_sdk/proto/plugin.proto,sha256=mlpLv9RYa7r6RuUKhOT1RlQS28M0JPxSxPBzsr_XRt8,1274
+squadron_sdk-0.1.1.dist-info/METADATA,sha256=DTyxeKbDXM1tObiH6qlgpoJgI5L0ydDwn8wRV0B59tA,7044
+squadron_sdk-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+squadron_sdk-0.1.1.dist-info/licenses/LICENSE,sha256=fILwPEdelkIjeEzc0o8FY3rqqQNQW_bKBYoD0gX6zmY,1065
+squadron_sdk-0.1.1.dist-info/RECORD,,

squadron_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

squadron_sdk-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Lund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.