gapit 0.5.4__tar.gz → 0.5.6__tar.gz

{gapit-0.5.4 → gapit-0.5.6}/AGENTS.md

@@ -31,7 +31,7 @@ are we?** A modern, typed, testable Python tool that:
   native (`seqconvert.py`); `any2fasta` is no longer a gapit dependency anywhere — the
   differential-validation oracle binary arrives transitively via abricate in the opt-in
   `parity` pixi env (prepend `.pixi/envs/parity/bin` to PATH for the differential test).
-- **Core libraries**: `typer` (CLI), `pydantic` v2 (data models / JSON schema), `rich` (terminal
+- **Core libraries**: `click` (CLI), `pydantic` v2 (data models / JSON schema), `rich` (terminal
   output). No biopython — FASTA I/O is a small streaming parser we own.
 - **Quality gates**: `ruff` (lint + format), `basedpyright` (strict mode), `pytest`.
 
@@ -89,7 +89,9 @@ gapit/
 │   ├── typing_results.py # typing evaluation-result models (PhenotypeDetail, SchemeCall)
 │   ├── typing_engine.py # typing evaluation, cluster path: rule scoring → phenotype call + breakdown
 │   ├── typing_gene.py   # typing evaluation, gene path (DEC markers): hits → per-scheme report phenotypes
-│   ├── bundled.py       # bundled databases: discovery + materialize-into-datadir (public-domain panels)
+│   ├── typing_cluster2.py # typing evaluation, multi-scheme cluster path: report → per-scheme phenotypes map
+│   ├── bundled.py       # bundled databases: discovery + kind-forked materialize-into-datadir
+│   ├── bundled_cluster.py # cluster-bundle materialization: committed artifacts → cluster build
 │   ├── blast.py         # blastn invocation + tabular output parsing
 │   ├── hits.py          # Hit model, identity/coverage computation, filtering, dedup
 │   ├── fragments.py     # opt-in --merge-fragments cross-contig gene-fragment merging
@@ -125,14 +127,16 @@ gapit/
 │   │   ├── reads_json.py # versioned JSON (gapit.reads/1, gapit.reads/2)
 │   │   ├── md.py        # Markdown (human + agent readable, YAML frontmatter)
 │   │   ├── cluster.py   # gapit.cluster/1 models + JSON/TSV renderers (typed variant)
-│   │   ├── cluster_md.py # gapit.cluster/1 Markdown renderer (Phenotype column when typed)
+│   │   ├── cluster2.py  # gapit.cluster/2 models + JSON/TSV renderers (multi-scheme phenotypes map)
+│   │   ├── cluster_md.py # gapit.cluster/1 + /2 Markdown renderers (Phenotype(s) column when typed)
 │   │   ├── typing_result.py # gapit.typing_result/1 models + TSV/JSON/MD renderers
 │   │   ├── schemas.py   # registered output models behind `gapit schema`
 │   │   └── summary.py   # summary matrix renderers (TSV/CSV/JSON/MD)
 │   ├── providers/       # 19 database provider modules (12 gene + 7 kaptive cluster) + cluster_common.py + common.py
 │   └── py.typed
 ├── scripts/
-│   └── cluster_calibration.py # developer calibration harness for typed cluster dbs
+│   ├── cluster_calibration.py # developer calibration harness for typed cluster dbs (single-scheme split dbs)
+│   └── generate_vp_typing.py # regenerates the committed vp_ok typing asset from the vpautils OAgc/CPSgc GBKs
 └── tests/
     ├── data/            # tiny synthetic db + contigs + reads (fast, offline)
     ├── golden/          # expected outputs incl. abricate reference TSVs
@@ -162,7 +166,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 | floors`). Keys are snake_case,
+  `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.
 - **Markdown**: YAML frontmatter (tool version, db, params, ISO-8601 UTC timestamp) + tables a
@@ -181,15 +185,24 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
   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 six
   content-provenance-audited bundles under `src/gapit/data/dbs/` — the public-domain
-  `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),
+  `ecoli_dec` and `lm_doumith` panels, three permissively licensed provider snapshots
+  (`ncbi` public domain, `resfinder` Apache-2.0, `ecoh` BSD-3-Clause), and the MIT
+  `vp_ok` typed cluster snapshot — a pure built-in in the ecoli_dec/lm_doumith pattern: no
+  provider module, no `db fetch`; vpautils OAgc+CPSgc merged content, MIT
+  (GPL/NC content is never bundled) — materialized into the datadir on first use via
+  `bundled.py` (gene bundles replay the gene pipeline, the cluster bundle the cluster
+  pipeline), with `db fetch <name>` the fresh-upstream refresh path for the
+  provider-backed bundled names (ecoh, ncbi, resfinder); what may
+  ride the wheel is governed by the §6 policy),
   database listing,
   records.jsonl gene search, staleness
   report, custom FASTA→native-db build, GBK/GFF→cluster-db build (`--typing` installs a
-  validated `gapit.typing/1` or `/2` spec on either kind), the four download-on-fetch kaptive cluster providers
-  (GPL content, never bundled), and SHA256-verified local-file install.
+  validated `gapit.typing/1` or `/2` spec on either kind), the seven download-on-fetch
+  kaptive cluster providers (four upstream repos, GPL content, never bundled), the
+  MIT-licensed `vp_ok` typed cluster bundle (OAgc+CPSgc merged: the committed typing asset
+  installs a 3-scheme `gapit.typing/2` doc so one screen renders `gapit.cluster/2` with
+  the composed `O:K` serotype, zero network from first install), and SHA256-verified
+  local-file install.
 - **MCP** `[gapit-extension]`: `gapit mcp` / `gapit-mcp` stdio server exposing nine tools:
   read-only `screen` (incl. `aligner minimap2` assembly survey), `screen_reads` (FASTQ via
   minimap2), `summary`, `schema`, `db_list`, `db_search`, `db_outdated`, plus the datadir-mutating
@@ -199,7 +212,38 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
 - **Self-description**: `gapit --version --json`, `gapit db list --json`, `gapit schema` — an agent
   must be able to discover everything without reading docs.
 
-## 6. Testing strategy
+## 6. Bundled-database policy (what may ride the wheel)
+
+`src/gapit/data/dbs/` is the sanctioned home for license-clean content shipped inside the
+wheel: a directory qualifies by carrying `sequences` + `bundled.json` (auto-discovered by
+`gapit.bundled`; `kind: cluster` in the metadata additionally requires `features.json`).
+Materialization is kind-aware: gene bundles replay the gene-build pipeline, cluster
+bundles the cluster-build pipeline (`bundled_cluster.py` rebuilds from the committed
+locus FASTA + resolved feature table — gene ids stay snapshot-resolved, the typing spec
+re-validates against them).
+Bundling stays the exception, not the pattern: the other providers fetch from upstream at
+`db fetch` time. Every new bundle passes two gates, in order:
+
+1. **License gate** (hard, independent of location): only public-domain or permissive
+   content (PD, Apache-2.0, BSD, MIT), provenance-audited. GPL (Kaptive) and
+   non-commercial terms (CARD, VFDB) never ride the MIT distribution — moving files
+   cannot fix this.
+2. **Size gate** (budget): the bundled-root total stays ≤ 30 MiB, mechanically enforced by
+   `tests/test_bundled.py` (every `pip install gapit` re-downloads all bundles; PyPI caps
+   one file at 100 MiB).
+
+Growth tiers past the budget — split rather than inflate the ceiling:
+
+- **≤ 30 MiB**: keep adding to `src/gapit/data/dbs/`. Atomic data-with-code versioning,
+  zero packaging machinery; the abricate precedent ships 16 MiB in-package.
+- **30–100 MiB**: split a separate `gapit-data` wheel with its own version (the
+  `spacy[lookups]` → `spacy-lookups-data` pattern), pulled via a `gapit[datasets]` extra;
+  `bundled_databases()` grows a second discovery root.
+- **> 100 MiB, or fast-moving upstreams**: fetch-on-demand only. `db fetch` is the
+  freshness path for every bundled name anyway — snapshots are point-in-time, and each
+  bundled upstream refresh would otherwise force a wheel release.
+
+## 7. Testing strategy
 
 - **Unit**: pure functions (coverage %, merge rules, header parsing) — no I/O beyond `tests/data`.
 - **Golden files**: fixed tiny db + fixed contigs → expected TSV/JSON/MD committed; update the
@@ -212,7 +256,7 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
 - Full suite + CI matrix 3.11/3.13/3.14; parity byte-diff is opt-in via the `parity` pixi env.
   Offline tests stay fast.
 
-## 7. Domain knowledge (abridged; full detail in SPEC.md)
+## 8. Domain knowledge (abridged; full detail in SPEC.md)
 
 - A **database** is a directory `<datadir>/<dbname>/sequences`: a nucleotide FASTA whose headers
   encode `>~~~GENE~~~PRODUCT` (and accession / resistance metadata depending on the source db).
@@ -234,13 +278,13 @@ This is what distinguishes gapit from abricate. Treat it as a public API.
   surfaces (reads, cluster, typing) follow their own documented contracts and may diverge from
   abricate by design.
 
-## 8. Git & workflow
+## 9. Git & workflow
 
 - Conventional Commits (`feat:`, `fix:`, `test:`, `docs:`, `refactor:`).
 - Never commit unless the user explicitly asks. Never force-push.
 - `PLAN.md` tracks phases; update it when scope changes, not retroactively.
 
-## 9. For agents working in this repo
+## 10. For agents working in this repo
 
 1. Read `SPEC.md` before touching `blast.py`, `hits.py`, or `minimap.py`.
 2. Public contract changes (JSON schema, exit codes, CLI flags) require a schema version bump and

{gapit-0.5.4 → gapit-0.5.6}/CHANGELOG.md

@@ -5,6 +5,70 @@ 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.6] - 2026-10-20
+
+### Changed
+
+- **`gapit.cluster/2` TSV/CSV reshaped: per-scheme winner evidence replaces the packed
+  PHENOTYPES cell and the global-best columns.** The header now derives from the typing
+  document: each compose scheme's value column renders first (`SEROTYPE` — the headline
+  answer leads), then every non-compose scheme carries its call plus the winning locus's
+  own evidence (`O_GROUP, O_LOCUS, O_COVERAGE, O_IDENTITY, O_PRESENT, O_PARTIAL,
+  O_MISSING` — the `o_group` evidence prefix shortens to `O`); `-` cells where no winner
+  exists. The misleading `BEST_LOCUS`/global-evidence columns are gone (they described
+  whichever locus of either family ranked first), and the JSON `phenotypes` map gains
+  additive `winner_*` fields (`winner_locus`, `winner_coverage_pct`, `winner_identity_pct`,
+  `winner_present`, `winner_partial`, `winner_missing`). Amendment of a contract shipped
+  in 0.5.5 days earlier with no downstream adoption; `/1` and `gapit.typing_result/1`
+  outputs are byte-frozen.
+
+## [0.5.5] - 2026-10-13
+
+### Added
+
+- **`gapit.cluster/2` — multi-scheme cluster output.** A cluster database whose typing
+  document holds more than one scheme now renders `gapit.cluster/2`: same body as /1,
+  `best` drops its phenotype fields, and each file gains `phenotypes: {scheme: SchemeCall}`
+  in document order — compose schemes (e.g. `"{o_group}:{k_group}"`) render from sibling
+  calls, and schemes evaluate even without a best call. TSV/CSV swap PHENOTYPE for a packed
+  PHENOTYPES column (`o_group=O3;k_group=K6;serotype=O3:K6`); MD mirrors it plus per-scheme
+  lines. Untyped and single-scheme databases keep byte-identical `gapit.cluster/1`.
+  /2 builds guarantee globally-unique gene ids (collision-aware
+  /gene→locus_tag→`locus:id@start` resolution at build time). Registered as
+  `gapit schema cluster2`.
+
+- **Bundled `vp_ok`: V. parahaemolyticus O:K serotyping, one scan.** The wheel now ships a
+  typed cluster bundle (six bundles total; ~7.9 MiB committed artifacts) built from the
+  vpasero OAgc/CPSgc reference loci (195 loci, MIT): `pip install gapit` →
+  `gapit screen genome.fna --db vp_ok` auto-materializes with zero network and renders
+  `gapit.cluster/2` with `o_group`, `k_group`, and the composed `O:K` serotype
+  (RIMD 2210633 → O3:K6). Kind-aware cluster-bundle materialization replays the same
+  cluster build entry `db build` uses — bundle ≡ build, byte-identical `sequences` +
+  `features.json` (regression-locked). Coverage floors calibrated over a 14,801-genome
+  corpus against Kaptive-style references: 90% coverage / 95% identity (O agreement
+  89.08%, K 82.91%, true cross-calls 29/29,602 calls); the HARD-locus matrix is committed
+  (`scripts/vp_rules_matrix.tsv`) and `scripts/generate_vp_typing.py` regenerates the
+  typing asset reproducibly.
+
+- **Bundled-database policy (AGENTS.md §6) with a mechanical 30 MiB budget guard** —
+  license gate (PD/Apache/BSD/MIT only) + size gate enforced by `tests/test_bundled.py`;
+  growth tiers documented (split a `gapit-data` wheel past the budget rather than inflate).
+
+### Changed
+
+- **CLI migrated from typer to click 8.5.** Same flags, exit codes, envelopes, and stdout
+  bytes on every gapit-owned surface; a net dependency diet (typer/shellingham/annotated-doc
+  out, click in). Framework-rendered help is now plain click, and shell completion moved
+  from typer's `--install-completion`/`--show-completion` flags to the
+  `_GAPIT_COMPLETE=bash_source` env-var activation model (bash/zsh/fish; docs updated).
+
+- **`gapit db list`: DESCRIPTION now precedes PROVIDER** (TSV and the rich table), and the
+  rich table renders with uniformly thin rule lines (was a heavy header separator).
+
+- **`upec_expec_vf` no longer rides the wheel** — it returns to pure fetch-on-demand in
+  the provider catalog; the sanctioned bundled set is `ecoh`, `ecoli_dec`, `lm_doumith`,
+  `ncbi`, `resfinder`, `vp_ok`.
+
 ## [0.5.4] - 2026-10-03
 
 ### Added

{gapit-0.5.4 → gapit-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: gapit
-Version: 0.5.4
+Version: 0.5.6
 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/
@@ -23,9 +23,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: >=3.11
+Requires-Dist: click>=8.2
 Requires-Dist: pydantic>=2.7
 Requires-Dist: rich>=13
-Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
 
 # gapit
@@ -111,19 +111,22 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 ## Databases
 
 A database is a directory under the datadir, resolved from `$GAPIT_DATADIR`, then
-`~/.local/share/gapit/db` (override per call with `--datadir`). Twenty-one databases are
-built into the catalog — twelve gene providers, seven kaptive cluster providers, and the
-two typed bundles `ecoli_dec` and `lm_doumith`. All of them build on `gapit db fetch`,
+`~/.local/share/gapit/db` (override per call with `--datadir`). Twenty-two databases are
+built into the catalog — twelve gene providers, seven kaptive cluster providers, and
+three typed bundles (`ecoli_dec`, `lm_doumith`, and the cluster-kind `vp_ok`). Every
+provider builds on `gapit db fetch`,
 which downloads from upstream — and six content-provenance-audited ones also ship inside
 the package (`ecoli_dec` and
-`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public
+`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh` snapshots — public
 domain / Apache-2.0 /
-BSD-3-Clause / MIT), materialized into the datadir on first use with zero network; the
+BSD-3-Clause / MIT — and the MIT typed-cluster snapshot `vp_ok`), materialized into the
+datadir on first use with zero network; the
 bundled `ecoli_dec` additionally carries per-gene identity floors (`floors.json`, `pic`
 at 90%) that reads mode applies before presence calls. 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
