Release HistAgent GigaPath-LoRA checkpoint

README.md

@@ -0,0 +1,62 @@
+---
+base_model: prov-gigapath/prov-gigapath
+library_name: peft
+pipeline_tag: image-to-text
+tags:
+  - computational-pathology
+  - spatial-transcriptomics
+  - histology
+  - gene-ranking
+  - lora
+---
+
+# HistAgent
+
+HistAgent is a visual-omics foundation model that generates ranked molecular readouts from routine H&E images. It combines a spot-centred image with surrounding tissue context and autoregressively predicts the top 50 genes for each location.
+
+## Model details
+
+| Property | Value |
+|---|---|
+| Base encoder | `prov-gigapath/prov-gigapath` tile encoder |
+| Vision adaptation | LoRA, rank 16, alpha 32 |
+| Image inputs | Paired local and context H&E views |
+| Decoder | Six-layer Transformer decoder, hidden size 512 |
+| Output | Ranked sequence of up to 50 genes |
+| Vocabulary | 44,538 genes plus four special tokens |
+| Species conditioning | Human, mouse or unknown |
+| Organ conditioning | 32-entry training vocabulary |
+
+The repository contains only the trained LoRA parameters and HistAgent-specific modules. The frozen GigaPath base weights are loaded separately from the official gated repository.
+
+## Training data
+
+The model was trained on 2.23 million paired H&E–ST locations from 936 human and mouse 10x Visium slides spanning 32 tissue categories. The release checkpoint corresponds to epoch 30 of the GigaPath training run.
+
+## Use
+
+Install the accompanying code:
+
+```bash
+git clone https://github.com/zipging/HistAgent.git
+cd HistAgent
+pip install -e .
+```
+
+Request access to [Prov-GigaPath](https://huggingface.co/prov-gigapath/prov-gigapath), set `HF_TOKEN`, and load the model:
+
+```python
+from histagent import load_pretrained
+
+model, tokenizer, config = load_pretrained("wli13/HistAgent", device="cuda")
+```
+
+See the [GitHub repository](https://github.com/zipging/HistAgent) for image preprocessing and ranked-gene inference examples.
+
+## Intended use and limitations
+
+This model is intended for research on computational pathology and spatial molecular biology. It predicts rank-based molecular readouts rather than transcript counts. Performance can vary with tissue type, staining, scanner characteristics, image resolution and preprocessing. Predictions require independent biological validation and are not intended for clinical diagnosis or treatment decisions.
+
+## Citation
+
+The HistAgent manuscript and citation will be added when publicly available.

checkpoint_manifest.json

@@ -0,0 +1,11 @@
+{
+  "source_checkpoint": "lora_v3_ep30.pth",
+  "source_sha256": "74e27bd55335d530536abfa93bf23c974100a7cbbd420f8f2002ee4d81e00996",
+  "release_file": "model.safetensors",
+  "release_sha256": "a91ef2fd44377051aa9193a69058e378ecd01510242477968a27a8935f46552b",
+  "source_keys": 1036,
+  "release_keys": 470,
+  "verified_frozen_gigapath_keys": 566,
+  "release_bytes": 378413816,
+  "base_model_id": "prov-gigapath/prov-gigapath"
+}

config.json

@@ -0,0 +1,16 @@
+{
+  "architecture": "HistAgentVisualOmics",
+  "base_model_id": "prov-gigapath/prov-gigapath",
+  "vocab_size": 44542,
+  "num_organs": 32,
+  "num_species": 3,
+  "d_model": 512,
+  "n_head": 8,
+  "n_layers": 6,
+  "max_len": 52,
+  "num_latents": 16,
+  "vision_embed_dim": 1536,
+  "lora_rank": 16,
+  "lora_alpha": 32,
+  "max_gene_rank": 50
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a91ef2fd44377051aa9193a69058e378ecd01510242477968a27a8935f46552b
+size 378413816

organ_vocab.json

@@ -0,0 +1,34 @@
+{
+  "Unknown": 0,
+  "b16f10 syngeneic tumor": 1,
+  "bone": 2,
+  "brain": 3,
+  "breast": 4,
+  "cervix": 5,
+  "colon": 6,
+  "digit": 7,
+  "embryo": 8,
+  "endometrium": 9,
+  "glioblastoma": 10,
+  "glioma": 11,
+  "heart": 12,
+  "joint": 13,
+  "kidney": 14,
+  "lacrimal gland": 15,
+  "leiomyosarcoma": 16,
+  "liver": 17,
+  "lung": 18,
+  "lymph node": 19,
+  "melanoma": 20,
+  "mouth": 21,
+  "muscle": 22,
+  "ovary": 23,
+  "pancreas": 24,
+  "prostate": 25,
+  "skin": 26,
+  "spleen": 27,
+  "stomach": 28,
+  "tendon": 29,
+  "thymus": 30,
+  "undifferentiated pleomorphic sarcoma": 31
+}

species_vocab.json

@@ -0,0 +1,5 @@
+{
+  "unknown": 0,
+  "human": 1,
+  "mouse": 2
+}