gapit 0.6.2__tar.gz → 0.6.4__tar.gz

{gapit-0.6.2 → gapit-0.6.4}/AGENTS.md

@@ -178,7 +178,7 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
 
 - **Formats**: `--format tsv|csv|json|md` (default `tsv` for abricate compatibility).
 - **JSON**: top-level `"schema": "gapit.report/1"`; schema introspectable via
-  `gapit schema report | reads | reads2 | summary | list | error | version` (plus
+  `gapit schema report | reads | reads2 | summary | cluster | cluster2 | dblist | dboutdated | datadir | error | version` (plus
   `cluster | cluster2 | features | typing | typing_result | floors`). Keys are snake_case,
   units explicit (`identity_pct`, `coverage_pct`). Semver the schema; never rename or
   retype a field in a minor bump.
@@ -220,7 +220,7 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
   `gapit db path [--json]` introspects it without creating, while `db list`/`setupdb`
   bootstrap a missing root. See `docs/datadir.md` for the database anatomy, sharing and
   Docker policy.
-- **MCP** `[gapit-extension]`: `gapit mcp` / `gapit-mcp` stdio server exposing nine tools:
+- **MCP** `[gapit-extension]`: `gapit mcp` / `gapit-mcp` stdio server exposing ten tools:
   read-only `screen` (incl. `aligner minimap2` assembly survey), `screen_reads` (FASTQ via
   minimap2), `summary`, `schema`, `db_search`, `db_outdated`, plus `db_list` (may create the
   empty datadir on first use), and the datadir-mutating `db_fetch` (installs databases from

{gapit-0.6.2 → gapit-0.6.4}/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to gapit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.4] - 2026-10-27
+
+### Fixed
+
+- **Batch progress vs stdout data.** The progress bar now uses the gside/gmlst
+  hand-off: `transient=True`, stdout chunks go through `BatchProgress.write`
+  (stop -> `sys.stdout.write` + flush -> start), and stderr notices have a
+  `notice()` hand-off. The bar is inactive for a single input. On a shared TTY
+  data rows no longer start inside the bar line; stdout bytes are unchanged when
+  output is piped. Applies to contig batches and positional FASTQ samples;
+  `db fetch` receipts use the same suspend/restore path.
+
+## [0.6.3] - 2026-10-26
+
+### Added
+
+- **Complete agent JSON surface.** `gapit.report/1` params now record
+  `merge_fragments`; `gapit.dblist/1`, `gapit.dboutdated/1`, and
+  `gapit.datadir/1` are registered in `gapit schema`; `gapit.error/1` exposes the
+  full machine-readable error-code enum.
+- **MCP `db_path`.** The stdio server exposes the resolved datadir document, and
+  `screen` now uses canonical snake_case parameters (`merge_fragments`,
+  `min_gene_cov`, `min_gene_id`, `min_cluster_cov`). Legacy camelCase names remain
+  accepted as aliases.
+
+### Changed
+
+- **0.6.3 is the provenance-clean republish.** 0.6.2 was uploaded manually and
+  therefore has no PyPI provenance attestation; 0.6.3 is published by the GitHub
+  Actions release workflow through PyPI Trusted Publishing. The historical 0.6.2
+  release should be yanked/deleted in the PyPI UI.
+
 ## [0.6.2] - 2026-10-26
 
 ### Changed

{gapit-0.6.2 → gapit-0.6.4}/CITATION.cff

@@ -7,7 +7,7 @@ authors:
 repository-code: "https://github.com/indexofire/gapit"
 url: "https://indexofire.github.io/gapit/"
 license: MIT
-version: "0.6.2"
+version: "0.6.4"
 date-released: "2026-10-26"
 keywords:
   - bioinformatics

{gapit-0.6.2 → gapit-0.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gapit
-Version: 0.6.2
+Version: 0.6.4
 Summary: Mass screening of contigs and reads for known genes — agent-first Python reimplementation of abricate
 Project-URL: Homepage, https://github.com/indexofire/gapit
 Project-URL: Documentation, https://indexofire.github.io/gapit/
@@ -195,7 +195,7 @@ surfaces each provider's content license where one is pinned.
 gapit ships an MCP (Model Context Protocol) stdio server so agent runtimes can
 screen assemblies without parsing CLI output: `gapit mcp` or the `gapit-mcp`
 console script speaks newline-delimited JSON-RPC 2.0 on stdin/stdout (no extra
-dependencies — the protocol is hand-rolled). It exposes nine tools:
+dependencies — the protocol is hand-rolled). It exposes ten tools:
 `screen` (gapit.report/1 by default; `aligner minimap2` for a fast assembly
 survey), `screen_reads` (FASTQ via minimap2, gapit.reads/1), `summary`
 (gapit.summary/1), `schema`, `db_list`, plus the database tools `db_fetch`,

{gapit-0.6.2 → gapit-0.6.4}/README.md

@@ -166,7 +166,7 @@ surfaces each provider's content license where one is pinned.
 gapit ships an MCP (Model Context Protocol) stdio server so agent runtimes can
 screen assemblies without parsing CLI output: `gapit mcp` or the `gapit-mcp`
 console script speaks newline-delimited JSON-RPC 2.0 on stdin/stdout (no extra
-dependencies — the protocol is hand-rolled). It exposes nine tools:
+dependencies — the protocol is hand-rolled). It exposes ten tools:
 `screen` (gapit.report/1 by default; `aligner minimap2` for a fast assembly
 survey), `screen_reads` (FASTQ via minimap2, gapit.reads/1), `summary`
 (gapit.summary/1), `schema`, `db_list`, plus the database tools `db_fetch`,

