OmicClaw: executable and reproducible natural-language multi-omics analysis over the unified OmicVerse ecosystem.

OmicClaw is an executable natural-language framework built on the unified OmicVerse ecosystem and J.A.R.V.I.S. runtime that transforms fragmented multi-omics analysis into reproducible, traceable workflows by converting user requests into validated actions over live data objects.

The Gist

Imagine you are a detective trying to solve a complex biological mystery. You have a massive pile of clues: DNA sequences, cell counts, protein levels, and spatial maps of where cells live in the body. This is what scientists call "multi-omics" data.

In the past, solving this mystery was like trying to build a house using tools from five different hardware stores that don't fit together. One tool for cutting wood, another for hammering nails, a third for painting, but none of them talk to each other. You had to manually carry the wood from the saw to the hammer, write your own instructions to make them work, and if you made a mistake, you had to start over. It was messy, slow, and hard to prove exactly how you built the house.

OmicClaw is the new, magical "Super-Detective Assistant" that fixes all of this. Here is how it works, broken down into simple parts:

1. The Unified Toolbox: OmicVerse

First, the researchers built a giant, organized toolbox called OmicVerse.

• The Metaphor: Imagine a massive, perfectly organized library where every single tool (method) for analyzing biological data is neatly labeled and speaks the same language.
• What it does: Instead of jumping between 50 different software programs that all speak different languages, OmicVerse puts everything (from cleaning up raw data to finding cell types) into one system. It uses a standard "language" (called AnnData) so that every tool understands the data instantly.

2. The Smart Manager: J.A.R.V.I.S.

This is the brain of the operation. In the movie Iron Man, J.A.R.V.I.S. is the AI that manages the suit. Here, J.A.R.V.I.S. is a smart manager that sits between you (the user) and the toolbox.

• The Problem it Solves: Usually, if you ask a computer AI to "analyze this data," the AI might just guess how to do it. It might invent a tool that doesn't exist or try to hammer a nail with a screwdriver (a "hallucination").
• The Solution: J.A.R.V.I.S. acts as a strict but helpful gatekeeper. It has a Registry—a master list of every tool that actually exists and works.
  • If you say, "Find the cell types," J.A.R.V.I.S. checks the list, sees which tools are available, checks if you have the right data ready, and then executes the steps perfectly.
  • If a step is missing (e.g., "You need to clean the data before you can find cell types"), J.A.R.V.I.S. stops and says, "Hold on, we need to do Step A first," rather than crashing.

3. The Conversation: Natural Language

The coolest part is how you talk to it. You don't need to be a coding wizard.

• The Metaphor: Think of it like ordering a complex meal at a restaurant. You don't need to know how to chop onions or grill steak. You just say, "I want a spicy chicken dish with rice."
• How it works: You type a sentence like, "Take this dataset of immune cells, clean it up, group them by type, and show me a map."
• The Magic: OmicClaw translates your English sentence into a precise, step-by-step recipe. It runs the code, checks for errors, and if something goes wrong, it fixes it automatically. It doesn't just guess; it follows a verified path.

4. The Safety Net: Reproducibility

In science, if you can't show exactly how you got your result, nobody believes you.

• The Metaphor: Imagine a cooking show where the chef makes a dish but doesn't write down the recipe. You can't recreate it.
• The Fix: OmicClaw keeps a perfect diary of everything it does. It records every tool used, every parameter changed, and every step taken. If you ask it to do the same thing tomorrow, it will do it exactly the same way. It turns "black box" magic into a transparent, reproducible process.

5. The Web Interface: For Everyone

Finally, they built a website (OmicVerse Web) so you don't even need to install anything on your computer.

• The Metaphor: It's like a high-tech cockpit. You can see your data on a giant screen, click buttons to run analyses, or chat with the AI assistant right in the browser. It can handle millions of cells (which is a lot of data!) without slowing down.

Summary

OmicClaw is like giving a biologist a super-intelligent, self-correcting project manager who speaks your language.

• It organizes the chaotic mess of biological software into one neat library.
• It prevents the AI from making up fake tools.
• It lets you ask for complex analyses in plain English.
• It keeps a perfect record of everything so your science is trustworthy.

It turns the difficult, fragmented world of biological data analysis into a smooth, conversational experience, allowing scientists to focus on the answers rather than the tools.

Technical Summary

1. Problem Statement

The rapid advancement in bulk, single-cell, and spatial omics has expanded biological discovery but created a significant software bottleneck. Current analysis workflows suffer from:

• Fragmentation: Core tasks (preprocessing, clustering, trajectory inference, etc.) are scattered across independent packages (e.g., Scanpy, Seurat, various R packages) with incompatible interfaces and object conventions.
• Heterogeneity: Users must manually bridge tools, write wrappers for specific APIs, and reorganize intermediate outputs, increasing technical burden and reducing reproducibility.
• AI Limitations: While Large Language Models (LLMs) show promise in bioinformatics, they often fail in practice due to code hallucination (inventing invalid function calls), method selection errors (recommending tools without understanding constraints), and the inability to handle long-horizon, multi-step workflows without a grounded execution environment.

2. Methodology

