# ahmadvh/ai-agents-for-medical-diagnostics architecture

> Architecture diagram of the GitHub repository ahmadvh/ai-agents-for-medical-diagnostics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmadvh/ai-agents-for-medical-diagnostics
- Repository: https://github.com/ahmadvh/ai-agents-for-medical-diagnostics

## Overview

##### Project type and purpose
- This is a Python-based, research/educational tool that orchestrates multiple LLM “agents” (Cardiologist, Psychologist, Pulmonologist) to analyze synthetic medical reports in parallel and produce a combined diagnosis.
- It is structured as a CLI application (Main.py) with supporting utilities (Utils/Agents.py), data folders (Medical Reports/), and output storage (Results/).

##### File structure
- Top level:
- Main.py – the orchestration entry point
- Utils/Agents.py – defines each specialized agent’s interface with the LLM
- Medical Reports/ – input data folder containing text files
- Results/ – output folder for final_diagnosis.txt
- apikey.env – environment configuration for the LLM API key
- requirements.txt – library dependencies (OpenAI SDK, threading, etc.)
- Architectural cues:
- A simple pipeline/orchestrator pattern
- Concurrency via Python threading
- Plug-in style agents that share a common interface

##### Key insights from README
- Three GPT-5 agents run in parallel
- Each agent specializes in a medical domain and returns findings
- Main.py collects, merges, and summarizes agent outputs into top health issues
- Future extensibility points: new agents, local LLMs, vision modules, real-time tools

##### Components
a. Main Components
1. Input Layer:
- Medical Reports folder (reader component)
2. Orchestrator:
- Main.py – coordinates loading, agent instantiation, threading, and merging
3. Agents (three parallel workers):
- Cardiologist Agent
- Psychologist Agent
- Pulmonologist Agent
4. External Service:
- LLM Provider API (OpenAI GPT-5)
5. Output Layer:
- Merger/Summarizer inside Main.py
- Results folder (final_diagnosis.txt)
6. Configuration Store:
- apikey.env (credentials)
- requirements.txt (dependencies)
b. Relationships and Interactions
- Data flow: Medical Reports → Orchestrator → Agents → LLM API ← Agents → Orchestrator → Results
- Control flow: Main.py spawns threads for each agent, waits for completion, then invokes merge logic
- Dependency edges: Utils/Agents.py → OpenAI SDK; Main.py → Utils/Agents.py; Main.py → apikey.env
c. Architectural Patterns & Principles
- Orchestrator pattern coordinating worker threads
- Plug-in architecture: each agent implements a shared interface so new agents can be added easily
- Single responsibility: Main.py handles orchestration, Utils/Agents.py defines domain logic per agent
- Externalization of secrets/config via apikey.env
d. Technologies & Frameworks
- Python 3.x, threading module
- OpenAI (GPT-5) SDK
- Filesystem I/O for loading reports and writing results

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    MR["Medical Reports\n(folder)"]:::datastore
    click MR "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/tree/main/Medical Reports/"

    %% Orchestrator
    Main["Main.py\n(Orchestrator)"]:::internal
    click Main "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/blob/main/Main.py"

    %% Configuration
    subgraph "Configuration" 
        direction TB
        apikey["apikey.env"]:::config
        req["requirements.txt"]:::config
        click apikey "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/blob/main/apikey.env"
        click req "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/blob/main/requirements.txt"
    end

    %% Agents Subgraph
    subgraph "Agents (parallel threads)" 
        direction TB
        CA["Cardiologist Agent"]:::internal
        PA["Psychologist Agent"]:::internal
        PU["Pulmonologist Agent"]:::internal
        click CA "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/blob/main/Utils/Agents.py"
        click PA "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/blob/main/Utils/Agents.py"
        click PU "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/blob/main/Utils/Agents.py"
    end

    %% External LLM Service
    LLM["LLM Provider API\n(OpenAI GPT-5)"]:::external

    %% Output Layer
    subgraph "Results"
        direction TB
        resultsDir["Results\n(folder)"]:::datastore
        finalDiagnosis["final_diagnosis.txt"]:::datastore
        click resultsDir "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/tree/main/Results/"
        click finalDiagnosis "https://github.com/ahmadvh/ai-agents-for-medical-diagnostics/blob/main/Results/final_diagnosis.txt"
    end

    %% Flow
    MR -->|"load reports"| Main
    Main -->|"spawn threads"| CA
    Main -->|"spawn threads"| PA
    Main -->|"spawn threads"| PU
    CA -->|"request/response"| LLM
    PA -->|"request/response"| LLM
    PU -->|"request/response"| LLM
    CA -->|"findings"| Main
    PA -->|"findings"| Main
    PU -->|"findings"| Main
    Main -->|"merge results"| finalDiagnosis

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef datastore fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef config fill:#FFF0F5,stroke:#000,stroke-width:1px,stroke-dasharray:5 5;

    %% Legend
    subgraph Legend
        direction TB
        Inp["Medical Reports / Results"]:::datastore --> Mod["Main.py / Utils/Agents.py"]:::internal --> Serv["LLM API"]:::external
        Conf["apikey.env / requirements.txt"]:::config
    end
```
