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

toolplane/__init__.py

@@ -0,0 +1,106 @@
+"""Modular Toolplane client package."""
+
+from .common import (
+    CACHE_TTL_SECONDS,
+    DEFAULT_BUFFER_SIZE,
+    DEFAULT_HEARTBEAT_INTERVAL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_WORKERS,
+    DEFAULT_POLL_INTERVAL,
+    DEFAULT_REQUEST_TIMEOUT,
+    GRPC_DEFAULT_PORT,
+    HTTP_DEFAULT_PORT,
+    BaseConfig,
+    BaseConnectionManager,
+    BaseSessionManager,
+    BaseToolManager,
+    TTLCache,
+    cache_with_ttl,
+    format_error_message,
+    generate_session_id,
+    normalize_url,
+    parse_json_safe,
+    validate_session_name,
+    validate_tool_name,
+    with_retry,
+)
+from .core import (
+    ClientConfig,
+    ConnectionError,
+    MachineError,
+    RequestError,
+    SessionContext,
+    SessionError,
+    TaskError,
+    ToolError,
+    ToolplaneAlreadyExistsError,
+    ToolplaneAPIError,
+    ToolplaneCancelledError,
+    ToolplaneConnectionError,
+    ToolplaneError,
+    ToolplaneFailedPreconditionError,
+    ToolplaneInternalError,
+    ToolplaneInvalidArgumentError,
+    ToolplaneNotFoundError,
+    ToolplanePermissionDeniedError,
+    ToolplaneResourceExhaustedError,
+    ToolplaneTimeoutError,
+    ToolplaneUnauthenticatedError,
+    ToolplaneUnavailableError,
+)
+from .http_core import HTTPClientConfig, HTTPSessionContext
+from .provider_runtime import ProviderRuntime
+from .toolplane_client import Toolplane
+from .toolplane_http_client import ToolplaneHTTP
+
+__all__ = [
+    "Toolplane",
+    "ProviderRuntime",
+    "SessionContext",
+    "ClientConfig",
+    "ToolplaneError",
+    "ConnectionError",
+    "ToolplaneConnectionError",
+    "ToolError",
+    "SessionError",
+    "MachineError",
+    "RequestError",
+    "TaskError",
+    "ToolplaneAPIError",
+    "ToolplaneNotFoundError",
+    "ToolplaneInvalidArgumentError",
+    "ToolplaneFailedPreconditionError",
+    "ToolplaneResourceExhaustedError",
+    "ToolplaneUnauthenticatedError",
+    "ToolplanePermissionDeniedError",
+    "ToolplaneAlreadyExistsError",
+    "ToolplaneTimeoutError",
+    "ToolplaneUnavailableError",
+    "ToolplaneCancelledError",
+    "ToolplaneInternalError",
+    "ToolplaneHTTP",
+    "HTTPSessionContext",
+    "HTTPClientConfig",
+    "BaseConfig",
+    "BaseToolManager",
+    "BaseSessionManager",
+    "BaseConnectionManager",
+    "generate_session_id",
+    "validate_tool_name",
+    "validate_session_name",
+    "parse_json_safe",
+    "format_error_message",
+    "with_retry",
+    "cache_with_ttl",
+    "TTLCache",
+    "normalize_url",
+    "DEFAULT_HEARTBEAT_INTERVAL",
+    "DEFAULT_MAX_WORKERS",
+    "DEFAULT_POLL_INTERVAL",
+    "DEFAULT_REQUEST_TIMEOUT",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_BUFFER_SIZE",
+    "CACHE_TTL_SECONDS",
+    "GRPC_DEFAULT_PORT",
+    "HTTP_DEFAULT_PORT",
+]

toolplane/common/__init__.py