-— and `db fetch <name>` always refreshes a bundled name from the latest upstream.
+— and `db fetch <name>` refreshes the provider-backed bundled names (`ecoh`, `ncbi`,
+`resfinder`) from the latest upstream.
 
 | Name | Content | dbtype |
 |---|---|---|
@@ -141,6 +144,7 @@ redistribution inside an MIT-licensed distribution, so everything else is fetch-
 | `bacmet2` | BacMet2 biocide/resistance genes (protein) | prot |
 | `victors` | Victors virulence factors | nucl |
 | `upec_expec_vf` | UPEC/ExPEC virulence genes | nucl |
+| `vp_ok` | V. parahaemolyticus O and K antigen loci (OAgc/CPSgc, vpasero; cluster, MIT, one-scan O:K serotype) | nucl |
 
 gapit also reads datadirs built by abricate itself (legacy `~~~` headers). The reverse
 does not hold: gapit-native databases use the `gapit/v1` header format (see SPEC.md §11),
@@ -150,7 +154,14 @@ Gene **cluster** databases are a second kind: `gapit db build NAME loci.gbk|gff3
 `kind: cluster` db (locus calls via minimap2, optional `--typing FILE` phenotype scoring),
 and the seven Kaptive cluster databases (kpsc_k, kpsc_o, kosc_k, kosc_o, ab_k, ab_o,
 ecoli_kps) fetch the Kaptive antigen-locus references at install time (GPL-3.0 content, so
-nothing is bundled — cite Kaptive/Wyres et al. 2020 for results). `gapit db list --json`
+nothing is bundled — cite Kaptive/Wyres et al. 2020 for results). The typed cluster
+bundle `vp_ok`
+merges the vpasero OAgc + CPSgc references (MIT) into one bundled db — a pure built-in in
+the ecoli_dec/lm_doumith pattern, no `db fetch` — where a single
+`gapit screen --db vp_ok` renders gapit.cluster/2 with `o_group`, `k_group`, and the
+composed `serotype` O:K call (RIMD 2210633 → O3:K6), working straight after
+`pip install gapit` with zero network.
+`gapit db list --json`
 surfaces each provider's content license where one is pinned.
 
 ## Output contract

{gapit-0.5.4 → gapit-0.5.6}/PLAN.md

@@ -226,6 +226,22 @@ consumes abricate-built datadirs.
   seven-column TSV/MD table. Cluster typing stays integrated in `gapit screen`
   (`TYPING_CLUSTER_DB` on the command). No typing MCP tool yet (future work). Parity
   15/15 + summary 6/6 unchanged; no version bump.
+> **`gapit.cluster/2` — multi-scheme cluster output (2026-10-12):** a cluster db whose
+> typing doc holds more than one scheme (compose allowed) renders `gapit.cluster/2`:
+> same body as /1, `best` drops its phenotype fields, each file gains
+> `phenotypes: {scheme: SchemeCall}` in doc order (compose schemes render from sibling
+> calls via the shared decision layer; schemes evaluate even without a best call).
+> TSV/CSV swap PHENOTYPE for a packed `PHENOTYPES` column (`o_group=O3;k_group=K6`);
+> MD mirrors it plus per-scheme lines. Untyped and single-scheme dbs keep byte-identical
+> `gapit.cluster/1`. /2 builds guarantee globally-unique gene ids (collision-aware
+> /gene→locus_tag→`locus:id@start` resolution at build time). Registered as
+> `gapit schema cluster2`. The vp_ok cookbook now installs as one merged db.
+> **Amended (2026-10-20, pre-adoption):** the packed `PHENOTYPES` cell and the
+> global-best columns are replaced by document-derived per-scheme columns — compose
+> value columns first (`SEROTYPE`), then each scheme's call + winner-locus evidence
+> (`O_LOCUS/O_COVERAGE/...`); JSON `phenotypes` gains additive `winner_*` fields. /2
+> shipped in 0.5.5 days earlier with no downstream adoption; /1 and typing_result/1
+> stay byte-frozen.
 
 ## Milestones
 

{gapit-0.5.4 → gapit-0.5.6}/README.md

@@ -81,19 +81,22 @@ presence defaults to 90% alignment breadth (`--min-breadth 90`).
 ## Databases
 
 A database is a directory under the datadir, resolved from `$GAPIT_DATADIR`, then
-`~/.local/share/gapit/db` (override per call with `--datadir`). Twenty-one databases are
-built into the catalog — twelve gene providers, seven kaptive cluster providers, and the
-two typed bundles `ecoli_dec` and `lm_doumith`. All of them build on `gapit db fetch`,
+`~/.local/share/gapit/db` (override per call with `--datadir`). Twenty-two databases are
+built into the catalog — twelve gene providers, seven kaptive cluster providers, and
+three typed bundles (`ecoli_dec`, `lm_doumith`, and the cluster-kind `vp_ok`). Every
+provider builds on `gapit db fetch`,
 which downloads from upstream — and six content-provenance-audited ones also ship inside
 the package (`ecoli_dec` and
-`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh`, `upec_expec_vf` snapshots: public
+`lm_doumith` plus the `ncbi`, `resfinder`, `ecoh` snapshots — public
 domain / Apache-2.0 /
-BSD-3-Clause / MIT), materialized into the datadir on first use with zero network; the
+BSD-3-Clause / MIT — and the MIT typed-cluster snapshot `vp_ok`), materialized into the
+datadir on first use with zero network; the
 bundled `ecoli_dec` additionally carries per-gene identity floors (`floors.json`, `pic`
 at 90%) that reads mode applies before presence calls. 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
-— and `db fetch <name>` always refreshes a bundled name from the latest upstream.
+— and `db fetch <name>` refreshes the provider-backed bundled names (`ecoh`, `ncbi`,
+`resfinder`) from the latest upstream.
 
 | Name | Content | dbtype |
 |---|---|---|
@@ -111,6 +114,7 @@ redistribution inside an MIT-licensed distribution, so everything else is fetch-
 | `bacmet2` | BacMet2 biocide/resistance genes (protein) | prot |
 | `victors` | Victors virulence factors | nucl |
 | `upec_expec_vf` | UPEC/ExPEC virulence genes | nucl |
+| `vp_ok` | V. parahaemolyticus O and K antigen loci (OAgc/CPSgc, vpasero; cluster, MIT, one-scan O:K serotype) | nucl |
 
 gapit also reads datadirs built by abricate itself (legacy `~~~` headers). The reverse
 does not hold: gapit-native databases use the `gapit/v1` header format (see SPEC.md §11),
@@ -120,7 +124,14 @@ Gene **cluster** databases are a second kind: `gapit db build NAME loci.gbk|gff3
 `kind: cluster` db (locus calls via minimap2, optional `--typing FILE` phenotype scoring),
 and the seven Kaptive cluster databases (kpsc_k, kpsc_o, kosc_k, kosc_o, ab_k, ab_o,
 ecoli_kps) fetch the Kaptive antigen-locus references at install time (GPL-3.0 content, so
-nothing is bundled — cite Kaptive/Wyres et al. 2020 for results). `gapit db list --json`
+nothing is bundled — cite Kaptive/Wyres et al. 2020 for results). The typed cluster
+bundle `vp_ok`
+merges the vpasero OAgc + CPSgc references (MIT) into one bundled db — a pure built-in in
+the ecoli_dec/lm_doumith pattern, no `db fetch` — where a single
+`gapit screen --db vp_ok` renders gapit.cluster/2 with `o_group`, `k_group`, and the
+composed `serotype` O:K call (RIMD 2210633 → O3:K6), working straight after
+`pip install gapit` with zero network.
+`gapit db list --json`
 surfaces each provider's content license where one is pinned.
 
 ## Output contract

