Enhance AlphaFold3-GUI with improved input handling and covalent ligand workflows

- Updated README.md to clarify installation steps, features, and usage instructions.
- Refactored streamlit_app.py to streamline entity input generation and validation.
- Introduced helper functions for parsing JSON arrays and model seeds.
- Enhanced ligand input handling with better covalent bond definition options.
- Improved error handling in utils.py for RDKit operations and molecule manipulations.
- Added validation checks for user inputs to ensure correct data entry.

Author: maxischuh

README.md

@@ -1,52 +1,107 @@
 # AlphaFold3-GUI
 
-Welcome to the AlphaFold3-GUI repository! This project provides a user-friendly graphical user interface (GUI) for the generation of AlphaFold 3 input files, enabling researchers to easily set up, run, and analyze protein structure predictions without the need for extensive .json and .mmCIF editing.
----
-## Installation
+`AlphaFold3-GUI` is a Streamlit app for building AlphaFold 3 input JSON files, including optional covalent ligand workflows from SMILES input.
+
+It is designed for users who want a guided interface instead of manually editing JSON and mmCIF content.
+
+## Features
+
+- Build AlphaFold 3 input JSON for proteins, RNA, DNA, and ligands
+- Add multiple copies of entities with automatic label assignment (`A`, `B`, `C`, ...)
+- Enter polymer modifications/templates as JSON arrays
+- Generate covalent ligand `userCCD` content from a SMILES-derived ligand structure
+- Download the generated JSON directly from the UI
+
+## Quick Start
 
 ### Prerequisites
+
 - Python 3.8+
-- Required Python packages (see `requirements.txt`)
-- AlphaFold 3 installed and configured on your system
-
-### Steps
-1. Clone this repository:
-   ```bash
-   git clone https://github.com/sieber-lab/AlphaFold3-GUI.git
-   cd AlphaFold3-GUI
-   ```
-2. Install the dependencies:
-   ```bash
-   pip install -r requirements.txt
-   ```
-3. Run the application:
-   ```bash
-   streamlit run streamlit_app.py
-   ```
-
-## Usage
-
-### Step 1: Launch the GUI
-After running `streamlit run streamlit_app.py`, the AlphaFold3-GUI window will open. From here, you can generate your .json file.
-Alternatively, you can use the publicly accessible webserver: https://alphafold3-gui.streamlit.app/ 
-
-### Step 2: Configure Input File
-1. Adjust prediction parameters such as proteins, and nucleic acids, ions, and ligands, similar to the AlphaFold3 Webserver.
-2. Unlike the AlphaFold3 Webserver, this interface supports covalent bond generation to any type of ligand, simply by SMILES input.
-3. Additionally, the interface supports editing of covalent ligands by:
-![AlphaFold3-GUI Screenshot](images/leaving_group_af.jpg)
-5. Selecting a leaving group via the 3D molecule visualization.
-6. Selecting the target atom using the 3D visualization.
-7. Use the built-in **JSON Generator** to create a JSON file that meets AlphaFold 3's input requirements.
-
-### Step 4: Run Prediction
-1. Once the setup is complete, simply download the .json file, and use it as input for your AlphaFold3 prediction
+- AlphaFold 3 installed/configured separately (this repo only generates inputs)
+- Dependencies from `requirements.txt`
 
-## License
+### Install
+
+```bash
+git clone https://github.com/sieber-lab/AlphaFold3-GUI.git
+cd AlphaFold3-GUI
+pip install -r requirements.txt
+```
+
+Notes:
+- `rdkit` installation can be platform-dependent. If `pip install` fails, install RDKit via `conda`/`mamba` and then install the remaining requirements.
+
+### Run
+
+```bash
+streamlit run streamlit_app.py
+```
+
+## Usage Guide
+
+### 1. Job Details
+
+- Set a job name (used in the JSON and download filename)
+- Enter model seeds as comma-separated integers (invalid values are ignored with a warning)
+
+### 2. Entity Counts
+
+- Choose how many protein, RNA, DNA, and ligand entities to add
+- The app will create input sections for each entity
+
+### 3. Fill Entity Inputs
 
-This project is licensed under the Apache License. See the `LICENSE` file for details.
+- **Protein / RNA / DNA**: add sequences and optional modifications
+- **Ligand**: add a SMILES string or use the covalent workflow
 
-## Acknowledgments
+### 4. Optional Covalent Ligand Workflow
+
+The covalent workflow helps create a custom ligand and bond definition:
+
+1. Render the ligand from SMILES
+2. Define the leaving group (by bond indices or atom list)
+3. Choose the ligand atom that will remain bound
+4. Choose the protein/RNA/DNA entity and residue
+5. Enter the target atom name (CCD atom name on the biomolecule side)
+6. Finalize the bond to generate `userCCD` data
+
+![Covalent ligand workflow](images/leaving_group_af.jpg)
+
+### 5. Generate and Download JSON
+
+- Click **Generate JSON**
+- Review the JSON preview in the app
+- Click **Download JSON** and use the file as AlphaFold 3 input
+
+## Current Limitations
+
+- Covalent ligand mode currently supports **one ligand with one copy** at a time
+- The app validates common input issues, but it does not fully validate every AlphaFold 3 schema rule
+- `userCCD` export currently uses a single generated ligand definition
+
+## Repository Layout
+
+- `streamlit_app.py` — Streamlit UI and input flow
+- `utils.py` — JSON generation and ligand/mmCIF conversion helpers
+- `seqs.py` — sequence data model classes
+- `requirements.txt` — Python dependencies
+- `monomers.cif` — reference monomer definitions used by the project
+
+## Troubleshooting
+
+- **RDKit errors while rendering a ligand**
+  - Check the SMILES string
+  - Try a simpler ligand first
+  - Some molecules may fail 3D embedding/optimization
+
+- **Covalent options unavailable**
+  - Ensure at least one protein/RNA/DNA entity is defined
+  - Use exactly one ligand with one copy for covalent mode
+
+- **Invalid JSON array fields**
+  - Use valid JSON arrays such as `[]`, `[{"ptmType":"..."}]`, or `[{"template":"..."}]`
+
+## License
 
-Special thanks to the contributors and the AlphaFold team for their incredible work in advancing protein structure prediction.
+This project is licensed under the Apache License. See `LICENSE`.