steerable-plugin-sdk 0.6.29__py3-none-any.whl

steerable_plugin_sdk/__init__.py

@@ -0,0 +1,27 @@
+"""Pure-Python Steerable plugin authoring and plugin-host RPC SDK."""
+
+from .rpc import PLUGIN_HOST_PROTOCOL_VERSION, PluginHostRpcClient, RpcRouterProxy
+from .schema import derive_schema
+from .tools import (
+    STEERABLE_TOOLS_ENTRY_POINT_GROUP,
+    LocalPluginRouter,
+    RegisteredTool,
+    ToolDescriptor,
+    ToolExposure,
+    ToolRegistrationError,
+    tool,
+)
+
+__all__ = [
+    "PLUGIN_HOST_PROTOCOL_VERSION",
+    "STEERABLE_TOOLS_ENTRY_POINT_GROUP",
+    "LocalPluginRouter",
+    "PluginHostRpcClient",
+    "RegisteredTool",
+    "RpcRouterProxy",
+    "ToolDescriptor",
+    "ToolExposure",
+    "ToolRegistrationError",
+    "derive_schema",
+    "tool",
+]

steerable_plugin_sdk/rpc.py

@@ -0,0 +1,124 @@
+"""Plugin-host JSON-RPC client and sidecar router projection."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol
+
+from steerable_agent_protocol.generated import ToolResult
+
+from .tools import ToolDescriptor
+
+PLUGIN_HOST_PROTOCOL_VERSION = "0.1.0"
+
+
+class RpcTransport(Protocol):
+    """Request transport supplied by the plugin-host process owner."""
+
+    async def request(self, method: str, params: dict[str, Any]) -> Any:
+        """Issue one JSON-RPC request and return its result."""
+
+
+class RemoteRegistrationRouter(Protocol):
+    """Runtime router surface needed to project remote plugin tools."""
+
+    def register_remote(
+        self,
+        name: str,
+        invoker: Callable[[str, dict[str, Any]], Awaitable[Any]],
+        **kwargs: Any,
+    ) -> Any:
+        """Register one remotely invoked tool."""
+
+    def unregister(self, name: str) -> None:
+        """Remove one projected tool."""
+
+
+class PluginHostRpcClient:
+    """Typed client for the frozen plugin-host RPC methods."""
+
+    def __init__(self, transport: RpcTransport) -> None:
+        self._transport = transport
+
+    async def ping(self) -> dict[str, Any]:
+        """Negotiate the plugin-host protocol version."""
+        return await self._transport.request(
+            "plugin.host.ping",
+            {"protocolVersion": PLUGIN_HOST_PROTOCOL_VERSION},
+        )
+
+    async def describe_tools(self) -> list[ToolDescriptor]:
+        """Read every tool currently enabled in the plugin host."""
+        result = await self._transport.request("plugin.tools.describe", {})
+        return [
+            ToolDescriptor.from_wire(value)
+            for value in result.get("tools", [])
+        ]
+
+    async def invoke(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        context: dict[str, Any] | None = None,
+    ) -> ToolResult:
+        """Invoke one plugin tool."""
+        result = await self._transport.request(
+            "plugin.tool.invoke",
+            {"name": name, "arguments": arguments, "context": context or {}},
+        )
+        return ToolResult(**result)
+
+    async def list_plugins(self) -> dict[str, Any]:
+        """Return plugin lifecycle records."""
+        return await self._transport.request("plugin.list", {})
+
+    async def enable(self, name: str) -> dict[str, Any]:
+        """Enable one plugin."""
+        return await self._lifecycle("plugin.enable", name)
+
+    async def disable(self, name: str) -> dict[str, Any]:
+        """Disable one plugin."""
+        return await self._lifecycle("plugin.disable", name)
+
+    async def reload(self, name: str) -> dict[str, Any]:
+        """Reload one plugin."""
+        return await self._lifecycle("plugin.reload", name)
+
+    async def _lifecycle(self, method: str, name: str) -> dict[str, Any]:
+        return await self._transport.request(method, {"name": name})
+
+
+class RpcRouterProxy:
+    """Project plugin-host descriptors onto a runtime remote-tool router."""
+
+    def __init__(
+        self,
+        client: PluginHostRpcClient,
+        router: RemoteRegistrationRouter,
+    ) -> None:
+        self._client = client
+        self._router = router
+        self._names: list[str] = []
+
+    async def sync_tools(self) -> list[str]:
+        """Replace projected registrations with the host's current catalog."""
+        for name in self._names:
+            self._router.unregister(name)
+        self._names = []
+        for descriptor in await self._client.describe_tools():
+            self._router.register_remote(
+                descriptor.name,
+                self._client.invoke,
+                mode=descriptor.mode,
+                description=descriptor.description,
+                schema=descriptor.schema,
+                require_consent=descriptor.require_consent,
+                concurrency_safe=descriptor.concurrency_safe,
+                exposure=descriptor.exposure,
+                metadata={
+                    "plugin": descriptor.plugin,
+                    "pluginHost": True,
+                },
+            )
+            self._names.append(descriptor.name)
+        return list(self._names)

