Open Kinetics Predictor is a production web interface for predicting enzyme kinetic parameters (kcat and KM) from protein sequence and substrate SMILES. It consolidates several state‑of‑the‑art machine learning / deep learning models behind a unified, asynchronous job API so you can submit sequences and retrieve structured predictions.

Live service: https://predictor.openkinetics.org/

Prediction Engines

Each model is loaded with its published weights/code from models/ and invoked through integration wrappers in api/prediction_engines/, so new engines can be added with minimal wiring.

Adding a New Prediction Method

See docs/project/contributing.rst for a step-by-step guide.

Features

• Batch submission of sequences and substrates.
• Long‑running inference handled asynchronously (Celery + Redis) with progress tracking.
• Sequence similarity distribution of input data vs mehtods' training data (Using mmseq2).
• Caching sequence embeddings.

Stack

Frontend

• React 18 + Vite (fast dev + ESM build)
• Bootstrap / React‑Bootstrap for layout & components
• Axios for API calls; Chart.js for result visualisation

Backend

• Django 5.1 (REST-style endpoints under api/)
• Celery workers for queued prediction tasks (api/tasks.py)
• Redis as Celery broker
• SQLite
• PyTorch, scikit-learn, RDKit, pandas for model computation & cheminformatics

Required Environment Variable

DJANGO_SECRET_KEY is required at runtime (no fallback hardcoded key).

Generate a strong key:

openssl rand -hex 50

Local/dev setup:

cp .env.example .env
# edit .env and set DJANGO_SECRET_KEY=...
docker compose up -d --build

Production setup:

# on the production host
cp .env.example .env.production
# edit .env.production and set DJANGO_SECRET_KEY=...
./deploy.sh prod

deploy.sh prod now reads .env.production automatically (falls back to .env if present). For non-interactive deploys (for example CI/systemd), provide an env file or inject DJANGO_SECRET_KEY in the service environment before running docker compose.

High-Level Flow

1. User submits a job (sequence + substrate(s) [+ products/mutant context if required]) via the frontend.
2. Backend validates input (api/services/validation_service.py).
3. A Celery task is enqueued; Redis broker stores the task message.
4. Worker loads the selected model wrapper (e.g. prediction_engines/kinform.py) and executes inference.
5. Results & intermediate status are persisted; cached for repeated identical queries.
6. Frontend polls job status endpoint to update progress and results.

API Access

OpenKineticsPredictor provides a REST API for programmatic access. Submit prediction jobs, poll their status, and download results — no web browser required.

Base URL: https://predictor.openkinetics.org/api/v1

Full interactive documentation is also available on the live site at /api-docs.

---

Endpoint Overview

---

Quick Start — Python

import requests
import time

API_KEY = "ak_your_key_here"
BASE    = "https://predictor.openkinetics.org/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# 1. Submit a job
with open("input.csv", "rb") as f:
    resp = requests.post(
        f"{BASE}/submit/",
        headers=HEADERS,
        files={"file": f},
        data={
            "predictionType":      "kcat",
            "kcatMethod":          "DLKcat",
            "handleLongSequences": "truncate",
            "useExperimental":     "true",
        },
    )
resp.raise_for_status()
job = resp.json()
print(f"Job ID: {job['jobId']}  |  Quota remaining: {job['quota']['remaining']:,}")

# 2. Poll until complete
while True:
    status = requests.get(f"{BASE}/status/{job['jobId']}/", headers=HEADERS).json()
    print(f"  {status['status']} ({status['elapsedSeconds']}s)")
    if status["status"] == "Completed":
        break
    if status["status"] == "Failed":
        raise RuntimeError(f"Job failed: {status.get('error')}")
    time.sleep(5)

# 3. Download results
result = requests.get(f"{BASE}/result/{job['jobId']}/", headers=HEADERS)
with open("output.csv", "wb") as f:
    f.write(result.content)
print("Saved to output.csv")

---

Quick Start — curl

API_KEY="ak_your_key_here"
BASE="https://predictor.openkinetics.org/api/v1"

# 1. Submit
JOB=$(curl -s -X POST "$BASE/submit/" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]" \
  -F "predictionType=kcat" \
  -F "kcatMethod=DLKcat" \
  -F "handleLongSequences=truncate")

JOB_ID=$(echo "$JOB" | python3 -c "import sys,json; print(json.load(sys.stdin)['jobId'])")
echo "Submitted: $JOB_ID"

