gside — Genome Species IDentification Engine

A standalone CLI for multi-layer species identification from assembled contigs and metagenomic profiling from FASTQ reads.

pip install gside

# Single-genome species identification
gside species contigs.fna --mode all

# Metagenomic profiling
gside meta reads_R1.fq reads_R2.fq --mode all

Species Identification (gside species)

Layered arbitration

Higher layers always outrank lower ones; within a layer, higher confidence wins.

Quick start

pixi install && pip install -e .

# Identify species (marker mode works out of the box)
gside species contigs.fna

# Install reference databases
gside db setup --tier panel

# Multi-method identification
gside species contigs.fna --mode all

# Parallel batch processing with streaming output
gside species *.fna --mode all -j 8 -t 4 -o results.tsv

Metagenomic Profiling (gside meta)

gside meta reads_R1.fq reads_R2.fq --mode all
gside meta contigs.fna --mode kraken2

Agent-Friendly Design

gside is built for AI agents as much as humans:

# JSON on stdout (always exit 0; errors in methods.<mode>.error)
gside species genome.fna --mode all

# Structured missing-database errors
# → methods.panel.suggested_command = "gside db setup --tier panel"
# → methods.panel.missing_tier = "panel"
# → methods.panel.estimated_size = "~130MB sketch / ~1GB genomes"

# Auto-install missing databases
gside species genome.fna --mode panel --auto-setup

# Machine-readable database status
gside db status -f json
gside db list -f json

MCP Server

gside includes an MCP (Model Context Protocol) stdio server:

gside mcp    # or: gside-mcp

Exposes species, db_status, db_list, db_setup as MCP tools for Claude Desktop or any MCP client.

{
  "mcpServers": {
    "gside": { "command": "gside-mcp" }
  }
}

CLI Reference

gside species <contigs.fna> [options]
  -m, --mode         marker|panel|mash_refseq|sourmash|gtdbtk|all
  -D, --db-dir       Database root
  -f, --format       json|tsv|md
  -o, --output       Write to file (tsv/md stream per input)
  -j, --jobs         Parallel input files
  -t, --threads      Threads per aligner
  -a, --auto-setup   Install missing databases automatically
  -n, --no-header    Suppress TSV header row

gside meta <reads/files> [options]
  -m, --mode         kraken2|sylph|all
  -D, --db-dir       Database root
  -f, --format       json|tsv
  -o, --output       Write to file
  -t, --threads      Threads per tool

gside db <subcommand>
  status             Show database readiness (--format table|tsv|csv|json)
  setup              Install databases (--tier mini|panel|mash|sourmash|all)
  list               List tiers with readiness (--format table|tsv|csv|json)

gside validate <contigs.fna>
  --mode simple|standard

gside mcp            MCP stdio server
gside --version      Version info
gside -V -J          Version as JSON

Databases

GTDB-Tk manages its own external database (GTDBTK_DATA_PATH).

Installation

# With pixi (recommended — includes blastn, skani, mash, sourmash)
curl -fsSL https://pixi.sh/install.sh | bash
pixi install
pip install -e .

# From PyPI (Python 3.12, binaries not included)
pip install gside

Documentation

• Quick Start
• CLI Reference
• Identification Modes
• Metagenomic Profiling
• JSON Output Contract
• 中文文档

License

MIT

Ecosystem