sns-network-solutions/ai-core/agents/scribe/diagram-tools.md

There are several excellent Python diagramming packages, but they specialize in different kinds of diagrams. For a document-specialist AI agent, I would install a combination rather than depend on one library.

Best overall choices

Package	Best use	My rating
diagrams	Cloud, network, infrastructure, and system architecture	9.5/10
graphviz	Flowcharts, dependency maps, decision trees, and directed graphs	9.5/10
schemdraw	Electrical circuits, engineering diagrams, and flowcharts	9/10
networkx	Analyzing and constructing complex networks	9/10
pyvis	Interactive network diagrams in HTML	8.5/10
matplotlib	Custom static technical visuals	8/10
plotly	Interactive charts and data-driven visuals	9/10
blockdiag family	Sequence, activity, packet, and block diagrams	8/10
plantuml wrappers	UML and formal software diagrams	8.5/10
erdantic	Entity-relationship diagrams from Python models	9/10

1. Diagrams

Best for:

• AWS architecture
• Azure and GCP architecture
• Kubernetes
• Network infrastructure
• On-premises systems
• Application architecture
• Hybrid-cloud diagrams

pip install diagrams

It uses Graphviz underneath, so Graphviz must also be installed on the operating system.

from diagrams import Cluster, Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("Web Application", show=False):
    load_balancer = ELB("Load Balancer")

    with Cluster("Application Servers"):
        servers = [
            EC2("Server 1"),
            EC2("Server 2")
        ]

    database = RDS("Database")

    load_balancer >> servers >> database

Why it is impressive:

• Professional cloud-provider icons
• Simple Python syntax
• Clusters and boundaries
• Automatic layout
• PNG, SVG, and PDF output
• Diagram source can be stored in Git

It supports AWS, Azure, GCP, Kubernetes, Oracle Cloud, on-premises equipment, programming frameworks, SaaS services, and more. Diagrams documentation

For your networking, Linux, AWS, and infrastructure work, this should be one of your primary packages.

2. Graphviz

Best for:

• Flowcharts
• Decision trees
• Legal process diagrams
• Organizational charts
• Dependency maps
• State transitions
• Evidence relationships
• Document workflows

pip install graphviz

from graphviz import Digraph

diagram = Digraph("approval_process", format="svg")

diagram.attr(rankdir="TB")
diagram.node("A", "Document Submitted")
diagram.node("B", "Technical Review")
diagram.node("C", "Legal Review")
diagram.node("D", "Approved")
diagram.node("E", "Return for Revision")

diagram.edge("A", "B")
diagram.edge("B", "C")
diagram.edge("C", "D", label="Approved")
diagram.edge("C", "E", label="Changes required")
diagram.edge("E", "A")

diagram.render("approval-process", cleanup=True)

Graphviz is arguably the most important general-purpose diagram engine. It automatically calculates node placement and routing, making it excellent for diagrams generated by an AI agent.

Use it when the relationships matter more than custom artwork.

3. Schemdraw

Best for:

• Electrical circuits
• Wiring diagrams
• Logic gates
• Signal-flow diagrams
• Engineering illustrations
• Simple flowcharts

pip install schemdraw

import schemdraw
import schemdraw.elements as elm

with schemdraw.Drawing() as drawing:
    drawing += elm.SourceV().label("12V")
    drawing += elm.Resistor().right().label("1kΩ")
    drawing += elm.LED().down().label("Status LED")
    drawing += elm.Line().left()

Schemdraw produces clean vector-style technical graphics and is especially valuable for hardware, structured cabling, electronics, and engineering documentation.

4. NetworkX

Best for:

• Network topology data
• Relationship analysis
• Dependency analysis
• Social networks
• Routing structures
• Finding paths, clusters, and central nodes

pip install networkx matplotlib

import matplotlib.pyplot as plt
import networkx as nx

network = nx.Graph()

network.add_edges_from([
    ("Core Switch", "Access Switch 1"),
    ("Core Switch", "Access Switch 2"),
    ("Access Switch 1", "Server 1"),
    ("Access Switch 2", "Server 2"),
])

