gapit 0.5.1__tar.gz → 0.5.2__tar.gz

{gapit-0.5.1 → gapit-0.5.2}/AGENTS.md

@@ -80,6 +80,7 @@ gapit/
 │   ├── db_query_ops.py  # db use-cases: search + outdated over installed DBs (shared CLI + MCP)
 │   ├── db_build_ops.py  # db use-case: custom FASTA+TSV → gene db, GBK/GFF → cluster db (shared CLI + MCP)
 │   ├── gbfeatures.py    # GenBank FEATURES/ORIGIN parser → LocusFeatures/GeneFeature + gapit.features/1
+│   ├── gene_floors.py   # gapit.floors/1 per-gene identity floors: model, loader, build validation, reads gate
 │   ├── gffparse.py      # GFF3 parser (embedded ##FASTA or sidecar) → the same locus/gene models
 │   ├── typing_models.py # gapit.typing schema (rules + named schemes; /1 degrades to one default scheme)
 │   ├── typing_rules.py  # gapit.typing rule models (weighted_genes/exact_set/cluster_match/learned_linear) + reference checks
@@ -160,7 +161,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
-  `cluster | features | typing | typing_result`). Keys are snake_case,
+  `cluster | 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.
 - **Markdown**: YAML frontmatter (tool version, db, params, ISO-8601 UTC timestamp) + tables a
@@ -177,12 +178,12 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
   database fetch from the provider catalog (every provider downloads from upstream at fetch
   time — nothing catalog-side is bundled inside the wheel beyond the sanctioned exceptions,
   a license-compliance requirement: CARD/VFDB terms are non-commercial and Kaptive is GPL,
-  so none of those may ride an MIT distribution; the sanctioned exceptions are the five
+  so none of those may ride an MIT distribution; the sanctioned exceptions are the six
   content-provenance-audited bundles under `src/gapit/data/dbs/` — the public-domain
-  `ecoli_dec` panel plus four permissively licensed provider snapshots (`ncbi` public
-  domain, `resfinder` Apache-2.0, `ecoh` BSD-3-Clause, `upec_expec_vf` MIT; GPL/NC content
-  is never bundled) — materialized into the datadir on first use via `bundled.py`, with
-  `db fetch <name>` still the fresh-upstream refresh path),
+  `ecoli_dec` and `lm_doumith` panels plus four permissively licensed provider snapshots
+  (`ncbi` public domain, `resfinder` Apache-2.0, `ecoh` BSD-3-Clause, `upec_expec_vf`
+  MIT; GPL/NC content is never bundled) — materialized into the datadir on first use via
+  `bundled.py`, with `db fetch <name>` still the fresh-upstream refresh path),
   database listing,
   records.jsonl gene search, staleness
   report, custom FASTA→native-db build, GBK/GFF→cluster-db build (`--typing` installs a

{gapit-0.5.1 → gapit-0.5.2}/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.5.2] - 2026-10-03
+
+### Added
+
+- **Per-gene identity floors for reads-mode presence (`gapit.floors/1`) — the db-driven
+  fix for the 26ECO0084 `pic` SPATE false positive.** A gene database may carry an
+  optional `floors.json` sidecar declaring a minimum alignment identity (%) per gene:
+  in reads mode, alignments to a floored gene below its floor are dropped BEFORE
+  aggregation, so breadth is recomputed from the surviving rows (a ~86.6%-identity,
+  97.59%-breadth SPATE homolog collapses below the presence threshold instead of
+  over-calling `pic`, matching the blastn contig verdict). **Strictly opt-in via
+  DATABASE metadata, not a CLI change**: a database without the sidecar screens
+  byte-identically to before, existing databases need nothing, and the blastn contig
+  path never reads floors (`--minid` already gates it). Floors compose conjunctively
+  with `gapit.reads/2` `--min-identity` (a row must clear both); `gapit.reads/1`
+  output shape is untouched (presence/breadth changes only for floored genes). New
+  module `gapit.gene_floors` (model registered as `gapit schema floors`), `gapit db
+  build NAME.fa --floors FILE` (gene builds only; cluster inputs reject it) installs a
+  validated copy — every listed gene must exist in the FASTA (`FLOORS_UNKNOWN_GENE`),
+  values in [0, 100] and structure per the schema (`FLOORS_MALFORMED`); dropping the
+  file into an existing db directory works too. The bundled `ecoli_dec` now ships
+  `{"genes": {"pic": 90.0}}` (true `pic` ≥95%; `astA` deliberately unfloored — true
+  alleles at 90.4–91% leave no margin), materialized with the bundle; MCP `screen_reads`
+  inherits the gate through the shared use-case.
+
+- **Bundled `lm_doumith`: Listeria monocytogenes serogrouping (Doumith 2004) — the sixth
+  bundled database.** Five markers extracted from public-domain INSDC records (`prs`,
+  `lmo0737`, `lmo1118`, `ORF2819`, `ORF2110`; strand-corrected, `lmo0737` verified against
+  EGD-e) behind the `gapit.typing/2` scheme `doumith_serogroup` (95/95 floors, `prs`
+  control gene, cutoff 1.0 / margin 0.0). Rules follow Doumith's multiplex-PCR table
+  (IIa = 1/2a·3a, IIc = 1/2c·3c, IIb = 1/2b·3b·7, IVb = 4b·4d·4e) extended with Huang
+  2011's 4b variant (`IVb-v`, declared before `IVb` so an lmo0737-carrying 4b profile
+  resolves to the variant); fallback `untypeable (4a/4c, atypical profile, or non-Lm
+  Listeria)`. Materializes on first screen like every bundle (zero network);
+  `tests/test_lm_doumith.py` pins the synthetic marker-subset matrix, the control gate,
+  the two-stage golden, and the bundled integration — the bundled roster grows to six
+  (discovery, red-flag scan, `db list`, and `setupdb` pins updated). Uppercase gene ids
+  (`ORF2819`/`ORF2110`) now ride a shipped database, locking that build/screen/typing
+   carry them verbatim.
+
 ## [0.5.1] - 2026-10-03
 
 ### Added

{gapit-0.5.1 → gapit-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gapit
-Version: 0.5.1
+Version: 0.5.2
 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/
@@ -91,7 +91,7 @@ gapit screen --r1 ont_reads.fastq.gz --db ncbi --read-type map-ont --format json
 # Summarize report tables into a gene presence/absence matrix
 gapit summary *.tsv
 
-# Databases: five ship in-wheel and work instantly; the rest download from upstream on fetch
+# Databases: six ship in-wheel and work instantly; the rest download from upstream on fetch
 gapit db fetch all         # default set (card, vfdb)
 gapit db fetch ncbi
 gapit db list
@@ -111,8 +111,9 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 A database is a directory under the datadir, resolved from `$GAPIT_DATADIR`, then
 `~/.local/share/gapit/db` (override per call with `--datadir`). Twelve databases are built
 into the catalog; all of them download from upstream and build on `gapit db fetch` — with
-five content-provenance-audited exceptions that ship inside the package (`ecoli_dec` plus
-the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public domain / Apache-2.0 /
+six content-provenance-audited exceptions that ship inside the package (`ecoli_dec` and
+`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public
+domain / Apache-2.0 /
 BSD-3-Clause / MIT), materialized into the datadir on first use with zero network. Several
 upstream licenses (CARD's McMaster terms, VFDB's CC BY-NC, Kaptive's GPL-3.0) forbid
 redistribution inside an MIT-licensed distribution, so everything else is fetch-on-demand
@@ -204,6 +205,6 @@ guide, `CHANGELOG.md` the change history.
 
 gapit is MIT-licensed. It is a behavioral reimplementation of abricate (GPL-2.0) and
 copies no Perl code; abricate itself remains GPL-2.0. The only database content inside
-the package is the five audited, permissively licensed bundles under `src/gapit/data/dbs/`
+the package is the six audited, permissively licensed bundles under `src/gapit/data/dbs/`
 (public domain / Apache-2.0 / BSD-3-Clause / MIT); every other provider downloads from
 upstream at fetch time, under its own license (SPEC.md §9).

{gapit-0.5.1 → gapit-0.5.2}/README.md

@@ -61,7 +61,7 @@ gapit screen --r1 ont_reads.fastq.gz --db ncbi --read-type map-ont --format json
 # Summarize report tables into a gene presence/absence matrix
 gapit summary *.tsv
 
-# Databases: five ship in-wheel and work instantly; the rest download from upstream on fetch
+# Databases: six ship in-wheel and work instantly; the rest download from upstream on fetch
 gapit db fetch all         # default set (card, vfdb)
 gapit db fetch ncbi
 gapit db list
@@ -81,8 +81,9 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 A database is a directory under the datadir, resolved from `$GAPIT_DATADIR`, then
 `~/.local/share/gapit/db` (override per call with `--datadir`). Twelve databases are built
 into the catalog; all of them download from upstream and build on `gapit db fetch` — with
-five content-provenance-audited exceptions that ship inside the package (`ecoli_dec` plus
-the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public domain / Apache-2.0 /
+six content-provenance-audited exceptions that ship inside the package (`ecoli_dec` and
+`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public
+domain / Apache-2.0 /
 BSD-3-Clause / MIT), materialized into the datadir on first use with zero network. Several
 upstream licenses (CARD's McMaster terms, VFDB's CC BY-NC, Kaptive's GPL-3.0) forbid
 redistribution inside an MIT-licensed distribution, so everything else is fetch-on-demand
@@ -174,6 +175,6 @@ guide, `CHANGELOG.md` the change history.
 
 gapit is MIT-licensed. It is a behavioral reimplementation of abricate (GPL-2.0) and
 copies no Perl code; abricate itself remains GPL-2.0. The only database content inside
-the package is the five audited, permissively licensed bundles under `src/gapit/data/dbs/`
+the package is the six audited, permissively licensed bundles under `src/gapit/data/dbs/`
 (public domain / Apache-2.0 / BSD-3-Clause / MIT); every other provider downloads from
 upstream at fetch time, under its own license (SPEC.md §9).

{gapit-0.5.1 → gapit-0.5.2}/docs/agents.md

@@ -13,7 +13,7 @@ Version, as one JSON line:
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.1"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
 ```
 
 Output schemas. Ten documents are introspectable: `report`, `typing_result`, `reads`,

{gapit-0.5.1 → gapit-0.5.2}/docs/agents.zh.md

@@ -12,7 +12,7 @@ gapit 生来就是被程序驱动的。每个输出都以机器可读为设计
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.1"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
 ```
 
 输出 schema。十个文档可自省：`report`、`typing_result`、`reads`、`reads2`、`cluster`、

{gapit-0.5.1 → gapit-0.5.2}/docs/databases.md

@@ -44,6 +44,7 @@ vfdb	USTC (VFDB)	available	nucl	VFDB virulence factors (set A, nucleotide)
 victors	University of Chicago	available	nucl	Victors virulence factors
 ecoh	Holt lab (srst2)	bundled	nucl	E. coli O and H antigens (srst2 EcOH)
 ecoli_dec	gapit-curated (public-domain sources)	bundled	nucl	Diarrheagenic E. coli marker panel (GB 4789.6 + risk-monitoring designation)
+lm_doumith	gapit-curated (public-domain INSDC sources)	bundled	nucl	Listeria monocytogenes serogrouping (Doumith 2004)
 ncbi	NCBI	bundled	nucl	NCBI AMRFinderPlus (reference finder) curated AMR
 resfinder	DTU CGE	bundled	nucl	CGE ResFinder acquired resistance genes
 upec_expec_vf	FordeGenomics	bundled	nucl	UPEC/ExPEC virulence genes (FordeGenomics)
@@ -51,7 +52,7 @@ upec_expec_vf	FordeGenomics	bundled	nucl	UPEC/ExPEC virulence genes (FordeGenomi
 
 NAME is the database name you pass to `--db`; PROVIDER names the upstream maintainer
 organisation. STATUS reads `installed (N)` when `<datadir>/<name>/gapit-manifest.json`
-exists, with N the record count, otherwise `available`. The last five rows are the
+exists, with N the record count, otherwise `available`. The last six rows are the
 wheel-shipped [bundled](#bundled-databases-install-time-ready) databases, alphabetical:
 `bundled` before materialization, `installed (N)` after. Four of them (`ecoh`, `ncbi`,
 `resfinder`, `upec_expec_vf`) are also registry providers — such names render exactly
@@ -121,7 +122,7 @@ surface.) See [outputs.md](./outputs.md).
 
 Most databases download from upstream at `db fetch` time because their licenses forbid
 redistribution (see [Providers](#providers)). A small set of **bundled** databases ships
-inside the gapit wheel instead — five databases whose content provenance was audited
+inside the gapit wheel instead — six databases whose content provenance was audited
 record-by-record (public-domain sources, or Apache-2.0 / BSD-3-Clause / MIT panels;
 GPL and non-commercial content never rides the wheel). Nothing to download, nothing to
 accept: a bundled database works out of the box.
@@ -130,6 +131,7 @@ accept: a bundled database works out of the box.
 |---|---|---|---|
 | `ecoh` | E. coli O and H antigens (597 records, srst2 EcOH) | 2026-10-02 | — |
 | `ecoli_dec` | Diarrheagenic E. coli marker panel (17 records, GB 4789.6 + risk-monitoring designation) | 2026-10-02 | `gapit.typing/2` (schemes `gb4789_6`, `risk_monitoring`) |
+| `lm_doumith` | Listeria monocytogenes serogrouping (5 records, Doumith 2004 markers) | 2026-10-03 | `gapit.typing/2` (scheme `doumith_serogroup`) |
 | `ncbi` | NCBI AMRFinderPlus curated AMR (8373 records) | 2026-10-02 | — |
 | `resfinder` | CGE ResFinder acquired resistance genes (3206 records) | 2026-10-02 | — |
 | `upec_expec_vf` | UPEC/ExPEC virulence genes (77 records, FordeGenomics) | 2026-10-02 | — |
@@ -137,13 +139,15 @@ accept: a bundled database works out of the box.
 **License provenance.** Every `ecoli_dec` record was re-sourced from primary
 public-domain submissions (NCBI RefSeq/GenBank/DDBJ accessions, same alleles as the
 rightsholder panel); two VFDB-derived records found in the original panel were removed
-and replaced during the 2026-10 audit. The four provider snapshots (`ecoh`, `ncbi`,
-`resfinder`, `upec_expec_vf`) passed the 2026-10 content-level audit across **all**
-records: NCBI AMRFinderPlus content is public domain (US government work), the CGE
-ResFinder database is Apache-2.0, srst2's EcOH is BSD-3-Clause, and FordeGenomics'
-UPEC-ExPEC panel is MIT — all four permits redistribution inside the MIT-licensed wheel.
-A regression test pins that no `VF*` / `VFDB` / `ARO:` tags appear in any of the five
-bundles' headers.
+and replaced during the 2026-10 audit. The `lm_doumith` panel was extracted the same
+way from public-domain INSDC records (accessions in each header; reverse-complement
+markers strand-corrected, `lmo0737` verified 100% against EGD-e). The four provider
+snapshots (`ecoh`, `ncbi`, `resfinder`, `upec_expec_vf`) passed the 2026-10
+content-level audit across **all** records: NCBI AMRFinderPlus content is public
+domain (US government work), the CGE ResFinder database is Apache-2.0, srst2's EcOH
+is BSD-3-Clause, and FordeGenomics' UPEC-ExPEC panel is MIT — all four permits
+redistribution inside the MIT-licensed wheel. A regression test pins that no `VF*` /
+`VFDB` / `ARO:` tags appear in any of the six bundles' headers.
 
 **Snapshots are point-in-time.** Each snapshot's `sequences` file is byte-for-byte what
 `gapit db fetch <name>` produces from upstream on the snapshot date (a regression test
@@ -167,6 +171,36 @@ manifest exists. `db list` shows the database as `bundled` before that and
 `installed (17)` after — on all four listing surfaces (TSV, rich table, `--json`, MCP
 `db_list`).
 
+### Listeria serogrouping (`lm_doumith`)
+
+The typed bundle behind Listeria monocytogenes serogroup prediction: five markers —
+`prs`, `lmo0737`, `lmo1118`, `ORF2819`, `ORF2110` — screened with 95/95 identity and
+coverage floors and folded by the `doumith_serogroup` scheme into Doumith's multiplex-PCR
+groups (Doumith et al. 2004, J Clin Microbiol 42:3819), extended with the Huang 2011
+4b variant: `prs` gates the scheme as a genus-level control gene, `IIa` (1/2a or 3a),
+`IIc` (1/2c or 3c), `IIb` (1/2b, 3b or 7), `IVb` (4b, 4d or 4e), and `IVb-v` (the
+lmo0737-carrying 4b variant) — the same in-silico semantics as tools like LisSero.
+Designation runs through the two-stage pipeline: `gapit screen -o table.tsv --db
+lm_doumith`, then `gapit typing table.tsv`.
+
+Known limitations, carried on the calls as notes where relevant:
+
+- **4b/4d/4e are unresolvable at gene level** — the three serovars share every published
+  molecular marker; resolve by cgMLST or antisera.
+- **IVb-v is an emergent concern** — lmo0737 in an otherwise-4b profile (Huang 2011
+  "unusual 4b"; ST382/ST554 clones) is declared before IVb so the variant wins.
+- **EGD-e types as IIc** — the 1/2a reference genome carries lmo1118 and lands in IIc;
+  documented in Doumith 2004, not a tool artifact.
+- **Horizontal gene transfer cuts both ways** — the lineage-II lmo0737 cassette moves
+  between lineages, and rare HGT of the ORF markers can produce false IIb-looking
+  profiles; treat single-marker IIb calls in epidemiologically unlikely contexts with
+  care.
+- **`prs` is genus-level, not Lm-specific** — other Listeria species carry it; a prs+
+  isolate with no serogroup markers falls back rather than being called non-Listeria.
+
+The fallback call — `untypeable (4a/4c, atypical profile, or non-Lm Listeria)` — is the
+honest answer for everything the five markers cannot resolve.
+
 ## Checking database freshness
 
 `gapit db outdated` reports every installed database's age against the staleness
@@ -263,7 +297,7 @@ unknown `--db NAME` is a usage error (exit 2) listing what is installed.
 ## Providers
 
 Nineteen providers ship with gapit. Every one of them — `card` and `vfdb` included —
-downloads from its upstream source at fetch time: with the exception of the five
+downloads from its upstream source at fetch time: with the exception of the six
 audited, permissively licensed bundles above, nothing is bundled inside the package,
 because several upstream licenses (CARD's McMaster terms, VFDB's CC BY-NC, Kaptive's
 GPL-3.0) forbid redistribution inside an MIT-licensed distribution. The seven kaptive
@@ -410,6 +444,8 @@ $ gapit db install card.json \
   sequences             generated FASTA projection (gapit/v1 tagged headers)
   sequences.n*|p*       BLAST index built from sequences
   gapit-manifest.json   provenance sidecar, written last
+  typing.json           optional gapit.typing/1 or /2 scoring spec (typed dbs)
+  floors.json           optional gapit.floors/1 per-gene identity floors (reads mode)
 ```
 
 ### records.jsonl
@@ -452,7 +488,7 @@ versions. A real one, from the plasmidfinder database:
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.5.1"
+    "version": "0.5.2"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"
@@ -479,6 +515,31 @@ versions. A real one, from the plasmidfinder database:
 `records.jsonl` and the manifest are file contracts. They never appear on stdout and are
 not registered with `gapit schema`.
 
+### floors.json — per-gene identity floors
+
+An optional sidecar declaring a MINIMUM alignment identity (%) per gene for reads-mode
+presence (schema `gapit.floors/1`, introspect with `gapit schema floors`; see
+[reads.md](./reads.md#per-gene-identity-floors-gapitfloors1-database-side) for the
+screening semantics and the `pic` worked example):
+
+```json
+{"schema": "gapit.floors/1", "default": null, "genes": {"pic": 90.0}}
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `schema` | string | Always `gapit.floors/1` |
+| `default` | number or null | Floor for genes not listed in `genes` (`null` = no floor) |
+| `genes` | object | `{gene: minimum identity %}`, values in [0, 100] |
+
+The file's presence IS the flag — no manifest field, no CLI switch. A database without
+the sidecar screens byte-identically to before (the floors are a db-driven opt-in, not a
+CLI contract change), and the blastn contig path never reads them. Built-in via
+`db build --floors` (next sections), or drop the file into an existing db directory; it
+is validated at screening time too (malformed content fails with `FLOORS_MALFORMED`,
+exit 4). The bundled `ecoli_dec` ships `{"genes": {"pic": 90.0}}` — the SPATE-homolog
+false-positive fix.
+
 ## Header formats and compatibility
 
 gapit reads two header formats and detects them per record:
@@ -581,6 +642,27 @@ gene	accession	function
 syn_betalac	SYN-0001	ampicillin;cephalosporin
 ```
 
+### Per-gene identity floors (`--floors`)
+
+`--floors FILE` installs a `gapit.floors/1` document as the database's `floors.json`
+sidecar — the per-gene minimum alignment identity for reads-mode presence (see
+[reads.md](./reads.md#per-gene-identity-floors-gapitfloors1-database-side)). The
+document is validated before any artifact is written: every gene in `genes` must exist
+in the FASTA (`FLOORS_UNKNOWN_GENE`, exit 4 — a floor for a missing gene is silently
+dead safety config), values must lie in [0, 100] and the structure parse
+(`FLOORS_MALFORMED`, exit 4). The file is then copied in byte-identical; the file's
+presence is the flag (no manifest field changes). Gene builds only — a GBK/GFF cluster
+input rejects `--floors` as a usage error.
+
+```console
+$ cat my_floors.json
+{"schema": "gapit.floors/1", "default": null, "genes": {"syn_betalac": 95.0}}
+$ gapit db build tinyamr my_genes.fa --datadir ./db --tsv my_meta.tsv --floors my_floors.json
+{"db":"tinyamr","records":2,"dbtype":"nucl","destination":"/tmp/opencode/gapit-build-demo/db/tinyamr"}
+$ cat ./db/tinyamr/floors.json
+{"schema": "gapit.floors/1", "default": null, "genes": {"syn_betalac": 95.0}}
+```
+
 ### Rebuilding
 
 Like `db fetch`, an existing database is never overwritten silently:

{gapit-0.5.1 → gapit-0.5.2}/docs/databases.zh.md

@@ -44,6 +44,7 @@ vfdb	USTC (VFDB)	available	nucl	VFDB virulence factors (set A, nucleotide)
 victors	University of Chicago	available	nucl	Victors virulence factors
 ecoh	Holt lab (srst2)	bundled	nucl	E. coli O and H antigens (srst2 EcOH)
 ecoli_dec	gapit-curated (public-domain sources)	bundled	nucl	Diarrheagenic E. coli marker panel (GB 4789.6 + risk-monitoring designation)
+lm_doumith	gapit-curated (public-domain INSDC sources)	bundled	nucl	Listeria monocytogenes serogrouping (Doumith 2004)
 ncbi	NCBI	bundled	nucl	NCBI AMRFinderPlus (reference finder) curated AMR
 resfinder	DTU CGE	bundled	nucl	CGE ResFinder acquired resistance genes
 upec_expec_vf	FordeGenomics	bundled	nucl	UPEC/ExPEC virulence genes (FordeGenomics)
@@ -51,7 +52,7 @@ upec_expec_vf	FordeGenomics	bundled	nucl	UPEC/ExPEC virulence genes (FordeGenomi
 
 NAME 是传给 `--db` 的数据库名；PROVIDER 是上游维护机构。当
 `<datadir>/<name>/gapit-manifest.json` 存在时 STATUS 显示 `installed (N)`，N 是
-记录数，否则显示 `available`。最后五行是按名称排序的 wheel 内置数据库（见下文
+记录数，否则显示 `available`。最后六行是按名称排序的 wheel 内置数据库（见下文
 "内置数据库（即装即用）"一节）：物化前为 `bundled`，物化后为 `installed (N)`。
 其中四个（`ecoh`、`ncbi`、`resfinder`、`upec_expec_vf`）同时是注册表提供商 ——
 这类名字只渲染一次，位于内置区（绝不会重复出现一条注册表 `available` 行），
@@ -117,7 +118,7 @@ abricate `--list` 的逐字节一致性。）见 [outputs.md](./outputs.md)。
 ## 内置数据库（即装即用）
 
 大多数数据库在 `db fetch` 时才从上游下载，因为许可证禁止再分发（见"提供商"一节）。
-少数**内置**数据库随 gapit wheel 一起发布 —— 共五个，其内容经过逐条记录的来源
+少数**内置**数据库随 gapit wheel 一起发布 —— 共六个，其内容经过逐条记录的来源
 审计（公共领域来源，或 Apache-2.0 / BSD-3-Clause / MIT 宽松许可面板；GPL 与
 非商业许可内容绝不随 wheel 分发）。无需下载、无需确认：内置数据库开箱即用。
 
@@ -125,17 +126,20 @@ abricate `--list` 的逐字节一致性。）见 [outputs.md](./outputs.md)。
 |---|---|---|---|
 | `ecoh` | 大肠杆菌 O/H 抗原基因（597 条记录，srst2 EcOH） | 2026-10-02 | — |
 | `ecoli_dec` | 致腹泻大肠杆菌标志基因面板（17 条记录，GB 4789.6 + 风险监测判定） | 2026-10-02 | `gapit.typing/2`（`gb4789_6`、`risk_monitoring` 双方案） |
+| `lm_doumith` | 单核细胞增生李斯特菌血清群分型（5 条记录，Doumith 2004 标记） | 2026-10-03 | `gapit.typing/2`（方案 `doumith_serogroup`） |
 | `ncbi` | NCBI AMRFinderPlus 精选 AMR（8373 条记录） | 2026-10-02 | — |
 | `resfinder` | CGE ResFinder 获得性耐药基因（3206 条记录） | 2026-10-02 | — |
 | `upec_expec_vf` | UPEC/ExPEC 毒力基因（77 条记录，FordeGenomics） | 2026-10-02 | — |
 
 **许可证来源声明。** `ecoli_dec` 的每条记录都取自公共领域的一级提交（NCBI
 RefSeq/GenBank/DDBJ 收录号，与权利方面板等位相同）；2026-10 审计中发现原面板里
-混入的两条 VFDB 来源记录已被移除并替换。四个提供商快照（`ecoh`、`ncbi`、
-`resfinder`、`upec_expec_vf`）通过了 2026-10 对**全部**记录的内容级审计：
+混入的两条 VFDB 来源记录已被移除并替换。`lm_doumith` 面板以同样方式取自公共领域
+的 INSDC 记录（收录号见每条头部；反向互补标记已做链向校正，`lmo0737` 经与 EGD-e
+比对验证 100% 一致）。四个提供商快照（`ecoh`、`ncbi`、`resfinder`、
+`upec_expec_vf`）通过了 2026-10 对**全部**记录的内容级审计：
 NCBI AMRFinderPlus 内容属公共领域（美国政府作品），CGE ResFinder 数据库为
 Apache-2.0，srst2 的 EcOH 为 BSD-3-Clause，FordeGenomics 的 UPEC-ExPEC 面板为
-MIT —— 四者均允许随 MIT 许可的 wheel 再分发。回归测试锁定了五个内置库的头部
+MIT —— 四者均允许随 MIT 许可的 wheel 再分发。回归测试锁定了六个内置库的头部
 不出现任何 `VF*` / `VFDB` / `ARO:` 标签。
 
 **快照是一个时间点。** 每个快照的 `sequences` 文件与快照当日 `gapit db fetch
@@ -156,6 +160,35 @@ ecoli_dec (17 records) into <datadir>`，`--quiet` 可静默），随后走标
 `bundled`、物化后显示 `installed (17)` —— 四个列表入口（TSV、rich 表格、
 `--json`、MCP `db_list`）一致。
 
+### 李斯特菌血清群分型（`lm_doumith`）
+
+用于单核细胞增生李斯特菌（Listeria monocytogenes）血清群预测的分型内置库：
+五个标记 —— `prs`、`lmo0737`、`lmo1118`、`ORF2819`、`ORF2110` —— 以 95/95
+的序列一致性与覆盖度阈值筛检，由 `doumith_serogroup` 方案折算为 Doumith 多重
+PCR 分群（Doumith 等 2004，J Clin Microbiol 42:3819），并扩展了 Huang 2011 的
+4b 变体：`prs` 作为属级控制基因把关整个方案，`IIa`（1/2a 或 3a）、`IIc`
+（1/2c 或 3c）、`IIb`（1/2b、3b 或 7）、`IVb`（4b、4d 或 4e）与 `IVb-v`（携带
+lmo0737 的 4b 变体）—— 与 LisSero 等工具的 in-silico 语义一致。判定走两阶段
+管线：`gapit screen -o table.tsv --db lm_doumith`，然后 `gapit typing
+table.tsv`。
+
+已知的局限（相关处以 notes 形式随判定输出）：
+
+- **4b/4d/4e 在基因层面无法区分** —— 三个血清型共享所有已发表的分子标记；
+  需用 cgMLST 或血清学进一步判定。
+- **IVb-v 是新出现的关注克隆** —— 4b 谱面中检出 lmo0737（Huang 2011
+  "unusual 4b"；ST382/ST554 克隆）时，该规则先于 IVb 声明，变体优先胜出。
+- **EGD-e 判为 IIc** —— 1/2a 参考基因组携带 lmo1118 而落入 IIc；这是 Doumith
+  2004 原文记载的现象，不是工具假象。
+- **水平基因转移是双向陷阱** —— 谱系 II 的 lmo0737 盒会在谱系间移动，罕见的
+  ORF 标记水平转移也可能造成貌似 IIb 的假谱面；在流行病学上不太可能的语境里，
+  单标记 IIb 判定需谨慎对待。
+- **`prs` 是属级基因，并非 Lm 特异** —— 其他李斯特菌物种也携带它；prs 阳性但
+  无任何血清群标记的分离株回退为 fallback，而不是被判为"非李斯特菌"。
+
+回退判定 —— `untypeable (4a/4c, atypical profile, or non-Lm Listeria)` ——
+是这五个标记无法给出答案时的诚实输出。
+
 ## 检查数据库新鲜度
 
 `gapit db outdated` 报告每个已安装数据库相对于过期阈值的年龄。对装满的数据
@@ -251,7 +284,7 @@ $ gapit db search "tet(M)" --field gene --exact --json | head -1
 ## 提供商
 
 gapit 自带十九个提供商。每一个——包括 `card` 和 `vfdb`——都在抓取时从上游下载：
-除上文五个通过审计、宽松许可的内置库之外，包里不内置任何内容，因为多家上游许可
+除上文六个通过审计、宽松许可的内置库之外，包里不内置任何内容，因为多家上游许可
 （CARD 的 McMaster 条款、VFDB 的 CC BY-NC、
 Kaptive 的 GPL-3.0）禁止随 MIT 许可的发行版再分发。七个 kaptive 提供商是**基因簇**
 数据库（抓取时经基因簇管线构建，见下文 Kaptive 提供商一节）。
@@ -390,6 +423,8 @@ $ gapit db install card.json \
   sequences             generated FASTA projection (gapit/v1 tagged headers)
   sequences.n*|p*       BLAST index built from sequences
   gapit-manifest.json   provenance sidecar, written last
+  typing.json           可选的 gapit.typing/1 或 /2 评分规范（带分型的数据库）
+  floors.json           可选的 gapit.floors/1 按基因一致性下限（reads 模式）
 ```
 
 ### records.jsonl
@@ -431,7 +466,7 @@ manifest，来自 plasmidfinder 数据库：
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.5.1"
+    "version": "0.5.2"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"
@@ -458,6 +493,28 @@ manifest，来自 plasmidfinder 数据库：
 `records.jsonl` 和 manifest 是文件契约。它们从不出现在 stdout，也未注册到
 `gapit schema`。
 
+### floors.json — 按基因设置一致性下限
+
+一个可选边车，为 reads 模式的存在判定声明逐基因的最小比对一致性（%）（schema 为
+`gapit.floors/1`，用 `gapit schema floors` 内省；筛查语义与 `pic` 实战示例见
+[reads.zh.md](./reads.zh.md#按基因设置一致性下限gapitfloors1数据库侧)）：
+
+```json
+{"schema": "gapit.floors/1", "default": null, "genes": {"pic": 90.0}}
+```
+
+| 字段 | 类型 | 含义 |
+|---|---|---|
+| `schema` | string | 恒为 `gapit.floors/1` |
+| `default` | number 或 null | 未在 `genes` 中列出的基因的下限（`null` = 无下限） |
+| `genes` | object | `{基因: 最小一致性 %}`，取值在 [0, 100] 内 |
+
+文件的存在本身就是开关——没有 manifest 字段，也没有 CLI 开关。不带边车的数据库
+输出与之前逐字节一致（下限是数据库驱动的可选开启，不是 CLI 契约变更）；blastn
+contig 路径从不读取它们。通过 `db build --floors` 安装（见下节），或把文件直接放
+进既有数据库目录；筛查时同样会校验（内容损坏以 `FLOORS_MALFORMED` 失败，exit 4）。
+内置的 `ecoli_dec` 携带 `{"genes": {"pic": 90.0}}`——SPATE 同源假阳性的修复。
+
 ## 表头格式与兼容性
 
 gapit 读取两种表头格式，逐记录检测：
@@ -552,6 +609,26 @@ gene	accession	function
 syn_betalac	SYN-0001	ampicillin;cephalosporin
 ```
 
+### 按基因一致性下限（`--floors`）
+
+`--floors FILE` 把一份 `gapit.floors/1` 文档安装为数据库的 `floors.json` 边车——
+reads 模式存在判定的逐基因最小比对一致性（见
+[reads.zh.md](./reads.zh.md#按基因设置一致性下限gapitfloors1数据库侧)）。文档在
+任何产物落盘前先校验：`genes` 里的每个基因必须存在于 FASTA
+（`FLOORS_UNKNOWN_GENE`，exit 4——给缺失基因设下限是静默失效的安全配置），取值必
+须在 [0, 100] 内、结构必须可解析（`FLOORS_MALFORMED`，exit 4）。随后文件原样拷入；
+文件的存在本身就是开关（manifest 字段不变）。仅限基因数据库——GBK/GFF 簇输入对
+`--floors` 报用法错误。
+
+```console
+$ cat my_floors.json
+{"schema": "gapit.floors/1", "default": null, "genes": {"syn_betalac": 95.0}}
+$ gapit db build tinyamr my_genes.fa --datadir ./db --tsv my_meta.tsv --floors my_floors.json
+{"db":"tinyamr","records":2,"dbtype":"nucl","destination":"/tmp/opencode/gapit-build-demo/db/tinyamr"}
+$ cat ./db/tinyamr/floors.json
+{"schema": "gapit.floors/1", "default": null, "genes": {"syn_betalac": 95.0}}
+```
+
 ### 重建
 
 与 `db fetch` 一样，已有的数据库绝不被静默覆盖：

{gapit-0.5.1 → gapit-0.5.2}/docs/installation.md

@@ -45,9 +45,9 @@ gapit --version
 
 ```console
 $ gapit --version
-gapit 0.5.1
+gapit 0.5.2
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.1"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
 ```
 
 ## External binaries

{gapit-0.5.1 → gapit-0.5.2}/docs/installation.zh.md

@@ -44,9 +44,9 @@ gapit --version
 
 ```console
 $ gapit --version
-gapit 0.5.1
+gapit 0.5.2
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.1"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.2"}
 ```
 
 ## 外部二进制

{gapit-0.5.1 → gapit-0.5.2}/docs/mcp.md

@@ -94,7 +94,7 @@ EOF
 Response line 1, verbatim:
 
 ```text
-{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.5.1"}}}
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.5.2"}}}
 ```
 
 Response line 2 (real output, elided in the middle; each tool carries its full
@@ -117,7 +117,7 @@ the same run):
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.5.1"},
+  "tool": {"name": "gapit", "version": "0.5.2"},
   "created_at": "2026-09-19T01:15:44Z",
   "params": {"db": "tinyamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [
@@ -173,7 +173,7 @@ the same run):
 ```json
 {
   "schema": "gapit.reads/1",
-  "tool": {"name": "gapit", "version": "0.5.1"},
+  "tool": {"name": "gapit", "version": "0.5.2"},
   "created_at": "2026-09-22T00:07:35Z",
   "params": {
     "db": "tinyreads",
@@ -248,7 +248,7 @@ hit is the gene the agent just built the database from (real output):
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.5.1"},
+  "tool": {"name": "gapit", "version": "0.5.2"},
   "created_at": "2026-09-20T13:38:39Z",
   "params": {"db": "myamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [

{gapit-0.5.1 → gapit-0.5.2}/docs/mcp.zh.md

@@ -88,7 +88,7 @@ EOF
 响应第 1 行，原样：
 
 ```text
-{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.5.1"}}}
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"gapit","version":"0.5.2"}}}
 ```
 
 响应第 2 行（真实输出，中段省略；每个工具携带完整的 `inputSchema`）：
@@ -109,7 +109,7 @@ EOF
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.5.1"},
+  "tool": {"name": "gapit", "version": "0.5.2"},
   "created_at": "2026-09-19T01:15:44Z",
   "params": {"db": "tinyamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [
@@ -163,7 +163,7 @@ EOF
 ```json
 {
   "schema": "gapit.reads/1",
-  "tool": {"name": "gapit", "version": "0.5.1"},
+  "tool": {"name": "gapit", "version": "0.5.2"},
   "created_at": "2026-09-22T00:07:35Z",
   "params": {
     "db": "tinyreads",
@@ -236,7 +236,7 @@ export GAPIT_DATADIR=/tmp/gapit-mcp-demo/datadir
 ```json
 {
   "schema": "gapit.report/1",
-  "tool": {"name": "gapit", "version": "0.5.1"},
+  "tool": {"name": "gapit", "version": "0.5.2"},
   "created_at": "2026-09-20T13:38:39Z",
   "params": {"db": "myamr", "minid": 80.0, "mincov": 80.0, "threads": 1},
   "files": [