# huiziy/aipatient architecture

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

- Interactive diagram: https://gitdiagram.com/huiziy/aipatient
- Repository: https://github.com/huiziy/aipatient

## Overview

##### Project type and purpose
- This is a research‐oriented full-stack application that builds LLM-powered simulated patients (“AIPatient”) from EHR data.
- Core purpose: ingest MIMIC III records, extract entities/relations into a Neo4j knowledge graph, power a multi-agent LLM system (Reasoning RAG: retrieval, reasoning, generation, memory) and expose it via a Streamlit interface for interactive medical training.
- There is also an out-of-distribution variant (AIPatient_OOD) and an analysis suite (AIPatient_Analysis) for ablation, robustness, readability, stability evaluations.

##### File structure
- Top-level folders:
- AIPatient_Analysis – data cleaning, KG construction, LLM model wrappers, evaluation modules, ablation studies.
- AIPatient_Interface – Streamlit app, agent orchestration, Neo4j interface, prompts.
- AIPatient_OOD – similar pipeline for out-of-distribution data (Coral dataset) and evaluation.
- fig – architecture and result figures.
- Key patterns:
- Modular Python packages (each subfolder has __init__.py).
- Separation of concerns: data ingestion/cleaning → graph construction → LLM model → evaluation.
- Config files at each component.
- Jupyter notebooks for prototyping (main.ipynb, main_OOD.ipynb).
- Streamlit is the sole frontend; backend components are Python modules.
- Neo4jDatabase modules in both Analysis and Interface for graph persistence and visualization.

##### README for additional insights
- High-level architecture described in Figure 1: EHR → KG → multi-agent system → user interface.
- Multi-agent design: retrieval agent, reasoning agent, generation agent, memory preservation.
- Uses Anthropic Claude via Amazon Bedrock as external service.
- Future plans: evaluator agent for feedback loops.

