gapit 0.2.2__py3-none-any.whl

gapit/__init__.py

@@ -0,0 +1,3 @@
+"""gapit — agent-first Python reimplementation of abricate."""
+
+__version__ = "0.2.2"

gapit/blast.py

@@ -0,0 +1,239 @@
+"""BLAST invocation, tabular parsing, and the screening pipeline (SPEC.md §3)."""
+
+import re
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+from gapit.db import Database
+from gapit.errors import DependencyError, GapitError, InputError
+from gapit.hits import process_rows
+from gapit.report import Report, ScreeningParams
+from gapit.seqconvert import SeqFormat, detect_format, to_fasta_lines
+
+BLAST_FIELDS = [
+    "qseqid",
+    "qstart",
+    "qend",
+    "qlen",
+    "sseqid",
+    "sstart",
+    "send",
+    "slen",
+    "sstrand",
+    "evalue",
+    "length",
+    "pident",
+    "gaps",
+    "gapopen",
+    "stitle",
+]
+
+_OUTFMT = "6 " + " ".join(BLAST_FIELDS)
+_MIN_BLAST_VERSION = (2, 2, 30)
+
+
+class BlastRow(BaseModel, frozen=True):
+    """One outfmt-6 row, typed at the boundary (SPEC.md §3 field order)."""
+
+    qseqid: str
+    qstart: int
+    qend: int
+    qlen: int
+    sseqid: str
+    sstart: int
+    send: int
+    slen: int
+    sstrand: str
+    evalue: float
+    length: int
+    pident: float
+    gaps: int
+    gapopen: int
+    stitle: str
+
+
+def parse_blast_row(line: str) -> BlastRow:
+    """Parse one tab-delimited outfmt-6 line; a row with != 15 columns is a
+    hard error (upstream wording)."""
+    fields = line.split("\t")
+    if len(fields) != 15:
+        raise GapitError("can not find sequence data", code="BLAST_PARSE_FAILED")
+    return BlastRow(
+        qseqid=fields[0],
+        qstart=int(fields[1]),
+        qend=int(fields[2]),
+        qlen=int(fields[3]),
+        sseqid=fields[4],
+        sstart=int(fields[5]),
+        send=int(fields[6]),
+        slen=int(fields[7]),
+        sstrand=fields[8],
+        evalue=float(fields[9]),
+        length=int(fields[10]),
+        pident=float(fields[11]),
+        gaps=int(fields[12]),
+        gapopen=int(fields[13]),
+        stitle=fields[14],
+    )
+
+
+def ensure_blast() -> None:
+    """Require blastn >= 2.2.30 on PATH (SPEC.md §1 version gate)."""
+    try:
+        result = subprocess.run(["blastn", "-version"], check=False, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise DependencyError(
+            "required binary not found on PATH: blastn",
+            code="MISSING_DEPENDENCY",
+            context={"binary": "blastn"},
+        ) from exc
+    if result.returncode != 0:
+        raise DependencyError(
+            f"blastn -version failed: {result.stderr.strip()}",
+            code="BLAST_VERSION_CHECK_FAILED",
+        )
+    match = re.search(r"blastn:\s*(\d+)\.(\d+)\.(\d+)", result.stdout)
+    if match is None:
+        raise DependencyError(
+            f"could not parse blastn version from: {result.stdout!r}",
+            code="BLAST_VERSION_CHECK_FAILED",
+        )
+    major, minor, revision = (int(part) for part in match.groups())
+    if (major, minor, revision) < _MIN_BLAST_VERSION:
+        raise DependencyError(
+            f"blastn {major}.{minor}.{revision} is older than 2.2.30",
+            code="BLAST_VERSION_TOO_OLD",
+        )
+
+
+def _normalize(query: Path) -> tuple[str, SeqFormat]:
+    """Convert one input file to FASTA text in-process (seqconvert), wrapping
+    any parser failure in the blast-path error shape
+    ``invalid input file {query}: <reason>``.
+
+    The whole normalized FASTA is held in memory and fed to blast via
+    ``input=`` — genome-scale inputs are a few MB, a deliberate trade-off:
+    ``subprocess.run``'s communicate() owns stdin/stdout concurrency, so the
+    retired ``any2fasta | blastn`` Popen chain needs no stderr-drain thread
+    here anymore.
+    """
+    try:
+        fmt = detect_format(query)
+        text = "".join(to_fasta_lines(query, fmt))
+    except InputError as exc:
+        raise InputError(
+            f"invalid input file {query}: {exc}",
+            code="INVALID_INPUT",
+            context={"file": str(query)},
+        ) from exc
+    return text, fmt
+
+
+def _pipeline(fasta_text: str, argv: list[str]) -> str:
+    """``<argv>`` reading the normalized FASTA on stdin; returns stdout as text."""
+    try:
+        result = subprocess.run(argv, input=fasta_text, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise DependencyError(
+            f"required binary not found on PATH: {argv[0]}",
+            code="MISSING_DEPENDENCY",
+            context={"binary": argv[0]},
+        ) from exc
+    if result.returncode != 0:
+        raise GapitError(
+            f"{argv[0]} failed: {result.stderr.strip()}",
+            code="BLAST_FAILED",
+            context={"binary": argv[0]},
+        )
+    return result.stdout
+
+
+def run_blastn(
+    query: Path,
+    database: Database,
+    params: ScreeningParams,
+    *,
+    dbtype: Literal["nucl", "prot"],
+    debug: bool = False,
+) -> list[BlastRow]:
+    """Run the normalize (native seqconvert) -> blastn/blastx pipeline for one
+    query file.
+
+    The database must already be indexed; protein databases switch to blastx
+    without -perc_identity (upstream quirk, minid silently ignored). With
+    ``debug``, echo the normalization step and the exact blast argv to stderr
+    (abricate --debug parity). ``dbtype`` comes from the caller resolving it
+    once per run, so dependency/index errors surface before any per-file work.
+    """
+    if dbtype == "prot":
+        argv = [
+            "blastx",
+            "-task",
+            "blastx-fast",
+            "-seg",
+            "no",
+            "-db",
+            str(database.sequences_path),
+            "-outfmt",
+            _OUTFMT,
+            "-num_threads",
+            str(params.threads),
+            "-evalue",
+            "1E-20",
+            "-culling_limit",
+            "1",
+            "-max_target_seqs",
+            "10000",
+        ]
+        sys.stderr.write("--minid is not applied to protein databases (abricate parity)\n")
+    else:
+        argv = [
+            "blastn",
+            "-task",
+            "blastn",
+            "-dust",
+            "no",
+            "-perc_identity",
+            str(params.minid),
+            "-db",
+            str(database.sequences_path),
+            "-outfmt",
+            _OUTFMT,
+            "-num_threads",
+            str(params.threads),
+            "-evalue",
+            "1E-20",
+            "-culling_limit",
+            "1",
+            "-max_target_seqs",
+            "10000",
+        ]
+    fasta_text, fmt = _normalize(query)
+    if debug:
+        sys.stderr.write(f"gapit: normalize: {query} ({fmt.value})\n")
+        sys.stderr.write(f"gapit: run: {shlex.join(argv)}\n")
+    output = _pipeline(fasta_text, argv)
+    return [parse_blast_row(line) for line in output.splitlines() if line.strip()]
+
+
+def screen_file(
+    query: Path,
+    database: Database,
+    params: ScreeningParams,
+    *,
+    dbtype: Literal["nucl", "prot"],
+    debug: bool = False,
+) -> Report:
+    """Screen one input file against one database into a sorted Report.
+
+    The caller owns the per-run gates (``ensure_blast`` and the one-shot
+    ``dbtype`` resolution) so a multi-file run pays each probe once."""
+    rows = run_blastn(query, database, params, dbtype=dbtype, debug=debug)
+    hits = process_rows(rows, mincov=params.mincov, default_db=params.db)
+    ordered = sorted(hits, key=lambda hit: (hit.sequence, hit.start))
+    return Report(file=str(query), hits=tuple(ordered))

gapit/cli.py

@@ -0,0 +1,128 @@
+"""gapit command-line interface (typer entrypoint)."""
+
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from gapit import __version__, config, db
+from gapit.cmd_db import register_db_command
+from gapit.cmd_screen import register_screen_command
+from gapit.cmd_summary import register_summary_command
+from gapit.dispatch import Datadir, dispatch
+from gapit.errors import usage_fail
+from gapit.formats.json import ListDocument, ListEntryDocument, VersionDocument
+from gapit.formats.schemas import SCHEMA_MODELS
+from gapit.mcp import register_mcp_command
+
+app = typer.Typer(
+    name="gapit",
+    help="Mass screening of contigs for antimicrobial resistance and virulence genes.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    show_version: Annotated[
+        bool | None,
+        typer.Option("--version", help="Show version and exit."),
+    ] = None,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="With --version: emit gapit.version/1 JSON."),
+    ] = False,
+) -> None:
+    """Mass screening of contigs for AMR and virulence genes."""
+    if show_version:
+        if as_json:
+            typer.echo(VersionDocument(version=__version__).model_dump_json(by_alias=True))
+        else:
+            typer.echo(f"gapit {__version__}")
+        raise typer.Exit()
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+def _list(datadir: Path | None, as_json: bool) -> None:
+    infos = db.list_databases(config.resolve_datadir(datadir), setupdb=False)
+    if as_json:
+        document = ListDocument(
+            databases=[
+                ListEntryDocument(
+                    name=info.name,
+                    sequences=info.n_sequences,
+                    dbtype=info.dbtype,
+                    date=info.date,
+                )
+                for info in infos
+            ]
+        )
+        typer.echo(document.model_dump_json(indent=2, by_alias=True))
+        return
+    typer.echo("DATABASE\tSEQUENCES\tDBTYPE\tDATE")
+    for info in infos:
+        typer.echo(f"{info.name}\t{info.n_sequences}\t{info.dbtype}\t{info.date}")
+
+
+def _setupdb(datadir: Path | None, debug: bool) -> None:
+    infos = db.list_databases(config.resolve_datadir(datadir), setupdb=True, debug=debug)
+    for info in infos:
+        typer.echo(
+            f"Indexed {info.name} ({info.n_sequences} sequences, {info.dbtype})",
+            err=True,
+        )
+
+
+@app.command("list")
+def list_dbs(
+    datadir: Datadir = None,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON instead of a table."),
+    ] = False,
+) -> None:
+    """List installed databases (abricate --list compatible)."""
+    dispatch(lambda: _list(datadir, as_json))
+
+
+@app.command("setupdb")
+def setupdb(
+    datadir: Datadir = None,
+    debug: Annotated[
+        bool,
+        typer.Option("--debug", help="Echo external command lines to stderr."),
+    ] = False,
+) -> None:
+    """Build BLAST indices for all databases under the datadir."""
+    dispatch(lambda: _setupdb(datadir, debug))
+
+
+register_screen_command(app)
+register_summary_command(app)
+register_db_command(app)
+register_mcp_command(app)
+
+
+@app.command("schema")
+def schema(
+    name: Annotated[
+        str,
+        typer.Argument(
+            help="Document to introspect: report, reads, reads2, summary, list, error, or version."
+        ),
+    ],
+) -> None:
+    """Print the JSON Schema of a gapit output document."""
+
+    def run() -> None:
+        model = SCHEMA_MODELS.get(name)
+        if model is None:
+            usage_fail(f"unknown schema name: {name} (choose from: {', '.join(SCHEMA_MODELS)})")
+        typer.echo(json.dumps(model.model_json_schema(by_alias=True), indent=2))
+
+    dispatch(run)