{gapit-0.6.2 → gapit-0.6.4}/SPEC.md

@@ -421,8 +421,9 @@ path and is not exercised by the offline suite.
   table (NAME = the `--db` value, PROVIDER = upstream maintainer org; `installed (N)`
   iff `<datadir>/<name>/gapit-manifest.json` exists, else `available`),
   or `gapit.dblist/1` JSON (`providers[]`: `name`, `vendor`, `description`, `dbtype`,
-  `installed`, `records` omitted when unset). Module-local schema, deliberately NOT in
-  `gapit schema`. A missing datadir is bootstrapped (created) before listing, so a fresh
+  `installed`, `indexed`, `records` omitted when unset). Registered as
+  `gapit schema dblist`; `gapit schema dboutdated`/`datadir` expose the sibling
+  listings. A missing datadir is bootstrapped (created) before listing, so a fresh
   installation can inspect the catalog; `setupdb` bootstraps it too.
 - `gapit db install SOURCE --sha256 HASH --output TARGET` — verified LOCAL-FILE install
   only (no network, no providers, no archives): streaming SHA256, atomic replace after the

{gapit-0.6.2 → gapit-0.6.4}/docs/agents.md

@@ -13,12 +13,13 @@ Version, as one JSON line:
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.6.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.6.4"}
 ```
 
-Output schemas. Twelve documents are introspectable: `report`, `typing_result`, `reads`,
-`reads2`, `cluster`, `cluster2`, `summary`, `error`, `version`, plus the database-side
-documents `features`, `typing`, and `floors`. Each prints its full JSON Schema:
+Output schemas. Fifteen documents are introspectable: `report`, `typing_result`,
+`reads`, `reads2`, `cluster`, `cluster2`, `summary`, `error`, `version`, `dblist`,
+`dboutdated`, `datadir`, plus the database-side documents `features`, `typing`, and
+`floors`. Each prints its full JSON Schema:
 
 ```console
 $ gapit schema report          # gapit.report/1 (contig screening)
@@ -30,6 +31,9 @@ $ gapit schema cluster2        # gapit.cluster/2 (multi-scheme cluster screening
 $ gapit schema summary         # gapit.summary/1
 $ gapit schema error           # gapit.error/1
 $ gapit schema version         # gapit.version/1
+$ gapit schema dblist          # gapit.dblist/1 (database catalog)
+$ gapit schema dboutdated      # gapit.dboutdated/1 (staleness report)
+$ gapit schema datadir         # gapit.datadir/1 (resolved path/source)
 $ gapit schema features        # gapit.features/1 (cluster db feature table)
 $ gapit schema typing          # gapit.typing/2 (db scoring spec; /1 still reads)
 $ gapit schema floors          # gapit.floors/1 (per-gene identity floors, reads mode)

{gapit-0.6.2 → gapit-0.6.4}/docs/agents.zh.md

@@ -12,11 +12,12 @@ gapit 生来就是被程序驱动的。每个输出都以机器可读为设计
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.6.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.6.4"}
 ```
 
-输出 schema。十二个文档可自省：`report`、`typing_result`、`reads`、`reads2`、`cluster`、`cluster2`、
-`summary`、`error`、`version`，外加数据库侧文档 `features`、`typing` 和 `floors`。每个都打印完整的
+输出 schema。十五个文档可自省：`report`、`typing_result`、`reads`、`reads2`、
+`cluster`、`cluster2`、`summary`、`error`、`version`、`dblist`、`dboutdated`、
+`datadir`，外加数据库侧文档 `features`、`typing` 和 `floors`。每个都打印完整的
 JSON Schema：
 
 ```console
@@ -29,6 +30,9 @@ $ gapit schema cluster2        # gapit.cluster/2 (multi-scheme cluster screening
 $ gapit schema summary         # gapit.summary/1
 $ gapit schema error           # gapit.error/1
 $ gapit schema version         # gapit.version/1