positions = nx.spring_layout(network, seed=42)

nx.draw(
    network,
    positions,
    with_labels=True,
    node_color="#10C8D8",
    node_size=3000,
    font_size=9
)

plt.show()

Important distinction: NetworkX is primarily a graph-analysis package, not a dedicated visualization system. Its documentation recommends using Graphviz, Matplotlib, or other visualization tools for more sophisticated presentation. NetworkX documentation

A strong combination is:

NetworkX → calculates relationships
Graphviz → lays them out
SVG/PDF → final document output

5. PyVis

Best for:

• Interactive network maps
• Clickable relationship diagrams
• Browser-based topology exploration
• Large graphs that users need to move and inspect

pip install pyvis networkx

from pyvis.network import Network

diagram = Network(height="700px", width="100%", directed=True)

diagram.add_node("router", label="Core Router")
diagram.add_node("switch", label="Access Switch")
diagram.add_node("server", label="Linux Server")

diagram.add_edge("router", "switch")
diagram.add_edge("switch", "server")

diagram.show("network.html")

PyVis creates interactive HTML where users can:

• Drag nodes
• Zoom
• Pan
• Hover for information
• Explore relationships

This is excellent for a live technical report but less suitable for a static legal PDF.

6. Erdantic

Best for automatically generating entity-relationship diagrams from:

• Pydantic models
• Dataclasses
• ORM models
• Structured Python classes

pip install erdantic

from dataclasses import dataclass
import erdantic as erd

@dataclass
class Customer:
    name: str
    email: str

@dataclass
class Order:
    number: str
    customer: Customer

erd.draw(Order, out="order-model.svg")

This is extremely useful for:

• Database documentation
• API documentation
• Application design
• Data-governance documentation
• Legal or compliance data maps

7. Plotly

Best for:

• Interactive business charts
• Dashboards
• Timelines
• Sankey diagrams
• Geographic maps
• Statistical visualizations

pip install plotly pandas

Example Sankey diagram:

import plotly.graph_objects as go

figure = go.Figure(
    go.Sankey(
        node={
            "label": [
                "Submitted",
                "Technical Review",
                "Legal Review",
                "Approved"
            ]
        },
        link={
            "source": [0, 1, 2],
            "target": [1, 2, 3],
            "value": [10, 8, 6]
        }
    )
)

figure.show()

Plotly is technically more of a data-visualization library than a traditional diagramming library, but its Sankey, timeline, treemap, and geographic capabilities are extremely valuable for professional reports.

8. Matplotlib

Best for:

• Custom static graphics
• Publication-quality charts
• Annotated illustrations
• Highly controlled layouts
• PDF and report integration

pip install matplotlib

Matplotlib requires more manual work than Graphviz, but it offers precise control over:

• Positioning
• Typography
• Lines and arrows
• Shapes
• Annotations
• Export resolution

Use it when other packages cannot create the exact visual required.

9. Blockdiag family

This is a collection of diagram-as-code tools:

• blockdiag — block diagrams
• seqdiag — sequence diagrams
• actdiag — activity diagrams
• nwdiag — network diagrams
• rackdiag — server-rack diagrams
• packetdiag — packet structures

These are especially interesting for a technical-documentation agent because each package addresses a specific diagram type.

pip install blockdiag seqdiag actdiag nwdiag

A network example:

nwdiag {
    network internal {
        address = "10.0.0.0/24";

        router;
        switch;
        server;

        router -- switch;
        switch -- server;
    }
}

This syntax is not Python itself, but Python packages render it.

rackdiag is particularly relevant to your data-center and rack-documentation work.

10. PlantUML with Python

Best for formal software-engineering diagrams:

• Class diagrams
• Sequence diagrams
• Component diagrams
• Deployment diagrams
• Use-case diagrams
• State diagrams
• Activity diagrams

Python can generate PlantUML source and call a PlantUML renderer.

pip install plantuml