gapit/cmd_db.py

@@ -0,0 +1,113 @@
+"""The `gapit db` command group: build, fetch, list, install.
+
+- ``db build NAME FASTA``: build a custom gapit-native database from a
+  user-supplied FASTA (+ optional TSV metadata) — the whole acquisition
+  pipeline without a provider (use-case: :mod:`gapit.db_build_ops`,
+  command: :mod:`gapit.cmd_db_build`).
+- ``db fetch [NAME]``: acquire provider database(s) under the datadir. With
+  no NAME the default set (``DEFAULT_DBS``: card, vfdb) installs in order —
+  each from its BUNDLED SNAPSHOT (Wave G) when one resolves, else over the
+  network; ``--from-source`` forces the upstream download even when a
+  snapshot exists. One JSON receipt line per database on stdout
+  (use-case: :mod:`gapit.db_ops`).
+- ``db list``: show every known provider with its installed state
+  (use-case: :mod:`gapit.db_ops`).
+- ``db outdated`` / ``db search``: read-only queries over the installed
+  databases (use-case: :mod:`gapit.db_query_ops`; commands:
+  :mod:`gapit.cmd_db_outdated`, :mod:`gapit.cmd_db_search`).
+- ``db install``: checksum-verified LOCAL-FILE installation
+  (:mod:`gapit.cmd_db_install`, split off in Wave G at the 250 LOC ceiling).
+"""
+
+from typing import Annotated
+
+import typer
+
+from gapit import config
+from gapit.cmd_db_build import db_build_command
+from gapit.cmd_db_install import db_install_command
+from gapit.cmd_db_outdated import db_outdated_command
+from gapit.cmd_db_search import db_search_command
+from gapit.db_ops import db_list_entries, db_list_json, perform_fetch
+from gapit.dispatch import Datadir, dispatch
+
+
+def db_fetch_command(
+    name: Annotated[
+        str | None,
+        typer.Argument(
+            help=(
+                "Provider name (see: gapit db list). Omitted: install the default set "
+                "(card, vfdb) from their bundled snapshots."
+            ),
+        ),
+    ] = None,
+    datadir: Datadir = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite the database if it already exists."),
+    ] = False,
+    from_source: Annotated[
+        bool,
+        typer.Option(
+            "--from-source", help="Ignore bundled snapshots, download from upstream sources."
+        ),
+    ] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Silence stderr diagnostics.")] = False,
+    debug: Annotated[
+        bool,
+        typer.Option("--debug", help="Echo external command lines to stderr."),
+    ] = False,
+) -> None:
+    """Fetch and build provider database(s) into <datadir>/NAME.
+
+    NAME omitted installs every database in DEFAULT_DBS order; each success
+    prints its own one-line JSON receipt to stdout (stdout purity: receipts
+    are data).
+    """
+
+    def run() -> None:
+        for receipt in perform_fetch(
+            name, datadir, force=force, from_source=from_source, quiet=quiet, debug=debug
+        ):
+            typer.echo(receipt.model_dump_json())
+
+    dispatch(run)
+
+
+def db_list_command(
+    datadir: Datadir = None,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print machine-readable JSON instead of a table."),
+    ] = False,
+) -> None:
+    """List database providers and their installed state under the datadir."""
+
+    def run() -> None:
+        root = config.resolve_datadir(datadir)
+        if as_json:
+            typer.echo(db_list_json(root))
+            return
+        entries = db_list_entries(root)
+        typer.echo("PROVIDER\tSTATUS\tDBTYPE\tDESCRIPTION")
+        for entry in entries:
+            status = f"installed ({entry.records})" if entry.installed else "available"
+            typer.echo(f"{entry.name}\t{status}\t{entry.dbtype}\t{entry.description}")
+
+    dispatch(run)
+
+
+def register_db_command(app: typer.Typer) -> None:
+    """Attach the `db` command group (install, fetch, list) to the CLI app."""
+    db_app = typer.Typer(
+        help="Database acquisition and maintenance (provider fetch, verified local install).",
+        no_args_is_help=True,
+    )
+    db_app.command("install")(db_install_command)
+    db_app.command("build")(db_build_command)
+    db_app.command("fetch")(db_fetch_command)
+    db_app.command("list")(db_list_command)
+    db_app.command("outdated")(db_outdated_command)
+    db_app.command("search")(db_search_command)
+    app.add_typer(db_app, name="db")