@@ -0,0 +1,93 @@
+"""Common functionality shared between gRPC and HTTP Toolplane clients."""
+
+from .base_config import BaseConfig
+from .base_connection_manager import BaseConnectionManager
+from .base_session_manager import BaseSessionManager
+from .base_tool_manager import BaseToolManager
+from .constants import (
+    BACKPRESSURE_THRESHOLD,
+    CACHE_TTL_SECONDS,
+    DEFAULT_BUFFER_SIZE,
+    DEFAULT_HEARTBEAT_INTERVAL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_WORKERS,
+    DEFAULT_POLL_INTERVAL,
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_RETRY_BACKOFF_MS,
+    ERROR_CONNECTION_FAILED,
+    ERROR_INVALID_PARAMETERS,
+    ERROR_SESSION_NOT_FOUND,
+    ERROR_STREAM_INTERRUPTED,
+    ERROR_TIMEOUT,
+    ERROR_TOOL_NOT_FOUND,
+    GRPC_DEFAULT_PORT,
+    HTTP_DEFAULT_PORT,
+    MAX_DESCRIPTION_LENGTH,
+    MAX_SESSION_NAME_LENGTH,
+    MAX_TOOL_EXECUTION_TIME,
+    MAX_TOOL_NAME_LENGTH,
+    STREAM_CHUNK_SIZE,
+)
+from .utils import (
+    TTLCache,
+    cache_with_ttl,
+    deep_merge,
+    extract_host_port,
+    format_error_message,
+    generate_session_id,
+    is_valid_json,
+    merge_dicts,
+    normalize_url,
+    parse_json_safe,
+    sanitize_input,
+    timeout_wrapper,
+    validate_description,
+    validate_session_name,
+    validate_tool_name,
+    with_retry,
+)
+
+__all__ = [
+    "BaseConfig",
+    "BaseToolManager",
+    "BaseSessionManager",
+    "BaseConnectionManager",
+    "generate_session_id",
+    "validate_tool_name",
+    "validate_session_name",
+    "validate_description",
+    "parse_json_safe",
+    "format_error_message",
+    "with_retry",
+    "cache_with_ttl",
+    "TTLCache",
+    "normalize_url",
+    "extract_host_port",
+    "merge_dicts",
+    "sanitize_input",
+    "is_valid_json",
+    "deep_merge",
+    "timeout_wrapper",
+    "DEFAULT_HEARTBEAT_INTERVAL",
+    "DEFAULT_MAX_WORKERS",
+    "DEFAULT_POLL_INTERVAL",
+    "DEFAULT_REQUEST_TIMEOUT",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_BUFFER_SIZE",
+    "DEFAULT_RETRY_BACKOFF_MS",
+    "CACHE_TTL_SECONDS",
+    "GRPC_DEFAULT_PORT",
+    "HTTP_DEFAULT_PORT",
+    "MAX_SESSION_NAME_LENGTH",
+    "MAX_TOOL_NAME_LENGTH",
+    "MAX_DESCRIPTION_LENGTH",
+    "MAX_TOOL_EXECUTION_TIME",
+    "STREAM_CHUNK_SIZE",
+    "BACKPRESSURE_THRESHOLD",
+    "ERROR_CONNECTION_FAILED",
+    "ERROR_TOOL_NOT_FOUND",
+    "ERROR_SESSION_NOT_FOUND",
+    "ERROR_INVALID_PARAMETERS",
+    "ERROR_TIMEOUT",
+    "ERROR_STREAM_INTERRUPTED",
+]

toolplane/common/base_config.py

