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

toolplane/common/constants.py

@@ -0,0 +1,47 @@
+"""Constants used across Toolplane client implementations."""
+
+# Server-side ceiling for wait_timeout_seconds on the synchronous execution
+# entrypoints (the same ceiling as timeout_seconds). The server rejects
+# values above it with OUT_OF_RANGE / TIMEOUT_ABOVE_MAX.
+WAIT_TIMEOUT_MAX_SECONDS = 3600
+
+# gRPC message-size ladder, sized from the server's chunk limits: replay
+# window reads (8 MiB) and chunk batch writes (16 MiB) plus envelope
+# headroom. The gRPC defaults (4 MiB receive) reject a full window read at
+# the client before it reaches application code.
+GRPC_MAX_RECEIVE_MESSAGE_LENGTH = 9 * 1024 * 1024
+GRPC_MAX_SEND_MESSAGE_LENGTH = 17 * 1024 * 1024
+
+# Default configuration values
+DEFAULT_HEARTBEAT_INTERVAL = 60
+DEFAULT_MAX_WORKERS = 10
+DEFAULT_POLL_INTERVAL = 0.5
+DEFAULT_REQUEST_TIMEOUT = 60
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BUFFER_SIZE = 4 * 1024 * 1024  # 4MB
+DEFAULT_RETRY_BACKOFF_MS = 250
+
+# Cache settings
+CACHE_TTL_SECONDS = 0.5
+
+# Protocol-specific defaults
+GRPC_DEFAULT_PORT = 9001
+HTTP_DEFAULT_PORT = 8080
+
+# Session settings
+MAX_SESSION_NAME_LENGTH = 100
+MAX_TOOL_NAME_LENGTH = 50
+MAX_DESCRIPTION_LENGTH = 500
+
+# Tool execution settings
+MAX_TOOL_EXECUTION_TIME = 300  # 5 minutes
+STREAM_CHUNK_SIZE = 1024
+BACKPRESSURE_THRESHOLD = 0.8  # 80% of buffer size
+
+# Error messages
+ERROR_CONNECTION_FAILED = "Failed to connect to server"
+ERROR_TOOL_NOT_FOUND = "Tool not found"
+ERROR_SESSION_NOT_FOUND = "Session not found"
+ERROR_INVALID_PARAMETERS = "Invalid parameters"
+ERROR_TIMEOUT = "Operation timed out"
+ERROR_STREAM_INTERRUPTED = "Stream was interrupted"

toolplane/common/utils.py

