Updated README

README.md

@@ -4,91 +4,110 @@ emoji: 🧬
 colorFrom: indigo
 colorTo: purple
 sdk: docker
-app_file: app.py 
+app_file: app.py
 pinned: false
 ---
 
+# HOMO‑LUMO Gap Predictor — Streamlit + Hybrid GNN
 
-This web app uses a trained Graph Neural Network (GNN) to predict HOMO–LUMO energy gaps from molecular SMILES strings. Built with [Streamlit](https://streamlit.io), it enables fast single or batch predictions with visualization.
-
-### Live App
-
-[Click here to launch the app](https://www.willfillinoncedeployed.com)  
+> **Live demo:** [huggingface.co/spaces/MooseML/homo-lumo-gap-predictor](https://huggingface.co/spaces/MooseML/homo-lumo-gap-predictor)  •   
+> **Code:** <https://github.com/MooseML/homo-lumo-gap-predictor>
 
+This web app predicts HOMO–LUMO energy gaps from molecular **SMILES** using a trained hybrid Graph Neural Network (PyTorch Geometric and RDKit descriptors).  
+It runs on Hugging Face Spaces via Docker and on any local machine with Docker or a Python ≥ 3.10 environment.
 
 ---
 
 ## Features
 
-- Predict HOMO–LUMO gap for one or many molecules
-- Accepts comma-separated SMILES or CSV uploads
-- RDKit rendering of molecule structures
-- Downloadable CSV of predictions
-- Powered by a trained hybrid GNN model with RDKit descriptors
+* Predict gaps for **single or batch** inputs (comma / newline SMILES or CSV upload)
+* Shows **up to 20 molecules** per run with RDKit 2‑D depictions
+* Download full predictions as CSV
+* Logs all predictions to a lightweight SQLite DB (`/data/predictions.db`)
+* Containerised environment identical to the public Space
 
 ---
 
-## Usage
+## Quick start
 
-1. **Input Options**:
-   - Type one or more SMILES strings separated by commas
-   - OR upload a `.csv` file with a single column of SMILES
+### 1  Use the hosted Space
 
-2. **Example SMILES**: CC(=O)Oc1ccccc1C(=O)O, C1=CC=CC=C1
+1. Open the [live URL](https://huggingface.co/spaces/MooseML/homo-lumo-gap-predictor).  
+2. Paste SMILES *or* upload a CSV (1 column, no header).  
+3. Click **Run Prediction** → results and structures appear; a CSV is downloadable.
 
-3. **CSV Format**:
-- One column
-- No header 
-- Each row contains a SMILES string
+> **Heads‑up:** on the free HF tier large files (> ~5 MB) can take 10–30 s to upload because of proxy buffering.  
+> Local Docker runs are instant, see below:
 
-4. **Output**:
-- Predictions displayed in-browser (up to 10 molecules shown)
-- Full results available for download as CSV
+### 2  Run locally with Docker (mirrors the Space)
 
----
+```bash
+git clone https://github.com/MooseML/homo-lumo-gap-predictor.git
+cd homo-lumo-gap-predictor
+docker build -t homolumo .
+docker run -p 7860:7860 homolumo
+# open http://localhost:7860
+````
 
-## Project Structure
+### 3  Run locally with Python (no Docker)
 
-streamlit-app/
-│
-├── app.py # Main Streamlit app
-├── model.py # Hybrid GNN architecture and model loader
-├── utils.py # RDKit and SMILES processing
-├── requirements.txt # Python dependencies
-└── predictions.db # SQLite log of predictions 
+```bash
+git clone https://github.com/MooseML/homo-lumo-gap-predictor.git
+cd homo-lumo-gap-predictor
+pip install -r requirements.txt
+streamlit run app.py 
+# app on http://localhost:8501
+```
 
 ---
 
-## Requirements
+## Input guidelines
 
-To run locally:
-```
-pip install -r requirements.txt
-streamlit run app.py
+| Format       | Example                                        |
+| ------------ | ---------------------------------------------- |
+| **Textarea** | `O=C(C)Oc1ccccc1C(=O)O, C1=CC=CC=C1`           |
+| **CSV**      | One column, no header:<br>`CCO`<br>`Cc1ccccc1` |
 
-```
+Invalid or exotic SMILES are skipped and listed in the terminal log (RDKit warnings)
 
+---
 
-## Model Info
-
-The app uses a trained hybrid GNN model combining:
+## Project files
 
-* AtomEncoder and BondEncoder from OGB
-* GINEConv layers from PyTorch Geometric
-* Global mean pooling
-* RDKit-based physicochemical descriptors
+```
+.
+├── app.py          – Streamlit front‑end
+├── model.py        – Hybrid GNN loader (PyTorch Geometric)
+├── utils.py        – RDKit helpers & SMILES→graph
+├── Dockerfile      – identical to the Hugging Face Space
+└── requirements.txt
+```
 
-Trained on the [OGB PCQM4Mv2 dataset](https://ogb.stanford.edu/docs/lsc/pcqm4mv2/), optimized using Optuna
+The Docker image creates `/data` (writable, 775) for the persistent SQLite DB when a volume is attached.
 
+---
 
-## Author
+## Model in brief
 
-Developed by [Matthew Graham](https://github.com/MooseML)
-For inquiries, collaborations, or ideas, feel free to reach out!
+* **Architecture:** AtomEncoder and BondEncoder → GINEConv layers → global mean pooling → dense head
+* **Descriptors:** six RDKit physico‑chemical features per molecule
+* **Training set:** [OGB PCQM4Mv2](https://ogb.stanford.edu/docs/lsc/pcqm4mv2/)
+* **Optimiser / search:** Optuna hyperparameter sweep
 
+---
 
+## Roadmap
 
+* Stream chunked CSV parsing to improve upload speed on the public Space
+* Toggle between 2‑D and 3‑D (3Dmol.js) molecule renderings
+* Serve the model weights from the HF Hub instead of bundling in the image
 
+---
 
+## Author
 
+**Matthew Graham** — [@MooseML](https://github.com/MooseML)
+Feel free to open issues or contact me for collaborations.
 
+```
+```