{gapit-0.5.4 → gapit-0.5.6}/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.4"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.6"}
 ```
 
 Output schemas. Eleven documents are introspectable: `report`, `typing_result`, `reads`,
@@ -63,7 +63,7 @@ For example, `gapit schema version` (real output):
 ```
 
 Databases: the database catalog and install state (`gapit db list --json`; real output,
-first two of twenty-one shown, trimmed):
+first two of twenty-two shown, trimmed):
 
 ```console
 $ gapit db list --json

{gapit-0.5.4 → gapit-0.5.6}/docs/agents.zh.md

@@ -12,7 +12,7 @@ gapit 生来就是被程序驱动的。每个输出都以机器可读为设计
 
 ```console
 $ gapit --version --json
-{"schema":"gapit.version/1","name":"gapit","version":"0.5.4"}
+{"schema":"gapit.version/1","name":"gapit","version":"0.5.6"}
 ```
 
 输出 schema。十一个文档可自省：`report`、`typing_result`、`reads`、`reads2`、`cluster`、
@@ -61,7 +61,7 @@ $ gapit schema floors          # gapit.floors/1 (per-gene identity floors, reads
 }
 ```
 
-数据库：数据库目录与安装状态（`gapit db list --json`；真实输出，二十一个中的前两
+数据库：数据库目录与安装状态（`gapit db list --json`；真实输出，二十二个中的前两
 个，有删节）：
 
 ```console

{gapit-0.5.4 → gapit-0.5.6}/docs/databases.md

@@ -26,38 +26,39 @@ $ gapit db list --datadir /no/such/dir
 
 ```console
 $ gapit db list