diagram = """
@startuml
actor User
participant Application
database Database

User -> Application: Submit request
Application -> Database: Save request
Database --> Application: Confirmation
Application --> User: Success
@enduml
"""

PlantUML is an excellent choice when compliance with familiar UML conventions matters more than custom visual styling.

My recommended toolkit

For the document-specialist agent you are designing, I would use:

graphviz
diagrams
schemdraw
networkx
pyvis
erdantic
plotly
matplotlib

Add the Blockdiag family or PlantUML when those specific formal diagram types are needed.

Best tool by assignment

Assignment	Recommended package
AWS/cloud architecture	diagrams
Network topology	diagrams or nwdiag
Flowchart	graphviz
Decision tree	graphviz
Legal process	graphviz
Organizational chart	graphviz
Electrical schematic	schemdraw
Rack elevation	rackdiag
Packet structure	packetdiag
Database model	erdantic
Software UML	PlantUML
Interactive network	pyvis
Network analysis	networkx
Business chart	plotly
Sankey diagram	plotly
Highly customized static graphic	matplotlib

My strongest overall recommendation is:

Use Graphviz as the general diagram engine, Diagrams for infrastructure architecture, Schemdraw for engineering visuals, and Plotly for data-driven visuals.

That combination would cover most technical, legal, business, and infrastructure documents your AI agent would encounter.

For networking and cloud infrastructure diagrams, I would build the agent around four layers:

1. diagrams for polished architecture drawings
2. N2G or custom Graphviz for network topology generation
3. Netmiko/Nornir/NAPALM for collecting live device information
4. Draw.io output for human editing

Best packages by purpose

Need	Best choice
Designed cloud architecture	diagrams
AWS-native diagram-as-code	AWS diagram-as-code
Traditional network topology	N2G + Graphviz
Live device discovery	Nornir + Netmiko or NAPALM
CDP/LLDP discovery	Netmiko, NAPALM, or pyATS
Graph analysis	networkx
Editable Draw.io output	N2G or direct Draw.io XML generation
Interactive browser topology	pyvis
Existing AWS account mapping	Cloud-provider APIs plus a custom renderer
Rack elevations	rackdiag or custom SVG
Cable and port mapping	Custom SVG/Draw.io generation

1. Diagrams: best for polished cloud architecture

This remains my top recommendation for designed cloud and infrastructure diagrams.

It supports:

• AWS
• Azure
• Google Cloud
• Kubernetes
• Oracle Cloud
• Alibaba Cloud
• OpenStack
• On-premises servers
• Cisco and generic network components
• SaaS products
• Common databases and frameworks

pip install diagrams

You must also install the Graphviz system package.

Ubuntu:

sudo apt install graphviz

Example hybrid network:

from diagrams import Cluster, Diagram, Edge
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import (
    InternetGateway,
    NATGateway,
    PrivateSubnet,
    PublicSubnet,
    TransitGateway,
    VPC
)
from diagrams.onprem.client import Users
from diagrams.onprem.network import CiscoRouter
from diagrams.onprem.compute import Server

with Diagram(
    "Hybrid Infrastructure",
    filename="hybrid-infrastructure",
    show=False,
    direction="LR"
):
    users = Users("Remote Users")
    router = CiscoRouter("Edge Router")

    with Cluster("On-Premises"):
        local_servers = Server("Linux Servers")

    transit = TransitGateway("Transit Gateway")

    with Cluster("AWS"):
        with Cluster("Production VPC"):
            vpc = VPC("10.10.0.0/16")

            with Cluster("Public Subnet"):
                public = PublicSubnet("10.10.1.0/24")
                gateway = InternetGateway("Internet Gateway")
                nat = NATGateway("NAT Gateway")

            with Cluster("Private Subnet"):
                private = PrivateSubnet("10.10.10.0/24")
                application = EC2("Application")
                database = RDS("Database")

    users >> router
    router >> Edge(label="VPN") >> transit
    transit >> vpc
    gateway >> public >> nat
    nat >> private >> application >> database
    router >> local_servers

