gapit 0.2.2__tar.gz

gapit-0.2.2/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true -diff

gapit-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  gates:
+    name: gates (${{ matrix.env }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        env: [default, py311, py313]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          cache: true
+      - run: pixi run -e ${{ matrix.env }} lint
+      - run: pixi run -e ${{ matrix.env }} fmt -- --check
+      - run: pixi run -e ${{ matrix.env }} typecheck
+      - run: pixi run -e ${{ matrix.env }} test
+
+  # Independent of gates: the bioconda solve is slow and orthogonal to the
+  # python matrix. Needs BOTH envs installed — the harness runs on the default
+  # env's python and invokes .pixi/envs/default/bin/gapit while parity env
+  # supplies abricate (see pixi.toml parity feature).
+  parity:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          cache: true
+      - run: pixi install -e default -e parity
+      - run: pixi run -e parity parity
+      - run: pixi run -e parity summary-parity

gapit-0.2.2/.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - pixi.toml
+      - pixi.lock
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          cache: true
+      - run: pixi run -e docs mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

gapit-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags: ["v*"]
+
+permissions:
+  # OIDC token for PyPI trusted publishing (pypa/gh-action-pypi-publish).
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gapit-0.2.2/.github/workflows/snapshot-refresh.yml

@@ -0,0 +1,129 @@
+name: Snapshot refresh
+
+# Monthly: re-fetch card + vfdb from upstream and regenerate the bundled
+# snapshot tars, so the wheel's zero-network defaults do not rot. A PR is the
+# review gate (license/provenance hygiene); `gapit db fetch <db> --from-source`
+# remains the manual path outside Actions.
+on:
+  schedule:
+    - cron: "0 3 1 * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+
+concurrency:
+  group: snapshot-refresh
+  cancel-in-progress: true
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.1
+        with:
+          cache: true
+      - run: pixi install
+      - name: Refresh card and vfdb snapshots from upstream
+        id: refresh
+        run: |
+          pixi run python - <<'PY'
+          import hashlib
+          import os
+          from datetime import UTC, datetime
+          from pathlib import Path
+          from tempfile import TemporaryDirectory
+
+          from gapit.providers import REGISTRY
+          from gapit.providers.common import fetch_provider
+          from gapit.providers.snapshots import extract_snapshot, make_snapshot
+
+          # Local verification reruns this exact script against a scratch dir
+          # via GAPIT_SNAPSHOT_REFRESH_DIR; the committed tars stay untouched.
+          snapshot_dir = Path(os.environ.get("GAPIT_SNAPSHOT_REFRESH_DIR", "src/gapit/data/snapshots"))
+          now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+          def sha256(path: Path) -> str:
+              digest = hashlib.sha256()
+              with path.open("rb") as handle:
+                  for chunk in iter(lambda: handle.read(1 << 20), b""):
+                      digest.update(chunk)
+              return digest.hexdigest()
+
+
+          def emit(key: str, value: str) -> None:
+              target = os.environ.get("GITHUB_OUTPUT")
+              if target:
+                  with open(target, "a", encoding="utf-8") as handle:
+                      print(f"{key}<<EOF", value, "EOF", sep="\n", file=handle)
+
+
+          rows = []
+          with TemporaryDirectory(prefix="gapit-snapshot-refresh.") as scratch:
+              for name in ("card", "vfdb"):
+                  db_dir = Path(scratch) / name
+                  manifest = fetch_provider(
+                      REGISTRY[name], db_dir, fetched_at=now, from_source=True, quiet=False
+                  )
+                  dest = snapshot_dir / f"{name}.tar.gz"
+                  before = sha256(dest) if dest.is_file() else "-"
+                  # The tar turns over only when the records changed: the
+                  # archived manifest carries fetched_at, so an unconditional
+                  # rebuild would rewrite bytes (and open a PR) on every run
+                  # even with identical upstream content.
+                  changed = True
+                  if dest.is_file():
+                      bundled = Path(scratch) / f"{name}-bundled"
+                      bundled.mkdir()
+                      extract_snapshot(dest, bundled)
+                      changed = (bundled / "records.jsonl").read_bytes() != (
+                          db_dir / "records.jsonl"
+                      ).read_bytes()
+                  if changed:
+                      snapshot_dir.mkdir(parents=True, exist_ok=True)
+                      make_snapshot(db_dir, dest)
+                  after = sha256(dest)
+                  rows.append((name, manifest.n_records, before, after, changed))
+                  verdict = "changed" if changed else "unchanged"
+                  print(f"{name}: {manifest.n_records} records, tar sha256 {before} -> {after} ({verdict})")
+
+          summary = "\n".join(
+              [
+                  "Monthly upstream refresh of the bundled card and vfdb snapshots.",
+                  "",
+                  "The snapshot carries `records.jsonl` plus the manifest; the BLAST index",
+                  "rebuilds locally on install (deterministic, matches the installed BLAST).",
+                  "",
+                  "| db | records | tar sha256 before | tar sha256 after | changed |",
+                  "|---|---|---|---|---|",
+                  *(
+                      f"| {name} | {records} | `{before}` | `{after}` | {'yes' if changed else 'no'} |"
+                      for name, records, before, after, changed in rows
+                  ),
+              ]
+          )
+          print()
+          print(summary)
+          emit("month", f"{datetime.now(UTC):%Y-%m}")
+          emit("summary", summary)
+          PY
+      - name: Open snapshot refresh pull request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: chore/snapshot-refresh
+          title: "data: refresh card and vfdb snapshots (${{ steps.refresh.outputs.month }})"
+          body: ${{ steps.refresh.outputs.summary }}
+          commit-message: "data: refresh card and vfdb snapshots"
+          delete-branch: true
+      - name: Open failure issue
+        if: failure() && github.event_name == 'schedule'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh issue create --repo "$GITHUB_REPOSITORY" \
+            --title "snapshot-refresh failed (run ${{ github.run_id }})" \
+            --body "Scheduled snapshot refresh failed. Check the [run log](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}). Common cause: upstream source outage (card.mcmaster.ca / mgc.ac.cn)."

gapit-0.2.2/.gitignore

@@ -0,0 +1,21 @@
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+
+# agent session tooling
+.omo/
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+
+# opencode
+.omo/
+
+# mkdocs rendered site
+site/

gapit-0.2.2/AGENTS.md

@@ -0,0 +1,197 @@
+# AGENTS.md — gapit
+
+> Python reimplementation of [abricate](https://github.com/tseemann/abricate): mass screening of
+> contigs for antimicrobial resistance and virulence genes. **Agent-first**: every output is
+> machine-readable (JSON / Markdown) by design, not as an afterthought.
+
+## 1. Mission
+
+`gapit` answers one question: **which known genes are present in this assembly, and how confident
+are we?** It replaces abricate (Perl) with a modern, typed, testable Python tool that:
+
+1. Produces byte-compatible TSV with abricate (drop-in replacement for existing pipelines).
+2. Adds first-class **JSON** and **Markdown** outputs so LLM agents and humans can consume
+   results without parsing tab-delimited text.
+3. Exposes stable, versioned output contracts (schemas, exit codes, error envelopes) that
+   autonomous agents can rely on.
+
+## 2. Environment & toolchain
+
+- **Environment manager**: [pixi](https://pixi.sh) (conda-forge channel). Never use pip/conda
+  directly; add dependencies to `pixi.toml` (`pixi add <pkg>` for conda, `pixi add --pypi <pkg>`
+  for PyPI).
+- **Python**: 3.14 in the pixi dev env (current stable); the package declares
+  `requires-python = ">=3.11"` and CI tests 3.11 / 3.13 / 3.14.
+- **External binaries**: BLAST+ (`blastn`, `blastx`, `makeblastdb`, `blastdbcmd`) and `minimap2`
+  (FASTQ read screening, SPEC.md §10), all from conda-forge/bioconda. Invoked only via `subprocess`
+  with an argument list — never `shell=True`. Input normalization (fa/fq/gbk/embl, gz/bz2) is
+  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
+  output). No biopython — FASTA I/O is a small streaming parser we own.
+- **Quality gates**: `ruff` (lint + format), `basedpyright` (strict mode), `pytest`.
+
+### Commands (pixi tasks)
+
+```bash
+pixi run lint        # ruff check
+pixi run fmt         # ruff format
+pixi run typecheck   # basedpyright --strict
+pixi run test        # pytest (unit, offline)
+pixi run gapit       # the CLI itself
+pixi run -e parity parity          # byte-diff screening vs real abricate (abricate-only env)
+pixi run -e parity summary-parity  # byte-diff summary vs real abricate
+```
+
+Every change must leave `lint`, `typecheck`, and `test` green.
+
+## 3. Repository layout
+
+```
+gapit/
+├── AGENTS.md            # this file
+├── PLAN.md              # development roadmap (phase-gated)
+├── SPEC.md              # distilled abricate behavior spec (source of truth for parity)
+├── pixi.toml
+├── recipe/
+│   └── meta.yaml        # conda recipe (submission deferred)
+├── .github/workflows/
+│   └── ci.yml           # gates matrix 3.11/3.13/3.14 + parity job
+├── src/gapit/
+│   ├── __init__.py
+│   ├── cli.py           # typer entrypoint: screen / summary / db / list / setupdb / schema / mcp
+│   ├── config.py        # datadir resolution, defaults, env vars
+│   ├── dispatch.py      # shared CLI dispatch (error envelope → exit codes) + --datadir option
+│   ├── proctools.py     # external-tool plumbing: argv subprocess runner + stderr notes
+│   ├── fasta.py         # streaming FASTA reader + shared gz/bz2 text opener
+│   ├── seqconvert.py    # native input normalization: fa/fq/gbk/embl (±gz/bz2) → FASTA
+│   ├── db.py            # database discovery, header parsing, makeblastdb wrapper
+│   ├── dbcodec.py       # gapit/v1 tagged-header codec (percent-encoded ids)
+│   ├── records.py       # records.jsonl truth store + gapit.manifest/1 provenance
+│   ├── dbbuild.py       # deterministic native-db build pipeline with self-check
+│   ├── db_ops.py        # db use-cases: provider fetch + list (shared CLI + MCP; no typer)
+│   ├── 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 → native db build (shared CLI + MCP)
+│   ├── blast.py         # blastn invocation + tabular output parsing
+│   ├── hits.py          # Hit model, identity/coverage computation, filtering, dedup
+│   ├── minimap.py       # COVERAGE_MAP construction (exact abricate arithmetic)
+│   ├── minimap2_run.py  # minimap2 invocation layer for reads mode (streaming PAF, --cs/NM tags)
+│   ├── paf.py           # PAF row parsing + interval arithmetic (minimap2 output boundary)
+│   ├── report.py        # Report model: the canonical in-memory result
+│   ├── screening.py     # blastn screen use-case + shared engine helpers (OutputFormat, AlignerEnum)
+│   ├── screening_reads.py # minimap2 use-cases: --r1/--r2 reads + --aligner minimap2 assemblies
+│   ├── reads.py         # FASTQ mode: minimap2 PAF parsing, coverage breadth/depth, presence
+│   ├── summary.py       # summary core: parse report tables into a gene matrix
+│   ├── cmd_screen.py    # `gapit screen` CLI (registered from cli.py)
+│   ├── cmd_summary.py   # `gapit summary` CLI (registered from cli.py)
+│   ├── cmd_db.py        # `gapit db` command group (fetch | list; registers the subcommands)
+│   ├── cmd_db_install.py # `gapit db install`: SHA256-verified local-file install
+│   ├── cmd_db_build.py  # `gapit db build` CLI (custom FASTA → native db)
+│   ├── cmd_db_search.py # `gapit db search` CLI (records.jsonl lookup)
+│   ├── cmd_db_outdated.py # `gapit db outdated` CLI (staleness report)
+│   ├── mcp.py           # MCP stdio server (hand-rolled JSON-RPC 2.0); backs gapit-mcp
+│   ├── mcp_tools.py     # MCP tool implementations (call the shared use-cases)
+│   ├── mcp_schemas.py   # MCP tools/list declarations (names, descriptions, inputSchemas)
+│   ├── errors.py        # typed errors + JSON error envelope
+│   ├── formats/
+│   │   ├── tsv.py       # abricate-compatible TSV/CSV
+│   │   ├── json.py      # versioned JSON (gapit.report/1 et al.)
+│   │   ├── md.py        # Markdown (human + agent readable, YAML frontmatter)
+│   │   ├── schemas.py   # registered output models behind `gapit schema`
+│   │   └── summary.py   # summary matrix renderers (TSV/CSV/JSON/MD)
+│   ├── providers/       # 12 DB providers + common.py helpers + snapshots.py loader
+│   ├── data/snapshots/  # bundled card + vfdb snapshot archives (.tar.gz)
+│   └── py.typed
+└── tests/
+    ├── data/            # tiny synthetic db + contigs + reads (fast, offline)
+    ├── golden/          # expected outputs incl. abricate reference TSVs
+    ├── parity/          # corpus + run_parity.py / run_summary_parity.py (opt-in env)
+    └── test_*.py        # unit + CLI + provider + integration tests
+```
+
+One file, one responsibility. Target ≤ 250 LOC per module; split before it hurts.
+
+## 4. Coding conventions
+
+- **Strict typing everywhere.** basedpyright strict; no `Any` unless isolated and justified in a
+  comment. No `# type: ignore`, no `cast` to silence real errors.
+- **Parse, don't validate.** BLAST rows, FASTA records, and db headers become typed models at the
+  boundary; the core logic never touches raw strings.
+- **No silent failures.** Errors are typed (`errors.py`), carry context, and map to documented
+  exit codes. Empty `except` blocks are forbidden.
+- **Deterministic output.** Stable sort orders, no wall-clock timestamps inside data payloads
+  (metadata block only), LF line endings, UTF-8.
+- **TDD for core logic.** hit filtering, merging, and coverage-map math are written test-first.
+- Match the style of the file you are editing; when in doubt, `ruff format` decides.
+
+## 5. The agent-facing output contract (design center)
+
+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`. 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
+  human can read and an agent can regex reliably.
+- **Errors**: failures print a JSON envelope to stderr
+  `{"schema": "gapit.error/1", "code": "...", "message": "...", "context": {...}}` and exit with a
+  documented non-zero code (2 = usage, 3 = missing dependency, 4 = db error, 5 = input error).
+- **DB acquisition** `[gapit-extension]`: `gapit db fetch|list|search|outdated|build|install` —
+  provider fetch (bundled card/vfdb snapshots install offline; `--from-source` forces upstream),
+  provider listing, records.jsonl gene search, staleness report, custom FASTA→native-db build,
+  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
+  `db_fetch` (installs provider databases; may download) and `db_build` (writes a custom db);
+  tool failures carry the `gapit.error/1` envelope.
+- **stdout purity**: data on stdout, diagnostics on stderr, always. `--quiet` only affects stderr.
+- **Self-description**: `gapit --version --json`, `gapit list --json`, `gapit schema` — an agent
+  must be able to discover everything without reading docs.
+
+## 6. 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
+  committed files deliberately and review diffs like code.
+- **Parity harness**: `pixi run -e parity parity` (and `summary-parity`) runs real abricate
+  (conda) and gapit over a small genome corpus and diffs the gene calls byte-for-byte (file,
+  gene, %identity, %coverage). Parity on the corpus is the release gate for v1.0.
+- 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)
+
+- 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).
+  `makeblastdb -dbtype nucl` builds the index. gapit also writes its own native `gapit/v1`
+  tagged-header format (SPEC §11), whose `func` key carries a locked per-provider function
+  vocabulary (antibiotic classes, `virulence`, `replicon`, ...); abricate cannot read
+  gapit-native databases.
+- Screening = native normalize (`seqconvert.py`, any2fasta-equivalent semantics) → `blastn` of
+  query contigs against one db → 15-field
+  tabular hits → filter by identity / coverage thresholds → **dedup hits sharing identical
+  `(contig, qstart, qend)`** (first/best BLAST row wins) → one TSV row per surviving hit.
+  abricate does **not** merge overlapping intervals — do not "improve" this on the default path.
+- Key computed fields: `%COVERAGE = 100*(length-gaps)/slen` (filtered unrounded, displayed
+  `%.2f`), `%IDENTITY` (BLAST pident, never post-filtered), `COVERAGE_MAP` (15-char minimap),
+  `GAPS`. Exact formulas, the dedup rule, and the minimap arithmetic live in `SPEC.md` — when
+  abricate and intuition disagree, **abricate wins** (parity is a feature).
+
+## 8. 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
+
+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
+   a note in `PLAN.md`.
+3. Do not add dependencies without checking this file's §2 first — the list is intentionally short.
+4. Verification is part of the task: `pixi run lint && pixi run typecheck && pixi run test` before
+   declaring done.

gapit-0.2.2/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+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.2.2] - 2026-09-24
+
+### Security
+
+- minimap2 input paths are passed as absolute paths, so a file named like an option
+  (e.g. `-d`) can no longer inject minimap2 flags; the child process no longer inherits
+  stdin (the MCP protocol stream).
+
+### Changed
+
+- `--minid`/`--mincov` with `--aligner minimap2` or `--r1/--r2` are now a usage error
+  (exit 2) instead of being silently ignored.
+- MCP `screen` (blastn) reuses the CLI use-case; its validation messages now match the CLI.
+- MCP `screen_reads` passes read arrays natively, so filenames containing commas work.
+
+### Fixed
+
+- MCP server replies `-32600`/`-32602` to malformed requests that carry an `id` instead of
+  silently dropping them.
+- A truncated gzip reads file raises a typed `INVALID_READS_FORMAT` error (exit 5) instead
+  of `UNEXPECTED` (exit 1).
+
+## [0.2.1] - 2026-09-22
+
+### Changed
+
+- License changed from GPL-2.0-only to MIT (rightsholder decision; behavioral
+  reimplementation status unchanged).
+
+## [0.2.0] - 2026-09-22
+
+Development window: 2026-09-15 to 2026-09-22 (PLAN.md Phases 1 through 8 and post-phase
+hardening).
+
+### Added
+
+- Screening core: `any2fasta` to `blastn` pipeline with SPEC-exact hit processing, and
+  byte-compatible TSV against abricate 1.4.0 (PLAN Phases 1-3, 2026-09-15). Parity is
+  checked on a genome corpus with `pixi run -e parity parity` (6/6 byte-identical).
+- Agent-facing outputs: `--format json|md` with versioned schemas (`gapit.report/1`,
+  `gapit.reads/1`, `gapit.summary/1`, `gapit.list/1`, `gapit.version/1`), the
+  `gapit.error/1` stderr envelope with documented exit codes, and introspection via
+  `gapit schema report|reads|summary|list|error|version` (2026-09-16).
+- FASTQ reads mode via minimap2: `gapit screen --r1/--r2 --read-type sr|map-ont|map-hifi`;
+  presence is called on alignment breadth (2026-09-16).
+- Summary matrix mode: `gapit summary` emits TSV/CSV/JSON/MD; byte parity with
+  `abricate --summary` via `pixi run -e parity summary-parity` (2026-09-17).
+- `gapit db install`: checksum-verified (SHA256), atomic local-file installation
+  (2026-09-17).
+- Native `gapit/v1` database format: tagged-header codec, `records.jsonl` truth store
+  with `gapit.manifest/1` provenance, deterministic build pipeline with self-check, and
+  `.mmi` BLAST index build with version-gated reuse (2026-09-18).
+- 12 database providers (ncbi, card, resfinder, argannot, plasmidfinder, megares, ecoh,
+  vfdb, ecoli_vf, bacmet2, victors, upec_expec_vf) with offline-tested transforms
+  (2026-09-18).
+- Bundled card and vfdb snapshots: a bare `gapit db fetch` installs the default set with
+  zero network; `--from-source` forces upstream download (2026-09-18).
+- CLI hardening: shell completions, `--debug` argv echo on stderr, and `--jobs` parallel
+  screening across inputs with input-order stdout (2026-09-18).
+- CI: gates matrix (lint, fmt, typecheck, test on Python 3.11 / 3.13 / 3.14) plus a
+  parity job that byte-diffs against real abricate (2026-09-18).
+- MCP stdio server: `gapit mcp` subcommand and `gapit-mcp` console script, hand-rolled
+  JSON-RPC 2.0 with zero new dependencies; read-only tools `screen`, `summary`,
+  `schema`, `db_list` (2026-09-18).
+- Conda recipe (`recipe/meta.yaml`) for PyPI/bioconda packaging (2026-09-18).
+- Custom database construction: `gapit db build NAME FASTA` builds a screening-ready native
+  database from plain, abricate `~~~`, or `gapit|` FASTA (auto-detected), with optional
+  `--tsv` metadata (accession, function classes) and `--dbtype` override; guide with worked
+  examples in `docs/custom-db.md` (2026-09-19).
+- `--aligner blastn|minimap2` engine selector on `gapit screen`: defaults follow the input
+  (blastn for contig files, minimap2 for `--r1`/`--r2` reads); `--aligner minimap2` screens
+  positional assembly FASTA through the minimap2 engine, `--aligner blastn` with `--r1`/`--r2`
+  is a usage error (2026-09-19).
+- `gapit db outdated`: staleness report over installed databases (age vs `--days`, newer
+  bundled snapshot) as a TSV table or `gapit.dboutdated/1` JSON document (2026-09-20).
+- `gapit db search TERM`: case-insensitive gene/accession/function/product lookup across
+  installed databases' `records.jsonl`, with `--field`, `--exact`, `--db`, `--limit` and
+  JSONL output (2026-09-20).
+- MCP database tools `db_fetch`, `db_build`, `db_search`, `db_outdated`: the MCP server now
+  exposes the `db` commands alongside the analysis tools, so agents can self-provision and
+  inspect databases mid-session; `mcp.py` split into protocol (`mcp.py`) and tool
+  implementations (`mcp_tools.py`) with zero wire change for the existing tools (2026-09-20).
+- CI snapshot refresh: monthly scheduled workflow (`.github/workflows/snapshot-refresh.yml`)
+  re-fetching card and vfdb from upstream, regenerating the bundled tars only when the
+  records changed, and opening a review PR (2026-09-20).
+- Reads-mode opt-in alignment filtering: `gapit screen --min-identity/--min-mapq` (reads
+  engine only) drops PAF alignments below the thresholds before aggregation and emits the new
+  `gapit.reads/2` document (params gain both thresholds; gene entries gain
+  `mean_identity_pct`, the alignment-length-weighted mean identity; introspectable via
+  `gapit schema reads2`). Both flags off keeps `gapit.reads/1` byte-identical, and the
+  identity floor fixes the documented family-splitting over-calls on homologous genes
+  (2026-09-20).
+- MCP reads tools: new `screen_reads` tool (FASTQ lanes via minimap2 → `gapit.reads/1`,
+  `min_identity`/`min_mapq` > 0 → `gapit.reads/2`) and new `screen` arguments
+  `aligner`/`min_breadth`/`min_identity`/`min_mapq` (`aligner minimap2` = fast assembly
+  survey). Both delegate to the shared reads use-cases with `quiet` stderr; additive
+  `gapit.mcp` contract — nine tools, the other eight wire-identical, no output-schema
+  version bump (2026-09-22).
+
+### Changed
+
+- `any2fasta` is no longer a runtime dependency: input normalization (FASTA/FASTQ/GenBank/EMBL,
+  plain/gz/bz2 → FASTA) is native (`seqconvert.py`, perl-extracted semantics) and blastn reads the
+  converted FASTA on stdin. Parsed-record equivalence with the binary is differentially tested
+  with the parity env on PATH (abricate provides any2fasta transitively), and `.fa` parity
+  remains byte-identical (2026-09-21).
+- Screening and reads paths route `gapit/v1` tagged headers to the native codec; legacy
+  abricate `~~~` headers keep the frozen parser, so abricate-built datadirs screen
+  identically. The reverse does not hold: gapit-built databases are unreadable by
+  abricate (accepted trade-off).
+- A bare `gapit db fetch` installs the bundled default set (card, vfdb) instead of
+  downloading; `--from-source` restores the upstream fetch path.
+- `gapit setupdb` honors the `gapit.manifest/1` dbtype on reindex (manifest-less abricate
+  dirs keep the mol_type heuristic), and reads/minimap2-assembly screening now rejects the
+  blastn-only flags `--fofn`, `--noheader`, `--nopath`, `--jobs N>1` with usage errors
+  (exit 2) instead of silently ignoring them (2026-09-22).
+
+### Removed
+
+- `--csv` flag on `gapit screen`; use `--format csv` instead (breaking: the flag is now
+  rejected as an unknown option, exit 2) (2026-09-19).
+
+### Fixed
+
+- Summary mode auto-detects TSV vs CSV per input file, avoiding the upstream quirk where
+  a global `--csv` flag mangles mixed-format input sets.

gapit-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 indexofire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.