# anantshri1/homo-lumo-gat architecture

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

- Interactive diagram: https://gitdiagram.com/anantshri1/homo-lumo-gat
- Repository: https://github.com/anantshri1/homo-lumo-gat

## Overview

MolPredict accepts molecular SMILES and returns HOMO-LUMO gap estimates with uncertainty. Its principal workflow parses SMILES into a molecular graph, runs GATv2 inference, and returns predictions through FastAPI; batch prediction repeats that flow for a list. An MCP server exposes single and batch prediction to agent clients, while the API also provides health status. The graph follows the sampled serving code and README capabilities; training and dataset-loading internals are not represented because their implementation was not sampled.

Main entry points: [`serving/app.py`](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/app.py) (FastAPI Routes), [`serving/inference.py`](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/inference.py) (Inference Service), [`mcp_server/server.py`](https://github.com/anantshri1/homo-lumo-gat/blob/main/mcp_server/server.py) (Prediction Tools), [`serving/graph_builder.py`](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/graph_builder.py) (SMILES Graph Builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chemistry["Molecule Graph"]
  node_graph_builder["SMILES Graph Builder<br/>[graph_builder.py]"]
  node_molecular_graph["Molecular Graph<br/>[graph_builder.py]"]
end

subgraph group_inference["Model Inference"]
  node_inference["Inference Service<br/>[inference.py]"]
  node_model["GATv2 Network<br/>[model.py]"]
  node_checkpoint["Model Checkpoint<br/>[best_model.pt]"]
end

subgraph group_api["HTTP API"]
  node_fastapi["FastAPI Routes<br/>[app.py]"]
  node_health["Health Status<br/>[app.py]"]
end

subgraph group_mcp["MCP Tools"]
  node_mcp_server["MCP Server<br/>[server.py]"]
  node_mcp_tools["Prediction Tools<br/>[server.py]"]
end

node_api_client(("API Client"))
node_agent(("LLM Agent"))

node_api_client -->|"sends requests"| node_fastapi
node_fastapi -->|"serves health"| node_health
node_fastapi -->|"parses SMILES"| node_graph_builder
node_graph_builder -->|"builds graph"| node_molecular_graph
node_fastapi -->|"requests prediction"| node_inference
node_inference -->|"loads weights"| node_checkpoint
node_inference -->|"runs forward pass"| node_model
node_molecular_graph -->|"provides graph data"| node_inference
node_inference -->|"returns estimates"| node_fastapi
node_agent -->|"calls tools"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_tools
node_mcp_tools -->|"posts predictions"| node_fastapi
node_fastapi -->|"returns results"| node_mcp_tools

click node_fastapi "https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/app.py"
click node_health "https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/app.py"
click node_graph_builder "https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/graph_builder.py"
click node_molecular_graph "https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/graph_builder.py"
click node_inference "https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/inference.py"
click node_model "https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/model.py"
click node_checkpoint "https://github.com/anantshri1/homo-lumo-gat/blob/main/checkpoints/best_model.pt"
click node_mcp_server "https://github.com/anantshri1/homo-lumo-gat/blob/main/mcp_server/server.py"
click node_mcp_tools "https://github.com/anantshri1/homo-lumo-gat/blob/main/mcp_server/server.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_graph_builder,node_molecular_graph,node_api_client toneBlue
class node_inference,node_model,node_checkpoint toneAmber
class node_fastapi,node_health toneMint
class node_mcp_server,node_mcp_tools toneRose
class node_agent toneIndigo
```

## Components

### Molecule Graph

- [SMILES Graph Builder](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/graph_builder.py): `serving/graph_builder.py`
- [Molecular Graph](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/graph_builder.py): `serving/graph_builder.py`

### Model Inference

- [Inference Service](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/inference.py): `serving/inference.py`
- [GATv2 Network](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/model.py): `serving/model.py`
- [Model Checkpoint](https://github.com/anantshri1/homo-lumo-gat/blob/main/checkpoints/best_model.pt): `checkpoints/best_model.pt`

### HTTP API

- [FastAPI Routes](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/app.py): `serving/app.py`
- [Health Status](https://github.com/anantshri1/homo-lumo-gat/blob/main/serving/app.py): `serving/app.py`

### MCP Tools

- [MCP Server](https://github.com/anantshri1/homo-lumo-gat/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [Prediction Tools](https://github.com/anantshri1/homo-lumo-gat/blob/main/mcp_server/server.py): `mcp_server/server.py`

### Other components

- **API Client**
- **LLM Agent**

## Connections

- API Client → FastAPI Routes: sends requests
- FastAPI Routes → Health Status: serves health
- FastAPI Routes → SMILES Graph Builder: parses SMILES
- SMILES Graph Builder → Molecular Graph: builds graph
- FastAPI Routes → Inference Service: requests prediction
- Inference Service → Model Checkpoint: loads weights
- Inference Service → GATv2 Network: runs forward pass
- Molecular Graph → Inference Service: provides graph data
- Inference Service → FastAPI Routes: returns estimates
- LLM Agent → MCP Server: calls tools
- MCP Server → Prediction Tools: dispatches tools
- Prediction Tools → FastAPI Routes: posts predictions
- FastAPI Routes → Prediction Tools: returns results