@@ -0,0 +1,310 @@
+"""Utility functions shared across Toolplane client implementations."""
+
+import functools
+import json
+import re
+import time
+import uuid
+from threading import RLock
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+from .constants import (
+    CACHE_TTL_SECONDS,
+    MAX_DESCRIPTION_LENGTH,
+    MAX_SESSION_NAME_LENGTH,
+    MAX_TOOL_NAME_LENGTH,
+)
+
+T = TypeVar("T")
+
+
+def generate_session_id() -> str:
+    """Generate a unique session ID."""
+    return str(uuid.uuid4())
+
+
+def validate_tool_name(name: str) -> bool:
+    """Validate tool name format."""
+    if not name or len(name) > MAX_TOOL_NAME_LENGTH:
+        return False
+
+    # Tool names should be alphanumeric with underscores/hyphens
+    return re.match(r"^[a-zA-Z0-9_-]+$", name) is not None
+
+
+def validate_session_name(name: str) -> bool:
+    """Validate session name format."""
+    if not name or len(name) > MAX_SESSION_NAME_LENGTH:
+        return False
+
+    # Session names allow more characters
+    return re.match(r"^[a-zA-Z0-9_\-\s\.]+$", name) is not None
+
+
+def validate_description(description: str) -> bool:
+    """Validate description length."""
+    return len(description) <= MAX_DESCRIPTION_LENGTH
+
+
+def parse_json_safe(json_str: str, default: Any = None) -> Any:
+    """Safely parse JSON string."""
+    try:
+        return json.loads(json_str)
+    except (json.JSONDecodeError, TypeError):
+        return default
+
+
+def proto_enum_name(value: Any, enum_type: Any) -> str:
+    """Return the symbolic name for a v1 enum value.
+
+    The gRPC transport delivers proto3 enums as plain ints while the HTTP
+    transport delivers the symbolic name; normalize both to the name so
+    callers can map it through normalize_status_name.
+    """
+    if isinstance(value, str):
+        return value
+    try:
+        return enum_type.Name(value)
+    except (ValueError, AttributeError, TypeError):
+        return ""
+
+
+def timestamp_to_iso(value: Any) -> str:
+    """Render a v1 Timestamp message as an RFC3339 string.
+
+    Tolerates strings (HTTP transport), None, and unset (epoch-zero)
+    timestamps so callers always get a plain str.
+    """
+    if value is None:
+        return ""
+    to_json = getattr(value, "ToJsonString", None)
+    if callable(to_json):
+        try:
+            if not getattr(value, "seconds", 1) and not getattr(value, "nanos", 1):
+                return ""
+            return to_json()
+        except Exception:
+            return ""
+    return value if isinstance(value, str) else str(value)
+
+
+def format_error_message(error: Exception, context: str = "") -> str:
+    """Format error message with context."""
+    if context:
+        return f"{context}: {str(error)}"
+    return str(error)
+
+
+def with_retry(
+    max_retries: int = 3, backoff_ms: int = 250, exceptions: tuple = (Exception,)
+) -> Callable:
+    """Decorator for retrying operations."""
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> T:
+            last_exception = None
+
+            for attempt in range(max_retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except exceptions as e:
+                    last_exception = e
+                    if attempt < max_retries:
+                        # Exponential backoff
+                        sleep_time = (backoff_ms * (2**attempt)) / 1000
+                        time.sleep(sleep_time)
+                    else:
+                        break
+
+            # If all retries failed, raise the last exception
+            raise last_exception
+
+        return wrapper
+
+    return decorator
+
+
+class TTLCache:
+    """Thread-safe cache with TTL (Time To Live)."""
+
+    def __init__(self, ttl_seconds: int = CACHE_TTL_SECONDS):
+        self.ttl_seconds = ttl_seconds
+        self.cache: Dict[str, tuple] = {}  # key -> (timestamp, value)
+        self.lock = RLock()
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache if not expired."""
+        with self.lock:
+            if key in self.cache:
+                timestamp, value = self.cache[key]
+                if time.time() - timestamp < self.ttl_seconds:
+                    return value
+                else:
+                    # Remove expired entry
+                    del self.cache[key]
+            return None
+
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache with current timestamp."""
+        with self.lock:
+            self.cache[key] = (time.time(), value)
+
+    def clear(self) -> None:
+        """Clear all cache entries."""
+        with self.lock:
+            self.cache.clear()
+
+    def cleanup_expired(self) -> None:
+        """Remove expired entries from cache."""
+        now = time.time()
+        with self.lock:
+            expired_keys = [
+                key
+                for key, (timestamp, _) in self.cache.items()
+                if now - timestamp >= self.ttl_seconds
+            ]
+            for key in expired_keys:
+                del self.cache[key]
+
+
+def cache_with_ttl(ttl_seconds: int = CACHE_TTL_SECONDS) -> Callable:
+    """Decorator for caching function results with TTL."""
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        cache = TTLCache(ttl_seconds)
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> T:
+            # Create cache key from function name and arguments
+            key = f"{func.__name__}:{hash((args, tuple(sorted(kwargs.items()))))}"
+
+            # Try to get from cache first
+            cached_result = cache.get(key)
+            if cached_result is not None:
+                return cached_result
+
+            # If not in cache, execute function and cache result
+            result = func(*args, **kwargs)
+            cache.set(key, result)
+            return result
+
+        # Add cache management methods
+        wrapper.cache_clear = cache.clear
+        wrapper.cache_cleanup = cache.cleanup_expired
+
+        return wrapper
+
+    return decorator
+
+
+def normalize_url(url: str, default_protocol: str = "http") -> str:
+    """Normalize URL by adding protocol if missing."""
+    if not url.startswith(("http://", "https://")):
+        url = f"{default_protocol}://{url}"
+    return url.rstrip("/")
+
+
+def extract_host_port(url: str) -> tuple[str, int]:
+    """Extract host and port from URL."""
+    # Remove protocol if present
+    if "://" in url:
+        url = url.split("://")[1]
+
+    # Remove path if present
+    if "/" in url:
+        url = url.split("/")[0]
+
+    # Split host and port
+    if ":" in url:
+        host, port_str = url.rsplit(":", 1)
+        try:
+            port = int(port_str)
+        except ValueError:
+            port = 80 if "http" in url else 443
+    else:
+        host = url
+        port = 80 if "http" in url else 443
+
+    return host, port
+
+
+def merge_dicts(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge two dictionaries, with override taking precedence."""
+    result = base.copy()
+    result.update(override)
+    return result
+
+
+def sanitize_input(value: str, max_length: int = 1000) -> str:
+    """Sanitize input string by limiting length and removing control characters."""
+    if not isinstance(value, str):
+        value = str(value)
+
+    # Remove control characters except newlines and tabs
+    sanitized = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]", "", value)
+
+    # Limit length
+    if len(sanitized) > max_length:
+        sanitized = sanitized[:max_length]
+
+    return sanitized
+
+
+def is_valid_json(json_str: str) -> bool:
+    """Check if string is valid JSON."""
+    try:
+        json.loads(json_str)
+        return True
+    except (json.JSONDecodeError, TypeError):
+        return False
+
+
+def deep_merge(dict1: Dict[str, Any], dict2: Dict[str, Any]) -> Dict[str, Any]:
+    """Deep merge two dictionaries."""
+    result = dict1.copy()
+
+    for key, value in dict2.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = deep_merge(result[key], value)
+        else:
+            result[key] = value
+
+    return result
+
+
+def timeout_wrapper(timeout_seconds: int) -> Callable:
+    """Decorator to add timeout to function execution."""
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> T:
+            import threading
+
+            result = [None]
+            exception = [None]
+
+            def target():
+                try:
+                    result[0] = func(*args, **kwargs)
+                except Exception as e:
+                    exception[0] = e
+
+            thread = threading.Thread(target=target)
+            thread.daemon = True
+            thread.start()
+            thread.join(timeout_seconds)
+
+            if thread.is_alive():
+                raise TimeoutError(
+                    f"Function {func.__name__} timed out after {timeout_seconds} seconds"
+                )
+
+            if exception[0]:
+                raise exception[0]
+
+            return result[0]
+
+        return wrapper
+
+    return decorator

toolplane/core/__init__.py

@@ -0,0 +1,67 @@
+"""Core modules for Toolplane client."""
+
+from .config import ClientConfig
+from .connection import ConnectionManager
+from .errors import (
+    ConnectionError,
+    MachineError,
+    RequestError,
+    SessionError,
+    TaskError,
+    ToolError,
+    ToolplaneAlreadyExistsError,
+    ToolplaneAPIError,
+    ToolplaneCancelledError,
+    ToolplaneConnectionError,
+    ToolplaneError,
+    ToolplaneFailedPreconditionError,
+    ToolplaneInternalError,
+    ToolplaneInvalidArgumentError,
+    ToolplaneNotFoundError,
+    ToolplanePermissionDeniedError,
+    ToolplaneResourceExhaustedError,
+    ToolplaneTimeoutError,
+    ToolplaneUnauthenticatedError,
+    ToolplaneUnavailableError,
+    api_error_from_http_response,
+    api_error_from_rpc_error,
+)
+from .machine import MachineManager
+from .request import RequestManager
+from .session import SessionManager
+from .session_context import SessionContext
+from .task import TaskManager
+from .tool import ToolManager
+
+__all__ = [
+    "ConnectionManager",
+    "MachineManager",
+    "ToolManager",
+    "RequestManager",
+    "TaskManager",
+    "SessionManager",
+    "SessionContext",
+    "ToolplaneError",
+    "ConnectionError",
+    "ToolplaneConnectionError",
+    "ToolError",
+    "SessionError",
+    "MachineError",
+    "RequestError",
+    "TaskError",
+    "ClientConfig",
+    "ToolplaneAPIError",
+    "ToolplaneNotFoundError",
+    "ToolplaneInvalidArgumentError",
+    "ToolplaneFailedPreconditionError",
+    "ToolplaneResourceExhaustedError",
+    "ToolplaneUnauthenticatedError",
+    "ToolplanePermissionDeniedError",
+    "ToolplaneAlreadyExistsError",
+    "ToolplaneTimeoutError",
+    "ToolplaneUnavailableError",
+    "ToolplaneCancelledError",
+    "ToolplaneInternalError",
+    "api_error_from_rpc_error",
+    "api_error_from_http_response",
+]

toolplane/core/config.py

@@ -0,0 +1,107 @@
+"""Configuration management for Toolplane gRPC client."""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from ..common.base_config import BaseConfig
+from ..common.constants import GRPC_DEFAULT_PORT
+
+
+@dataclass
+class ClientConfig(BaseConfig):
+    """Configuration for Toolplane gRPC client."""
+
+    server_host: str = "localhost"
+    server_port: int = GRPC_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
+    tls_server_name: Optional[str] = None
+    # Retry configuration parameters
+    max_retries: int = 3
+    retry_base_delay: float = 1.0
+    retry_max_delay: float = 60.0
+    retry_backoff_factor: float = 2.0
+
+    def normalize(self):
+        """Normalize gRPC-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 retry values are reasonable
+        if self.max_retries < 0:
+            self.max_retries = 3
+        if self.retry_base_delay <= 0:
+            self.retry_base_delay = 1.0
+        if self.retry_max_delay <= 0:
+            self.retry_max_delay = 60.0
+        if self.retry_backoff_factor <= 1.0:
+            self.retry_backoff_factor = 2.0
+
+    def get_auth_info(self) -> Dict[str, Any]:
+        """Get gRPC authentication information."""
+        return {
+            "metadata": self.get_metadata(),
+            "use_tls": self.use_tls,
+            "tls_cert_path": self.tls_cert_path,
+            "tls_key_path": self.tls_key_path,
+            "tls_ca_cert_path": self.tls_ca_cert_path,
+            "tls_server_name": self.tls_server_name,
+        }
+
+    def get_metadata(self) -> List[tuple]:
+        """Get gRPC metadata headers."""
+        metadata = []
+        if self.api_key:
+            metadata.append(("authorization", f"Bearer {self.api_key}"))
+            metadata.append(("api_key", self.api_key))
+        return metadata
+
+    def get_server_address(self) -> str:
+        """Get formatted server address."""
+        return f"{self.server_host}:{self.server_port}"
+
+    def copy(self) -> "ClientConfig":
+        """Create a copy of the configuration."""
+        return ClientConfig(**self.to_dict())
+
+    def merge(self, other: "ClientConfig") -> "ClientConfig":
+        """Merge this configuration with another."""
+        merged_dict = self.to_dict()
+        merged_dict.update(other.to_dict())
+        return ClientConfig(**merged_dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary."""
+        result = super().to_dict()
+        result.update(
+            {
+                "server_host": self.server_host,
+                "server_port": self.server_port,
+                "use_tls": self.use_tls,
+                "tls_cert_path": self.tls_cert_path,
+                "tls_key_path": self.tls_key_path,
+                "tls_ca_cert_path": self.tls_ca_cert_path,
+                "tls_server_name": self.tls_server_name,
+                "max_retries": self.max_retries,
+                "retry_base_delay": self.retry_base_delay,
+                "retry_max_delay": self.retry_max_delay,
+                "retry_backoff_factor": self.retry_backoff_factor,
+            }
+        )
+        return result