gapit 0.2.2__py3-none-any.whl

gapit/formats/json.py

@@ -0,0 +1,309 @@
+"""Agent-facing JSON documents: gapit.report/1, gapit.list/1, gapit.version/1."""
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from gapit import __version__
+from gapit.hits import Hit
+from gapit.reads import GeneCoverage, ReadsParams, ReadsReport
+from gapit.report import Report, ScreeningParams
+
+
+class HitDocument(BaseModel, frozen=True):
+    """One hit — 1:1 with the TSV columns, snake_case, same string values."""
+
+    sequence: str
+    start: int
+    end: int
+    strand: str
+    gene: str
+    coverage: str
+    coverage_map: str
+    gaps: str
+    coverage_pct: float
+    identity_pct: float
+    database: str
+    accession: str
+    product: str
+    # "resistance" is frozen by gapit.report/1 (1:1 with the TSV RESISTANCE
+    # column); the value flows from Hit.function and carries functional
+    # categories for native DBs (Wave F1 renamed the internal slot only).
+    resistance: str
+
+
+class FileDocument(BaseModel, frozen=True):
+    """One screened file and its hits (zero hits -> empty list)."""
+
+    file: str
+    hits: list[HitDocument]
+
+
+class ParamsDocument(BaseModel, frozen=True):
+    """The screening parameters in effect."""
+
+    db: str
+    minid: float
+    mincov: float
+    threads: int
+
+
+class ToolDocument(BaseModel, frozen=True):
+    """Tool self-identification."""
+
+    name: str = "gapit"
+    version: str = __version__
+
+
+class ReportDocument(BaseModel, frozen=True):
+    """gapit.report/1 — the canonical machine-readable screening output."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    schema_name: Literal["gapit.report/1"] = Field(default="gapit.report/1", alias="schema")
+    tool: ToolDocument = ToolDocument()
+    created_at: str
+    params: ParamsDocument
+    files: list[FileDocument]
+
+
+class ListEntryDocument(BaseModel, frozen=True):
+    """One row of `gapit list --json`."""
+
+    name: str
+    sequences: int
+    dbtype: str
+    date: str
+
+
+class ListDocument(BaseModel, frozen=True):
+    """gapit.list/1."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    schema_name: Literal["gapit.list/1"] = Field(default="gapit.list/1", alias="schema")
+    databases: list[ListEntryDocument]
+
+
+class VersionDocument(BaseModel, frozen=True):
+    """gapit.version/1 — compact one-line self-description."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    schema_name: Literal["gapit.version/1"] = Field(default="gapit.version/1", alias="schema")
+    name: str = "gapit"
+    version: str
+
+
+class GeneCoverageDocument(BaseModel, frozen=True):
+    """One gene's presence call in reads mode."""
+
+    gene: str
+    database: str
+    accession: str
+    product: str
+    # "resistance" is frozen by gapit.reads/1; the value flows from
+    # GeneCoverage.function (functional categories for native DBs).
+    resistance: str
+    tlen: int
+    breadth_pct: float
+    mean_depth: float
+    reads_mapped: int
+    present: bool
+
+
+class ReadsFileDocument(BaseModel, frozen=True):
+    """One screened read set."""
+
+    reads: list[str]
+    genes: list[GeneCoverageDocument]
+
+
+class ReadsParamsDocument(BaseModel, frozen=True):
+    """Read-screening parameters in effect."""
+
+    db: str
+    read_type: str
+    min_breadth: float
+    threads: int
+
+
+class ReadsDocument(BaseModel, frozen=True):
+    """gapit.reads/1 — machine-readable read-screening output."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    schema_name: Literal["gapit.reads/1"] = Field(default="gapit.reads/1", alias="schema")
+    tool: ToolDocument = ToolDocument()
+    created_at: str
+    params: ReadsParamsDocument
+    files: list[ReadsFileDocument]
+
+
+class GeneCoverage2Document(BaseModel, frozen=True):
+    """One gene's presence call in reads/2 mode: the reads/1 fields plus the
+    alen-weighted mean per-alignment identity."""
+
+    gene: str
+    database: str
+    accession: str
+    product: str
+    resistance: str
+    tlen: int
+    breadth_pct: float
+    mean_depth: float
+    reads_mapped: int
+    present: bool
+    mean_identity_pct: float
+
+
+class Reads2FileDocument(BaseModel, frozen=True):
+    """One screened read set (reads/2)."""
+
+    reads: list[str]
+    genes: list[GeneCoverage2Document]
+
+
+class Reads2ParamsDocument(BaseModel, frozen=True):
+    """Read-screening parameters in effect (reads/2): reads/1 params plus the
+    opt-in alignment filters."""
+
+    db: str
+    read_type: str
+    min_breadth: float
+    threads: int
+    min_identity: float
+    min_mapq: int
+
+
+class Reads2Document(BaseModel, frozen=True):
+    """gapit.reads/2 — read-screening output under opt-in identity/MAPQ
+    alignment filtering (reads/1 stays the default and is frozen)."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    schema_name: Literal["gapit.reads/2"] = Field(default="gapit.reads/2", alias="schema")
+    tool: ToolDocument = ToolDocument()
+    created_at: str
+    params: Reads2ParamsDocument
+    files: list[Reads2FileDocument]
+
+
+def utc_timestamp(now: datetime) -> str:
+    """ISO-8601 UTC with a trailing Z, second precision."""
+    return now.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _hit_document(hit: Hit) -> HitDocument:
+    return HitDocument(
+        sequence=hit.sequence,
+        start=hit.start,
+        end=hit.end,
+        strand=hit.strand,
+        gene=hit.gene,
+        coverage=f"{hit.s_start}-{hit.s_end}/{hit.s_len}",
+        coverage_map=hit.coverage_map,
+        gaps=f"{hit.gap_openings}/{hit.gaps}",
+        coverage_pct=round(hit.coverage_pct, 2),
+        identity_pct=round(hit.identity_pct, 2),
+        database=hit.database,
+        accession=hit.accession,
+        product=hit.product,
+        resistance=hit.function,
+    )
+
+
+def render_json(reports: Iterable[Report], params: ScreeningParams, *, now: datetime) -> str:
+    """Serialize screening results as gapit.report/1 (indented, schema first)."""
+    document = ReportDocument(
+        created_at=utc_timestamp(now),
+        params=ParamsDocument(
+            db=params.db, minid=params.minid, mincov=params.mincov, threads=params.threads
+        ),
+        files=[
+            FileDocument(file=report.file, hits=[_hit_document(hit) for hit in report.hits])
+            for report in reports
+        ],
+    )
+    return document.model_dump_json(indent=2, by_alias=True)
+
+
+def _gene_coverage_document(gene: GeneCoverage) -> GeneCoverageDocument:
+    return GeneCoverageDocument(
+        gene=gene.gene,
+        database=gene.database,
+        accession=gene.accession,
+        product=gene.product,
+        resistance=gene.function,
+        tlen=gene.tlen,
+        breadth_pct=round(gene.breadth_pct, 2),
+        mean_depth=round(gene.mean_depth, 2),
+        reads_mapped=gene.reads_mapped,
+        present=gene.present,
+    )
+
+
+def render_reads_json(reports: Iterable[ReadsReport], params: ReadsParams, *, now: datetime) -> str:
+    """Serialize read-screening results as gapit.reads/1 (indented, schema first)."""
+    document = ReadsDocument(
+        created_at=utc_timestamp(now),
+        params=ReadsParamsDocument(
+            db=params.db,
+            read_type=params.read_type,
+            min_breadth=params.min_breadth,
+            threads=params.threads,
+        ),
+        files=[
+            ReadsFileDocument(
+                reads=list(report.reads),
+                genes=[_gene_coverage_document(gene) for gene in report.genes],
+            )
+            for report in reports
+        ],
+    )
+    return document.model_dump_json(indent=2, by_alias=True)
+
+
+def _gene_coverage2_document(gene: GeneCoverage) -> GeneCoverage2Document:
+    return GeneCoverage2Document(
+        gene=gene.gene,
+        database=gene.database,
+        accession=gene.accession,
+        product=gene.product,
+        resistance=gene.function,
+        tlen=gene.tlen,
+        breadth_pct=round(gene.breadth_pct, 2),
+        mean_depth=round(gene.mean_depth, 2),
+        reads_mapped=gene.reads_mapped,
+        present=gene.present,
+        mean_identity_pct=round(gene.mean_identity_pct, 2),
+    )
+
+
+def render_reads2_json(
+    reports: Iterable[ReadsReport], params: ReadsParams, *, now: datetime
+) -> str:
+    """Serialize filtered read-screening results as gapit.reads/2 (indented,
+    schema first; same shape as /1 plus the filter params and per-gene
+    mean_identity_pct)."""
+    document = Reads2Document(
+        created_at=utc_timestamp(now),
+        params=Reads2ParamsDocument(
+            db=params.db,
+            read_type=params.read_type,
+            min_breadth=params.min_breadth,
+            threads=params.threads,
+            min_identity=params.min_identity,
+            min_mapq=params.min_mapq,
+        ),
+        files=[
+            Reads2FileDocument(
+                reads=list(report.reads),
+                genes=[_gene_coverage2_document(gene) for gene in report.genes],
+            )
+            for report in reports
+        ],
+    )
+    return document.model_dump_json(indent=2, by_alias=True)

