# agasthya736/multi-agent-system architecture

> Architecture diagram of the GitHub repository agasthya736/multi-agent-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agasthya736/multi-agent-system
- Repository: https://github.com/agasthya736/multi-agent-system

## Overview

#### Purpose and Entry Points
Radiology MAS generates structured chest X-ray reports through a staged multi-agent pipeline: Vision → Knowledge → Writing → Verifier. The interactive entry point is the Streamlit application at `app.py`; batch/pipeline execution is represented by `pipeline_runner.py`. A standalone baseline path exists in `baseline.py`.

#### Orchestration and Agent Stages
The core architecture is a sequential, file-oriented agent workflow:
1. **Vision analysis** interprets chest X-ray inputs: `vision_agent/agent.py`, `vision_agent/runner.py`.
2. **Knowledge augmentation** adds medical/radiology context: `knowledge_agent/agent.py`.
3. **Report writing** converts upstream findings into radiology-report text: `writing_agent/agent.py`.
4. **Verification** reviews generated content for hallucinations or unsupported claims: `verifier_agent/agent.py`.

The verifier is an explicit quality boundary between generated draft content and final report outputs.

#### Data Boundaries
Local dataset assets are central dependencies. Image data is stored under `data/images/NLMCXR_png`, while source radiology reports are a large XML corpus under `data/report/NLMCXR_reports/ecgen-radiology`. `data/dataset.csv` appears to provide the dataset-level index or sample metadata connecting these artifacts.

Dataset parsing is separated into `parse_dataset.py`, creating a boundary between raw XML/image resources and pipeline-ready records.

#### Generated Artifacts and Comparative Runs
Outputs are persisted by pipeline stage beneath `results/generated_reports`, including `results/generated_reports/vision`, `results/generated_reports/knowledge`, `results/generated_reports/writing`, and `results/generated_reports/verifier`. This preserves intermediate agent outputs for inspection and supports comparison against `results/generated_reports/baseline`.

The result layout indicates runs are keyed by sample ID and materialized as text files, rather than stored in a database or served through an API.

#### Evaluation Layer
Evaluation is decoupled from generation. Clinical scoring is represented by `clinical_metric.py`, while general and multi-agent evaluation scripts include `evaluate.py`, `evaluation_mas.py`, and `evaluate_mas.py`. Persisted aggregates include `results/clinical_metrics.csv`, `results/scores.csv`, and `results/summary.csv`.

This separation enables comparison of baseline and staged-agent reports using the same sample-level artifacts.

#### Runtime and Infrastructure
The repository is Python-based, with dependencies declared in `requirements.txt` and evaluation-specific dependencies in `requirements_eval.txt`. It runs as a Streamlit service locally or in Docker via `Dockerfile`; Streamlit settings reside in `.streamlit/config.toml`.

The system supports external LLM providers—Gemini, OpenAI, and Ollama—per the project description. Docker deployment specifically expects `GOOGLE_API_KEY`, making Gemini an operationally documented integration. No external persistence, message queue, or backend service is evidenced in the repository tree.

