# lamm-mit/graphreasoning architecture

> Architecture diagram of the GitHub repository lamm-mit/graphreasoning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lamm-mit/graphreasoning
- Repository: https://github.com/lamm-mit/graphreasoning

## Overview

##### Project Type and Purpose
- This is a Python software library (“GraphReasoning”) for scientific knowledge‐graph construction, analysis, embedding, and LLM‐driven reasoning.

##### File‐Structure Analysis
- Top‐level modules under GraphReasoning/:
- graph_generation.py – build or extend a knowledge graph from text.
- graph_analysis.py – find paths, communities, centralities, scale‐free tests.
- graph_tools.py – embedding I/O, visualization, simplification, statistics.
- agents.py – conversational agent classes and simulators.
- openai_tools.py – wrappers for LLM calls (OpenAI, llama.cpp).
- utils.py – filesystem, plotting, helper routines.
- Notebooks/: Jupyter notebooks that demonstrate workflows end‐to‐end.
- setup.py, README.md, LICENSE: packaging & documentation.

##### Key Architectural Insights from README
- Data sources: GraphML files and pickled embeddings hosted on HuggingFace.
- External dependencies: transformers, llama‐cpp, powerlaw, wkhtmltopdf, huggingface_hub, networkx, pyvis.
- Core flows:
b. Multi‐agent loops for conversational reasoning.

##### Main Components & Interactions
A. Data Layer
- Raw Graph Data (GraphML) & Embeddings (PKL) – stored locally or fetched via huggingface_hub.
- Notebooks & Scripts – user‐facing clients that invoke library functions.
B. Core Processing Layer (Python Modules)
- graph_generation: “Text → Graph” pipeline using openai_tools.
- graph_analysis: “Graph → Metrics/Paths/Communities.”
- graph_tools: “Graph & Embeddings ↔ Visualization & Stats.”
- agents: “LLM Agents ↔ Conversation Simulation.”
- openai_tools: abstracts LLM API (OpenAI, llama.cpp) for all modules.
- utils: shared helpers (file I/O, plotting).
C. External Services
- HuggingFace Hub – storage & retrieval of models, data files.
- OpenAI API / llama.cpp – language model inference.
- wkhtmltopdf – HTML to PDF conversion for reports.
D. Presentation Layer
- HTML / PDF Reports (pyvis networks, matplotlib plots).
- Jupyter Notebooks – orchestrate end‐to‐end examples.

Data flows:
1. Notebooks call core modules → graph data loaded or generated.
2. graph_generation invokes openai_tools → receives LLM output → produces GraphML.
3. graph_tools loads embeddings (via huggingface_hub) → networkx graph → generate node embeddings (via openai_tools).
4. graph_analysis consumes graph & embeddings → computes metrics, paths (optionally calling openai_tools for reasoning).
5. agents orchestrate openai_tools calls for conversational reasoning.
6. graph_tools & utils produce HTML/PDF outputs saved to disk.

##### Architectural Patterns & Principles
- Modular separation: each module encapsulates one concern.
- Adapter pattern: openai_tools wraps external LLM APIs.
- Dependency injection: notebooks pass tokenizer, model, generate functions to modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        C1["Graph Analysis Notebook"]:::client
        C2["Graph Reasoning with LLM Notebook"]:::client
    end

    %% Data Layer
    subgraph "Data Layer"
        D1[(GraphML Data)]:::data
        D2[(Pickle Embeddings)]:::data
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        GGEN["graph_generation.py"]:::core
        GANAL["graph_analysis.py"]:::core
        GTOOLS["graph_tools.py"]:::core
        AGENTS["agents.py"]:::core
        OAI["openai_tools.py"]:::core
        UTILS["utils.py"]:::core
    end

    %% External Services
    subgraph "External Services"
        HF["HuggingFace Hub"]:::external
        OAPI["OpenAI API / llama.cpp"]:::external
        WK["wkhtmltopdf"]:::external
    end

    %% Presentation Outputs
    subgraph "Presentation Outputs"
        HTML["HTML/PDF Reports"]:::data
    end

    %% Packaging & Documentation
    subgraph "Packaging & Documentation"
        SP["setup.py"]:::client
        RM["README.md"]:::client
        LI["LICENSE"]:::client
    end

    %% Connections
    C1 -->|"calls"| GANAL
    C1 -->|"calls"| GTOOLS
    C2 -->|"calls"| GGEN
    C2 -->|"calls"| AGENTS

    D1 -->|"load_graph()"| GANAL
    D1 -->|"load_graph()"| GTOOLS
    D1 -->|"load_graph()"| GGEN
    D2 -->|"load_embeddings()"| GTOOLS
    D2 -->|"load_embeddings()"| GANAL

    GGEN -->|"uses"| OAI
    GTOOLS -->|"fetch_embeddings()"| HF
    GTOOLS -->|"uses"| OAI
    GANAL -->|"uses"| OAI
    AGENTS -->|"uses"| OAI

    OAI -->|"calls inference"| OAPI
    GTOOLS -->|"produce reports"| HTML
    HTML -->|"convert"| WK

    UTILS -->|"support"| GGEN
    UTILS -->|"support"| GANAL
    UTILS -->|"support"| GTOOLS
    UTILS -->|"support"| AGENTS

    %% Click Events
    click C1 "https://github.com/lamm-mit/graphreasoning/blob/main/Notebooks/GraphReasoning - Graph Analysis.ipynb"
    click C2 "https://github.com/lamm-mit/graphreasoning/blob/main/Notebooks/GraphReasoning - Graph Reasoning with LLM - BioMixtral.ipynb"
    click GGEN "https://github.com/lamm-mit/graphreasoning/blob/main/GraphReasoning/graph_generation.py"
    click GANAL "https://github.com/lamm-mit/graphreasoning/blob/main/GraphReasoning/graph_analysis.py"
    click GTOOLS "https://github.com/lamm-mit/graphreasoning/blob/main/GraphReasoning/graph_tools.py"
    click AGENTS "https://github.com/lamm-mit/graphreasoning/blob/main/GraphReasoning/agents.py"
    click OAI "https://github.com/lamm-mit/graphreasoning/blob/main/GraphReasoning/openai_tools.py"
    click UTILS "https://github.com/lamm-mit/graphreasoning/blob/main/GraphReasoning/utils.py"
    click SP "https://github.com/lamm-mit/graphreasoning/blob/main/setup.py"
    click RM "https://github.com/lamm-mit/graphreasoning/blob/main/README.md"
    click LI "https://github.com/lamm-mit/graphreasoning/tree/main/LICENSE"

    %% Styles
    classDef core fill:#a8ddb5,stroke:#2b7a0b,color:#000
    classDef data fill:#feb24c,stroke:#b25609,color:#000
    classDef external fill:#9ecae1,stroke:#2171b5,color:#000
    classDef client fill:#d9d9d9,stroke:#636363,color:#000
```
