Public case study

HyCell

AI virtual-cell infrastructure for biological representation and simulation.

Year: 2026
Status: status.prototype
Role: System design, architecture and engineering
Category: Computational Biology · AI Virtual Cell · Representation Learning
Stack: Python 3.10+
PyTorch
NumPy
Streamlit
pytest
Public code: Public repository
Reality: Research prototype Runnable v0.1 prototype with real acceptance scripts.

Status v0.1 engineering MVP. Runnable prototype, not a validated biological discovery system.

What it is

HyCell is an AI prototype for cell modelling and life-science research. It studies how cell state can be represented by a model, and how that state is expected to move under an intervention.

The current artefact, HyCell-JEPA, is a v0.1 engineering MVP: a cell world-model prototype that runs locally. It is not a complete virtual cell, not a transcriptome-scale generative model, and not validated in a wet lab.

Why it matters

The easiest failure mode in this direction is to report an engineering pipeline as a biological discovery.

HyCell is organised in the opposite order: data contracts, validation and stated limits first; the model second. The model is deliberately small, and what makes it auditable sits around it.

Current public status

v0.1 engineering MVP, research prototype. It runs, and that says the pipeline works — not that any biology has been established.

There is no wet-lab validation, no clinical conclusion and no benchmark against a foundation model.

What is publicly available

The HyCell-JEPA repository — Python and PyTorch, runnable locally.
A real-matrix engineering check: the inspect → prepare → validate → summarise path over a GSE130973 subset (capped at 5,000 cells × 2,000 genes by default), with its own report. The subset’s state_label and age_label are explicitly marked unknown in the pipeline.
Acceptance scripts: scripts/verify_release.sh and the per-goal check scripts.

Notes

Public matrices validate the pipeline, not the biology. No biological or clinical conclusion is published here.

Implementation status

Runnable v0.1 prototype with real acceptance scripts.

What exists today, and how you would check it. Nothing below is a rendered mockup of something that does not exist.

Public code: Public repository

States describe what a visitor can verify, not how finished something feels.
Component	State	Note
Schema and data contracts	Built	A typed schema layer plus a real-dataset validation path covering .csv, .npz and optional .h5ad inputs.
Core interfaces — encoders and transition head	Built	Bio-state, action, context and adapter encoders feed a JEPA-style core. In v0.1 the transition head is a compact NumPy ridge regression — small and inspectable by design.
EvidenceGraph	Built	Links toy actions, readouts, assumptions and limits in one structure so caveats travel with the claim.
Biological verifier	Built	Structured pass / warn / fail output rather than a single score. On the accepted toy benchmark all eight transitions returned warn — the guardrail reports uncertainty instead of hiding it.
Target-state planner	Built	Top-K action-sequence search over toy compact states. The README is explicit that planner output is a demonstration, not a therapy recommendation.
Real-data ingestion — GSE130973	Built	Matrix Market files are inspected, prepared, validated and summarised; the smoke artifact is capped at 5,000 cells × 2,000 genes.
Real-matrix smoke training	Built	A lightweight encoder-style training path exists for the prepared real matrix. Labels are explicitly unknown — the smoke run does not infer them.
Acceptance scripts and reproducibility contract	Built	Seven goal verifiers plus a release verifier, invocable through make targets. This is the strongest artifact in the repository.
Test suite	Built	Eighteen test modules including real-data loader, schema, verifier, evidence-graph, benchmark and CLI-contract tests.
Streamlit demo	Built	A portfolio UI exposing toy states, predicted transitions, verifier messages, planner output and real-data status.
Cloud GPU scaffold	Prototype	An RTX 4090 run script, configuration and result packager exist. It does not download large datasets automatically.
Biological validation	Planned	None. The README lists this first among limitations: not wet-lab validated, no clinical claim, no benchmark against a published virtual-cell model.
Metadata annotation and HDF subset (v0.2)	Planned	The current real smoke data is unfiltered human skin single-cell data with unknown age and state labels.
Real perturbation benchmark (v0.4)	Planned	Roadmap item, not started in v0.1.

How to read these states 3

Built Implemented in code. Says nothing about how good it is.
Prototype Runs end to end on toy or sample data. Not a production system.
Planned Identified for future work. Nothing to inspect yet.

Command / Output

Reproducibility contract

Open source artifact

$ make verify
python -m pytest
bash scripts/verify_goal1.sh
bash scripts/verify_goal2.sh
bash scripts/verify_goal3.sh
bash scripts/verify_goal4.sh
bash scripts/verify_goal4_real_smoke.sh
bash scripts/verify_goal5.sh
bash scripts/verify_goal6.sh
bash scripts/verify_goal7.sh

$ make verify-release
bash scripts/verify_release.sh

Acceptance is scripted. `make verify` runs pytest plus all seven goal verifiers, so a reviewer can check claims without trusting prose.

Source HyCell-JEPA Makefile and README.md

Command / Output

Benchmark smoke output

Open source artifact

Toy score transitions: 8
Training transitions: 6
Held-out eval transitions: 2
All-transition MSE: 0.014585165
Verifier status counts: {"warn": 8}
Planner sequence: regeneration -> control

These numbers prove runnable engineering plumbing only. The README states plainly that they do not validate biology.

Source HyCell-JEPA README.md — quoted verbatim.

Command / Output

Planner output

Open source artifact

Top-K toy action sequences:
1. aging_stress -> regeneration | distance=0.458229
2. partial_reprogramming -> regeneration | distance=0.497030
3. control -> regeneration | distance=0.620774

Top-K search over toy compact states, with distances. Demonstration output, not a protocol.

Source HyCell-JEPA README.md — toy smoke path.

Repository

Module inventory

Open source artifact

src/hycell/
├── schema.py                # typed contracts
├── config.py                # YAML-driven configuration
├── toy_data.py              # deterministic generator
├── data_loaders.py          # csv / npz / h5ad
├── real_datasets.py         # GSE130973 ingestion
├── datasets.py
├── gene_sets.py             # configurable scoring
├── encoders.py              # bio-state, action, context
├── hdf_adapter.py           # cell-system adapter h_t
├── jepa.py                  # transition core
├── verifier.py              # pass / warn / fail
├── planner.py               # top-K target-state search
├── evidence_graph.py        # claims ↔ assumptions ↔ limits
├── real_training.py         # real-matrix smoke training
├── training.py
├── benchmark.py             # reports
└── demo/

tests/  18 modules — data loaders, schema, real-data smoke,
        real-training smoke, CLI contracts, verifier, evidence graph,
        benchmark, encoders, gene sets, planner, packaging

docs/    model_card, design_summary, limitations, ACCEPTANCE,
        data_card, benchmark_report, gse130973_integration,
        gse130973_smoke_report, roadmap, release_v0.1, progress_log

Source GitHub API — huangdi97/HyCell-JEPA src listing.

Quoted

Limitations, quoted from the repository

Open source artifact

Not clinical advice.
Not wet-lab validated.
Not a complete virtual cell.
Not Lingshu-Cell-scale transcriptome diffusion.
Toy data is engineering validation only.
Planner outputs are demonstrations, not therapy recommendations.
GSE130973 smoke workflows are real-matrix engineering validation only.
Smoke data is unfiltered human skin single-cell data with unknown age and state labels.

Source HyCell-JEPA README.md — "Limitations First".