🕵️‍♂️ Email-Tracer: GraphRAG Compliance Investigation Tool

An advanced GraphRAG (Retrieval-Augmented Generation) forensic audit tool designed to investigate communication networks, extract semantic relations, and trace compliance paths within large-scale email archives (such as the Enron Corpus).

By merging dense vector embeddings (for semantic concept retrieval) with structural network topology (for multi-hop relation analysis), the tool solves complex investigative compliance questions that traditional flat-text search tools miss.

---

🏗️ System Architecture

The following diagram illustrates how the system ingests raw emails, constructs the multi-relational knowledge graph, indexes contents semantically, and traverses connections to solve compliance queries:

graph TD
    A[Raw CSV Email Dump] --> B[Email Header & Body Parser]
    B --> C[Name Normalizer & Entity Resolver]
    B --> D[Rule & NLP Topic Matcher]
    
    C --> E[Knowledge Graph Builder - NetworkX]
    D --> E
    
    E --> F[Hybrid Search Engine]
    B --> G[SentenceTransformer Embedding Index]
    G --> F
    
    F --> H[Forensic Query Interface]
    H --> I[Q1: Raptor Connector Paths]
    H --> J[Q2: Legal-Trading Bridges]
    H --> K[Q3: Budget-Offshore Links]
    
    E --> L[Visualizer - PyVis & Matplotlib]
    L --> M[Interactive HTML Graph]
    L --> N[Static PNG Layout]

Loading

---

⚡ Key Features

• Multi-Relational Knowledge Graph: Models communication patterns (EMAILED relation edges) alongside content categories (TALKS_ABOUT relation edges) for both People and Topic nodes.
• Smart Name Normalization: Resolves entity aliases, email address variants, and directory formatting using regex cleaning, preventing broken paths in network traversal.
• Hybrid Vector-Graph Retrieval: Embeds text chunks via all-MiniLM-L6-v2 for conceptual queries while traversing communication paths dynamically using shortest-path algorithms.
• Bridges & Centrality Auditing: Identifies topological and functional bridging nodes between disparate corporate departments (e.g., Legal vs. Trading).
• Rich Graph Visualizations: Generates physics-simulated interactive HTML visualizations via PyVis and static network layouts via Matplotlib.

---

📊 Compliance Case Studies (Enron Evaluation)

🔍 Q1: Kenneth Lay to Jeffrey Skilling (Topic: "Raptor")

• Finding: No direct communication containing the term "Raptor" exists between Lay and Skilling.
• Bridge Identified: Steven J. Kean (Chief of Staff) and Mark Koenig (Investor Relations).
• Trace Path: $$\text{Kenneth Lay} \longleftrightarrow \text{Steven Kean} \longleftrightarrow \text{Jeffrey Skilling}$$
• Detail: Steve Kean acted as the administrative pivot point, receiving spreadsheet write-downs of the Raptor partnerships, while Mark Koenig routed whistleblower concerns regarding Raptor unwinds to Kean and the legal team.

⚖️ Q2: Legal Team to Trading Desk Bridge (Topic: "Energy Contracts")

• Finding: Stacey Richardson (Credit Analyst) acts as the primary functional bridge between Legal and Trading on contract approvals.
• Bridge Count: Stacey Richardson lies on 272 shortest communication paths between Legal draftspersons (Mark Taylor, Tana Jones, Sara Shackleton) and Trading desks (Chris Germany).
• Detail: She reviews and signs off on credit guidelines and master netting agreements (ISDAs), serving as the mandatory gatekeeper between legal terms and trade execution.

💰 Q3: Budget Discussions to Offshore Entities Link

• Finding: Senior managers Susan Mara and Louise Kitchen directly overlap, holding roles in both budget allocation and offshore entities.
• Trace Path (No Overlap): If overlapping personnel are excluded, the shortest connection is a 1-hop communication link: $$\text{amy.kim@enron.com (Budget)} \longleftrightarrow \text{ginger.dernehl@enron.com (Offshore)}$$ with 16 direct emails establishing the connection.

---

🛠️ Installation & Setup

Prerequisites

Make sure Python 3.8+ is installed. Clone the repository and install dependencies:

git clone https://github.com/957908/email-tracer.git
cd email-tracer
pip install -r requirements.txt

Run the Pipeline

Place your email dataset at the path configured in graph_rag.py and run:

python graph_rag.py

Utility: Convert Graph Formats

Convert the GEXF graph file to JSON:

python gexf_to_json.py

Convert the PyVis visualization nodes/edges to JSON:

python convert_html_graph.py

---

📂 Output Deliverables

• graph_export.gexf: Exported NetworkX graph for loading into Gephi or Neo4j.
• graph_export.json: Graph structure represented in node-link JSON format.
• graph_visualization.html: Interactive browser-based visualization (colors: Blue = People, Red = Topics).
• graph_visualization.json: Coordinates, colors, and labels extracted from the visual layout.
• visualization_screenshot.png: High-resolution network topology plot.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.