The authors propose OmicClaw, a framework that integrates a unified omics ecosystem with a bounded, state-aware execution runtime to enable executable natural-language analysis. The system consists of three core layers:

A. The Analytical Substrate: OmicVerse

OmicVerse is a unified, AnnData-centered ecosystem that harmonizes over 100 methods across multiple omics modalities (bulk, single-cell, spatial, multi-omics).

• Unified Interface: It organizes diverse algorithms into task-oriented modules (ov.alignment, ov.preprocess, ov.single, ov.space, ov.bulk, ov.fm) sharing a common API.
• Interoperability: It supports optimized backends (CUDA, Apple Metal/MPS) and interoperates with ML frameworks (PyTorch, PyG, MLX).
• Registry Grounding: Functions are exposed via a @register_function decorator, creating a centralized tool registry with structured metadata (arguments, prerequisites, outputs).

B. The Execution Runtime: J.A.R.V.I.S.

J.A.R.V.I.S. (Just Another Runtime for Validated Interactive Scientific workflows) acts as the "brain" and execution layer, converting natural language into traceable workflows.

• Bounded Action Space: Instead of allowing unconstrained code generation, the LLM interacts with a centralized tool registry. The system validates prerequisites (e.g., checking if a scaled layer exists before PCA) before execution.
• State-Aware & Recoverable: It maintains a session context including the active AnnData object, history, and failure traces. It supports iterative repair, plateau detection, and multi-stage recovery from execution errors.
• Controller-Mediated Loop: The system uses a multi-turn controller that separates model reasoning from action execution, ensuring that tool calls are validated against the current data state.
• Security & Policy: It employs AST-based static scanning, tool-level approval gates, and sandboxed execution to prevent malicious or unsafe operations.

C. The Agent Interface: ov.Agent & MCP

• ov.Agent: A language-driven entry point that accepts natural language tasks and an AnnData object, mapping requests to registered functions.
• MCP (Model Context Protocol) Server: Exposes the registry to external agents (e.g., Claude Code, custom scripts) via a standard JSON-RPC interface. Crucially, data never leaves the server; only lightweight handles (adata_id) are passed, ensuring security and efficiency.

3. Key Contributions

1. OmicClaw Framework: The first integrated system to combine a unified multi-omics ecosystem with a registry-grounded, state-aware runtime for executable natural-language analysis.
2. J.A.R.V.I.S. Runtime: A novel architecture that prevents AI hallucination by enforcing strict prerequisite validation and state tracking, transforming informal analysis suggestions into recoverable, traceable workflows.
3. Unified OmicVerse Ecosystem: A comprehensive Python library harmonizing >100 methods across bulk, single-cell, and spatial omics with a consistent API, supporting both CPU and GPU acceleration.
4. Benchmarking & Validation: A rigorous benchmark of 15 diverse tasks (scRNA-seq, spatial, velocity, scATAC-seq, CITE-seq, multiome) demonstrating that the agent significantly outperforms bare LLM baselines.
5. User Platforms:
   • OmicVerse Web: A beginner-friendly web platform with million-scale visualization, a notebook-style code editor, and an embedded terminal.
   • Skill Store: A mechanism for users to curate and reuse analytical workflows as "skills."

4. Results

• Performance Benchmark: Across 15 tasks spanning various omics modalities, ov.Agent significantly outperformed "bare" one-shot LLM baselines in rubric-based scores (execution success, artifact validity, scientific reasonableness).
  • Long-Horizon Tasks: The improvement was most pronounced in complex, multi-step workflows (e.g., trajectory and velocity inference), where the agent's ability to validate prerequisites and recover from errors was critical.
  • Error Reduction: The registry-grounded approach eliminated common failure modes like invalid argument passing and missing preprocessing steps.
• Computational Efficiency: OmicVerse demonstrated competitive or superior runtime scaling compared to Scanpy across datasets ranging from 2,000 to 100,000 cells, particularly when utilizing GPU backends.
• Output Fidelity: The system produced outputs (HVGs, PCA embeddings, clustering) that were structurally consistent with reference implementations (Scanpy), validated via Jaccard indices, subspace similarity, and clustering metrics (AMI, Homogeneity).
• Adoption: The ecosystem has seen rapid adoption, with >800 GitHub stars, >100k PyPI downloads, and usage in high-impact journals.

5. Significance

• Reproducibility: By grounding AI in a unified ecosystem and enforcing strict execution traces, OmicClaw addresses the reproducibility crisis in computational biology, ensuring that natural-language prompts result in verifiable, executable code.
• Democratization: The framework lowers the barrier to entry for experimental biologists, allowing them to perform complex multi-omics analyses via natural language or a web interface without deep coding expertise.
• Human-AI Collaboration: It shifts the paradigm from "LLM as a code generator" to "LLM as a bounded, auditable collaborator," where the AI operates within a safe, verified action space.
• Scalability: The architecture supports million-scale datasets and integrates modern foundation models, positioning it as a durable infrastructure for future multi-omics research.

In summary, OmicClaw provides a practical foundation for executable, reproducible, and scalable human-AI collaboration in modern multi-omics research, solving the fragmentation and reliability issues that have hindered the adoption of AI in bioinformatics.