chatspatial 1.1.0__py3-none-any.whl

chatspatial/utils/path_utils.py

@@ -0,0 +1,243 @@
+"""Path handling utilities for ChatSpatial MCP server.
+
+This module provides robust path handling that works correctly regardless of
+the current working directory when the MCP server is launched.
+
+Key features:
+- Resolves relative paths against project root (not cwd)
+- Automatic fallback to /tmp for permission issues
+- Security checks to prevent writing outside safe directories
+"""
+
+import os
+import warnings
+from pathlib import Path
+
+# Project root directory (based on utils module location)
+# This is always correct regardless of cwd
+_PROJECT_ROOT = Path(__file__).parent.parent.resolve()
+
+
+def get_project_root() -> Path:
+    """Get ChatSpatial project root directory.
+
+    Returns:
+        Absolute path to project root, regardless of current working directory.
+
+    Example:
+        >>> root = get_project_root()
+        >>> print(root)
+        /path/to/chatspatial/chatspatial
+    """
+    return _PROJECT_ROOT
+
+
+def get_safe_output_path(
+    output_dir: str,
+    fallback_to_tmp: bool = True,
+    create_if_missing: bool = True,
+) -> Path:
+    """Get safe, writable output directory path.
+
+    This function handles path resolution robustly:
+    - Relative paths are resolved against CURRENT WORKING DIRECTORY (respects user config)
+    - Tests write permission before returning
+    - Falls back to /tmp/chatspatial/outputs if original path not writable
+
+    Args:
+        output_dir: User-provided output directory (relative or absolute)
+        fallback_to_tmp: If True, fallback to /tmp if output_dir not writable
+        create_if_missing: If True, create directory if it doesn't exist
+
+    Returns:
+        Absolute path to writable output directory
+
+    Raises:
+        PermissionError: If no writable path can be found (when fallback disabled)
+
+    Examples:
+        >>> # Relative path (resolved against cwd)
+        >>> path = get_safe_output_path("./outputs")
+        >>> # Returns: <cwd>/outputs
+
+        >>> # Absolute path
+        >>> path = get_safe_output_path("/tmp/my_outputs")
+        >>> # Returns: /tmp/my_outputs
+
+        >>> # Read-only path with fallback
+        >>> path = get_safe_output_path("/outputs")
+        >>> # Returns: /tmp/chatspatial/outputs (with warning)
+    """
+    # Convert to Path object
+    user_path = Path(output_dir)
+
+    # If absolute path, use directly; otherwise resolve against CWD
+    if user_path.is_absolute():
+        target_path = user_path
+    else:
+        # For relative paths, resolve against CWD (respects user configuration!)
+        # This follows standard Unix/Python conventions
+        target_path = Path.cwd() / user_path
+
+    # Try to create/verify the directory
+    try:
+        if create_if_missing:
+            target_path.mkdir(parents=True, exist_ok=True)
+
+        # Test write permission by creating a temporary test file
+        test_file = target_path / ".write_test"
+        test_file.touch()
+        test_file.unlink()
+
+        return target_path
+
+    except (OSError, PermissionError) as e:
+        # If fallback enabled, try temp directory
+        if fallback_to_tmp:
+            warnings.warn(
+                f"Cannot write to {target_path}: {e}. "
+                f"Falling back to /tmp/chatspatial/outputs",
+                UserWarning,
+                stacklevel=2,
+            )
+
+            fallback_path = Path("/tmp/chatspatial/outputs")
+            fallback_path.mkdir(parents=True, exist_ok=True)
+            return fallback_path
+        else:
+            raise PermissionError(
+                f"Cannot write to output directory: {target_path}. " f"Error: {e}"
+            ) from e
+
+
+def is_safe_output_path(path: Path) -> bool:
+    """Check if output path is safe (within project or /tmp).
+
+    This provides security by ensuring files are only written to:
+    1. Project directory or its subdirectories
+    2. /tmp/chatspatial directory
+
+    Args:
+        path: Path to check
+
+    Returns:
+        True if path is safe for output, False otherwise
+
+    Examples:
+        >>> # Safe paths
+        >>> is_safe_output_path(Path("/Users/.../chatspatial/outputs"))
+        True
+        >>> is_safe_output_path(Path("/tmp/chatspatial/outputs"))
+        True
+
+        >>> # Unsafe paths
+        >>> is_safe_output_path(Path("/etc/outputs"))
+        False
+        >>> is_safe_output_path(Path("/Users/other_user/outputs"))
+        False
+    """
+    # Normalize path to absolute
+    abs_path = path.resolve() if not path.is_absolute() else path
+
+    project_root = get_project_root()
+    tmp_root = Path("/tmp/chatspatial")
+
+    # Allow paths within project directory
+    try:
+        abs_path.relative_to(project_root)
+        return True
+    except ValueError:
+        pass
+
+    # Allow paths within /tmp/chatspatial
+    try:
+        abs_path.relative_to(tmp_root)
+        return True
+    except ValueError:
+        pass
+
+    # Disallow all other paths
+    return False
+
+
+def get_output_dir_from_config(default: str = "./outputs") -> str:
+    """Get output directory from environment variable or configuration.
+
+    Priority order:
+    1. CHATSPATIAL_OUTPUT_DIR environment variable (highest priority)
+    2. Default value (usually "./outputs")
+
+    This allows users to configure the output directory via:
+    - Claude Desktop config: env.CHATSPATIAL_OUTPUT_DIR
+    - Shell environment: export CHATSPATIAL_OUTPUT_DIR=/path/to/outputs
+
+    Args:
+        default: Default output directory if no configuration found
+
+    Returns:
+        Output directory path (relative or absolute)
+
+    Examples:
+        >>> # With environment variable set
+        >>> os.environ["CHATSPATIAL_OUTPUT_DIR"] = "/tmp/results"
+        >>> get_output_dir_from_config()
+        '/tmp/results'
+
+        >>> # Without environment variable
+        >>> get_output_dir_from_config()
+        './outputs'
+
+    Configuration example for Claude Desktop (claude_desktop_config.json):
+    ```json
+    {
+      "mcpServers": {
+        "chatspatial": {
+          "command": "python",
+          "args": ["-m", "chatspatial"],
+          "cwd": "/Users/username/my_project",
+          "env": {
+            "CHATSPATIAL_OUTPUT_DIR": "./results"
+          }
+        }
+      }
+    }
+    ```
+    """
+    # Check environment variable (highest priority)
+    if env_dir := os.getenv("CHATSPATIAL_OUTPUT_DIR"):
+        return env_dir
+
+    # Return default
+    return default
+
+
+def resolve_output_path(
+    output_dir: str,
+    default_dir: str = "./outputs",
+) -> Path:
+    """Resolve output directory path safely.
+
+    Resolves relative paths against current working directory,
+    following standard Unix/Python conventions.
+
+    Args:
+        output_dir: User-provided output directory
+        default_dir: Default directory if output_dir is None
+
+    Returns:
+        Resolved absolute path
+
+    Examples:
+        >>> resolve_output_path("./outputs")
+        PosixPath('<cwd>/outputs')
+
+        >>> resolve_output_path("/tmp/test")
+        PosixPath('/tmp/test')
+    """
+    path = Path(output_dir or default_dir)
+
+    if path.is_absolute():
+        return path
+    else:
+        # Resolve against CWD (respects user configuration)
+        return Path.cwd() / path