gapit/cmd_db_build.py

@@ -0,0 +1,72 @@
+"""The `gapit db build` command: typer shell over the use-case
+(:mod:`gapit.db_build_ops`), which turns a user-supplied FASTA into a
+fully built gapit-native database (records.jsonl -> sequences + BLAST
+index + manifest, written last).
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from gapit.db_build_ops import Dbtype, perform_build
+from gapit.dispatch import dispatch
+
+
+def db_build_command(
+    name: Annotated[
+        str,
+        typer.Argument(help="Target database name (created under the datadir)."),
+    ],
+    fasta: Annotated[
+        Path,
+        typer.Argument(
+            help=(
+                "Input FASTA: plain, abricate ~~~, or gapit| headers, detected per"
+                " record (.gz/.bz2 accepted)."
+            ),
+        ),
+    ],
+    tsv: Annotated[
+        Path | None,
+        typer.Option(
+            "--tsv", help="Metadata TSV: header row with gene/accession/function columns."
+        ),
+    ] = None,
+    dbtype: Annotated[
+        Dbtype | None,
+        typer.Option("--dbtype", help="Force nucl or prot (default: auto-detect)."),
+    ] = None,
+    datadir: Annotated[
+        Path | None,
+        typer.Option(
+            "--datadir",
+            help="Database directory (default: $GAPIT_DATADIR, then ~/.local/share/gapit/db).",
+        ),
+    ] = None,
+    description: Annotated[
+        str,
+        typer.Option(
+            "--description",
+            help="Default product for records whose FASTA header has no description text.",
+        ),
+    ] = "",
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Overwrite the database if it already exists."),
+    ] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", help="Silence stderr diagnostics.")] = False,
+) -> None:
+    """Build a custom gapit-native database from a FASTA (+ optional TSV)."""
+
+    def run() -> None:
+        def warn(message: str) -> None:
+            if not quiet:
+                typer.echo(f"WARNING: {message}", err=True)
+
+        receipt = perform_build(
+            name, fasta, tsv, dbtype, description, datadir, force, warn=warn, quiet=quiet
+        )
+        typer.echo(receipt.model_dump_json())
+
+    dispatch(run)

gapit/cmd_db_install.py

@@ -0,0 +1,126 @@
+"""The verified LOCAL-FILE install path: `gapit db install` (from cmd_db.py).
+
+``db install`` checksum-verifies and atomically installs BYTES: SOURCE must
+be a path to an existing regular file; no network, no provider IDs, no
+archives, no manifests — streaming SHA256 + atomic copy, kept deliberately
+independent of db.py and the screening pipeline.
+
+Split from cmd_db.py in Wave G: cmd_db hit the 250 LOC ceiling when fetch
+gained the bundled-snapshot defaults; this path is self-contained and no
+test imports it directly (everything drives `gapit.cli.app`).
+"""
+
+import hashlib
+import os
+import re
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Annotated
+
+import typer
+from pydantic import BaseModel
+
+from gapit.dispatch import dispatch
+from gapit.errors import InputError, UsageError
+
+_SHA256_SHAPE = re.compile(r"[0-9a-fA-F]{64}")
+_CHUNK_BYTES = 1 << 20
+
+
+class FetchReceipt(BaseModel, frozen=True):
+    """One-line JSON success receipt printed to stdout (no biological data)."""
+
+    destination: str
+    sha256: str
+
+
+def _parse_sha256(raw: str) -> str:
+    """Lowercased digest if it is exactly 64 hex characters, else UsageError."""
+    if not _SHA256_SHAPE.fullmatch(raw):
+        raise UsageError(
+            "--sha256 must be exactly 64 hex characters",
+            code="USAGE_ERROR",
+            context={"sha256": raw},
+        )
+    return raw.lower()
+
+
+def install_verified(source: Path, target: Path, expected: str) -> FetchReceipt:
+    """Copy source to target with a streaming SHA256 check; atomic on success.
+
+    Bytes land in a NamedTemporaryFile in the target's parent (same
+    filesystem) and are os.replace()d over the target only after the digest
+    verifies, so any failure leaves an existing target untouched. The temp
+    file is removed on every error path.
+    """
+    if not source.is_file():
+        raise InputError(
+            f"source file not found or unreadable: {source}",
+            code="INPUT_NOT_FOUND",
+            context={"source": str(source)},
+        )
+    temp_path: Path | None = None
+    try:
+        with source.open("rb") as src, NamedTemporaryFile(dir=target.parent, delete=False) as temp:
+            temp_path = Path(temp.name)
+            hasher = hashlib.sha256()
+            while chunk := src.read(_CHUNK_BYTES):
+                hasher.update(chunk)
+                temp.write(chunk)
+            actual = hasher.hexdigest()
+            if actual != expected:
+                raise InputError(
+                    f"SHA256 mismatch for {source}",
+                    code="CHECKSUM_MISMATCH",
+                    context={
+                        "source": str(source),
+                        "expected": expected,
+                        "actual": actual,
+                    },
+                )
+        assert temp_path is not None
+        os.replace(temp_path, target)
+    except OSError as exc:
+        raise InputError(
+            f"cannot install {source} to {target}: {exc}",
+            code="FILE_IO_ERROR",
+            context={"source": str(source), "target": str(target)},
+        ) from exc
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+    return FetchReceipt(destination=str(target), sha256=expected)
+
+
+def db_install_command(
+    source: Annotated[
+        Path,
+        typer.Argument(
+            help="Local source file path (plain filesystem only; no URLs, no provider IDs)."
+        ),
+    ],
+    sha256: Annotated[
+        str,
+        typer.Option("--sha256", help="Expected SHA256 digest of the source (64 hex chars)."),
+    ],
+    output: Annotated[
+        Path,
+        typer.Option(
+            "--output", help="Destination path; replaced atomically only after verification."
+        ),
+    ],
+) -> None:
+    """Install a local file to --output after verifying its SHA256.
+
+    VERIFIED LOCAL-FILE INSTALLATION ONLY: this never fetches over the
+    network and knows nothing about database providers or sequence content —
+    it checksum-verifies and atomically installs bytes. On success a one-line
+    JSON receipt (destination, verified digest) is printed to stdout.
+    """
+
+    def run() -> None:
+        expected = _parse_sha256(sha256)
+        receipt = install_verified(source, output, expected)
+        typer.echo(receipt.model_dump_json())
+
+    dispatch(run)