# 2. Poll
while true; do
  STATE=$(curl -s "$BASE/status/$JOB_ID/" \
    -H "Authorization: Bearer $API_KEY" \
    | python3 -c "import sys,json; print(json.load(sys.stdin)['status'])")
  echo "  $STATE"
  [ "$STATE" = "Completed" ] && break
  [ "$STATE" = "Failed" ]    && { echo "Job failed"; exit 1; }
  sleep 5
done

# 3. Download
curl -s "$BASE/result/$JOB_ID/" \
  -H "Authorization: Bearer $API_KEY" \
  -o output.csv

---

JSON Body Submission (no CSV file needed)

For small datasets (≤ 10,000 rows) you can send data directly as JSON:

requests.post(
    f"{BASE}/submit/",
    headers={**HEADERS, "Content-Type": "application/json"},
    json={
        "predictionType":      "kcat",
        "kcatMethod":          "DLKcat",
        "handleLongSequences": "truncate",
        "useExperimental":     True,
        "data": [
            {"Protein Sequence": "MKTLLIFAG...", "Substrate": "CC(=O)O"},
            {"Protein Sequence": "MGSSHHHHH...", "Substrate": "C1CCCCC1"},
        ],
    },
)

---

Validating Input Before Submission

Use /validate/ to check substrate SMILES/InChI strings, protein sequences, and per-model length limits without consuming any quota or running predictions. This is equivalent to the validation step available in the web interface.

import requests

API_KEY = "ak_your_key_here"
BASE    = "https://predictor.openkinetics.org/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Basic validation (fast)
with open("input.csv", "rb") as f:
    resp = requests.post(
        f"{BASE}/validate/",
        headers=HEADERS,
        files={"file": f},
        data={"runSimilarity": "false"},
    )

result = resp.json()
print(f"Rows: {result['rowCount']}")
print(f"Invalid substrates: {len(result['invalidSubstrates'])}")
print(f"Invalid proteins:   {len(result['invalidProteins'])}")
print(f"Length violations:  {result['lengthViolations']}")

Set runSimilarity=true to also run MMseqs2 sequence similarity analysis against each method's training database. The request blocks synchronously until the analysis is complete (can take several minutes for large inputs):

with open("input.csv", "rb") as f:
    resp = requests.post(
        f"{BASE}/validate/",
        headers=HEADERS,
        files={"file": f},
        data={"runSimilarity": "true"},
        timeout=600,
    )

similarity = resp.json()["similarity"]
for method, data in similarity.items():
    print(f"{method}: avg max identity = {data['average_max_similarity']:.1f}%")

The similarity field in the response is a dict keyed by method name. Each entry contains histogram_max, histogram_mean (10-bin arrays, 0–100% identity), average_max_similarity, average_mean_similarity, count_max, and count_mean.

---

CSV Format

Supported input schemas are:

• Protein Sequence, Substrate for one molecular input.
• Protein Sequence, Substrates for a Multi-Substrate input: an ordered, semicolon-separated list.
• Protein Sequence, Substrates, Products for a full reaction. Products is required by TurNup and is preserved but ignored by substrate-pair methods.

For a Substrates list, single-substrate methods predict every protein/substrate pair. The reaction kcat is the maximum successful value; Km and direct kcat/Km outputs are JSON arrays in substrate order, with null for failed entries. The matching Extra Info <target> cell contains a JSON array with each substrate's one-based position, input value, prediction, source, error, and the selected kcat maximum.

CatPred kcat is the exception: it consumes the complete ordered substrate set as one native multi-substrate input and returns one scalar. CatPred Km still uses the per-substrate array behavior, including when kcat and Km are requested together. TurNup consumes both sides of a full reaction; every other method preserves but ignores Products.

Substrates and products must be SMILES or InChI strings. Separate ordered values in Substrates and Products with semicolons, for example CC(=O)O;C1CCCCC1. Supplied products are validated even when the selected method preserves but does not use them.

---

Rate Limits

• 20,000 input reaction rows/day per API key (default; custom limits available). Internal per-substrate predictions do not consume additional quota.
• Counter resets at midnight UTC.
• Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• HTTP 429 is returned when the quota is exceeded.

---

Error Format

All errors return JSON with a single error key:

{ "error": "A human-readable description of what went wrong." }

---

Attribution

Please cite the original publications when using predictions from a specific engine. Cite all underlying sources plus this platform.

Contact

For questions or collaboration: open an issue or reach out to the authors of the respective model.

Funding

This work was supported by EU Horizon Europe #101080997, Swiss SERI #23.00232, UKRI #10083717 & #10080153, FNR PRIDE21/16763386/CANBIO2, Novo Nordisk Foundation #NNF10CC1016517, Knut & Alice Wallenberg Foundation, EU Horizon 2020 #686070 & #814650, National Key R&D China 2025YFA0922700