solidworks-mcp-python 1.5.0__py3-none-any.whl

solidworks_mcp/adapters/factory.py

@@ -0,0 +1,366 @@
+"""Adapter factory for creating SolidWorks adapters.
+
+Provides centralized adapter creation with configuration-based selection and automatic
+fallback strategies.
+"""
+
+from __future__ import annotations
+
+import platform
+from typing import Any
+
+from ..config import AdapterType, SolidWorksMCPConfig
+from .base import SolidWorksAdapter
+from .mock_adapter import MockSolidWorksAdapter
+from .vba_adapter import VbaGeneratorAdapter
+
+
+class AdapterFactory:
+    """Factory-pattern adapter creator with singleton and fallback strategies.
+
+    Manages adapter registration and creation with configuration-based selection.
+    Automatically wraps adapters with decorators (circuit breaker, connection pool) based on
+    configuration. Implements singleton pattern for consistency.
+
+    Attributes:
+        _adapter_registry (dict[AdapterType, type[SolidWorksAdapter]]): The adapter registry
+                                                                        value.
+        _adapters (dict[AdapterType, type[SolidWorksAdapter]]): The adapters value.
+        _instance (AdapterFactory | None): The instance value.
+
+    Example:
+                        >>> factory = AdapterFactory()
+                        >>> config = SolidWorksMCPConfig(adapter_type=AdapterType.PYWIN32)
+                        >>> adapter = factory.create_adapter(config)
+                        >>> await adapter.connect()
+    """
+
+    _adapter_registry: dict[AdapterType, type[SolidWorksAdapter]] = {}
+    _adapters: dict[AdapterType, type[SolidWorksAdapter]] = _adapter_registry
+    _instance: AdapterFactory | None = None
+
+    def __new__(cls) -> AdapterFactory:
+        """Initialize or return singleton AdapterFactory instance.
+
+        Enforces singleton pattern to ensure single adapter registry and consistent factory
+        behavior across application lifetime.
+
+        Returns:
+            AdapterFactory: The result produced by the operation.
+
+        Example:
+                            >>> factory1 = AdapterFactory()
+                            >>> factory2 = AdapterFactory()
+                            >>> factory1 is factory2
+                            True
+        """
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @classmethod
+    def register_adapter(
+        cls, adapter_type: AdapterType, adapter_class: type[SolidWorksAdapter]
+    ) -> None:
+        """Register an adapter class for a given adapter type.
+
+        Updates the adapter registry to map a specific AdapterType enum value to a
+        SolidWorksAdapter implementation class. Called during initialization to register built-
+        in adapters (PyWin32, Mock, etc.).
+
+        Args:
+            adapter_type (AdapterType): The adapter type value.
+            adapter_class (type[SolidWorksAdapter]): The adapter class value.
+
+        Returns:
+            None: None.
+
+        Example:
+                            >>> from adapters.pywin32_adapter import PyWin32Adapter
+                            >>> AdapterFactory.register_adapter(
+                            ...     AdapterType.PYWIN32, PyWin32Adapter
+                            ... )
+        """
+        cls._adapter_registry[adapter_type] = adapter_class
+
+    @classmethod
+    def create_adapter(cls, config: SolidWorksMCPConfig) -> SolidWorksAdapter:
+        """Create and configure a SolidWorks adapter instance.
+
+        Determines the best adapter type based on configuration and environment. Selects
+        implementation, applies wrappers (circuit breaker, connection pool), and returns a
+        fully-initialized adapter ready for connection.
+
+        The adapter is automatically downgraded to Mock on non-Windows platforms or when testing
+        is enabled, with fallback to configured type otherwise.
+
+        Args:
+            config (SolidWorksMCPConfig): Configuration values for the operation.
+
+        Returns:
+            SolidWorksAdapter: The result produced by the operation.
+
+        Example:
+                            >>> config = SolidWorksMCPConfig(mock_solidworks=True)
+                            >>> adapter = AdapterFactory.create_adapter(config)
+                            >>> isinstance(adapter, MockSolidWorksAdapter)
+                            True
+        """
+        factory = cls()
+        return factory._create_adapter_impl(config)
+
+    def _create_adapter_impl(self, config: SolidWorksMCPConfig) -> SolidWorksAdapter:
+        """Internal implementation for adapter creation and wrapping.
+
+        Handles the core logic of creating base adapter, applying optional wrappers (circuit
+        breaker, connection pooling), and returning final adapter configured for use.
+
+        Args:
+            config (SolidWorksMCPConfig): Configuration values for the operation.
+
+        Returns:
+            SolidWorksAdapter: The result produced by the operation.
+
+        Raises:
+            ValueError: If the operation cannot be completed.
+        """
+        # Determine the best adaptertype
+        adapter_type = self._determine_adapter_type(config)
+
+        # Get adapter class
+        if adapter_type not in self._adapter_registry:
+            raise ValueError(f"Adaptertype {adapter_type} not registered")
+
+        adapter_class = self._adapter_registry[adapter_type]
+
+        # Create base adapter
+        if adapter_type == AdapterType.VBA:
+            backing_type = self._determine_vba_backing_type(config)
+            if backing_type not in self._adapter_registry:
+                raise ValueError(f"Backing adapter type {backing_type} not registered")
+
+            backing_class = self._adapter_registry[backing_type]
+            if backing_type == AdapterType.MOCK:
+                backing_adapter = backing_class(config)
+            else:
+                backing_adapter = backing_class(self._build_adapter_config(config))
+            base_adapter = VbaGeneratorAdapter(backing_adapter=backing_adapter)
+        elif adapter_type == AdapterType.MOCK:
+            base_adapter = adapter_class(config)  # type: ignore[assignment]
+        else:
+            adapter_config = self._build_adapter_config(config)
+            base_adapter = adapter_class(adapter_config)  # type: ignore[assignment]
+
+        # Wrap with additional features if enabled
+        adapter: SolidWorksAdapter = base_adapter  # type: ignore[assignment]
+
+        # Keep mock/testing adapters simple and deterministic.
+        if adapter_type != AdapterType.MOCK and config.enable_circuit_breaker:
+            adapter = self._wrap_with_circuit_breaker(adapter, config)
+
+        if adapter_type != AdapterType.MOCK and config.enable_connection_pooling:
+            adapter = self._wrap_with_connection_pool(adapter, config)
+
+        self._apply_soc_logging(adapter, config)
+
+        return adapter
+
+    @staticmethod
+    def _apply_soc_logging(
+        adapter: SolidWorksAdapter, config: SolidWorksMCPConfig
+    ) -> None:
+        """Turn on SolidWorks-as-Code session logging when the config asks for it.
+
+        Sets ``soc_session_id`` / ``soc_db_path`` on the returned adapter from
+        config. Off unless ``config.soc_logging_enabled``. The actual
+        ``ToolCallRecord`` writes happen in ``CircuitBreakerAdapter._soc_log``,
+        so logging is effective only when the circuit breaker wrapper is in
+        play (the default for non-mock adapters).
+        """
+        if not getattr(config, "soc_logging_enabled", False):
+            return
+        adapter.soc_session_id = config.soc_session_id
+        if config.soc_db_path is not None:
+            adapter.soc_db_path = config.soc_db_path
+
+    def _determine_adapter_type(self, config: SolidWorksMCPConfig) -> AdapterType:
+        """Determine optimal adapter type based on environment and config.
+
+        Applies decision logic to select best adapter implementation: 1. Force Mock if testing
+        or mock_solidworks flag set 2. Fall back to Mock if PyWin32 requested but not on Windows
+        3. Use configured adapter_type otherwise
+
+        Args:
+            config (SolidWorksMCPConfig): Configuration values for the operation.
+
+        Returns:
+            AdapterType: The result produced by the operation.
+
+        Example:
+                            >>> config = SolidWorksMCPConfig(adapter_type=AdapterType.PYWIN32)
+                            >>> factory = AdapterFactory()
+                            >>> adapter_type = factory._determine_adapter_type(config)
+                            >>> # On non-Windows: AdapterType.MOCK
+                            >>> # On Windows: AdapterType.PYWIN32
+        """
+        # Force mock adapter for testing
+        if config.testing or config.mock_solidworks:
+            return AdapterType.MOCK
+
+        # Check platform compatibility
+        if (
+            platform.system() != "Windows"
+            and config.adapter_type == AdapterType.PYWIN32
+        ):
+            # Fallback to mock on non-Windows platforms
+            return AdapterType.MOCK
+
+        # Use configured adaptertype
+        return config.adapter_type
+
+    def _determine_vba_backing_type(self, config: SolidWorksMCPConfig) -> AdapterType:
+        """Determine which adapter should back the VBA wrapper.
+
+        Args:
+            config (SolidWorksMCPConfig): Configuration values for the operation.
+
+        Returns:
+            AdapterType: The result produced by the operation.
+        """
+        if config.testing or config.mock_solidworks:
+            return AdapterType.MOCK
+        if platform.system() != "Windows":
+            return AdapterType.MOCK
+        return AdapterType.PYWIN32
+
+    def _build_adapter_config(self, config: SolidWorksMCPConfig) -> dict[str, Any]:
+        """Extract and transform config for adapter instantiation.
+
+        Creates adapter-specific configuration dict from main config object. Includes SolidWorks
+        paths, validation settings, and timeouts/retries.
+
+        Args:
+            config (SolidWorksMCPConfig): Configuration values for the operation.
+
+        Returns:
+            dict[str, Any]: A dictionary containing the resulting values.
+
+        Example:
+                            >>> main_config = SolidWorksMCPConfig(solidworks_path='/sw/sw.exe')
+                            >>> factory = AdapterFactory()
+                            >>> adapter_cfg = factory._build_adapter_config(main_config)
+                            >>> adapter_cfg['timeout']
+                            30
+        """
+        return {
+            "solidworks_path": config.solidworks_path,
+            "enable_windows_validation": config.enable_windows_validation,
+            "debug": config.debug,
+            "timeout": 30,  # Default timeout in seconds
+            "retry_attempts": 3,
+            "retry_delay": 1.0,
+        }
+
+    def _wrap_with_circuit_breaker(
+        self, adapter: SolidWorksAdapter, config: SolidWorksMCPConfig
+    ) -> SolidWorksAdapter:
+        """Wrap adapter with circuit breaker for fault tolerance.
+
+        Applies circuit breaker decorator to handle COM failures, timeouts, and transient
+        errors. Automatically opens circuit after threshold failures and enters half-open
+        recovery state.
+
+        Args:
+            adapter (SolidWorksAdapter): Adapter instance used for the operation.
+            config (SolidWorksMCPConfig): Configuration values for the operation.
+
+        Returns:
+            SolidWorksAdapter: The result produced by the operation.
+
+        Example:
+                            >>> from adapters.mock_adapter import MockSolidWorksAdapter
+                            >>> base = MockSolidWorksAdapter()
+                            >>> config = SolidWorksMCPConfig()
+                            >>> wrapped = factory._wrap_with_circuit_breaker(base, config)
+        """
+        from .circuit_breaker import CircuitBreakerAdapter
+
+        return CircuitBreakerAdapter(
+            adapter=adapter,
+            failure_threshold=config.circuit_breaker_threshold,
+            recovery_timeout=config.circuit_breaker_timeout,
+            half_open_max_calls=3,
+        )
+
+    def _wrap_with_connection_pool(
+        self, adapter: SolidWorksAdapter, config: SolidWorksMCPConfig
+    ) -> SolidWorksAdapter:
+        """Wrap adapter with connection pooling for performance.
+
+        Applies connection pool decorator to reuse SolidWorks COM connections, reducing
+        connection overhead for repeated operations. Pool size and timeout configured via config
+        object.
+
+        Args:
+            adapter (SolidWorksAdapter): Adapter instance used for the operation.
+            config (SolidWorksMCPConfig): Configuration values for the operation.
+
+        Returns:
+            SolidWorksAdapter: The result produced by the operation.
+
+        Example:
+                            >>> from adapters.mock_adapter import MockSolidWorksAdapter
+                            >>> base = MockSolidWorksAdapter()
+                            >>> config = SolidWorksMCPConfig()
+                            >>> pooled = factory._wrap_with_connection_pool(base, config)
+        """
+        from .connection_pool import ConnectionPoolAdapter
+
+        return ConnectionPoolAdapter(
+            adapter_factory=lambda: adapter,
+            pool_size=config.connection_pool_size,
+            max_retries=3,
+        )
+
+
+async def create_adapter(config: SolidWorksMCPConfig) -> SolidWorksAdapter:
+    """Async factory function for creating SolidWorks adapters.
+
+    Args:
+        config (SolidWorksMCPConfig): Configuration values for the operation.
+
+    Returns:
+        SolidWorksAdapter: The result produced by the operation.
+    """
+    # Register adapters if not already done
+    _register_default_adapters()
+
+    # Create adapter using factory
+    adapter = AdapterFactory.create_adapter(config)
+
+    return adapter
+
+
+def _register_default_adapters() -> None:
+    """Register default adapter implementations.
+
+    Returns:
+        None: None.
+    """
+    # Always register mock adapter
+    AdapterFactory.register_adapter(AdapterType.MOCK, MockSolidWorksAdapter)
+    AdapterFactory.register_adapter(AdapterType.VBA, VbaGeneratorAdapter)  # type: ignore[arg-type]
+
+    # Register pywin32 adapter if on Windows
+    if platform.system() == "Windows":
+        try:
+            from .pywin32_adapter import PyWin32Adapter
+
+            AdapterFactory.register_adapter(AdapterType.PYWIN32, PyWin32Adapter)
+        except ImportError:
+            # pywin32 not available, will fall back to mock
+            pass
+
+    # Future adapters can be registered here
+    # AdapterFactory.register_adapter(AdapterType.EDGE_DOTNET, EdgeDotNetAdapter)
+    # AdapterFactory.register_adapter(AdapterType.POWERSHELL, PowerShellAdapter)