steerable_plugin_sdk/schema.py

@@ -0,0 +1,86 @@
+"""Conservative JSON Schema derivation for plugin tool handlers."""
+
+from __future__ import annotations
+
+import inspect
+import types
+import typing
+from collections.abc import Callable
+from typing import Any, get_args, get_origin
+
+_SCALAR_TYPES: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+}
+
+
+def _annotation_to_schema(annotation: Any) -> dict[str, Any]:
+    if annotation is inspect.Parameter.empty or annotation is Any:
+        return {}
+    origin = get_origin(annotation)
+    if origin is typing.Union or origin is types.UnionType:
+        members = list(get_args(annotation))
+        nullable = type(None) in members
+        non_null = [member for member in members if member is not type(None)]
+        if len(non_null) == 1:
+            inner = _annotation_to_schema(non_null[0])
+            inner_type = inner.get("type")
+            if nullable and isinstance(inner_type, str):
+                return {**inner, "type": [inner_type, "null"]}
+            return inner if inner else ({"type": "null"} if nullable else {})
+        types_seen = [
+            _SCALAR_TYPES[member]
+            for member in non_null
+            if member in _SCALAR_TYPES
+        ]
+        if nullable:
+            types_seen.append("null")
+        return {"type": types_seen} if types_seen else {}
+    if origin is list:
+        args = get_args(annotation)
+        items = _annotation_to_schema(args[0]) if args else {}
+        return {"type": "array", **({"items": items} if items else {})}
+    if origin is dict:
+        return {"type": "object"}
+    if origin is typing.Literal:
+        values = list(get_args(annotation))
+        schema: dict[str, Any] = {"enum": values}
+        if values and all(isinstance(value, type(values[0])) for value in values):
+            literal_type = _SCALAR_TYPES.get(type(values[0]))
+            if literal_type:
+                schema["type"] = literal_type
+        return schema
+    if annotation in _SCALAR_TYPES:
+        return {"type": _SCALAR_TYPES[annotation]}
+    if annotation is list:
+        return {"type": "array"}
+    if annotation is dict:
+        return {"type": "object"}
+    return {}
+
+
+def derive_schema(handler: Callable[..., Any]) -> dict[str, Any]:
+    """Build an object schema from the model-supplied handler parameters."""
+    try:
+        hints = typing.get_type_hints(handler)
+    except (NameError, TypeError, AttributeError, SyntaxError, ValueError):
+        hints = {}
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+    for parameter in inspect.signature(handler).parameters.values():
+        if parameter.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ) or parameter.name == "context":
+            continue
+        properties[parameter.name] = _annotation_to_schema(
+            hints.get(parameter.name, parameter.annotation)
+        )
+        if parameter.default is inspect.Parameter.empty:
+            required.append(parameter.name)
+    schema: dict[str, Any] = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return schema

steerable_plugin_sdk/tools.py

