chatspatial 1.1.0__py3-none-any.whl

chatspatial/utils/exceptions.py

@@ -0,0 +1,185 @@
+"""
+Exception classes for ChatSpatial.
+
+Exception Hierarchy Design Principles:
+======================================
+1. SEMANTIC CLARITY: Exception type immediately indicates error category
+2. MINIMAL HIERARCHY: Only add subclasses when semantically distinct
+3. CONSISTENCY: Same semantic error uses same exception type everywhere
+4. DEBUGGABILITY: Always preserve exception chain with `raise X from e`
+
+Exception Hierarchy:
+====================
+ChatSpatialError (base)
+├── DataError (data access/availability/format issues)
+│   ├── DataNotFoundError (required data missing)
+│   └── DataCompatibilityError (format/species mismatch)
+├── ParameterError (invalid user input/parameters)
+├── ProcessingError (algorithm/computation failures)
+└── DependencyError (missing packages/R environment)
+
+Usage Guidelines:
+=================
+
+INSTEAD OF ValueError, USE:
+---------------------------
+- ParameterError: Invalid parameter values, invalid combinations
+  Example: "n_clusters must be > 0", "method must be 'leiden' or 'louvain'"
+
+- DataError: Data validation failures (missing columns, wrong format)
+  Example: "Column 'cell_type' not found", "Data contains NaN values"
+
+INSTEAD OF RuntimeError, USE:
+-----------------------------
+- ProcessingError: Algorithm failures, computation errors
+  Example: "Clustering failed to converge", "Model training failed"
+
+- DependencyError: Package/environment issues
+  Example: "scvi-tools not installed", "R environment not configured"
+
+ALWAYS use exception chaining:
+------------------------------
+    try:
+        result = compute()
+    except Exception as e:
+        raise ProcessingError(f"Computation failed: {e}") from e
+
+NEVER silently swallow exceptions:
+----------------------------------
+    # BAD
+    except Exception:
+        pass
+
+    # GOOD
+    except ExpectedError as e:
+        logger.debug(f"Expected error: {e}")
+        # Handle gracefully
+"""
+
+
+class ChatSpatialError(Exception):
+    """Base exception for all ChatSpatial errors.
+
+    All custom exceptions inherit from this class, allowing:
+    - Catch all ChatSpatial errors: `except ChatSpatialError`
+    - Distinguish from Python built-in exceptions
+    """
+
+
+# =============================================================================
+# Data Errors - Issues with data access, availability, or format
+# =============================================================================
+
+
+class DataError(ChatSpatialError):
+    """Data-related errors (missing, invalid format, validation failures).
+
+    Use when:
+    - Required data column/key is missing
+    - Data format is invalid (wrong dtype, contains NaN/Inf)
+    - Data validation fails (too few cells, no spatial coordinates)
+
+    Examples:
+        raise DataError("Spatial coordinates contain NaN values")
+        raise DataError("Expression matrix is empty")
+        raise DataError(f"Column '{col}' not found in adata.obs")
+    """
+
+
+class DataNotFoundError(DataError):
+    """Required data not found in the expected location.
+
+    Use when:
+    - Dataset ID not found in registry
+    - Required analysis results missing (e.g., deconvolution not run)
+    - Expected file/resource doesn't exist
+
+    Examples:
+        raise DataNotFoundError(f"Dataset '{data_id}' not found")
+        raise DataNotFoundError("Deconvolution results not found")
+        raise DataNotFoundError("Velocity results not found in adata.obsm")
+    """
+
+
+class DataCompatibilityError(DataError):
+    """Data format or compatibility issues between datasets.
+
+    Use when:
+    - Gene naming convention mismatch (Ensembl vs Symbol)
+    - Species mismatch between spatial and reference data
+    - Incompatible data formats for integration
+
+    Examples:
+        raise DataCompatibilityError("Gene naming mismatch: symbols vs Ensembl")
+        raise DataCompatibilityError("Species mismatch: mouse vs human")
+    """
+
+
+# =============================================================================
+# Parameter Errors - Invalid user input or parameter combinations
+# =============================================================================
+
+
+class ParameterError(ChatSpatialError):
+    """Invalid parameter values or combinations.
+
+    Use when:
+    - Parameter value out of valid range
+    - Invalid parameter combination
+    - Required parameter missing
+    - Parameter type is wrong
+
+    REPLACES: ValueError for parameter validation
+
+    Examples:
+        raise ParameterError("n_clusters must be > 0")
+        raise ParameterError("method must be one of: 'leiden', 'louvain'")
+        raise ParameterError("Cannot use both 'n_clusters' and 'resolution'")
+        raise ParameterError("species parameter is required")
+    """
+
+
+# =============================================================================
+# Processing Errors - Algorithm or computation failures
+# =============================================================================
+
+
+class ProcessingError(ChatSpatialError):
+    """Errors during analysis processing or computation.
+
+    Use when:
+    - Algorithm fails to converge
+    - Numerical computation errors
+    - Model training failures
+    - Unexpected processing failures
+
+    REPLACES: RuntimeError for processing failures
+
+    Examples:
+        raise ProcessingError("Leiden clustering failed to converge")
+        raise ProcessingError(f"Model training failed: {e}") from e
+        raise ProcessingError("PCA computation failed: matrix is singular")
+    """
+
+
+# =============================================================================
+# Dependency Errors - Missing packages or environment issues
+# =============================================================================
+
+
+class DependencyError(ChatSpatialError):
+    """Missing or incompatible dependency.
+
+    Use when:
+    - Required Python package not installed
+    - R environment not configured
+    - R package missing
+    - Version incompatibility
+
+    REPLACES: ImportError for optional dependencies
+
+    Examples:
+        raise DependencyError("scvi-tools required: pip install scvi-tools")
+        raise DependencyError("R environment not configured")
+        raise DependencyError("CellChat R package not installed")
+    """

