gspec 0.8.0__py3-none-any.whl

gapit/__init__.py

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

gapit/blast.py

@@ -0,0 +1,291 @@
+"""BLAST invocation, tabular parsing, and the screening pipeline (SPEC.md §3)."""
+
+import re
+import shlex
+import subprocess
+import sys
+from collections.abc import Iterable
+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.fragments import merge_fragment_hits
+from gapit.gene_floors import apply_hit_floors, gene_floors
+from gapit.gseek_engine import engine, run_blast_gseek
+from gapit.hits import process_rows, process_rows_with_partials
+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")
+    try:
+        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],
+        )
+    except (TypeError, ValueError) as exc:
+        raise GapitError(
+            f"can not parse BLAST row (numeric field): {line!r}",
+            code="BLAST_PARSE_FAILED",
+        ) from exc
+
+
+def ensure_blast() -> None:
+    """Require blastn >= 2.2.30 on PATH (SPEC.md §3 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)
+    switch = engine()
+    mode = switch.mode.value
+    if debug:
+        sys.stderr.write(f"gspec: normalize: {query} ({fmt.value})\n")
+        if mode in {"legacy", "shadow"}:
+            sys.stderr.write(f"gspec: run: {shlex.join(argv)}\n")
+
+    def legacy_rows() -> list[BlastRow]:
+        output = _pipeline(fasta_text, argv)
+        return [parse_blast_row(line) for line in output.splitlines() if line.strip()]
+
+    def gseek_rows() -> list[BlastRow]:
+        return run_blast_gseek(fasta_text, database, params, dbtype=dbtype, debug=debug)
+
+    return switch.run(legacy_rows, gseek_rows)
+
+
+def report_from_rows(
+    rows: Iterable[BlastRow],
+    query: Path,
+    database: Database,
+    params: ScreeningParams,
+    *,
+    merge_fragments: bool = False,
+) -> Report:
+    """Fold typed BLAST rows into one sorted Report.
+
+    Shared by the per-file and batch gseek paths; the caller owns the BLAST
+    run and the per-run ``ensure_blast``/dbtype gates.
+    """
+    floors = gene_floors(database)
+    if merge_fragments:
+        hits, partials = process_rows_with_partials(
+            rows, mincov=params.mincov, default_db=params.db
+        )
+        if floors is not None:
+            hits = apply_hit_floors(hits, floors)
+            partials = apply_hit_floors(partials, floors)
+        hits = merge_fragment_hits(hits, partials, mincov=params.mincov)
+    else:
+        hits = process_rows(rows, mincov=params.mincov, default_db=params.db)
+        if floors is not None:
+            hits = apply_hit_floors(hits, floors)
+    ordered = sorted(hits, key=lambda hit: (hit.sequence, hit.start))
+    return Report(file=str(query), hits=tuple(ordered))
+
+
+def screen_file(
+    query: Path,
+    database: Database,
+    params: ScreeningParams,
+    *,
+    dbtype: Literal["nucl", "prot"],
+    debug: bool = False,
+    merge_fragments: 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. With
+    ``merge_fragments`` (opt-in gspec extension), sub-mincov dedup survivors
+    are folded into one hit per gene when their union coverage reaches mincov.
+    """
+    rows = run_blastn(query, database, params, dbtype=dbtype, debug=debug)
+    return report_from_rows(rows, query, database, params, merge_fragments=merge_fragments)

gapit/bundled.py