Main entry points: [`results/generated_reports`](https://github.com/agasthya736/multi-agent-system/tree/main/results/generated_reports) (Stage report outputs), [`parse_dataset.py`](https://github.com/agasthya736/multi-agent-system/blob/main/parse_dataset.py) (Dataset parser), [`vision_agent/agent.py`](https://github.com/agasthya736/multi-agent-system/blob/main/vision_agent/agent.py) (Vision analysis), [`knowledge_agent/agent.py`](https://github.com/agasthya736/multi-agent-system/blob/main/knowledge_agent/agent.py) (Knowledge augmentation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_streamlit["Streamlit app<br/>interactive entry<br/>[app.py]"]
  node_runner["Pipeline runner<br/>batch orchestration<br/>[pipeline_runner.py]"]
  node_baseline["Baseline generator<br/>standalone path<br/>[baseline.py]"]
end

subgraph group_pipeline["MAS pipeline"]
  node_vision["Vision analysis<br/>agent stage<br/>[agent.py]"]
  node_vision_runner["Vision runner<br/>vision execution<br/>[runner.py]"]
  node_knowledge["Knowledge augmentation<br/>agent stage<br/>[agent.py]"]
  node_writing["Report writing<br/>agent stage<br/>[agent.py]"]
  node_verifier{{"Report verifier<br/>quality boundary<br/>[agent.py]"}}
end

subgraph group_data["Dataset"]
  node_parser["Dataset parser<br/>record preparation<br/>[parse_dataset.py]"]
  node_dataset_index["Dataset index<br/>sample metadata<br/>[dataset.csv]"]
  node_xray_images["Chest X-ray images<br/>image corpus"]
  node_source_reports["Source XML reports<br/>report corpus"]
end

subgraph group_artifacts["Generated artifacts"]
  node_stage_outputs["Stage report outputs<br/>sample text artifacts"]
  node_baseline_outputs["Baseline outputs<br/>sample text artifacts"]
end

subgraph group_evaluation["Evaluation"]
  node_clinical_metric["Clinical metric<br/>clinical scoring<br/>[clinical_metric.py]"]
  node_mas_evaluation["MAS evaluation<br/>comparison scripts<br/>[evaluation_mas.py]"]
  node_score_aggregates["Score aggregates<br/>evaluation results<br/>[scores.csv]"]
end

node_llm_providers(("LLM providers<br/>external AI services"))
node_docker["Docker runtime<br/>local deployment"]

node_streamlit -->|"starts pipeline"| node_runner
node_runner -->|"loads records"| node_parser
node_dataset_index -->|"indexes samples"| node_parser
node_xray_images -->|"image assets"| node_parser
node_source_reports -->|"reference reports"| node_parser
node_parser -->|"prepared samples"| node_vision_runner
node_vision_runner -->|"executes"| node_vision
node_vision -->|"findings"| node_knowledge
node_knowledge -->|"augmented context"| node_writing
node_writing -->|"draft report"| node_verifier
node_vision -.->|"persists output"| node_stage_outputs
node_knowledge -.->|"persists output"| node_stage_outputs
node_writing -.->|"persists draft"| node_stage_outputs
node_verifier -->|"persists final report"| node_stage_outputs
node_baseline -->|"persists reports"| node_baseline_outputs
node_stage_outputs -->|"generated reports"| node_clinical_metric
node_baseline_outputs -->|"comparison input"| node_mas_evaluation
node_stage_outputs -->|"comparison input"| node_mas_evaluation
node_clinical_metric -->|"clinical metrics"| node_score_aggregates
node_mas_evaluation -->|"scores and summary"| node_score_aggregates
node_vision -.->|"model inference"| node_llm_providers
node_knowledge -.->|"model inference"| node_llm_providers
node_writing -.->|"model inference"| node_llm_providers
node_verifier -.->|"model inference"| node_llm_providers
node_docker -.->|"runs locally"| node_streamlit

click node_streamlit "https://github.com/agasthya736/multi-agent-system/blob/main/app.py"
click node_runner "https://github.com/agasthya736/multi-agent-system/blob/main/pipeline_runner.py"
click node_baseline "https://github.com/agasthya736/multi-agent-system/blob/main/baseline.py"
click node_parser "https://github.com/agasthya736/multi-agent-system/blob/main/parse_dataset.py"
click node_dataset_index "https://github.com/agasthya736/multi-agent-system/blob/main/data/dataset.csv"
click node_xray_images "https://github.com/agasthya736/multi-agent-system/tree/main/data/images/NLMCXR_png"
click node_source_reports "https://github.com/agasthya736/multi-agent-system/tree/main/data/report/NLMCXR_reports/ecgen-radiology"
click node_vision "https://github.com/agasthya736/multi-agent-system/blob/main/vision_agent/agent.py"
click node_vision_runner "https://github.com/agasthya736/multi-agent-system/blob/main/vision_agent/runner.py"
click node_knowledge "https://github.com/agasthya736/multi-agent-system/blob/main/knowledge_agent/agent.py"
click node_writing "https://github.com/agasthya736/multi-agent-system/blob/main/writing_agent/agent.py"
click node_verifier "https://github.com/agasthya736/multi-agent-system/blob/main/verifier_agent/agent.py"
click node_stage_outputs "https://github.com/agasthya736/multi-agent-system/tree/main/results/generated_reports"
click node_baseline_outputs "https://github.com/agasthya736/multi-agent-system/tree/main/results/generated_reports/baseline"
click node_clinical_metric "https://github.com/agasthya736/multi-agent-system/blob/main/clinical_metric.py"
click node_mas_evaluation "https://github.com/agasthya736/multi-agent-system/blob/main/evaluation_mas.py"
click node_score_aggregates "https://github.com/agasthya736/multi-agent-system/blob/main/results/scores.csv"
click node_docker "https://github.com/agasthya736/multi-agent-system/blob/main/Dockerfile"

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_streamlit,node_runner,node_baseline toneBlue
class node_vision,node_vision_runner,node_knowledge,node_writing,node_verifier toneAmber
class node_parser,node_dataset_index,node_xray_images,node_source_reports toneMint
class node_stage_outputs,node_baseline_outputs toneRose
class node_clinical_metric,node_mas_evaluation,node_score_aggregates toneIndigo
class node_llm_providers,node_docker toneNeutral
```

## Components

### Entry points

- [Streamlit app](https://github.com/agasthya736/multi-agent-system/blob/main/app.py): interactive entry · `app.py`
- [Pipeline runner](https://github.com/agasthya736/multi-agent-system/blob/main/pipeline_runner.py): batch orchestration · `pipeline_runner.py`
- [Baseline generator](https://github.com/agasthya736/multi-agent-system/blob/main/baseline.py): standalone path · `baseline.py`

### MAS pipeline

- [Vision analysis](https://github.com/agasthya736/multi-agent-system/blob/main/vision_agent/agent.py): agent stage · Interprets chest X-ray inputs. · `vision_agent/agent.py`
- [Vision runner](https://github.com/agasthya736/multi-agent-system/blob/main/vision_agent/runner.py): vision execution · `vision_agent/runner.py`
- [Knowledge augmentation](https://github.com/agasthya736/multi-agent-system/blob/main/knowledge_agent/agent.py): agent stage · Adds medical and radiology context. · `knowledge_agent/agent.py`
- [Report writing](https://github.com/agasthya736/multi-agent-system/blob/main/writing_agent/agent.py): agent stage · Produces radiology-report text from upstream findings. · `writing_agent/agent.py`
- [Report verifier](https://github.com/agasthya736/multi-agent-system/blob/main/verifier_agent/agent.py): quality boundary · Rejects hallucinated or unsupported claims before final output. · `verifier_agent/agent.py`

### Dataset

- [Dataset parser](https://github.com/agasthya736/multi-agent-system/blob/main/parse_dataset.py): record preparation · Transforms raw dataset resources into pipeline-ready records. · `parse_dataset.py`
- [Dataset index](https://github.com/agasthya736/multi-agent-system/blob/main/data/dataset.csv): sample metadata · `data/dataset.csv`
- [Chest X-ray images](https://github.com/agasthya736/multi-agent-system/tree/main/data/images/NLMCXR_png): image corpus · `data/images/NLMCXR_png`
- [Source XML reports](https://github.com/agasthya736/multi-agent-system/tree/main/data/report/NLMCXR_reports/ecgen-radiology): report corpus · `data/report/NLMCXR_reports/ecgen-radiology`

### Generated artifacts

- [Stage report outputs](https://github.com/agasthya736/multi-agent-system/tree/main/results/generated_reports): sample text artifacts · Intermediate vision, knowledge, writing, and verifier outputs keyed by sample ID. · `results/generated_reports`
- [Baseline outputs](https://github.com/agasthya736/multi-agent-system/tree/main/results/generated_reports/baseline): sample text artifacts · `results/generated_reports/baseline`

### Evaluation

- [Clinical metric](https://github.com/agasthya736/multi-agent-system/blob/main/clinical_metric.py): clinical scoring · `clinical_metric.py`
- [MAS evaluation](https://github.com/agasthya736/multi-agent-system/blob/main/evaluation_mas.py): comparison scripts · Evaluates baseline and staged-agent reports. · `evaluation_mas.py`
- [Score aggregates](https://github.com/agasthya736/multi-agent-system/blob/main/results/scores.csv): evaluation results · Clinical metrics, scores, and summaries are persisted as CSV files. · `results/scores.csv`

### Other components

- **LLM providers**: external AI services · Gemini, OpenAI, or Ollama supply model inference.
- [Docker runtime](https://github.com/agasthya736/multi-agent-system/blob/main/Dockerfile): local deployment · Documented deployment expects GOOGLE_API_KEY for Gemini. · `Dockerfile`

## Connections

- Streamlit app → Pipeline runner: starts pipeline
- Pipeline runner → Dataset parser: loads records
- Dataset index → Dataset parser: indexes samples
- Chest X-ray images → Dataset parser: image assets
- Source XML reports → Dataset parser: reference reports
- Dataset parser → Vision runner: prepared samples
- Vision runner → Vision analysis: executes
- Vision analysis → Knowledge augmentation: findings
- Knowledge augmentation → Report writing: augmented context
- Report writing → Report verifier: draft report
- Vision analysis → Stage report outputs: persists output
- Knowledge augmentation → Stage report outputs: persists output
- Report writing → Stage report outputs: persists draft
- Report verifier → Stage report outputs: persists final report
- Baseline generator → Baseline outputs: persists reports
- Stage report outputs → Clinical metric: generated reports
- Baseline outputs → MAS evaluation: comparison input
- Stage report outputs → MAS evaluation: comparison input
- Clinical metric → Score aggregates: clinical metrics
- MAS evaluation → Score aggregates: scores and summary
- Vision analysis → LLM providers: model inference
- Knowledge augmentation → LLM providers: model inference
- Report writing → LLM providers: model inference
- Report verifier → LLM providers: model inference
- Docker runtime → Streamlit app: runs locally