final commit

README.md

@@ -11,6 +11,179 @@ license: apache-2.0
 short_description: MCP server to simulate protein folding on Modal cluster
 tags: 
    - mcp-server-track
+   - Modal Labs Choice Award
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+![Logo project](images/logo1.png)
+
+# Stakes
+The industry is undergoing a profound transformation due to the development of Large Language Models (LLMs) and the recent advancements that enable them to access external tools. 
+For years, companies have leveraged simulation tools to accelerate and reduce the costs of product development. 
+One of the primary challenges in the coming years will be to create agents capable of setting up, running, and processing simulations to further expedite innovation.
+Engineers will focus on analysis rather than simulation setup, allowing them to concentrate on the most critical aspects of their work.
+
+# Objective
+
+This project represents a first step towards developing AI agents that can perform simulations using existing engineering softwares. 
+Key domains of application include:
+- **CFD** (Computational Fluid Dynamics) simulations
+- **Biology** (Protein Folding, Molecular Dynamics, etc.)
+- **Neural network applications**
+
+While this project focuses on biomolecules folding, the principles employed can be extended to other domains. 
+Specifically, it uses [Chai-1](https://www.chaidiscovery.com/blog/introducing-chai-1), a multi-modal foundation model for molecular structure prediction that achieves state-of-the-art performance across various benchmarks. 
+Chai-1 enables unified prediction of proteins, small molecules, DNA, RNA, glycosylations, and more. 
+
+Industrial computations frequently require substantial resources (large number of CPUs and GPUs) that are performed on High-Performance Computing (HPC) clusters. 
+To this end, [Modal Labs](https://modal.com/), a serverless platform that offers a straightforward method to run any application with the latest CPU and GPU hardware, will be used.
+        
+MCP servers are an efficient solution to connect LLMs to real world engineering applications by providing access to a set of tools. 
+The purpose of this project is to enable users to run biomolecule folding simulations using the Chai-1 model through any LLM chat or with a Gradio interface.
+                
+
+# Benefits
+
+1. **Efficiency**: The MCP server's connected to high-performance computing capabilities ensure that simulations are run quickly and efficiently.
+
+2. **Ease of Use**: Only provide necessary parameters to the user to simplify the process of setting up and running complex simulations.
+
+3. **Integration**: The seamless integration between the LLM's chat interface and the MCP server allows for a streamlined workflow, from simulation setup to results analysis.
+
+The following video illustrates a practical use of the MCP server to run a biomolecules folding simulation using the Chai-1 model. 
+In this scenario, Copilot is used in Agent mode with Claude 3.5 Sonnet to leverage the tools provided by the MCP server.
+
+# MCP tools
+1. `create_fasta_file`: Create a FASTA file from a biomolecule sequence string with a unique name.
+2. `create_json_config`: Create a JSON configuration file from the Gradio interface inputs.
+3. `compute_Chai1`: Compute a Chai-1 simulation on Modal labs server. Return a DataFrame with predicted scores: aggregated, pTM and ipTM.
+4. `plot_protein`: Plot the 3D structure of a biomolecule using the DataFrame from `compute_Chai1` (Use for Gradio interface).
+5. `show_cif_file`: Plot a 3D structure from a CIF file with the Molecule3D library (Use for the Gradio interface).
+
+ # Result example
+The following image shows an example of a protein folding simulation using the Chai-1 model. 
+The simulation was run with the default configuration and the image is 3D view from the Gradio interface.
+
+![Protein folding example](images/protein.png)
+
+
+ # What's next?
+1. Expose additional tools to post-process the results of the simulations. 
+The current post-processing tools are suited for the Gradio interface (ex: Plot images of the molecule structure from a file).
+2. Continue the pipeline by adding softawres like [OpenMM](https://openmm.org/) or [Gromacs](https://www.gromacs.org/) for molecular dynamics simulations.
+3. Perform complete simulation plans including loops over parameters fully automated by the LLM.
+
+# Contact
+For any issues or questions, please contact the developer or refer to the documentation.
+
+
+# Environment creation with uv
+Run the following in a bash shell:
+```bash
+uv venv 
+source .venv/bin/activate
+uv pip install gradio[mcp] modal gemmi gradio_molecule3d 
+```
+
+# Connect to Modal
+Create an account on Modal [website](https://modal.com) and run in your local terminal:
+```
+python -m modal setup
+```
+
+
+# Run the app 
+Run in a bash shell: 
+```bash
+gradio app.py
+```
+
+
+
+# Gradio interface instructions
+
+<div style="background-color:#f5f5f5; border-radius:8px; padding:18px 24px; margin-bottom:24px; border:1px solid #cccccc;">
+
+### 1. <span style="color:#e98935;">Create your JSON configuration file (Optional)</span>
+<small>Default configuration is available if you skip this step.</small>
+
+- In the `Configuration 📦` window, set your simulation parameters and generate the JSON config file. You can provide a file name in the dedicated box that will appear in the list of available configuration files. If you don't, a unique identifier will be assigned (e.g., `chai_{unique_id}_config.json`).
+- **Parameters:**
+  - <b>Number of diffusion time steps:</b> 1 to 500
+  - <b>Number of trunk recycles:</b> 1 to 5
+  - <b>Seed:</b> 1 to 100
+  - <b>ESM_embeddings:</b> Include or not
+  - <b>MSA_server:</b> Include or not
+
+### 2. <span style="color:#e98935;">Upload a FASTA file with your molecule sequence (Optional)</span>
+<small>Default FASTA files are available if you skip this step.</small>
+
+- In the `Configuration 📦` window, write your FASTA content and create the file. You can provide a file name in the dedicated box that will appear in the list of available configuration files. If you don't provide a file name a unique identifier will be assigned (e.g., `chai_{unique_id}_input.fasta`). Also, if you don't provide a fasta content a default sequence will be written in the file.
+- <b style="color:#b91c1c;">Warning:</b> The header must be well formatted for Chai1 to process it.
+
+**FASTA template:**
+<div style="background-color:#ffffff; border-radius:8px; padding:18px 24px; margin-bottom:24px; border:1px solid #cccccc;">
+
+```fasta
+>{molecule_type}|{molecule_name}
+Sequence (for protein/RNA/DNA) or SMILES for ligand
+```
+
+</div>
+
+**Accepted  molecule types:** 
+ `protein`/ `rna`/  `dna` / `ligand`
+
+**Default input (provided by Chai1):**
+<div style="background-color:#ffffff; border-radius:8px; padding:18px 24px; margin-bottom:24px; border:1px solid #cccccc;">
+
+```fasta
+>protein|name=example-of-long-protein
+AGSHSMRYFSTSVSRPGRGEPRFIAVGYVDDTQFVRFDSDAASPRGEPRAPWVEQEGPEYWDRETQKYKRQAQTDRVSLRNLRGYYNQSEAGSHTLQWMFGCDLGPDGRLLRGYDQSAYDGKDYIALNEDLRSWTAADTAAQITQRKWEAAREAEQRRAYLEGTCVEWLRRYLENGKETLQRAEHPKTHVTHHPVSDHEATLRCWALGFYPAEITLTWQWDGEDQTQDTELVETRPAGDGTFQKWAAVVVPSGEEQRYTCHVQHEGLPEPLTLRWEP
+
+>protein|name=example-of-short-protein
+AIQRTPKIQVYSRHPAENGKSNFLNCYVSGFHPSDIEVDLLKNGERIEKVEHSDLSFSKDWSFYLLYYTEFTPTEKDEYACRVNHVTLSQPKIVKWDRDM
+
+>protein|name=example-peptide
+GAAL
+
+>ligand|name=example-ligand-as-smiles
+CCCCCCCCCCCCCC(=O)O
+```
+
+</div>
+<small>For a peptide, use `protein` as the molecule type.</small>
+
+**Other example:**
+<div style="background-color:#ffffff; border-radius:8px; padding:18px 24px; margin-bottom:24px; border:1px solid #cccccc;">
+
+```fasta
+>protein|lysozyme
+MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPDLNAAKSELDKAIGRNCNGVITKDEAEKLFNQDVDAAVRGILRNAKLKPVYDSLDAVRRCAAINQVFQMGETGVAGFTNSLRMLQQKRWDEAAVNLAKSRWYNQTPDRAKRVITTFRTGTWDAYKNL
+```
+
+```fasta
+>rna|Chain B
+UUAGGCGGCCACAGCGGUGGGGUUGCCUCCCGUACCCAUCCCGAACACGGAAGAUAAGCCCACCAGCGUUCCGGGGAGUACUGGAGUGCGCGAGCCUCUGGGAAACCCGGUUCGCCGCCACC
+MNIFEMLRIDEGLRLKIYKDTEGYYTIGIGHLLTKSPDLNAAKSELDKAIGRNCNGVITKDEAEKLFNQDVDAAVRGILRNAKLKPVYDSLDAVRRCAAINQVFQMGETGVAGFTNSLRMLQQKRWDEAAVNLAKSRWYNQTPDRAKRVITTFRTGTWDAYKNL
+```
+
+</div>
+
+### 3. <span style="color:#e98935;">Select your config and FASTA files</span>
+<small>Files are stored in your working directory as you create them.</small>
+
+In the `Run folding simulation 🚀` window, refresh the file list by clicking on the `Refresh available files`. Then select the configuration and fasta file you want.
+
+### 4. <span style="color:#e98935;">Run the simulation</span>
+
+Press the `Run Simulation` button to start de folding Simulation. Five proteins folding simulations will be performed. This parameter is hard coded in Chai-1. The simulation time is expected to be from 2min to 10min depending on the molecule.
+
+### 5. <span style="color:#e98935;">Analyse the results of your simulation</span>
+
+To analyse the results of the simulation, two outputs are provided:
+- A table showing the score of the 5 folding performed
+- Interactive 3D visualization of the molecule
+
+Finally, you can get to the `Plot CIF file 💻` window to watch the cif files. This is mainly used to visualize CIF files after using this tool as an MCP server.

app.py

@@ -64,7 +64,7 @@ def select_best_model(
 # Definition of the tools for the MCP server 
 # Function to return a fasta file
 def create_fasta_file(file_content: str, name: Optional[str] = None, seq_name: Optional[str] = None) -> str:
-    """Create a FASTA file from a protein sequence string with a unique name.
+    """Create a FASTA file from a biomolecule sequence string with a unique name.
     
     Args:
         file_content (str): The content of the FASTA file required with optional line breaks
@@ -95,7 +95,10 @@ def create_fasta_file(file_content: str, name: Optional[str] = None, seq_name: O
     
     # Generate a unique file name
     unique_id = hashlib.sha256(uuid4().bytes).hexdigest()[:8]
-    file_name = f"{name if name else "chai1_"+unique_id+".fasta"}"
+    if name:
+        file_name = name
+    else:
+        file_name = f"chai1_{unique_id}.fasta"
     file_path = here / "inputs/fasta" / file_name
     
     # Write the FASTA file
@@ -137,7 +140,11 @@ def create_json_config(
     }
     
     # Generate file name based on provided name or unique ID
-    file_name = f"{name if name else "chai1_"+hashlib.sha256(uuid4().bytes).hexdigest()[:8]+".json"}"
+    unique_id = hashlib.sha256(uuid4().bytes).hexdigest()[:8]
+    if name:
+        file_name = name
+    else:
+        file_name = f"chai1_{unique_id}.json"
     file_path = here / "inputs/config" / file_name
     
     # Write the JSON file 
@@ -225,7 +232,7 @@ def compute_Chai1(
 
 # Function to plot the 3D protein structure
 def plot_protein(result_df) -> str:
-    """Plot the 3D structure of a protein using the DataFrame from compute_Chai1.
+    """Plot the 3D structure of a biomolecule using the DataFrame from compute_Chai1.
 
     Args:
         result_df (pd.DataFrame): DataFrame containing model information and scores
@@ -249,12 +256,13 @@ def plot_protein(result_df) -> str:
     
     return pdb_file
 
+
 # Function to plot a CIF file
 def show_cif_file(cif_file):
     """Plot a 3D structure from a CIF file with the Molecule3D library.
 
     Args:
-        cif_file: A protein structure file in CIF format. This can be a file uploaded by the user.
+        cif_file: A biomolecule structure file in CIF format. This can be a file uploaded by the user.
             If None, the function will return None.
 
     Returns:
@@ -271,6 +279,7 @@ def show_cif_file(cif_file):
     
     return str(pdb_file)
 
+
 # Create the Gradio interface
 reps = [{"model": 0,"style": "cartoon","color": "hydrophobicity"}]
 
@@ -279,29 +288,50 @@ with gr.Blocks(theme=theme) as demo:
     gr.Markdown(
     """
     # Protein Folding Simulation Interface
-    This interface provides the tools to fold any FASTA chain based on Chai-1 model. Also, this is a MCP server to provide all the tools to automate the process of folding proteins with LLMs.     
+    This interface provides the tools to fold FASTA chains based on Chai-1 model. Also, this is a MCP server to provide all the tools to automate the process of folding biomolecules with LLMs.     
     """) 
     
     with gr.Tab("Introduction 🔭"):
         
-        gr.Image("images/logo1.png", show_label=False, width=600, show_download_button=False, show_fullscreen_button=False)
+        gr.Image("images/logo1.png", show_label=False, width=600, show_download_button=False, show_fullscreen_button=False, show_share_button=False)
         
         gr.Markdown(
         """
         # Stakes
 
-        The industry is being deeply changed by the development of LLMs and the recent possibilities to provide them access to external tools. For years, companies have used simulation tools to accelerate and reduce the cost of product development. One of the main challenges in the coming years will be to create agents that can set up, run, and process simulations to further accelerate innovation.
+        The industry is undergoing a profound transformation due to the development of Large Language Models (LLMs) and the recent advancements that enable them to access external tools. 
+        For years, companies have leveraged simulation tools to accelerate and reduce the costs of product development. 
+        One of the primary challenges in the coming years will be to create agents capable of setting up, running, and processing simulations to further expedite innovation.
+        Engineers will focus on analysis rather than simulation setup, allowing them to concentrate on the most critical aspects of their work.
 
         # Objective
 
-        This project is a first step in creating AI agents that perform simulations on existing software. Key domains include:
+        This project represents a first step towards developing AI agents that can perform simulations using existing engineering softwares. 
+        Key domains of application include:
         - **CFD** (Computational Fluid Dynamics) simulations
         - **Biology** (Protein Folding, Molecular Dynamics, etc.)
         - **Neural network applications**
 
-        This project focuses on protein folding, but the same principles can be applied to other domains. In particular it uses [Chai-1](https://www.chaidiscovery.com/blog/introducing-chai-1), which is a multi-modal foundation model for molecular structure prediction, performing at state-of-the-art levels across a variety of benchmarks. Chai-1 enables unified prediction of proteins, small molecules, DNA, RNA, glycosylations, and more. Using Chai-1 on Modal is a great example of running folding simulations.
+        While this project focuses on biomolecules folding, the principles employed can be extended to other domains. 
+        Specifically, it uses [Chai-1](https://www.chaidiscovery.com/blog/introducing-chai-1), a multi-modal foundation model for molecular structure prediction that achieves state-of-the-art performance across various benchmarks. 
+        Chai-1 enables unified prediction of proteins, small molecules, DNA, RNA, glycosylations, and more. 
+
+        Industrial computations frequently require substantial resources (large number of CPUs and GPUs) that are performed on High-Performance Computing (HPC) clusters. 
+        To this end, [Modal Labs](https://modal.com/), a serverless platform that offers a straightforward method to run any application with the latest CPU and GPU hardware, will be used.
+        
+        MCP servers are an efficient solution to connect LLMs to real world engineering applications by providing access to a set of tools. 
+        The purpose of this project is to enable users to run biomolecule folding simulations using the Chai-1 model through any LLM chat or with a Gradio interface.
+                
+        # Benefits
+
+        1. **Efficiency**: The MCP server's connected to high-performance computing capabilities ensure that simulations are run quickly and efficiently.
 
-        Industrial computations are often performed on HPC clusters with large resources, so simulations typically run on separate servers. The LLM must be able to access simulation results to provide complete answers to users. To this purpose, [Modal](https://modal.com/), a serverless platform that provides a simple way to run any application with the latest CPU and GPU hardware will be used.
+        2. **Ease of Use**: Only provide necessary parameters to the user to simplify the process of setting up and running complex simulations.
+
+        3. **Integration**: The seamless integration between the LLM's chat interface and the MCP server allows for a streamlined workflow, from simulation setup to results analysis.
+        
+        The following video illustrates a practical use of the MCP server to run a biomolecule folding simulation using the Chai-1 model. 
+        In this scenario, Copilot is used in Agent mode with Claude 3.5 Sonnet to leverage the tools provided by the MCP server.
 
         """
         )
@@ -319,6 +349,16 @@ with gr.Blocks(theme=theme) as demo:
             label="MCP demonstration video"
         )
         
+        gr.Markdown(
+        """
+        # MCP tools
+        1. `create_fasta_file`: Create a FASTA file from a biomolecule sequence string with a unique name.
+        2. `create_json_config`: Create a JSON configuration file from the Gradio interface inputs.
+        3. `compute_Chai1`: Compute a Chai-1 simulation on Modal labs server. Return a DataFrame with protein scores.
+        4. `plot_protein`: Plot the 3D structure of a biomolecule using the DataFrame from `compute_Chai1` (Use for Gradio interface).
+        5. `show_cif_file`: Plot a 3D structure from a CIF file with the Molecule3D library (Use for the Gradio interface).
+        """)
+        
         with open("introduction_page.md", "r") as f:
             intro_md = f.read()
         gr.Markdown(intro_md)
@@ -330,10 +370,16 @@ with gr.Blocks(theme=theme) as demo:
         The simulation was run with the default configuration and the image is 3D view from the Gradio interface.
         """)    
         
-        gr.Image("images/protein.png", show_label=True, width=400, label="Protein Folding example", show_download_button=False, show_fullscreen_button=False)
+        gr.Image("images/protein.png", show_label=True, width=400, label="Protein Folding example", show_download_button=False, show_fullscreen_button=False, show_share_button=False)
     
         gr.Markdown(
         """
+        # What's next?
+        1. Expose additional tools to post-process the results of the simulations (ex: Plot images of the molecule structure from a file). 
+        The current post-processing tools are suited for the Gradio interface.
+        2. Continue the pipeline by adding softawres like [OpenMM](https://openmm.org/) or [Gromacs](https://www.gromacs.org/) for molecular dynamics simulations.
+        3. Perform full simulation plans including loops over parameters fully automated by the LLM.
+        
         # Contact
         For any issues or questions, please contact the developer or refer to the documentation.
         """)    
@@ -377,7 +423,7 @@ with gr.Blocks(theme=theme) as demo:
         with gr.Row():                
             with gr.Column(scale=1):
                 inp2 = gr.FileExplorer(root_dir=here / "inputs/config", 
-                                value="chai1_quick_inference.json",
+                                value="chai1_default_inference.json",
                                 label="Configuration file", 
                                 file_count='single')    
                 
@@ -415,7 +461,7 @@ with gr.Blocks(theme=theme) as demo:
         )
     
     
-    with gr.Tab("Show molecule from a CIF file 💻"):     
+    with gr.Tab("Plot CIF file 💻"):     
         
         gr.Markdown(
         """

introduction_page.md

@@ -6,14 +6,14 @@ code[class*="language-bash"], pre[class*="language-bash"] {
 
 ---
 
-# Instructions
+# Gradio interface instructions
 
 <div style="background-color:#f5f5f5; border-radius:8px; padding:18px 24px; margin-bottom:24px; border:1px solid #cccccc;">
 
 ### 1. <span style="color:#e98935;">Create your JSON configuration file (Optional)</span>
 <small>Default configuration is available if you skip this step.</small>
 
-- In the `Configuration 📦` window, set your simulation parameters and generate the JSON config file. You can provide a file name in the dedicated box that will appear in the list of available configuration files. If you don't, a unique identifier will be assigned (e.g., `chai_{run_id}_config.json`).
+- In the `Configuration 📦` window, set your simulation parameters and generate the JSON config file. You can provide a file name in the dedicated box that will appear in the list of available configuration files. If you don't, a unique identifier will be assigned (e.g., `chai_{unique_id}_config.json`).
 - **Parameters:**
   - <b>Number of diffusion time steps:</b> 1 to 500
   - <b>Number of trunk recycles:</b> 1 to 5
@@ -24,7 +24,7 @@ code[class*="language-bash"], pre[class*="language-bash"] {
 ### 2. <span style="color:#e98935;">Upload a FASTA file with your molecule sequence (Optional)</span>
 <small>Default FASTA files are available if you skip this step.</small>
 
-- In the `Configuration 📦` window, write your FASTA content and create the file. You can provide a file name in the dedicated box that will appear in the list of available configuration files. If you don't provide a file name a unique identifier will be assigned (e.g., `chai_{run_id}_input.fasta`). Also, if you don't provide a fasta content a default sequence will be written in the file.
+- In the `Configuration 📦` window, write your FASTA content and create the file. You can provide a file name in the dedicated box that will appear in the list of available configuration files. If you don't provide a file name a unique identifier will be assigned (e.g., `chai_{unique_id}_input.fasta`). Also, if you don't provide a fasta content a default sequence will be written in the file.
 - <b style="color:#b91c1c;">Warning:</b> The header must be well formatted for Chai1 to process it.
 
 **FASTA template:**
@@ -77,7 +77,7 @@ In the `Run folding simulation 🚀` window, refresh the file list by clicking o
 
 ### 4. <span style="color:#e98935;">Run the simulation</span>
 
-Press the `Run Simulation` button to start de folding Simulation. Five protein folding simulations will be performed. Unfortunately, this parameter is hard coded in Chai-1. The simulation time is expected to be from 2min to 10min depending on the molecule.
+Press the `Run Simulation` button to start the folding simulation. Five biomolecules folding simulations will be performed. This parameter is hard coded in Chai-1. The simulation time is expected to be from 2min to 10min depending on the molecule.
 
 ### 5. <span style="color:#e98935;">Analyse the results of your simulation</span>
 
@@ -85,6 +85,6 @@ To analyse the results of the simulation, two outputs are provided:
 - A table showing the score of the 5 folding performed
 - Interactive 3D visualization of the molecule
 
-Finally, you can get to the `Show molecule from a CIF file 💻` window to watch the cif files. This is mainly used to visualize CIF files after using this tool as an MCP server.
+Finally, you can get to the `Plot CIF file 💻` window to watch the cif files. This is mainly used to visualize CIF files after using this tool as an MCP server.
 
 </div>