-NAME	PROVIDER	STATUS	DBTYPE	DESCRIPTION
-ab_k	Kaptive (Kenyon lab)	available	nucl	A. baumannii K locus (Kaptive)
-ab_o	Kaptive (Kenyon lab)	available	nucl	A. baumannii OC locus — official keyword ab_o (Kaptive)
-argannot	IHU Méditerranée-Infection	available	nucl	ARG-ANNOT acquired resistance genes
-bacmet2	University of Gothenburg	available	prot	BacMet2 experimentally confirmed biocide/resistance genes (protein)
-card	McMaster University	available	nucl	CARD protein homolog resistance models
-ecoli_kps	Kaptive (Gladstone lab)	available	nucl	E. coli group 2+3 capsular polysaccharide loci (Kaptive)
-ecoli_vf	PHAC-NML	available	nucl	E. coli virulence factors (phac-nml)
-kosc_k	Kaptive (klebgenomics)	available	nucl	K. oxytoca species complex K locus (Kaptive)
-kosc_o	Kaptive (klebgenomics)	available	nucl	K. oxytoca species complex O locus (Kaptive)
-kpsc_k	Kaptive (klebgenomics)	available	nucl	K. pneumoniae species complex K locus (Kaptive)
-kpsc_o	Kaptive (klebgenomics)	available	nucl	K. pneumoniae species complex O locus (Kaptive)
-megares	MEG Lab	available	nucl	MEGARes antimicrobial resistance genes
-plasmidfinder	DTU CGE	available	nucl	CGE PlasmidFinder replicons
-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)
+NAME	DESCRIPTION	STATUS	DBTYPE	PROVIDER
+ab_k	A. baumannii K locus (Kaptive)	available	nucl	Kaptive (Kenyon lab)
+ab_o	A. baumannii OC locus — official keyword ab_o (Kaptive)	available	nucl	Kaptive (Kenyon lab)
+argannot	ARG-ANNOT acquired resistance genes	available	nucl	IHU Méditerranée-Infection
+bacmet2	BacMet2 experimentally confirmed biocide/resistance genes (protein)	available	prot	University of Gothenburg
+card	CARD protein homolog resistance models	available	nucl	McMaster University
+ecoli_kps	E. coli group 2+3 capsular polysaccharide loci (Kaptive)	available	nucl	Kaptive (Gladstone lab)
+ecoli_vf	E. coli virulence factors (phac-nml)	available	nucl	PHAC-NML
+kosc_k	K. oxytoca species complex K locus (Kaptive)	available	nucl	Kaptive (klebgenomics)
+kosc_o	K. oxytoca species complex O locus (Kaptive)	available	nucl	Kaptive (klebgenomics)
+kpsc_k	K. pneumoniae species complex K locus (Kaptive)	available	nucl	Kaptive (klebgenomics)
+kpsc_o	K. pneumoniae species complex O locus (Kaptive)	available	nucl	Kaptive (klebgenomics)
+megares	MEGARes antimicrobial resistance genes	available	nucl	MEG Lab
+plasmidfinder	CGE PlasmidFinder replicons	available	nucl	DTU CGE
+vfdb	VFDB virulence factors (set A, nucleotide)	available	nucl	USTC (VFDB)
+victors	Victors virulence factors	available	nucl	University of Chicago
+ecoh	E. coli O and H antigens (srst2 EcOH)	bundled	nucl	Holt lab (srst2)
+ecoli_dec	Diarrheagenic E. coli marker panel (GB 4789.6 + risk-monitoring designation)	bundled	nucl	gapit-curated (public-domain sources)
+lm_doumith	Listeria monocytogenes serogrouping (Doumith 2004)	bundled	nucl	gapit-curated (public-domain INSDC sources)
+ncbi	NCBI AMRFinderPlus (reference finder) curated AMR	bundled	nucl	NCBI
+resfinder	CGE ResFinder acquired resistance genes	bundled	nucl	DTU CGE
+vp_ok	V. parahaemolyticus O and K antigen loci (OAgc/CPSgc, vpasero)	bundled	nucl	gapit-curated (vpasero)
 ```
 
 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 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
-once, in the bundled section (never as a duplicate registry `available` row), and
-`gapit db fetch <name>` remains their fresh-upstream update path. Databases installed
+`bundled` before materialization, `installed (N)` after. Three of them (`ecoh`, `ncbi`,
+`resfinder`) are also registry providers — such names render
+exactly once, in the bundled section (never as a duplicate registry `available` row), and
+`gapit db fetch <name>` remains their fresh-upstream update path; `vp_ok` is bundled-only
+(no provider, no fetch). Databases installed
 into the datadir outside the catalog also appear, after the bundled section and sorted by
 name: `db build` products (gene and cluster kinds alike) and manifest-less directories
 (abricate-style or `db install` bytes) render with PROVIDER `local`, the record count
@@ -138,7 +139,7 @@ accept: a bundled database works out of the box.
 | `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 | — |