##### Final advice
- Config.py modules to denote parameterization points.
- Don’t overthink: list all 7 major subsystems plus evaluation branches and external API, connect them logically.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% AIPatient Analysis (MIMIC)
    subgraph "AIPatient_Analysis (MIMIC Pipeline)"
        direction TB
        subgraph "Data Ingestion & Cleaning"
            direction TB
            DC1["create_dataframe"]:::processing
            DC2["data_cleaning_mimic_class"]:::processing
        end
        subgraph "Knowledge Graph Construction"
            direction TB
            GC1["entity_creation"]:::processing
        end
        subgraph "Neo4j Database"
            direction TB
            NDB1["Neo4jDatabase_class"]:::storage
            NDB2["Neo4jDatabase_visualizer"]:::storage
        end
        LLM_A["llm_model_class"]:::agent
        subgraph "Evaluations"
            direction TB
            EVA1["ablation_study_class"]:::evaluation
            EVA2["readability_evaluation_class"]:::evaluation
            EVA3["robustness_evaluation_class"]:::evaluation
            EVA4["stability_evaluation_class"]:::evaluation
        end
    end

    DC1 -->|feeds into| DC2
    DC2 -->|feeds into| GC1
    GC1 -->|pushes to| NDB1
    NDB1 -->|visualized by| NDB2
    NDB1 -->|queried by| LLM_A
    LLM_A -->|outputs to| EVA1
    LLM_A -->|outputs to| EVA2
    LLM_A -->|outputs to| EVA3
    LLM_A -->|outputs to| EVA4

    %% AIPatient Interface
    subgraph "AIPatient_Interface (Main App)"
        direction TB
        UI["Streamlit Interface"]:::interface
        CFG["config.py"]:::processing
        subgraph "Neo4j Database (Interface)"
            direction TB
            NDB_I["Neo4jDatabase_class"]:::storage
        end
        subgraph "Graph Construction (Interface)"
            direction TB
            GC_I["entity_creation"]:::processing
        end
        subgraph "LLM & Agents"
            direction TB
            LLM_I["llm_model_class"]:::agent
            AGT["agents_class"]:::agent
            PRM["prompts"]:::agent
        end
    end

    UI -->|reads config| CFG
    UI -->|invokes| LLM_I
    LLM_I -->|uses prompts| PRM
    LLM_I -->|coordinated by| AGT
    AGT -->|retrieves from| NDB_I
    AGT -->|constructs context via| GC_I
    GC_I -->|pushes to| NDB_I
    AGT -->|returns response to| UI

    %% External Service
    External["Anthropic Claude (Amazon Bedrock)"]:::external
    AGT -->|calls| External
    External -->|returns| AGT

    %% AIPatient OOD
    subgraph "AIPatient_OOD (Coral Pipeline)"
        direction TB
        subgraph "Data Ingestion & Cleaning (OOD)"
            direction TB
            ODC1["create_dataframe"]:::processing
            ODC2["data_cleaning_class"]:::processing
        end
        subgraph "Knowledge Graph Construction (OOD)"
            direction TB
            OGC1["entity_creation"]:::processing
        end
        subgraph "Neo4j Database (OOD)"
            direction TB
            NDB_O["Neo4jDatabase_class"]:::storage
        end
        OLLM["llm_model_class"]:::agent
        subgraph "Evaluations (OOD)"
            direction TB
            OEA1["ablation_study_class"]:::evaluation
            OEA2["readability_evaluation_class"]:::evaluation
            OEA3["robustness_evaluation_class"]:::evaluation
            OEA4["stability_evaluation_class"]:::evaluation
        end
    end

    ODC1 --> ODC2
    ODC2 --> OGC1
    OGC1 --> NDB_O
    NDB_O --> OLLM
    OLLM --> OEA1
    OLLM --> OEA2
    OLLM --> OEA3
    OLLM --> OEA4

    %% Click Events - Analysis
    click DC1 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/data_cleaning_mimic/data_cleaning_function/create_dataframe.py"
    click DC2 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/data_cleaning_mimic/data_cleaning_mimic_class.py"
    click GC1 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/graph_construction/graph_construction_function/entity_creation.py"
    click NDB1 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/Neo4jDatabase/Neo4jDatabase_class.py"
    click NDB2 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/Neo4jDatabase/Neo4jDatabase_visualizer.py"
    click LLM_A "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/llm_models/llm_model_class.py"
    click EVA1 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/ablation_study/ablation_study_class.py"
    click EVA2 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/readability_evaluation/readability_evaluation_class.py"
    click EVA3 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/robustness_evaluation/robustness_evaluation_class.py"
    click EVA4 "https://github.com/huiziy/aipatient/blob/main/AIPatient_Analysis/code/stability_evaluation/stability_evaluation_class.py"

    %% Click Events - Interface
    click UI "https://github.com/huiziy/aipatient/blob/main/AIPatient_Interface/AIPatient_Interface.py"
    click CFG "https://github.com/huiziy/aipatient/blob/main/AIPatient_Interface/config.py"
    click NDB_I "https://github.com/huiziy/aipatient/blob/main/AIPatient_Interface/Neo4jDatabase/Neo4jDatabase_class.py"
    click GC_I "https://github.com/huiziy/aipatient/blob/main/AIPatient_Interface/graph_construction/graph_construction_function/entity_creation.py"
    click LLM_I "https://github.com/huiziy/aipatient/blob/main/AIPatient_Interface/llm_models/llm_model_class.py"
    click AGT "https://github.com/huiziy/aipatient/blob/main/AIPatient_Interface/agents/agents_class.py"
    click PRM "https://github.com/huiziy/aipatient/blob/main/AIPatient_Interface/agents/agents_functions/prompts.py"

    %% Click Events - OOD
    click ODC1 "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/data_cleaning_coral/data_cleaning_function/create_dataframe.py"
    click ODC2 "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/data_cleaning_coral/data_cleaning_class.py"
    click OGC1 "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/graph_construction/graph_construction_function/entity_creation.py"
    click NDB_O "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/Neo4jDatabase/Neo4jDatabase_class.py"
    click OLLM "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/llm_models/llm_model_class.py"
    click OEA1 "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/ablation_study/ablation_study_class.py"
    click OEA2 "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/readability_evaluation/readability_evaluation_class.py"
    click OEA3 "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/robustness_evaluation/robustness_evaluation_class.py"
    click OEA4 "https://github.com/huiziy/aipatient/blob/main/AIPatient_OOD/code/stability_evaluation/stability_evaluation_class.py"

    %% Styles
    classDef processing fill:#a8d08d,color:#000;
    classDef storage fill:#9dc3e6,color:#000;
    classDef agent fill:#f4b183,color:#000;
    classDef interface fill:#b4a7d6,color:#000;
    classDef evaluation fill:#ffe599,color:#000;
    classDef external fill:#d9d9d9,color:#000;
```