gapit/formats/md.py

@@ -0,0 +1,190 @@
+"""Human- and agent-readable Markdown reports (gapit.report/1, gapit.reads/1)."""
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+
+from gapit import __version__
+from gapit.reads import ReadsParams, ReadsReport
+from gapit.report import Report, ScreeningParams
+
+_COLUMNS = (
+    "Sequence",
+    "Start",
+    "End",
+    "Strand",
+    "Gene",
+    "Coverage",
+    "Map",
+    "Gaps",
+    "%Coverage",
+    "%Identity",
+    "Database",
+    "Accession",
+    "Product",
+    "Resistance",
+)
+
+
+def _md_cell(value: str) -> str:
+    """Escape Markdown table metacharacters so cells cannot break the table
+    (victors gene ids like ``gi|115534241:2616-3152`` contain pipes)."""
+    return value.replace("\\", "\\\\").replace("|", "\\|")
+
+
+def render_markdown(reports: Iterable[Report], params: ScreeningParams, *, now: datetime) -> str:
+    """Render screening results as deterministic Markdown: YAML frontmatter,
+    one section per file, stable table columns."""
+    files = list(reports)
+    total_hits = sum(len(report.hits) for report in files)
+    lines: list[str] = [
+        "---",
+        "schema: gapit.report/1",
+        f"tool: gapit {__version__}",
+        f"created_at: {now.astimezone(UTC).strftime('%Y-%m-%dT%H:%M:%SZ')}",
+        f"db: {params.db}",
+        f"minid: {params.minid}",
+        f"mincov: {params.mincov}",
+        f"threads: {params.threads}",
+        f"files: {len(files)}",
+        f"hits: {total_hits}",
+        "---",
+        "",
+        "# gapit screening report",
+        "",
+    ]
+    for report in files:
+        lines.append(f"## `{report.file}`")
+        lines.append("")
+        if not report.hits:
+            lines.append("_No hits._")
+            lines.append("")
+            continue
+        lines.append("| " + " | ".join(_COLUMNS) + " |")
+        lines.append("|" + "---|" * len(_COLUMNS))
+        for hit in report.hits:
+            cells = (
+                hit.sequence,
+                str(hit.start),
+                str(hit.end),
+                hit.strand,
+                hit.gene,
+                f"{hit.s_start}-{hit.s_end}/{hit.s_len}",
+                hit.coverage_map,
+                f"{hit.gap_openings}/{hit.gaps}",
+                f"{hit.coverage_pct:.2f}",
+                f"{hit.identity_pct:.2f}",
+                hit.database,
+                hit.accession,
+                hit.product,
+                hit.function,
+            )
+            lines.append("| " + " | ".join(_md_cell(cell) for cell in cells) + " |")
+        lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+_READS_COLUMNS = (
+    "Gene",
+    "Breadth%",
+    "Depth",
+    "Reads",
+    "Present",
+    "Database",
+    "Accession",
+    "Product",
+    "Resistance",
+)
+
+_READS2_COLUMNS = (*_READS_COLUMNS, "Identity%")
+
+
+def _render_reads_markdown(
+    reports: Iterable[ReadsReport],
+    params: ReadsParams,
+    *,
+    now: datetime,
+    schema: str,
+    columns: tuple[str, ...],
+    with_identity: bool,
+) -> str:
+    """Shared reads-report Markdown core; gapit.reads/2 adds the two filter
+    lines to the frontmatter and an Identity% cell per gene."""
+    files = list(reports)
+    genes_found = sum(1 for report in files for gene in report.genes if gene.present)
+    lines: list[str] = [
+        "---",
+        f"schema: {schema}",
+        f"tool: gapit {__version__}",
+        f"created_at: {now.astimezone(UTC).strftime('%Y-%m-%dT%H:%M:%SZ')}",
+        f"db: {params.db}",
+        f"read_type: {params.read_type}",
+        f"min_breadth: {params.min_breadth}",
+        f"threads: {params.threads}",
+    ]
+    if with_identity:
+        lines.append(f"min_identity: {params.min_identity}")
+        lines.append(f"min_mapq: {params.min_mapq}")
+    lines += [
+        f"files: {len(files)}",
+        f"genes_found: {genes_found}",
+        "---",
+        "",
+        "# gapit read screening report",
+        "",
+    ]
+    for report in files:
+        lines.append(f"## `{', '.join(report.reads)}`")
+        lines.append("")
+        if not report.genes:
+            lines.append("_No genes detected._")
+            lines.append("")
+            continue
+        lines.append("| " + " | ".join(columns) + " |")
+        lines.append("|" + "---|" * len(columns))
+        for gene in report.genes:
+            cells = (
+                gene.gene,
+                f"{gene.breadth_pct:.2f}",
+                f"{gene.mean_depth:.2f}",
+                str(gene.reads_mapped),
+                "yes" if gene.present else "no",
+                gene.database,
+                gene.accession,
+                gene.product,
+                gene.function,
+            )
+            if with_identity:
+                cells += (f"{gene.mean_identity_pct:.2f}",)
+            lines.append("| " + " | ".join(_md_cell(cell) for cell in cells) + " |")
+        lines.append("")
+    return "\n".join(lines) + "\n"
+
+
+def render_reads_markdown(
+    reports: Iterable[ReadsReport], params: ReadsParams, *, now: datetime
+) -> str:
+    """Render read-screening results as deterministic Markdown."""
+    return _render_reads_markdown(
+        reports,
+        params,
+        now=now,
+        schema="gapit.reads/1",
+        columns=_READS_COLUMNS,
+        with_identity=False,
+    )
+
+
+def render_reads2_markdown(
+    reports: Iterable[ReadsReport], params: ReadsParams, *, now: datetime
+) -> str:
+    """Render filtered read-screening results as deterministic Markdown
+    (gapit.reads/2): the reads/1 shape plus the filter thresholds in
+    frontmatter and an Identity% column per gene."""
+    return _render_reads_markdown(
+        reports,
+        params,
+        now=now,
+        schema="gapit.reads/2",
+        columns=_READS2_COLUMNS,
+        with_identity=True,
+    )