+$ gapit schema dblist          # gapit.dblist/1（数据库目录）
+$ gapit schema dboutdated      # gapit.dboutdated/1（过期报告）
+$ gapit schema datadir         # gapit.datadir/1（解析路径/来源）
 $ gapit schema features        # gapit.features/1 (cluster db feature table)
 $ gapit schema typing          # gapit.typing/2 (db scoring spec; /1 still reads)
 $ gapit schema floors          # gapit.floors/1 (per-gene identity floors, reads mode)

{gapit-0.6.2 → gapit-0.6.4}/docs/databases.md

@@ -308,8 +308,8 @@ databases; an unparseable `fetched_at` is `MANIFEST_MALFORMED` (exit 5). For bun
 databases the report is manifest-based as everywhere else: a materialized bundle ages
 from its materialization time, and no bundled-vs-upstream comparison happens in v1
 (see [Bundled databases](#bundled-databases-install-time-ready) — future work). For
-agents, `--json` emits a `gapit.dboutdated/1` document (a CLI listing like `gapit.dblist/1`, not registered with
-`gapit schema`):
+agents, `--json` emits a `gapit.dboutdated/1` document (introspectable via
+`gapit schema dboutdated`):
 
 ```console
 $ gapit db outdated --days 3 --json
@@ -564,7 +564,7 @@ versions. A real one, from the plasmidfinder database:
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"
@@ -589,7 +589,8 @@ versions. A real one, from the plasmidfinder database:
 | `minimap2_version` | string | minimap2 version in the build environment (reads mode indexes in memory; no `.mmi` is built) |
 
 `records.jsonl` and the manifest are file contracts. They never appear on stdout and are
-not registered with `gapit schema`.
+not registered with `gapit schema` (the stdio/listing documents `dblist`, `dboutdated`,
+and `datadir` are).
 
 ### floors.json — per-gene identity floors
 

{gapit-0.6.2 → gapit-0.6.4}/docs/databases.zh.md

@@ -281,8 +281,7 @@ card	2020-01-01T00:00:00Z	2454.55	stale
 目录；无法解析的 `fetched_at` 是 `MANIFEST_MALFORMED`（退出码 5）。内置数据库的
 报告与其他库一样以 manifest 为准：已物化的内置库从物化时刻起算年龄，v1 不做
 内置-vs-上游比较（见"内置数据库（即装即用）"一节 —— 属未来工作）。面向 agent，
-`--json` 输出 `gapit.dboutdated/1` 文档（形如 `gapit.dblist/1` 的 CLI 列表，未注册
-到 `gapit schema`）：
+`--json` 输出 `gapit.dboutdated/1` 文档（可用 `gapit schema dboutdated` 内省）：
 
 ```console
 $ gapit db outdated --days 3 --json
@@ -527,7 +526,7 @@ manifest，来自 plasmidfinder 数据库：
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"
@@ -552,7 +551,7 @@ manifest，来自 plasmidfinder 数据库：
 | `minimap2_version` | string | 构建环境中的 minimap2 版本（reads 模式在内存中建索引，不生成 `.mmi`） |
 
 `records.jsonl` 和 manifest 是文件契约。它们从不出现在 stdout，也未注册到
-`gapit schema`。
+`gapit schema`（stdio/列表文档 `dblist`、`dboutdated`、`datadir` 已注册）。
 
 ### floors.json — 按基因设置一致性下限 {#floorsjson}
 

{gapit-0.6.2 → gapit-0.6.4}/docs/datadir.md

@@ -180,7 +180,7 @@ docker run --rm -it \
   --user "$(id -u):$(id -g)" \
   -v gapit-data:/data/gapit \
   -e GAPIT_DATADIR=/data/gapit \
-  gapit:0.6.2 gapit db list
+  gapit:0.6.4 gapit db list
 ```
 
 For CI, mount or cache a workspace directory and pin versions:
@@ -189,7 +189,7 @@ For CI, mount or cache a workspace directory and pin versions:
 docker run --rm \
   -v "$PWD/.gapit-db:/data/gapit" \
   -e GAPIT_DATADIR=/data/gapit \
-  gapit:0.6.2 gapit screen sample.fna --db ecoli_dec
+  gapit:0.6.4 gapit screen sample.fna --db ecoli_dec
 ```
 
 You can bake reference databases into an image for **read-only** screening:

{gapit-0.6.2 → gapit-0.6.4}/docs/datadir.zh.md

@@ -164,7 +164,7 @@ docker run --rm -it \
   --user "$(id -u):$(id -g)" \
   -v gapit-data:/data/gapit \
   -e GAPIT_DATADIR=/data/gapit \
-  gapit:0.6.2 gapit db list
+  gapit:0.6.4 gapit db list
 ```
 
 CI 中挂载或缓存 workspace 目录，并固定版本：
@@ -173,7 +173,7 @@ CI 中挂载或缓存 workspace 目录，并固定版本：
 docker run --rm \
   -v "$PWD/.gapit-db:/data/gapit" \
   -e GAPIT_DATADIR=/data/gapit \
-  gapit:0.6.2 gapit screen sample.fna --db ecoli_dec
+  gapit:0.6.4 gapit screen sample.fna --db ecoli_dec
 ```
 
 可以为**只读**筛查把参考库烤进镜像：

{gapit-0.6.2 → gapit-0.6.4}/docs/installation.md

@@ -48,9 +48,9 @@ gapit --version
 
 ```console
 $ gapit --version
-gapit 0.6.2
+gapit 0.6.4
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.6.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.6.4"}
 ```
 
 ## Optional gseek engine

{gapit-0.6.2 → gapit-0.6.4}/docs/installation.zh.md

@@ -46,9 +46,9 @@ gapit --version
 
 ```console
 $ gapit --version
-gapit 0.6.2
+gapit 0.6.4
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.6.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.6.4"}
 ```
 
 ## 可选 gseek 引擎

{gapit-0.6.2 → gapit-0.6.4}/docs/mcp.md

@@ -30,8 +30,8 @@ the module CLI as `{"command": "gapit", "args": ["mcp"]}`.
 
 ## Tools
 
-Nine tools: four analysis tools (`screen`, `screen_reads`, `summary`, `schema`)
-and five database tools (`db_list`, `db_fetch`, `db_build`, `db_search`,
+Ten tools: four analysis tools (`screen`, `screen_reads`, `summary`, `schema`)
+and six database tools (`db_list`, `db_path`, `db_fetch`, `db_build`, `db_search`,
 `db_outdated`) that mirror `gapit db ...` exactly. `db_list`/`db_search`/
 `db_outdated` are read-only (`db_list` may create an empty datadir on first
 use); `db_fetch`/`db_build` mutate the datadir. Argument lists below are
@@ -39,11 +39,12 @@ transcribed from the live `tools/list` `inputSchema` objects.
 
 | Tool | Arguments | Returns |
 |---|---|---|
-| `screen` | `files` (array of strings, required), `db` (string, required — no default), `minid` (number), `mincov` (number), `format` (string: `json` \| `tsv` \| `csv` \| `md`, default `json`), `aligner` (string: `blastn` \| `minimap2`, default `blastn`), `mergeFragments` (boolean, default `false`; blastn only — cross-contig fragment merging), `min_breadth` (number 0–100, default `90`; minimap2 only), `min_identity` (number 0–100, default `0`; minimap2 only), `min_mapq` (integer ≥ 0, default `0`; minimap2 only), `all_genes` (boolean; minimap2 only), `minGeneCov` (number 0–100, default `90`; cluster dbs only), `minGeneId` (number 0–100, default `90`; cluster dbs only), `minClusterCov` (number 0–100, default `96`; cluster dbs only), `datadir` (string) | Report text: `gapit.report/1` JSON by default, TSV/CSV/Markdown per `format`; `aligner minimap2` runs the reads engine and emits `gapit.reads/1`. A cluster-kind `db` emits `gapit.cluster/1`: best-locus call, per-gene verdicts, and — when the database carries a single-scheme `typing.json` — the phenotype call with its `phenotype_detail` score breakdown; a multi-scheme `typing.json` emits `gapit.cluster/2` with a `phenotypes` map of every scheme's call |
+| `screen` | `files` (array of strings, required), `db` (string, required — no default), `minid` (number), `mincov` (number), `format` (string: `json` \| `tsv` \| `csv` \| `md`, default `json`), `aligner` (string: `blastn` \| `minimap2`, default `blastn`), `merge_fragments` (boolean, default `false`; blastn only — cross-contig fragment merging), `min_breadth` (number 0–100, default `90`; minimap2 only), `min_identity` (number 0–100, default `0`; minimap2 only), `min_mapq` (integer ≥ 0, default `0`; minimap2 only), `all_genes` (boolean; minimap2 only), `min_gene_cov` (number 0–100, default `90`; cluster dbs only), `min_gene_id` (number 0–100, default `90`; cluster dbs only), `min_cluster_cov` (number 0–100, default `96`; cluster dbs only), `datadir` (string) | Report text: `gapit.report/1` JSON by default, TSV/CSV/Markdown per `format`; `aligner minimap2` runs the reads engine and emits `gapit.reads/1`. A cluster-kind `db` emits `gapit.cluster/1`: best-locus call, per-gene verdicts, and — when the database carries a single-scheme `typing.json` — the phenotype call with its `phenotype_detail` score breakdown; a multi-scheme `typing.json` emits `gapit.cluster/2` with a `phenotypes` map of every scheme's call |
 | `screen_reads` | `r1` (array of strings, required — one path per lane), `r2` (array of strings, same count as `r1`), `read_type` (string: `sr` \| `map-ont` \| `map-hifi`, default `sr`), `min_breadth` (number 0–100, default `90`), `min_identity` (number 0–100, default `0`), `min_mapq` (integer ≥ 0, default `0`), `all_genes` (boolean), `format` (string: `json` \| `tsv` \| `csv` \| `md`, default `json`), `db` (string, required — no default), `datadir` (string) | `gapit.reads/1` JSON by default or TSV/CSV/Markdown per `format`; `min_identity`/`min_mapq` > 0 switches to `gapit.reads/2` |
 | `summary` | `files` (array of report table paths, required), `identity` (boolean), `nopath` (boolean) | `gapit.summary/1` JSON |
 | `schema` | `name` (string, required, one of `cluster`, `error`, `features`, `floors`, `reads`, `reads2`, `report`, `summary`, `typing`, `typing_result`, `version`) | The JSON Schema of that output document |
-| `db_list` | `datadir` (string) | `gapit.dblist/1`: database names, install state, record counts |
+| `db_list` | `datadir` (string) | `gapit.dblist/1`: database names, install state, record counts, indexed flag |
+| `db_path` | `datadir` (string) | `gapit.datadir/1`: resolved datadir, existence, and source |
 | `db_fetch` | `name` (string, required — a database NAME, or `all` for the card+vfdb default set), `datadir` (string), `force` (boolean, default `false`) | One JSON receipt line per database (`db`, `records`, `dbtype`, `destination`). Every database downloads from its upstream provider, so installs need network and can take minutes |
 | `db_build` | `name` (string, required), `fasta` (string, required — a LOCAL filesystem path), `tsv` (string), `dbtype` (string: `nucl` \| `prot`), `description` (string), `kind` (string: `gene` \| `cluster`), `typing` (string), `floors` (string), `datadir` (string), `force` (boolean, default `false`) | One JSON receipt line (`db`, `records`, `dbtype`, `destination`) |
 | `db_search` | `term` (string, required), `db` (string), `field` (string: `gene` \| `accession` \| `function` \| `product` \| `any`, default `any`), `exact` (boolean, default `false`), `limit` (integer ≥ 0, default `100`; `0` = unlimited), `datadir` (string) | TSV hit rows with columns `DB`, `GENE`, `ACCESSION`, `FUNCTION`, `PRODUCT`, `LENGTH` |
@@ -57,6 +58,9 @@ reads-engine parameters); `minid`/`mincov` are ignored by `minimap2`.
 
 Notes:
 
+- Screen parameters use snake_case (`merge_fragments`, `min_gene_cov`,
+  `min_gene_id`, `min_cluster_cov`). The pre-0.6.4 camelCase spellings are still
+  accepted as aliases for compatibility, but new clients should use snake_case.
 - File paths resolve relative to the server's working directory; absolute
   paths are safest.
 - The datadir comes from `--datadir` (where available), then `$GAPIT_DATADIR`, then
@@ -98,7 +102,7 @@ EOF
 Response line 1, verbatim:
 
 ```text
-{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.6.2"}}}
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.6.4"}}}
 ```
 
 Response line 2 (real output, elided in the middle; each tool carries its full
@@ -121,7 +125,7 @@ the same run):
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-09-19T01:15:44Z",
   "params": {"db": "tinyamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [
@@ -177,7 +181,7 @@ the same run):
 ```json
 {
   "schema": "gapit.reads/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-09-22T00:07:35Z",
   "params": {
     "db": "tinyreads",
@@ -252,7 +256,7 @@ hit is the gene the agent just built the database from (real output):
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-09-20T13:38:39Z",
   "params": {"db": "myamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [

{gapit-0.6.2 → gapit-0.6.4}/docs/mcp.zh.md

@@ -28,8 +28,8 @@ shell 外调或解析终端输出。协议是手写的换行分隔 JSON-RPC 2.0
 
 ## 工具
 
-九个工具：四个分析工具（`screen`、`screen_reads`、`summary`、`schema`）和五个
-数据库工具（`db_list`、`db_fetch`、`db_build`、`db_search`、`db_outdated`），与
+十个工具：四个分析工具（`screen`、`screen_reads`、`summary`、`schema`）和六个
+数据库工具（`db_list`、`db_path`、`db_fetch`、`db_build`、`db_search`、`db_outdated`），与
 `gapit db ...` 完全对应。`db_list`/`db_search`/`db_outdated` 是只读的
 （`db_list` 首次使用可能创建空 datadir）；`db_fetch`/`db_build` 会修改 datadir。
 下表参数列表转写自线上的
@@ -37,11 +37,12 @@ shell 外调或解析终端输出。协议是手写的换行分隔 JSON-RPC 2.0
 
 | 工具 | 参数 | 返回 |
 |---|---|---|
-| `screen` | `files`（字符串数组，必填）、`db`（string，必填 —— 无默认值）、`minid`（number）、`mincov`（number）、`format`（string：`json` \| `tsv` \| `csv` \| `md`，默认 `json`）、`aligner`（string：`blastn` \| `minimap2`，默认 `blastn`）、`mergeFragments`（boolean，默认 `false`；仅 blastn：跨 contig 片段合并）、`min_breadth`（number 0-100，默认 `90`；仅 minimap2）、`min_identity`（number 0-100，默认 `0`；仅 minimap2）、`min_mapq`（integer ≥ 0，默认 `0`；仅 minimap2）、`all_genes`（boolean；仅 minimap2）、`minGeneCov`（number 0-100，默认 `90`；仅 cluster 数据库）、`minGeneId`（number 0-100，默认 `90`；仅 cluster 数据库）、`minClusterCov`（number 0-100，默认 `96`；仅 cluster 数据库）、`datadir`（string） | 报告文本：默认 `gapit.report/1` JSON，按 `format` 也可为 TSV、CSV 或 Markdown；`aligner minimap2` 跑 reads 引擎并输出 `gapit.reads/1`。cluster 类型的 `db` 输出 `gapit.cluster/1`：最佳位点判定、逐基因判定，数据库携带单 scheme `typing.json` 时还有带 `phenotype_detail` 分数分解的表型判定；多 scheme `typing.json` 则输出 `gapit.cluster/2`，携带每个 scheme 判定的 `phenotypes` 映射 |
+| `screen` | `files`（字符串数组，必填）、`db`（string，必填 —— 无默认值）、`minid`（number）、`mincov`（number）、`format`（string：`json` \| `tsv` \| `csv` \| `md`，默认 `json`）、`aligner`（string：`blastn` \| `minimap2`，默认 `blastn`）、`merge_fragments`（boolean，默认 `false`；仅 blastn：跨 contig 片段合并）、`min_breadth`（number 0-100，默认 `90`；仅 minimap2）、`min_identity`（number 0-100，默认 `0`；仅 minimap2）、`min_mapq`（integer ≥ 0，默认 `0`；仅 minimap2）、`all_genes`（boolean；仅 minimap2）、`min_gene_cov`（number 0-100，默认 `90`；仅 cluster 数据库）、`min_gene_id`（number 0-100，默认 `90`；仅 cluster 数据库）、`min_cluster_cov`（number 0-100，默认 `96`；仅 cluster 数据库）、`datadir`（string） | 报告文本：默认 `gapit.report/1` JSON，按 `format` 也可为 TSV、CSV 或 Markdown；`aligner minimap2` 跑 reads 引擎并输出 `gapit.reads/1`。cluster 类型的 `db` 输出 `gapit.cluster/1`：最佳位点判定、逐基因判定，数据库携带单 scheme `typing.json` 时还有带 `phenotype_detail` 分数分解的表型判定；多 scheme `typing.json` 则输出 `gapit.cluster/2`，携带每个 scheme 判定的 `phenotypes` 映射 |
 | `screen_reads` | `r1`（字符串数组，必填，每条 lane 一个路径）、`r2`（字符串数组，数量与 `r1` 相同）、`read_type`（string：`sr` \| `map-ont` \| `map-hifi`，默认 `sr`）、`min_breadth`（number 0-100，默认 `90`）、`min_identity`（number 0-100，默认 `0`）、`min_mapq`（integer ≥ 0，默认 `0`）、`all_genes`（boolean）、`format`（string：`json` \| `tsv` \| `csv` \| `md`，默认 `json`）、`db`（string，必填 —— 无默认值）、`datadir`（string） | 默认 `gapit.reads/1` JSON，按 `format` 可为 TSV、CSV 或 Markdown；`min_identity`/`min_mapq` > 0 切换为 `gapit.reads/2` |
 | `summary` | `files`（报告表路径数组，必填）、`identity`（boolean）、`nopath`（boolean） | `gapit.summary/1` JSON |
 | `schema` | `name`（string，必填，取值 `cluster`、`error`、`features`、`floors`、`reads`、`reads2`、`report`、`summary`、`typing`、`typing_result`、`version` 之一） | 该输出文档的 JSON Schema |
-| `db_list` | `datadir`（string） | `gapit.dblist/1`：数据库名、安装状态、记录数 |
+| `db_list` | `datadir`（string） | `gapit.dblist/1`：数据库名、安装状态、记录数、索引状态 |
+| `db_path` | `datadir`（string） | `gapit.datadir/1`：解析后的数据目录、是否存在、来源 |
 | `db_fetch` | `name`（string，必填——数据库名，或 `all` 表示 card+vfdb 默认集合）、`datadir`（string）、`force`（boolean，默认 `false`） | 每个数据库一行 JSON 回执（`db`、`records`、`dbtype`、`destination`）。每个数据库都从其上游提供商下载，安装需要网络且可能耗时数分钟 |
 | `db_build` | `name`（string，必填）、`fasta`（string，必填，本地文件系统路径）、`tsv`（string）、`dbtype`（string：`nucl` \| `prot`）、`description`（string）、`kind`（string：`gene` \| `cluster`）、`typing`（string）、`floors`（string）、`datadir`（string）、`force`（boolean，默认 `false`） | 一行 JSON 回执（`db`、`records`、`dbtype`、`destination`） |
 | `db_search` | `term`（string，必填）、`db`（string）、`field`（string：`gene` \| `accession` \| `function` \| `product` \| `any`，默认 `any`）、`exact`（boolean，默认 `false`）、`limit`（integer ≥ 0，默认 `100`；`0` = 不限）、`datadir`（string） | TSV 命中行，列为 `DB`、`GENE`、`ACCESSION`、`FUNCTION`、`PRODUCT`、`LENGTH` |
@@ -54,6 +55,9 @@ shell 外调或解析终端输出。协议是手写的换行分隔 JSON-RPC 2.0
 
 注意事项：
 
+- screen 参数使用 snake_case（`merge_fragments`、`min_gene_cov`、`min_gene_id`、
+  `min_cluster_cov`）；0.6.4 之前的 camelCase 拼写仍作为兼容别名接受，新客户端
+  应使用 snake_case。
 - 文件路径相对服务器的工作目录解析；绝对路径最稳妥。
 - 数据目录来自 `--datadir`（可用时），然后 `$GAPIT_DATADIR`，然后
   `$XDG_DATA_HOME/gapit/db`，最后 `~/.local/share/gapit/db`（见 `./datadir.md`）。
@@ -94,7 +98,7 @@ EOF
 响应第 1 行，原样：
 
 ```text
-{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.6.2"}}}
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.6.4"}}}
 ```
 
 响应第 2 行（真实输出，中段省略；每个工具携带完整的 `inputSchema`）：
@@ -115,7 +119,7 @@ EOF
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-09-19T01:15:44Z",
   "params": {"db": "tinyamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [
@@ -169,7 +173,7 @@ EOF
 ```json
 {
   "schema": "gapit.reads/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-09-22T00:07:35Z",
   "params": {
     "db": "tinyreads",
@@ -242,7 +246,7 @@ export GAPIT_DATADIR=/tmp/gapit-mcp-demo/datadir
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-09-20T13:38:39Z",
   "params": {"db": "myamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [

{gapit-0.6.2 → gapit-0.6.4}/docs/outputs.md

@@ -141,7 +141,7 @@ Real document, same run as the TSV above:
   "schema": "gapit.report/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T01:12:20Z",
   "params": {
@@ -186,6 +186,7 @@ Real document, same run as the TSV above:
 | `params.minid` | number | Minimum identity threshold |
 | `params.mincov` | number | Minimum coverage threshold |
 | `params.threads` | integer | BLAST thread count |
+| `params.merge_fragments` | boolean | Present (true) only for `--merge-fragments` runs |
 | `files` | array | One entry per input file, zero-hit files included |
 | `files[].file` | string | Input path as given |
 | `files[].hits` | array | Surviving hits, empty list when none |
@@ -232,7 +233,7 @@ row by `(%IDENTITY, %COVERAGE)`. Real document (trimmed):
 ```json
 {
   "schema": "gapit.typing_result/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-10-02T10:04:55Z",
   "source": ["dec.tsv"],
   "db": "ecoli_dec",
@@ -419,7 +420,7 @@ summarizing two report files, one with a `tetA` hit and one with none:
   "schema": "gapit.summary/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T01:11:09Z",
   "params": {
@@ -495,7 +496,7 @@ Any failure prints one line of JSON to stderr:
 | Field | Type | Meaning |
 |---|---|---|
 | `schema` | string | Always `gapit.error/1` |
-| `code` | string | Machine-stable error code, SCREAMING_SNAKE_CASE |
+| `code` | string | Machine-stable error code, SCREAMING_SNAKE_CASE; the enum is exposed by `gapit schema error` |
 | `message` | string | Human-readable description |
 | `context` | object | String-valued details (file paths, digests, db names) |
 
@@ -543,7 +544,7 @@ An agent can discover the whole contract from the binary alone.
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.6.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.6.4"}
 ```
 
 `gapit schema <name>` prints the JSON Schema for each document. The eleven names: `report`,

{gapit-0.6.2 → gapit-0.6.4}/docs/outputs.zh.md

@@ -130,7 +130,7 @@ non-DEC。零命中文件不产生筛查行，因此不会出现在判定输出
   "schema": "gapit.report/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T01:12:20Z",
   "params": {
@@ -175,6 +175,7 @@ non-DEC。零命中文件不产生筛查行，因此不会出现在判定输出
 | `params.minid` | number | 最小一致性阈值 |
 | `params.mincov` | number | 最小覆盖度阈值 |
 | `params.threads` | integer | BLAST 线程数 |
+| `params.merge_fragments` | boolean | 仅 `--merge-fragments` 运行时出现（true） |
 | `files` | array | 每个输入文件一项，含零命中文件 |
 | `files[].file` | string | 按原样的输入路径 |
 | `files[].hits` | array | 幸存命中，无命中时为空列表 |
@@ -219,7 +220,7 @@ non-DEC。零命中文件不产生筛查行，因此不会出现在判定输出
 ```json
 {
   "schema": "gapit.typing_result/1",
-  "tool": {"name": "gapit", "version": "0.6.2"},
+  "tool": {"name": "gapit", "version": "0.6.4"},
   "created_at": "2026-10-02T10:04:55Z",
   "source": ["dec.tsv"],
   "db": "ecoli_dec",
@@ -402,7 +403,7 @@ typing 的数据库是同一个表头去掉 `PHENOTYPE`。没有位点判定的
   "schema": "gapit.summary/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T01:11:09Z",
   "params": {
@@ -477,7 +478,7 @@ frontmatter 在第一个文件之前即可知，因此 md 与 tsv 行一样逐
 | 字段 | 类型 | 含义 |
 |---|---|---|
 | `schema` | string | 恒为 `gapit.error/1` |
-| `code` | string | 机器稳定的错误码，SCREAMING_SNAKE_CASE |
+| `code` | string | 机器稳定的错误码，SCREAMING_SNAKE_CASE；枚举由 `gapit schema error` 暴露 |
 | `message` | string | 人类可读的描述 |
 | `context` | object | 字符串值的细节（文件路径、摘要、数据库名） |
 
@@ -525,7 +526,7 @@ agent 只凭二进制就能发现整个契约。
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.6.2"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.6.4"}
 ```
 
 `gapit schema <name>` 打印每个文档的 JSON Schema。十二个名字：`report`、

{gapit-0.6.2 → gapit-0.6.4}/docs/quickstart.md

@@ -94,7 +94,7 @@ gapit screen tests/data/contigs/full.fa --db tinyamr --format json
   "schema": "gapit.report/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T01:11:06Z",
   "params": {

{gapit-0.6.2 → gapit-0.6.4}/docs/quickstart.zh.md

@@ -89,7 +89,7 @@ gapit screen tests/data/contigs/full.fa --db tinyamr --format json
   "schema": "gapit.report/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T01:11:06Z",
   "params": {

{gapit-0.6.2 → gapit-0.6.4}/docs/reads.md

@@ -123,7 +123,7 @@ table, one chunk for the one sample).
 ## Options
 
 Reads mode runs through the same `gapit screen` command; these are the flags that apply
-(transcribed from `gapit screen --help`, gapit 0.6.2). Contig-mode flags not listed here
+(transcribed from `gapit screen --help`, gapit 0.6.4). Contig-mode flags not listed here
 (`--minid`, `--mincov`, `--fofn`, `--noheader`, `--nopath`) do not apply; `--jobs` applies
 to the wildcard path only.
 
@@ -337,7 +337,7 @@ The short-read fixture behaves the same with one calibration: `sr` soft-clipping
 $ gapit screen --r1 ont_homologs.fq --db homologs --read-type map-ont --min-identity 95 --format md --quiet
 ---
 schema: gapit.reads/2
-tool: gapit 0.6.2
+tool: gapit 0.6.4
 created_at: 2026-09-20T14:23:33Z
 db: homologs
 read_type: map-ont
@@ -433,7 +433,7 @@ $ gapit screen --r1 tetx_full.fq --db tinyreads --format json
   "schema": "gapit.reads/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T01:12:25Z",
   "params": {
@@ -528,7 +528,7 @@ $ gapit screen --r1 tetx_lane1.fq,tetx_lane2.fq --db tinyreads --format json --q
 $ gapit screen --r1 tetx_full.fq --db tinyreads --format md
 ---
 schema: gapit.reads/1
-tool: gapit 0.6.2
+tool: gapit 0.6.4
 created_at: 2026-09-19T01:12:25Z
 db: tinyreads
 read_type: sr
@@ -630,7 +630,7 @@ Detected 2 present genes in /tmp/gapit-demo/assembly.fa
   "schema": "gapit.reads/1",
   "tool": {
     "name": "gapit",
-    "version": "0.6.2"
+    "version": "0.6.4"
   },
   "created_at": "2026-09-19T14:23:00Z",
   "params": {
@@ -689,7 +689,7 @@ cost of allele-level precision. That trade suggests a two-stage workflow over ma
    pipeline, which applies the identity and coverage floors at abricate parity.
 
 Real numbers, one K. pneumoniae RefSeq assembly (GCF_000240185.1, 5.3 Mb, `--db ncbi`,
-single-threaded, gapit 0.6.2):
+single-threaded, gapit 0.6.4):
 
 ```console
 $ # Stage 1: survey, ~0.9 s