steerable-plugin-sdk 0.6.29__tar.gz

steerable_plugin_sdk-0.6.29/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,19 @@
+# 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/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "steerable-plugin-sdk"
+version = "0.6.29"
+description = "Pure-Python authoring and RPC SDK for Steerable tool plugins"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "steerable-agent-harness>=0.1.0,<1.0.0",
+  "steerable-agent-protocol>=0.1.0,<1.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.uv.sources]
+steerable-agent-harness = { workspace = true }
+steerable-agent-protocol = { workspace = true }

steerable_plugin_sdk-0.6.29/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steerable_plugin_sdk-0.6.29/src/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-0.6.29/src/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-0.6.29/src/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-0.6.29/src/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/src/steerable_plugin_sdk.egg-info/PKG-INFO

@@ -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/src/steerable_plugin_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/steerable_plugin_sdk/__init__.py
+src/steerable_plugin_sdk/rpc.py
+src/steerable_plugin_sdk/schema.py
+src/steerable_plugin_sdk/tools.py
+src/steerable_plugin_sdk.egg-info/PKG-INFO
+src/steerable_plugin_sdk.egg-info/SOURCES.txt
+src/steerable_plugin_sdk.egg-info/dependency_links.txt
+src/steerable_plugin_sdk.egg-info/requires.txt
+src/steerable_plugin_sdk.egg-info/top_level.txt
+tests/test_plugin_sdk.py

steerable_plugin_sdk-0.6.29/src/steerable_plugin_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

steerable_plugin_sdk-0.6.29/src/steerable_plugin_sdk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+steerable-agent-harness<1.0.0,>=0.1.0
+steerable-agent-protocol<1.0.0,>=0.1.0

steerable_plugin_sdk-0.6.29/src/steerable_plugin_sdk.egg-info/top_level.txt

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

steerable_plugin_sdk-0.6.29/tests/test_plugin_sdk.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from typing import Literal
+
+import pytest
+from steerable_plugin_sdk import (
+    LocalPluginRouter,
+    PluginHostRpcClient,
+    RpcRouterProxy,
+    ToolDescriptor,
+    derive_schema,
+    tool,
+)
+
+
+def test_schema_derives_without_importing_runtime() -> None:
+    def search(query: str, limit: int = 8, mode: Literal["fast", "deep"] = "fast"):
+        pass
+
+    assert derive_schema(search) == {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string"},
+            "limit": {"type": "integer"},
+            "mode": {"enum": ["fast", "deep"], "type": "string"},
+        },
+        "required": ["query"],
+    }
+    check = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            (
+                "import sys; import steerable_plugin_sdk; "
+                "assert 'steerable_agent_runtime' not in sys.modules"
+            ),
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    assert check.returncode == 0, check.stderr
+
+
+@pytest.mark.asyncio
+async def test_author_decorator_and_local_dispatch() -> None:
+    router = LocalPluginRouter()
+
+    @tool(router=router, description="Greet by name")
+    async def greet(name: str, context: dict) -> str:
+        return f"{context['prefix']} {name}"
+
+    descriptors = router.descriptors()
+    assert [descriptor.name for descriptor in descriptors] == ["greet"]
+    assert descriptors[0].schema["required"] == ["name"]
+    result = await router.dispatch("greet", {"name": "Ada"}, {"prefix": "hello"})
+    assert result.success is True
+    assert result.data == {"value": "hello Ada"}
+
+
+class _Transport:
+    def __init__(self) -> None:
+        self.requests: list[tuple[str, dict]] = []
+
+    async def request(self, method: str, params: dict):
+        self.requests.append((method, params))
+        if method == "plugin.tools.describe":
+            return {
+                "tools": [
+                    ToolDescriptor(
+                        name="remote_greet",
+                        description="greet",
+                        schema={
+                            "type": "object",
+                            "properties": {"name": {"type": "string"}},
+                            "required": ["name"],
+                        },
+                        mode="read",
+                        exposure="direct",
+                        require_consent=False,
+                        concurrency_safe=True,
+                        plugin="example",
+                    ).to_wire()
+                ]
+            }
+        if method == "plugin.tool.invoke":
+            return {
+                "success": True,
+                "data": {"value": f"hello {params['arguments']['name']}"},
+            }
+        raise AssertionError(method)
+
+
+class _RuntimeRouter:
+    def __init__(self) -> None:
+        self.tools: dict[str, tuple] = {}
+
+    def register_remote(self, name, invoker, **kwargs):
+        self.tools[name] = (invoker, kwargs)
+
+    def unregister(self, name):
+        self.tools.pop(name, None)
+
+
+@pytest.mark.asyncio
+async def test_rpc_proxy_projects_and_invokes_remote_tools() -> None:
+    transport = _Transport()
+    client = PluginHostRpcClient(transport)
+    runtime = _RuntimeRouter()
+    proxy = RpcRouterProxy(client, runtime)
+
+    assert await proxy.sync_tools() == ["remote_greet"]
+    invoker, metadata = runtime.tools["remote_greet"]
+    assert metadata["metadata"] == {
+        "plugin": "example",
+        "pluginHost": True,
+    }
+    result = await invoker("remote_greet", {"name": "Ada"})
+    assert result.success is True
+    assert result.data == {"value": "hello Ada"}