MGraph AI Service Html Graph

A powerful service that transforms HTML documents into graph representations for visualization, analysis, and manipulation. Built on the MGraph AI framework.

Overview

HTML Document  ──────►  Graph Representation  ──────►  Visual Output

<html>                     ┌─────────────┐              ┌─────────────┐
  <body>           ──►     │   Nodes     │      ──►     │   DOT       │
    <div>                  │   Edges     │              │   D3        │
  </body>                  │   Clusters  │              │   Cytoscape │
</html>                    └─────────────┘              │   VisJs     │
                                                        │   Mermaid   │
                                                        │   Tree      │
                                                        └─────────────┘

The Html Graph Service converts any HTML into a multi-graph model where different aspects of the document (DOM structure, attributes, scripts, styles) are represented as interconnected graphs that can be visualized using multiple rendering engines.

Features

Quick Start

Installation

pip install mgraph-ai-service-html-graph

Basic Usage

from mgraph_ai_service_html_graph.service.html_graph.Html_Graph__Export__Service import Html_Graph__Export__Service

service = Html_Graph__Export__Service()

html = """
<html>
    <body>
        <div class="container">
            <p>Hello World</p>
        </div>
    </body>
</html>
"""

# Export to DOT format
result = service.export(
    html           = html,
    engine         = 'dot',
    transformation = 'default'
)

print(result['output'])

Running the Server

# Development
uvicorn mgraph_ai_service_html_graph.web.Html_Graph__Web:app --reload

# Production
uvicorn mgraph_ai_service_html_graph.web.Html_Graph__Web:app --host 0.0.0.0 --port 8000

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Html_MGraph Document                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────────────────────────┐  │
│   │  HEAD GRAPH │   │  BODY GRAPH │   │       ATTRIBUTES GRAPH          │  │
│   │             │   │             │   │                                 │  │
│   │  <head>     │   │  <body>     │   │  element ──► instance ──► name  │  │
│   │    └─title  │   │    └─div    │   │                    └──► value   │  │
│   └─────────────┘   └─────────────┘   └─────────────────────────────────┘  │
│                                                                             │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────────────────────────┐  │
│   │SCRIPTS GRAPH│   │STYLES GRAPH │   │       DOCUMENT GRAPH            │  │
│   │             │   │             │   │         (Meta View)             │  │
│   │  <script>   │   │  <style>    │   │  Connects all subgraphs         │  │
│   └─────────────┘   └─────────────┘   └─────────────────────────────────┘  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

API Endpoints

Export HTML to Graph

POST /api/v1/html-graph/export
Content-Type: application/json

{
    "html": "<html><body><div>Hello</div></body></html>",
    "engine": "dot",
    "transformation": "default"
}

List Available Engines

GET /api/v1/html-graph/engines

Returns: ["dot", "d3", "cytoscape", "visjs", "mermaid", "tree"]

List Available Transformations

GET /api/v1/html-graph/transformations

Returns transformation metadata including name, label, and description.

Rendering Engines

Transformations

Creating Custom Transformations

from mgraph_ai_service_html_graph.service.html_graph__transformations.Graph_Transformation__Base import Graph_Transformation__Base

class My_Custom_Transformation(Graph_Transformation__Base):

    name        : str = "my-custom"
    label       : str = "My Custom View"
    description : str = "Custom visualization"

    def html_mgraph__to__mgraph(self, html_mgraph):
        # Select which graph to visualize
        return html_mgraph.attrs_graph.mgraph

    def configure_dot(self, config):
        # Customize DOT rendering
        config.rankdir = 'LR'
        return config

The 5-Phase Pipeline

Phase 1              Phase 2              Phase 3              Phase 4              Phase 5
────────             ────────             ────────             ────────             ────────
   │                    │                    │                    │                    │
   ▼                    ▼                    ▼                    ▼                    ▼

┌───────┐          ┌───────────┐        ┌─────────┐        ┌──────────┐        ┌────────┐
│ HTML  │────────► │Html_MGraph│───────►│ MGraph  │───────►│  Engine  │───────►│ Output │
└───────┘          └───────────┘        └─────────┘        └──────────┘        └────────┘

html__to__         html_mgraph__        transform_         configure_*         transform_
html_mgraph()      to__mgraph()         mgraph()           callbacks           export()

Each phase has a transformation hook allowing complete customization of the visualization pipeline.

Development

Setup

git clone https://github.com/the-cyber-boardroom/MGraph-AI__Service__Html__Graph.git
cd MGraph-AI__Service__Html__Graph
poetry install

Running Tests

pytest tests/

Project Structure

mgraph_ai_service_html_graph/
├── service/
│   ├── html_graph/              # Export service
│   ├── html_mgraph/             # Multi-graph HTML model
│   │   ├── converters/          # HTML ↔ MGraph converters
│   │   └── graphs/              # Subgraph implementations
│   ├── html_graph__transformations/  # View transformations
│   └── mgraph__engines/         # Rendering engines
└── web/                         # FastAPI endpoints

Use Cases

• Web Scraping Analysis - Visualize DOM structure of scraped pages
• HTML Diff Visualization - Compare documents via graph representations
• Accessibility Auditing - Analyze attribute patterns for ARIA compliance
• DOM Manipulation Planning - Visualize before/after transformation states
• Educational Tool - Teach HTML structure through visual graphs
• Security Analysis - Analyze script and style injection points

Documentation

• Project Brief - Comprehensive overview
• Attribute Refactor - 3-node attribute model

License

Apache 2.0 - See LICENSE for details.

Contributing

Contributions welcome! Please read our contributing guidelines and submit pull requests.

Related Projects

• MGraph AI - Core graph framework
• The Cyber Boardroom - Parent organization