chatspatial/utils/image_utils.py

@@ -0,0 +1,267 @@
+"""
+Image utilities for spatial transcriptomics MCP.
+
+This module provides standardized functions for handling images in the MCP.
+All functions return Image objects that can be directly used in MCP tools.
+"""
+
+import base64
+import io
+import uuid
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Optional
+from collections.abc import Generator
+
+from mcp.types import ImageContent
+
+from .exceptions import ProcessingError
+from .path_utils import get_safe_output_path
+
+if TYPE_CHECKING:
+    from ..spatial_mcp_adapter import ToolContext
+
+
+# =============================================================================
+# Matplotlib Backend Management
+# =============================================================================
+
+
+def _ensure_non_interactive_backend() -> None:
+    """Ensure matplotlib uses non-interactive backend to prevent GUI popups on macOS."""
+    import matplotlib
+
+    current_backend = matplotlib.get_backend()
+    if current_backend != "Agg":
+        matplotlib.use("Agg")
+        import matplotlib.pyplot as plt
+
+        plt.ioff()
+
+
+@contextmanager
+def non_interactive_backend() -> Generator[None, None, None]:
+    """Context manager for temporary non-interactive matplotlib backend.
+
+    Use this when calling external plotting functions (e.g., cellrank, scvelo)
+    that may trigger interactive backend behavior. The original backend is
+    restored after the context exits.
+
+    For internal plotting code that doesn't need backend restoration,
+    use _ensure_non_interactive_backend() instead.
+
+    Usage:
+        with non_interactive_backend():
+            cr.pl.circular_projection(adata, ...)
+            fig = plt.gcf()
+
+    Yields:
+        None
+    """
+    import matplotlib
+
+    original_backend = matplotlib.get_backend()
+    needs_restore = original_backend != "Agg"
+
+    try:
+        if needs_restore:
+            matplotlib.use("Agg")
+            import matplotlib.pyplot as plt
+
+            plt.ioff()
+        yield
+    finally:
+        if needs_restore:
+            matplotlib.use(original_backend)
+
+
+if TYPE_CHECKING:
+    import matplotlib.pyplot as plt
+
+
+# Standard savefig parameters for consistent figure output
+SAVEFIG_PARAMS: dict[str, Any] = {
+    "bbox_inches": "tight",
+    "transparent": False,
+    "facecolor": "white",
+    "edgecolor": "none",
+    "pad_inches": 0.1,
+    "metadata": {"Software": "spatial-transcriptomics-mcp"},
+}
+
+
+def bytes_to_image_content(data: bytes, format: str = "png") -> ImageContent:
+    """Convert raw image bytes to MCP ImageContent.
+
+    This unified utility function handles the conversion from raw image bytes
+    to the MCP-compatible ImageContent type with proper MIME type mapping.
+
+    Args:
+        data: Raw image bytes
+        format: Image format (png, jpg, jpeg, gif, webp)
+
+    Returns:
+        ImageContent object ready for MCP tool return
+
+    Examples:
+        >>> img_bytes = fig.savefig(buf, format='png')
+        >>> content = bytes_to_image_content(img_bytes, format='png')
+    """
+    # MIME type mapping for common image formats
+    format_to_mime = {
+        "png": "image/png",
+        "jpg": "image/jpeg",
+        "jpeg": "image/jpeg",
+        "gif": "image/gif",
+        "webp": "image/webp",
+    }
+
+    # Get MIME type, default to PNG if format is unknown
+    mime_type = format_to_mime.get(format.lower(), "image/png")
+
+    # Encode to base64 string as required by ImageContent
+    encoded_data = base64.b64encode(data).decode("utf-8")
+
+    return ImageContent(type="image", data=encoded_data, mimeType=mime_type)
+
+
+def fig_to_image(
+    fig: "plt.Figure",
+    dpi: int = 100,
+    format: str = "png",
+    close_fig: bool = True,
+) -> ImageContent:
+    """Convert matplotlib figure to ImageContent
+
+    This function respects user's DPI and format settings without any
+    automatic compression or quality reduction. Large images are handled
+    by optimize_fig_to_image_with_cache which saves them to disk.
+
+    Args:
+        fig: Matplotlib figure
+        dpi: Resolution in dots per inch (user's setting is always respected)
+        format: Image format (png or jpg)
+        close_fig: Whether to close the figure after conversion
+
+    Returns:
+        ImageContent object ready for MCP tool return
+    """
+    _ensure_non_interactive_backend()  # Prevent GUI popups on macOS
+    import matplotlib.pyplot as plt
+
+    buf = io.BytesIO()
+
+    # Save figure with user's exact settings - no compromise
+    # Check for extra artists (e.g., legends positioned outside plot area)
+    extra_artists = getattr(fig, "_chatspatial_extra_artists", None)
+
+    try:
+        if format == "jpg":
+            try:
+                # Try with quality parameter first (newer matplotlib)
+                fig.savefig(
+                    buf,
+                    format=format,
+                    dpi=dpi,
+                    bbox_extra_artists=extra_artists,
+                    quality=85,
+                    **SAVEFIG_PARAMS,
+                )
+            except TypeError:
+                # Fallback for older matplotlib without quality parameter
+                fig.savefig(
+                    buf,
+                    format=format,
+                    dpi=dpi,
+                    bbox_extra_artists=extra_artists,
+                    **SAVEFIG_PARAMS,
+                )
+        else:  # PNG
+            fig.savefig(
+                buf,
+                format=format,
+                dpi=dpi,
+                bbox_extra_artists=extra_artists,
+                **SAVEFIG_PARAMS,
+            )
+
+        buf.seek(0)
+        img_data = buf.read()
+
+        if close_fig:
+            plt.close(fig)
+
+        # Convert to ImageContent using unified utility
+        return bytes_to_image_content(img_data, format=format)
+
+    except Exception as e:
+        if close_fig:
+            plt.close(fig)
+        raise ProcessingError(f"Failed to convert figure to image: {e}") from e
+
+
+# ============ Token Optimization and Publication Export Support ============
+
+
+async def optimize_fig_to_image_with_cache(
+    fig: "plt.Figure",
+    params: Any,
+    ctx: Optional["ToolContext"] = None,
+    data_id: Optional[str] = None,
+    plot_type: Optional[str] = None,
+    mode: str = "auto",  # Kept for API compatibility, ignored
+) -> str:
+    """Save figure to file and return path for MCP protocol efficiency.
+
+    MCP protocol has ~3.3x overhead for embedded ImageContent, so we always
+    save to file and return path as text (following MCP best practice:
+    "Prefer using URIs over embedded content for large files").
+
+    Args:
+        fig: Matplotlib figure
+        params: Visualization parameters (used for DPI extraction)
+        ctx: ToolContext (unused, kept for API compatibility)
+        data_id: Dataset ID (unused, kept for API compatibility)
+        plot_type: Plot type (used for filename generation)
+        mode: Ignored (always saves to file)
+
+    Returns:
+        str with file path (FastMCP auto-converts to TextContent)
+    """
+    _ensure_non_interactive_backend()
+    import matplotlib.pyplot as plt
+
+    target_dpi = params.dpi if hasattr(params, "dpi") and params.dpi else 100
+    extra_artists = getattr(fig, "_chatspatial_extra_artists", None)
+
+    # Generate image
+    buf = io.BytesIO()
+    fig.savefig(
+        buf,
+        format="png",
+        dpi=target_dpi,
+        bbox_extra_artists=extra_artists,
+        **SAVEFIG_PARAMS,
+    )
+    actual_size = buf.tell()
+
+    # Save to file (use centralized path utility for consistent output handling)
+    output_dir = get_safe_output_path("./visualizations")
+    filename = (
+        f"{plot_type}_{uuid.uuid4().hex[:8]}.png"
+        if plot_type
+        else f"viz_{uuid.uuid4().hex[:8]}.png"
+    )
+    filepath = output_dir / filename
+
+    buf.seek(0)
+    with open(filepath, "wb") as f:
+        f.write(buf.read())
+    buf.close()
+    plt.close(fig)
+
+    return (
+        f"Visualization saved: {filepath}\n"
+        f"Type: {plot_type or 'visualization'}\n"
+        f"Size: {actual_size // 1024}KB\n"
+        f"Resolution: {target_dpi} DPI"
+    )

