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

toolplane/http_core/http_tool.py

@@ -0,0 +1,400 @@
+"""HTTP tool management for Toolplane client."""
+
+import json
+import time
+from typing import Any, Callable, Dict, List, Optional
+
+from toolplane.utils.schema import generate_schema_from_function
+
+from ..common.base_tool_manager import BaseToolManager
+from ..common.utils import validate_tool_name
+from ..core.errors import ToolError, ToolplaneAPIError
+from .http_connection import HTTPConnectionManager
+
+# Gateway JSON enums arrive as their proto names (lowercased here); map the
+# terminal ones onto the normalized status names used by the waiters.
+_RESPONSE_STATUS_NAMES = {
+    "request_status_done": "done",
+    "request_status_failed": "failed",
+    "request_status_cancelled": "cancelled",
+    "done": "done",
+    "failed": "failed",
+    "failure": "failed",
+    "cancelled": "cancelled",
+}
+
+
+class HTTPToolManager(BaseToolManager):
+    """Manages tool registration and execution for HTTP client."""
+
+    def __init__(self, connection_manager: HTTPConnectionManager):
+        """Initialize HTTP tool manager."""
+        super().__init__(connection_manager)
+
+    def _normalize_tool(self, tool: Dict[str, Any]) -> Dict[str, Any]:
+        schema = tool.get("schema", {})
+        if isinstance(schema, str):
+            try:
+                schema = json.loads(schema)
+            except Exception:
+                schema = {}
+
+        if not isinstance(schema, dict):
+            schema = {}
+
+        return {
+            "id": tool.get("id", ""),
+            "name": tool.get("name", ""),
+            "description": tool.get("description", ""),
+            "schema": schema,
+            "config": tool.get("config", {}),
+            "created_at": tool.get("createdAt", tool.get("created_at", "")),
+            "last_ping_at": tool.get("lastPingAt", tool.get("last_ping_at", "")),
+            "session_id": tool.get("sessionId", tool.get("session_id", "")),
+            "tags": tool.get("tags", []),
+        }
+
+    def register_tool(
+        self,
+        session_id: str,
+        machine_id: str,
+        name: str,
+        func: Callable,
+        schema: Optional[Dict] = None,
+        description: Optional[str] = None,
+        stream: bool = False,
+        tags: Optional[List[str]] = None,
+    ):
+        """Register a tool for a session."""
+        if tags is None:
+            tags = []
+
+        # Validate tool name
+        if not validate_tool_name(name):
+            raise ToolError(f"Invalid tool name: {name}")
+
+        # Generate schema if not provided
+        if schema is None:
+            schema = generate_schema_from_function(func)
+
+        # Add description and tags to schema
+        if description:
+            schema["description"] = description
+        schema["tags"] = tags
+
+        # Store tool locally
+        if session_id not in self.tools:
+            self.tools[session_id] = {}
+            self.tool_schemas[session_id] = {}
+            self.streaming_tools[session_id] = set()
+
+        self.tools[session_id][name] = func
+        self.tool_schemas[session_id][name] = schema
+
+        if stream:
+            self.streaming_tools[session_id].add(name)
+
+        # Register with server
+        self._register_tool_with_server(session_id, machine_id, name, schema)
+
+    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()
+
+            payload = {
+                "sessionId": session_id,
+                "machineId": machine_id,
+                "name": name,
+                "description": schema.get("description", ""),
+                "schema": json.dumps(schema.get("schema", {})),
+                "tags": schema.get("tags", []),
+                "config": {},  # Default config
+            }
+
+            self.connection_manager.register_tool(payload)
+
+        except Exception as e:
+            raise ToolError(f"Failed to register tool {name} with server: {e}")
+
+    def unregister_tool(self, session_id: str, name: str):
+        """Unregister a tool from a session."""
+        try:
+            # Remove from local storage
+            if session_id in self.tools:
+                self.tools[session_id].pop(name, None)
+                self.tool_schemas[session_id].pop(name, None)
+                self.streaming_tools[session_id].discard(name)
+
+            # Remove from server
+            self._unregister_tool_from_server(session_id, name)
+
+        except Exception as e:
+            raise ToolError(f"Failed to unregister tool {name}: {e}")
+
+    def _unregister_tool_from_server(self, session_id: str, name: str):
+        """Unregister tool from server."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            # Get tool by name first
+            tool_response = self.connection_manager.get_tool_by_name(session_id, name)
+
+            if "tool" in tool_response:
+                tool_id = tool_response["tool"].get("id")
+                if tool_id:
+                    self.connection_manager.delete_tool(session_id, tool_id)
+
+        except Exception as e:
+            raise ToolError(f"Failed to unregister tool {name} from server: {e}")
+
+    def get_tool(self, session_id: str, name: str) -> Optional[Callable]:
+        """Get a tool function by name."""
+        return self.tools.get(session_id, {}).get(name)
+
+    def is_streaming_tool(self, session_id: str, name: str) -> bool:
+        """Check if a tool is a streaming tool."""
+        return name in self.streaming_tools.get(session_id, set())
+
+    def get_session_tools(self, session_id: str) -> Dict[str, Callable]:
+        """Get all tools for a session."""
+        return self.tools.get(session_id, {})
+
+    def _get_available_tools_from_server(self, session_id: str) -> Dict[str, Any]:
+        """Get available tools from server."""
+        # Check cache first
+        now = time.time()
+        cached = self._tool_cache.get(session_id)
+        if cached and now - cached[0] < 30:  # 30 second cache
+            return {"tools": cached[1]}
+
+        try:
+            self.connection_manager.ensure_connected()
+
+            response = self.connection_manager.list_tools(session_id)
+
+            # Handle case where response might be a string or dict
+            if isinstance(response, str):
+                try:
+                    response = json.loads(response)
+                except (TypeError, ValueError, json.JSONDecodeError):
+                    return {"tools": []}
+
+            if not isinstance(response, dict):
+                return {"tools": []}
+
+            tools = []
+            for tool in response.get("tools", []):
+                try:
+                    # Handle case where tool might be a string
+                    if isinstance(tool, str):
+                        try:
+                            tool = json.loads(tool)
+                        except (TypeError, ValueError, json.JSONDecodeError):
+                            continue
+
+                    if not isinstance(tool, dict):
+                        continue
+
+                    tools.append(self._normalize_tool(tool))
+                except Exception:
+                    continue
+
+            # Cache result
+            self._tool_cache[session_id] = (now, tools)
+            return {"tools": tools}
+
+        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()
+            response = self.connection_manager.get_tool_by_id(session_id, tool_id)
+            payload = response.get("tool", response)
+            if not isinstance(payload, dict):
+                raise ToolError(f"Unexpected tool lookup payload for {tool_id}")
+            return self._normalize_tool(payload)
+        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()
+            response = self.connection_manager.get_tool_by_name(session_id, tool_name)
+            payload = response.get("tool", response)
+            if not isinstance(payload, dict):
+                raise ToolError(f"Unexpected tool lookup payload for {tool_name}")
+            return self._normalize_tool(payload)
+        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
+
+            response = self.connection_manager.delete_tool(session_id, tool_id)
+            success = (
+                bool(response.get("success", False))
+                if isinstance(response, dict)
+                else bool(response)
+            )
+
+            if success:
+                self.get_available_tools.cache_clear()
+                self._tool_cache.pop(session_id, None)
+                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 success
+        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 a tool and return ``(request_id, terminal_status, result)``.
+
+        ``terminal_status``/``result`` are populated only when the
+        server-side long-poll observed a terminal state.
+        """
+        try:
+            self.connection_manager.ensure_connected()
+
+            response = self.connection_manager.execute_tool(
+                session_id,
+                tool_name,
+                json.dumps(params),
+                idempotency_key,
+                timeout_seconds=timeout_seconds,
+                wait_timeout_seconds=wait_timeout_seconds,
+            )
+
+            # 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 = _RESPONSE_STATUS_NAMES.get(
+                str(response.get("status", "")).lower()
+            )
+            if wait_timeout_seconds > 0 and status_name in (
+                "done",
+                "failed",
+                "cancelled",
+            ):
+                result_value = None
+                if status_name == "done" and response.get("result") is not None:
+                    raw = response["result"]
+                    if isinstance(raw, str):
+                        try:
+                            result_value = json.loads(raw)
+                        except ValueError:
+                            result_value = raw
+                    else:
+                        result_value = raw
+                return response.get("requestId"), status_name, result_value
+
+            if response.get("error"):
+                raise ToolError(f"Tool execution failed: {response.get('error')}")
+            return response.get("requestId"), None, None
+
+        except ToolplaneAPIError:
+            raise
+        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."""
+        try:
+            self.connection_manager.ensure_connected()
+
+            response = self.connection_manager.stream_execute_tool(
+                session_id, tool_name, json.dumps(params), idempotency_key
+            )
+
+            # Track buffer for backpressure
+            self.connection_manager.current_buffer_size = 0
+
+            # Parse newline-delimited JSON (NDJSON)
+            for line in response.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+
+                # Check buffer size and apply backpressure if needed
+                line_size = len(line.encode("utf-8"))
+                self.connection_manager.current_buffer_size += line_size
+
+                if (
+                    self.connection_manager.current_buffer_size
+                    > self.connection_manager.config.max_buffer_size
+                ):
+                    # Apply backpressure by pausing before processing
+                    time.sleep(0.05)
+
+                try:
+                    chunk = json.loads(line)
+                    yield chunk
+
+                    # Update buffer tracking as we process
+                    self.connection_manager.current_buffer_size -= line_size
+
+                    if chunk.get("isFinal"):
+                        break
+
+                except ValueError:
+                    continue
+
+        except Exception as e:
+            raise ToolError(f"Failed to stream tool {tool_name}: {e}")
+
+    def cleanup_session_tools(self, session_id: str):
+        """Cleanup all tools for a session."""
+        if session_id in self.tools:
+            for tool_name in list(self.tools[session_id].keys()):
+                try:
+                    self.unregister_tool(session_id, tool_name)
+                except Exception:
+                    # Ignore cleanup errors
+                    pass
+
+            # Clear local storage
+            self.tools.pop(session_id, None)
+            self.tool_schemas.pop(session_id, None)
+            self.streaming_tools.pop(session_id, None)
+
+    def cleanup_all(self):
+        """Cleanup all tools."""
+        for session_id in list(self.tools.keys()):
+            self.cleanup_session_tools(session_id)

toolplane/interfaces/__init__.py

@@ -0,0 +1,27 @@
+"""Interface definitions for Toolplane client components."""
+
+from .client_interface import ClientProtocol, IClientFactory, IToolplaneClient
+from .connection_interface import IConnectionManager, IConnectionStrategy
+from .event_interface import IEventEmitter, IEventHandler
+from .request_interface import IRequestManager, IRequestProcessor
+from .session_interface import ISessionContext, ISessionManager
+from .tool_interface import IToolExecutor, IToolManager
+
+__all__ = [
+    # Client interfaces
+    "IToolplaneClient",
+    "IClientFactory",
+    "ClientProtocol",
+    # Component interfaces
+    "IConnectionManager",
+    "IConnectionStrategy",
+    "ISessionManager",
+    "ISessionContext",
+    "IToolManager",
+    "IToolExecutor",
+    "IRequestManager",
+    "IRequestProcessor",
+    # Event interfaces
+    "IEventEmitter",
+    "IEventHandler",
+]

toolplane/interfaces/client_interface.py

@@ -0,0 +1,122 @@
+"""Client interface definitions for protocol-agnostic Toolplane clients."""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Protocol, runtime_checkable
+
+from .session_interface import ISessionContext
+
+
+class ClientProtocol(Enum):
+    """Supported client protocols."""
+
+    HTTP = "http"
+    GRPC = "grpc"
+    WEBSOCKET = "websocket"
+
+
+@runtime_checkable
+class IToolplaneClient(Protocol):
+    """Protocol interface for Toolplane clients."""
+
+    def connect(self) -> bool:
+        """Connect to Toolplane server."""
+        ...
+
+    def disconnect(self) -> None:
+        """Disconnect from Toolplane server."""
+        ...
+
+    def create_session(
+        self,
+        session_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        namespace: Optional[str] = None,
+        register_machine: bool = False,
+    ) -> ISessionContext:
+        """Create a new session."""
+        ...
+
+    def get_session(self, session_id: str) -> Optional[ISessionContext]:
+        """Get session context by ID."""
+        ...
+
+    def list_sessions(self) -> List[ISessionContext]:
+        """List all session contexts."""
+        ...
+
+    def start(self) -> None:
+        """Start the client."""
+        ...
+
+    def stop(self) -> None:
+        """Stop the client."""
+        ...
+
+
+class IClientFactory(ABC):
+    """Abstract factory for creating protocol-specific Toolplane clients."""
+
+    @abstractmethod
+    def create_client(
+        self, protocol: ClientProtocol, config: Dict[str, Any]
+    ) -> IToolplaneClient:
+        """Create a client for the specified protocol."""
+        pass
+
+    @abstractmethod
+    def get_supported_protocols(self) -> List[ClientProtocol]:
+        """Get list of supported protocols."""
+        pass
+
+    @abstractmethod
+    def validate_config(self, protocol: ClientProtocol, config: Dict[str, Any]) -> bool:
+        """Validate configuration for the specified protocol."""
+        pass
+
+
+class BaseClientFactory(IClientFactory):
+    """Base implementation of client factory with registry pattern."""
+
+    def __init__(self):
+        self._client_classes: Dict[ClientProtocol, type] = {}
+        self._config_validators: Dict[ClientProtocol, Callable] = {}
+
+    def register_client(
+        self,
+        protocol: ClientProtocol,
+        client_class: type,
+        config_validator: Optional[Callable] = None,
+    ) -> None:
+        """Register a client implementation for a protocol."""
+        self._client_classes[protocol] = client_class
+        if config_validator:
+            self._config_validators[protocol] = config_validator
+
+    def create_client(
+        self, protocol: ClientProtocol, config: Dict[str, Any]
+    ) -> IToolplaneClient:
+        """Create a client for the specified protocol."""
+        if protocol not in self._client_classes:
+            raise ValueError(f"Unsupported protocol: {protocol}")
+
+        if not self.validate_config(protocol, config):
+            raise ValueError(f"Invalid configuration for protocol: {protocol}")
+
+        client_class = self._client_classes[protocol]
+        return client_class(**config)
+
+    def get_supported_protocols(self) -> List[ClientProtocol]:
+        """Get list of supported protocols."""
+        return list(self._client_classes.keys())
+
+    def validate_config(self, protocol: ClientProtocol, config: Dict[str, Any]) -> bool:
+        """Validate configuration for the specified protocol."""
+        if protocol in self._config_validators:
+            try:
+                return self._config_validators[protocol](config)
+            except Exception:
+                return False
+        return True  # No validator means valid by default