scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/_mcp_tools/introspect.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+# Timestamp: 2025-01-20
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_tools/introspect.py
+
+"""Introspection module tools for FastMCP unified server."""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+
+def _json(data: dict) -> str:
+    return json.dumps(data, indent=2, default=str)
+
+
+def register_introspect_tools(mcp) -> None:
+    """Register introspection tools with FastMCP server."""
+
+    @mcp.tool()
+    async def introspect_signature(
+        dotted_path: str,
+        include_defaults: bool = True,
+        include_annotations: bool = True,
+    ) -> str:
+        """[introspect] Get function/class signature (like IPython's func?)."""
+        from scitex.introspect._mcp.handlers import signature_handler
+
+        result = await signature_handler(
+            dotted_path=dotted_path,
+            include_defaults=include_defaults,
+            include_annotations=include_annotations,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_docstring(
+        dotted_path: str,
+        format: str = "raw",
+    ) -> str:
+        """[introspect] Get docstring of a Python object. format: raw|parsed|summary."""
+        from scitex.introspect._mcp.handlers import docstring_handler
+
+        result = await docstring_handler(
+            dotted_path=dotted_path,
+            format=format,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_source(
+        dotted_path: str,
+        max_lines: Optional[int] = None,
+        include_decorators: bool = True,
+    ) -> str:
+        """[introspect] Get source code of a Python object (like IPython's func??)."""
+        from scitex.introspect._mcp.handlers import source_handler
+
+        result = await source_handler(
+            dotted_path=dotted_path,
+            max_lines=max_lines,
+            include_decorators=include_decorators,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_members(
+        dotted_path: str,
+        filter: str = "public",
+        kind: Optional[str] = None,
+        include_inherited: bool = False,
+    ) -> str:
+        """[introspect] List members of module/class (like dir()). filter: all|public|private|dunder."""
+        from scitex.introspect._mcp.handlers import members_handler
+
+        result = await members_handler(
+            dotted_path=dotted_path,
+            filter=filter,
+            kind=kind,
+            include_inherited=include_inherited,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_exports(dotted_path: str) -> str:
+        """[introspect] Get __all__ exports of a module."""
+        from scitex.introspect._mcp.handlers import exports_handler
+
+        result = await exports_handler(dotted_path=dotted_path)
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_examples(
+        dotted_path: str,
+        search_paths: Optional[str] = None,
+        max_results: int = 10,
+    ) -> str:
+        """[introspect] Find usage examples in tests/examples directories."""
+        from scitex.introspect._mcp.handlers import examples_handler
+
+        # Parse search_paths if provided as comma-separated string
+        paths_list = None
+        if search_paths:
+            paths_list = [p.strip() for p in search_paths.split(",")]
+
+        result = await examples_handler(
+            dotted_path=dotted_path,
+            search_paths=paths_list,
+            max_results=max_results,
+        )
+        return _json(result)
+
+    # Advanced introspection tools
+
+    @mcp.tool()
+    async def introspect_class_hierarchy(
+        dotted_path: str,
+        include_builtins: bool = False,
+        max_depth: int = 10,
+    ) -> str:
+        """[introspect] Get class inheritance hierarchy (MRO + subclasses)."""
+        from scitex.introspect._mcp.handlers import class_hierarchy_handler
+
+        result = await class_hierarchy_handler(
+            dotted_path=dotted_path,
+            include_builtins=include_builtins,
+            max_depth=max_depth,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_type_hints(
+        dotted_path: str,
+        include_extras: bool = True,
+    ) -> str:
+        """[introspect] Get detailed type hint analysis for function/class."""
+        from scitex.introspect._mcp.handlers import type_hints_handler
+
+        result = await type_hints_handler(
+            dotted_path=dotted_path,
+            include_extras=include_extras,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_imports(
+        dotted_path: str,
+        categorize: bool = True,
+    ) -> str:
+        """[introspect] Get all imports from a module (AST-based static analysis)."""
+        from scitex.introspect._mcp.handlers import imports_handler
+
+        result = await imports_handler(
+            dotted_path=dotted_path,
+            categorize=categorize,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_dependencies(
+        dotted_path: str,
+        recursive: bool = False,
+        max_depth: int = 3,
+    ) -> str:
+        """[introspect] Get module dependencies (what it imports)."""
+        from scitex.introspect._mcp.handlers import dependencies_handler
+
+        result = await dependencies_handler(
+            dotted_path=dotted_path,
+            recursive=recursive,
+            max_depth=max_depth,
+        )
+        return _json(result)
+
+    @mcp.tool()
+    async def introspect_call_graph(
+        dotted_path: str,
+        max_depth: int = 2,
+        timeout_seconds: int = 10,
+        internal_only: bool = True,
+    ) -> str:
+        """[introspect] Get function call graph (with timeout protection)."""
+        from scitex.introspect._mcp.handlers import call_graph_handler
+
+        result = await call_graph_handler(
+            dotted_path=dotted_path,
+            max_depth=max_depth,
+            timeout_seconds=timeout_seconds,
+            internal_only=internal_only,
+        )
+        return _json(result)

scitex/_mcp_tools/plt.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-24
+# File: /home/ywatanabe/proj/scitex-code/src/scitex/_mcp_tools/plt.py
+"""Plt module tools for FastMCP unified server.
+
+This module delegates to figrecipe's MCP tools for single source of truth.
+All plt_* tools are thin wrappers around figrecipe's canonical implementation.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def register_plt_tools(mcp) -> None:
+    """Register plt tools with FastMCP server.
+
+    Delegates to figrecipe's plt tools (canonical source).
+    Tools are prefixed with 'plt_' for scitex namespace consistency.
+    """
+    # Ensure branding is set before any figrecipe imports
+    os.environ.setdefault("FIGRECIPE_BRAND", "scitex.plt")
+    os.environ.setdefault("FIGRECIPE_ALIAS", "plt")
+
+    # Check if figrecipe is available
+    try:
+        from figrecipe._mcp import server as fr_mcp
+
+        # Access underlying functions from FunctionTool objects
+        _plot = fr_mcp.plot.fn
+        _reproduce = fr_mcp.reproduce.fn
+        _compose = fr_mcp.compose.fn
+        _info = fr_mcp.info.fn
+        _validate = fr_mcp.validate.fn
+        _crop = fr_mcp.crop.fn
+        _extract_data = fr_mcp.extract_data.fn
+        _list_styles = fr_mcp.list_styles.fn
+        _get_plot_types = fr_mcp.get_plot_types.fn
+
+        _FIGRECIPE_AVAILABLE = True
+    except ImportError:
+        _FIGRECIPE_AVAILABLE = False
+
+    if not _FIGRECIPE_AVAILABLE:
+
+        @mcp.tool()
+        def plt_not_available() -> str:
+            """[plt] figrecipe not installed."""
+            return "figrecipe is required for plt tools. Install with: pip install figrecipe"
+
+        return
+
+    # Delegate to figrecipe's MCP tools with plt_ prefix
+    # Each wrapper simply calls the figrecipe function
+
+
+    @mcp.tool()
+    def plt_plot(
+        spec: Dict[str, Any],
+        output_path: str,
+        dpi: int = 300,
+        save_recipe: bool = True,
+    ) -> Dict[str, Any]:
+        """[plt] Create a matplotlib figure from a declarative specification.
+
+        See figrecipe._api._plot module docstring for full spec format.
+
+        Parameters
+        ----------
+        spec : dict
+            Declarative specification. Key sections: figure, plots, stat_annotations,
+            xlabel, ylabel, title, legend, xlim, ylim.
+        output_path : str
+            Path to save the output figure.
+        dpi : int
+            DPI for raster output (default: 300).
+        save_recipe : bool
+            If True, also save as figrecipe YAML recipe.
+
+        Returns
+        -------
+        dict
+            Result with 'image_path' and 'recipe_path'.
+
+        Raises
+        ------
+        ValueError
+            If no plots are specified or data is missing.
+        """
+        return _plot(spec, output_path, dpi, save_recipe)
+
+    @mcp.tool()
+    def plt_reproduce(
+        recipe_path: str,
+        output_path: Optional[str] = None,
+        format: str = "png",
+        dpi: int = 300,
+    ) -> Dict[str, Any]:
+        """[plt] Reproduce a figure from a saved YAML recipe.
+
+        Parameters
+        ----------
+        recipe_path : str
+            Path to the .yaml recipe file.
+
+        output_path : str, optional
+            Output path for the reproduced figure.
+            Defaults to recipe_path with .reproduced.{format} suffix.
+
+        format : str
+            Output format: png, pdf, or svg.
+
+        dpi : int
+            DPI for raster output.
+
+        Returns
+        -------
+        dict
+            Result with 'output_path' and 'success'.
+        """
+        return _reproduce(recipe_path, output_path, format, dpi)
+
+    @mcp.tool()
+    def plt_compose(
+        sources: List[str],
+        output_path: str,
+        layout: str = "horizontal",
+        gap_mm: float = 5.0,
+        dpi: int = 300,
+        panel_labels: bool = True,
+        label_style: str = "uppercase",
+        caption: Optional[str] = None,
+        create_symlinks: bool = True,
+        canvas_size_mm: Optional[Tuple[float, float]] = None,
+        facecolor: str = "white",
+    ) -> Dict[str, Any]:
+        """[plt] Compose multiple figures into a single figure with panel labels.
+
+        Supports two modes:
+        1. Grid-based layout (list sources): automatic arrangement with layout parameter
+        2. Free-form positioning (dict sources): precise mm-based positioning
+
+        Parameters
+        ----------
+        sources : list of str or dict
+            Either:
+            - List of paths to source images or recipe files (grid-based layout)
+            - Dict mapping source paths to positioning specs with 'xy_mm' and 'size_mm':
+              {"panel_a.yaml": {"xy_mm": [0, 0], "size_mm": [80, 50]}, ...}
+        output_path : str
+            Path to save the composed figure.
+        layout : str
+            Layout mode for list sources: 'horizontal', 'vertical', or 'grid'.
+            Ignored when using dict sources with mm positioning.
+        gap_mm : float
+            Gap between panels in millimeters (for grid-based layout only).
+        dpi : int
+            DPI for output.
+        panel_labels : bool
+            If True, add panel labels (A, B, C, D) automatically.
+        label_style : str
+            Style: 'uppercase' (A,B,C), 'lowercase' (a,b,c), 'numeric' (1,2,3).
+        caption : str, optional
+            Figure caption to add below.
+        create_symlinks : bool
+            If True (default), create symlinks to source files for traceability.
+        canvas_size_mm : tuple of (float, float), optional
+            Canvas size as (width_mm, height_mm) for free-form positioning.
+            Required when sources is a dict with mm positioning.
+        facecolor : str
+            Background color for the composed figure. Default is 'white'.
+            All source panels are flattened onto this background to ensure
+            consistent appearance regardless of original panel transparency.
+
+        Returns
+        -------
+        dict
+            Result with 'output_path', 'success', and 'sources_dir' (if symlinks created).
+        """
+        return _compose(
+            sources,
+            output_path,
+            layout,
+            gap_mm,
+            dpi,
+            panel_labels,
+            label_style,
+            caption,
+            create_symlinks,
+            canvas_size_mm,
+            facecolor,
+        )
+
+    @mcp.tool()
+    def plt_info(recipe_path: str, verbose: bool = False) -> Dict[str, Any]:
+        """[plt] Get information about a recipe file.
+
+        Parameters
+        ----------
+        recipe_path : str
+            Path to the .yaml recipe file.
+
+        verbose : bool
+            If True, include detailed call information.
+
+        Returns
+        -------
+        dict
+            Recipe information including figure dimensions, call counts, etc.
+        """
+        return _info(recipe_path, verbose)
+
+    @mcp.tool()
+    def plt_validate(
+        recipe_path: str,
+        mse_threshold: float = 100.0,
+    ) -> Dict[str, Any]:
+        """[plt] Validate that a recipe can reproduce its original figure.
+
+        Parameters
+        ----------
+        recipe_path : str
+            Path to the .yaml recipe file.
+
+        mse_threshold : float
+            Maximum acceptable mean squared error (default: 100).
+
+        Returns
+        -------
+        dict
+            Validation result with 'passed', 'mse', and details.
+        """
+        return _validate(recipe_path, mse_threshold)
+
+    @mcp.tool()
+    def plt_crop(
+        input_path: str,
+        output_path: Optional[str] = None,
+        margin_mm: float = 1.0,
+        overwrite: bool = False,
+    ) -> Dict[str, Any]:
+        """[plt] Crop whitespace from a figure image.
+
+        Parameters
+        ----------
+        input_path : str
+            Path to the input image.
+
+        output_path : str, optional
+            Path for cropped output. Defaults to input with .cropped suffix.
+
+        margin_mm : float
+            Margin to keep around content in millimeters.
+
+        overwrite : bool
+            If True, overwrite the input file.
+
+        Returns
+        -------
+        dict
+            Result with 'output_path' and 'success'.
+        """
+        return _crop(input_path, output_path, margin_mm, overwrite)
+
+    @mcp.tool()
+    def plt_extract_data(recipe_path: str) -> Dict[str, Dict[str, Any]]:
+        """[plt] Extract plotted data arrays from a saved recipe.
+
+        Parameters
+        ----------
+        recipe_path : str
+            Path to the .yaml recipe file.
+
+        Returns
+        -------
+        dict
+            Nested dict: {call_id: {'x': list, 'y': list, ...}}
+        """
+        return _extract_data(recipe_path)
+
+    @mcp.tool()
+    def plt_list_styles() -> Dict[str, Any]:
+        """[plt] List available figure style presets.
+
+        Returns
+        -------
+        dict
+            Dictionary with 'presets' list of available style names.
+        """
+        return _list_styles()
+
+    @mcp.tool()
+    def plt_get_plot_types() -> Dict[str, Any]:
+        """[plt] Get list of supported plot types.
+
+        Returns
+        -------
+        dict
+            Dictionary with 'plot_types' and their descriptions.
+        """
+        return _get_plot_types()
+
+
+# EOF