# wyl-willing/mindmap architecture

> Architecture diagram of the GitHub repository wyl-willing/mindmap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wyl-willing/mindmap
- Repository: https://github.com/wyl-willing/mindmap

## Overview

##### Project type and purpose
- This is an ML research codebase implementing “MindMap,” a prompting framework that uses knowledge-graph prompting to elicit graph-of-thought reasoning in large language models (LLMs).
- It is not a web app or service but a Python pipeline: data preparation, knowledge graph construction (Neo4j), LLM prompting (OpenAI API), and evaluation.

##### File structure
- Top-level:
- MindMap.py – the orchestration script
- data/ – raw and preprocessed datasets for three tasks (chatdoctor5k, cmcqa, explainpe)
- pre-training/ – scripts to construct or transform data into KG or embeddings
- evaluation/ – notebooks and scripts to score and compare outputs
- output/ – results of running MindMap.py on each dataset
- requirements.txt
- Patterns:
- A core driver (MindMap.py) that loads data, connects to Neo4j, invokes the prompt generation & LLM calls, and writes outputs.
- Separate subfolders for dataset-specific preprocessing, indicating a modular approach.
- Evaluation is decoupled from generation, enabling reproducible metrics.

##### README for additional insights
- Confirms the pipeline: build KG in Neo4j (EMCKG for chatdoctor5k), then prompt the LLM with graph structures, then generate evidence-grounded text.
- External dependencies: Neo4j sandbox, OpenAI API.

##### Detail and comprehensiveness
- Subfolder as part of either Data Prep or Pre-training modules.
- How entity_embeddings.pkl, word2vec.model feed into the KG builder.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data Storage"
        DS1["chatdoctor5k"]:::data
        DS2["cmcqa"]:::data
        DS3["explainpe"]:::data
    end
    click DS1 "https://github.com/wyl-willing/mindmap/tree/main/data/chatdoctor5k"
    click DS2 "https://github.com/wyl-willing/mindmap/tree/main/data/cmcqa"
    click DS3 "https://github.com/wyl-willing/mindmap/tree/main/data/explainpe"

    subgraph "Pre-training Modules"
        PT1["csvToDocument (chatdoctor5k)"]:::compute
        PT2["csvToKG (chatdoctor5k)"]:::compute
        PT3["encode_keyword_entity (chatdoctor5k)"]:::compute
        PT4["word2vec (chatdoctor5k)"]:::compute
        PT5["jsonToDocument (cmcqa)"]:::compute
        PT6["MindMap_CMCQA"]:::compute
        PT7["keyword (explainpe)"]:::compute
    end
    click PT1 "https://github.com/wyl-willing/mindmap/blob/main/pre-training/chatdoctor5k/csvTodocument.py"
    click PT2 "https://github.com/wyl-willing/mindmap/blob/main/pre-training/chatdoctor5k/csvTokg.py"
    click PT3 "https://github.com/wyl-willing/mindmap/blob/main/pre-training/chatdoctor5k/encode_keyword_entity.py"
    click PT4 "https://github.com/wyl-willing/mindmap/blob/main/pre-training/chatdoctor5k/word2vec.py"
    click PT5 "https://github.com/wyl-willing/mindmap/blob/main/pre-training/cmcqa/jsonTodocument.py"
    click PT6 "https://github.com/wyl-willing/mindmap/blob/main/pre-training/cmcqa/MindMap_CMCQA.py"
    click PT7 "https://github.com/wyl-willing/mindmap/blob/main/pre-training/explainpe/keyword.py"

    subgraph "Knowledge Graph Service"
        Neo4j[(Neo4j Database)]:::external
    end

    subgraph "MindMap Core"
        MM["MindMap.py"]:::core
    end
    click MM "https://github.com/wyl-willing/mindmap/blob/main/MindMap.py"

    subgraph "External LLM Service"
        OpenAI[(OpenAI API)]:::external
    end

    subgraph "Output & Visualization"
        Out["CSV Results"]:::data
        Fig["Diagrams"]:::data
    end
    click Out "https://github.com/wyl-willing/mindmap/tree/main/output/"
    click Fig "https://github.com/wyl-willing/mindmap/tree/main/fig/"

    subgraph "Evaluation Suite"
        Eval1["BertScore.ipynb"]:::eval
        Eval2["GPT_4_ranking.ipynb"]:::eval
        Eval3["gpt4_preference_disease.py"]:::eval
        Eval4["gpt4_preference_drug.py"]:::eval
        Eval5["gpt4_preference_total.py"]:::eval
        Eval6["hallucination quantify"]:::eval
    end
    click Eval1 "https://github.com/wyl-willing/mindmap/blob/main/evaluation/BertScore.ipynb"
    click Eval2 "https://github.com/wyl-willing/mindmap/blob/main/evaluation/GPT_4_ranking.ipynb"
    click Eval3 "https://github.com/wyl-willing/mindmap/blob/main/evaluation/gpt4_preference_disease.py"
    click Eval4 "https://github.com/wyl-willing/mindmap/blob/main/evaluation/gpt4_preference_drug.py"
    click Eval5 "https://github.com/wyl-willing/mindmap/blob/main/evaluation/gpt4_preference_total.py"
    click Eval6 "https://github.com/wyl-willing/mindmap/tree/main/evaluation/hallucination quantify"

    DS1 --> PT1
    DS1 --> PT2
    DS1 --> PT3
    DS1 --> PT4
    DS2 --> PT5
    DS2 --> PT6
    DS3 --> PT7

    PT1 --> PT2
    PT3 --> PT2
    PT4 --> PT2
    PT5 --> PT6
    PT7 --> PT6

    PT2 --> Neo4j
    PT6 --> Neo4j

    Neo4j --> MM
    MM --> Neo4j

    MM --> OpenAI
    OpenAI --> MM

    MM --> Out

    DS1 --> Eval1
    DS2 --> Eval1
    DS3 --> Eval1

    Out --> Eval1
    Out --> Eval2
    Out --> Eval3
    Out --> Eval4
    Out --> Eval5
    Out --> Eval6

    classDef data fill:#D6EAF8,stroke:#1B4F72;
    classDef compute fill:#D5F5E3,stroke:#186A3B;
    classDef external fill:#FAD7A0,stroke:#B9770E;
    classDef core fill:#A9CCE3,stroke:#2874A6;
    classDef eval fill:#EBDEF0,stroke:#7D3C98;
```
