Merge pull request #35 from theproteinbot/feat/multi-substrate-ki-separation

feat(web): multi-substrate input, Ki separation, and frontend improvements

Author: Vedasheersh

.env.vercel

@@ -0,0 +1,4 @@
+CATPRED_DEFAULT_BACKEND=modal
+CATPRED_MODAL_ENDPOINT=https://kaalabhairava2026--catpred-modal-api-predict.modal.run
+CATPRED_MODAL_TOKEN=
+CATPRED_MODAL_FALLBACK_TO_LOCAL=0

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install minimal runtime dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Compile Python sources
+        run: |
+          git ls-files '*.py' | xargs -r python -m py_compile
+
+      - name: Smoke test API entrypoints
+        run: |
+          python - <<'PY'
+          from catpred.web.app import create_app
+          from api.index import app as vercel_app
+
+          api_app = create_app()
+          assert api_app.title == "CatPred API"
+          assert vercel_app is not None
+          print("API smoke checks passed.")
+          PY

.github/workflows/deploy-modal.yml

@@ -0,0 +1,49 @@
+name: Deploy Modal
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/deploy-modal.yml"
+      - "modal_app.py"
+      - "predict.py"
+      - "scripts/create_pdbrecords.py"
+      - "catpred/**"
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    concurrency:
+      group: modal-production-deploy
+      cancel-in-progress: true
+    env:
+      MODAL_TOKEN_ID: ${{ secrets.MODAL_TOKEN_ID }}
+      MODAL_TOKEN_SECRET: ${{ secrets.MODAL_TOKEN_SECRET }}
+    steps:
+      - name: Skip when Modal credentials are not configured
+        if: ${{ env.MODAL_TOKEN_ID == '' || env.MODAL_TOKEN_SECRET == '' }}
+        run: echo "Skipping Modal deploy because MODAL_TOKEN_ID / MODAL_TOKEN_SECRET are not configured."
+
+      - name: Checkout
+        if: ${{ env.MODAL_TOKEN_ID != '' && env.MODAL_TOKEN_SECRET != '' }}
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        if: ${{ env.MODAL_TOKEN_ID != '' && env.MODAL_TOKEN_SECRET != '' }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install Modal CLI
+        if: ${{ env.MODAL_TOKEN_ID != '' && env.MODAL_TOKEN_SECRET != '' }}
+        run: |
+          python -m pip install --upgrade pip
+          pip install "modal>=0.73"
+
+      - name: Deploy modal_app.py
+        if: ${{ env.MODAL_TOKEN_ID != '' && env.MODAL_TOKEN_SECRET != '' }}
+        run: modal deploy modal_app.py

.vercelignore

@@ -0,0 +1,8 @@
+.venv/
+.e2e-assets/
+.e2e-tests/
+results/
+output/
+checkpoints/
+external/
+*.ipynb

README.md

@@ -24,6 +24,7 @@
    - [Installation](#installing)
    - [Prediction](#predict)
    - [Web API (Optional)](#web-api-optional)
+   - [Vercel Deployment (Optional)](#vercel-deployment-optional)
    - [Reproducibility](#reproduce)
 - [Acknowledgements](#acknw)
 - [License](#license)
@@ -126,6 +127,7 @@ By default, the API is hardened for service use:
 - `input_file` requests are disabled (use `input_rows` instead).
 - request-time overrides of `repo_root` / `python_executable` are disabled.
 - `results_dir` is constrained under `CATPRED_API_RESULTS_ROOT`.
+- for local backend (and modal requests with fallback enabled), `checkpoint_dir` must resolve under `CATPRED_API_CHECKPOINT_ROOT`.
 
 Minimal `POST /predict` example for local inference using `input_rows`:
 
@@ -134,7 +136,7 @@ curl -X POST http://127.0.0.1:8000/predict \
   -H "Content-Type: application/json" \
   -d '{
     "parameter": "kcat",
-    "checkpoint_dir": "../data/pretrained/reproduce_checkpoints/kcat",
+    "checkpoint_dir": "kcat",
     "input_rows": [
       {"SMILES": "CCO", "sequence": "ACDEFGHIK", "pdbpath": "seq_a"},
       {"SMILES": "CCN", "sequence": "LMNPQRSTV", "pdbpath": "seq_b"}
@@ -154,6 +156,7 @@ export CATPRED_MODAL_FALLBACK_TO_LOCAL=1
 ```
 
 Use `"backend": "modal"` in `/predict` requests to route through Modal. If fallback is enabled (env var above or request field `fallback_to_local`), failed modal requests can automatically reroute to local inference.
+For local backend requests, place local checkpoints under `CATPRED_API_CHECKPOINT_ROOT` and pass a path relative to that root (for example, `"checkpoint_dir": "kcat"`).
 
 Optional API environment variables:
 
@@ -183,6 +186,93 @@ export CATPRED_TRUSTED_DESERIALIZATION_ROOTS="/srv/catpred:/srv/catpred-data"
 export CATPRED_ALLOW_UNSAFE_DESERIALIZATION=1
 ```
 
+### ▲ Vercel Deployment (Optional) <a name="vercel-deployment-optional"></a>
+
+This repository includes a Vercel-ready ASGI entrypoint at `api/index.py` and a `vercel.json` route config.
+
+1. Push this repository to GitHub.
+2. In Vercel, create a new project from that repo.
+3. Set Environment Variables in Vercel Project Settings:
+
+```bash
+# Use remote inference backend in serverless deployments
+CATPRED_DEFAULT_BACKEND=modal
+CATPRED_MODAL_ENDPOINT=https://<your-modal-endpoint>
+CATPRED_MODAL_TOKEN=<optional-token>
+CATPRED_MODAL_FALLBACK_TO_LOCAL=0
+```
+
+Notes:
+- Serverless filesystems are ephemeral/read-only except `/tmp`; this app auto-uses `/tmp/catpred` on Vercel.
+- Local checkpoint-based inference is not recommended on Vercel serverless due runtime/dependency limits.
+- If `CATPRED_MODAL_ENDPOINT` is not configured, the UI still loads but prediction requests will be limited by backend readiness.
+
+#### Deploy a Modal endpoint for Vercel
+
+This repo includes `modal_app.py`, a Modal `POST` endpoint compatible with CatPred's `/predict` modal backend contract.
+
+1. Install and authenticate Modal CLI:
+
+```bash
+pip install modal
+modal setup
+```
+
+2. Create/upload checkpoints into a Modal Volume (one-time):
+
+```bash
+modal volume create catpred-checkpoints
+modal volume put catpred-checkpoints ./checkpoints/kcat kcat
+modal volume put catpred-checkpoints ./checkpoints/km km
+modal volume put catpred-checkpoints ./checkpoints/ki ki
+```
+
+3. (Recommended) create a secret token for endpoint auth:
+
+```bash
+modal secret create catpred-modal-auth CATPRED_MODAL_AUTH_TOKEN="<your-token>"
+```
+
+4. Deploy:
+
+```bash
+modal deploy modal_app.py
+```
+
+After deploy, copy the printed endpoint URL (for function `predict`) and set Vercel variables:
+
+```bash
+CATPRED_DEFAULT_BACKEND=modal
+CATPRED_MODAL_ENDPOINT=https://<your-modal-endpoint>
+CATPRED_MODAL_TOKEN=<your-token>
+CATPRED_MODAL_FALLBACK_TO_LOCAL=0
+```
+
+#### CI/CD (GitHub Actions + Vercel + Modal)
+
+This repo includes two GitHub Actions workflows:
+
+- `.github/workflows/ci.yml`
+  - Runs on every PR and push to `main`.
+  - Installs minimal API dependencies, compiles all Python files, and smoke-tests API entrypoints.
+- `.github/workflows/deploy-modal.yml`
+  - Runs on push to `main` when backend files change (and manually via `workflow_dispatch`).
+  - Deploys `modal_app.py` automatically.
+
+To enable automatic Modal deploys from GitHub Actions, add repository secrets:
+
+- `MODAL_TOKEN_ID`
+- `MODAL_TOKEN_SECRET`
+
+Create these from Modal:
+
+1. Go to [https://modal.com/settings/tokens](https://modal.com/settings/tokens).
+2. Create a token with deploy permissions for your workspace.
+3. Copy token ID and secret into GitHub repo settings:
+   `Settings -> Secrets and variables -> Actions -> New repository secret`.
+
+Vercel deployment remains automatic from the connected GitHub branch (`main`).
+
 ### 🧪 Fine-Tuning On Custom Data
 
 You can fine-tune CatPred on your own regression targets using `train.py`.

api/index.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from pathlib import Path
+import os
+import sys
+
+
+ROOT = Path(__file__).resolve().parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+if os.environ.get("VERCEL"):
+    os.environ.setdefault("CATPRED_API_RUNTIME_ROOT", "/tmp/catpred")
+    os.environ.setdefault("CATPRED_MODAL_FALLBACK_TO_LOCAL", "0")
+    if os.environ.get("CATPRED_MODAL_ENDPOINT"):
+        os.environ.setdefault("CATPRED_DEFAULT_BACKEND", "modal")
+
+from catpred.web.app import app
+
+
+__all__ = ["app"]

catpred/data/utils.py

@@ -1,10 +1,12 @@
+from __future__ import annotations
+
 from collections import OrderedDict, defaultdict
 import sys
 import csv
 import ctypes
 from logging import Logger
 from random import Random
-from typing import List, Set, Tuple, Union
+from typing import List, Set, Tuple, Union, TYPE_CHECKING
 import os
 import json
 import torch
@@ -18,11 +20,13 @@
 from .esm_utils import get_protein_embedder, get_coords
 from .data import MoleculeDatapoint, MoleculeDataset, make_mols
 from .scaffold import log_scaffold_stats, scaffold_split
-from catpred.args import PredictArgs, TrainArgs
 from catpred.features import load_features, load_valid_atom_or_bond_features, is_mol
 from catpred.rdkit import make_mol
 from catpred.security import load_index_artifact, load_pickle_artifact
 
+if TYPE_CHECKING:
+    from catpred.args import PredictArgs, TrainArgs
+
 # Increase maximum size of field in the csv processing for the current architecture
 csv.field_size_limit(int(ctypes.c_ulong(-1).value // 2))
 

catpred/features/features_generators.py

@@ -85,7 +85,6 @@ def morgan_binary_features_generator(mol: Molecule,
 
 #     return features
 
-import ipdb
 @register_features_generator('morgan_diff_fp')
 def morgan_difference_features_generator(rxn: Reaction) -> np.ndarray:
     """

catpred/models/model.py

@@ -127,8 +127,11 @@ def create_protein_model(self, args: TrainArgs) -> None:
             x = list(self.pretrained_egnn_feats_dict.values())
             self.pretrained_egnn_feats_avg = torch.stack(x).mean(dim=0)
 
-        # For rotary positional embeddings
-        self.rotary_embedder = RotaryEmbedding(dim=args.seq_embed_dim//4)
+        # Rotary embeddings require an even feature dimension.
+        rotary_dim = max(2, args.seq_embed_dim // 4)
+        if rotary_dim % 2 != 0:
+            rotary_dim -= 1
+        self.rotary_embedder = RotaryEmbedding(dim=rotary_dim)
 
         # For self-attention
         self.multihead_attn = nn.MultiheadAttention(args.seq_embed_dim,