TiterBench

Local web app for ensemble dry-lab predictions (protein expression, strain titer, bioproduction curves), aligned with SPECS.md.

Quick start

chmod +x run.sh
./run.sh

Open http://127.0.0.1:8000

Hands-on walkthrough: TUTORIAL.md — astaxanthin bioproduction with example uploads in data/tutorial/astaxanthin/.

Modes

• Demo — Bundled pilot data only; browse and predict immediately.
• My project — Create a workspace, upload CSV/JSON (templates linked in Workflow), run steps: upload → train → fine-tune → validate → predict. Send X-Workspace-Id header on predict calls (UI does this automatically).

Demo

Bundled pilot data (data/demo/):

• 10 protein variants (GFP, mCherry, scFv, lipase, insulin) with measured expression (mg/L)
• 10 strain designs (E. coli / yeast) with titers (g/L)
• 8 bioproduction time-series (OD600, glucose, product titer) — proteins, astaxanthin, biosurfactants, etc.

Product catalog: GET /api/products — astaxanthin, biosurfactant, organic acid, bioethanol, antibiotic, SCP, PHA, recombinant protein. Predict with product_type on /api/predict/fermentation.

Use Overview → Run validation, or load preset examples on each prediction tab.

API

Endpoint	Method
/api/predict/protein	POST
/api/predict/strain	POST
/api/predict/fermentation	POST
/api/demo/proteins	GET
/api/demo/validation	GET

Models are sklearn surrogates by default. Use public data + fine-tuning for real ESM-2 / DNA / LSTM heads.

Public data & fine-tuning

# 1) Download FLIP GB1, Thermostability, Anderson promoters, fermentation curves
python scripts/download_public_data.py

# 2) Install fine-tune deps (PyTorch + Transformers)
pip install -r requirements-finetune.txt

# 3) Fine-tune all heads (use --quick for a fast local demo)
python scripts/finetune_all.py --quick

# Or individually:
python -m backend.finetune.protein_esm --quick
python -m backend.finetune.strain_dna --cnn --quick
python -m backend.finetune.fermentation_ts --quick

Source	Dataset	Task
HuggingFace AI4Protein/FLIP_GB1_three-vs-rest	~15k sequences	Protein fitness (GB1)
HuggingFace AI4Protein/Thermostability_ESMFold	~5k proteins	Tm (°C)
iGEM Anderson promoter collection	19 promoters	Promoter strength
Zenodo / literature	Fed-batch curves	Fermentation titer

Fine-tuned weights are saved under models/finetuned/. The API uses them automatically when present.

Hugging Face token

For gated models and higher download rate limits, set a token from huggingface.co/settings/tokens:

• UI: click HF in the header → paste token → Validate / Save (stored in browser; optional server copy per workspace).
• Environment: export HF_TOKEN=hf_… or copy .env.example to .env.
• API header: X-HF-Token: hf_… on download / fine-tune requests.

TiterBench ships without HF or LLM keys. Each user sets their own in the UI (HF / LLM) or in a local .env (copy from .env.example). Never commit tokens (data/.hf_token, data/.llm_token, data/workspaces/ are gitignored).

Bio-expert (LLM)

Default provider is xAI Grok (grok-4.20-reasoning). Open LLM in the header to switch provider/model (OpenAI or any OpenAI-compatible endpoint).

Set XAI_API_KEY in .env or paste the key in the UI. Overview → Ask Bio-expert sends validation metrics and optional last prediction to the LLM for wet-lab next-step suggestions.

Endpoint	Method
/api/llm/providers	GET
/api/llm/analyze	POST
/api/llm/status	GET

License

TiterBench is licensed under the Business Source License 1.1 (BSL). Source is public; non-commercial and R&D use is permitted. Commercial production use requires a separate license. On 2030-06-08 the project converts to Apache 2.0.