chatspatial/utils/mcp_utils.py

@@ -0,0 +1,137 @@
+"""
+MCP utilities for ChatSpatial.
+
+Tools for MCP server: error handling decorator and output suppression.
+"""
+
+import io
+import logging
+import traceback
+import warnings
+from contextlib import contextmanager, redirect_stderr, redirect_stdout
+from functools import wraps
+from typing import get_type_hints
+
+# =============================================================================
+# Output Suppression
+# =============================================================================
+@contextmanager
+def suppress_output():
+    """
+    Context manager to suppress stdout, stderr, warnings, and logging.
+
+    Usage:
+        with suppress_output():
+            noisy_function()
+    """
+    old_level = logging.getLogger().level
+    logging.getLogger().setLevel(logging.ERROR)
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        stdout_buffer = io.StringIO()
+        stderr_buffer = io.StringIO()
+
+        try:
+            with redirect_stdout(stdout_buffer), redirect_stderr(stderr_buffer):
+                yield
+        finally:
+            logging.getLogger().setLevel(old_level)
+
+
+# =============================================================================
+# MCP Tool Error Handler
+# =============================================================================
+def _get_return_type_category(func) -> str:
+    """
+    Determine return type category using proper type inspection.
+
+    Returns one of: "image", "basemodel", "str", "simple", "unknown"
+    """
+    try:
+        from typing import Union, get_args, get_origin
+
+        from mcp.types import ImageContent
+        from pydantic import BaseModel
+
+        hints = get_type_hints(func)
+        return_type = hints.get("return")
+
+        if return_type is None:
+            return "unknown"
+
+        # Handle Union types (including Optional which is Union[X, None])
+        origin = get_origin(return_type)
+        if origin is Union:
+            types = [t for t in get_args(return_type) if t is not type(None)]
+        else:
+            types = [return_type]
+
+        # Check ImageContent first (it's a BaseModel subclass, so order matters)
+        for t in types:
+            if isinstance(t, type) and issubclass(t, ImageContent):
+                return "image"
+
+        # Check for BaseModel subclasses
+        for t in types:
+            if isinstance(t, type) and issubclass(t, BaseModel):
+                return "basemodel"
+
+        # Check for str
+        if str in types:
+            return "str"
+
+        return "simple"
+
+    except Exception:
+        return "unknown"
+
+
+def mcp_tool_error_handler(include_traceback: bool = True):
+    """
+    Decorator for MCP tools to handle errors gracefully.
+
+    Errors are returned in the result object (not raised as exceptions),
+    allowing LLMs to see and potentially handle them.
+    """
+
+    def decorator(func):
+        return_type_category = _get_return_type_category(func)
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await func(*args, **kwargs)
+
+            except Exception as e:
+                error_msg = str(e)
+
+                if return_type_category == "image":
+                    # Return error as text (Union[ImageContent, str] allows this)
+                    msg = f"Visualization Error: {error_msg}"
+                    if include_traceback and not isinstance(e, (ValueError, KeyError)):
+                        msg += f"\n\nDetails:\n{traceback.format_exc()}"
+                    return msg
+
+                elif return_type_category == "basemodel":
+                    # Re-raise for FastMCP to handle
+                    raise
+
+                elif return_type_category == "str":
+                    return f"Error: {error_msg}"
+
+                else:
+                    # Return error dict for simple types
+                    content = [{"type": "text", "text": f"Error: {error_msg}"}]
+                    if include_traceback and not isinstance(e, ValueError):
+                        content.append(
+                            {
+                                "type": "text",
+                                "text": f"Traceback:\n{traceback.format_exc()}",
+                            }
+                        )
+                    return {"content": content, "isError": True}
+
+        return wrapper
+
+    return decorator