@@ -0,0 +1,218 @@
+"""Plugin tool declaration and local plugin-host dispatch."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+from steerable_agent_harness.policy import ToolMode, decide_tool_mode
+from steerable_agent_protocol.generated import ToolResult
+
+from .schema import derive_schema
+
+ToolHandler = Callable[..., Any] | Callable[..., Awaitable[Any]]
+ToolExposure = Literal["direct", "deferred", "hidden"]
+STEERABLE_TOOLS_ENTRY_POINT_GROUP = "steerable.tools"
+
+
+class ToolRegistrationError(RuntimeError):
+    """A plugin attempted an invalid or duplicate tool registration."""
+
+
+class RegistrationRouter(Protocol):
+    """Router methods consumed by the SDK's decorator."""
+
+    def register(self, handler: ToolHandler, **kwargs: Any) -> Any:
+        """Register one handler and return the host's registration record."""
+
+
+@dataclass(slots=True)
+class ToolDescriptor:
+    """Wire-safe metadata advertised by a plugin host."""
+
+    name: str
+    description: str
+    schema: dict[str, Any]
+    mode: ToolMode
+    exposure: ToolExposure
+    require_consent: bool
+    concurrency_safe: bool
+    plugin: str | None = None
+
+    def to_wire(self) -> dict[str, Any]:
+        """Return the camelCase plugin-host representation."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "schema": self.schema,
+            "mode": self.mode,
+            "exposure": self.exposure,
+            "requireConsent": self.require_consent,
+            "concurrencySafe": self.concurrency_safe,
+            "plugin": self.plugin,
+        }
+
+    @classmethod
+    def from_wire(cls, value: dict[str, Any]) -> ToolDescriptor:
+        """Decode one plugin-host descriptor."""
+        return cls(
+            name=str(value["name"]),
+            description=str(value.get("description") or ""),
+            schema=dict(value.get("schema") or {}),
+            mode=value.get("mode") or decide_tool_mode(str(value["name"])),
+            exposure=value.get("exposure") or "direct",
+            require_consent=bool(value.get("requireConsent", False)),
+            concurrency_safe=bool(value.get("concurrencySafe", False)),
+            plugin=str(value["plugin"]) if value.get("plugin") else None,
+        )
+
+
+@dataclass(slots=True)
+class RegisteredTool:
+    """One plugin-host registration and its local handler."""
+
+    descriptor: ToolDescriptor
+    handler: ToolHandler = field(repr=False)
+
+
+class LocalPluginRouter:
+    """Pure-Python registry used inside the future plugin-host process."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, RegisteredTool] = {}
+
+    def register(
+        self,
+        handler: ToolHandler,
+        *,
+        name: str | None = None,
+        mode: ToolMode | None = None,
+        description: str | None = None,
+        schema: dict[str, Any] | None = None,
+        require_consent: bool | None = None,
+        concurrency_safe: bool | None = None,
+        exposure: ToolExposure = "direct",
+        plugin: str | None = None,
+        **_ignored: Any,
+    ) -> RegisteredTool:
+        """Register one plugin handler."""
+        resolved_name = name or getattr(handler, "__name__", None)
+        if not resolved_name:
+            raise ToolRegistrationError("tool handler must have a name")
+        if resolved_name in self._tools:
+            raise ToolRegistrationError(f"tool already registered: {resolved_name}")
+        resolved_mode = mode or decide_tool_mode(resolved_name)
+        descriptor = ToolDescriptor(
+            name=resolved_name,
+            description=description or (inspect.getdoc(handler) or "").strip(),
+            schema=schema if schema is not None else derive_schema(handler),
+            mode=resolved_mode,
+            exposure=exposure,
+            require_consent=(
+                require_consent
+                if require_consent is not None
+                else resolved_mode == "destructive"
+            ),
+            concurrency_safe=(
+                concurrency_safe
+                if concurrency_safe is not None
+                else resolved_mode == "read"
+            ),
+            plugin=plugin,
+        )
+        registered = RegisteredTool(descriptor=descriptor, handler=handler)
+        self._tools[resolved_name] = registered
+        return registered
+
+    def unregister(self, name: str) -> None:
+        """Remove a handler if present."""
+        self._tools.pop(name, None)
+
+    def descriptors(self) -> list[ToolDescriptor]:
+        """Return registrations in insertion order."""
+        return [registered.descriptor for registered in self._tools.values()]
+
+    async def dispatch(
+        self,
+        name: str,
+        arguments: dict[str, Any],
+        context: dict[str, Any] | None = None,
+    ) -> ToolResult:
+        """Invoke one local plugin handler and normalize its result."""
+        registered = self._tools.get(name)
+        if registered is None:
+            return ToolResult(
+                success=False,
+                error=f"unknown plugin tool: {name}",
+                terminal=False,
+                needsFollowup=True,
+            )
+        handler = registered.handler
+        signature = inspect.signature(handler)
+        accepts_kwargs = any(
+            parameter.kind is inspect.Parameter.VAR_KEYWORD
+            for parameter in signature.parameters.values()
+        )
+        kwargs = {
+            parameter.name: (
+                (context or {})
+                if parameter.name == "context"
+                else arguments[parameter.name]
+            )
+            for parameter in signature.parameters.values()
+            if parameter.kind
+            not in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD)
+            and (parameter.name == "context" or parameter.name in arguments)
+        }
+        if accepts_kwargs:
+            for key, value in arguments.items():
+                kwargs.setdefault(key, value)
+        try:
+            result = handler(**kwargs)
+            if inspect.isawaitable(result):
+                result = await result
+        except Exception as exc:
+            return ToolResult(
+                success=False,
+                error=str(exc),
+                terminal=False,
+                needsFollowup=True,
+            )
+        if isinstance(result, ToolResult):
+            return result
+        if isinstance(result, dict) and "success" in result:
+            return ToolResult(**result)
+        return ToolResult(success=True, data={"value": result})
+
+
+def tool(
+    *,
+    name: str | None = None,
+    mode: ToolMode | None = None,
+    description: str | None = None,
+    schema: dict[str, Any] | None = None,
+    require_consent: bool | None = None,
+    concurrency_safe: bool | None = None,
+    exposure: ToolExposure = "direct",
+    router: RegistrationRouter | None = None,
+) -> Callable[[ToolHandler], ToolHandler]:
+    """Decorate and optionally register a plugin handler."""
+
+    def decorate(handler: ToolHandler) -> ToolHandler:
+        metadata = {
+            "name": name,
+            "mode": mode,
+            "description": description,
+            "schema": schema,
+            "require_consent": require_consent,
+            "concurrency_safe": concurrency_safe,
+            "exposure": exposure,
+        }
+        handler.__steerable_tool_meta__ = metadata
+        if router is not None:
+            router.register(handler, **metadata)
+        return handler
+
+    return decorate