@@ -0,0 +1,240 @@
+"""Bundled databases: license-clean content shipped inside the wheel.
+
+A bundled database is a directory ``gapit/data/dbs/<name>/`` holding
+``sequences``, a ``bundled.json`` metadata file, and kind-dependent
+companions: gene bundles an optional ``typing.json`` and ``floors.json``
+(gapit.floors/1), cluster bundles a REQUIRED ``features.json``
+(gapit.features/1) plus their typing document. Materialization replays the
+standard build pipelines into the user's datadir — the gene path through
+:func:`gapit.db_build_ops.perform_build`, the cluster path through
+:func:`gapit.bundled_cluster.materialize_cluster_bundle` (which rebuilds
+from the committed locus FASTA + resolved feature table via
+:func:`gapit.clusterbuild.build_cluster_database`) — deterministic, zero
+network, so a bundled database is ready at install time with no
+``db fetch``.
+
+Only gspec-curated content with clean provenance may live here (the wheel
+is MIT): our own panels and public-domain / permissive sources, never GPL,
+non-commercial, or third-party provider snapshots whose redistribution terms
+are uncertain. Every provider database — ncbi, card, ecoh, resfinder, ... —
+is fetch-on-demand only, even when its upstream license would permit a
+snapshot. The typed cluster snapshot vpa_ok is a pure built-in (no provider
+behind it) carrying the resolved gapit.features/1 table a completed /2
+build produced; a refresh means a new snapshot riding a wheel release.
+The gene build pipeline re-headers any bundled FASTA into gapit/v1 like a
+custom build, so header styles round-trip.
+
+Bundling is the exception, not the pattern, and every new bundle clears
+two gates in order (the full policy lives in AGENTS.md §6): the license
+gate above, then the size gate — the whole bundled root stays within a
+30 MiB wheel budget, mechanically enforced by tests/test_bundled.py.
+Past the budget, split a separate data wheel or keep the database
+fetch-on-demand instead of inflating the ceiling.
+"""
+
+import shutil
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel
+
+from gapit import config
+from gapit.bundled_cluster import materialize_cluster_bundle
+from gapit.db_build_ops import perform_build
+from gapit.db_info_models import DbGuidance
+from gapit.errors import DatabaseError
+from gapit.fasta import iter_fasta
+from gapit.proctools import note
+
+BUNDLED_ROOT = Path(__file__).resolve().parent / "data" / "dbs"
+
+
+class BundledMetadata(BaseModel, frozen=True):
+    """Parsed ``bundled.json`` — the listing-facing facts for one bundle.
+
+    ``snapshotted`` is the ISO date the wheel copy was produced from
+    upstream (provenance for humans; ``db fetch`` refreshes past it).
+    ``kind`` routes materialization (gene vs cluster pipeline; cluster
+    bundles additionally require ``features.json``). ``license`` and
+    ``note`` carry content provenance into the materialized manifest
+    (cluster bundles); they default to empty so the gene bundles'
+    metadata stays minimal. ``guidance`` is what `gspec db info` reports:
+    the literature references, the intended usage recipe, and the caveats
+    a caller must not skip.
+    """
+
+    name: str
+    description: str
+    vendor: str
+    dbtype: Literal["nucl", "prot"]
+    kind: Literal["gene", "cluster"] = "gene"
+    snapshotted: str
+    license: str = ""
+    note: str = ""
+    guidance: DbGuidance = DbGuidance()
+
+
+class BundledDatabase(BaseModel, frozen=True):
+    """One bundled database directory plus its parsed metadata."""
+
+    metadata: BundledMetadata
+    path: Path
+
+    @property
+    def name(self) -> str:
+        return self.metadata.name
+
+    @property
+    def sequences_path(self) -> Path:
+        return self.path / "sequences"
+
+    @property
+    def typing_path(self) -> Path | None:
+        """The bundled typing spec, when the database ships one."""
+        typing = self.path / "typing.json"
+        return typing if typing.is_file() else None
+
+    @property
+    def floors_path(self) -> Path | None:
+        """The bundled gapit.floors/1 sidecar, when the database ships one."""
+        floors = self.path / "floors.json"
+        return floors if floors.is_file() else None
+
+    @property
+    def screen_path(self) -> Path | None:
+        """The bundled gapit.screen/1 defaults, when the database ships one."""
+        screen = self.path / "screen.json"
+        return screen if screen.is_file() else None
+
+    @property
+    def features_path(self) -> Path | None:
+        """The bundled gapit.features/1 table — required (and checked at
+        discovery) for cluster bundles, absent from gene bundles."""
+        features = self.path / "features.json"
+        return features if features.is_file() else None
+
+    @property
+    def profile_path(self) -> Path | None:
+        """The optional gapit.cluster_profile/1 sidecar for cluster bundles."""
+        profile = self.path / "cluster.json"
+        return profile if profile.is_file() else None
+
+    @property
+    def gene_families_path(self) -> Path | None:
+        """The optional gapit.gene_families/1 sidecar for cluster bundles."""
+        families = self.path / "gene_families.json"
+        return families if families.is_file() else None
+
+    @property
+    def markers_path(self) -> Path | None:
+        """The optional marker metadata sidecar for a gene bundle."""
+        markers = self.path / "markers.json"
+        return markers if markers.is_file() else None
+
+    @property
+    def serotype_path(self) -> Path | None:
+        """The optional gapit.serotype/1 profile sidecar for a gene bundle."""
+        serotype = self.path / "serotype.json"
+        return serotype if serotype.is_file() else None
+
+
+def bundled_databases() -> list[BundledDatabase]:
+    """Every bundled database, sorted by name. A directory qualifies when it
+    carries both ``sequences`` and ``bundled.json`` — plus ``features.json``
+    when the metadata declares ``kind: cluster`` (a cluster bundle without
+    its feature table cannot materialize; typed error, no silent
+    degradation). Malformed metadata propagates, and a wheel without the
+    data dir lists nothing."""
+    if not BUNDLED_ROOT.is_dir():
+        return []
+    databases: list[BundledDatabase] = []
+    for child in sorted(BUNDLED_ROOT.iterdir()):
+        metadata_path = child / "bundled.json"
+        if not (child.is_dir() and (child / "sequences").is_file() and metadata_path.is_file()):
+            continue
+        try:
+            metadata = BundledMetadata.model_validate_json(
+                metadata_path.read_text(encoding="utf-8")
+            )
+        except (OSError, UnicodeDecodeError, ValueError) as exc:
+            raise DatabaseError(
+                f"bundled metadata is malformed: {metadata_path}: {exc}",
+                code="BUNDLED_MALFORMED",
+                context={"db": child.name, "file": str(metadata_path)},
+            ) from exc
+        if metadata.kind == "cluster" and not (child / "features.json").is_file():
+            raise DatabaseError(
+                f"bundled cluster database {metadata.name} lacks features.json",
+                code="BUNDLED_MALFORMED",
+                context={"db": metadata.name},
+            )
+        databases.append(BundledDatabase(metadata=metadata, path=child))
+    return databases
+
+
+def bundled_names() -> list[str]:
+    """Sorted names of every bundled database."""
+    return [database.name for database in bundled_databases()]
+
+
+def find_bundled(name: str) -> BundledDatabase | None:
+    """The bundled database called ``name``, or None when none ships."""
+    return next((database for database in bundled_databases() if database.name == name), None)
+
+
+def materialize_bundled(name: str, datadir: Path, *, quiet: bool = True) -> None:
+    """Build a bundled database into ``<datadir>/name`` via its kind's
+    standard pipeline (records.jsonl/sequences for gene bundles, locus
+    FASTA + features.json for cluster bundles; BLAST index, typing copy,
+    manifest stamped ``source: "bundled"`` — written last, as always).
+    Zero network: every input travels inside the wheel.
+
+    An already-materialized database (manifest present) is left untouched —
+    callers short-circuit on the manifest, and each path's
+    DB_ALREADY_EXISTS guard turns a racing double build into a typed error.
+    """
+    bundled = find_bundled(name)
+    if bundled is None:
+        raise DatabaseError(
+            f"unknown bundled database: {name}",
+            code="BUNDLED_NOT_FOUND",
+            context={"db": name},
+        )
+    if bundled.metadata.kind == "cluster":
+        materialize_cluster_bundle(bundled, datadir, quiet=quiet)
+        return
+    n_records = sum(1 for _ in iter_fasta(bundled.sequences_path))
+    note(quiet, f"materializing bundled database {name} ({n_records} records) into {datadir}")
+    perform_build(
+        name,
+        bundled.sequences_path,
+        None,
+        None,
+        bundled.metadata.description,
+        datadir,
+        force=False,
+        warn=lambda message: note(quiet, message),
+        quiet=True,
+        typing=bundled.typing_path,
+        floors=bundled.floors_path,
+        screen=bundled.screen_path,
+        source="bundled",
+    )
+    if bundled.markers_path is not None:
+        shutil.copyfile(bundled.markers_path, datadir / name / "markers.json")
+    if bundled.serotype_path is not None:
+        shutil.copyfile(bundled.serotype_path, datadir / name / "serotype.json")
+
+
+def resolve_screen_datadir(cli_value: Path | None, db_name: str) -> Path:
+    """``resolve_datadir`` for the screening lookup — except that a MISSING
+    datadir is bootstrapped when (and only when) the requested database is
+    bundled: the zero-network first-use path must work on a fresh machine
+    where ``~/.local/share/gspec/db`` does not exist yet. Every other
+    missing-datadir case keeps the typed DATADIR_NOT_FOUND error."""
+    try:
+        return config.resolve_datadir(cli_value)
+    except DatabaseError as exc:
+        if exc.code != "DATADIR_NOT_FOUND" or find_bundled(db_name) is None:
+            raise
+        return config.ensure_datadir(cli_value)

