# zaiwen/mr-mas architecture

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

- Interactive diagram: https://gitdiagram.com/zaiwen/mr-mas
- Repository: https://github.com/zaiwen/mr-mas

## Overview

MR-MAS turns an exposure–outcome research question into a reviewed Mendelian Randomization manuscript. Its documented stages cover planning, GWAS retrieval and preparation, local MR execution, interpretation, writing, and paper review; the workflow controller coordinates those stages. The source excerpts confirm key controller, engine, literature, and inference relationships, while several stage links rely on the README. Shared memory and human checkpoints are documented capabilities, but their implementation is not identifiable in the supplied excerpts, so they are represented at the documented subsystem level.

Main entry points: [`MR-MAS-main.py`](https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py) (Workflow Controller), [`mr_code_engine.py`](https://github.com/zaiwen/mr-mas/blob/main/mr_code_engine.py) (MR Execution), [`manuscript_engine.py`](https://github.com/zaiwen/mr-mas/blob/main/manuscript_engine.py) (Manuscript Generation), [`agents.py`](https://github.com/zaiwen/mr-mas/blob/main/agents.py) (Specialist Agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow Coordination"]
  node_workflow["Workflow Controller<br/>[MR-MAS-main.py]"]
  node_specialists["Specialist Agents<br/>[agents.py]"]
  node_checkpoints["Validation And Repair<br/>[MR-MAS-main.py]"]
  node_memory["Shared Memory<br/>[MR-MAS-main.py]"]
end

subgraph group_analysis["MR Analysis"]
  node_traitmatcher["Trait Matching<br/>[tools.py]"]
  node_gwas["GWAS Retrieval<br/>[tools.py]"]
  node_preparation["Instrument Preparation<br/>[MR-MAS-main.py]"]
  node_datasets[("Prepared GWAS Data")]
  node_mrengine["MR Execution<br/>[mr_code_engine.py]"]
  node_mrkb["MR Knowledge Base"]
  node_results[("Analysis Artifacts")]
end

subgraph group_research["Research Resources"]
end

subgraph group_publication["Interpretation And Writing"]
  node_interpretation["Results Interpretation<br/>[agents.py]"]
  node_literature["Literature Retrieval<br/>[PubmedSearch.py]"]
  node_manuscript["Manuscript Generation"]
  node_review["Paper Review<br/>[agents.py]"]
end

node_researcher(("Researcher"))
node_llm{{"LLM Services"}}
node_catalog{{"GWAS Catalog"}}
node_pubmed{{"PubMed And PMC"}}
node_r_runtime{{"Local R Runtime"}}
node_latex{{"LaTeX Compiler"}}

node_researcher -->|"submits objective"| node_workflow
node_workflow -->|"coordinates agents"| node_specialists
node_workflow -->|"normalizes traits"| node_traitmatcher
node_workflow -->|"retrieves studies"| node_gwas
node_gwas -->|"queries"| node_catalog
node_workflow -->|"prepares datasets"| node_preparation
node_preparation -->|"stores prepared data"| node_datasets
node_workflow -->|"starts analysis"| node_mrengine
node_mrengine -->|"reads inputs"| node_datasets
node_mrengine -->|"executes scripts"| node_r_runtime
node_mrengine -->|"uses method specifications"| node_mrkb
node_mrengine -->|"writes outputs"| node_results
node_workflow -->|"coordinates interpretation"| node_interpretation
node_specialists -.->|"requests inference"| node_llm
node_workflow -->|"starts drafting"| node_manuscript
node_manuscript -->|"retrieves references"| node_literature
node_literature -->|"searches and fetches"| node_pubmed
node_manuscript -.->|"generates text"| node_llm
node_manuscript -->|"compiles draft"| node_latex
node_workflow -->|"coordinates review"| node_review
node_workflow -->|"validates stages"| node_checkpoints
node_checkpoints -->|"triggers repair"| node_mrengine
node_workflow -->|"retains artifacts"| node_memory

click node_workflow "https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py"
click node_specialists "https://github.com/zaiwen/mr-mas/blob/main/agents.py"
click node_checkpoints "https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py"
click node_memory "https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py"
click node_traitmatcher "https://github.com/zaiwen/mr-mas/blob/main/tools.py"
click node_gwas "https://github.com/zaiwen/mr-mas/blob/main/tools.py"
click node_preparation "https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py"
click node_datasets "https://github.com/zaiwen/mr-mas/tree/main/research_results/processed_data"
click node_mrengine "https://github.com/zaiwen/mr-mas/blob/main/mr_code_engine.py"
click node_mrkb "https://github.com/zaiwen/mr-mas/tree/main/root_library"
click node_results "https://github.com/zaiwen/mr-mas/tree/main/research_results/results"
click node_interpretation "https://github.com/zaiwen/mr-mas/blob/main/agents.py"
click node_literature "https://github.com/zaiwen/mr-mas/blob/main/PubmedSearch.py"
click node_manuscript "https://github.com/zaiwen/mr-mas/blob/main/manuscript_engine.py"
click node_review "https://github.com/zaiwen/mr-mas/blob/main/agents.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_workflow,node_specialists,node_checkpoints,node_memory toneBlue
class node_traitmatcher,node_gwas,node_preparation,node_datasets,node_mrengine,node_mrkb,node_results toneAmber
class node_interpretation,node_literature,node_manuscript,node_review toneRose
class node_researcher,node_llm,node_catalog,node_pubmed,node_r_runtime,node_latex toneIndigo
```

## Components

### Workflow Coordination

- [Workflow Controller](https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py): `MR-MAS-main.py`
- [Specialist Agents](https://github.com/zaiwen/mr-mas/blob/main/agents.py): `agents.py`
- [Validation And Repair](https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py): `MR-MAS-main.py`
- [Shared Memory](https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py): `MR-MAS-main.py`

### MR Analysis

- [Trait Matching](https://github.com/zaiwen/mr-mas/blob/main/tools.py): `tools.py`
- [GWAS Retrieval](https://github.com/zaiwen/mr-mas/blob/main/tools.py): `tools.py`
- [Instrument Preparation](https://github.com/zaiwen/mr-mas/blob/main/MR-MAS-main.py): `MR-MAS-main.py`
- [Prepared GWAS Data](https://github.com/zaiwen/mr-mas/tree/main/research_results/processed_data): `research_results/processed_data`
- [MR Execution](https://github.com/zaiwen/mr-mas/blob/main/mr_code_engine.py): `mr_code_engine.py`
- [MR Knowledge Base](https://github.com/zaiwen/mr-mas/tree/main/root_library): `root_library`
- [Analysis Artifacts](https://github.com/zaiwen/mr-mas/tree/main/research_results/results): `research_results/results`

### Interpretation And Writing

- [Results Interpretation](https://github.com/zaiwen/mr-mas/blob/main/agents.py): `agents.py`
- [Literature Retrieval](https://github.com/zaiwen/mr-mas/blob/main/PubmedSearch.py): `PubmedSearch.py`
- [Manuscript Generation](https://github.com/zaiwen/mr-mas/blob/main/manuscript_engine.py): `manuscript_engine.py`
- [Paper Review](https://github.com/zaiwen/mr-mas/blob/main/agents.py): `agents.py`

### Other components

- **Researcher**
- **LLM Services**
- **GWAS Catalog**
- **PubMed And PMC**
- **Local R Runtime**
- **LaTeX Compiler**

## Connections

- Researcher → Workflow Controller: submits objective (evidence: `README.md`)
- Workflow Controller → Specialist Agents: coordinates agents (evidence: `MR-MAS-main.py`)
- Workflow Controller → Trait Matching: normalizes traits (evidence: `README.md`)
- Workflow Controller → GWAS Retrieval: retrieves studies (evidence: `README.md`)
- GWAS Retrieval → GWAS Catalog: queries (evidence: `README.md`)
- Workflow Controller → Instrument Preparation: prepares datasets (evidence: `README.md`)
- Instrument Preparation → Prepared GWAS Data: stores prepared data (evidence: `README.md`)
- Workflow Controller → MR Execution: starts analysis (evidence: `MR-MAS-main.py`)
- MR Execution → Prepared GWAS Data: reads inputs (evidence: `mr_code_engine.py`)
- MR Execution → Local R Runtime: executes scripts (evidence: `README.md`)
- MR Execution → MR Knowledge Base: uses method specifications (evidence: `README.md`)
- MR Execution → Analysis Artifacts: writes outputs (evidence: `README.md`)
- Workflow Controller → Results Interpretation: coordinates interpretation (evidence: `README.md`)
- Specialist Agents → LLM Services: requests inference
- Workflow Controller → Manuscript Generation: starts drafting (evidence: `MR-MAS-main.py`)
- Manuscript Generation → Literature Retrieval: retrieves references (evidence: `manuscript_engine.py`)
- Literature Retrieval → PubMed And PMC: searches and fetches (evidence: `PubmedSearch.py`)
- Manuscript Generation → LLM Services: generates text
- Manuscript Generation → LaTeX Compiler: compiles draft (evidence: `README.md`)
- Workflow Controller → Paper Review: coordinates review (evidence: `README.md`)
- Workflow Controller → Validation And Repair: validates stages (evidence: `README.md`)
- Validation And Repair → MR Execution: triggers repair (evidence: `README.md`)
- Workflow Controller → Shared Memory: retains artifacts (evidence: `README.md`)