+| `vp_ok` | V. parahaemolyticus O and K antigen loci (195 loci, vpautils OAgc+CPSgc; cluster kind) | 2026-10-12 | `gapit.typing/2` (schemes `o_group`, `k_group`, `serotype`) |
 
 **License provenance.** Every `ecoli_dec` record was re-sourced from primary
 public-domain submissions (NCBI RefSeq/GenBank/DDBJ accessions, same alleles as the
@@ -147,20 +148,29 @@ and replaced during the 2026-10 audit, and the byte-identical `estA4` (J03311.1)
 `estA3` (M18346.1) — one `sth` gene, one sequence — was dropped by the build pipeline's
 exact-duplicate dedup in the 2026-10 rebuild, leaving 16 records. 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
+markers strand-corrected, `lmo0737` verified 100% against EGD-e). The three provider
+snapshots (`ecoh`, `ncbi`, `resfinder`) 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.
+domain (US government work), the CGE ResFinder database is Apache-2.0, and srst2's EcOH
+is BSD-3-Clause — all three permit
+redistribution inside the MIT-licensed wheel. The `vp_ok` cluster snapshot is
+MIT-licensed vpautils content (lab-curated loci, Bakta-annotated, via
+[indexofire/vpautils](https://github.com/indexofire/vpautils)); it ships as the
+resolved `sequences` + `features.json` pair a completed gapit.typing/2 build
+produces. 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
-proves the byte-identity for `resfinder` against a pinned copy of the upstream archive).
-The wheel copy therefore drifts as upstream curation moves on: `gapit db fetch <name>`
+the upstream content produces on the snapshot date (a regression test proves the
+byte-identity for `resfinder` against a pinned copy of the upstream archive, and for
+`vp_ok` against a `gapit db build` over the real vpautils GenBank files when local
+copies exist — `features.json` included, gene-id resolution included).
+The wheel copy therefore drifts as upstream curation moves on: for the provider-backed
+names (`ecoh`, `ncbi`, `resfinder`) `gapit db fetch <name>`
 (alone, or with `--force` to overwrite a materialized copy) re-downloads the **latest**
-upstream content and rebuilds the datadir database — the freshness path. `bundled.json`
+upstream content and rebuilds the datadir database — the freshness path. `vp_ok` has no
+provider: a refresh means a new resolved snapshot riding a wheel release.
+`bundled.json`
 records the snapshot date for reference. (`db outdated` stays manifest-based in v1:
 it reports the materialization/fetch time of what is installed, not bundled-vs-upstream
 drift — comparing the wheel snapshots against latest upstream is future work.)
@@ -172,7 +182,11 @@ silenced by `--quiet`), then the standard gene-build pipeline: `records.jsonl`,
 `sequences` FASTA with gapit/v1 headers, the BLAST index, the `typing.json` copy when the
 bundle ships one, and a manifest stamped `source: "bundled"`. That pipeline — shared with
 `gapit db build` — drops exact `(gene, sequence)` duplicate records at build time (first
-kept; a stderr note and the receipt's `duplicates_dropped` count the drops). Deterministic, zero
+kept; a stderr note and the receipt's `duplicates_dropped` count the drops). Cluster
+bundles (`vp_ok`) run the cluster pipeline instead: materialization rebuilds the locus
+FASTA and `features.json` from the committed artifacts through the same cluster build
+entry a `db build` uses — gene ids stay snapshot-resolved, the typing spec re-validates
+against them, no re-resolution. Deterministic, zero
 network. A missing datadir is created on this path only; `gapit setupdb` materializes
 every bundled database alongside indexing; re-running either is a no-op once the
 manifest exists. `db list` shows the database as `bundled` before that and
@@ -209,10 +223,41 @@ Known limitations, carried on the calls as notes where relevant:
 The fallback call — `untypeable (4a/4c, atypical profile, or non-Lm Listeria)` — is the
 honest answer for everything the five markers cannot resolve.
 
+### vp_ok (V. parahaemolyticus O:K, MIT, typed on install)
+
+`vp_ok` wraps the two *Vibrio parahaemolyticus* serotype references of
+[indexofire/vpautils](https://github.com/indexofire/vpautils) — `OAgc.gbk` (32
+O-antigen gene cluster loci) and `CPSgc.gbk` (163 capsular polysaccharide loci) —
+into ONE merged `kind: cluster` database. It is a PURE built-in bundled database in
+the `ecoli_dec`/`lm_doumith` pattern: no provider, no source URLs, no
+`gapit db fetch vp_ok`. The committed three-scheme typing asset
+(`src/gapit/data/typing/vp_ok.json`, generated reproducibly by
+`scripts/generate_vp_typing.py`) installs with it, so screening renders
+`gapit.cluster/2` with per-file phenotypes `o_group`, `k_group`, and the composed
+`serotype` `"{o_group}:{k_group}"` (fallbacks `OUT`/`KUT`) — the O:K serotype from a
+single scan:
+
+```console
+$ gapit screen RIMD.fna --db vp_ok --format json
+{"schema": "gapit.cluster/2", ..., "phenotypes": {"o_group": {"phenotype": "O3"},
+ "k_group": {"phenotype": "K6"}, "serotype": {"phenotype": "O3:K6"}}}
+```
+
+The database content is **MIT** (Bakta-annotated, via vpautils), so unlike the
+kaptive providers it is license-clean for redistribution — a resolved snapshot ships
+inside the wheel as the sixth bundled database (8.3 MiB committed artifacts, within
+the 30 MiB budget), and first use materializes it with zero network. The
+typing rules recompute sequence-unique key genes per locus (variants fold: OL4V1 →
+O4, KL20V1 → K20; untyped OLU*/KLU* loci get no rule and fall back to OUT/KUT), and
+the asset validates against the loci at build and materialization time — a drifted
+upstream GBK fails `TYPING_UNKNOWN_GENE` instead of installing silently. Calibrated
+against real genomes with RIMD 2210633 locked to O3:K6 (see the rule notes for the
+documented per-locus tuning).
+
 ## Checking database freshness
 
 `gapit db outdated` reports every installed database's age against the staleness
-threshold. Against a fully installed datadir (output trimmed to three of twenty-one rows):
+threshold. Against a fully installed datadir (output trimmed to three of twenty-two rows):
 
 ```console
 $ gapit db outdated --days 30
@@ -309,8 +354,10 @@ 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
-providers are **cluster** databases (built through the cluster pipeline at fetch time —
-see [Kaptive providers](#kaptive-providers-gpl-downloaded-on-fetch)).
+providers are **cluster** databases (built through the cluster pipeline at
+fetch time — see [Kaptive providers](#kaptive-providers-gpl-downloaded-on-fetch));
+the eighth cluster database, the typed `vp_ok`, is bundled-only
+([vp_ok](#vp_ok-v-parahaemolyticus-ok-mit-typed-on-install)).
 
 | Name | Maintainer | Content | dbtype |
 |---|---|---|---|
@@ -496,7 +543,7 @@ versions. A real one, from the plasmidfinder database:
   "upstream_version": "",
   "tool": {
     "name": "gapit",
-    "version": "0.5.4"
+    "version": "0.5.6"
   },
   "makeblastdb_version": "blastn: 2.17.0+",
   "minimap2_version": "2.31-r1302"