gseek

Unified, reproducible DNA alignment infrastructure for Python ≥ 3.12.

gseek 把 BLAST+、minimap2、MUMmer、KMA、BWA、mash/sourmash 等外部 DNA 比对工具封装成一层稳定 API：统一请求、统一结果模型、内容寻址索引、可复现的 run manifest。它面向 gside、gapit、gmlst 这类“需要反复做 DNA 比对”的基因组工具，避免每个项目重复实现命令拼装、输出解析、缓存和版本记录。

状态：M0 基座 + M1–M4 适配器（0.3.1 alpha，已发布 PyPI）。 BLAST+（核酸/蛋白）、minimap2、KMA、MUMmer4、BWA、mash、sourmash、skani 已可用；replay 已落地。真实输出 golden fixtures、8 后端 replay 矩阵与 gside 迁移分支已验证；剩余工作是 gmlst/gapit 迁移。

当前进度

• 工程骨架：pyproject.toml、src/ 布局、pixi、CI、MIT。
• gseek.model：AlignmentRecord / AlignmentResult / DistanceResult / RunManifest。
• gseek.execution：无 shell、绝对路径、超时、流式、stderr 排空、版本探测。
• gseek.index：内容寻址、文件锁、staging + 原子发布、GC。
• gseek.provenance：SHA-256、canonical JSON、recipe hash、manifest verify。
• gseek.adapter + gseek.registry + gseek.runner：三阶段协议与端到端编排。
• gseek.api 与 gseek CLI：align/distance/backends/doctor/index/manifest。
• 项目更名 gseek（原 gcore 名称冲突）；身份契约测试先红后绿。
• 工程规范：AGENTS.md（强制 TDD）、CONTRIBUTING.md、.editorconfig、pre-commit、ADR。
• MUMmer 版本确认：MUMmer 4.x（测试基线 4.0.1，ADR-0001）。
• M1：BLAST+（blastn）与 minimap2 适配器；真实工具集成测试通过。
• M2：KMA（FASTA/FASTQ/paired）与 MUMmer4（nucmer/show-coords、反向 strand）；真实工具集成测试通过。
• M3：BWA（SAM）、mash（sketch/dist/screen）、sourmash（sketch/search）；真实工具集成测试通过。
• M4：BLAST 蛋白任务（blastp/blastx/tblastn/tblastx）、sourmash gather、skani ANI、manifest replay。
• 真实工具 golden fixtures、gside/gapit/gmlst 字段 parity、8 后端 replay 矩阵。
• 321 个单元/契约测试 + 35 个集成测试（无工具时 skip）；覆盖率 88%；ruff + pyright 全绿。

为什么需要 gseek

三个现有工具各自维护了一套比对层，且语义并不一致：

gseek 的设计目标是：适配器只负责“无损规范化”，执行层负责“可复现”，业务结论留在消费者。

安装

# PyPI
pip install gseek==0.3.1

# 本地 wheel（发布物验证）
uv pip install dist/gseek-0.3.1-py3-none-any.whl

# 源码开发模式
pip install -e ".[dev]"

# 仓库环境
pixi install

命名说明：项目原名 gcore，因 PyPI 上的 gcore 已被 Gcore Python API 占用，于 2026-10-22 更名为 gseek。PyPI 分发名、导入名和 CLI 均为 gseek；0.3.1 已发布。决策记录见 ADR-0002。

稳定性：0.3.1 仍是 alpha；1.0 前公共 API 可能调整。生产集成请钉住 gseek==0.3.1，并通过 GSIDE_ENGINE/feature flag 保留旧路径。

外部工具不随包安装，按需通过 conda/pixi/系统包管理器安装：

pixi add blast minimap2 mummer4 kma bwa mash sourmash skani
# 或
conda install -c bioconda blast minimap2 mummer4 kma bwa mash sourmash skani

快速预览（M1–M4 可用）

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, hit.target_coverage)

summary = result.summarize_by_target()
best = result.best_per_query_target()

更多 API：

gseek.backends()                       # 能力矩阵
gseek.get_backend("blast").probe()     # 工具/版本探测
gseek.distance(...)                    # mash/sourmash/skani 距离/ANI
gseek.replay(Path("run.manifest.json"), check=True)
gseek.verify(Path("run.manifest.json"))