solidworks_mcp/adapters/intelligent_router.py

@@ -0,0 +1,218 @@
+"""Intelligent router for COM/VBA execution with optional response caching."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ..cache.response_cache import ResponseCache
+from .base import AdapterResult, AdapterResultStatus
+from .complexity_analyzer import ComplexityAnalyzer
+
+OperationCallable = Callable[..., Awaitable[AdapterResult[Any]]]
+
+
+@dataclass(frozen=True)
+class RouteResult:
+    """Route execution metadata.
+
+    Attributes:
+        route (str): The route value.
+        used_cache (bool): The used cache value.
+    """
+
+    route: str
+    used_cache: bool
+
+
+class IntelligentRouter:
+    """Route operations between COM and VBA paths using complexity analysis.
+
+    Args:
+        analyzer (ComplexityAnalyzer): The analyzer value.
+        cache (ResponseCache): The cache value.
+        cacheable_operations (set[str] | None): The cacheable operations value. Defaults to
+                                                None.
+
+    Attributes:
+        _analyzer (Any): The analyzer value.
+        _cache (Any): The cache value.
+        _cacheable_operations (Any): The cacheable operations value.
+    """
+
+    def __init__(
+        self,
+        analyzer: ComplexityAnalyzer,
+        cache: ResponseCache,
+        cacheable_operations: set[str] | None = None,
+    ) -> None:
+        """Initialize router dependencies.
+
+        Args:
+            analyzer (ComplexityAnalyzer): The analyzer value.
+            cache (ResponseCache): The cache value.
+            cacheable_operations (set[str] | None): The cacheable operations value. Defaults to
+                                                    None.
+
+        Returns:
+            None: None.
+        """
+        self._analyzer = analyzer
+        self._cache = cache
+        self._cacheable_operations = cacheable_operations or {
+            # Live document metadata is deliberately NOT cached. Model state,
+            # save state, paths, features, configurations, dimensions and
+            # properties can all change after any CAD operation, and this
+            # router has no reliable mutation-triggered invalidation.
+            # "get_model_info",
+            # "list_features",
+            # "list_configurations",
+            # "get_file_properties",
+            # "get_dimension",
+            # Analysis operations — NOT cached: model state changes with
+            # every feature-creation tool call and the router has no
+            # automatic invalidation. Caching these produced stale
+            # volumes mid-build.
+            # "get_mass_properties",
+            # "calculate_mass_properties",
+            "get_material_properties",
+            "analyze_geometry",
+            "check_interference",
+            # Drawing analysis operations
+            "analyze_drawing_comprehensive",
+            "analyze_drawing_dimensions",
+            "analyze_drawing_views",
+            "analyze_drawing_annotations",
+            "check_drawing_compliance",
+            "check_drawing_standards",
+            "compare_drawing_versions",
+            # Classification and indexing
+            "classify_feature_tree",
+            "discover_solidworks_docs",
+        }
+
+    async def execute(
+        self,
+        operation: str,
+        payload: object,
+        call_args: tuple[Any, ...],
+        call_kwargs: dict[str, Any],
+        com_operation: OperationCallable,
+        vba_operation: OperationCallable | None,
+        cache_ttl_seconds: int | None = None,
+    ) -> tuple[AdapterResult[Any], RouteResult]:
+        """Provide execute support for the intelligent router.
+
+        Args:
+            operation (str): Callable object executed by the helper.
+            payload (object): The payload value.
+            call_args (tuple[Any, ...]): The call args value.
+            call_kwargs (dict[str, Any]): The call kwargs value.
+            com_operation (OperationCallable): The com operation value.
+            vba_operation (OperationCallable | None): The vba operation value.
+            cache_ttl_seconds (int | None): The cache ttl seconds value. Defaults to None.
+
+        Returns:
+            tuple[AdapterResult[Any], RouteResult]: A tuple containing the resulting values.
+        """
+        if operation in self._cacheable_operations and self._cache.enabled:
+            key = self._cache.make_key(operation, payload)
+            cached = self._cache.get(key)
+            if isinstance(cached, AdapterResult):
+                return cached, RouteResult(route="cache", used_cache=True)
+
+        decision = self._analyzer.analyze(operation=operation, payload=payload)
+
+        if decision.prefer_vba and vba_operation is not None:
+            vba_result = await self._safe_call(vba_operation, call_args, call_kwargs)
+            self._analyzer.record_result(
+                operation=operation,
+                route="vba",
+                success=vba_result.is_success,
+            )
+            if vba_result.is_success:
+                self._cache_result(operation, payload, vba_result, cache_ttl_seconds)
+                return vba_result, RouteResult(route="vba", used_cache=False)
+
+        com_result = await self._safe_call(com_operation, call_args, call_kwargs)
+        self._analyzer.record_result(
+            operation=operation,
+            route="com",
+            success=com_result.is_success,
+        )
+
+        if com_result.is_success:
+            self._cache_result(operation, payload, com_result, cache_ttl_seconds)
+            return com_result, RouteResult(route="com", used_cache=False)
+
+        if not decision.prefer_vba and vba_operation is not None:
+            fallback_result = await self._safe_call(
+                vba_operation,
+                call_args,
+                call_kwargs,
+            )
+            self._analyzer.record_result(
+                operation=operation,
+                route="vba",
+                success=fallback_result.is_success,
+            )
+            if fallback_result.is_success:
+                self._cache_result(
+                    operation,
+                    payload,
+                    fallback_result,
+                    cache_ttl_seconds,
+                )
+                return fallback_result, RouteResult(
+                    route="vba-fallback", used_cache=False
+                )
+
+        return com_result, RouteResult(route="com-error", used_cache=False)
+
+    async def _safe_call(
+        self,
+        operation_callable: OperationCallable,
+        call_args: tuple[Any, ...],
+        call_kwargs: dict[str, Any],
+    ) -> AdapterResult[Any]:
+        """Call adapter operation and normalize unexpected exceptions.
+
+        Args:
+            operation_callable (OperationCallable): The operation callable value.
+            call_args (tuple[Any, ...]): The call args value.
+            call_kwargs (dict[str, Any]): The call kwargs value.
+
+        Returns:
+            AdapterResult[Any]: The result produced by the operation.
+        """
+        try:
+            return await operation_callable(*call_args, **call_kwargs)
+        except Exception as exc:
+            return AdapterResult(
+                status=AdapterResultStatus.ERROR,
+                error=f"operation failed: {exc}",
+            )
+
+    def _cache_result(
+        self,
+        operation: str,
+        payload: object,
+        result: AdapterResult[Any],
+        ttl_seconds: int | None,
+    ) -> None:
+        """Persist successful operation result in cache when eligible.
+
+        Args:
+            operation (str): Callable object executed by the helper.
+            payload (object): The payload value.
+            result (AdapterResult[Any]): The result value.
+            ttl_seconds (int | None): The ttl seconds value.
+
+        Returns:
+            None: None.
+        """
+        if operation not in self._cacheable_operations:
+            return
+        key = self._cache.make_key(operation, payload)
+        self._cache.set(key=key, value=result, ttl_seconds=ttl_seconds)