Add keep-alive scripts and environment configuration for Tranception Space

.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(grep:*)",
+      "Bash(git reset:*)",
+      "Bash(git rm:*)",
+      "Bash(python test:*)",
+      "Bash(rm:*)",
+      "Bash(chmod:*)"
+    ],
+    "deny": []
+  }
+}

.env.example

@@ -0,0 +1,13 @@
+# Environment variables for Tranception app
+
+# Set to 'true' to disable Zero GPU support (useful for debugging or when Zero GPU is unstable)
+DISABLE_ZERO_GPU=false
+
+# Set to 'true' to enable debug logging
+DEBUG_MODE=false
+
+# Maximum inference batch size (reduce for CPU mode)
+MAX_BATCH_SIZE=50
+
+# Timeout for Zero GPU operations (in seconds)
+ZERO_GPU_TIMEOUT=300

.github/workflows/keep_space_alive.yml

@@ -0,0 +1,44 @@
+name: Keep Hugging Face Space Alive
+
+on:
+  schedule:
+    # Run every 30 minutes
+    - cron: '*/30 * * * *'
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  keep-alive:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Ping Tranception Space
+      run: |
+        SPACE_URL="https://huggingface.co/spaces/MoraxCheng/Transeption_iGEM_BASISCHINA_2025"
+        
+        # Try to access the Space
+        response=$(curl -s -o /dev/null -w "%{http_code}" "$SPACE_URL" --max-time 30)
+        echo "Space returned HTTP $response"
+        
+        if [ "$response" != "200" ]; then
+          echo "Space might be sleeping, sending wake-up request..."
+          
+          # Send a minimal prediction request
+          curl -s -X POST "$SPACE_URL/api/predict" \
+            -H "Content-Type: application/json" \
+            -d '{
+              "fn_index": 0,
+              "data": ["MSKGEELFTGVVPILVELDGDVNGHKFSVSGEGEGDATYGKLTLKFICTTGKLPVPWPTLVTTLSYGVQCFSRYPDHMKQHDFFKSAMPEGYVQERTIFFKDDGNYKTRAEVKFEGDTLVNRIELKGIDFKEDGNILGHKLEYNYNSHNVYIMADKQKNGIKVNFKIRHNIEDGSVQLADHYQQNTPIGDGPVLLPDNHYLSTQSALSKDPNEKRDHMVLLEFVTAAGITHGMDELYK",
+                1, 10, "Small", false, 10
+              ]
+            }' \
+            --max-time 120 > /dev/null || true
+          
+          echo "Wake-up request sent"
+        else
+          echo "Space is active!"
+        fi
+        
+    - name: Log Status
+      if: always()
+      run: |
+        echo "Keep-alive job completed at $(date)"

app.py

@@ -17,10 +17,22 @@ import zipfile
 import shutil
 import uuid
 import gc
+import time
+import signal
+import threading
+import datetime
 
 # Check if Zero GPU should be disabled via environment variable
 DISABLE_ZERO_GPU = os.environ.get('DISABLE_ZERO_GPU', 'false').lower() == 'true'
 
+# Keep-alive settings
+KEEP_ALIVE_INTERVAL = 300  # 5 minutes
+last_activity_time = datetime.datetime.now()
+keep_alive_thread = None
+
+# Auto-refresh component to keep connection alive
+AUTO_REFRESH_INTERVAL = 240  # 4 minutes
+
 # Create a mock spaces module for fallback
 class MockSpaces:
     """Mock spaces module for when Zero GPU is not available"""
@@ -52,6 +64,79 @@ else:
         spaces = MockSpaces()
         print(f"Warning: Error with spaces module: {e}. Running without Zero GPU support.")
 
+# Flag to track if we should avoid Zero GPU due to initialization errors
+USE_ZERO_GPU = SPACES_AVAILABLE and not DISABLE_ZERO_GPU
+
+# Global flag to track initialization state
+INIT_FAILED = False
+
+def handle_init_error(signum, frame):
+    """Handle initialization errors gracefully"""
+    global INIT_FAILED
+    INIT_FAILED = True
+    print("Handling initialization error...")
+    sys.exit(1)
+
+# Set up signal handler for graceful shutdown
+signal.signal(signal.SIGTERM, handle_init_error)
+
+def update_activity():
+    """Update last activity time"""
+    global last_activity_time
+    last_activity_time = datetime.datetime.now()
+
+def keep_alive_worker():
+    """Background thread to keep the Space alive"""
+    while True:
+        try:
+            time.sleep(KEEP_ALIVE_INTERVAL)
+            current_time = datetime.datetime.now()
+            time_since_activity = (current_time - last_activity_time).total_seconds()
+            
+            print(f"Keep-alive check: Last activity {time_since_activity:.0f} seconds ago")
+            
+            # Update activity timestamp
+            if time_since_activity > KEEP_ALIVE_INTERVAL:
+                print("Updating activity timestamp...")
+                update_activity()
+                
+                # Create a dummy inference to keep Zero GPU warm
+                try:
+                    if USE_ZERO_GPU and hasattr(score_and_create_matrix_all_singles, '__wrapped__'):
+                        print("Triggering keep-alive inference...")
+                        # Use the smallest possible input
+                        dummy_result = score_and_create_matrix_all_singles(
+                            sequence="MSKGE",
+                            mutation_range_start=1,
+                            mutation_range_end=2,
+                            model_type="Small",
+                            scoring_mirror=False,
+                            batch_size_inference=1
+                        )
+                        print("Keep-alive inference completed")
+                        # Clean up results
+                        if dummy_result and len(dummy_result) > 2:
+                            for file in dummy_result[2]:  # CSV files
+                                try:
+                                    os.remove(file)
+                                except:
+                                    pass
+                except Exception as e:
+                    print(f"Keep-alive inference error (non-critical): {e}")
+        except Exception as e:
+            print(f"Keep-alive thread error: {e}")
+            time.sleep(60)  # Wait a bit before retrying
+
+def warm_up_zero_gpu():
+    """Warm up Zero GPU after idle period"""
+    if not USE_ZERO_GPU:
+        return False
+    
+    print("Warming up Zero GPU...")
+    # Note: Cannot reliably warm up Zero GPU outside of decorated functions
+    # This is a limitation of the Zero GPU system
+    return False
+
 # Add current directory to path
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
@@ -259,6 +344,9 @@ def get_mutated_protein(sequence,mutant):
   return ''.join(mutated_sequence)
 
 def score_and_create_matrix_all_singles_impl(sequence,mutation_range_start=None,mutation_range_end=None,model_type="Large",scoring_mirror=False,batch_size_inference=20,max_number_positions_per_heatmap=50,num_workers=0,AA_vocab=AA_vocab):
+  # Update activity time
+  update_activity()
+  
   # Clean up old files periodically
   cleanup_old_files()
   