diagrams is designed for architecture rather than live discovery. It does not inspect or configure your actual cloud resources. Diagrams documentation

2. N2G: best Python library for editable network diagrams

The relevant N2G here means Need to Graph, a Python diagram-generation library. It can generate:

• Draw.io diagrams
• yEd diagrams
• Interactive 3D visualizations
• Network topologies
• Layer 2 maps
• Layer 3 maps

Install:

pip install N2G

A simple Draw.io topology:

from N2G import drawio_diagram

diagram = drawio_diagram()
diagram.add_diagram("Network Topology")

diagram.add_node(
    id="core-01",
    label="Core Switch\n10.0.0.1"
)

diagram.add_node(
    id="access-01",
    label="Access Switch 1\n10.0.0.11"
)

diagram.add_node(
    id="access-02",
    label="Access Switch 2\n10.0.0.12"
)

diagram.add_link(
    source="core-01",
    target="access-01",
    label="TenGig1/1 ↔ TenGig1/1"
)

diagram.add_link(
    source="core-01",
    target="access-02",
    label="TenGig1/2 ↔ TenGig1/1"
)

diagram.dump_file(
    filename="network-topology.drawio",
    folder="./output"
)

The major advantage is the .drawio output. An engineer can open the generated topology and manually reposition, annotate, or correct it.

That makes it better than a PNG-only system for professional network documentation.

3. Nornir: orchestration and inventory

Nornir does not make diagrams itself. It manages network-device inventory and runs collection tasks concurrently.

pip install nornir nornir-netmiko

Use it to gather:

• CDP neighbors
• LLDP neighbors
• Interface information
• VLAN assignments
• Port channels
• Routing neighbors
• IP addresses
• Device models
• Serial numbers
• Software versions

The data can then be passed to N2G, Graphviz, or Draw.io generation.

The workflow would be:

flowchart LR
    A["Nornir inventory"] --> B["Netmiko or NAPALM"]
    B --> C["CDP, LLDP and interfaces"]
    C --> D["Normalize topology data"]
    D --> E["N2G or Graphviz"]
    E --> F["Draw.io, SVG and PDF"]

4. Netmiko: command collection

Netmiko is useful when the topology agent needs to SSH into Cisco or other network devices and execute commands.

pip install netmiko

Example:

from netmiko import ConnectHandler

device = {
    "device_type": "cisco_ios",
    "host": "10.0.0.1",
    "username": "admin",
    "password": "password"
}

with ConnectHandler(**device) as connection:
    cdp = connection.send_command(
        "show cdp neighbors detail",
        use_textfsm=True
    )

    interfaces = connection.send_command(
        "show interfaces status",
        use_textfsm=True
    )

The agent could combine the neighbor data from multiple switches and construct the topology automatically.

Credentials should come from environment variables or a secret manager—not source code.

5. NAPALM: normalized multi-vendor data

NAPALM gives a relatively consistent Python interface across supported vendors.

pip install napalm

It can retrieve information such as:

• Interfaces
• LLDP neighbors
• ARP entries
• MAC information
• BGP neighbors
• Device facts
• Configuration
• VLANs

from napalm import get_network_driver

driver = get_network_driver("ios")
device = driver(
    hostname="10.0.0.1",
    username="admin",
    password="password"
)

device.open()

facts = device.get_facts()
interfaces = device.get_interfaces()
neighbors = device.get_lldp_neighbors_detail()

device.close()

NAPALM is especially valuable when the environment contains multiple vendors because it reduces the amount of vendor-specific parsing.

6. Cisco pyATS and Genie

For Cisco-heavy environments, pyATS and Genie are extremely valuable.

They can:

• Connect to Cisco devices
• Parse command output into structured data
• Learn network features
• Compare network states
• Validate configurations
• Identify changes between snapshots

pip install pyats genie

Instead of manually parsing this:

Device ID    Local Intrfce    Holdtme    Capability
SBN-SW-02    Ten 1/1          122        R S I

Genie can convert command output into structured dictionaries that your agent can feed into a diagram generator.