chatspatial/utils/persistence.py

@@ -0,0 +1,78 @@
+"""
+Data persistence utilities for spatial transcriptomics data.
+
+Handles saving AnnData objects to disk with proper path management.
+"""
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from anndata import AnnData
+
+
+def get_save_path(data_id: str, original_path: str) -> Path:
+    """
+    Get save path for adata, supports environment variable configuration.
+
+    Priority:
+    1. CHATSPATIAL_DATA_DIR environment variable
+    2. .chatspatial_saved/ directory next to original data (default)
+
+    Args:
+        data_id: Dataset identifier
+        original_path: Original data file path
+
+    Returns:
+        Directory path for saving
+    """
+    env_dir = os.getenv("CHATSPATIAL_DATA_DIR")
+    if env_dir:
+        save_dir = Path(env_dir)
+        save_dir.mkdir(parents=True, exist_ok=True)
+        return save_dir
+
+    # Default: use directory next to original data
+    path_obj = Path(original_path)
+
+    # Determine parent directory based on whether path looks like a file
+    # Check if path has a file extension or ends with a known data format
+    if path_obj.suffix in [".h5ad", ".h5", ".csv", ".txt", ".mtx", ".gz"]:
+        # It's a file path, use parent directory
+        parent_dir = path_obj.parent
+    elif path_obj.is_dir():
+        # It's an existing directory
+        parent_dir = path_obj
+    else:
+        # Assume it's a file path (even if doesn't exist yet)
+        parent_dir = path_obj.parent
+
+    save_dir = parent_dir / ".chatspatial_saved"
+    save_dir.mkdir(parents=True, exist_ok=True)
+    return save_dir
+
+
+def save_adata(data_id: str, adata: "AnnData", original_path: str) -> Path:
+    """
+    Save AnnData object to disk.
+
+    Args:
+        data_id: Dataset identifier
+        adata: AnnData object to save
+        original_path: Original data file path
+
+    Returns:
+        Path where data was saved
+
+    Raises:
+        IOError: If save fails
+    """
+    save_dir = get_save_path(data_id, original_path)
+    save_path = save_dir / f"{data_id}.h5ad"
+
+    try:
+        adata.write_h5ad(save_path, compression="gzip", compression_opts=4)
+        return save_path
+    except Exception as e:
+        raise IOError(f"Failed to save data to {save_path}: {e}") from e

