toolplane-python-client 0.1.0__py3-none-any.whl

toolplane/core/tool.py

@@ -0,0 +1,329 @@
+"""Tool management for Toolplane gRPC client."""
+
+import json
+from typing import Any, Dict, List
+
+import grpc
+
+from toolplane.proto.service_pb2 import (
+    DeleteToolRequest,
+    ExecuteToolRequest,
+    GetToolByIdRequest,
+    GetToolByNameRequest,
+    ListToolsRequest,
+    RegisterToolRequest,
+    RequestStatus,
+)
+
+from ..common.base_tool_manager import BaseToolManager
+from ..common.utils import parse_json_safe, timestamp_to_iso
+from .connection import ConnectionManager
+from .errors import ToolError, api_error_from_rpc_error
+
+# Wire enum -> normalized status name; UNSPECIFIED maps to None so an
+# in-flight long-poll return is distinguishable from a terminal one.
+_REQUEST_STATUS_NAMES = {
+    RequestStatus.REQUEST_STATUS_DONE: "done",
+    RequestStatus.REQUEST_STATUS_FAILED: "failed",
+    RequestStatus.REQUEST_STATUS_CANCELLED: "cancelled",
+}
+
+
+class ToolManager(BaseToolManager):
+    """Manages tool registration and execution for gRPC client."""
+
+    def __init__(self, connection_manager: ConnectionManager):
+        """Initialize gRPC tool manager."""
+        super().__init__(connection_manager)
+
+    def _normalize_tool(self, tool: Any) -> Dict[str, Any]:
+        try:
+            schema = parse_json_safe(tool.schema)
+        except Exception:
+            schema = {}
+
+        if not isinstance(schema, dict):
+            schema = {}
+
+        return {
+            "id": tool.id,
+            "name": tool.name,
+            "description": tool.description,
+            "schema": schema,
+            "config": dict(tool.config),
+            "created_at": timestamp_to_iso(tool.created_at),
+            "last_ping_at": timestamp_to_iso(tool.last_ping_at),
+            "session_id": tool.session_id,
+            "machine_id": tool.machine_id,
+            "tags": list(tool.tags),
+        }
+
+    def _register_tool_with_server(
+        self, session_id: str, machine_id: str, name: str, schema: Dict
+    ):
+        """Register tool with server."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            request = RegisterToolRequest(
+                session_id=session_id,
+                machine_id=machine_id,
+                name=name,
+                description=schema.get("description", ""),
+                schema=json.dumps(schema.get("schema", {})),
+                tags=schema.get("tags", []),
+            )
+
+            self.connection_manager.tool_stub.RegisterTool(
+                request, metadata=self.connection_manager.get_metadata()
+            )
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context=f"Failed to register tool {name} with server"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to register tool {name} with server: {e}")
+
+    def _unregister_tool_from_server(self, session_id: str, name: str):
+        """Unregister tool from server."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            # Get tool ID first
+            tool_request = GetToolByNameRequest(session_id=session_id, tool_name=name)
+
+            tool_response = self.connection_manager.tool_stub.GetToolByName(
+                tool_request, metadata=self.connection_manager.get_metadata()
+            )
+
+            # Delete the tool. machine_id makes this a properly-attributed
+            # provide-scoped call (per-machine credential in metadata).
+            delete_request = DeleteToolRequest(
+                session_id=session_id,
+                tool_id=tool_response.tool.id,
+                machine_id=tool_response.tool.machine_id,
+            )
+
+            self.connection_manager.tool_stub.DeleteTool(
+                delete_request, metadata=self.connection_manager.get_metadata()
+            )
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context=f"Failed to unregister tool {name} from server"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to unregister tool {name} from server: {e}")
+
+    def _get_available_tools_from_server(self, session_id: str) -> Dict[str, Any]:
+        """Get available tools from server."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            request = ListToolsRequest(session_id=session_id)
+            response = self.connection_manager.tool_stub.ListTools(
+                request, metadata=self.connection_manager.get_metadata()
+            )
+
+            return {"tools": [self._normalize_tool(tool) for tool in response.tools]}
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context="Failed to get available tools"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to get available tools: {e}")
+
+    def list_tools(self, session_id: str) -> List[Dict[str, Any]]:
+        """List tools for a session."""
+        return self.get_available_tools(session_id).get("tools", [])
+
+    def get_tool_by_id(self, session_id: str, tool_id: str) -> Dict[str, Any]:
+        """Get a tool by ID."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            request = GetToolByIdRequest(session_id=session_id, tool_id=tool_id)
+            response = self.connection_manager.tool_stub.GetToolById(
+                request, metadata=self.connection_manager.get_metadata()
+            )
+            return self._normalize_tool(response.tool)
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context=f"Failed to get tool {tool_id}"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to get tool {tool_id}: {e}")
+
+    def get_tool_by_name(self, session_id: str, tool_name: str) -> Dict[str, Any]:
+        """Get a tool by name."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            request = GetToolByNameRequest(session_id=session_id, tool_name=tool_name)
+            response = self.connection_manager.tool_stub.GetToolByName(
+                request, metadata=self.connection_manager.get_metadata()
+            )
+            return self._normalize_tool(response.tool)
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context=f"Failed to get tool {tool_name}"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to get tool {tool_name}: {e}")
+
+    def delete_tool(self, session_id: str, tool_id: str) -> bool:
+        """Delete a tool by ID."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            tool_name = None
+            try:
+                tool = self.get_tool_by_id(session_id, tool_id)
+                tool_name = tool.get("name")
+            except Exception:
+                tool_name = None
+
+            request = DeleteToolRequest(
+                session_id=session_id,
+                tool_id=tool_id,
+                machine_id=str(tool.get("machine_id", "") or ""),
+            )
+            response = self.connection_manager.tool_stub.DeleteTool(
+                request, metadata=self.connection_manager.get_metadata()
+            )
+
+            if response.success:
+                self.get_available_tools.cache_clear()
+                with self._lock:
+                    if tool_name and session_id in self.tools:
+                        self.tools[session_id].pop(tool_name, None)
+                        self.tool_schemas[session_id].pop(tool_name, None)
+                        self.streaming_tools[session_id].discard(tool_name)
+
+            return response.success
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context=f"Failed to delete tool {tool_id}"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to delete tool {tool_id}: {e}")
+
+    def _execute_tool_on_server(
+        self,
+        session_id: str,
+        tool_name: str,
+        params: Dict,
+        idempotency_key: str = "",
+        timeout_seconds: int = 0,
+        wait_timeout_seconds: int = 0,
+    ):
+        """Execute tool on server.
+
+        Returns ``(request_id, terminal_status, result)`` where
+        ``terminal_status`` is the normalized status name when the
+        server-side long-poll (a positive ``wait_timeout_seconds``) observed
+        a terminal state (``result`` carries the parsed result value for a
+        successful run), and both are ``None`` when the request is still in
+        flight.
+        """
+        try:
+            self.connection_manager.ensure_connected()
+
+            request = ExecuteToolRequest(
+                session_id=session_id,
+                tool_name=tool_name,
+                input=json.dumps(params),
+                idempotency_key=idempotency_key,
+                timeout_seconds=timeout_seconds,
+                wait_timeout_seconds=wait_timeout_seconds,
+            )
+
+            response = self.connection_manager.tool_stub.InvokeTool(
+                request, metadata=self.connection_manager.get_metadata()
+            )
+
+            # Classify the terminal status BEFORE the generic error check:
+            # server-side FAILED/CANCELLED long-poll responses carry an
+            # error, and callers need the typed tuple (with the request id)
+            # rather than a generic ToolError.
+            status_name = _REQUEST_STATUS_NAMES.get(response.status)
+            if wait_timeout_seconds > 0 and status_name in (
+                "done",
+                "failed",
+                "cancelled",
+            ):
+                result_value = None
+                if status_name == "done" and response.result:
+                    try:
+                        result_value = json.loads(response.result)
+                    except (TypeError, ValueError):
+                        result_value = response.result
+                return response.request_id, status_name, result_value
+
+            if response.error:
+                raise ToolError(f"Tool execution failed: {response.error}")
+            return response.request_id, None, None
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context=f"Failed to execute tool {tool_name}"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to execute tool {tool_name}: {e}")
+
+    def _stream_tool_on_server(
+        self,
+        session_id: str,
+        tool_name: str,
+        params: Dict,
+        idempotency_key: str = "",
+        timeout_seconds: int = 0,
+    ):
+        """Stream tool execution on server."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            request = ExecuteToolRequest(
+                session_id=session_id,
+                tool_name=tool_name,
+                input=json.dumps(params),
+                idempotency_key=idempotency_key,
+                timeout_seconds=timeout_seconds,
+            )
+
+            # Use streaming endpoint
+            for chunk in self.connection_manager.tool_stub.StreamExecuteTool(
+                request, metadata=self.connection_manager.get_metadata()
+            ):
+                yield chunk
+
+        except grpc.RpcError as rpc_error:
+            self._handle_rpc_error(rpc_error)
+            raise api_error_from_rpc_error(
+                rpc_error, context=f"Failed to stream tool {tool_name}"
+            ) from rpc_error
+        except Exception as e:
+            raise ToolError(f"Failed to stream tool {tool_name}: {e}")
+
+    def _handle_rpc_error(self, rpc_error: grpc.RpcError):
+        """Reset the channel when the connection itself is broken.
+
+        Only UNAVAILABLE indicates a channel-level failure. Status errors
+        like UNAUTHENTICATED (bad or revoked key) or FAILED_PRECONDITION
+        (state conflict) are deterministic per-call outcomes: recycling the
+        channel would churn reconnection and re-registration for no effect.
+        """
+        if rpc_error.code() == grpc.StatusCode.UNAVAILABLE:
+            self.connection_manager.mark_unhealthy()

toolplane/http_core/__init__.py

@@ -0,0 +1,37 @@
+"""HTTP-specific core modules for Toolplane client."""
+
+from ..core.errors import (
+    ConnectionError,
+    MachineError,
+    RequestError,
+    SessionError,
+    TaskError,
+    ToolError,
+    ToolplaneError,
+)
+from .http_config import HTTPClientConfig
+from .http_connection import HTTPConnectionManager
+from .http_machine import HTTPMachineManager
+from .http_request import HTTPRequestManager
+from .http_session import HTTPSessionManager
+from .http_session_context import HTTPSessionContext
+from .http_task import HTTPTaskManager
+from .http_tool import HTTPToolManager
+
+__all__ = [
+    "HTTPClientConfig",
+    "HTTPConnectionManager",
+    "HTTPMachineManager",
+    "HTTPToolManager",
+    "HTTPRequestManager",
+    "HTTPTaskManager",
+    "HTTPSessionManager",
+    "HTTPSessionContext",
+    "ToolplaneError",
+    "ConnectionError",
+    "ToolError",
+    "SessionError",
+    "MachineError",
+    "RequestError",
+    "TaskError",
+]

toolplane/http_core/http_config.py

@@ -0,0 +1,97 @@
+"""HTTP configuration management for Toolplane client."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from ..common.base_config import BaseConfig
+from ..common.constants import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_RETRY_BACKOFF_MS,
+    HTTP_DEFAULT_PORT,
+)
+
+
+@dataclass
+class HTTPClientConfig(BaseConfig):
+    """Configuration for HTTP Toolplane client."""
+
+    server_host: str = "localhost"
+    server_port: int = HTTP_DEFAULT_PORT
+    use_tls: bool = False
+    tls_cert_path: Optional[str] = None
+    tls_key_path: Optional[str] = None
+    tls_ca_cert_path: Optional[str] = None
+
+    def normalize(self):
+        """Normalize HTTP-specific configuration values."""
+        # Normalize server host
+        if self.server_host.startswith("http://"):
+            self.server_host = self.server_host[7:]
+        elif self.server_host.startswith("https://"):
+            self.server_host = self.server_host[8:]
+            self.use_tls = True
+
+        # Extract port from host if present
+        if ":" in self.server_host:
+            host_parts = self.server_host.split(":")
+            if len(host_parts) == 2:
+                try:
+                    self.server_port = int(host_parts[1])
+                    self.server_host = host_parts[0]
+                except ValueError:
+                    pass
+
+        # Ensure timeout and retry values are reasonable
+        if self.request_timeout <= 0:
+            self.request_timeout = DEFAULT_REQUEST_TIMEOUT
+        if self.max_retries < 0:
+            self.max_retries = DEFAULT_MAX_RETRIES
+        if self.retry_backoff_ms < 0:
+            self.retry_backoff_ms = DEFAULT_RETRY_BACKOFF_MS
+
+    def get_auth_info(self) -> Dict[str, Any]:
+        """Get HTTP authentication information."""
+        return {
+            "headers": self.get_headers(),
+            "server_url": self.server_url,
+        }
+
+    def get_headers(self) -> Dict[str, str]:
+        """Get HTTP headers for requests."""
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+            # Keep legacy header for backward compatibility
+            headers["Grpc-Metadata-api_key"] = self.api_key
+        return headers
+
+    def get_server_address(self) -> str:
+        """Get formatted server address."""
+        return f"{self.server_host}:{self.server_port}"
+
+    @property
+    def server_url(self) -> str:
+        """Get complete server URL with protocol."""
+        protocol = "https" if self.use_tls else "http"
+        return f"{protocol}://{self.server_host}:{self.server_port}"
+
+    def copy(self) -> "HTTPClientConfig":
+        """Create a copy of the configuration."""
+        return HTTPClientConfig(**self.to_dict())
+
+    def merge(self, other: "HTTPClientConfig") -> "HTTPClientConfig":
+        """Merge this configuration with another."""
+        merged_dict = self.to_dict()
+        merged_dict.update(other.to_dict())
+        return HTTPClientConfig(**merged_dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary."""
+        result = super().to_dict()
+        result.update(
+            {
+                "server_url": self.server_url,
+            }
+        )
+        return result