# imyangc7/lungnoduleagent architecture

> Architecture diagram of the GitHub repository imyangc7/lungnoduleagent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imyangc7/lungnoduleagent
- Repository: https://github.com/imyangc7/lungnoduleagent

## Overview

LungNoduleAgent turns CT cases into AIS/MIA/IAC diagnoses. The main workflow accepts an image and optional mask or report, then runs detection, sizing, report generation, and multi-agent diagnosis in order; the pipeline returns a diagnosis trace. The README also documents standalone MoE detection and optional GraphRAG retrieval. Stage wiring is supported by the sampled pipeline and README; details inside unsampled stage implementations are represented only where documented.

Main entry points: [`pipeline.py`](https://github.com/imyangc7/lungnoduleagent/blob/main/pipeline.py) (Pipeline Orchestrator), [`nodule_spotter/pipeline.py`](https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/pipeline.py) (Spotter Pipeline), [`agentbase/model/litellm_model.py`](https://github.com/imyangc7/lungnoduleagent/blob/main/agentbase/model/litellm_model.py) (LLM Adapter), [`lung_agents/orchestrator.py`](https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/orchestrator.py) (Debate Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Case Pipeline"]
  node_entry["CLI Entry<br/>[main.py]"]
  node_orchestrator["Pipeline Orchestrator<br/>[pipeline.py]"]
  node_case_state["Case State<br/>[case.py]"]
end

subgraph group_detection["Nodule Detection"]
  node_spot_stage["Spotter Stage<br/>[spotter.py]"]
  node_spot_pipeline["Spotter Pipeline<br/>[pipeline.py]"]
  node_detectors["Detector Experts"]
  node_moe["Detector MoE<br/>[moe.py]"]
  node_cluster["Mask Clustering<br/>[clustering.py]"]
  node_panel["VLM Panel<br/>[judging_panel.py]"]
end

subgraph group_reporting["Measurement And Reports"]
  node_sizer_stage["Sizer Stage<br/>[sizer.py]"]
  node_measurement["Nodule Measurement<br/>[measure.py]"]
  node_radiologist_stage["Radiologist Stage<br/>[radiologist.py]"]
  node_dam["DAM Report Generation"]
  node_dam_server["DAM Server<br/>[dam_server.py]"]
end

subgraph group_diagnosis["Clinical Debate"]
  node_doctor_stage["Doctor Stage<br/>[doctor.py]"]
  node_debate["Debate Orchestrator<br/>[orchestrator.py]"]
  node_judges["Specialist Judges<br/>[judge_agent.py]"]
  node_summary["Summary Agent<br/>[summary_agent.py]"]
  node_graphrag_tool["GraphRAG Tool<br/>[tool.py]"]
  node_retriever["GraphRAG Retriever<br/>[retriever.py]"]
end

subgraph group_shared["Agent Runtime"]
  node_model["LLM Adapter<br/>[litellm_model.py]"]
end

node_user(("Clinician / Operator"))
node_case_input["CT Case Inputs"]
node_result["Diagnosis Trace"]
node_llm_service{{"LLM Provider"}}

node_user -->|"starts run"| node_entry
node_case_input -->|"supplies case"| node_entry
node_entry -->|"runs cases"| node_orchestrator
node_orchestrator -->|"builds state"| node_case_state
node_orchestrator -->|"runs first"| node_spot_stage
node_spot_stage -->|"requests masks"| node_spot_pipeline
node_spot_pipeline -->|"runs experts"| node_moe
node_moe -->|"dispatches detection"| node_detectors
node_spot_pipeline -->|"clusters candidates"| node_cluster
node_spot_pipeline -->|"judges clusters"| node_panel
node_orchestrator -->|"runs next"| node_sizer_stage
node_sizer_stage -->|"measures nodule"| node_measurement
node_orchestrator -->|"runs next"| node_radiologist_stage
node_radiologist_stage -.->|"generates report"| node_dam
node_dam_server -.->|"serves model"| node_dam
node_orchestrator -->|"runs last"| node_doctor_stage
node_doctor_stage -->|"starts debate"| node_debate
node_debate -->|"runs rounds"| node_judges
node_debate -->|"requests summaries"| node_summary
node_judges -.->|"retrieves knowledge"| node_graphrag_tool
node_graphrag_tool -->|"queries backend"| node_retriever
node_judges -->|"requests reasoning"| node_model
node_summary -->|"requests summary"| node_model
node_panel -->|"requests judgments"| node_model
node_model -->|"calls provider"| node_llm_service
node_orchestrator -->|"returns diagnosis"| node_result

click node_entry "https://github.com/imyangc7/lungnoduleagent/blob/main/main.py"
click node_orchestrator "https://github.com/imyangc7/lungnoduleagent/blob/main/pipeline.py"
click node_case_state "https://github.com/imyangc7/lungnoduleagent/blob/main/case.py"
click node_spot_stage "https://github.com/imyangc7/lungnoduleagent/blob/main/stages/spotter.py"
click node_spot_pipeline "https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/pipeline.py"
click node_detectors "https://github.com/imyangc7/lungnoduleagent/tree/main/nodule_spotter/detectors"
click node_moe "https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/moe.py"
click node_cluster "https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/clustering.py"
click node_panel "https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/judging_panel.py"
click node_sizer_stage "https://github.com/imyangc7/lungnoduleagent/blob/main/stages/sizer.py"
click node_measurement "https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_sizer/measure.py"
click node_radiologist_stage "https://github.com/imyangc7/lungnoduleagent/blob/main/stages/radiologist.py"
click node_dam "https://github.com/imyangc7/lungnoduleagent/blob/main/simulated_radiologist/dam/describe_anything_model.py"
click node_dam_server "https://github.com/imyangc7/lungnoduleagent/blob/main/simulated_radiologist/dam_server.py"
click node_doctor_stage "https://github.com/imyangc7/lungnoduleagent/blob/main/stages/doctor.py"
click node_debate "https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/orchestrator.py"
click node_judges "https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/judge_agent.py"
click node_summary "https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/summary_agent.py"
click node_graphrag_tool "https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/graphrag/tool.py"
click node_retriever "https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/graphrag/retriever.py"
click node_model "https://github.com/imyangc7/lungnoduleagent/blob/main/agentbase/model/litellm_model.py"

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_entry,node_orchestrator,node_case_state toneBlue
class node_spot_stage,node_spot_pipeline,node_detectors,node_moe,node_cluster,node_panel toneAmber
class node_sizer_stage,node_measurement,node_radiologist_stage,node_dam,node_dam_server toneMint
class node_doctor_stage,node_debate,node_judges,node_summary,node_graphrag_tool,node_retriever toneRose
class node_model,node_user,node_case_input,node_result,node_llm_service toneIndigo
```

## Components

### Case Pipeline

- [CLI Entry](https://github.com/imyangc7/lungnoduleagent/blob/main/main.py): `main.py`
- [Pipeline Orchestrator](https://github.com/imyangc7/lungnoduleagent/blob/main/pipeline.py): `pipeline.py`
- [Case State](https://github.com/imyangc7/lungnoduleagent/blob/main/case.py): `case.py`

### Nodule Detection

- [Spotter Stage](https://github.com/imyangc7/lungnoduleagent/blob/main/stages/spotter.py): `stages/spotter.py`
- [Spotter Pipeline](https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/pipeline.py): `nodule_spotter/pipeline.py`
- [Detector Experts](https://github.com/imyangc7/lungnoduleagent/tree/main/nodule_spotter/detectors): `nodule_spotter/detectors`
- [Detector MoE](https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/moe.py): `nodule_spotter/moe.py`
- [Mask Clustering](https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/clustering.py): `nodule_spotter/clustering.py`
- [VLM Panel](https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_spotter/judging_panel.py): `nodule_spotter/judging_panel.py`

### Measurement And Reports

- [Sizer Stage](https://github.com/imyangc7/lungnoduleagent/blob/main/stages/sizer.py): `stages/sizer.py`
- [Nodule Measurement](https://github.com/imyangc7/lungnoduleagent/blob/main/nodule_sizer/measure.py): `nodule_sizer/measure.py`
- [Radiologist Stage](https://github.com/imyangc7/lungnoduleagent/blob/main/stages/radiologist.py): `stages/radiologist.py`
- [DAM Report Generation](https://github.com/imyangc7/lungnoduleagent/blob/main/simulated_radiologist/dam/describe_anything_model.py): `simulated_radiologist/dam/describe_anything_model.py`
- [DAM Server](https://github.com/imyangc7/lungnoduleagent/blob/main/simulated_radiologist/dam_server.py): `simulated_radiologist/dam_server.py`

### Clinical Debate

- [Doctor Stage](https://github.com/imyangc7/lungnoduleagent/blob/main/stages/doctor.py): `stages/doctor.py`
- [Debate Orchestrator](https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/orchestrator.py): `lung_agents/orchestrator.py`
- [Specialist Judges](https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/judge_agent.py): `lung_agents/judge_agent.py`
- [Summary Agent](https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/summary_agent.py): `lung_agents/summary_agent.py`
- [GraphRAG Tool](https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/graphrag/tool.py): `lung_agents/graphrag/tool.py`
- [GraphRAG Retriever](https://github.com/imyangc7/lungnoduleagent/blob/main/lung_agents/graphrag/retriever.py): `lung_agents/graphrag/retriever.py`

### Agent Runtime

- [LLM Adapter](https://github.com/imyangc7/lungnoduleagent/blob/main/agentbase/model/litellm_model.py): `agentbase/model/litellm_model.py`

### Other components

- **Clinician / Operator**
- **CT Case Inputs**
- **Diagnosis Trace**
- **LLM Provider**

## Connections

- Clinician / Operator → CLI Entry: starts run
- CT Case Inputs → CLI Entry: supplies case
- CLI Entry → Pipeline Orchestrator: runs cases
- Pipeline Orchestrator → Case State: builds state
- Pipeline Orchestrator → Spotter Stage: runs first
- Spotter Stage → Spotter Pipeline: requests masks
- Spotter Pipeline → Detector MoE: runs experts
- Detector MoE → Detector Experts: dispatches detection
- Spotter Pipeline → Mask Clustering: clusters candidates
- Spotter Pipeline → VLM Panel: judges clusters
- Pipeline Orchestrator → Sizer Stage: runs next
- Sizer Stage → Nodule Measurement: measures nodule
- Pipeline Orchestrator → Radiologist Stage: runs next
- Radiologist Stage → DAM Report Generation: generates report
- DAM Server → DAM Report Generation: serves model
- Pipeline Orchestrator → Doctor Stage: runs last
- Doctor Stage → Debate Orchestrator: starts debate
- Debate Orchestrator → Specialist Judges: runs rounds
- Debate Orchestrator → Summary Agent: requests summaries
- Specialist Judges → GraphRAG Tool: retrieves knowledge
- GraphRAG Tool → GraphRAG Retriever: queries backend
- Specialist Judges → LLM Adapter: requests reasoning
- Summary Agent → LLM Adapter: requests summary
- VLM Panel → LLM Adapter: requests judgments
- LLM Adapter → LLM Provider: calls provider
- Pipeline Orchestrator → Diagnosis Trace: returns diagnosis