# anand-subu/automated-clinical-coding-llm architecture

> Architecture diagram of the GitHub repository anand-subu/automated-clinical-coding-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anand-subu/automated-clinical-coding-llm
- Repository: https://github.com/anand-subu/automated-clinical-coding-llm

## Overview

##### Project Type and Purpose
- This is a research/script-based implementation of an LLM-guided tree-search algorithm for automated ICD coding in clinical notes.
- It processes Spanish medical notes by first translating them to English (using GPT-3.5), then applies a tree search guided by LLM predictions (either via GPT-3.5 or Llama-2 70B Chat) to assign ICD labels, and finally evaluates the prediction performance.

##### Main Components (Modules)
A. Data Input & Preprocessing:
- Translation Module:
◦ File: translate_files.py
◦ Purpose: Translates Spanish medical notes to English using GPT-3.5.
- Dataset: The input dataset (e.g., the CodiEsp Dataset) is externally provided.

B. Core Processing – Tree Search Algorithm:
- Tree Search Module:
◦ Files: tree_search_icd.py and run_tree_search.py
◦ Purpose: Implements the iterative tree-search algorithm. It starts at the ICD ontology’s root and, with LLM-guided decision making, navigates through the predictive tree to output the relevant ICD codes.
- Prompt Templates & Helpers:
◦ Files: prompt_templates.py and helpers.py
◦ Purpose: Build and manage the prompts and configuration for interacting with the LLM APIs (for both OpenAI’s GPT variants and DeepInfra’s Llama deployment).

C. Output Predictions:
- Predictions Storage:
◦ Directory: predictions/
◦ Structure: Subdirectories (e.g., GPT-3.5 and Llama-70B) each contain model-specific output files (JSON, TSV, README) for predictions.

D. Evaluation Module:
- Evaluation Script:
◦ File: evaluate_performance.py
◦ Purpose: Evaluates the predicted ICD codes against a gold-standard dataset, converting between JSON and TSV as needed and computing macro- and micro-average metrics.

##### Relationships and Data Flow
- The process starts with raw Spanish clinical notes provided as input.
- The Translation Module (translate_files.py) consumes these notes, uses GPT-3.5 via the LLM API client (configured in helpers.py), and produces English-translated documents.
- The Tree Search Module (run_tree_search.py and tree_search_icd.py) takes the translated texts, and iteratively queries the LLM (using configurations detailed in helpers.py), utilizing templates from prompt_templates.py. This module logs predictions for each LLM (organized in separate directories under predictions/).
- The Evaluation Module (evaluate_performance.py) then reads the JSON prediction files, converts them if necessary, and compares with reference data to compute performance metrics.

##### Architectural Patterns and Design Principles
- Modular Pipeline: The system is structured as a sequential pipeline where each module (Translation → Tree Search → Evaluation) is a well-defined stage.
- Separation of Concerns: Each script handles a specific task (translation, prediction, evaluation) and communicates via intermediate files (e.g., translated files, predictions in JSON/TSV).
- External Integration: The architecture clearly shows integration points with external LLM APIs and the use of configuration details (found in helpers.py).

## Diagram (Mermaid)

```mermaid
flowchart TD
    DS["CodiEsp Dataset"]:::storage
    
    T["Translation Module (translate_files.py)"]:::processing
    
    subgraph "Core Processing"
        TS["ICD Tree Search (tree_search_icd.py)"]:::processing
        TSR["Tree Search Runner (run_tree_search.py)"]:::processing
    end

    subgraph "LLM Config"
        PT["Prompt Templates (prompt_templates.py)"]:::processing
        H["Helpers (helpers.py)"]:::processing
    end

    OAI["OpenAI GPT-3.5"]:::external
    DLI["DeepInfra Llama-2 70B Chat"]:::external

    subgraph "Predictions Storage"
        GPT["GPT-3.5 Predictions"]:::storage
        LLA["Llama-2 70B Predictions"]:::storage
    end

    E["Evaluation Module (evaluate_performance.py)"]:::processing

    %% Data Flow
    DS -->|"RawClinicalNotes"| T
    T -->|"TranslatedTexts"| TS
    TS -->|"Iteration"| TSR
    TS -->|"UsesPrompts"| PT
    TS -->|"UsesConfig"| H
    PT -->|"APICall"| OAI
    PT -->|"APICall"| DLI
    H -->|"APICall"| OAI
    H -->|"APICall"| DLI
    TSR -->|"LLMPredictions"| GPT
    TSR -->|"LLMPredictions"| LLA
    GPT -->|"EvaluatedPredictions"| E
    LLA -->|"EvaluatedPredictions"| E

    %% Click Events
    click T "https://github.com/anand-subu/automated-clinical-coding-llm/blob/main/translate_files.py"
    click TS "https://github.com/anand-subu/automated-clinical-coding-llm/blob/main/tree_search_icd.py"
    click TSR "https://github.com/anand-subu/automated-clinical-coding-llm/blob/main/run_tree_search.py"
    click PT "https://github.com/anand-subu/automated-clinical-coding-llm/blob/main/prompt_templates.py"
    click H "https://github.com/anand-subu/automated-clinical-coding-llm/blob/main/helpers.py"
    click GPT "https://github.com/anand-subu/automated-clinical-coding-llm/blob/main/predictions/GPT-3.5"
    click LLA "https://github.com/anand-subu/automated-clinical-coding-llm/tree/main/predictions/Llama-70B"
    click E "https://github.com/anand-subu/automated-clinical-coding-llm/blob/main/evaluate_performance.py"

    %% Styles
    classDef processing fill:#d1e8ff,stroke:#333,stroke-width:2px;
    classDef storage fill:#d0f0c0,stroke:#333,stroke-width:2px;
    classDef external fill:#ffda79,stroke:#333,stroke-width:2px;
```