For your Cisco background, a strong stack would be:

pyATS/Genie → structured Cisco data
NetworkX    → topology model and analysis
N2G         → editable Draw.io diagram
Graphviz    → polished SVG/PDF

7. NetworkX: topology intelligence

NetworkX should represent the topology internally, even if another package draws it.

import networkx as nx

topology = nx.MultiGraph()

topology.add_node(
    "core-01",
    role="core",
    management_ip="10.0.0.1"
)

topology.add_node(
    "access-01",
    role="access",
    management_ip="10.0.0.11"
)

topology.add_edge(
    "core-01",
    "access-01",
    local_interface="TenGig1/1",
    remote_interface="TenGig1/1",
    link_type="trunk"
)

NetworkX lets the agent answer questions such as:

• Is a device disconnected?
• Are there redundant paths?
• Which switch is a single point of failure?
• What devices depend on this core switch?
• Are there unexpected topology loops?
• What changed since the previous discovery?
• What is the shortest path between two devices?

NetworkX itself provides basic drawing, but its documentation states that analysis—not advanced visualization—is its primary purpose. NetworkX documentation

8. AWS diagram-as-code

AWS Labs has a diagram-as-code project that describes AWS architecture in YAML.

It is useful when you want:

• AWS-specific architecture
• Human-readable YAML
• Git version control
• Repeatable rendering
• Standardized AWS visuals

The AWS Labs project focuses specifically on generating AWS infrastructure diagrams from YAML.

This could be easier for an AI agent than writing complex layout logic directly in Python.

9. Existing cloud-environment discovery

There is an important difference between:

Designed architecture

You tell the agent what the cloud should look like.

Use:

• diagrams
• AWS diagram-as-code
• Graphviz

Discovered architecture

The agent connects to a cloud account and determines what currently exists.

Use:

• boto3 for AWS
• Azure SDK for Python
• Google Cloud Python SDKs
• NetworkX for the internal resource graph
• N2G, Graphviz, or custom SVG for rendering

For AWS:

pip install boto3 networkx

import boto3

ec2 = boto3.client("ec2")

vpcs = ec2.describe_vpcs()["Vpcs"]
subnets = ec2.describe_subnets()["Subnets"]
route_tables = ec2.describe_route_tables()["RouteTables"]
instances = ec2.describe_instances()["Reservations"]
security_groups = ec2.describe_security_groups()["SecurityGroups"]

The agent can build relationships among:

• Organizations and accounts
• Regions
• VPCs
• Availability Zones
• Public and private subnets
• Route tables
• Internet gateways
• NAT gateways
• Transit gateways
• VPN connections
• EC2 instances
• Load balancers
• Databases
• Security groups
• VPC endpoints

The original open-source CloudMapper once offered AWS network visualization, but its repository now says that visualization functionality is no longer maintained. I would not build a new agent around that original implementation. CloudMapper repository

My strongest recommendation

For a serious network and cloud document agent, use:

Collection
├── Nornir
├── Netmiko
├── NAPALM
├── pyATS/Genie
├── boto3
├── Azure SDK
└── Google Cloud SDK

Modeling and analysis
├── NetworkX
├── Pydantic
└── Pandas

Diagram generation
├── N2G
├── Diagrams
├── Graphviz
└── PyVis

Output
├── Draw.io
├── SVG
├── PDF
├── PNG
└── Interactive HTML

Best practical combination for you

Given your Cisco, AWS, Linux, cabling, and data-center interests, I would choose:

1. pyATS/Genie for Cisco discovery and parsing.
2. Nornir for managing multiple devices.
3. NetworkX for building and analyzing the topology.
4. N2G for editable Draw.io network maps.
5. diagrams for polished cloud and hybrid architecture.
6. Graphviz for clean automated layouts and SVG/PDF export.
7. boto3 for discovering actual AWS infrastructure.

That stack could support both:

• As-designed documentation: what the infrastructure is supposed to be.
• As-built documentation: what discovery shows actually exists.

A high-quality agent should preserve both and flag differences between them.