How ahmadvh/ai-agents-for-medical-diagnostics works
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