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

scitex/diagram/_mcp_handlers.py

@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-08
+# File: src/scitex/diagram/_mcp_handlers.py
+# ----------------------------------------
+
+"""
+MCP Handler implementations for SciTeX diagram module.
+
+Provides async handlers for paper-optimized diagram generation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Optional
+
+
+async def create_diagram_handler(
+    spec_path: Optional[str] = None,
+    spec_dict: Optional[dict] = None,
+) -> dict:
+    """
+    Create a diagram from specification.
+
+    Parameters
+    ----------
+    spec_path : str, optional
+        Path to YAML spec file
+    spec_dict : dict, optional
+        Spec as dictionary
+
+    Returns
+    -------
+    dict
+        Success status and diagram info
+    """
+    try:
+        from scitex.diagram import Diagram
+
+        if spec_path:
+            loop = asyncio.get_event_loop()
+            diagram = await loop.run_in_executor(
+                None,
+                lambda: Diagram.from_yaml(spec_path),
+            )
+        elif spec_dict:
+            diagram = Diagram(spec_dict)
+        else:
+            return {
+                "success": False,
+                "error": "Either spec_path or spec_dict must be provided",
+            }
+
+        # Get diagram info
+        spec = diagram.spec if hasattr(diagram, "spec") else {}
+
+        return {
+            "success": True,
+            "diagram_type": spec.get("type", "unknown"),
+            "node_count": len(spec.get("nodes", [])),
+            "edge_count": len(spec.get("edges", [])),
+            "message": "Diagram created successfully",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def compile_mermaid_handler(
+    spec_path: Optional[str] = None,
+    output_path: Optional[str] = None,
+    spec_dict: Optional[dict] = None,
+) -> dict:
+    """
+    Compile diagram to Mermaid format.
+
+    Parameters
+    ----------
+    spec_path : str, optional
+        Path to YAML spec file
+    output_path : str, optional
+        Output .mmd file path
+    spec_dict : dict, optional
+        Spec as dictionary
+
+    Returns
+    -------
+    dict
+        Success status and Mermaid output
+    """
+    try:
+        from scitex.diagram import Diagram, compile_to_mermaid
+
+        if spec_path:
+            loop = asyncio.get_event_loop()
+            diagram = await loop.run_in_executor(
+                None,
+                lambda: Diagram.from_yaml(spec_path),
+            )
+        elif spec_dict:
+            diagram = Diagram(spec_dict)
+        else:
+            return {
+                "success": False,
+                "error": "Either spec_path or spec_dict must be provided",
+            }
+
+        # Compile to Mermaid
+        loop = asyncio.get_event_loop()
+        mermaid_code = await loop.run_in_executor(
+            None,
+            lambda: compile_to_mermaid(diagram.spec),
+        )
+
+        # Save if output path provided
+        if output_path:
+            from pathlib import Path
+
+            Path(output_path).write_text(mermaid_code)
+
+        return {
+            "success": True,
+            "mermaid_code": mermaid_code,
+            "output_path": output_path,
+            "message": f"Compiled to Mermaid{f' and saved to {output_path}' if output_path else ''}",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def compile_graphviz_handler(
+    spec_path: Optional[str] = None,
+    output_path: Optional[str] = None,
+    spec_dict: Optional[dict] = None,
+) -> dict:
+    """
+    Compile diagram to Graphviz DOT format.
+
+    Parameters
+    ----------
+    spec_path : str, optional
+        Path to YAML spec file
+    output_path : str, optional
+        Output .dot file path
+    spec_dict : dict, optional
+        Spec as dictionary
+
+    Returns
+    -------
+    dict
+        Success status and DOT output
+    """
+    try:
+        from scitex.diagram import Diagram, compile_to_graphviz
+
+        if spec_path:
+            loop = asyncio.get_event_loop()
+            diagram = await loop.run_in_executor(
+                None,
+                lambda: Diagram.from_yaml(spec_path),
+            )
+        elif spec_dict:
+            diagram = Diagram(spec_dict)
+        else:
+            return {
+                "success": False,
+                "error": "Either spec_path or spec_dict must be provided",
+            }
+
+        # Compile to Graphviz
+        loop = asyncio.get_event_loop()
+        dot_code = await loop.run_in_executor(
+            None,
+            lambda: compile_to_graphviz(diagram.spec),
+        )
+
+        # Save if output path provided
+        if output_path:
+            from pathlib import Path
+
+            Path(output_path).write_text(dot_code)
+
+        return {
+            "success": True,
+            "dot_code": dot_code,
+            "output_path": output_path,
+            "message": f"Compiled to Graphviz{f' and saved to {output_path}' if output_path else ''}",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def list_presets_handler() -> dict:
+    """
+    List available diagram presets.
+
+    Returns
+    -------
+    dict
+        Success status and preset list
+    """
+    try:
+        presets = [
+            {
+                "name": "workflow",
+                "description": "Linear workflow diagrams (step1 → step2 → step3)",
+                "use_case": "Methods section, data processing pipelines",
+                "direction": "left-to-right",
+            },
+            {
+                "name": "decision",
+                "description": "Decision tree/flowchart diagrams",
+                "use_case": "Algorithm flowcharts, decision processes",
+                "direction": "top-to-bottom",
+            },
+            {
+                "name": "pipeline",
+                "description": "Data pipeline with parallel branches",
+                "use_case": "Complex data flows, parallel processing",
+                "direction": "left-to-right",
+            },
+        ]
+
+        return {
+            "success": True,
+            "count": len(presets),
+            "presets": presets,
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def get_preset_handler(preset_name: str) -> dict:
+    """
+    Get a specific preset configuration.
+
+    Parameters
+    ----------
+    preset_name : str
+        Preset name (workflow, decision, pipeline)
+
+    Returns
+    -------
+    dict
+        Success status and preset config
+    """
+    try:
+        from scitex.diagram import DECISION_PRESET, PIPELINE_PRESET, WORKFLOW_PRESET
+
+        presets = {
+            "workflow": WORKFLOW_PRESET,
+            "decision": DECISION_PRESET,
+            "pipeline": PIPELINE_PRESET,
+        }
+
+        if preset_name not in presets:
+            return {
+                "success": False,
+                "error": f"Unknown preset: {preset_name}",
+                "available": list(presets.keys()),
+            }
+
+        preset = presets[preset_name]
+
+        return {
+            "success": True,
+            "preset_name": preset_name,
+            "config": preset,
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def split_diagram_handler(
+    spec_path: str,
+    strategy: str = "horizontal",
+    max_nodes_per_part: int = 10,
+) -> dict:
+    """
+    Split a large diagram into smaller parts.
+
+    Parameters
+    ----------
+    spec_path : str
+        Path to YAML spec file
+    strategy : str
+        Split strategy (horizontal, vertical, semantic)
+    max_nodes_per_part : int
+        Max nodes per part
+
+    Returns
+    -------
+    dict
+        Success status and split results
+    """
+    try:
+        from scitex.diagram import Diagram, SplitConfig, SplitStrategy, split_diagram
+
+        # Map strategy string to enum
+        strategy_map = {
+            "horizontal": SplitStrategy.HORIZONTAL,
+            "vertical": SplitStrategy.VERTICAL,
+            "semantic": SplitStrategy.SEMANTIC,
+        }
+
+        if strategy not in strategy_map:
+            return {
+                "success": False,
+                "error": f"Unknown strategy: {strategy}",
+                "available": list(strategy_map.keys()),
+            }
+
+        loop = asyncio.get_event_loop()
+        diagram = await loop.run_in_executor(
+            None,
+            lambda: Diagram.from_yaml(spec_path),
+        )
+
+        config = SplitConfig(
+            strategy=strategy_map[strategy],
+            max_nodes_per_part=max_nodes_per_part,
+        )
+
+        result = await loop.run_in_executor(
+            None,
+            lambda: split_diagram(diagram.spec, config),
+        )
+
+        return {
+            "success": True,
+            "strategy": strategy,
+            "parts_count": len(result.parts) if hasattr(result, "parts") else 0,
+            "result": str(result),
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+async def get_paper_modes_handler() -> dict:
+    """
+    Get available paper layout modes.
+
+    Returns
+    -------
+    dict
+        Success status and paper modes
+    """
+    try:
+        from scitex.diagram import PaperMode
+
+        modes = []
+        for mode in PaperMode:
+            modes.append(
+                {
+                    "name": mode.name,
+                    "value": mode.value,
+                }
+            )
+
+        return {
+            "success": True,
+            "count": len(modes),
+            "modes": modes,
+            "description": "Paper modes control diagram sizing for publication layouts",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e),
+        }
+
+
+__all__ = [
+    "create_diagram_handler",
+    "compile_mermaid_handler",
+    "compile_graphviz_handler",
+    "list_presets_handler",
+    "get_preset_handler",
+    "split_diagram_handler",
+    "get_paper_modes_handler",
+]
+
+# EOF

scitex/diagram/_mcp_tool_schemas.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-08
+# File: src/scitex/diagram/_mcp_tool_schemas.py
+# ----------------------------------------
+
+"""
+MCP Tool schemas for SciTeX diagram module.
+
+Defines tools for paper-optimized diagram generation:
+- create_diagram: Create diagram from YAML spec
+- compile_mermaid: Export to Mermaid format
+- compile_graphviz: Export to Graphviz DOT format
+- list_presets: List available diagram presets
+- apply_preset: Apply workflow/decision/pipeline preset
+"""
+
+from __future__ import annotations
+
+import mcp.types as types
+
+
+def get_tool_schemas() -> list[types.Tool]:
+    """Return list of available MCP tools for diagram operations."""
+    return [
+        # Create diagram from YAML
+        types.Tool(
+            name="create_diagram",
+            description="Create a diagram from a YAML specification file or dictionary",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "spec_path": {
+                        "type": "string",
+                        "description": "Path to YAML specification file",
+                    },
+                    "spec_dict": {
+                        "type": "object",
+                        "description": "Diagram specification as dictionary (alternative to spec_path)",
+                    },
+                },
+                "required": [],
+            },
+        ),
+        # Compile to Mermaid
+        types.Tool(
+            name="compile_mermaid",
+            description="Compile diagram specification to Mermaid format",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "spec_path": {
+                        "type": "string",
+                        "description": "Path to YAML specification file",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Output file path for .mmd file",
+                    },
+                    "spec_dict": {
+                        "type": "object",
+                        "description": "Diagram specification as dictionary (alternative to spec_path)",
+                    },
+                },
+                "required": [],
+            },
+        ),
+        # Compile to Graphviz
+        types.Tool(
+            name="compile_graphviz",
+            description="Compile diagram specification to Graphviz DOT format",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "spec_path": {
+                        "type": "string",
+                        "description": "Path to YAML specification file",
+                    },
+                    "output_path": {
+                        "type": "string",
+                        "description": "Output file path for .dot file",
+                    },
+                    "spec_dict": {
+                        "type": "object",
+                        "description": "Diagram specification as dictionary (alternative to spec_path)",
+                    },
+                },
+                "required": [],
+            },
+        ),
+        # List presets
+        types.Tool(
+            name="list_presets",
+            description="List available diagram presets (workflow, decision, pipeline)",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "required": [],
+            },
+        ),
+        # Get preset
+        types.Tool(
+            name="get_preset",
+            description="Get a diagram preset configuration by name",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "preset_name": {
+                        "type": "string",
+                        "description": "Preset name",
+                        "enum": ["workflow", "decision", "pipeline"],
+                    },
+                },
+                "required": ["preset_name"],
+            },
+        ),
+        # Split diagram
+        types.Tool(
+            name="split_diagram",
+            description="Split a large diagram into smaller parts for multi-column layouts",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "spec_path": {
+                        "type": "string",
+                        "description": "Path to YAML specification file",
+                    },
+                    "strategy": {
+                        "type": "string",
+                        "description": "Split strategy",
+                        "enum": ["horizontal", "vertical", "semantic"],
+                        "default": "horizontal",
+                    },
+                    "max_nodes_per_part": {
+                        "type": "integer",
+                        "description": "Maximum nodes per split part",
+                        "default": 10,
+                    },
+                },
+                "required": ["spec_path"],
+            },
+        ),
+        # Get paper modes
+        types.Tool(
+            name="get_paper_modes",
+            description="Get available paper layout modes and their constraints",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+                "required": [],
+            },
+        ),
+    ]
+
+
+__all__ = ["get_tool_schemas"]
+
+# EOF

scitex/diagram/mcp_server.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+# Timestamp: 2026-01-08
+# File: src/scitex/diagram/mcp_server.py
+# ----------------------------------------
+
+"""
+MCP Server for SciTeX diagram - Paper-optimized diagram generation.
+
+Provides tools for:
+- Creating diagrams from YAML specs
+- Compiling to Mermaid/Graphviz formats
+- Using workflow/decision/pipeline presets
+- Splitting large diagrams for publication layouts
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+# Graceful MCP dependency handling
+try:
+    import mcp.types as types
+    from mcp.server import NotificationOptions, Server
+    from mcp.server.models import InitializationOptions
+    from mcp.server.stdio import stdio_server
+
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+    types = None  # type: ignore
+    Server = None  # type: ignore
+    NotificationOptions = None  # type: ignore
+    InitializationOptions = None  # type: ignore
+    stdio_server = None  # type: ignore
+
+__all__ = ["DiagramServer", "main", "MCP_AVAILABLE"]
+
+
+class DiagramServer:
+    """MCP Server for Paper-Optimized Diagram Generation."""
+
+    def __init__(self):
+        self.server = Server("scitex-diagram")
+        self.setup_handlers()
+
+    def setup_handlers(self):
+        """Set up MCP server handlers."""
+        from ._mcp_handlers import (
+            compile_graphviz_handler,
+            compile_mermaid_handler,
+            create_diagram_handler,
+            get_paper_modes_handler,
+            get_preset_handler,
+            list_presets_handler,
+            split_diagram_handler,
+        )
+        from ._mcp_tool_schemas import get_tool_schemas
+
+        @self.server.list_tools()
+        async def handle_list_tools():
+            return get_tool_schemas()
+
+        @self.server.call_tool()
+        async def handle_call_tool(name: str, arguments: dict):
+            if name == "create_diagram":
+                return await self._wrap_result(create_diagram_handler(**arguments))
+
+            elif name == "compile_mermaid":
+                return await self._wrap_result(compile_mermaid_handler(**arguments))
+
+            elif name == "compile_graphviz":
+                return await self._wrap_result(compile_graphviz_handler(**arguments))
+
+            elif name == "list_presets":
+                return await self._wrap_result(list_presets_handler())
+
+            elif name == "get_preset":
+                return await self._wrap_result(get_preset_handler(**arguments))
+
+            elif name == "split_diagram":
+                return await self._wrap_result(split_diagram_handler(**arguments))
+
+            elif name == "get_paper_modes":
+                return await self._wrap_result(get_paper_modes_handler())
+
+            else:
+                raise ValueError(f"Unknown tool: {name}")
+
+    async def _wrap_result(self, coro):
+        """Wrap handler result as MCP TextContent."""
+        import json
+
+        try:
+            result = await coro
+            return [
+                types.TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2, default=str),
+                )
+            ]
+        except Exception as e:
+            return [
+                types.TextContent(
+                    type="text",
+                    text=json.dumps({"success": False, "error": str(e)}, indent=2),
+                )
+            ]
+
+
+async def _run_server():
+    """Run the MCP server (internal)."""
+    server = DiagramServer()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="scitex-diagram",
+                server_version="0.1.0",
+                capabilities=server.server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+def main():
+    """Main entry point for the MCP server."""
+    if not MCP_AVAILABLE:
+        import sys
+
+        print("=" * 60)
+        print("MCP Server 'scitex-diagram' requires the 'mcp' package.")
+        print()
+        print("Install with:")
+        print("  pip install mcp")
+        print()
+        print("Or install scitex with MCP support:")
+        print("  pip install scitex[mcp]")
+        print("=" * 60)
+        sys.exit(1)
+
+    asyncio.run(_run_server())
+
+
+if __name__ == "__main__":
+    main()
+
+
+# EOF