chatspatial/utils/scipy_compat.py

@@ -0,0 +1,143 @@
+"""
+Scipy compatibility layer for deprecated functions.
+
+This module provides compatibility shims for scipy functions that have been
+removed or relocated in newer versions, enabling packages like SpatialDE
+that depend on these deprecated APIs to work with modern scipy (>=1.14).
+
+Background:
+    - scipy.misc.derivative was deprecated in scipy 1.10.0
+    - scipy.misc.derivative was removed in scipy 1.14.0
+    - SpatialDE 1.1.3 still imports from scipy.misc.derivative
+    - This module patches scipy.misc to restore the derivative function
+
+Usage:
+    Call `patch_scipy_misc_derivative()` before importing SpatialDE:
+
+        from chatspatial.utils.scipy_compat import patch_scipy_misc_derivative
+        patch_scipy_misc_derivative()
+        import SpatialDE  # Now works with scipy >= 1.14
+"""
+
+import numpy as np
+from scipy import misc as scipy_misc
+
+
+def _derivative_compat(func, x0, dx=1.0, n=1, args=(), order=3):
+    """Compute the nth derivative of a function at a point.
+
+    This is a compatibility implementation of the deprecated scipy.misc.derivative,
+    using central difference formulas.
+
+    Parameters
+    ----------
+    func : callable
+        Function of which to compute the derivative. Should accept a single
+        float argument and return a float.
+    x0 : float
+        Point at which to evaluate the derivative.
+    dx : float, optional
+        Spacing for finite difference. Default is 1.0.
+    n : int, optional
+        Order of the derivative. Default is 1.
+    args : tuple, optional
+        Extra arguments to pass to func.
+    order : int, optional
+        Number of points to use for the central difference formula.
+        Must be odd. Default is 3.
+
+    Returns
+    -------
+    float
+        The nth derivative of func at x0.
+
+    Notes
+    -----
+    This implementation uses central difference formulas. The accuracy
+    depends on the `order` parameter and the smoothness of the function.
+
+    For SpatialDE, only n=1 and n=2 are used with default dx=1.0 and order=3.
+    """
+    if order < n + 1:
+        raise ValueError(
+            f"'order' ({order}) must be at least the derivative order 'n' ({n}) plus 1"
+        )
+    if order % 2 == 0:
+        raise ValueError(f"'order' ({order}) must be odd")
+
+    # Central difference weights for various orders and derivative degrees
+    # These are the standard finite difference coefficients
+    # Reference: https://en.wikipedia.org/wiki/Finite_difference_coefficient
+
+    # For simplicity, we implement the most common cases used by SpatialDE
+    # First derivative using central difference (3-point formula)
+    if n == 1 and order >= 3:
+        # f'(x) ≈ (f(x+h) - f(x-h)) / (2h)
+        return (func(x0 + dx, *args) - func(x0 - dx, *args)) / (2 * dx)
+    # Second derivative using central difference (3-point formula)
+    elif n == 2 and order >= 3:
+        # f''(x) ≈ (f(x+h) - 2f(x) + f(x-h)) / h²
+        return (
+            func(x0 + dx, *args) - 2 * func(x0, *args) + func(x0 - dx, *args)
+        ) / (dx**2)
+
+    # For higher derivatives or orders, use Richardson extrapolation
+    # This is a more general but slower approach
+    return _derivative_richardson(func, x0, dx, n, args, order)
+
+
+def _derivative_richardson(func, x0, dx, n, args, order):
+    """Compute derivative using Richardson extrapolation.
+
+    This is a more general implementation that handles arbitrary
+    derivative orders using Richardson extrapolation for improved accuracy.
+    """
+    # Number of points for central difference
+    num_points = order
+
+    # Generate sample points symmetrically around x0
+    half = num_points // 2
+    points = np.arange(-half, half + 1) * dx + x0
+
+    # Evaluate function at all points
+    f_values = np.array([func(p, *args) for p in points])
+
+    # Compute derivative using finite differences
+    # For nth derivative, we need to apply the difference operator n times
+    result = f_values.copy()
+    for _ in range(n):
+        result = np.diff(result) / dx
+
+    # Return the central value
+    return result[len(result) // 2]
+
+
+def patch_scipy_misc_derivative():
+    """Patch scipy.misc to include the deprecated derivative function.
+
+    This function adds a `derivative` attribute to `scipy.misc` module,
+    allowing packages like SpatialDE that import `from scipy.misc import derivative`
+    to work with scipy >= 1.14.
+
+    This patch is idempotent - calling it multiple times has no additional effect.
+
+    Example
+    -------
+    >>> from chatspatial.utils.scipy_compat import patch_scipy_misc_derivative
+    >>> patch_scipy_misc_derivative()
+    >>> import SpatialDE  # Now works!
+    """
+    if not hasattr(scipy_misc, 'derivative'):
+        scipy_misc.derivative = _derivative_compat
+
+
+# Auto-check: provide helpful message if scipy already has derivative
+def check_scipy_derivative_status():
+    """Check the status of scipy.misc.derivative and return diagnostic info."""
+    import scipy
+    has_derivative = hasattr(scipy_misc, 'derivative')
+    return {
+        'scipy_version': scipy.__version__,
+        'has_derivative': has_derivative,
+        'needs_patch': not has_derivative,
+    }

chatspatial-1.1.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: chatspatial
+Version: 1.1.0
+Summary: ChatSpatial: Natural language-driven spatial transcriptomics analysis via Model Context Protocol (MCP) integration
+Author-email: Chen Yang <cafferychen777@tamu.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/cafferychen777/ChatSpatial
+Project-URL: Documentation, https://chatspatial.readthedocs.io
+Project-URL: Repository, https://github.com/cafferychen777/ChatSpatial
+Project-URL: Issues, https://github.com/cafferychen777/ChatSpatial/issues
+Keywords: spatial-transcriptomics,single-cell,mcp,llm,bioinformatics,scanpy,squidpy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.14,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.17.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: seaborn>=0.11.0
+Requires-Dist: Pillow>=8.0.0
+Requires-Dist: scanpy<2.0,>=1.9.0
+Requires-Dist: anndata>=0.11.0
+Requires-Dist: squidpy>=1.2.0
+Requires-Dist: umap-learn>=0.5.0
+Requires-Dist: igraph>=0.9.0
+Requires-Dist: leidenalg>=0.8.0
+Requires-Dist: pydantic<3.0,>=2.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: scvi-tools<2.0,>=1.0.0
+Requires-Dist: mudata>=0.2.0
+Requires-Dist: scvelo>=0.2.5
+Requires-Dist: liana
+Requires-Dist: cellphonedb<6.0,>=5.0.0
+Requires-Dist: ktplotspy>=0.3.0
+Requires-Dist: fastccc>=0.1.0
+Requires-Dist: harmonypy>=0.0.9
+Requires-Dist: bbknn>=1.5.0
+Requires-Dist: esda>=2.4.0
+Requires-Dist: libpysal>=4.6.0
+Requires-Dist: gseapy>=1.0.0
+Requires-Dist: flashdeconv>=0.1.0
+Provides-Extra: full
+Requires-Dist: torch<3.0,>=2.0.0; extra == "full"
+Requires-Dist: SpaGCN<2.0,>=1.2.5; extra == "full"
+Requires-Dist: GraphST>=1.1.0; extra == "full"
+Requires-Dist: cell2location>=0.1.4; extra == "full"
+Requires-Dist: cellrank<3.0,>=2.0.0; extra == "full"
+Requires-Dist: palantir>=1.0.0; extra == "full"
+Requires-Dist: petsc4py<4.0,>=3.18.0; sys_platform != "win32" and extra == "full"
+Requires-Dist: slepc4py<4.0,>=3.18.0; sys_platform != "win32" and extra == "full"
+Requires-Dist: scanorama>=1.7.0; extra == "full"
+Requires-Dist: spatialde>=1.1.3; extra == "full"
+Requires-Dist: scikit-misc>=0.5.0; extra == "full"
+Requires-Dist: tangram-sc>=1.0.0; extra == "full"
+Requires-Dist: singler>=0.4.0; sys_platform != "win32" and extra == "full"
+Requires-Dist: singlecellexperiment>=0.4.0; sys_platform != "win32" and extra == "full"
+Requires-Dist: celldex>=0.3.0; sys_platform != "win32" and extra == "full"
+Requires-Dist: mllmcelltype>=0.1.0; extra == "full"
+Requires-Dist: rpy2<3.7,>=3.5.0; extra == "full"
+Requires-Dist: anndata2ri>=1.3.0; extra == "full"
+Requires-Dist: pysal>=2.6.0; extra == "full"
+Requires-Dist: statsmodels>=0.13.0; extra == "full"
+Requires-Dist: networkx>=2.6.0; extra == "full"
+Requires-Dist: POT>=0.9.0; extra == "full"
+Requires-Dist: paste-bio>=1.0.0; extra == "full"
+Requires-Dist: infercnvpy>=0.4.0; extra == "full"
+Requires-Dist: pydeseq2>=0.4.0; extra == "full"
+Requires-Dist: enrichmap; extra == "full"
+Requires-Dist: statannotations>=0.2.0; extra == "full"
+Requires-Dist: pygam>=0.8.0; extra == "full"
+Requires-Dist: scikit-gstat>=1.0.0; extra == "full"
+Requires-Dist: adjustText>=0.8.0; extra == "full"
+Requires-Dist: splot>=1.1.0; extra == "full"
+Requires-Dist: spatialdata>=0.2.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0,>=0.23.0; extra == "dev"
+Requires-Dist: black<26.0,>=22.0.0; extra == "dev"
+Requires-Dist: mypy<2.0,>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: pre-commit<5.0,>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# ChatSpatial
+
+**MCP server for spatial transcriptomics analysis via natural language**
+
+[![PyPI](https://img.shields.io/pypi/v/chatspatial)](https://pypi.org/project/chatspatial/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-available-blue)](https://cafferychen777.github.io/ChatSpatial/)
+
+</div>
+
+---
+
+<table>
+<tr>
+<td width="50%">
+
+### ❌ Before
+```python
+import scanpy as sc
+import squidpy as sq
+adata = sc.read_h5ad("data.h5ad")
+sc.pp.filter_cells(adata, min_genes=200)
+sc.pp.normalize_total(adata)
+sc.pp.log1p(adata)
+sc.pp.highly_variable_genes(adata)
+sc.tl.pca(adata)
+sc.pp.neighbors(adata)
+# ... 40 more lines
+```
+
+</td>
+<td width="50%">
+
+### ✅ After
+```text
+"Load my Visium data and identify
+ spatial domains"
+```
+
+```
+✓ Loaded 3,456 spots, 18,078 genes
+✓ Identified 7 spatial domains
+✓ Generated visualization
+```
+
+</td>
+</tr>
+</table>
+
+---
+
+## Install
+
+```bash
+pip install chatspatial
+```
+
+## Configure
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chatspatial": {
+      "command": "python",
+      "args": ["-m", "chatspatial", "server"]
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```bash
+claude mcp add chatspatial python -- -m chatspatial server
+```
+
+> Restart Claude after configuration.
+
+---
+
+## Use
+
+Open Claude and chat:
+
+```text
+Load /path/to/spatial_data.h5ad and show me the tissue structure
+```
+
+```text
+Identify spatial domains using SpaGCN
+```
+
+```text
+Find spatially variable genes and create a heatmap
+```
+
+---
+
+## Capabilities
+
+| Category | Methods |
+|----------|---------|
+| **Spatial Domains** | SpaGCN, STAGATE, Leiden |
+| **Deconvolution** | Cell2location, RCTD, Tangram, SPOTlight |
+| **Cell Communication** | LIANA+, CellPhoneDB |
+| **Cell Type Annotation** | Tangram, scANVI, CellAssign, mLLMCelltype |
+| **Trajectory** | CellRank, Palantir, scVelo |
+| **Spatial Statistics** | Moran's I, Getis-Ord Gi*, Ripley's K |
+| **Gene Set Enrichment** | GSEA, ORA, Enrichr |
+
+**60+ methods** across 12 categories. **Supports** 10x Visium, Xenium, Slide-seq v2, MERFISH, seqFISH.
+
+---
+
+## Docs
+
+- [Installation Guide](INSTALLATION.md) — detailed setup for all platforms
+- [Examples](docs/examples/) — step-by-step workflows
+- [Full Documentation](https://cafferychen777.github.io/ChatSpatial/) — complete reference
+
+---
+
+## Citation
+
+```bibtex
+@software{chatspatial2025,
+  title={ChatSpatial: Agentic Workflow for Spatial Transcriptomics},
+  author={Chen Yang and Xianyang Zhang and Jun Chen},
+  year={2025},
+  url={https://github.com/cafferychen777/ChatSpatial}
+}
+```
+
+<div align="center">
+
+**MIT License** · [GitHub](https://github.com/cafferychen777/ChatSpatial) · [Issues](https://github.com/cafferychen777/ChatSpatial/issues)
+
+</div>
+
+<!-- mcp-name: io.github.cafferychen777/chatspatial -->