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
