# Copyright 2026 InstaDeep Ltd and CentraleSupélec # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """High-level API: raw counts in, cell types / cell states out.""" from dataclasses import dataclass from typing import Optional, Sequence, Union import torch from .postprocessing import extract_predicted_cell_type, parse_cell_state_prediction from .preprocessing import GeneMapper, ScFoundationPreprocessor from .prompts import ( TASK_CELL_STATE, TASK_CELL_TYPING, build_in_context_prompt, build_prompt, ) # Mixed precision of the predictor: None (fp32), "auto" or a torch dtype. AutocastDtype = Union[str, torch.dtype, None] @dataclass class CellStatePrediction: programs: list[tuple[str, float]] # (meta-program, score), strongest first hallmark: Optional[str] text: str class CellScribePredictor: """ >>> predictor = model.predictor(tokenizer) >>> predictor.predict_cell_type(counts, gene_names) """ def __init__( self, model: torch.nn.Module, # CellScribe (not imported: no import cycle) tokenizer, gene_list: Optional[Sequence[str]] = None, cell_types: Optional[Sequence[str]] = None, ) -> None: """``gene_list`` / ``cell_types``: default to the model's. ``cell_types`` is the label vocabulary used to read cell-type answers (the training vocabulary, as in the paper's evaluation); without it, the free text after "The cell type is" is returned.""" gene_list = gene_list or model.gene_list if gene_list is None: raise ValueError("no gene list: load the model with from_pretrained") cell_types = cell_types or model.cell_types self.model = model.eval() self.cell_types = list(cell_types) if cell_types else None self.tokenizer = tokenizer self.tokenizer.padding_side = "left" self.mapper = GeneMapper(gene_list) cfg = model.config.scfoundation self.preprocessor = ScFoundationPreprocessor( num_genes=len(gene_list) + 2, pad_token_id=cfg["pad_token_id"], target_res_str=cfg["tgthighres"], ).to(self.device) @property def device(self) -> torch.device: return next(self.model.parameters()).device def _autocast(self, autocast_dtype: AutocastDtype) -> torch.autocast: """Mixed-precision context. ``"auto"``: bfloat16 on GPU (the precision of the paper's evaluation, and half the encoder memory), fp32 on CPU.""" if autocast_dtype == "auto": autocast_dtype = torch.bfloat16 if self.device.type == "cuda" else None if isinstance(autocast_dtype, str): raise ValueError( "autocast_dtype must be 'auto', None or a dtype, " f"got {autocast_dtype!r}" ) if autocast_dtype is not None and self.device.type != "cuda": # On CPU, torch's TransformerEncoderLayer keeps its fused fast path # under autocast, which mixes reduced-precision inputs with fp32 weights. raise ValueError("mixed precision is only supported on GPU; use None") return torch.autocast( self.device.type, dtype=autocast_dtype or torch.float32, enabled=autocast_dtype is not None, ) @torch.no_grad() def generate_text( self, counts, gene_names: Sequence[str], task: str = TASK_CELL_TYPING, batch_size: int = 32, autocast_dtype: AutocastDtype = None, ) -> list[str]: """Generated answer for each cell. Args: counts: ``(n_cells, n_genes)`` raw UMI counts (numpy or scipy sparse). gene_names: HGNC symbols of the columns. autocast_dtype: mixed precision. ``None`` (default): fp32; ``"auto"``: bfloat16 on GPU, as in the paper's evaluation, and fp32 on CPU; or a dtype such as ``torch.bfloat16``. The scFoundation pooling runs over the padded batch, so a cell's embedding depends slightly on its batch-mates; results are reproducible for a fixed ``batch_size`` and cell order. """ if len(gene_names) != counts.shape[1]: raise ValueError(f"{len(gene_names)} names for {counts.shape[1]} columns") # Genes are matched once; cells are densified one batch at a time, so a # large sparse or backed matrix never has to fit in memory as a whole. indices = self.mapper.column_indices(gene_names) prompt = self.tokenizer( [build_prompt(self.tokenizer, task)], return_tensors="pt" ) texts: list[str] = [] for start in range(0, counts.shape[0], batch_size): dense = self.mapper.map_columns(counts[start : start + batch_size], indices) cells = self.preprocessor(torch.from_numpy(dense).to(self.device)) n = cells["x"].shape[0] with self._autocast(autocast_dtype): generated = self.model.generate( input_ids=prompt.input_ids.expand(n, -1).to(self.device), attention_mask=prompt.attention_mask.expand(n, -1).to(self.device), scrnaseq_preprocessed_input=cells, ) texts += self.tokenizer.batch_decode(generated, skip_special_tokens=True) return texts def predict_cell_type( self, counts, gene_names: Sequence[str], **kwargs ) -> list[str]: texts = self.generate_text(counts, gene_names, task=TASK_CELL_TYPING, **kwargs) return [extract_predicted_cell_type(t, self.cell_types) for t in texts] def predict_cell_state( self, counts, gene_names: Sequence[str], **kwargs ) -> list[CellStatePrediction]: texts = self.generate_text(counts, gene_names, task=TASK_CELL_STATE, **kwargs) predictions = [] for text in texts: programs, hallmark = parse_cell_state_prediction(text) predictions.append(CellStatePrediction(programs, hallmark, text)) return predictions @torch.no_grad() def embed_cells( self, counts, gene_names: Sequence[str], batch_size: int = 32, autocast_dtype: AutocastDtype = None, ) -> torch.Tensor: """Conditioning vector of each cell, ``[n_cells, hidden_size]``.""" if len(gene_names) != counts.shape[1]: raise ValueError(f"{len(gene_names)} names for {counts.shape[1]} columns") indices = self.mapper.column_indices(gene_names) vectors = [] for start in range(0, counts.shape[0], batch_size): dense = self.mapper.map_columns(counts[start : start + batch_size], indices) cells = self.preprocessor(torch.from_numpy(dense).to(self.device)) with self._autocast(autocast_dtype): vectors.append(self.model.embed_cells(cells).float()) return torch.cat(vectors) @torch.no_grad() def generate_text_in_context( self, counts, gene_names: Sequence[str], example_counts, example_gene_names: Sequence[str], example_labels: Sequence[str], batch_size: int = 32, autocast_dtype: AutocastDtype = None, ) -> list[str]: """Generated cell-typing answer for each cell, given labelled example cells. In-context learning: the prompt lists the example cells with their cell types ("Example cell k: The cell type is