GEO-Agent

An intelligent assistant for biomedical researchers to discover and analyze datasets from the GEO (Gene Expression Omnibus) database using natural language interaction.

Key Features

• AI-Powered Multi-Stage Search: Sophisticated retrieval pipeline with LLM-based intent parsing, a dual-database backend (SQLite FTS5 + Vector Embeddings), LLM-driven logical filtering, anddeep Cross-Encoder re-ranking.
• Instant Dataset Insights: Provides one-click extraction of core study summaries, standardized sample metadata tables, and integrated bibliographic details—including linked publication titles and abstracts.
• Automated Omics and Platforms Identification: Uses LLMs to deeply analyze experimental protocols, automatically identifying omics types and experimental platform.
• Multi-omics & ChIP-seq Pairing: Intelligently parses sample relationships to automate multi-omics pairing logic and identify Input/IP relationships in ChIP-seq datasets.
• Metadata Cleaning & Standardized Naming: Automatically parses and standardizes complex sample naming conventions based on contextual understanding.
• Extensive API Compatibility: Full, out-of-the-box support for OpenAI-compatible APIs to enable seamless switching between diverse LLM providers.
• bioStream Pipeline Orchestration: Turnkey generation of reproducible Nextflow execution scripts tailored for bioStream, allowing users to seamlessly dispatch automated primary analysis across 6 major omics types (RNA-seq, scRNA-seq, ATAC-seq, scATAC-seq, ChIP-seq, and scMultiome) to their local high-compute infrastructure.

🚀 Quick Start (Web Portal)

For most researchers, the easiest way to experience GEOAgent is through our free, fully-managed public cloud platform. No local installation, Docker configuration, or hardware acceleration is required.

👉 Access the Live Workspace immediately at: http://geoagent.ccla.ac.cn/

If you prefer to deploy a private instance on your own high-performance computing cluster or modify the source code, please skip to the Installation and Setup section below.

---

📖 Usage Guide

GEOAgent operates through two identical core intelligence engines: an interactive Web UI for visual exploration, and a VS Code Extension that brings the exact same multi-omics orchestration capabilities directly into your local development workspace without switching context.

1. Web UI Workflow: Curation & Analysis

1. Configure Search Parameters: Setup your preferred LLM provider (e.g., DeepSeek) and search result limits in the configuration panels.
2. Execute Dual-Engine Search: Input free-text natural language queries or specific GEO IDs (e.g., GSE136846) into the search interface. The backend will trigger a multi-stage execution trace—combining intent parsing, keyword search, and vector semantic ranking.
3. Select Target Dataset: Review the prioritized results ranked by computed relevance scores, and click "Select GSEXXXXXX" to load the comprehensive dataset details.
4. Inspect Metadata & Identify Omics: View the dynamically structured sample attributes, and click "Identify Omics Technology" to automatically classify sample-level assay modalities.
5. Filter & Extract Downstream Links: Filter targeted omics types or individual samples of interest. Click "Generate Download Links" to trigger the backend automated parsing logic for sample re-naming, single-cell multi-omics pairing, or ChIP-seq Input-IP control matching.
6. Orchestrate bioStream Pipeline: Click "Run bioStream for Automated Download and Preprocessing" to obtain structured metadata configuration files and reproducible Nextflow execution commands for your cluster.

2. VS Code Client Workflow: Native Workspace Integration

Note: This workflow requires the GEOAgent desktop client. If you haven't set it up yet, please quickly follow the VS Code Extension Installation guide below.

The GEOAgent VS Code Extension wraps the exact same backend intelligence pipeline into your native IDE, allowing you to curate datasets without switching to a web browser:

1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and execute the primary command: GEO-Agent: Interactive GEO Dataset Discovery
2. An interactive panel will launch inside your VS Code editor.
3. Use the integrated interface to search datasets, audit metadata, and directly copy the generated bioStream reproducible execution commands or configurations straight into your local scripts and terminal.

Installation and Setup

We provide a fully pre-configured, self-contained Docker image that bundles all software runtimes (including LangChain, Ollama client wrappers, and the Streamlit web backend) to eliminate platform-specific dependency conflicts and ensure an out-of-the-box runtime experience.

💡 Which deployment do you need?

• Just want the lightweight VS Code Client? You do not need to clone this repository or run Docker containers. Skip directly to VS Code Extension Installation to connect to our official cloud infrastructure in 60 seconds.
• Want to host a private instance? If you need local LLM support, custom dataset indexing, or private infrastructure execution, please proceed with Step 1 through Step 4 below.