@@ -295,6 +383,11 @@ def score_and_create_matrix_all_singles_impl(sequence,mutation_range_start=None,
   
   # Device selection - Zero GPU will provide CUDA when decorated with @spaces.GPU
   print(f"GPU Available: {torch.cuda.is_available()}")
+  
+  # Try to ensure GPU is available when using Zero GPU
+  if USE_ZERO_GPU and not torch.cuda.is_available():
+    print("Zero GPU enabled but CUDA not available - this is expected before GPU allocation")
+  
   if torch.cuda.is_available():
     device = torch.device("cuda")
     model = model.to(device)
@@ -308,7 +401,9 @@ def score_and_create_matrix_all_singles_impl(sequence,mutation_range_start=None,
     device = torch.device("cpu")
     model = model.to(device)
     print("Inference will take place on CPU")
-    print("Note: If you expected GPU, ensure Zero GPU is enabled in Space settings")
+    if USE_ZERO_GPU:
+      print("WARNING: Zero GPU is enabled but CUDA is not available!")
+      print("The Space may need to be restarted from the Hugging Face interface.")
     # Reduce batch size for CPU inference
     batch_size_inference = min(batch_size_inference, 10)
     
@@ -366,15 +461,10 @@ def score_and_create_matrix_all_singles_impl(sequence,mutation_range_start=None,
         torch.cuda.empty_cache()
 
 # Apply Zero GPU decorator - will use real decorator if available, mock otherwise
-try:
+if USE_ZERO_GPU:
     score_and_create_matrix_all_singles = spaces.GPU(duration=300)(score_and_create_matrix_all_singles_impl)
-except Exception as e:
-    print(f"Warning: Failed to apply GPU decorator with duration: {e}")
-    try:
-        score_and_create_matrix_all_singles = spaces.GPU()(score_and_create_matrix_all_singles_impl)
-    except Exception as e2:
-        print(f"Warning: Failed to apply GPU decorator: {e2}")
-        score_and_create_matrix_all_singles = score_and_create_matrix_all_singles_impl
+else:
+    score_and_create_matrix_all_singles = score_and_create_matrix_all_singles_impl
 
 def extract_sequence(protein_id, taxon, sequence):
   return sequence
@@ -385,6 +475,19 @@ def clear_inputs(protein_sequence_input,mutation_range_start,mutation_range_end)
   mutation_range_end = None
   return protein_sequence_input,mutation_range_start,mutation_range_end
 
+# Health check endpoint
+def health_check():
+    """Simple health check that returns current status"""
+    update_activity()
+    status = {
+        "status": "healthy",
+        "zero_gpu": USE_ZERO_GPU,
+        "cuda_available": torch.cuda.is_available(),
+        "last_activity": last_activity_time.isoformat(),
+        "timestamp": datetime.datetime.now().isoformat()
+    }
+    return status
+
 # Create Gradio app
 tranception_design = gr.Blocks()
 
@@ -393,7 +496,42 @@ with tranception_design:
     gr.Markdown("## 🧬 BASIS-China iGEM Team 2025 - Protein Engineering Platform")
     gr.Markdown("### Welcome to BASIS-China's implementation of Tranception on Hugging Face Spaces!")
     gr.Markdown("We are the BASIS-China iGEM team, and we're excited to present our deployment of the Tranception model for protein fitness prediction. This tool enables in silico directed evolution to iteratively improve protein fitness through single amino acid substitutions. At each step, Tranception computes log likelihood ratios for all possible mutations compared to the starting sequence, generating fitness heatmaps and recommendations to guide protein engineering.")
-    gr.Markdown("**Technical Details**: This deployment leverages Hugging Face's Zero GPU infrastructure, which dynamically allocates H200 GPU resources when available. This allows for efficient inference while managing computational resources effectively. When GPU resources are temporarily unavailable, the system seamlessly falls back to CPU processing.")
+    gr.Markdown("**Technical Details**: This deployment leverages Hugging Face's Zero GPU infrastructure, which dynamically allocates H200 GPU resources when available. This allows for efficient inference while managing computational resources effectively. The system includes automatic keep-alive mechanisms to maintain GPU availability.")
+    
+    # Status indicator
+    with gr.Row():
+        with gr.Column(scale=1):
+            def get_gpu_status():
+                time_since = (datetime.datetime.now() - last_activity_time).total_seconds()
+                if USE_ZERO_GPU:
+                    if torch.cuda.is_available():
+                        gpu_name = torch.cuda.get_device_name(0)
+                        return f"🔥 Zero GPU Active: {gpu_name} | Last activity: {int(time_since)}s ago"
+                    else:
+                        return f"⚠️ Zero GPU: Ready | Last activity: {int(time_since)}s ago"
+                else:
+                    return "💻 Running on CPU"
+            
+            gpu_status = gr.Textbox(
+                label="Compute Status", 
+                value=get_gpu_status, 
+                every=5,  # Update every 5 seconds
+                interactive=False,
+                elem_id="gpu_status"
+            )
+    
+    # Hidden components for keep-alive
+    with gr.Row(visible=False):
+        # Auto-refresh component to maintain WebSocket connection
+        keep_alive_refresh = gr.Number(value=0, visible=False)
+        
+        def increment_counter():
+            update_activity()
+            return gr.update(value=time.time())
+        
+        # This will trigger every 4 minutes to keep the connection alive
+        keep_alive_timer = gr.Timer(value=AUTO_REFRESH_INTERVAL)
+        keep_alive_timer.tick(increment_counter, outputs=[keep_alive_refresh])
     
     with gr.Tabs():
         with gr.TabItem("Input"):
@@ -484,6 +622,15 @@ with tranception_design:
     gr.Markdown("Links: <a href='https://proceedings.mlr.press/v162/notin22a.html' target='_blank'>Paper</a>  <a href='https://github.com/OATML-Markslab/Tranception' target='_blank'>Code</a>  <a href='https://sites.google.com/view/proteingym/substitutions' target='_blank'>ProteinGym</a>  <a href='https://igem.org/teams/5247' target='_blank'>BASIS-China iGEM Team</a>")
 
 if __name__ == "__main__":
+    # Start keep-alive thread
+    if USE_ZERO_GPU:
+        print("Starting keep-alive thread for Zero GPU...")
+        keep_alive_thread = threading.Thread(target=keep_alive_worker, daemon=True)
+        keep_alive_thread.start()
+        
+        # Schedule periodic dummy inferences to keep alive
+        print("Keep-alive system activated - will perform dummy inferences every 5 minutes")
+    
     # Configure queue for better resource management
     tranception_design.queue(
         max_size=10,  # Limit queue size
@@ -492,10 +639,49 @@ if __name__ == "__main__":
     )
     
     # Launch with appropriate settings for HF Spaces
-    # The spaces module is already handled above (either real or mock)
-    tranception_design.launch(
-        max_threads=2,  # Limit concurrent threads
-        show_error=True,
-        server_name="0.0.0.0",
-        server_port=7860
-    )
+    # Wrap launch in try-except to handle Zero GPU initialization errors gracefully
+    launch_retries = 0
+    max_launch_retries = 3
+    
+    while launch_retries < max_launch_retries:
+        try:
+            # Add a small delay on retries to allow system to stabilize
+            if launch_retries > 0:
+                print(f"Retry attempt {launch_retries}/{max_launch_retries}...")
+                time.sleep(5)
+            
+            tranception_design.launch(
+                max_threads=2,  # Limit concurrent threads
+                show_error=True,
+                server_name="0.0.0.0",
+                server_port=7860,
+                quiet=False,  # Show all logs
+                prevent_thread_lock=True,  # Prevent thread locking issues
+                share=False,  # Don't create public link
+                inbrowser=False  # Don't open browser
+            )
+            break  # If successful, exit the retry loop
+            
+        except RuntimeError as e:
+            error_msg = str(e)
+            if "ZeroGPU" in error_msg or "Unknown" in error_msg:
+                print(f"Zero GPU initialization error: {e}")
+                launch_retries += 1
+                
+                if launch_retries < max_launch_retries:
+                    print("Retrying with Zero GPU after warm-up...")
+                    # Wait longer before retry
+                    time.sleep(10)
+                else:
+                    print("Max retries reached. The Space may need to be restarted.")
+                    print("Note: Zero GPU containers can crash after idle periods.")
+                    print("Consider restarting the Space from the Hugging Face interface.")
+                    sys.exit(1)
+            else:
+                # Non-Zero GPU error, re-raise
+                raise
+        except Exception as e:
+            print(f"Unexpected error during launch: {e}")
+            launch_retries += 1
+            if launch_retries >= max_launch_retries:
+                raise

app_wrapper.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""
+Wrapper script for Tranception app with Zero GPU error handling
+"""
+import os
+import sys
+import subprocess
+import time
+
+def run_app(disable_zero_gpu=False):
+    """Run the main app with optional Zero GPU disable"""
+    env = os.environ.copy()
+    if disable_zero_gpu:
+        env['DISABLE_ZERO_GPU'] = 'true'
+        print("Running with Zero GPU disabled")
+    else:
+        print("Attempting to run with Zero GPU support")
+    
+    cmd = [sys.executable, "app.py"]
+    return subprocess.run(cmd, env=env)
+
+def main():
+    """Main wrapper that handles Zero GPU initialization errors"""
+    max_retries = 3
+    retry_count = 0
+    
+    while retry_count < max_retries:
+        try:
+            # First attempt with Zero GPU
+            if retry_count == 0:
+                result = run_app(disable_zero_gpu=False)
+            else:
+                # Subsequent attempts without Zero GPU
+                print(f"Retry {retry_count}: Running without Zero GPU")
+                result = run_app(disable_zero_gpu=True)
+            
+            # Check if the app exited due to Zero GPU error
+            if result.returncode == 1:
+                retry_count += 1
+                if retry_count < max_retries:
+                    print(f"App crashed. Waiting 5 seconds before retry...")
+                    time.sleep(5)
+                continue
+            else:
+                # Normal exit or other error
+                break
+                
+        except KeyboardInterrupt:
+            print("\nShutting down...")
+            break
+        except Exception as e:
+            print(f"Unexpected error: {e}")
+            retry_count += 1
+            if retry_count < max_retries:
+                time.sleep(5)
+    
+    if retry_count >= max_retries:
+        print("Max retries reached. Please check the logs.")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

app_zero_gpu_fixed.py

@@ -0,0 +1,498 @@
+#!/usr/bin/env python3
+"""
+Tranception Design App - Hugging Face Spaces Version (Zero GPU Fixed)
+"""
+import os
+import sys
+import torch
+import transformers
+from transformers import PreTrainedTokenizerFast
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+import gradio as gr
+from huggingface_hub import hf_hub_download
+import shutil
+import uuid
+import gc
+import time
+import datetime
+
+# Simplified Zero GPU handling
+try:
+    import spaces
+    SPACES_AVAILABLE = True
+    print("Zero GPU support detected")
+except ImportError:
+    SPACES_AVAILABLE = False
+    print("Running without Zero GPU support")
+
+# Add current directory to path
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Check if we need to download and extract the tranception module
+if not os.path.exists("tranception"):
+    print("Downloading Tranception repository...")
+    try:
+        # Clone the repository structure
+        result = os.system("git clone https://github.com/OATML-Markslab/Tranception.git temp_tranception")
+        if result != 0:
+            raise Exception("Failed to clone Tranception repository")
+        # Move the tranception module to current directory
+        shutil.move("temp_tranception/tranception", "tranception")
+        # Clean up
+        shutil.rmtree("temp_tranception")
+    except Exception as e:
+        print(f"Error setting up Tranception: {e}")
+        if os.path.exists("temp_tranception"):
+            shutil.rmtree("temp_tranception")
+        raise
+
+import tranception
+from tranception import config, model_pytorch
+
+# Download model checkpoints if not present
+def download_model_from_hf(model_name):
+    """Download model from Hugging Face Hub if not present locally"""
+    model_path = f"./{model_name}"
+    if not os.path.exists(model_path):
+        print(f"Loading {model_name} model from Hugging Face Hub...")
+        # All models are available on HF Hub
+        return f"PascalNotin/{model_name}"
+    return model_path
+
+AA_vocab = "ACDEFGHIKLMNPQRSTVWY"
+tokenizer = PreTrainedTokenizerFast(tokenizer_file="./tranception/utils/tokenizers/Basic_tokenizer",
+                                                unk_token="[UNK]",
+                                                sep_token="[SEP]",
+                                                pad_token="[PAD]",
+                                                cls_token="[CLS]",
+                                                mask_token="[MASK]"
+                                            )
+
+def create_all_single_mutants(sequence,AA_vocab=AA_vocab,mutation_range_start=None,mutation_range_end=None):
+  all_single_mutants={}
+  sequence_list=list(sequence)
+  if mutation_range_start is None: mutation_range_start=1
+  if mutation_range_end is None: mutation_range_end=len(sequence)
+  for position,current_AA in enumerate(sequence[mutation_range_start-1:mutation_range_end]):
+    for mutated_AA in AA_vocab:
+      if current_AA!=mutated_AA:
+        mutated_sequence = sequence_list.copy()
+        mutated_sequence[mutation_range_start + position - 1] = mutated_AA
+        all_single_mutants[current_AA+str(mutation_range_start+position)+mutated_AA]="".join(mutated_sequence)
+  all_single_mutants = pd.DataFrame.from_dict(all_single_mutants,columns=['mutated_sequence'],orient='index')
+  all_single_mutants.reset_index(inplace=True)
+  all_single_mutants.columns = ['mutant','mutated_sequence']
+  return all_single_mutants
+
+def create_scoring_matrix_visual(scores,sequence,image_index=0,mutation_range_start=None,mutation_range_end=None,AA_vocab=AA_vocab,annotate=True,fontsize=20,unique_id=None):
+  if unique_id is None:
+    unique_id = str(uuid.uuid4())
+    
+  filtered_scores=scores.copy()
+  filtered_scores=filtered_scores[filtered_scores.position.isin(range(mutation_range_start,mutation_range_end+1))]
+  piv=filtered_scores.pivot(index='position',columns='target_AA',values='avg_score').round(4)
+  
+  # Save CSV file
+  csv_path = 'fitness_scoring_substitution_matrix_{}_{}.csv'.format(unique_id, image_index)
+  
+  # Create a more detailed CSV with mutation info
+  csv_data = []
+  for position in range(mutation_range_start,mutation_range_end+1):
+    for target_AA in list(AA_vocab):
+      mutant = sequence[position-1]+str(position)+target_AA
+      if mutant in set(filtered_scores.mutant):
+        score_value = filtered_scores.loc[filtered_scores.mutant==mutant,'avg_score']
+        if isinstance(score_value, pd.Series):
+          score = float(score_value.iloc[0])
+        else:
+          score = float(score_value)
+      else:
+        score = 0.0
+      
+      csv_data.append({
+        'position': position,
+        'original_AA': sequence[position-1],
+        'target_AA': target_AA,
+        'mutation': mutant,
+        'fitness_score': score
+      })
+  
+  csv_df = pd.DataFrame(csv_data)
+  csv_df.to_csv(csv_path, index=False)
+  
+  # Continue with visualization
+  mutation_range_len = mutation_range_end - mutation_range_start + 1
+  # Limit figure size to prevent memory issues
+  fig_width = min(50, len(AA_vocab) * 0.8)
+  fig_height = min(mutation_range_len, 50)
+  fig, ax = plt.subplots(figsize=(fig_width, fig_height))
+  scores_dict = {}
+  valid_mutant_set=set(filtered_scores.mutant)  
+  ax.tick_params(bottom=True, top=True, left=True, right=True)
+  ax.tick_params(labelbottom=True, labeltop=True, labelleft=True, labelright=True)
+  if annotate:
+    for position in range(mutation_range_start,mutation_range_end+1):
+      for target_AA in list(AA_vocab):
+        mutant = sequence[position-1]+str(position)+target_AA
+        if mutant in valid_mutant_set:
+          score_value = filtered_scores.loc[filtered_scores.mutant==mutant,'avg_score']
+          if isinstance(score_value, pd.Series):
+            scores_dict[mutant] = float(score_value.iloc[0])
+          else:
+            scores_dict[mutant] = float(score_value)
+        else:
+          scores_dict[mutant]=0.0
+    labels = (np.asarray(["{} \n {:.4f}".format(symb,value) for symb, value in scores_dict.items() ])).reshape(mutation_range_len,len(AA_vocab))
+    heat = sns.heatmap(piv,annot=labels,fmt="",cmap='RdYlGn',linewidths=0.30,ax=ax,vmin=np.percentile(scores.avg_score,2),vmax=np.percentile(scores.avg_score,98),\
+                cbar_kws={'label': 'Log likelihood ratio (mutant / starting sequence)'},annot_kws={"size": fontsize})
+  else:
+    heat = sns.heatmap(piv,cmap='RdYlGn',linewidths=0.30,ax=ax,vmin=np.percentile(scores.avg_score,2),vmax=np.percentile(scores.avg_score,98),\
+                cbar_kws={'label': 'Log likelihood ratio (mutant / starting sequence)'},annot_kws={"size": fontsize})
+  heat.figure.axes[-1].yaxis.label.set_size(fontsize=int(fontsize*1.5))
+  heat.set_title("Higher predicted scores (green) imply higher protein fitness",fontsize=fontsize*2, pad=40)
+  heat.set_ylabel("Sequence position", fontsize = fontsize*2)
+  heat.set_xlabel("Amino Acid mutation", fontsize = fontsize*2)
+  
+  # Set y-axis labels (positions)
+  yticklabels = [str(pos)+' ('+sequence[pos-1]+')' for pos in range(mutation_range_start,mutation_range_end+1)]
+  heat.set_yticklabels(yticklabels, fontsize=fontsize, rotation=0)
+  
+  # Set x-axis labels (amino acids) - ensuring correct number
+  heat.set_xticklabels(list(AA_vocab), fontsize=fontsize)
+  try:
+    plt.tight_layout()
+    image_path = 'fitness_scoring_substitution_matrix_{}_{}.png'.format(unique_id, image_index)
+    plt.savefig(image_path,dpi=100)
+    return image_path, csv_path
+  finally:
+    plt.close('all')  # Ensure all figures are closed
+    plt.clf()  # Clear the current figure
+    plt.cla()  # Clear the current axes
+
+def suggest_mutations(scores):
+  intro_message = "The following mutations may be sensible options to improve fitness: \n\n"
+  #Best mutants
+  top_mutants=list(scores.sort_values(by=['avg_score'],ascending=False).head(5).mutant)
+  top_mutants_fitness=list(scores.sort_values(by=['avg_score'],ascending=False).head(5).avg_score)
+  top_mutants_recos = [top_mutant+" ("+str(round(top_mutant_fitness,4))+")" for (top_mutant,top_mutant_fitness) in zip(top_mutants,top_mutants_fitness)]
+  mutant_recos = "The single mutants with highest predicted fitness are (positive scores indicate fitness increase Vs starting sequence, negative scores indicate fitness decrease):\n {} \n\n".format(", ".join(top_mutants_recos))
+  #Best positions
+  positive_scores = scores[scores.avg_score > 0]
+  if len(positive_scores) > 0:
+    # Only select numeric columns for groupby mean
+    positive_scores_position_avg = positive_scores.groupby(['position'])['avg_score'].mean().reset_index()
+    top_positions=list(positive_scores_position_avg.sort_values(by=['avg_score'],ascending=False).head(5)['position'].astype(str))
+    position_recos = "The positions with the highest average fitness increase are (only positions with at least one fitness increase are considered):\n {}".format(", ".join(top_positions))
+  else:
+    position_recos = "No positions with positive fitness effects found."
+  return intro_message+mutant_recos+position_recos
+
+def check_valid_mutant(sequence,mutant,AA_vocab=AA_vocab):
+  valid = True
+  try:
+    from_AA, position, to_AA = mutant[0], int(mutant[1:-1]), mutant[-1]
+  except:
+    valid = False
+  if valid and position > 0 and position <= len(sequence):
+    if sequence[position-1]!=from_AA: valid=False
+  else:
+    valid = False
+  if to_AA not in AA_vocab: valid=False
+  return valid
+
+def cleanup_old_files(max_age_minutes=30):
+    """Clean up old inference files"""
+    import glob
+    current_time = time.time()
+    patterns = ["fitness_scoring_substitution_matrix_*.png", 
+                "fitness_scoring_substitution_matrix_*.csv",
+                "all_mutations_fitness_scores_*.csv"]
+    
+    cleaned_count = 0
+    for pattern in patterns:
+        for file_path in glob.glob(pattern):
+            try:
+                file_age = current_time - os.path.getmtime(file_path)
+                if file_age > max_age_minutes * 60:
+                    os.remove(file_path)
+                    cleaned_count += 1
+            except Exception as e:
+                # Log error but continue cleaning other files
+                print(f"Warning: Could not remove {file_path}: {e}")
+    
+    if cleaned_count > 0:
+        print(f"Cleaned up {cleaned_count} old files")
+
+def get_mutated_protein(sequence,mutant):
+  if not check_valid_mutant(sequence,mutant):
+    return "The mutant is not valid"
+  mutated_sequence = list(sequence)
+  mutated_sequence[int(mutant[1:-1])-1]=mutant[-1]
+  return ''.join(mutated_sequence)
+
+def score_and_create_matrix_all_singles_impl(sequence,mutation_range_start=None,mutation_range_end=None,model_type="Large",scoring_mirror=False,batch_size_inference=20,max_number_positions_per_heatmap=50,num_workers=0,AA_vocab=AA_vocab):
+  # Clean up old files periodically
+  cleanup_old_files()
+  
+  # Generate unique ID for this request
+  unique_id = str(uuid.uuid4())
+  
+  if mutation_range_start is None: mutation_range_start=1
+  if mutation_range_end is None: mutation_range_end=len(sequence)
+  
+  # Clean sequence
+  sequence = sequence.strip().upper()
+  
+  # Validate
+  assert len(sequence) > 0, "no sequence entered"
+  assert mutation_range_start <= mutation_range_end, "mutation range is invalid"
+  assert mutation_range_end <= len(sequence), f"End position ({mutation_range_end}) exceeds sequence length ({len(sequence)})"
+  
+  # Load model with HF Space compatibility
+  try:
+    if model_type=="Small":
+      model_path = download_model_from_hf("Tranception_Small")
+      model = tranception.model_pytorch.TranceptionLMHeadModel.from_pretrained(pretrained_model_name_or_path=model_path)
+    elif model_type=="Medium":
+      model_path = download_model_from_hf("Tranception_Medium")
+      model = tranception.model_pytorch.TranceptionLMHeadModel.from_pretrained(pretrained_model_name_or_path=model_path)
+    elif model_type=="Large":
+      model_path = download_model_from_hf("Tranception_Large")
+      model = tranception.model_pytorch.TranceptionLMHeadModel.from_pretrained(pretrained_model_name_or_path=model_path)
+  except Exception as e:
+    print(f"Error loading {model_type} model: {e}")
+    print("Falling back to Medium model...")
+    model_path = download_model_from_hf("Tranception_Medium")
+    model = tranception.model_pytorch.TranceptionLMHeadModel.from_pretrained(pretrained_model_name_or_path=model_path)
+  
+  # Device selection - Zero GPU will provide CUDA when decorated with @spaces.GPU
+  print(f"GPU Available: {torch.cuda.is_available()}")
+  
+  if torch.cuda.is_available():
+    device = torch.device("cuda")
+    model = model.to(device)
+    gpu_name = torch.cuda.get_device_name(0)
+    gpu_memory = torch.cuda.get_device_properties(0).total_memory / 1024**3
+    print(f"Inference will take place on {gpu_name}")
+    print(f"GPU Memory: {gpu_memory:.2f} GB")
+    # Increase batch size for GPU inference
+    batch_size_inference = min(batch_size_inference, 50)
+  else:
+    device = torch.device("cpu")
+    model = model.to(device)
+    print("Inference will take place on CPU")
+    # Reduce batch size for CPU inference
+    batch_size_inference = min(batch_size_inference, 10)
+    
+  try:
+    model.eval()
+    model.config.tokenizer = tokenizer
+    
+    all_single_mutants = create_all_single_mutants(sequence,AA_vocab,mutation_range_start,mutation_range_end)
+    
+    with torch.no_grad():
+      scores = model.score_mutants(DMS_data=all_single_mutants, 
+                                        target_seq=sequence, 
+                                        scoring_mirror=scoring_mirror, 
+                                        batch_size_inference=batch_size_inference,  
+                                        num_workers=num_workers, 
+                                        indel_mode=False
+                                        )
+    
+    scores = pd.merge(scores,all_single_mutants,on="mutated_sequence",how="left")
+    scores["position"]=scores["mutant"].map(lambda x: int(x[1:-1]))
+    scores["target_AA"] = scores["mutant"].map(lambda x: x[-1])
+    
+    score_heatmaps = []
+    csv_files = []
+    mutation_range = mutation_range_end - mutation_range_start + 1
+    number_heatmaps = int((mutation_range - 1) / max_number_positions_per_heatmap) + 1
+    image_index = 0
+    window_start = mutation_range_start
+    window_end = min(mutation_range_end,mutation_range_start+max_number_positions_per_heatmap-1)
+    
+    for image_index in range(number_heatmaps):
+      image_path, csv_path = create_scoring_matrix_visual(scores,sequence,image_index,window_start,window_end,AA_vocab,unique_id=unique_id)
+      score_heatmaps.append(image_path)
+      csv_files.append(csv_path)
+      window_start += max_number_positions_per_heatmap
+      window_end = min(mutation_range_end,window_start+max_number_positions_per_heatmap-1)
+    
+    # Also save a comprehensive CSV with all mutations
+    comprehensive_csv_path = 'all_mutations_fitness_scores_{}.csv'.format(unique_id)
+    scores_export = scores[['mutant', 'position', 'target_AA', 'avg_score', 'mutated_sequence']].copy()
+    scores_export['original_AA'] = scores_export['mutant'].str[0]
+    scores_export = scores_export.rename(columns={'avg_score': 'fitness_score'})
+    scores_export = scores_export[['position', 'original_AA', 'target_AA', 'mutant', 'fitness_score', 'mutated_sequence']]
+    scores_export.to_csv(comprehensive_csv_path, index=False)
+    csv_files.append(comprehensive_csv_path)
+    
+    return score_heatmaps, suggest_mutations(scores), csv_files
+    
+  finally:
+    # Always clean up model from memory
+    if 'model' in locals():
+      del model
+      gc.collect()
+      if torch.cuda.is_available():
+        torch.cuda.empty_cache()
+
+# Apply Zero GPU decorator if available
+if SPACES_AVAILABLE:
+    score_and_create_matrix_all_singles = spaces.GPU(duration=300)(score_and_create_matrix_all_singles_impl)
+else:
+    score_and_create_matrix_all_singles = score_and_create_matrix_all_singles_impl
+
+def extract_sequence(protein_id, taxon, sequence):
+  return sequence
+
+def clear_inputs(protein_sequence_input,mutation_range_start,mutation_range_end):
+  protein_sequence_input = ""
+  mutation_range_start = None
+  mutation_range_end = None
+  return protein_sequence_input,mutation_range_start,mutation_range_end
+
+# Create Gradio app
+tranception_design = gr.Blocks()
+
+with tranception_design:
+    gr.Markdown("# In silico directed evolution for protein redesign with Tranception")
+    gr.Markdown("## 🧬 BASIS-China iGEM Team 2025 - Protein Engineering Platform")
+    gr.Markdown("### Welcome to BASIS-China's implementation of Tranception on Hugging Face Spaces!")
+    gr.Markdown("We are the BASIS-China iGEM team, and we're excited to present our deployment of the Tranception model for protein fitness prediction. This tool enables in silico directed evolution to iteratively improve protein fitness through single amino acid substitutions. At each step, Tranception computes log likelihood ratios for all possible mutations compared to the starting sequence, generating fitness heatmaps and recommendations to guide protein engineering.")
+    gr.Markdown("**Technical Details**: This deployment leverages Hugging Face's Zero GPU infrastructure, which dynamically allocates H200 GPU resources when available. This allows for efficient inference while managing computational resources effectively.")
+    
+    # Status indicator
+    with gr.Row():
+        with gr.Column(scale=1):
+            def get_gpu_status():
+                if SPACES_AVAILABLE:
+                    if torch.cuda.is_available():
+                        gpu_name = torch.cuda.get_device_name(0)
+                        return f"🔥 Zero GPU Active: {gpu_name}"
+                    else:
+                        return "⚠️ Zero GPU: Ready (GPU allocated on inference)"
+                else:
+                    return "💻 Running on CPU"
+            
+            gpu_status = gr.Textbox(
+                label="Compute Status", 
+                value=get_gpu_status, 
+                every=5,  # Update every 5 seconds
+                interactive=False,
+                elem_id="gpu_status"
+            )
+    
+    with gr.Tabs():
+        with gr.TabItem("Input"):
+            with gr.Row():
+                protein_sequence_input = gr.Textbox(lines=1, 
+                                                label="Protein sequence",
+                                                placeholder = "Input the sequence of amino acids representing the starting protein of interest or select one from the list of examples below. You may enter the full sequence or just a subdomain (providing full context typically leads to better results, but is slower at inference)"
+                                                )
+            
+            with gr.Row():
+                mutation_range_start = gr.Number(label="Start of mutation window (first position indexed at 1)", value=1, precision=0)
+                mutation_range_end = gr.Number(label="End of mutation window (leave empty for full lenth)", value=10, precision=0)
+
+        with gr.TabItem("Parameters"):
+            with gr.Row():
+                model_size_selection = gr.Radio(label="Tranception model size (larger models are more accurate but are slower at inference)", 
+                                                choices=["Small","Medium","Large"], 
+                                                value="Small")
+            with gr.Row():
+                scoring_mirror = gr.Checkbox(label="Score protein from both directions (leads to more robust fitness predictions, but doubles inference time)")
+            with gr.Row():
+                batch_size_inference = gr.Number(label="Model batch size at inference time (reduce for CPU)",value = 10, precision=0)
+            with gr.Row():
+                gr.Markdown("Note: the current version does not leverage retrieval of homologs at inference time to increase fitness prediction performance.")
+                
+    with gr.Row():
+        clear_button = gr.Button(value="Clear",variant="secondary")
+        run_button = gr.Button(value="Predict fitness",variant="primary")
+        
+    protein_ID = gr.Textbox(label="Uniprot ID", visible=False)
+    taxon = gr.Textbox(label="Taxon", visible=False)
+    
+    examples = gr.Examples(
+        inputs=[protein_ID, taxon, protein_sequence_input],
+        outputs=[protein_sequence_input],
+        fn=extract_sequence,
+        examples=[
+            ['ADRB2_HUMAN'  ,'Human',           'MGQPGNGSAFLLAPNGSHAPDHDVTQERDEVWVVGMGIVMSLIVLAIVFGNVLVITAIAKFERLQTVTNYFITSLACADLVMGLAVVPFGAAHILMKMWTFGNFWCEFWTSIDVLCVTASIETLCVIAVDRYFAITSPFKYQSLLTKNKARVIILMVWIVSGLTSFLPIQMHWYRATHQEAINCYANETCCDFFTNQAYAIASSIVSFYVPLVIMVFVYSRVFQEAKRQLQKIDKSEGRFHVQNLSQVEQDGRTGHGLRRSSKFCLKEHKALKTLGIIMGTFTLCWLPFFIVNIVHVIQDNLIRKEVYILLNWIGYVNSGFNPLIYCRSPDFRIAFQELLCLRRSSLKAYGNGYSSNGNTGEQSGYHVEQEKENKLLCEDLPGTEDFVGHQGTVPSDNIDSQGRNCSTNDSLL'],
+            ['IF1_ECOLI'    ,'Prokaryote',      'MAKEDNIEMQGTVLETLPNTMFRVELENGHVVTAHISGKMRKNYIRILTGDKVTVELTPYDLSKGRIVFRSR'],
+            ['P53_HUMAN'    ,'Human',           'MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGPDEAPRMPEAAPRVAPAPAAPTPAAPAPAPSWPLSSSVPSQKTYQGSYGFRLGFLHSGTAKSVTCTYSPALNKMFCQLAKTCPVQLWVDSTPPPGTRVRAMAIYKQSQHMTEVVRRCPHHERCSDSDGLAPPQHLIRVEGNLRVEYLDDRNTFRHSVVVPYEPPEVGSDCTTIHYNYMCNSSCMGGMNRRPILTIITLEDSSGNLLGRNSFEVRVCACPGRDRRTEEENLRKKGEPHHELPPGSTKRALPNNTSSSPQPKKKPLDGEYFTLQIRGRERFEMFRELNEALELKDAQAGKEPGGSRAHSSHLKSKKGQSTSRHKKLMFKTEGPDSD'],
+            ['BLAT_ECOLX'	  ,'Prokaryote',      'MSIQHFRVALIPFFAAFCLPVFAHPETLVKVKDAEDQLGARVGYIELDLNSGKILESFRPEERFPMMSTFKVLLCGAVLSRVDAGQEQLGRRIHYSQNDLVEYSPVTEKHLTDGMTVRELCSAAITMSDNTAANLLLTTIGGPKELTAFLHNMGDHVTRLDRWEPELNEAIPNDERDTTMPAAMATTLRKLLTGELLTLASRQQLIDWMEADKVAGPLLRSALPAGWFIADKSGAGERGSRGIIAALGPDGKPSRIVVIYTTGSQATMDERNRQIAEIGASLIKHW'],
+            ['BRCA1_HUMAN'	,'Human',           'MDLSALRVEEVQNVINAMQKILECPICLELIKEPVSTKCDHIFCKFCMLKLLNQKKGPSQCPLCKNDITKRSLQESTRFSQLVEELLKIICAFQLDTGLEYANSYNFAKKENNSPEHLKDEVSIIQSMGYRNRAKRLLQSEPENPSLQETSLSVQLSNLGTVRTLRTKQRIQPQKTSVYIELGSDSSEDTVNKATYCSVGDQELLQITPQGTRDEISLDSAKKAACEFSETDVTNTEHHQPSNNDLNTTEKRAAERHPEKYQGSSVSNLHVEPCGTNTHASSLQHENSSLLLTKDRMNVEKAEFCNKSKQPGLARSQHNRWAGSKETCNDRRTPSTEKKVDLNADPLCERKEWNKQKLPCSENPRDTEDVPWITLNSSIQKVNEWFSRSDELLGSDDSHDGESESNAKVADVLDVLNEVDEYSGSSEKIDLLASDPHEALICKSERVHSKSVESNIEDKIFGKTYRKKASLPNLSHVTENLIIGAFVTEPQIIQERPLTNKLKRKRRPTSGLHPEDFIKKADLAVQKTPEMINQGTNQTEQNGQVMNITNSGHENKTKGDSIQNEKNPNPIESLEKESAFKTKAEPISSSISNMELELNIHNSKAPKKNRLRRKSSTRHIHALELVVSRNLSPPNCTELQIDSCSSSEEIKKKKYNQMPVRHSRNLQLMEGKEPATGAKKSNKPNEQTSKRHDSDTFPELKLTNAPGSFTKCSNTSELKEFVNPSLPREEKEEKLETVKVSNNAEDPKDLMLSGERVLQTERSVESSSISLVPGTDYGTQESISLLEVSTLGKAKTEPNKCVSQCAAFENPKGLIHGCSKDNRNDTEGFKYPLGHEVNHSRETSIEMEESELDAQYLQNTFKVSKRQSFAPFSNPGNAEEECATFSAHSGSLKKQSPKVTFECEQKEENQGKNESNIKPVQTVNITAGFPVVGQKDKPVDNAKCSIKGGSRFCLSSQFRGNETGLITPNKHGLLQNPYRIPPLFPIKSFVKTKCKKNLLEENFEEHSMSPEREMGNENIPSTVSTISRNNIRENVFKEASSSNINEVGSSTNEVGSSINEIGSSDENIQAELGRNRGPKLNAMLRLGVLQPEVYKQSLPGSNCKHPEIKKQEYEEVVQTVNTDFSPYLISDNLEQPMGSSHASQVCSETPDDLLDDGEIKEDTSFAENDIKESSAVFSKSVQKGELSRSPSPFTHTHLAQGYRRGAKKLESSEENLSSEDEELPCFQHLLFGKVNNIPSQSTRHSTVATECLSKNTEENLLSLKNSLNDCSNQVILAKASQEHHLSEETKCSASLFSSQCSELEDLTANTNTQDPFLIGSSKQMRHQSESQGVGLSDKELVSDDEERGTGLEENNQEEQSMDSNLGEAASGCESETSVSEDCSGLSSQSDILTTQQRDTMQHNLIKLQQEMAELEAVLEQHGSQPSNSYPSIISDSSALEDLRNPEQSTSEKAVLTSQKSSEYPISQNPEGLSADKFEVSADSSTSKNKEPGVERSSPSKCPSLDDRWYMHSCSGSLQNRNYPSQEELIKVVDVEEQQLEESGPHDLTETSYLPRQDLEGTPYLESGISLFSDDPESDPSEDRAPESARVGNIPSSTSALKVPQLKVAESAQSPAAAHTTDTAGYNAMEESVSREKPELTASTERVNKRMSMVVSGLTPEEFMLVYKFARKHHITLTNLITEETTHVVMKTDAEFVCERTLKYFLGIAGGKWVVSYFWVTQSIKERKMLNEHDFEVRGDVVNGRNHQGPKRARESQDRKIFRGLEICCYGPFTNMPTDQLEWMVQLCGASVVKELSSFTLGTGVHPIVVVQPDAWTEDNGFHAIGQMCEAPVVTREWVLDSVALYQCQELDTYLIPQIPHSHY'],
+            ['CALM1_HUMAN'	,'Human',           'MADQLTEEQIAEFKEAFSLFDKDGDGTITTKELGTVMRSLGQNPTEAELQDMINEVDADGNGTIDFPEFLTMMARKMKDTDSEEEIREAFRVFDKDGNGYISAAELRHVMTNLGEKLTDEEVDEMIREADIDGDGQVNYEEFVQMMTAK'],
+            ['CCDB_ECOLI'	  ,'Prokaryote',	    'MQFKVYTYKRESRYRLFVDVQSDIIDTPGRRMVIPLASARLLSDKVSRELYPVVHIGDESWRMMTTDMASVPVSVIGEEVADLSHRENDIKNAINLMFWGI'],
+            ['GFP_AEQVI'	  ,'Other eukaryote', 'MSKGEELFTGVVPILVELDGDVNGHKFSVSGEGEGDATYGKLTLKFICTTGKLPVPWPTLVTTLSYGVQCFSRYPDHMKQHDFFKSAMPEGYVQERTIFFKDDGNYKTRAEVKFEGDTLVNRIELKGIDFKEDGNILGHKLEYNYNSHNVYIMADKQKNGIKVNFKIRHNIEDGSVQLADHYQQNTPIGDGPVLLPDNHYLSTQSALSKDPNEKRDHMVLLEFVTAAGITHGMDELYK'],
+            ['GRB2_HUMAN'	  ,'Human',           'MEAIAKYDFKATADDELSFKRGDILKVLNEECDQNWYKAELNGKDGFIPKNYIEMKPHPWFFGKIPRAKAEEMLSKQRHDGAFLIRESESAPGDFSLSVKFGNDVQHFKVLRDGAGKYFLWVVKFNSLNELVDYHRSTSVSRNQQIFLRDIEQVPQQPTYVQALFDFDPQEDGELGFRRGDFIHVMDNSDPNWWKGACHGQTGMFPRNYVTPVNRNV'],
+        ],
+    )
+    
+    gr.Markdown("<br>")
+    gr.Markdown("# Fitness predictions for all single amino acid substitutions in mutation range")
+    gr.Markdown("Inference may take a few seconds for short proteins & mutation ranges to several minutes for longer ones")
+    output_image = gr.Gallery(label="Fitness predictions for all single amino acid substitutions in mutation range") #Using Gallery to break down large scoring matrices into smaller images
+    
+    output_recommendations = gr.Textbox(label="Mutation recommendations")
+    
+    with gr.Row():
+        gr.Markdown("## Download CSV Files")
+    output_csv_files = gr.File(label="Download CSV files with fitness scores", file_count="multiple", interactive=False)
+    
+    clear_button.click(
+        inputs = [protein_sequence_input,mutation_range_start,mutation_range_end],
+        outputs = [protein_sequence_input,mutation_range_start,mutation_range_end],
+        fn=clear_inputs
+    )
+    run_button.click(
+        fn=score_and_create_matrix_all_singles,
+        inputs=[protein_sequence_input,mutation_range_start,mutation_range_end,model_size_selection,scoring_mirror,batch_size_inference],
+        outputs=[output_image,output_recommendations,output_csv_files],
+    )
+    
+    gr.Markdown("# Mutate the starting protein sequence")
+    with gr.Row():
+        mutation_triplet = gr.Textbox(lines=1,label="Selected mutation", placeholder = "Input the mutation triplet for the selected mutation (eg., M1A)")
+    mutate_button = gr.Button(value="Apply mutation to starting protein", variant="primary")
+    mutated_protein_sequence = gr.Textbox(lines=1,label="Mutated protein sequence")
+    mutate_button.click(
+        fn = get_mutated_protein,
+        inputs = [protein_sequence_input,mutation_triplet],
+        outputs = mutated_protein_sequence
+    )
+    
+    gr.Markdown("<p>You may now use the output mutated sequence above as the starting sequence for another round of in silico directed evolution.</p>")
+    gr.Markdown("### About BASIS-China iGEM Team")
+    gr.Markdown("We are a high school synthetic biology team participating in the International Genetically Engineered Machine (iGEM) competition. Our 2025 project focuses on protein engineering and computational biology applications. This Tranception deployment is part of our broader effort to make advanced protein design tools accessible to the synthetic biology community.")
+    gr.Markdown("### About Tranception")
+    gr.Markdown("<p><b>Tranception: Protein Fitness Prediction with Autoregressive Transformers and Inference-time Retrieval</b><br>Pascal Notin, Mafalda Dias, Jonathan Frazer, Javier Marchena-Hurtado, Aidan N. Gomez, Debora S. Marks<sup>*</sup>, Yarin Gal<sup>*</sup><br><sup>* equal senior authorship</sup></p>")
+    gr.Markdown("Links: <a href='https://proceedings.mlr.press/v162/notin22a.html' target='_blank'>Paper</a>  <a href='https://github.com/OATML-Markslab/Tranception' target='_blank'>Code</a>  <a href='https://sites.google.com/view/proteingym/substitutions' target='_blank'>ProteinGym</a>  <a href='https://igem.org/teams/5247' target='_blank'>BASIS-China iGEM Team</a>")
+
+if __name__ == "__main__":
+    # Configure queue for better resource management
+    tranception_design.queue(
+        max_size=10,  # Limit queue size
+        status_update_rate="auto",  # Show status updates
+        api_open=False  # Disable API to prevent external requests
+    )
+    
+    # Launch with settings optimized for HF Spaces
+    try:
+        tranception_design.launch(
+            max_threads=2,  # Limit concurrent threads
+            show_error=True,
+            server_name="0.0.0.0",
+            server_port=7860,
+            quiet=False,  # Show all logs
+            prevent_thread_lock=True  # Prevent thread locking issues
+        )
+    except Exception as e:
+        print(f"Launch error: {e}")
+        # If launch fails, try again with minimal settings
+        tranception_design.launch()

healthcheck.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""
+Health check script for Tranception app on Hugging Face Spaces
+"""
+import os
+import sys
+import torch
+
+def check_environment():
+    """Check if the environment is properly configured"""
+    print("=== Tranception Health Check ===")
+    
+    # Check Python version
+    print(f"Python version: {sys.version}")
+    
+    # Check PyTorch
+    print(f"PyTorch version: {torch.__version__}")
+    print(f"CUDA available: {torch.cuda.is_available()}")
+    if torch.cuda.is_available():
+        print(f"CUDA version: {torch.version.cuda}")
+        print(f"GPU: {torch.cuda.get_device_name(0)}")
+    
+    # Check environment variables
+    print(f"\nEnvironment variables:")
+    print(f"DISABLE_ZERO_GPU: {os.environ.get('DISABLE_ZERO_GPU', 'not set')}")
+    print(f"SPACE_ID: {os.environ.get('SPACE_ID', 'not set')}")
+    
+    # Check if running on Hugging Face Spaces
+    if os.environ.get('SPACE_ID'):
+        print("\nRunning on Hugging Face Spaces")
+        
+        # Try to import spaces module
+        try:
+            import spaces
+            print("✓ spaces module available")
+            # Try to create a GPU decorator
+            try:
+                test_decorator = spaces.GPU()
+                print("✓ Zero GPU decorator can be created")
+            except Exception as e:
+                print(f"✗ Zero GPU decorator error: {e}")
+        except ImportError:
+            print("✗ spaces module not available")
+    else:
+        print("\nNot running on Hugging Face Spaces")
+    
+    # Check model files
+    print(f"\nChecking model availability on Hugging Face Hub:")
+    models = ["Tranception_Small", "Tranception_Medium", "Tranception_Large"]
+    for model in models:
+        print(f"- PascalNotin/{model}: Available on HF Hub")
+    
+    print("\n=== Health check complete ===")
+
+if __name__ == "__main__":
+    check_environment()

keep_alive_cron.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Keep-alive script for Tranception Hugging Face Space
+# Add to crontab: */5 * * * * /path/to/keep_alive_cron.sh
+
+SPACE_URL="https://huggingface.co/spaces/MoraxCheng/Transeption_iGEM_BASISCHINA_2025"
+LOG_FILE="/var/log/tranception_keep_alive.log"
+
+# Function to log with timestamp
+log_message() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_FILE"
+}
+
+# Ping the Space
+response=$(curl -s -o /dev/null -w "%{http_code}" "$SPACE_URL" --max-time 30)
+
+if [ "$response" = "200" ]; then
+    log_message "SUCCESS: Space is alive (HTTP $response)"
+else
+    log_message "WARNING: Space returned HTTP $response"
+    
+    # Try to wake it up with a simple request
+    curl -s -X POST "$SPACE_URL/api/predict" \
+        -H "Content-Type: application/json" \
+        -d '{"fn_index": 0, "data": ["MSKGEELFT", 1, 5, "Small", false, 10]}' \
+        --max-time 60 > /dev/null
+    
+    log_message "Sent wake-up request"
+fi
+
+# Keep log file size under control (max 1MB)
+if [ -f "$LOG_FILE" ] && [ $(stat -f%z "$LOG_FILE" 2>/dev/null || stat -c%s "$LOG_FILE" 2>/dev/null) -gt 1048576 ]; then
+    tail -n 1000 "$LOG_FILE" > "$LOG_FILE.tmp"
+    mv "$LOG_FILE.tmp" "$LOG_FILE"
+    log_message "Log file rotated"
+fi

manual_keep_alive.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""
+Manual keep-alive script for Tranception Space
+Run this locally to keep your Space active
+"""
+import requests
+import time
+from datetime import datetime
+
+SPACE_URL = "https://huggingface.co/spaces/MoraxCheng/Transeption_iGEM_BASISCHINA_2025"
+PING_INTERVAL = 300  # 5 minutes
+
+def ping_space():
+    """Ping the Space to keep it alive"""
+    try:
+        print(f"[{datetime.now()}] Pinging Space...")
+        response = requests.get(SPACE_URL, timeout=30)
+        
+        if response.status_code == 200:
+            print(f"✓ Space is alive (HTTP {response.status_code})")
+            return True
+        else:
+            print(f"⚠ Space returned HTTP {response.status_code}")
+            return False
+    except requests.exceptions.Timeout:
+        print("⚠ Request timed out - Space might be starting up")
+        return False
+    except Exception as e:
+        print(f"✗ Error: {e}")
+        return False
+
+def main():
+    print(f"Starting keep-alive for: {SPACE_URL}")
+    print(f"Ping interval: {PING_INTERVAL} seconds")
+    print("Press Ctrl+C to stop\n")
+    
+    while True:
+        try:
+            ping_space()
+            print(f"Next ping in {PING_INTERVAL} seconds...\n")
+            time.sleep(PING_INTERVAL)
+        except KeyboardInterrupt:
+            print("\nStopped by user")
+            break
+
+if __name__ == "__main__":
+    main()

monitor_space.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""
+Monitor and keep alive your Hugging Face Space
+Run this on your local computer or a server
+"""
+import requests
+import time
+from datetime import datetime
+import json
+
+# Your Space details
+SPACE_URL = "https://huggingface.co/spaces/MoraxCheng/Transeption_iGEM_BASISCHINA_2025"
+EMBED_URL = "https://moraxcheng-transeption-igem-basischina-2025.hf.space"
+API_URL = f"{EMBED_URL}/api/predict"
+
+# Monitoring settings
+CHECK_INTERVAL = 300  # 5 minutes
+WAKE_UP_TIMEOUT = 180  # 3 minutes max wait for wake up
+
+def check_space_status():
+    """Check if Space is responding"""
+    try:
+        print(f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] Checking Space status...")
+        response = requests.get(EMBED_URL, timeout=10)
+        
+        if response.status_code == 200:
+            print("✓ Space is online")
+            return True
+        else:
+            print(f"⚠ Space returned status {response.status_code}")
+            return False
+    except requests.exceptions.Timeout:
+        print("⚠ Request timed out - Space might be sleeping")
+        return False
+    except Exception as e:
+        print(f"✗ Error checking status: {e}")
+        return False
+
+def wake_up_space():
+    """Send a minimal request to wake up the Space"""
+    try:
+        print("Attempting to wake up Space...")
+        
+        # Send a minimal prediction request
+        payload = {
+            "fn_index": 0,
+            "data": [
+                "MSKGE",  # Minimal sequence
+                1,        # Start position
+                2,        # End position
+                "Small",  # Model size
+                False,    # No mirror scoring
+                1         # Minimal batch size
+            ]
+        }
+        
+        headers = {
+            "Content-Type": "application/json",
+        }
+        
+        response = requests.post(
+            API_URL,
+            json=payload,
+            headers=headers,
+            timeout=30
+        )
+        
+        if response.status_code in [200, 202]:
+            print("✓ Wake-up request sent successfully")
+            return True
+        else:
+            print(f"⚠ Wake-up request returned status {response.status_code}")
+            return False
+            
+    except Exception as e:
+        print(f"✗ Error sending wake-up request: {e}")
+        return False
+
+def wait_for_space_ready(max_wait=WAKE_UP_TIMEOUT):
+    """Wait for Space to become ready"""
+    print(f"Waiting for Space to become ready (max {max_wait}s)...")
+    start_time = time.time()
+    
+    while time.time() - start_time < max_wait:
+        if check_space_status():
+            print(f"✓ Space is ready after {int(time.time() - start_time)}s")
+            return True
+        
+        print(".", end="", flush=True)
+        time.sleep(10)
+    
+    print(f"\n✗ Space did not become ready after {max_wait}s")
+    return False
+
+def monitor_loop():
+    """Main monitoring loop"""
+    print("="*60)
+    print("Hugging Face Space Monitor")
+    print(f"Space: {SPACE_URL}")
+    print(f"Check interval: {CHECK_INTERVAL}s")
+    print("Press Ctrl+C to stop")
+    print("="*60)
+    
+    consecutive_failures = 0
+    
+    while True:
+        try:
+            # Check if Space is alive
+            if check_space_status():
+                consecutive_failures = 0
+                print(f"Next check in {CHECK_INTERVAL}s...\n")
+            else:
+                consecutive_failures += 1
+                print(f"Space appears to be down (failure #{consecutive_failures})")
+                
+                # Try to wake it up
+                if wake_up_space():
+                    # Wait for it to become ready
+                    if wait_for_space_ready():
+                        consecutive_failures = 0
+                        print("✓ Space successfully revived!\n")
+                    else:
+                        print("✗ Failed to revive Space\n")
+                else:
+                    print("✗ Could not send wake-up request\n")
+                
+                if consecutive_failures >= 3:
+                    print("⚠️  ATTENTION: Space has been down for multiple checks!")
+                    print("You may need to manually restart it from the Hugging Face interface.")
+                    print(f"Go to: {SPACE_URL}/settings\n")
+            
+            # Wait before next check
+            time.sleep(CHECK_INTERVAL)
+            
+        except KeyboardInterrupt:
+            print("\n\nMonitoring stopped by user")
+            break
+        except Exception as e:
+            print(f"\nUnexpected error: {e}")
+            print("Continuing monitoring...\n")
+            time.sleep(60)
+
+if __name__ == "__main__":
+    # Test connection first
+    print("Testing connection to Space...")
+    if check_space_status():
+        print("✓ Initial connection successful\n")
+    else:
+        print("⚠ Space appears to be sleeping, attempting to wake...")
+        if wake_up_space() and wait_for_space_ready():
+            print("✓ Space is now ready\n")
+        else:
+            print("✗ Could not wake Space. It may need manual restart.\n")
+    
+    # Start monitoring
+    monitor_loop()

setup_cron.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Setup script for keep-alive cron job
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+CRON_SCRIPT="$SCRIPT_DIR/keep_alive_cron.sh"
+
+# Make the script executable
+chmod +x "$CRON_SCRIPT"
+
+# Add to crontab (runs every 5 minutes)
+(crontab -l 2>/dev/null; echo "*/5 * * * * $CRON_SCRIPT") | crontab -
+
+echo "Keep-alive cron job installed!"
+echo "It will ping your Space every 5 minutes."
+echo ""
+echo "To view current cron jobs: crontab -l"
+echo "To remove the cron job: crontab -e (then delete the line)"
+echo ""
+echo "Space URL: https://huggingface.co/spaces/MoraxCheng/Transeption_iGEM_BASISCHINA_2025"

zero_gpu_monitor.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+Zero GPU Monitor - Keeps the Space alive and monitors health
+"""
+import os
+import time
+import requests
+import sys
+from datetime import datetime
+
+# Configuration
+SPACE_URL = os.environ.get('SPACE_URL', 'http://localhost:7860')
+CHECK_INTERVAL = 180  # 3 minutes
+HEALTH_ENDPOINT = '/health'
+MAX_FAILURES = 3
+
+def check_space_health():
+    """Check if the Space is responding"""
+    try:
+        response = requests.get(SPACE_URL, timeout=10)
+        return response.status_code == 200
+    except Exception as e:
+        print(f"Health check failed: {e}")
+        return False
+
+def keep_space_warm():
+    """Send a dummy request to keep the Space warm"""
+    try:
+        # Send a simple request to the API
+        payload = {
+            "fn_index": 0,
+            "data": ["MSKGEELFTGVVPILVELDGDVNGHKFSVSGEGEGDATYGKLTLKFICTTGKLPVPWPTLVTTLSYGVQCFSRYPDHMKQHDFFKSAMPEGYVQERTIFFKDDGNYKTRAEVKFEGDTLVNRIELKGIDFKEDGNILGHKLEYNYNSHNVYIMADKQKNGIKVNFKIRHNIEDGSVQLADHYQQNTPIGDGPVLLPDNHYLSTQSALSKDPNEKRDHMVLLEFVTAAGITHGMDELYK", 1, 10, "Small", False, 10]
+        }
+        response = requests.post(f"{SPACE_URL}/api/predict", json=payload, timeout=30)
+        return response.status_code in [200, 202]
+    except Exception as e:
+        print(f"Keep-warm request failed: {e}")
+        return False
+
+def monitor_loop():
+    """Main monitoring loop"""
+    print(f"Starting Zero GPU Space monitor...")
+    print(f"Space URL: {SPACE_URL}")
+    print(f"Check interval: {CHECK_INTERVAL} seconds")
+    
+    consecutive_failures = 0
+    last_warm_up = datetime.now()
+    
+    while True:
+        try:
+            current_time = datetime.now()
+            print(f"\n[{current_time}] Performing health check...")
+            
+            # Check if Space is healthy
+            if check_space_health():
+                print("✓ Space is healthy")
+                consecutive_failures = 0
+                
+                # Send keep-warm request every check
+                time_since_warmup = (current_time - last_warm_up).total_seconds()
+                if time_since_warmup > CHECK_INTERVAL:
+                    print("Sending keep-warm request...")
+                    if keep_space_warm():
+                        print("✓ Keep-warm successful")
+                        last_warm_up = current_time
+                    else:
+                        print("✗ Keep-warm failed")
+            else:
+                consecutive_failures += 1
+                print(f"✗ Space is not responding (failure {consecutive_failures}/{MAX_FAILURES})")
+                
+                if consecutive_failures >= MAX_FAILURES:
+                    print("ERROR: Space appears to be down!")
+                    print("Please restart the Space from Hugging Face interface")
+                    # Could add notification logic here
+            
+            # Wait before next check
+            time.sleep(CHECK_INTERVAL)
+            
+        except KeyboardInterrupt:
+            print("\nMonitor stopped by user")
+            break
+        except Exception as e:
+            print(f"Monitor error: {e}")
+            time.sleep(60)  # Wait a minute before retrying
+
+if __name__ == "__main__":
+    # Get Space URL from environment or command line
+    if len(sys.argv) > 1:
+        SPACE_URL = sys.argv[1]
+    
+    monitor_loop()