mermaid-trace 0.5.3.post0__py3-none-any.whl → 0.6.0.post0__py3-none-any.whl

mermaid_trace/cli.py

@@ -232,7 +232,7 @@ def _create_handler(
     return Handler
 
 
-def serve(filename: str, port: int = 8000) -> None:
+def serve(filename: str, port: int = 8000, master: bool = False) -> None:
     """
     Starts the local HTTP server and file watcher to preview a Mermaid diagram.
 
@@ -249,7 +249,30 @@ def serve(filename: str, port: int = 8000) -> None:
     Args:
         filename (str): The path to the .mmd file to serve.
         port (int): The port number to bind the server to (default: 8000).
+        master (bool): Whether to use the enhanced Master Preview Server (FastAPI + SSE).
     """
+    # 1. Enhanced Master Mode
+    if master:
+        try:
+            from .server import run_server, HAS_SERVER_DEPS
+
+            if HAS_SERVER_DEPS:
+                # For master mode, we watch the directory of the file
+                target_dir = os.path.dirname(os.path.abspath(filename))
+                if os.path.isdir(filename):
+                    target_dir = os.path.abspath(filename)
+
+                # Open browser first
+                webbrowser.open(f"http://localhost:{port}")
+                run_server(target_dir, port)
+                return
+            else:
+                print(
+                    "Warning: FastAPI/Uvicorn not found. Falling back to basic server."
+                )
+        except ImportError:
+            print("Warning: server module not found. Falling back to basic server.")
+
     # Create a Path object for robust file path handling
     path = Path(filename)
 
@@ -342,6 +365,11 @@ def main() -> None:
     serve_parser.add_argument(
         "--port", type=int, default=8000, help="Port to bind to (default: 8000)"
     )
+    serve_parser.add_argument(
+        "--master",
+        action="store_true",
+        help="Use enhanced Master Preview (requires FastAPI)",
+    )
 
     # Parse the arguments provided by the user
     args = parser.parse_args()
@@ -349,7 +377,7 @@ def main() -> None:
     # Dispatch logic
     if args.command == "serve":
         # Invoke the serve function with parsed arguments
-        serve(args.file, args.port)
+        serve(args.file, args.port, args.master)
 
 
 if __name__ == "__main__":

mermaid_trace/integrations/__init__.py

@@ -2,3 +2,8 @@
 MermaidTrace integrations package.
 Contains middleware and adapters for third-party frameworks.
 """
+
+from .fastapi import MermaidTraceMiddleware
+from .langchain import MermaidTraceCallbackHandler
+
+__all__ = ["MermaidTraceMiddleware", "MermaidTraceCallbackHandler"]

mermaid_trace/integrations/langchain.py

@@ -0,0 +1,312 @@
+"""
+LangChain Integration Module for MermaidTrace.
+
+This module provides a LangChain Callback Handler that allows you to automatically
+generate Mermaid sequence diagrams for your LangChain chains, LLM calls, and tool usage.
+"""
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+import uuid
+
+from ..core.events import FlowEvent
+from ..core.context import LogContext
+from ..core.decorators import get_flow_logger
+
+if TYPE_CHECKING:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.outputs import LLMResult
+else:
+    try:
+        from langchain_core.callbacks import BaseCallbackHandler
+        from langchain_core.outputs import LLMResult
+    except ImportError:
+        BaseCallbackHandler = object
+        LLMResult = Any
+
+
+class MermaidTraceCallbackHandler(BaseCallbackHandler):
+    """
+    LangChain Callback Handler that records execution flow as Mermaid sequence diagrams.
+
+    This handler intercepts LangChain events (Chain, LLM, Tool) and logs them as
+    FlowEvents, which are then processed by MermaidTrace to generate diagrams.
+    """
+
+    def __init__(self, host_name: str = "LangChain"):
+        """
+        Initialize the callback handler.
+
+        Args:
+            host_name (str): The name of the host participant in the diagram.
+                             Defaults to "LangChain".
+        """
+        if BaseCallbackHandler is object:
+            raise ImportError(
+                "langchain-core is required to use MermaidTraceCallbackHandler. "
+                "Install it with `pip install langchain-core`."
+            )
+        self.host_name = host_name
+        self.logger = get_flow_logger()
+        self._participant_stack: List[str] = []
+
+    def _get_current_source(self) -> str:
+        if self._participant_stack:
+            return self._participant_stack[-1]
+        return str(LogContext.get("current_participant", self.host_name))
+
+    def on_chain_start(
+        self,
+        serialized: Optional[Dict[str, Any]],
+        inputs: Dict[str, Any],
+        **kwargs: Any,
+    ) -> None:
+        """Run when chain starts running."""
+        target = (
+            (serialized.get("name") if serialized else None)
+            or kwargs.get("name")
+            or "Chain"
+        )
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=source,
+            target=target,
+            action="Run Chain",
+            message=f"Start Chain: {target}",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            params=str(inputs),
+        )
+        self.logger.info(
+            f"{source} -> {target}: {event.action}", extra={"flow_event": event}
+        )
+        self._participant_stack.append(target)
+
+    def on_chain_end(self, outputs: Dict[str, Any], **kwargs: Any) -> None:
+        """Run when chain ends running."""
+        if not self._participant_stack:
+            return
+
+        target = self._participant_stack.pop()
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=target,
+            target=source,
+            action="Finish Chain",
+            message="Chain Complete",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            result=str(outputs),
+            is_return=True,
+        )
+        self.logger.info(
+            f"{target} -> {source}: {event.action}", extra={"flow_event": event}
+        )
+
+    def on_llm_start(
+        self, serialized: Optional[Dict[str, Any]], prompts: List[str], **kwargs: Any
+    ) -> None:
+        """Run when LLM starts running."""
+        target = (serialized.get("name") if serialized else None) or "LLM"
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=source,
+            target=target,
+            action="Prompt",
+            message="LLM Request",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            params=str(prompts),
+        )
+        self.logger.info(
+            f"{source} -> {target}: {event.action}", extra={"flow_event": event}
+        )
+        self._participant_stack.append(target)
+
+    def on_chat_model_start(
+        self,
+        serialized: Optional[Dict[str, Any]],
+        messages: List[List[Any]],
+        **kwargs: Any,
+    ) -> None:
+        """Run when Chat Model starts running."""
+        target = (serialized.get("name") if serialized else None) or "ChatModel"
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=source,
+            target=target,
+            action="Chat",
+            message="ChatModel Request",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            params=str(messages),
+        )
+        self.logger.info(
+            f"{source} -> {target}: {event.action}", extra={"flow_event": event}
+        )
+        self._participant_stack.append(target)
+
+    def on_llm_end(self, response: LLMResult, **kwargs: Any) -> None:
+        """Run when LLM ends running."""
+        if not self._participant_stack:
+            return
+
+        source = self._participant_stack.pop()
+        target = self._get_current_source()
+
+        event = FlowEvent(
+            source=source,
+            target=target,
+            action="Response",
+            message="LLM/Chat Completion",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            result=str(response.generations),
+            is_return=True,
+        )
+        self.logger.info(
+            f"{source} -> {target}: {event.action}", extra={"flow_event": event}
+        )
+
+    def on_llm_error(self, error: BaseException, **kwargs: Any) -> None:
+        """Run when LLM errors."""
+        if not self._participant_stack:
+            return
+        target = self._participant_stack.pop()
+        source = self._get_current_source()
+        event = FlowEvent(
+            source=target,
+            target=source,
+            action="Error",
+            message=f"LLM Error: {type(error).__name__}",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            is_error=True,
+            error_message=str(error),
+            is_return=True,
+        )
+        self.logger.info(
+            f"{target} -> {source}: {event.action}", extra={"flow_event": event}
+        )
+
+    def on_retriever_start(
+        self,
+        serialized: Optional[Dict[str, Any]],
+        query: str,
+        **kwargs: Any,
+    ) -> None:
+        """Run when Retriever starts running."""
+        target = (serialized.get("name") if serialized else None) or "Retriever"
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=source,
+            target=target,
+            action="Retrieve",
+            message=f"Query: {query[:50]}...",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            params=query,
+        )
+        self.logger.info(
+            f"{source} -> {target}: {event.action}", extra={"flow_event": event}
+        )
+        self._participant_stack.append(target)
+
+    def on_retriever_end(self, documents: List[Any], **kwargs: Any) -> Any:  # type: ignore[override]
+        """Run when Retriever ends running."""
+        if not self._participant_stack:
+            return
+
+        target = self._participant_stack.pop()
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=target,
+            target=source,
+            action="Documents",
+            message=f"Retrieved {len(documents)} docs",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            result=f"Count: {len(documents)}",
+            is_return=True,
+        )
+        self.logger.info(
+            f"{target} -> {source}: {event.action}", extra={"flow_event": event}
+        )
+
+    def on_tool_start(
+        self, serialized: Optional[Dict[str, Any]], input_str: str, **kwargs: Any
+    ) -> None:
+        """Run when tool starts running."""
+        target = (serialized.get("name") if serialized else None) or "Tool"
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=source,
+            target=target,
+            action="Call Tool",
+            message=f"Tool: {target}",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            params=input_str,
+        )
+        self.logger.info(
+            f"{source} -> {target}: {event.action}", extra={"flow_event": event}
+        )
+        self._participant_stack.append(target)
+
+    def on_tool_end(self, output: Any, **kwargs: Any) -> None:
+        """Run when tool ends running."""
+        if not self._participant_stack:
+            return
+
+        target = self._participant_stack.pop()
+        source = self._get_current_source()
+
+        event = FlowEvent(
+            source=target,
+            target=source,
+            action="Finish Tool",
+            message="Tool Complete",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            result=str(output),
+            is_return=True,
+        )
+        self.logger.info(
+            f"{target} -> {source}: {event.action}", extra={"flow_event": event}
+        )
+
+    def on_chain_error(self, error: BaseException, **kwargs: Any) -> None:
+        """Run when chain errors."""
+        if not self._participant_stack:
+            return
+        target = self._participant_stack.pop()
+        source = self._get_current_source()
+        event = FlowEvent(
+            source=target,
+            target=source,
+            action="Error",
+            message=f"Chain Error: {type(error).__name__}",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            is_error=True,
+            error_message=str(error),
+            is_return=True,
+        )
+        self.logger.info(
+            f"{target} -> {source}: {event.action}", extra={"flow_event": event}
+        )
+
+    def on_tool_error(self, error: BaseException, **kwargs: Any) -> None:
+        """Run when tool errors."""
+        if not self._participant_stack:
+            return
+        target = self._participant_stack.pop()
+        source = self._get_current_source()
+        event = FlowEvent(
+            source=target,
+            target=source,
+            action="Error",
+            message=f"Tool Error: {type(error).__name__}",
+            trace_id=LogContext.get("trace_id", str(uuid.uuid4())),
+            is_error=True,
+            error_message=str(error),
+            is_return=True,
+        )
+        self.logger.info(
+            f"{target} -> {source}: {event.action}", extra={"flow_event": event}
+        )

mermaid_trace/server.py

@@ -0,0 +1,406 @@
+"""
+Enhanced Web Server for MermaidTrace.
+
+This module provides a robust, real-time preview server using FastAPI and Server-Sent Events (SSE).
+It monitors .mmd files and pushes updates to the browser instantly.
+"""
+
+import asyncio
+import os
+import json
+from pathlib import Path
+from typing import AsyncGenerator, Set, Any
+
+try:
+    from fastapi import FastAPI, Request, HTTPException
+    from fastapi.responses import HTMLResponse, StreamingResponse
+    import uvicorn
+
+    HAS_SERVER_DEPS = True
+except ImportError:
+    HAS_SERVER_DEPS = False
+
+try:
+    from watchdog.observers import Observer
+    from watchdog.events import FileSystemEventHandler
+
+    HAS_WATCHDOG = True
+except ImportError:
+    HAS_WATCHDOG = False
+
+app = FastAPI(title="MermaidTrace Preview Server")
+
+
+# Global state to manage connected clients for SSE
+class ConnectionManager:
+    def __init__(self) -> None:
+        self.active_connections: Set[asyncio.Queue[dict[str, Any]]] = set()
+
+    async def subscribe(self) -> asyncio.Queue[dict[str, Any]]:
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        self.active_connections.add(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        self.active_connections.remove(queue)
+
+    async def broadcast(self, data: dict[str, Any]) -> None:
+        for queue in self.active_connections:
+            await queue.put(data)
+
+
+manager = ConnectionManager()
+
+# HTML Template with enhanced UI
+HTML_TEMPLATE = """
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>MermaidTrace Master Preview</title>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/svg-pan-zoom@3.6.1/dist/svg-pan-zoom.min.js"></script>
+    <link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">
+    <style>
+        body { background-color: #f8fafc; }
+        .mermaid { background: white; }
+        #diagram-container { 
+            height: calc(100vh - 10rem); 
+            overflow: hidden; 
+            position: relative;
+            background-image: radial-gradient(#e2e8f0 1px, transparent 1px);
+            background-size: 20px 20px;
+            display: flex;
+            flex-direction: column;
+        }
+        #svg-wrapper { 
+            flex: 1;
+            width: 100%; 
+            height: 100%; 
+            cursor: grab; 
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+        #svg-wrapper:active { cursor: grabbing; }
+        .sidebar-item:hover { background-color: #e2e8f0; }
+        .sidebar-item.active { background-color: #3b82f6; color: white; }
+        /* Ensure mermaid SVG doesn't have max-width constraints */
+        #mermaid-graph {
+            width: 100%;
+            height: 100%;
+            display: flex;
+            align-items: center;
+            justify-content: center;
+        }
+        #mermaid-graph svg {
+            max-width: none !important;
+            max-height: none !important;
+        }
+    </style>
+</head>
+<body class="flex flex-col h-screen">
+    <!-- Header -->
+    <header class="bg-white border-b border-gray-200 px-6 py-4 flex justify-between items-center shadow-sm">
+        <div class="flex items-center space-x-3">
+            <div class="bg-blue-600 text-white p-2 rounded-lg">
+                <svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"></path>
+                </svg>
+            </div>
+            <h1 class="text-xl font-bold text-gray-800">MermaidTrace <span class="text-blue-600">Master</span></h1>
+        </div>
+        <div class="flex items-center space-x-4">
+            <span id="status-badge" class="px-3 py-1 rounded-full text-xs font-medium bg-green-100 text-green-800">Live Connected</span>
+            <button onclick="resetZoom()" class="text-gray-600 hover:text-blue-600 transition">
+                <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 8V4m0 0h4M4 4l5 5m11-1V4m0 0h-4m4 0l-5 5M4 16v4m0 0h4m-4 0l5-5m11 5l-5-5m5 5v-4m0 4h-4"></path></svg>
+            </button>
+            <button onclick="downloadSVG()" class="text-gray-600 hover:text-blue-600 transition">
+                <svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 16v1a3 3 0 003 3h10a3 3 0 003-3v-1m-4-4l-4 4m0 0l-4-4m4 4V4"></path></svg>
+            </button>
+        </div>
+    </header>
+
+    <div class="flex flex-1 overflow-hidden">
+        <!-- Sidebar -->
+        <aside class="w-64 bg-white border-r border-gray-200 overflow-y-auto hidden md:block">
+            <div class="p-4 border-b border-gray-100">
+                <h2 class="text-xs font-semibold text-gray-500 uppercase tracking-wider">Trace Files</h2>
+            </div>
+            <nav id="file-list" class="p-2 space-y-1">
+                <!-- File items will be injected here -->
+            </nav>
+        </aside>
+
+        <!-- Main Content -->
+        <main class="flex-1 flex flex-col p-6 overflow-hidden">
+            <div class="mb-4 flex justify-between items-end">
+                <div>
+                    <h2 id="current-filename" class="text-2xl font-bold text-gray-900">Select a file</h2>
+                    <p id="last-updated" class="text-sm text-gray-500 mt-1">Ready to visualize</p>
+                </div>
+            </div>
+
+            <div id="diagram-container" class="flex-1 bg-white rounded-xl shadow-inner border border-gray-200 overflow-hidden">
+                <div id="svg-wrapper">
+                    <div class="mermaid" id="mermaid-graph">
+                        sequenceDiagram
+                        Note over Server, Client: Waiting for trace data...
+                    </div>
+                </div>
+            </div>
+        </main>
+    </div>
+
+    <script>
+        let panZoomInstance = null;
+        let currentFile = null;
+
+        function initMermaid() {
+            if (typeof mermaid === 'undefined') {
+                console.log("Waiting for mermaid...");
+                setTimeout(initMermaid, 100);
+                return;
+            }
+            
+            mermaid.initialize({ 
+                startOnLoad: false, 
+                theme: 'default',
+                securityLevel: 'loose',
+                useMaxWidth: false,
+                sequence: { 
+                    showSequenceNumbers: true,
+                    useMaxWidth: false,
+                    bottomMarginAdjustment: 1
+                }
+            });
+            
+            // Initialize
+            updateFileList();
+        }
+
+        async function loadFile(filename) {
+            if (!filename) return;
+            currentFile = filename;
+            
+            // Update active state in sidebar
+            document.querySelectorAll('.sidebar-item').forEach(el => {
+                if (el.dataset.filename === filename) el.classList.add('active');
+                else el.classList.remove('active');
+            });
+
+            try {
+                const response = await fetch(`/api/file?name=${encodeURIComponent(filename)}`);
+                const data = await response.json();
+                
+                document.getElementById('current-filename').textContent = filename;
+                renderDiagram(data.content);
+                updateTimestamp();
+            } catch (err) {
+                console.error("Failed to load file:", err);
+            }
+        }
+
+        async function renderDiagram(content) {
+            const graphDiv = document.getElementById('mermaid-graph');
+            graphDiv.removeAttribute('data-processed');
+            // Clean up previous SVG before rendering new one
+            graphDiv.innerHTML = content;
+            
+            try {
+                const { svg } = await mermaid.render('mermaid-svg-' + Date.now(), content);
+                graphDiv.innerHTML = svg;
+                setupPanZoom();
+            } catch (err) {
+                console.error("Mermaid render error:", err);
+            }
+        }
+
+        function setupPanZoom() {
+            if (panZoomInstance) {
+                panZoomInstance.destroy();
+                panZoomInstance = null;
+            }
+            const svg = document.querySelector('#mermaid-graph svg');
+            if (svg) {
+                // Ensure SVG takes up all available space for the pan-zoom container
+                svg.style.width = '100%';
+                svg.style.height = '100%';
+                svg.style.maxWidth = 'none';
+                svg.style.maxHeight = 'none';
+                
+                // Clear explicit width/height attributes that might conflict with 'fit'
+                svg.removeAttribute('width');
+                svg.removeAttribute('height');
+                
+                panZoomInstance = svgPanZoom(svg, {
+                    zoomEnabled: true,
+                    controlIconsEnabled: false,
+                    fit: true,
+                    center: true,
+                    minZoom: 0.1,
+                    maxZoom: 20,
+                    zoomScaleSensitivity: 0.2
+                });
+
+                // Auto fit on window resize
+                window.addEventListener('resize', () => {
+                    if (panZoomInstance) {
+                        panZoomInstance.resize();
+                        panZoomInstance.fit();
+                        panZoomInstance.center();
+                    }
+                });
+            }
+        }
+
+        function resetZoom() {
+            if (panZoomInstance) {
+                panZoomInstance.fit();
+                panZoomInstance.center();
+            }
+        }
+
+        function updateTimestamp() {
+            const now = new Date();
+            document.getElementById('last-updated').textContent = `Last updated: ${now.toLocaleTimeString()}`;
+        }
+
+        async function updateFileList() {
+            const response = await fetch('/api/files');
+            const files = await response.json();
+            const list = document.getElementById('file-list');
+            list.innerHTML = '';
+            
+            files.forEach(f => {
+                const item = document.createElement('a');
+                item.href = "#";
+                item.className = `sidebar-item block px-3 py-2 text-sm font-medium rounded-md transition ${f === currentFile ? 'active' : 'text-gray-700'}`;
+                item.dataset.filename = f;
+                item.textContent = f;
+                item.onclick = (e) => {
+                    e.preventDefault();
+                    loadFile(f);
+                };
+                list.appendChild(item);
+            });
+
+            if (!currentFile && files.length > 0) {
+                loadFile(files[0]);
+            }
+        }
+
+        // SSE Connection for real-time updates
+        const eventSource = new EventSource("/events");
+        eventSource.onmessage = (event) => {
+            const data = JSON.parse(event.data);
+            if (data.type === "update" && data.filename === currentFile) {
+                console.log("File update received:", data.filename);
+                loadFile(data.filename);
+            } else if (data.type === "refresh_list") {
+                updateFileList();
+            }
+        };
+
+        eventSource.onerror = () => {
+            document.getElementById('status-badge').className = "px-3 py-1 rounded-full text-xs font-medium bg-red-100 text-red-800";
+            document.getElementById('status-badge').textContent = "Connection Lost";
+        };
+        
+        // Start Initialization
+        initMermaid();
+
+        function downloadSVG() {
+            const svg = document.querySelector('#diagram-container svg');
+            if (!svg) return;
+            const serializer = new XMLSerializer();
+            let source = serializer.serializeToString(svg);
+            if(!source.match(/^<svg[^>]+xmlns="http\\:\\/\\/www\\.w3\\.org\\/2000\\/svg"/)){
+                source = source.replace(/^<svg/, '<svg xmlns="http://www.w3.org/2000/svg"');
+            }
+            if(!source.match(/^<svg[^>]+xmlns\\:xlink="http\\:\\/\\/www\\.w3\\.org\\/1999\\/xlink"/)){
+                source = source.replace(/^<svg/, '<svg xmlns:xlink="http://www.w3.org/1999/xlink"');
+            }
+            source = '<?xml version="1.0" standalone="no"?>\\r\\n' + source;
+            const url = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(source);
+            const link = document.createElement("a");
+            link.href = url;
+            link.download = `${currentFile || 'diagram'}.svg`;
+            link.click();
+        }
+    </script>
+</body>
+</html>
+"""
+
+# Global directory to watch
+watch_dir: Path = Path(".")
+
+
+@app.get("/", response_class=HTMLResponse)
+async def get_index() -> str:
+    return HTML_TEMPLATE
+
+
+@app.get("/api/files")
+async def list_files() -> list[str]:
+    files = sorted([f.name for f in watch_dir.glob("*.mmd")])
+    return files
+
+
+@app.get("/api/file")
+async def get_file_content(name: str) -> dict[str, str]:
+    file_path = watch_dir / name
+    if not file_path.exists() or not str(file_path).endswith(".mmd"):
+        raise HTTPException(status_code=404, detail="File not found")
+    return {"content": file_path.read_text(encoding="utf-8")}
+
+
+@app.get("/events")
+async def sse_endpoint(request: Request) -> StreamingResponse:
+    async def event_generator() -> AsyncGenerator[str, None]:
+        queue = await manager.subscribe()
+        try:
+            while True:
+                if await request.is_disconnected():
+                    break
+                data = await queue.get()
+                yield f"data: {json.dumps(data)}\\n\\n"
+        finally:
+            manager.unsubscribe(queue)
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+def run_server(directory: str, port: int = 8000) -> None:
+    global watch_dir
+    watch_dir = Path(directory).resolve()
+
+    if not HAS_SERVER_DEPS:
+        print("Error: FastAPI, Uvicorn are required for the enhanced server.")
+        print("Install them with: pip install fastapi uvicorn")
+        return
+
+    # Start Watchdog
+    if HAS_WATCHDOG:
+
+        class Handler(FileSystemEventHandler):
+            def on_modified(self, event: Any) -> None:
+                if not event.is_directory and event.src_path.endswith(".mmd"):
+                    filename = os.path.basename(event.src_path)
+                    asyncio.run(
+                        manager.broadcast({"type": "update", "filename": filename})
+                    )
+
+            def on_created(self, event: Any) -> None:
+                if not event.is_directory and event.src_path.endswith(".mmd"):
+                    asyncio.run(manager.broadcast({"type": "refresh_list"}))
+
+        observer = Observer()
+        observer.schedule(Handler(), str(watch_dir), recursive=False)
+        observer.start()
+        print(f"[*] Watching directory: {watch_dir}")
+
+    print(f"[*] Starting Master Preview Server at http://localhost:{port}")
+    uvicorn.run(app, host="0.0.0.0", port=port, log_level="error")

mermaid_trace-0.6.0.post0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: mermaid-trace
+Version: 0.6.0.post0
+Summary: Visualize your Python code execution flow as Mermaid Sequence Diagrams.
+Project-URL: Documentation, https://github.com/xt765/mermaid-trace#readme
+Project-URL: Changelog, https://github.com/xt765/mermaid-trace/blob/main/docs/en/CHANGELOG.md
+Project-URL: Issues, https://github.com/xt765/mermaid-trace/issues
+Project-URL: Source, https://github.com/xt765/mermaid-trace
+Author-email: xt765 <xt765@foxmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 xt765
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: asyncio,logging,mermaid,mermaid-trace,sequence-diagram,trace,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: watchdog>=2.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.100.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100.0; extra == 'dev'
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: langchain-core>=0.1.0; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# MermaidTrace: Visualize Your Python Code Logic
+
+**Stop drowning in cryptic logs. One line of code to transform complex execution logic into clear Mermaid sequence diagrams.**
+
+🌐 **Language**: [English](README.md) | [中文](README_CN.md)
+
+[![CSDN Blog](https://img.shields.io/badge/CSDN-玄同765-orange?style=flat-square&logo=csdn)](https://blog.csdn.net/Yunyi_Chi)
+[![GitHub](https://img.shields.io/badge/GitHub-mermaid--trace-black?style=flat-square&logo=github)](https://github.com/xt765/mermaid-trace)
+[![Gitee](https://img.shields.io/badge/Gitee-mermaid--trace-red?style=flat-square&logo=gitee)](https://gitee.com/xt765/mermaid-trace)
+[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
+[![License](https://img.shields.io/github/license/xt765/mermaid-trace?style=flat-square)](LICENSE)
+[![CI Status](https://img.shields.io/github/actions/workflow/status/xt765/mermaid-trace/ci.yml?style=flat-square&label=CI)](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
+[![Codecov](https://img.shields.io/codecov/c/github/xt765/mermaid-trace?style=flat-square&logo=codecov)](https://codecov.io/gh/xt765/mermaid-trace)
+
+---
+
+## ⚡️ Understand MermaidTrace in 5 Seconds
+
+#### 1. Original Code (15+ lines)
+```python
+@trace(source="User", target="OrderSys")
+def create_order(user_id, items):
+    # Complex business logic
+    if not check_inventory(items):
+        return "Out of Stock"
+
+    # Nested logic calls
+    price = calculate_price(items)
+    discount = get_discount(user_id)
+    final = price - discount
+
+    # External service interactions
+    res = pay_service.process(final)
+    if res.success:
+        update_stock(items)
+        send_notif(user_id)
+        return "Success"
+    return "Failed"
+```
+
+#### 2. Auto-Generated Sequence Diagram
+```mermaid
+sequenceDiagram
+    autonumber
+    User->>OrderSys: create_order(user_id, items)
+    activate OrderSys
+    OrderSys->>Inventory: check_inventory(items)
+    Inventory-->>OrderSys: True
+    OrderSys->>Pricing: calculate_price(items)
+    Pricing-->>OrderSys: 100.0
+    OrderSys->>UserDB: get_discount(user_id)
+    UserDB-->>OrderSys: 5.0
+    OrderSys->>PayService: process(95.0)
+    activate PayService
+    PayService-->>OrderSys: success
+    deactivate PayService
+    OrderSys->>Inventory: update_stock(items)
+    OrderSys->>Notification: send_notif(user_id)
+    OrderSys-->>User: "Success"
+    deactivate OrderSys
+```
+
+---
+
+## 🚀 Dynamic Demo & Online Tryout
+
+### 🎬 Quick Demo
+
+![MermaidTrace Master Preview](docs/images/master_preview.png)
+
+*(Master Preview: Multi-file browsing, live-reload, and interactive pan/zoom)*
+
+```mermaid
+sequenceDiagram
+    participant CLI as mermaid-trace CLI
+    participant App as Python App
+    participant Web as Live Preview
+
+    Note over CLI, Web: Enable Live Preview Mode
+    CLI->>Web: Start HTTP Server (localhost:8000)
+    App->>App: Run Logic (with @trace decorator)
+    App->>App: Auto-update flow.mmd
+    Web->>Web: File Change Detected (Hot Reload)
+    Web-->>CLI: Render Latest Diagram
+```
+*(From adding decorators to browser live preview in 10 seconds)*
+
+### 🛠️ Try Online (Google Colab)
+
+No local setup required. Experience core features in your browser:
+
+[![Open In Colab](https://img.shields.io/badge/Colab-Open%20in%20Colab-blue?style=flat&logo=google-colab&logoColor=white)](https://colab.research.google.com/github/xt765/mermaid-trace/blob/main/examples/MermaidTrace_Demo.ipynb)
+
+---
+
+## 🎯 Why MermaidTrace? (Use Cases)
+
+### 1. Master "Legacy" Codebases
+**Pain**: Taking over a complex, undocumented legacy project with tangled function calls.
+**Solution**: Add `@trace_class` or `@trace` to entry points and run the code once.
+**Value**: Instantly generate a complete execution path map to understand the architecture.
+
+### 2. Automated Technical Docs
+**Pain**: Manual sequence diagrams are time-consuming and quickly become outdated.
+**Solution**: Integrate MermaidTrace during development.
+**Value**: Diagrams stay 100% in sync with your code logic automatically.
+
+### 3. Debug Complex Recursion & Concurrency
+**Pain**: Nested calls or async tasks produce interleaved logs that are impossible to read.
+**Solution**: Use built-in async support and intelligent collapsing.
+**Value**: Visualize recursion depth and concurrency flow to pinpoint logic bottlenecks.
+
+---
+
+## 🚀 Quick Start in 3 Steps
+
+### 1. Install
+```bash
+pip install mermaid-trace
+```
+
+### 2. Add Decorators
+```python
+from mermaid_trace import trace, configure_flow
+
+# Configure output file
+configure_flow("my_flow.mmd")
+
+@trace(source="User", target="AuthService")
+def login(username):
+    return verify_db(username)
+
+@trace(source="AuthService", target="DB")
+def verify_db(username):
+    return True
+
+login("admin")
+```
+
+### 3. View Diagram
+
+Run the built-in CLI tool to preview in real-time (with hot-reload):
+
+```bash
+# Basic preview
+mermaid-trace serve my_flow.mmd
+
+# Master mode (Directory browsing, zoom, multi-file switching)
+mermaid-trace serve . --master
+# Or preview a specific file in Master mode
+mermaid-trace serve .\mermaid_diagrams\examples\08-log-rotation.mmd --master
+```
+
+### 🔗 LangChain Integration
+Visualize LLM chains, agents, and RAG retrieval with a single handler:
+```python
+from mermaid_trace.integrations.langchain import MermaidTraceCallbackHandler
+
+handler = MermaidTraceCallbackHandler(host_name="MyAIApp")
+# Pass to any LangChain object
+chain.invoke({"input": "..."}, config={"callbacks": [handler]})
+```
+
+---
+
+## ✨ Key Features
+
+- **Decorator-Driven**: Simply add `@trace` or `@trace_interaction` to functions.
+- **Auto-Instrumentation**: Use `@trace_class` to trace a whole class at once.
+- **Third-Party Patching**: Use `patch_object` to trace calls inside external libraries.
+- **Async Support**: Seamlessly works with `asyncio` coroutines and concurrency.
+- **Enhanced Web UI**: Interactive preview server with file browsing, auto-reload, and pan/zoom support (use `--master`).
+- **Intelligent Collapsing**: Automatically collapses repetitive calls and identifies loops.
+- **FastAPI Integration**: Middleware for zero-config HTTP request tracing.
+- **LangChain Integration**: Callback Handler for LLM chains and agent visualization.
+- **Detailed Exceptions**: Captures full stack traces for errors, displayed in the diagram.
+
+---
+
+## 📚 Documentation
+
+### Core Documentation
+
+[User Guide](docs/en/USER_GUIDE.md) · [API Reference](docs/en/API.md) · [Contributing Guidelines](docs/en/CONTRIBUTING.md) · [Changelog](docs/en/CHANGELOG.md) · [License](LICENSE)
+
+### Code Comment Documents
+
+| Category | Links |
+| :--- | :--- |
+| **Core Modules** | [Context](docs/en/code_comments/src/mermaid_trace/core/context.md) · [Decorators](docs/en/code_comments/src/mermaid_trace/core/decorators.md) · [Events](docs/en/code_comments/src/mermaid_trace/core/events.md) · [Formatter](docs/en/code_comments/src/mermaid_trace/core/formatter.md) |
+| **Handlers** | [Async Handler](docs/en/code_comments/src/mermaid_trace/handlers/async_handler.md) · [Mermaid Handler](docs/en/code_comments/src/mermaid_trace/handlers/mermaid_handler.md) |
+| **Integrations** | [FastAPI](docs/en/code_comments/src/mermaid_trace/integrations/fastapi.md) |
+| **Others** | [init](docs/en/code_comments/src/mermaid_trace/__init__.md) · [CLI](docs/en/code_comments/src/mermaid_trace/cli.md) |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
+
+---
+
+## 📄 License
+
+MIT

{mermaid_trace-0.5.3.post0.dist-info → mermaid_trace-0.6.0.post0.dist-info}/RECORD

@@ -1,6 +1,7 @@
 mermaid_trace/__init__.py,sha256=EnAsz6R6ag4dtabdHEg1wdB2k7V1uwmwpYTTC41GQX4,6721
-mermaid_trace/cli.py,sha256=g7Qriiox9YqfJutUntE1a7GwByg62wGwQcLfpvicjT8,15076
+mermaid_trace/cli.py,sha256=FCbm9kHf7B74bvkRv_k7stTeG7S7GqNSITmUQW1kJEA,16173
 mermaid_trace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_trace/server.py,sha256=1nNIS6pNAn3_XCwuoUkKIOsq4GJK5o33QFzv-hh-IJY,15458
 mermaid_trace/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mermaid_trace/core/config.py,sha256=akTOc3m_bzcZ7e1Qtf1n5Ct9Dj8XPTTcWzATG3-qJHw,1890
 mermaid_trace/core/context.py,sha256=wr-Ys3c6PsYCtbPUsQTrnaciSkP-fofxOewo4oZ27QM,8556
@@ -10,10 +11,11 @@ mermaid_trace/core/formatter.py,sha256=3KEq236E3GAj_j53MuBM2ndWm7Kx4KeywJWmoY5o5
 mermaid_trace/core/utils.py,sha256=FagsMYLZcbmOgKmRo3v9tcRNVIpuc1YEKTAjcRk7keY,3410
 mermaid_trace/handlers/async_handler.py,sha256=WmLcULXHasapt7-W0p_Eltjmwvlq6r6BS6pViuseZ4w,8252
 mermaid_trace/handlers/mermaid_handler.py,sha256=Czar6JYSPTu5L1fQC0I8v1UpToD6aE_r96IkPpRSByw,6142
-mermaid_trace/integrations/__init__.py,sha256=uU_8E1tlP327Fn79kvzlgEdoiIpQLsWJl3BgyqgsFMQ,104
+mermaid_trace/integrations/__init__.py,sha256=stWAHIL1zv21foaXFXZ_3SLxJ8icN0YFGWOvvHERCDI,269
 mermaid_trace/integrations/fastapi.py,sha256=6LRs4Z508l38ymfj5SP39vOV6OLfYLRkpxyL_SxvudM,9483
-mermaid_trace-0.5.3.post0.dist-info/METADATA,sha256=FR1kgM-wlTzrFasLpIeqbWbV_X3h3TwwUkxQCvgbvo0,9959
-mermaid_trace-0.5.3.post0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mermaid_trace-0.5.3.post0.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
-mermaid_trace-0.5.3.post0.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
-mermaid_trace-0.5.3.post0.dist-info/RECORD,,
+mermaid_trace/integrations/langchain.py,sha256=n1M2-OYNMsKiMpfGj04cs_dLyn2t5T9APmgAZsqqm5Q,10598
+mermaid_trace-0.6.0.post0.dist-info/METADATA,sha256=kIvprKuj4jiOxpTaqumiqclh3euhw_7BkeZWg3i-YyE,10954
+mermaid_trace-0.6.0.post0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mermaid_trace-0.6.0.post0.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
+mermaid_trace-0.6.0.post0.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
+mermaid_trace-0.6.0.post0.dist-info/RECORD,,

mermaid_trace-0.5.3.post0.dist-info/METADATA

@@ -1,232 +0,0 @@
-Metadata-Version: 2.4
-Name: mermaid-trace
-Version: 0.5.3.post0
-Summary: Visualize your Python code execution flow as Mermaid Sequence Diagrams.
-Project-URL: Documentation, https://github.com/xt765/mermaid-trace#readme
-Project-URL: Changelog, https://github.com/xt765/mermaid-trace/blob/main/docs/en/CHANGELOG.md
-Project-URL: Issues, https://github.com/xt765/mermaid-trace/issues
-Project-URL: Source, https://github.com/xt765/mermaid-trace
-Author-email: xt765 <xt765@foxmail.com>
-License: MIT License
-        
-        Copyright (c) 2026 xt765
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy
-        of this software and associated documentation files (the "Software"), to deal
-        in the Software without restriction, including without limitation the rights
-        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-        copies of the Software, and to permit persons to whom the Software is
-        furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all
-        copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-        SOFTWARE.
-License-File: LICENSE
-Keywords: asyncio,logging,mermaid,mermaid-trace,sequence-diagram,trace,visualization
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Classifier: Programming Language :: Python :: Implementation :: PyPy
-Classifier: Topic :: Software Development :: Debuggers
-Classifier: Topic :: System :: Logging
-Requires-Python: >=3.10
-Requires-Dist: typing-extensions>=4.0.0
-Requires-Dist: watchdog>=2.0.0
-Provides-Extra: all
-Requires-Dist: fastapi>=0.100.0; extra == 'all'
-Provides-Extra: dev
-Requires-Dist: fastapi>=0.100.0; extra == 'dev'
-Requires-Dist: httpx; extra == 'dev'
-Requires-Dist: mypy; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-asyncio; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
-Provides-Extra: fastapi
-Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
-Description-Content-Type: text/markdown
-
-# MermaidTrace: The Python Logger That Draws Diagrams
-
-🌐 **Language**: [English](README.md) | [中文](README_CN.md)
-
-[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
-[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
-[![License](https://img.shields.io/github/license/xt765/mermaid-trace?style=flat-square)](LICENSE)
-[![CI Status](https://img.shields.io/github/actions/workflow/status/xt765/mermaid-trace/ci.yml?style=flat-square&label=CI)](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
-[![Codecov](https://img.shields.io/codecov/c/github/xt765/mermaid-trace?style=flat-square&logo=codecov)](https://codecov.io/gh/xt765/mermaid-trace)
-
----
-
-## 📋 Overview
-
-**Stop reading logs. Start watching them.**
-
-MermaidTrace is a specialized logging tool that automatically generates [Mermaid JS](https://mermaid.js.org/) sequence diagrams from your code execution. It's perfect for visualizing complex business logic, microservice interactions, or asynchronous flows.
-
----
-
-## 📚 Documentation
-
-### Core Documentation
-
-[User Guide](docs/en/USER_GUIDE.md) · [API Reference](docs/en/API.md) · [Contributing Guidelines](docs/en/CONTRIBUTING.md) · [Changelog](docs/en/CHANGELOG.md) · [License](docs/en/LICENSE)
-
-### Code Comment Documents (Chinese)
-
-| Category | Links |
-| :--- | :--- |
-| **Core Modules** | [Context](docs/zh/code_comments/src/mermaid_trace/core/context.md) · [Decorators](docs/zh/code_comments/src/mermaid_trace/core/decorators.md) · [Events](docs/zh/code_comments/src/mermaid_trace/core/events.md) · [Formatter](docs/zh/code_comments/src/mermaid_trace/core/formatter.md) |
-| **Handlers** | [Async Handler](docs/zh/code_comments/src/mermaid_trace/handlers/async_handler.md) · [Mermaid Handler](docs/zh/code_comments/src/mermaid_trace/handlers/mermaid_handler.md) |
-| **Integrations** | [FastAPI](docs/zh/code_comments/src/mermaid_trace/integrations/fastapi.md) |
-| **Others** | [init](docs/zh/code_comments/src/mermaid_trace/__init__.md) · [CLI](docs/zh/code_comments/src/mermaid_trace/cli.md) |
-
----
-
-## ✨ Key Features
-
-- **Decorator-Driven**: Just add `@trace` or `@trace_interaction` to your functions.
-- **Auto-Instrumentation**: Use `@trace_class` to trace a whole class at once.
-- **Third-Party Patching**: Use `patch_object` to trace calls inside external libraries.
-- **Auto-Diagramming**: Generates `.mmd` files that can be viewed in VS Code, GitHub, or Mermaid Live Editor.
-- **Async Support**: Works seamlessly with `asyncio` coroutines.
-- **Context Inference**: Automatically tracks nested calls and infers `source` participants using `contextvars`.
-- **Intelligent Collapsing**: Prevents diagram explosion by collapsing repetitive high-frequency calls and identifying recurring patterns (e.g., loops).
-- **Detailed Exceptions**: Captures full stack traces for errors, displayed in interactive notes.
-- **Simplified Objects**: Automatically cleans up memory addresses (e.g., `<__main__.Obj at 0x...>` -> `<Obj>`) and **groups consecutive identical items** in lists/tuples (e.g., `[<Obj> x 5]`) for cleaner diagrams.
-- **Log Rotation**: Supports `RotatingMermaidFileHandler` for handling long-running systems by splitting logs based on size or time.
-- **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing, supporting distributed tracing via `X-Trace-ID` and `X-Source` headers.
-- **CLI Tool**: Built-in viewer with live-reload to preview diagrams in your browser.
-
----
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-pip install mermaid-trace
-```
-
-### Basic Usage
-
-```python
-from mermaid_trace import trace, configure_flow
-import time
-
-# 1. Configure output
-# Recommendation: Store diagrams in a dedicated directory (e.g., mermaid_diagrams/)
-configure_flow("mermaid_diagrams/my_flow.mmd", async_mode=True)
-
-# 2. Add decorators
-@trace(source="Client", target="PaymentService", action="Process Payment")
-def process_payment(amount):
-    if check_balance(amount):
-        return "Success"
-    return "Failed"
-
-@trace(source="PaymentService", target="Database", action="Check Balance")
-def check_balance(amount):
-    return True
-
-# 3. Run your code
-process_payment(100)
-```
-
-### Configuration
-
-You can configure global settings via `configure_flow` or environment variables to control performance and behavior.
-
-```python
-configure_flow(
-    "flow.mmd", 
-    overwrite=True,    # Overwrite the file on each restart (default: True)
-    level=logging.DEBUG, 
-    queue_size=5000,  # Increase buffer for high-throughput
-    config_overrides={
-        "capture_args": False,       # Disable arg capturing for max performance
-        "max_string_length": 100     # Increase string truncation limit
-    }
-)
-```
-
-**Environment Variables:**
-- `MERMAID_TRACE_CAPTURE_ARGS` (true/false)
-- `MERMAID_TRACE_MAX_STRING_LENGTH` (int)
-- `MERMAID_TRACE_MAX_ARG_DEPTH` (int)
-- `MERMAID_TRACE_QUEUE_SIZE` (int)
-
-### Nested Calls (Context Inference)
-
-You don't need to specify `source` every time. MermaidTrace infers it from the current context.
-
-```python
-@trace(source="Client", target="API")
-def main():
-    # Inside here, current participant is "API"
-    service_call()
-
-@trace(target="Service") # source inferred as "API"
-def service_call():
-    pass
-```
-
-### FastAPI Integration
-
-```python
-from fastapi import FastAPI
-from mermaid_trace.integrations.fastapi import MermaidTraceMiddleware
-
-app = FastAPI()
-app.add_middleware(MermaidTraceMiddleware, app_name="MyAPI")
-
-@app.get("/")
-async def root():
-    return {"message": "Hello World"}
-```
-
-### CLI Viewer
-
-Visualize your generated `.mmd` files instantly:
-
-```bash
-mermaid-trace serve my_flow.mmd
-```
-
-### Examples
-
-Check out the [examples/](examples/) directory for a complete set of demos covering all features:
-- **[Basic Usage](examples/01_basic_usage.py)**: Decorators and class methods.
-- **[Advanced Instrumentation](examples/02_advanced_instrumentation.py)**: `@trace_class` and `patch_object` for third-party libraries.
-- **[Async & Concurrency](examples/03_async_concurrency.py)**: Tracing `asyncio` and concurrent tasks.
-- **[Error Handling](examples/04_error_handling.py)**: Stack trace capture and error rendering.
-- **[Intelligent Collapsing](examples/05_intelligent_collapsing.py)**: Keeping diagrams clean in loops.
-- **[FastAPI Integration](examples/06_fastapi_integration.py)**: Middleware for web apps.
-- **[Full Stack App](examples/07_full_stack_app.py)**: Comprehensive example with FastAPI, SQLAlchemy, and Pydantic.
-- **[Log Rotation](examples/08-log-rotation.py)**: Handling long-running processes with file rotation.
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
-
----
-
-## 📄 License
-
-MIT