---

Step 1: Clone the Repository & Prepare the Directory

First, clone the GEOAgent source code repository to your local machine or server, and navigate into the project root directory:

# Clone the core repository
git clone https://github.com/JiekaiLab/GEOAgent.git

# Enter the repository directory
cd GEOAgent

Step 2: Download & Integrate the Knowledge Base from Zenodo

Because the GEOAgent database and local BGE models are massive, they are decoupled from the core repository. Download the asset package, extract it, and place the components directly into a newly created database folder within the cloned directory:

# Download the asset package (approx. May 2026 update)
wget https://zenodo.org/record/20138122/files/geoAgent_database_20260512.tar.gz

# Extract the package
tar -xzf geoAgent_database_20260512.tar.gz

# Reorganize into a dedicated database directory
mkdir -p ./database
mv bge-reranker sqlite_db vector_db ./database/

Step 3: Launch the Container & Run the Workspace

Now, pull the latest production Docker image and launch the Streamlit server in interactive mode. If you are deploying on a remote high-performance computing node, we also provide the precise SSH tunneling commands to map the port back to your local browser.

# 1. Pull the Production-Ready Image
docker pull zhaoyybio/geo_agent:latest

# 2. Run the Container and Mount the Repository
docker run -it --rm \
  --name geo_agent \
  -p 8501:8501 \
  -v $(pwd):/workspace \
  zhaoyybio/geo_agent:latest

# 3. Start the Streamlit Application
streamlit run app.py --server.address 0.0.0.0 --server.port 8501

Step 4: Accessing the Workspace

Once the Streamlit server is running, you can access the interactive interface via your browser:

• Local Machine: Open http://localhost:8501

• Remote Server (SSH Tunnel): If running on a remote node, forward the port from your local machine terminal:

  ssh -L 8080:localhost:8501 user@your-server-ip

  Then open http://localhost:8080 in your browser.

VS Code Extension Installation

The GEOAgent VS Code Extension operates as a lightweight desktop client. It communicates via API endpoints and does not require downloading any database or running heavy containers on your local workstation. It connects directly to our centrally hosted cloud portal.

1. Install the VSIX Package

1. Navigate to the GEOAgent Releases Page and download the latest geo-agent-1.0.0.vsix from the Assets section.
2. Open your VS Code editor, and navigate to the Extensions side panel (Ctrl+Shift+X or Cmd+Shift+X).
3. Click the ... (Views and More Actions) dropdown menu at the top-right corner of the Extensions bar, select Install from VSIX..., and choose the downloaded file.

2. Configure your API Endpoint

Once installed, open your VS Code Settings (Ctrl+, or Cmd+,), search for GEOAgent, and bind the plugin to our official public infrastructure endpoint:

• Server URL: http://geoagent.ccla.ac.cn/api

Repository Architecture

The GEOAgent repository maintains a modular layout separating core intelligence backends, visualization components, and database storage runtimes.

Note: The contents of the database/ directory contain heavy binary assets and are excluded from GitHub version control via .gitignore. They are fully restored via the Zenodo data package as detailed in Installation and Setup.

├── app.py                  # Main Streamlit web application entry point
├── components/             # Reusable modular frontend UI widgets
│   └── ui_widgets.py
├── config/                 # Global application and LLM hyperparameter profiles
│   └── config.py
├── database/               # [Zenodo Target] Local runtime knowledge base mount point
│   ├── bge-reranker/       # Local BGE-Reranker-v2-m3 model weights for deep ranking
│   ├── sqlite_db/          # Pre-indexed SQLite databases for lightning-fast keyword search
│   └── vector_db/          # Persistent Chroma vector store for semantic embeddings
├── modules/                # Core backend intelligence engines and LLM pipeline wrappers
│   ├── database.py         # Relational and vector database query orchestration
│   ├── fetch_gsm_info.py   # Automated sample-level (GSM) metadata extraction logic
│   ├── llm.py              # LLM agent prompts, parsing controls, and API configurations
│   └── reranker.py         # Deep semantic ranking execution pipeline
└── dockerfile              # Production Docker image build recipe

License & Contact

• License: Distributed under the MIT License. Feel free to use, modify, and distribute the platform for both academic and commercial applications.
• Contact & Issues: For bug reports, feature requests, or collaboration inquiries, please open a GitHub Issue directly in this repository.