Skip to content

gseek documentation

English | 简体中文

gseek is a zero-runtime-dependency Python library for reproducible DNA alignment and distance workflows. It wraps BLAST+, minimap2, MUMmer4, KMA, BWA, mash, sourmash, and skani behind one request/result model, with content-addressed indexes and replayable run manifests.

Start here

I want to… Read
Install and run a first alignment Quickstart
Follow a complete walkthrough Tutorial
Use the Python API API reference
Script/automate the CLI CLI reference
Handle failures by code Error model
Understand reproducibility API: manifests and replay
Add a custom backend API: adapter protocol
Migrate a consumer safely Compatibility

Core idea

consumers: gside / gapit / gmlst / your pipeline
                  │
                  ▼
        gseek.align / gseek.distance
                  │
                  ▼
  probe → index → plan → execute → parse → manifest
                  │
                  ▼
      normalized records + provenance

Adapters are pure planners and parsers. Only gseek.execution starts processes. Business decisions such as allele calling, species thresholds, or phenotype rules belong in the consumer.

Install

pip install gseek==0.10.0

External tools are not bundled:

pixi add blast minimap2 mummer4 kma bwa mash sourmash skani

Check the environment:

gseek doctor
gseek backends

First Python call

from pathlib import Path

import gseek

result = gseek.align(
    backend="minimap2",
    query=Path("sample.fna"),
    target=[Path("scheme/alleles.fna")],
    preset="asm5",
    threads=8,
    index="auto",
    manifest=Path("runs/sample.manifest.json"),
)

for hit in result.records:
    print(hit.query_id, hit.target_id, hit.identity)

First CLI call

gseek align \
  --backend minimap2 \
  --query sample.fna \
  --target scheme/alleles.fna \
  --preset asm5 \
  --manifest runs/sample.manifest.json \
  -o runs/sample.json

Documentation map

  • Quickstart — install, first run, verify/replay.
  • API reference — public functions, result models, adapters, execution, indexing, manifests, schemas.
  • CLI reference — command matrix, output, exit codes.
  • Error model — exception hierarchy and JSON envelope.

Development material lives outside the user docs: