# ryan0114/clin-bhc-summ architecture

> Architecture diagram of the GitHub repository ryan0114/clin-bhc-summ, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ryan0114/clin-bhc-summ
- Repository: https://github.com/ryan0114/clin-bhc-summ

## Overview

This repository is a research pipeline for hospital-course summarization: prepare MIMIC-IV-BHC notes, fine-tune or prompt language models, generate summaries, and score outputs. Its main runtime paths are the PEFT training and inference scripts and the discrete-prompting runner, with shared argument, configuration, and data-processing code. The README also documents GPT and Llama notebook workflows. Those notebook internals and several source modules were not sampled, so their connections are shown only where the README documents them.

Main entry points: [`src/train_peft.py`](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/train_peft.py) (PEFT training), [`src/calc_metrics.py`](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/calc_metrics.py) (Metric calculation), [`src/process.py`](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/process.py) (Data and prompts), [`src/run_peft.py`](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/run_peft.py) (PEFT inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_mimic["MIMIC-IV-BHC source"]
  node_preprocessing["Dataset preprocessing"]
  node_token_filter["Token filtering"]
end

subgraph group_shared["Shared runtime"]
  node_config["Models and cases<br/>[constants.py]"]
  node_arguments["Arguments and paths<br/>[parser.py]"]
  node_data_processing["Data and prompts<br/>[process.py]"]
end

subgraph group_train["Model adaptation"]
  node_peft_training["PEFT training<br/>[train_peft.py]"]
  node_clm_training["Causal LM training<br/>[run_clm.py]"]
  node_adapter_merge["Adapter merging"]
  node_peft_notebook["QLoRA notebook<br/>[llama2_peft.ipynb]"]
  node_training_script["Model training script<br/>[train_peft.sh]"]
end

subgraph group_infer["Summarization and evaluation"]
  node_peft_inference["PEFT inference<br/>[run_peft.py]"]
  node_discrete_inference["Discrete prompting<br/>[run_discrete.py]"]
  node_gpt_notebook["GPT prompting"]
  node_llama_notebook["Llama inference"]
  node_summary_outputs["Summary outputs"]
  node_metric_calculation["Metric calculation<br/>[calc_metrics.py]"]
  node_metric_outputs["Metric results"]
end

node_researcher(("Researcher"))

node_researcher -->|"prepares dataset"| node_preprocessing
node_mimic -->|"reads notes"| node_preprocessing
node_preprocessing -.-> node_token_filter
node_researcher -->|"fine-tunes models"| node_peft_notebook
node_researcher -->|"fine-tunes models"| node_training_script
node_training_script -.->|"runs training"| node_peft_training
node_researcher -.->|"trains model"| node_clm_training
node_peft_training -->|"parses arguments"| node_arguments
node_peft_training -->|"reads settings"| node_config
node_peft_training -->|"loads and batches data"| node_data_processing
node_peft_training -.-> node_adapter_merge
node_researcher -->|"runs prompting"| node_discrete_inference
node_researcher -->|"runs tuned models"| node_peft_inference
node_researcher -->|"runs prompting"| node_gpt_notebook
node_researcher -->|"runs inference"| node_llama_notebook
node_discrete_inference -->|"parses arguments"| node_arguments
node_discrete_inference -->|"reads model settings"| node_config
node_discrete_inference -->|"loads and saves data"| node_data_processing
node_peft_inference -->|"parses arguments"| node_arguments
node_peft_inference -->|"loads model settings"| node_config
node_peft_inference -->|"loads and saves data"| node_data_processing
node_data_processing -->|"writes summaries"| node_summary_outputs
node_researcher -->|"scores outputs"| node_metric_calculation
node_metric_calculation -->|"parses arguments"| node_arguments
node_metric_calculation -->|"loads summaries"| node_data_processing
node_metric_calculation -->|"reads predictions"| node_summary_outputs
node_metric_calculation -->|"writes metrics"| node_metric_outputs

click node_preprocessing "https://github.com/ryan0114/clin-bhc-summ/blob/main/utils/mimic_iv_bhc_preprocessing.py"
click node_token_filter "https://github.com/ryan0114/clin-bhc-summ/blob/main/utils/filter_data_by_token.ipynb"
click node_config "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/constants.py"
click node_arguments "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/parser.py"
click node_data_processing "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/process.py"
click node_peft_training "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/train_peft.py"
click node_clm_training "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/run_clm.py"
click node_adapter_merge "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/merge_adapter_weights.py"
click node_peft_inference "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/run_peft.py"
click node_discrete_inference "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/run_discrete.py"
click node_gpt_notebook "https://github.com/ryan0114/clin-bhc-summ/blob/main/inference/gpt_inference.ipynb"
click node_llama_notebook "https://github.com/ryan0114/clin-bhc-summ/blob/main/inference/llama2_inference.ipynb"
click node_metric_calculation "https://github.com/ryan0114/clin-bhc-summ/blob/main/src/calc_metrics.py"
click node_peft_notebook "https://github.com/ryan0114/clin-bhc-summ/blob/main/training/llama2_peft.ipynb"
click node_training_script "https://github.com/ryan0114/clin-bhc-summ/blob/main/training/train_peft.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mimic,node_preprocessing,node_token_filter toneBlue
class node_config,node_arguments,node_data_processing toneAmber
class node_peft_training,node_clm_training,node_adapter_merge,node_peft_notebook,node_training_script toneMint
class node_peft_inference,node_discrete_inference,node_gpt_notebook,node_llama_notebook,node_summary_outputs,node_metric_calculation,node_metric_outputs toneRose
class node_researcher toneIndigo
```

## Components

### Data preparation

- **MIMIC-IV-BHC source**
- [Dataset preprocessing](https://github.com/ryan0114/clin-bhc-summ/blob/main/utils/mimic_iv_bhc_preprocessing.py): `utils/mimic_iv_bhc_preprocessing.py`
- [Token filtering](https://github.com/ryan0114/clin-bhc-summ/blob/main/utils/filter_data_by_token.ipynb): `utils/filter_data_by_token.ipynb`

### Shared runtime

- [Models and cases](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/constants.py): `src/constants.py`
- [Arguments and paths](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/parser.py): `src/parser.py`
- [Data and prompts](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/process.py): `src/process.py`

### Model adaptation

- [PEFT training](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/train_peft.py): `src/train_peft.py`
- [Causal LM training](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/run_clm.py): `src/run_clm.py`
- [Adapter merging](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/merge_adapter_weights.py): `src/merge_adapter_weights.py`
- [QLoRA notebook](https://github.com/ryan0114/clin-bhc-summ/blob/main/training/llama2_peft.ipynb): `training/llama2_peft.ipynb`
- [Model training script](https://github.com/ryan0114/clin-bhc-summ/blob/main/training/train_peft.sh): `training/train_peft.sh`

### Summarization and evaluation

- [PEFT inference](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/run_peft.py): `src/run_peft.py`
- [Discrete prompting](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/run_discrete.py): `src/run_discrete.py`
- [GPT prompting](https://github.com/ryan0114/clin-bhc-summ/blob/main/inference/gpt_inference.ipynb): `inference/gpt_inference.ipynb`
- [Llama inference](https://github.com/ryan0114/clin-bhc-summ/blob/main/inference/llama2_inference.ipynb): `inference/llama2_inference.ipynb`
- **Summary outputs**
- [Metric calculation](https://github.com/ryan0114/clin-bhc-summ/blob/main/src/calc_metrics.py): `src/calc_metrics.py`
- **Metric results**

### Other components

- **Researcher**

## Connections

- Researcher → Dataset preprocessing: prepares dataset (evidence: `README.md`)
- MIMIC-IV-BHC source → Dataset preprocessing: reads notes (evidence: `utils/mimic_iv_bhc_preprocessing.py`)
- Dataset preprocessing → Token filtering
- Researcher → QLoRA notebook: fine-tunes models (evidence: `README.md`)
- Researcher → Model training script: fine-tunes models (evidence: `README.md`)
- Model training script → PEFT training: runs training
- Researcher → Causal LM training: trains model
- PEFT training → Arguments and paths: parses arguments (evidence: `src/train_peft.py`)
- PEFT training → Models and cases: reads settings (evidence: `src/train_peft.py`)
- PEFT training → Data and prompts: loads and batches data (evidence: `src/train_peft.py`)
- PEFT training → Adapter merging
- Researcher → Discrete prompting: runs prompting (evidence: `README.md`)
- Researcher → PEFT inference: runs tuned models (evidence: `README.md`)
- Researcher → GPT prompting: runs prompting (evidence: `README.md`)
- Researcher → Llama inference: runs inference (evidence: `README.md`)
- Discrete prompting → Arguments and paths: parses arguments (evidence: `src/run_discrete.py`)
- Discrete prompting → Models and cases: reads model settings (evidence: `src/run_discrete.py`)
- Discrete prompting → Data and prompts: loads and saves data (evidence: `src/run_discrete.py`)
- PEFT inference → Arguments and paths: parses arguments (evidence: `src/run_peft.py`)
- PEFT inference → Models and cases: loads model settings (evidence: `src/run_peft.py`)
- PEFT inference → Data and prompts: loads and saves data (evidence: `src/run_peft.py`)
- Data and prompts → Summary outputs: writes summaries (evidence: `src/process.py`)
- Researcher → Metric calculation: scores outputs (evidence: `README.md`)
- Metric calculation → Arguments and paths: parses arguments (evidence: `src/calc_metrics.py`)
- Metric calculation → Data and prompts: loads summaries (evidence: `src/calc_metrics.py`)
- Metric calculation → Summary outputs: reads predictions (evidence: `src/calc_metrics.py`)
- Metric calculation → Metric results: writes metrics (evidence: `src/calc_metrics.py`)