steerable_plugin_sdk-0.6.29.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: steerable-plugin-sdk
+Version: 0.6.29
+Summary: Pure-Python authoring and RPC SDK for Steerable tool plugins
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: steerable-agent-harness<1.0.0,>=0.1.0
+Requires-Dist: steerable-agent-protocol<1.0.0,>=0.1.0
+
+# Steerable Plugin SDK
+
+Pure-Python plugin authoring surface for Steerable tools. This package does
+not depend on `steerable-agent-runtime` or its native CoreLoop wheel.
+
+```python
+from steerable_plugin_sdk import tool
+
+
+def register(router):
+    @tool(router=router, description="Greet by name")
+    async def greet(name: str) -> str:
+        return f"hello {name}"
+```
+
+Packaged plugins publish `register` through the `steerable.tools` entry-point
+group. `LocalPluginRouter` is the plugin-host registry; `PluginHostRpcClient`
+and `RpcRouterProxy` bridge its descriptors and invocations to a sidecar
+router.

steerable_plugin_sdk-0.6.29.dist-info/RECORD

@@ -0,0 +1,8 @@
+steerable_plugin_sdk/__init__.py,sha256=lZiY0ffvcAaWXtiFx7yMsXfzuvNaqHr4OwYNcVs4CO0,660
+steerable_plugin_sdk/rpc.py,sha256=-sRMoC6THWezROfa-hFucxxzK7ZzX5XziqKNFfrySdI,4159
+steerable_plugin_sdk/schema.py,sha256=Kki1-M6Lt0z6iQ5iRG7eyBHSDoL505zsOyAhRXjbqYo,3175
+steerable_plugin_sdk/tools.py,sha256=6qkzBvqY_oNax0ACV10eqk7bRwoFYjy6tw6FRICGY3s,7560
+steerable_plugin_sdk-0.6.29.dist-info/METADATA,sha256=zTdxjFsCfJ-Y76jzi0apkhEwnwGhln94NoIEz1_sGUo,916
+steerable_plugin_sdk-0.6.29.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+steerable_plugin_sdk-0.6.29.dist-info/top_level.txt,sha256=MrP64sC9BWffVptG1NjXalwH_NHOEflXHGB7mjKedyw,21
+steerable_plugin_sdk-0.6.29.dist-info/RECORD,,

steerable_plugin_sdk-0.6.29.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

steerable_plugin_sdk-0.6.29.dist-info/top_level.txt

@@ -0,0 +1 @@
+steerable_plugin_sdk