@@ -0,0 +1,129 @@
+"""Base configuration class shared between gRPC and HTTP clients."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+from .constants import (
+    DEFAULT_BUFFER_SIZE,
+    DEFAULT_HEARTBEAT_INTERVAL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MAX_WORKERS,
+    DEFAULT_POLL_INTERVAL,
+    DEFAULT_REQUEST_TIMEOUT,
+    DEFAULT_RETRY_BACKOFF_MS,
+)
+from .utils import validate_description, validate_session_name
+
+
+@dataclass
+class BaseConfig(ABC):
+    """Base configuration for Toolplane clients."""
+
+    # Common configuration fields
+    api_key: Optional[str] = None
+    user_id: Optional[str] = None
+    session_name: Optional[str] = None
+    session_description: Optional[str] = None
+    session_namespace: Optional[str] = None
+
+    # Performance settings
+    heartbeat_interval: int = DEFAULT_HEARTBEAT_INTERVAL
+    max_workers: int = DEFAULT_MAX_WORKERS
+    poll_interval: float = DEFAULT_POLL_INTERVAL
+    request_timeout: int = DEFAULT_REQUEST_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    max_buffer_size: int = DEFAULT_BUFFER_SIZE
+    retry_backoff_ms: int = DEFAULT_RETRY_BACKOFF_MS
+
+    # Additional configuration
+    extra_config: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate configuration after initialization."""
+        self.validate()
+        self.normalize()
+
+    def validate(self):
+        """Validate configuration parameters."""
+        if self.session_name and not validate_session_name(self.session_name):
+            raise ValueError(f"Invalid session name: {self.session_name}")
+
+        if self.session_description and not validate_description(
+            self.session_description
+        ):
+            raise ValueError(
+                f"Session description too long: {len(self.session_description)} characters"
+            )
+
+        if self.heartbeat_interval <= 0:
+            raise ValueError("Heartbeat interval must be positive")
+
+        if self.max_workers <= 0:
+            raise ValueError("Max workers must be positive")
+
+        if self.poll_interval <= 0:
+            raise ValueError("Poll interval must be positive")
+
+        if self.request_timeout <= 0:
+            raise ValueError("Request timeout must be positive")
+
+        if self.max_retries < 0:
+            raise ValueError("Max retries must be non-negative")
+
+        if self.max_buffer_size <= 0:
+            raise ValueError("Max buffer size must be positive")
+
+        if self.retry_backoff_ms < 0:
+            raise ValueError("Retry backoff must be non-negative")
+
+    @abstractmethod
+    def normalize(self):
+        """Normalize configuration values (protocol-specific)."""
+        pass
+
+    @abstractmethod
+    def get_auth_info(self) -> Dict[str, Any]:
+        """Get authentication information (protocol-specific)."""
+        pass
+
+    def get_common_fields(self) -> Dict[str, Any]:
+        """Get common configuration fields."""
+        return {
+            "api_key": self.api_key,
+            "user_id": self.user_id,
+            "session_name": self.session_name,
+            "session_description": self.session_description,
+            "session_namespace": self.session_namespace,
+            "heartbeat_interval": self.heartbeat_interval,
+            "max_workers": self.max_workers,
+            "poll_interval": self.poll_interval,
+            "request_timeout": self.request_timeout,
+            "max_retries": self.max_retries,
+            "max_buffer_size": self.max_buffer_size,
+            "retry_backoff_ms": self.retry_backoff_ms,
+        }
+
+    def update_from_dict(self, config_dict: Dict[str, Any]):
+        """Update configuration from dictionary."""
+        for key, value in config_dict.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+            else:
+                self.extra_config[key] = value
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary."""
+        result = self.get_common_fields()
+        result.update(self.extra_config)
+        return result
+
+    def copy(self) -> "BaseConfig":
+        """Create a copy of the configuration."""
+        # This will be implemented by subclasses
+        raise NotImplementedError("Subclasses must implement copy method")
+
+    def merge(self, other: "BaseConfig") -> "BaseConfig":
+        """Merge this configuration with another."""
+        # This will be implemented by subclasses
+        raise NotImplementedError("Subclasses must implement merge method")

toolplane/common/base_connection_manager.py

@@ -0,0 +1,171 @@
+"""Base connection manager class shared between gRPC and HTTP clients."""
+
+import threading
+import time
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+try:
+    from ..core.errors import ConnectionError
+except ImportError:
+    # Fallback for standalone testing
+    class ConnectionError(Exception):
+        """Connection error for standalone testing."""
+
+        pass
+
+
+from .constants import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RETRY_BACKOFF_MS,
+)
+from .utils import with_retry
+
+
+class BaseConnectionManager(ABC):
+    """Base class for connection management."""
+
+    def __init__(self, config):
+        """Initialize base connection manager."""
+        self.config = config
+        self.connected = False
+        self.connection_lock = threading.RLock()
+        self.last_heartbeat = 0
+        self.connection_stats = {
+            "connect_time": 0,
+            "last_activity": 0,
+            "total_requests": 0,
+            "failed_requests": 0,
+            "reconnect_count": 0,
+        }
+
+    @abstractmethod
+    def connect(self):
+        """Establish connection (protocol-specific)."""
+        pass
+
+    @abstractmethod
+    def disconnect(self):
+        """Close connection (protocol-specific)."""
+        pass
+
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """Check if connection is active (protocol-specific)."""
+        pass
+
+    def ensure_connected(self):
+        """Ensure connection is established."""
+        if not self.is_connected():
+            self.connect()
+
+    @with_retry(max_retries=DEFAULT_MAX_RETRIES, backoff_ms=DEFAULT_RETRY_BACKOFF_MS)
+    def reconnect(self):
+        """Reconnect with retry logic."""
+        try:
+            self.disconnect()
+            time.sleep(0.1)  # Brief pause before reconnecting
+            self.connect()
+
+            with self.connection_lock:
+                self.connection_stats["reconnect_count"] += 1
+
+        except Exception as e:
+            raise ConnectionError(f"Failed to reconnect: {e}")
+
+    def health_check(self) -> bool:
+        """Perform health check."""
+        try:
+            return self._perform_health_check()
+        except Exception:
+            return False
+
+    @abstractmethod
+    def _perform_health_check(self) -> bool:
+        """Perform protocol-specific health check."""
+        pass
+
+    def heartbeat(self):
+        """Send heartbeat to server."""
+        try:
+            if self.is_connected():
+                current_time = time.time()
+                if current_time - self.last_heartbeat >= self.config.heartbeat_interval:
+                    self._send_heartbeat()
+                    self.last_heartbeat = current_time
+        except Exception:
+            # Heartbeat failures are not critical
+            pass
+
+    @abstractmethod
+    def _send_heartbeat(self):
+        """Send protocol-specific heartbeat."""
+        pass
+
+    def get_connection_info(self) -> Dict[str, Any]:
+        """Get connection information."""
+        with self.connection_lock:
+            return {
+                "connected": self.is_connected(),
+                "config": self.config.to_dict(),
+                "stats": self.connection_stats.copy(),
+                "last_heartbeat": self.last_heartbeat,
+            }
+
+    def reset_stats(self):
+        """Reset connection statistics."""
+        with self.connection_lock:
+            self.connection_stats = {
+                "connect_time": time.time() if self.is_connected() else 0,
+                "last_activity": time.time(),
+                "total_requests": 0,
+                "failed_requests": 0,
+                "reconnect_count": 0,
+            }
+
+    def _record_request(self, success: bool = True):
+        """Record request statistics."""
+        with self.connection_lock:
+            self.connection_stats["total_requests"] += 1
+            self.connection_stats["last_activity"] = time.time()
+            if not success:
+                self.connection_stats["failed_requests"] += 1
+
+    def get_request_stats(self) -> Dict[str, Any]:
+        """Get request statistics."""
+        with self.connection_lock:
+            stats = self.connection_stats.copy()
+
+            # Calculate success rate
+            total = stats["total_requests"]
+            failed = stats["failed_requests"]
+            success_rate = ((total - failed) / total * 100) if total > 0 else 0
+
+            return {
+                "total_requests": total,
+                "failed_requests": failed,
+                "success_rate": success_rate,
+                "reconnect_count": stats["reconnect_count"],
+                "uptime": (
+                    time.time() - stats["connect_time"]
+                    if stats["connect_time"] > 0
+                    else 0
+                ),
+                "last_activity": stats["last_activity"],
+            }
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.disconnect()
+
+    def __del__(self):
+        """Destructor to ensure connection is closed."""
+        try:
+            self.disconnect()
+        except Exception:
+            pass