gapit/formats/schemas.py

@@ -0,0 +1,30 @@
+"""The schema registry: every document name ``gapit schema`` can introspect.
+
+Lives beside the document models but one level up: it needs the summary
+document (formats/summary.py) and the error envelope (errors.py), and
+formats/summary.py already imports from formats/json.py — so this module, not
+formats/json.py, is the cycle-free single home. Insertion order is part of the
+public surface (``gapit schema`` unknown-name message iterates it).
+"""
+
+from pydantic import BaseModel
+
+from gapit.errors import ErrorEnvelope
+from gapit.formats.json import (
+    ListDocument,
+    Reads2Document,
+    ReadsDocument,
+    ReportDocument,
+    VersionDocument,
+)
+from gapit.formats.summary import SummaryDocument
+
+SCHEMA_MODELS: dict[str, type[BaseModel]] = {
+    "report": ReportDocument,
+    "reads": ReadsDocument,
+    "reads2": Reads2Document,
+    "summary": SummaryDocument,
+    "list": ListDocument,
+    "error": ErrorEnvelope,
+    "version": VersionDocument,
+}

gapit/formats/summary.py

@@ -0,0 +1,103 @@
+"""Summary output formats: abricate-parity TSV/CSV, gapit.summary/1 JSON, Markdown."""
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from gapit import __version__
+from gapit.formats.json import ToolDocument, utc_timestamp
+from gapit.summary import ABSENT, FIELDSEP, SummaryMatrix
+
+
+class SummaryParamsDocument(BaseModel, frozen=True):
+    """The summary parameters in effect (metric is explicit)."""
+
+    metric: Literal["%COVERAGE", "%IDENTITY"]
+    nopath: bool
+
+
+class SummaryRowDocument(BaseModel, frozen=True):
+    """One matrix row: label, distinct-gene count, per-gene value lists."""
+
+    file: str
+    num_found: int
+    cells: dict[str, list[str]]
+
+
+class SummaryDocument(BaseModel, frozen=True):
+    """gapit.summary/1 — machine-readable summary matrix."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    schema_name: Literal["gapit.summary/1"] = Field(default="gapit.summary/1", alias="schema")
+    tool: ToolDocument = ToolDocument()
+    created_at: str
+    params: SummaryParamsDocument
+    genes: list[str]
+    rows: list[SummaryRowDocument]
+
+
+def format_summary_tsv(matrix: SummaryMatrix, *, csv: bool) -> str:
+    """Render the matrix in abricate --summary shape: '#FILE NUM_FOUND <genes>'
+    header, one row per input, ';' cells, '.' absent. Line = sep.join + '\\n'."""
+    sep = "," if csv else "\t"
+    lines = [sep.join(("#FILE", "NUM_FOUND", *matrix.genes))]
+    for row in matrix.rows:
+        cells = [
+            FIELDSEP.join(row.cells[gene]) if gene in row.cells else ABSENT for gene in matrix.genes
+        ]
+        lines.append(sep.join((row.file, str(row.num_found), *cells)))
+    return "".join(line + "\n" for line in lines)
+
+
+def render_summary_json(matrix: SummaryMatrix, *, now: datetime) -> str:
+    """Serialize the matrix as gapit.summary/1 (indented, schema first)."""
+    document = SummaryDocument(
+        created_at=utc_timestamp(now),
+        params=SummaryParamsDocument(metric=matrix.params.metric, nopath=matrix.params.nopath),
+        genes=list(matrix.genes),
+        rows=[
+            SummaryRowDocument(
+                file=row.file,
+                num_found=row.num_found,
+                cells={gene: list(values) for gene, values in row.cells.items()},
+            )
+            for row in matrix.rows
+        ],
+    )
+    return document.model_dump_json(indent=2, by_alias=True)
+
+
+def _md_cell(value: str) -> str:
+    """Escape Markdown table metacharacters so cells cannot break the table."""
+    return value.replace("\\", "\\\\").replace("|", "\\|")
+
+
+def render_summary_md(matrix: SummaryMatrix, *, now: datetime) -> str:
+    """Render the matrix as deterministic Markdown: YAML frontmatter, then a
+    File x gene table with escaped cells ('.' = absent, ';' = multi-value)."""
+    columns = ("File", "Num found", *matrix.genes)
+    lines: list[str] = [
+        "---",
+        "schema: gapit.summary/1",
+        f"tool: gapit {__version__}",
+        f"created_at: {utc_timestamp(now)}",
+        f"metric: '{matrix.params.metric}'",
+        f"nopath: {str(matrix.params.nopath).lower()}",
+        f"files: {len(matrix.rows)}",
+        f"genes: {len(matrix.genes)}",
+        "---",
+        "",
+        "# gapit summary matrix",
+        "",
+        "| " + " | ".join(_md_cell(column) for column in columns) + " |",
+        "|" + "---|" * len(columns),
+    ]
+    for row in matrix.rows:
+        cells = [
+            _md_cell(FIELDSEP.join(row.cells[gene])) if gene in row.cells else ABSENT
+            for gene in matrix.genes
+        ]
+        lines.append("| " + " | ".join((_md_cell(row.file), str(row.num_found), *cells)) + " |")
+    return "\n".join(lines) + "\n"

gapit/formats/tsv.py

@@ -0,0 +1,45 @@
+"""abricate-byte-compatible TSV/CSV rendering of Reports (SPEC.md §5)."""
+
+from collections.abc import Iterable
+from pathlib import PurePath
+
+from gapit.report import Report
+
+HEADER = (
+    "#FILE\tSEQUENCE\tSTART\tEND\tSTRAND\tGENE\tCOVERAGE\tCOVERAGE_MAP\tGAPS\t"
+    "%COVERAGE\t%IDENTITY\tDATABASE\tACCESSION\tPRODUCT\tRESISTANCE"
+)
+
+
+def format_tsv(reports: Iterable[Report], *, csv: bool, noheader: bool, nopath: bool) -> str:
+    """Render reports as abricate-format lines: one header (unless noheader),
+    then one line per hit per report in report order. Line = sep.join(fields)
+    + "\\n"; fields never contain the separator (product cleanup strips commas).
+    """
+    sep = "," if csv else "\t"
+    lines: list[str] = [] if noheader else [HEADER.replace("\t", sep)]
+    for report in reports:
+        file_column = PurePath(report.file).name if nopath else report.file
+        for hit in report.hits:
+            lines.append(
+                sep.join(
+                    (
+                        file_column,
+                        hit.sequence,
+                        str(hit.start),
+                        str(hit.end),
+                        hit.strand,
+                        hit.gene,
+                        f"{hit.s_start}-{hit.s_end}/{hit.s_len}",
+                        hit.coverage_map,
+                        f"{hit.gap_openings}/{hit.gaps}",
+                        f"{hit.coverage_pct:.2f}",
+                        f"{hit.identity_pct:.2f}",
+                        hit.database,
+                        hit.accession,
+                        hit.product,
+                        hit.function,
+                    )
+                )
+            )
+    return "".join(line + "\n" for line in lines)