psforge 0.2.0__py3-none-any.whl

psforge/__init__.py

@@ -0,0 +1,5 @@
+"""PSForge - AI-Powered Photoshop Automation via MCP."""
+
+from psforge.app import __app_name__, __description__, __version__
+
+__all__ = ["__version__", "__app_name__", "__description__"]

psforge/app.py

@@ -0,0 +1,5 @@
+"""PSForge application metadata."""
+
+__version__ = "0.2.0"
+__app_name__ = "PSForge"
+__description__ = "AI-Powered Photoshop Automation via MCP"

psforge/decorators.py

@@ -0,0 +1,91 @@
+"""MCP tool decorators for logging, debugging, and error handling."""
+
+import functools
+import traceback
+from typing import Any, Callable
+
+from loguru import logger
+
+
+def log_tool_call(func: Callable) -> Callable:
+    """Log tool call entry and exit with parameters and results.
+
+    Args:
+        func: The tool function to wrap.
+
+    Returns:
+        Wrapped function with logging.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        tool_name = func.__name__
+        logger.info(f"Tool called: {tool_name}")
+        logger.debug(f"Tool params: args={args}, kwargs={kwargs}")
+
+        try:
+            result = func(*args, **kwargs)
+            if isinstance(result, dict) and "success" in result:
+                status = "SUCCESS" if result["success"] else "FAILED"
+                logger.info(f"Tool {tool_name} {status}")
+            else:
+                logger.info(f"Tool {tool_name} completed")
+            return result
+        except Exception as e:
+            logger.error(f"Tool {tool_name} raised exception: {e}")
+            raise
+
+    return wrapper
+
+
+def debug_tool(func: Callable) -> Callable:
+    """Enhanced error handling decorator that ensures consistent error format.
+
+    All errors are caught and converted to standardized dict format:
+    {
+        "success": False,
+        "error": "Brief error message",
+        "detailed_error": "Full error with traceback",
+        "context": {...}  # Current PS state (if available)
+    }
+
+    Args:
+        func: The tool function to wrap.
+
+    Returns:
+        Wrapped function with enhanced error handling.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> dict:
+        try:
+            result = func(*args, **kwargs)
+            # If function returns dict with success field, pass through
+            if isinstance(result, dict):
+                return result
+            # Otherwise wrap in success format
+            return {"success": True, "result": result}
+        except Exception as e:
+            error_msg = str(e)
+            detailed_error = traceback.format_exc()
+
+            logger.error(f"Tool {func.__name__} failed: {error_msg}")
+            logger.debug(f"Full traceback:\n{detailed_error}")
+
+            # Try to get context even on error
+            context = None
+            try:
+                from psforge.ps_adapter.context import get_context_info
+
+                context = get_context_info()
+            except Exception as ctx_error:
+                logger.debug(f"Could not retrieve context after error: {ctx_error}")
+
+            return {
+                "success": False,
+                "error": error_msg,
+                "detailed_error": detailed_error,
+                "context": context,
+            }
+
+    return wrapper

psforge/ps_adapter/__init__.py

@@ -0,0 +1,12 @@
+"""Photoshop adapter layer - manages PS connection, execution, and context."""
+
+from psforge.ps_adapter.application import PhotoshopApp
+from psforge.ps_adapter.context import get_context_info
+from psforge.ps_adapter.process_guard import check_photoshop_alive, restart_photoshop
+
+__all__ = [
+    "PhotoshopApp",
+    "get_context_info",
+    "check_photoshop_alive",
+    "restart_photoshop",
+]

psforge/ps_adapter/action_manager.py

@@ -0,0 +1,5 @@
+"""Action Manager interface for Photoshop's Descriptor API.
+
+Currently unused placeholder. Reserved for future state-caching
+or advanced descriptor-based operations.
+"""

psforge/ps_adapter/application.py

