mLLMCelltype

mLLMCelltype is an iterative Multi-LLM consensus framework designed for cell type annotation of single-cell RNA sequencing (scRNA-seq) data. It combines predictions from multiple Large Language Models (including OpenAI GPT-5.5, Anthropic Claude, Google Gemini, etc.) to improve annotation accuracy and provide transparent uncertainty quantification (using consensus ratios and Shannon entropy).

Key characteristics:

• No reference dataset required: Unlike traditional methods, it does not need a pre-trained reference.
• Consensus-based: Reduces errors and hallucinations through multi-round collaborative discussion between models.
• Integration: Works seamlessly with standard Scanpy (Python) and Seurat (R) workflows.
• Uncertainty Quantification: Identifies ambiguous cell populations that may require expert review.

The consensus model is responsible for high-level reasoning tasks that directly impact the reliability of cell type annotations. A high-quality model is required to:

• Evaluate Semantic Similarity: Correctly identify that different names (e.g., "T Lymphocyte" vs "T cell") refer to the same cell type.
• Understand Biological Context: Grasp biological hierarchies and context.
• Synthesize Discussions: Aggregate reasoning from multiple models to reach an accurate conclusion.
• Provide Confidence Metrics: Generate reliable indicators for downstream analysis.

Using weak models for these tasks can lead to misidentification of controversial clusters, incorrect consensus calculations, and poor resolution of disagreements between models.

Starting from version 1.3.0, you can provide custom endpoints for each API provider using the base_urls parameter in annotate_cell_types() and interactive_consensus_annotation(). This is particularly useful for:

• Users in China: Accessing international APIs via proxy servers.
• Enterprise users: Connecting to internal API gateways.
• Developers: Testing against local or mock API environments.

Qwen models support automatic endpoint detection. If you do not provide base_urls, the system will automatically attempt to connect to the international endpoint, then fallback to the domestic endpoint, and finally try the legacy international compatible endpoint. This provides a 'zero-configuration' experience that adapts to your network environment.

# Recommended usage: Let the system automatically select the best endpoint
result <- annotate_cell_types(
  input = marker_genes_list,
  tissue_name = "human PBMC",
  model = "qwen3.6-plus",
  api_key = "your-qwen-api-key"
  # No base_urls needed; system auto-selects
)

If you are using a local proxy server, you can configure it via environment variables or within your code.

# R: Set HTTP proxy via environment variables
Sys.setenv(http_proxy = "http://proxy-server:port")
Sys.setenv(https_proxy = "http://proxy-server:port")

# R: Set proxy using httr
library(httr)
set_config(use_proxy(url = "http://proxy-server:port"))

# Python: Set HTTP proxy via environment variables
import os
os.environ["HTTP_PROXY"] = "http://proxy-server:port"
os.environ["HTTPS_PROXY"] = "http://proxy-server:port"

# Python: Set proxy using requests
import requests
proxies = {
    "http": "http://proxy-server:port",
    "https": "http://proxy-server:port"
}
response = requests.get("https://api.example.com", proxies=proxies)

You can install the mllmcelltype package directly from PyPI using pip.

Requirements:

• Python >= 3.9
• Internet connection (for LLM API access)

pip install mllmcelltype

mLLMCelltype supports multiple LLM providers (OpenAI, Anthropic, Google, etc.). You must set your API keys as environment variables before running annotations.

Common environment variables include:

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• GEMINI_API_KEY

# Set API keys
Sys.setenv(ANTHROPIC_API_KEY = "your-anthropic-api-key")
Sys.setenv(OPENAI_API_KEY = "your-openai-api-key")
Sys.setenv(GEMINI_API_KEY = "your-gemini-api-key")

In R, mLLMCelltype can be used alongside Seurat to annotate clusters.

Workflow:

1. Load your Seurat object.
2. Identify marker genes using FindAllMarkers.
3. (Optional) Set a cache_dir to speed up subsequent processing.

Note: For detailed R tutorials, refer to the official documentation website.

library(mLLMCelltype)
library(Seurat)

# Load Seurat object
pbmc <- readRDS("your_seurat_object.rds")

# Find marker genes
pbmc_markers <- FindAllMarkers(pbmc,
                            only.pos = TRUE,
                            min.pct = 0.25,
                            logfc.threshold = 0.25)

# Set cache directory
cache_dir <- "./mllmcelltype_cache"
dir.create(cache_dir, showWarnings = FALSE, recursive = TRUE)