CLI 快速开始

# 先确认工具是否齐全；缺失时返回 1
gseek doctor

# 比对，并写出可 verify/replay 的 manifest
gseek align \
  --backend minimap2 \
  --query sample.fna \
  --target scheme/alleles.fna \
  --preset asm5 \
  --threads 8 \
  --manifest runs/sample.manifest.json \
  -o runs/sample.json

# 校验输入/工具/结果哈希
gseek verify runs/sample.manifest.json

# 重新规划并校验 result_hash；不会执行 manifest 里的旧 argv
gseek replay runs/sample.manifest.json --check --json

CLI 约定：结果写 stdout，错误写 stderr，默认错误是 gseek.error/1 JSON； --error-format text 可切换人类可读格式。详见 CLI。

架构

┌────────────────────────────────────────────────────────────┐
│ gside / gapit / gmlst / CLI                                │
└──────────────────────────┬─────────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────────┐
│ gseek.api: align / distance / backends                     │
└──────────────────────────┬─────────────────────────────────┘
                           ▼
┌────────────────────────────────────────────────────────────┐
│ runner: probe → index → plan → execute → parse → manifest  │
└───────┬──────────────────────┬──────────────────────┬──────┘
        ▼                      ▼                      ▼
┌──────────────┐      ┌────────────────┐     ┌────────────────┐
│  adapters    │      │   execution    │     │   index store  │
│ blast        │      │ command plan   │     │ content hash   │
│ minimap2     │      │ subprocess     │     │ lock + atomic  │
│ mummer4/kma  │      │ timeouts       │     │ GC             │
│ bwa/minhash  │      │ env/streaming  │     └────────────────┘
└───────┬──────┘      └───────┬────────┘
        └─────────────────────┴──────────────┐
                                             ▼
                              ┌────────────────────────────┐
                              │ result model + provenance  │
                              │ records / manifest / views │
                              └────────────────────────────┘

文档

• 文档首页：按角色导航。
• Quickstart：安装、第一个 CLI/Python 调用、manifest/replay。
• CLI：子命令、JSON 输出、退出码、自动化约定。
• 错误模型：异常层级、code/exit_code、处理建议。
• API 参考：公共 API、模型、适配器协议、执行/索引/可复现层、schema。
• 开发计划：目标、架构、接口、里程碑、风险、开放决策。
• 三工具调研：gside/gapit/gmlst 的代码级对比与重复点。
• 适配器矩阵：六类工具的命令、索引、解析、版本和坑。
• 兼容性迁移：字段映射、影子模式、parity 验收。
• ADR-0001：MUMmer4：确认目标为 MUMmer 4.x。
• ADR-0002：更名 gseek：名称冲突与迁移清单。
• AGENTS.md：TDD、架构边界、验证命令（开发者/agent 必读）。
• CONTRIBUTING.md：贡献流程与测试分层。
• CHANGELOG.md：版本变更记录。
• 发布清单：版本、构建、PyPI 上传与验证。

开发

TDD 是强制的：先写失败测试，确认失败原因，再写最少实现，最后跑全量门禁。详见 AGENTS.md。

pixi run test          # 全量单测
pixi run test-cov      # 覆盖率（fail_under=85）
pixi run lint          # ruff check + format --check
pixi run typecheck     # pyright
pixi run check         # lint + typecheck + test
pixi run pre-commit    # 全部 pre-commit hook

或手动：

PYTHONPATH=src pytest
ruff check . && ruff format --check src tests
PYTHONPATH=src pyright

设计原则

1. 适配器是纯规划器/解析器，不直接启动子进程。
2. 结果无损；归并是显式视图，不是隐式行为。
3. 坐标统一为 0-based half-open，strand 单独字段。
4. identity/coverage 带来源和公式，不只是一个数字。
5. 索引内容寻址；不依赖 mtime。
6. 默认确定性：稳定排序、LC_ALL=C、绝对路径、无 shell。
7. 核心零运行时依赖；外部工具通过 PATH/显式路径发现。
8. 类型化错误 + code + context + hint。
9. 文档即契约：适配器矩阵与 schema 和代码同步。
10. 先迁移、后删除；影子模式护航。

许可证

MIT。详见 LICENSE。