@@ -0,0 +1,149 @@
+"""Photoshop application singleton and connection management."""
+
+import time
+from typing import Any
+
+from loguru import logger
+from photoshop import Session
+
+from psforge.ps_adapter.utils import retry_on_ps_error
+
+
+class PhotoshopApp:
+    """Singleton class for managing Photoshop application connection."""
+
+    _instance = None
+    _session = None
+    _app = None
+    _operation_count = 0
+    _max_operations_before_restart = 1000
+
+    def __new__(cls):
+        """Ensure only one instance exists (singleton pattern)."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        """Initialize Photoshop connection."""
+        if self._app is None:
+            self._connect()
+
+    def _connect(self) -> None:
+        """Establish connection to Photoshop."""
+        try:
+            logger.info("Connecting to Photoshop...")
+
+            # Create session
+            self._session = Session()
+            self._session.__enter__()
+            self._app = self._session.app
+
+            # Disable all dialogs to prevent blocking
+            self._execute_javascript_internal("app.displayDialogs = DialogModes.NO;")
+
+            logger.info("Successfully connected to Photoshop")
+
+        except Exception as e:
+            logger.error(f"Failed to connect to Photoshop: {e}")
+            raise ConnectionError(f"Could not connect to Photoshop: {e}")
+
+    def _disconnect(self) -> None:
+        """Disconnect from Photoshop."""
+        try:
+            if self._session:
+                self._session.__exit__(None, None, None)
+                self._session = None
+                self._app = None
+                logger.info("Disconnected from Photoshop")
+        except Exception as e:
+            logger.warning(f"Error during disconnect: {e}")
+
+    def reconnect(self) -> None:
+        """Reconnect to Photoshop (useful after restart)."""
+        logger.info("Reconnecting to Photoshop...")
+        self._disconnect()
+        time.sleep(2)  # Give PS time to fully start
+        self._connect()
+        self._operation_count = 0
+
+    @property
+    def app(self):
+        """Get the Photoshop Application object."""
+        if self._app is None:
+            self._connect()
+        return self._app
+
+    def _execute_javascript_internal(self, script: str) -> Any:
+        """Internal JavaScript execution (single attempt, retry handled by tenacity).
+
+        Args:
+            script: JavaScript/ExtendScript code to execute.
+
+        Returns:
+            Result from JavaScript execution.
+        """
+        if self._app is None:
+            self._connect()
+
+        return self._app.doJavaScript(script)
+
+    @retry_on_ps_error(max_attempts=3, base_wait=1.0)
+    def execute_javascript(self, script: str) -> Any:
+        """Execute JavaScript/ExtendScript in Photoshop with retry logic.
+
+        Args:
+            script: JavaScript/ExtendScript code to execute.
+
+        Returns:
+            Result from JavaScript execution.
+        """
+        # Increment operation counter
+        self._operation_count += 1
+
+        # Optional: Auto-restart PS after many operations to prevent memory leaks
+        # Uncomment if you experience stability issues
+        # if self._operation_count >= self._max_operations_before_restart:
+        #     logger.info(f"Reached {self._operation_count} operations, considering restart...")
+        #     from psforge.ps_adapter.process_guard import restart_photoshop
+        #     restart_photoshop()
+        #     self.reconnect()
+
+        return self._execute_javascript_internal(script)
+
+    def get_active_document(self):
+        """Get the currently active document.
+
+        Returns:
+            Active document object, or None if no document is open.
+        """
+        try:
+            if self.app.documents.length == 0:
+                return None
+            return self.app.activeDocument
+        except Exception as e:
+            logger.error(f"Failed to get active document: {e}")
+            return None
+
+    def has_active_document(self) -> bool:
+        """Check if there is an active document.
+
+        Returns:
+            True if a document is open and active, False otherwise.
+        """
+        try:
+            return self.app.documents.length > 0
+        except Exception:
+            return False
+
+    def get_photoshop_version(self) -> str:
+        """Get Photoshop version string.
+
+        Returns:
+            Version string, or 'Unknown' if cannot be determined.
+        """
+        try:
+            return str(self.app.version)
+        except Exception as e:
+            logger.error(f"Failed to get PS version: {e}")
+            return "Unknown"

psforge/ps_adapter/context.py

@@ -0,0 +1,219 @@
+"""Context tracking for Photoshop state - documents, layers, selections."""
+
+from typing import Any
+
+from loguru import logger
+
+from psforge.ps_adapter.application import PhotoshopApp
+
+
+def get_context_info() -> dict[str, Any]:
+    """Get comprehensive context information about current Photoshop state.
+
+    This function executes JavaScript in Photoshop to retrieve:
+    - Whether a document is open
+    - Document details (name, dimensions, resolution, color mode, layer count, selection status)
+    - Active layer details (name, type, opacity, blend mode, visibility, bounds, etc.)
+
+    Returns:
+        Dictionary containing context information with structure:
+        {
+            "has_document": bool,
+            "document": {
+                "name": str,
+                "width": int,
+                "height": int,
+                "resolution": float,
+                "color_mode": str,
+                "bit_depth": int,
+                "layer_count": int,
+                "has_selection": bool,
+            } or None,
+            "active_layer": {
+                "name": str,
+                "kind": str,
+                "opacity": float,
+                "blend_mode": str,
+                "visible": bool,
+                "locked": bool,
+                "is_background": bool,
+                "bounds": {"left": int, "top": int, "right": int, "bottom": int}
+            } or None
+        }
+    """
+    ps_app = PhotoshopApp()
+
+    # JavaScript to extract context information
+    context_script = """
+    (function() {
+        var context = {
+            has_document: false,
+            document: null,
+            active_layer: null
+        };
+
+        // Check if any document is open
+        if (app.documents.length === 0) {
+            return JSON.stringify(context);
+        }
+
+        context.has_document = true;
+        var doc = app.activeDocument;
+
+        // Get document information
+        var colorModeMap = {
+            1: "BITMAP",
+            2: "GRAYSCALE",
+            3: "INDEXED",
+            4: "RGB",
+            5: "CMYK",
+            7: "MULTICHANNEL",
+            8: "DUOTONE",
+            9: "LAB"
+        };
+
+        var bitDepthMap = {
+            1: 1,
+            8: 8,
+            16: 16,
+            32: 32
+        };
+
+        context.document = {
+            name: doc.name,
+            width: parseInt(doc.width),
+            height: parseInt(doc.height),
+            resolution: parseFloat(doc.resolution),
+            color_mode: colorModeMap[doc.mode] || "UNKNOWN",
+            bit_depth: bitDepthMap[doc.bitsPerChannel] || 8,
+            layer_count: doc.layers.length,
+            has_selection: false
+        };
+
+        // Check for active selection
+        try {
+            var selBounds = doc.selection.bounds;
+            if (selBounds) {
+                context.document.has_selection = true;
+            }
+        } catch(e) {
+            context.document.has_selection = false;
+        }
+
+        // Get active layer information
+        if (doc.activeLayer) {
+            var layer = doc.activeLayer;
+
+            var layerKindMap = {
+                1: "NORMAL",
+                2: "TEXT",
+                3: "SOLIDFILL",
+                4: "GRADIENTFILL",
+                5: "PATTERNFILL",
+                6: "LEVELS",
+                7: "CURVES",
+                8: "COLORBALANCE",
+                9: "BRIGHTNESSCONTRAST",
+                10: "HUESATURATION",
+                11: "SELECTIVECOLOR",
+                12: "CHANNELMIXER",
+                13: "GRADIENTMAP",
+                14: "INVERT",
+                15: "THRESHOLD",
+                16: "POSTERIZE",
+                17: "SMARTOBJECT",
+                18: "PHOTOFILTER",
+                19: "EXPOSURE",
+                20: "VIBRANCE",
+                21: "VIDEO",
+                22: "3D",
+                23: "LAYER3D"
+            };
+
+            var blendModeMap = {
+                "NORMAL": "NORMAL",
+                "DISSOLVE": "DISSOLVE",
+                "DARKEN": "DARKEN",
+                "MULTIPLY": "MULTIPLY",
+                "COLORBURN": "COLORBURN",
+                "LINEARBURN": "LINEARBURN",
+                "DARKERCOLOR": "DARKERCOLOR",
+                "LIGHTEN": "LIGHTEN",
+                "SCREEN": "SCREEN",
+                "COLORDODGE": "COLORDODGE",
+                "LINEARDODGE": "LINEARDODGE",
+                "LIGHTERCOLOR": "LIGHTERCOLOR",
+                "OVERLAY": "OVERLAY",
+                "SOFTLIGHT": "SOFTLIGHT",
+                "HARDLIGHT": "HARDLIGHT",
+                "VIVIDLIGHT": "VIVIDLIGHT",
+                "LINEARLIGHT": "LINEARLIGHT",
+                "PINLIGHT": "PINLIGHT",
+                "HARDMIX": "HARDMIX",
+                "DIFFERENCE": "DIFFERENCE",
+                "EXCLUSION": "EXCLUSION",
+                "SUBTRACT": "SUBTRACT",
+                "DIVIDE": "DIVIDE",
+                "HUE": "HUE",
+                "SATURATION": "SATURATION",
+                "COLOR": "COLOR",
+                "LUMINOSITY": "LUMINOSITY"
+            };
+
+            var isBackground = false;
+            try {
+                isBackground = layer.isBackgroundLayer;
+            } catch(e) {
+                isBackground = false;
+            }
+
+            var bounds = {left: 0, top: 0, right: 0, bottom: 0};
+            try {
+                bounds = {
+                    left: parseInt(layer.bounds[0]),
+                    top: parseInt(layer.bounds[1]),
+                    right: parseInt(layer.bounds[2]),
+                    bottom: parseInt(layer.bounds[3])
+                };
+            } catch(e) {}
+
+            context.active_layer = {
+                name: layer.name,
+                kind: layerKindMap[layer.kind] || "UNKNOWN",
+                opacity: parseFloat(layer.opacity),
+                blend_mode: blendModeMap[layer.blendMode.toString()] || "NORMAL",
+                visible: layer.visible,
+                locked: layer.allLocked || layer.pixelsLocked,
+                is_background: isBackground,
+                bounds: bounds
+            };
+        }
+
+        return JSON.stringify(context);
+    })();
+    """
+
+    try:
+        result = ps_app.execute_javascript(context_script)
+
+        # Parse JSON result
+        import json
+
+        if isinstance(result, str):
+            context = json.loads(result)
+        else:
+            context = result
+
+        logger.debug(f"Context retrieved: {context}")
+        return context
+
+    except Exception as e:
+        logger.error(f"Failed to get context info: {e}")
+
+        # Return minimal error context
+        return {
+            "has_document": False,
+            "document": None,
+            "active_layer": None,
+            "error": str(e),
+        }

psforge/ps_adapter/process_guard.py

@@ -0,0 +1,109 @@
+"""Process guard for Photoshop - health checks and restart."""
+
+import os
+import subprocess
+import time
+
+import psutil
+from loguru import logger
+
+
+def check_photoshop_alive() -> bool:
+    """Check if Photoshop process is running.
+
+    Returns:
+        True if Photoshop.exe is running, False otherwise.
+    """
+    try:
+        for proc in psutil.process_iter(["name"]):
+            if proc.info["name"] and "photoshop.exe" in proc.info["name"].lower():
+                return True
+        return False
+    except Exception as e:
+        logger.error(f"Failed to check Photoshop process: {e}")
+        return False
+
+
+def kill_photoshop_process() -> bool:
+    """Force kill all Photoshop processes.
+
+    Returns:
+        True if any process was killed, False otherwise.
+    """
+    killed = False
+
+    try:
+        for proc in psutil.process_iter(["name", "pid"]):
+            if proc.info["name"] and "photoshop.exe" in proc.info["name"].lower():
+                logger.warning(f"Force killing Photoshop process (PID: {proc.info['pid']})")
+                try:
+                    process = psutil.Process(proc.info["pid"])
+                    process.kill()
+                    killed = True
+                except Exception as e:
+                    logger.error(f"Failed to kill process {proc.info['pid']}: {e}")
+
+        if killed:
+            time.sleep(2)  # Wait for processes to fully terminate
+
+    except Exception as e:
+        logger.error(f"Error while killing Photoshop: {e}")
+
+    return killed
+
+
+def restart_photoshop(photoshop_path: str | None = None) -> bool:
+    """Restart Photoshop by killing existing processes and starting a new one.
+
+    Args:
+        photoshop_path: Optional path to Photoshop executable.
+                       If not provided, attempts to find it automatically.
+
+    Returns:
+        True if restart was successful, False otherwise.
+    """
+    logger.info("Restarting Photoshop...")
+
+    # Kill existing processes
+    kill_photoshop_process()
+
+    # Try to start Photoshop
+    if photoshop_path is None:
+        # Common Photoshop installation paths
+        possible_paths = [
+            r"C:\Program Files\Adobe\Adobe Photoshop 2024\Photoshop.exe",
+            r"C:\Program Files\Adobe\Adobe Photoshop 2023\Photoshop.exe",
+            r"C:\Program Files\Adobe\Adobe Photoshop 2022\Photoshop.exe",
+            r"C:\Program Files\Adobe\Adobe Photoshop CC 2019\Photoshop.exe",
+        ]
+
+        for path in possible_paths:
+            if os.path.exists(path):
+                photoshop_path = path
+                break
+
+    if photoshop_path and os.path.exists(photoshop_path):
+        try:
+            logger.info(f"Starting Photoshop from: {photoshop_path}")
+            subprocess.Popen([photoshop_path], shell=False)
+
+            # Wait for Photoshop to start
+            max_wait = 30
+            for i in range(max_wait):
+                time.sleep(1)
+                if check_photoshop_alive():
+                    logger.info("Photoshop started successfully")
+                    time.sleep(3)  # Additional wait for full initialization
+                    return True
+
+            logger.error(f"Photoshop did not start within {max_wait} seconds")
+            return False
+
+        except Exception as e:
+            logger.error(f"Failed to start Photoshop: {e}")
+            return False
+    else:
+        logger.warning("Could not find Photoshop executable path")
+        logger.info("Please start Photoshop manually")
+        return False
+

psforge/ps_adapter/utils.py

@@ -0,0 +1,80 @@
+"""Utility functions and decorators for PS adapter."""
+
+import functools
+from typing import Any, Callable
+
+from loguru import logger
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+
+def retry_on_ps_error(max_attempts: int = 3, base_wait: float = 1.0) -> Callable:
+    """Retry decorator for Photoshop operations that may fail transiently.
+
+    Args:
+        max_attempts: Maximum number of retry attempts.
+        base_wait: Base wait time in seconds (exponential backoff).
+
+    Returns:
+        Decorator function.
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        @retry(
+            retry=retry_if_exception_type((ConnectionError, TimeoutError, RuntimeError)),
+            stop=stop_after_attempt(max_attempts),
+            wait=wait_exponential(multiplier=base_wait, min=base_wait, max=10),
+            reraise=True,
+        )
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                logger.warning(f"PS operation {func.__name__} failed, will retry: {e}")
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def validate_numeric_range(value: float, min_val: float, max_val: float, param_name: str) -> None:
+    """Validate that a numeric parameter is within the allowed range.
+
+    Args:
+        value: The value to validate.
+        min_val: Minimum allowed value.
+        max_val: Maximum allowed value.
+        param_name: Parameter name for error messages.
+
+    Raises:
+        ValueError: If value is out of range.
+    """
+    if not (min_val <= value <= max_val):
+        raise ValueError(f"{param_name} must be between {min_val} and {max_val}, got {value}")
+
+
+def validate_color_channel(value: int, channel_name: str = "color") -> None:
+    """Validate that a color channel value is in valid range (0-255).
+
+    Args:
+        value: The color channel value.
+        channel_name: Channel name for error messages.
+
+    Raises:
+        ValueError: If value is out of range.
+    """
+    if not (0 <= value <= 255):
+        raise ValueError(f"{channel_name} must be between 0 and 255, got {value}")
+
+
+def js_escape_string(text: str) -> str:
+    """Escape a string for safe use in JavaScript/ExtendScript.
+
+    Args:
+        text: The string to escape.
+
+    Returns:
+        Escaped string safe for JavaScript.
+    """
+    return text.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\r", "\\r")