gapit/bundled_cluster.py

@@ -0,0 +1,130 @@
+"""Kind-aware materialization for CLUSTER bundles (the bundled.py sibling).
+
+A cluster bundle ships its build INPUTS committed: the locus FASTA plus the
+``gapit.features/1`` table already carrying RESOLVED gene ids (the snapshot
+was produced by a completed gapit.typing/2 build, so its rules reference
+the resolved locus_tag-style ids). Materialization reconstructs
+:class:`LocusSequence` objects from those artifacts and replays
+:func:`gapit.clusterbuild.build_cluster_database` — the entry taking
+pre-parsed loci, the SAME code a provider fetch runs — into the user's
+datadir, deterministic and zero network.
+
+Gene-id resolution deliberately does NOT re-run: the bundled feature table
+is already resolved, and re-running would be a no-op at best. The typing
+document IS validated against the reconstructed loci (mirroring the build
+path's pre-write gate), and the screen-time /2 guard re-checks afterwards
+— belt and braces, like the fetch path.
+"""
+
+import shutil
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pydantic import ValidationError
+
+from gapit.clusterbuild import build_cluster_database
+from gapit.db_txn import staged_database
+from gapit.errors import DatabaseError
+from gapit.fasta import iter_fasta
+from gapit.gbfeatures import FeaturesDocument, LocusSequence
+from gapit.proctools import note
+from gapit.typing_models import (
+    read_typing_document,
+    typing_schema_of,
+    validate_references,
+)
+
+if TYPE_CHECKING:  # bundled.py imports this module at runtime; no cycle.
+    from gapit.bundled import BundledDatabase
+
+
+def _malformed(db_name: str, reason: str) -> DatabaseError:
+    """The broken-wheel-cluster-bundle failure: located, stable code."""
+    return DatabaseError(
+        f"bundled cluster database {db_name} is malformed ({reason})",
+        code="BUNDLED_MALFORMED",
+        context={"db": db_name, "reason": reason},
+    )
+
+
+def _reconstruct_loci(bundled: "BundledDatabase") -> list[LocusSequence]:
+    """The bundle's committed artifacts back into LocusSequence objects.
+
+    features.json supplies the feature tables (loci in document order), the
+    FASTA the sequences (one bare-id record per locus); every locus must
+    pair with the same-order same-id record — the reconstruction mirror of
+    the build self-check, BUNDLED_MALFORMED on any drift."""
+    features_path = bundled.path / "features.json"
+    try:
+        document = FeaturesDocument.model_validate_json(features_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError) as exc:
+        raise _malformed(bundled.name, f"unreadable features.json: {exc}") from exc
+    except ValidationError as exc:
+        raise _malformed(bundled.name, f"unparseable features.json: {exc}") from exc
+    records = list(iter_fasta(bundled.sequences_path))
+    if len(records) != len(document.loci):
+        raise _malformed(
+            bundled.name,
+            f"{len(document.loci)} loci but {len(records)} sequence records",
+        )
+    loci: list[LocusSequence] = []
+    for locus, record in zip(document.loci, records, strict=True):
+        if locus.id != record.id:
+            raise _malformed(bundled.name, f"locus {locus.id!r} paired with record {record.id!r}")
+        loci.append(LocusSequence(features=locus, sequence=record.sequence))
+    return loci
+
+
+def materialize_cluster_bundle(
+    bundled: "BundledDatabase", datadir: Path, *, quiet: bool = True
+) -> None:
+    """Build a cluster-kind bundle into ``<datadir>/name`` through the
+    cluster pipeline (locus FASTA, features.json, typing copy, BLAST index,
+    manifest stamped ``source: "bundled"`` and written last, as always).
+    The typing spec validates BEFORE any artifact is written, so a spec
+    drifting from the committed table fails with no half-built database;
+    an existing manifest is a typed DB_ALREADY_EXISTS (the racing
+    double-build guard perform_build gives the gene path)."""
+    name = bundled.name
+    db_dir = datadir / name
+    if (db_dir / "gapit-manifest.json").is_file():
+        raise DatabaseError(
+            f"won't overwrite existing database {name} (use --force)",
+            code="DB_ALREADY_EXISTS",
+            context={"db": name},
+        )
+    n_loci = sum(1 for _ in iter_fasta(bundled.sequences_path))
+    note(quiet, f"materializing bundled database {name} ({n_loci} loci) into {datadir}")
+    loci = _reconstruct_loci(bundled)
+    typing_schema = ""
+    if bundled.typing_path is not None:
+        document = read_typing_document(bundled.typing_path)
+        validate_references(
+            document, FeaturesDocument(loci=tuple(locus.features for locus in loci))
+        )
+        typing_schema = typing_schema_of(bundled.typing_path)
+    with staged_database(db_dir) as build_dir:
+        if (db_dir / "gapit-manifest.json").is_file():
+            raise DatabaseError(
+                f"won't overwrite existing database {name} (use --force)",
+                code="DB_ALREADY_EXISTS",
+                context={"db": name},
+            )
+        if bundled.profile_path is not None:
+            shutil.copyfile(bundled.profile_path, build_dir / "cluster.json")
+        if bundled.gene_families_path is not None:
+            shutil.copyfile(bundled.gene_families_path, build_dir / "gene_families.json")
+        build_cluster_database(
+            build_dir,
+            name=name,
+            loci=loci,
+            typing=bundled.typing_path,
+            source_urls=("local",),
+            fetched_at=datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            typing_schema=typing_schema,
+            quiet=True,  # the materializing note above is the only stderr line (gene-path parity)
+            content_license=bundled.metadata.license,
+            content_note=bundled.metadata.note,
+            source="bundled",
+        )