pufprobe 0.5.0__py3-none-any.whl

pufprobe/__init__.py

@@ -0,0 +1,10 @@
+"""PUFprobe: second-stage functional inference for hypothetical proteins.
+
+PUFprobe consumes the output of Bakta, Prokka or NCBI PGAP and adds a
+second-stage inference layer for CDS records annotated as hypothetical
+protein, uncharacterized protein or domains of unknown function.
+"""
+
+__version__ = "0.4.0"
+
+__all__ = ["__version__"]

pufprobe/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m pufprobe`` as an alias for the console script."""
+
+from pufprobe.cli import cli
+
+if __name__ == "__main__":
+    cli()

pufprobe/annotate/__init__.py

@@ -0,0 +1 @@
+"""annotate stage: backfill predictions into GFF3/GBK/FAA files."""

pufprobe/annotate/backfill.py

@@ -0,0 +1,247 @@
+"""Backfill high-confidence predictions into new annotation files.
+
+Original GFF3 / GenBank / FASTA files are only ever opened for reading.  For
+every sample the stage writes parallel files under ``09_annotate``:
+
+* ``<sample>.pufprobe.gff3`` — every line copied verbatim except matched CDS
+  lines, whose ``product`` attribute is replaced, ``Dbxref`` entries appended
+  and a ``PUFprobe=...`` evidence note added;
+* ``<sample>.pufprobe.gbk``  — minimal line-based GenBank rewrite when a
+  GenBank source exists (``/product`` replaced, ``/db_xref`` and ``/note``
+  appended);
+* ``<sample>.pufprobe.faa``  — protein records renamed via
+  :func:`pufprobe.io_utils.write_fasta`.
+
+A ``changes.tsv`` ledger records every edit.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from pufprobe.io_utils import read_fasta, write_fasta
+from pufprobe.logging_utils import get_logger
+from pufprobe.models import ProteinPrediction, Sample, TermPrediction
+
+log = get_logger("annotate.backfill")
+
+
+def select_terms(
+    predictions: List[ProteinPrediction], min_confidence: float
+) -> Dict[str, Dict[str, Any]]:
+    """Map global key -> accepted edit info for terms >= min_confidence."""
+    accepted: Dict[str, Dict[str, Any]] = {}
+    for pred in predictions:
+        terms = sorted(
+            (t for t in pred.terms if t.confidence >= min_confidence),
+            key=lambda t: (-t.confidence, t.term_type, t.term_id),
+        )
+        if not terms:
+            continue
+        groups = sorted({g for t in terms for g in t.evidence_groups})
+        accepted[pred.key] = {
+            "new_product": " / ".join(t.term_name for t in terms),
+            "confidence": max(t.confidence for t in terms),
+            "evidence_groups": groups,
+            "term_ids": [f"{t.term_type}:{t.term_id}" for t in terms],
+            "terms": terms,
+        }
+    return accepted
+
+
+# ---------------------------------------------------------------------------
+# GFF3
+# ---------------------------------------------------------------------------
+def parse_gff_attributes(attr_string: str) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for part in attr_string.split(";"):
+        if not part:
+            continue
+        key, _, value = part.partition("=")
+        out[key] = value
+    return out
+
+
+def rewrite_gff3(
+    src: Path,
+    out: Path,
+    sample_id: str,
+    accepted: Dict[str, Dict[str, Any]],
+) -> List[Dict[str, str]]:
+    """Copy ``src`` to ``out``, editing matched CDS lines. Returns change rows."""
+    changes: List[Dict[str, str]] = []
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with src.open("r", encoding="utf-8", errors="replace") as handle:
+        lines = handle.read().splitlines()
+
+    rewritten: List[str] = []
+    for line in lines:
+        if not line or line.startswith("#"):
+            rewritten.append(line)
+            continue
+        fields = line.split("\t")
+        if len(fields) < 9 or fields[2] != "CDS":
+            rewritten.append(line)
+            continue
+        attrs = parse_gff_attributes(fields[8])
+        locus = attrs.get("locus_tag") or attrs.get("ID", "")
+        key = f"{sample_id}@{locus}"
+        if key not in accepted:
+            rewritten.append(line)
+            continue
+
+        edit = accepted[key]
+        old_product = attrs.get("product", "")
+        attrs["product"] = edit["new_product"]
+
+        dbxref = [x for x in attrs.get("Dbxref", "").split(",") if x]
+        for term_id in edit["term_ids"]:
+            if term_id not in dbxref:
+                dbxref.append(term_id)
+        if dbxref:
+            attrs["Dbxref"] = ",".join(dbxref)
+
+        note = f"PUFprobe:confidence={edit['confidence']:.3f};evidence_groups={'+'.join(edit['evidence_groups'])}"
+        if attrs.get("note"):
+            attrs["note"] = f"{attrs['note']},{note}"
+        else:
+            attrs["note"] = note
+
+        fields[8] = ";".join(f"{k}={v}" for k, v in attrs.items())
+        rewritten.append("\t".join(fields))
+        changes.append(
+            {
+                "sample": sample_id,
+                "locus": locus,
+                "old_product": old_product,
+                "new_product": edit["new_product"],
+                "confidence": f"{edit['confidence']:.3f}",
+                "supporting_terms": ";".join(edit["term_ids"]),
+            }
+        )
+
+    with out.open("w", encoding="utf-8", newline="\n") as handle:
+        handle.write("\n".join(rewritten) + "\n")
+    return changes
+
+
+# ---------------------------------------------------------------------------
+# GenBank (minimal line-based rewrite)
+# ---------------------------------------------------------------------------
+_PRODUCT_RE = re.compile(r"^(\s+)/product=")
+_LOCUS_RE = re.compile(r'^\s+/locus_tag="([^"]+)"')
+
+
+def rewrite_gbk(
+    src: Path,
+    out: Path,
+    sample_id: str,
+    accepted: Dict[str, Dict[str, Any]],
+) -> int:
+    """Minimal GenBank rewrite; returns the number of edited feature blocks."""
+    out.parent.mkdir(parents=True, exist_ok=True)
+    lines = src.read_text(encoding="utf-8", errors="replace").splitlines()
+    rewritten: List[str] = []
+    i = 0
+    edited = 0
+    while i < len(lines):
+        line = lines[i]
+        if not line.startswith(" ") or line.startswith("FEATURES"):
+            rewritten.append(line)
+            i += 1
+            continue
+        # Collect one feature block: a non-qualifier line starts a new feature.
+        block = [line]
+        j = i + 1
+        while j < len(lines):
+            nxt = lines[j]
+            if nxt.startswith("ORIGIN") or nxt.startswith("//"):
+                break
+            if not nxt.startswith(" "):
+                break
+            stripped = nxt.lstrip()
+            if not stripped.startswith("/"):
+                break
+            block.append(nxt)
+            j += 1
+
+        locus = None
+        for bl in block:
+            m = _LOCUS_RE.match(bl)
+            if m:
+                locus = m.group(1)
+                break
+        key = f"{sample_id}@{locus}" if locus else None
+        if key is None or key not in accepted:
+            rewritten.extend(block)
+        else:
+            edit = accepted[key]
+            for bl in block:
+                rewritten.append(bl)
+                if _PRODUCT_RE.match(bl):
+                    indent = _PRODUCT_RE.match(bl).group(1)
+                    rewritten.append(f'{indent}/db_xref="{";".join(edit["term_ids"])}"')
+                    rewritten.append(
+                        f'{indent}/note="PUFprobe:confidence={edit["confidence"]:.3f};'
+                        f'evidence_groups={"+".join(edit["evidence_groups"])}"'
+                    )
+            edited += 1
+        i = j
+    out.write_text("\n".join(rewritten) + "\n", encoding="utf-8", newline="\n")
+    return edited
+
+
+# ---------------------------------------------------------------------------
+# FASTA
+# ---------------------------------------------------------------------------
+def rewrite_faa(
+    src: Path,
+    out: Path,
+    sample_id: str,
+    accepted: Dict[str, Dict[str, Any]],
+) -> int:
+    """Rename matched protein records; returns the number of renamed records."""
+    renamed = 0
+    records = []
+    for header, seq in read_fasta(src):
+        first = header.split()[0] if header else ""
+        new_header = header
+        for key, edit in accepted.items():
+            _, _, locus = key.partition("@")
+            if locus and locus in header:
+                new_header = f"{first} {edit['new_product']}"
+                renamed += 1
+                break
+        records.append((new_header, seq))
+    write_fasta(out, records)
+    return renamed
+
+
+def run_backfill(
+    out_dir: Path,
+    samples: List[Sample],
+    accepted: Dict[str, Dict[str, Any]],
+) -> List[Dict[str, str]]:
+    """Backfill every sample; returns the combined change ledger."""
+    all_changes: List[Dict[str, str]] = []
+    for sample in samples:
+        sid = sample.sample_id
+        if sample.gff_path:
+            changes = rewrite_gff3(
+                Path(sample.gff_path), out_dir / f"{sid}.pufprobe.gff3", sid, accepted
+            )
+            all_changes.extend(changes)
+            log.info("%s: %d CDS rows backfilled in GFF3.", sid, len(changes))
+        if sample.gbk_path:
+            n = rewrite_gbk(
+                Path(sample.gbk_path), out_dir / f"{sid}.pufprobe.gbk", sid, accepted
+            )
+            log.info("%s: %d feature blocks edited in GenBank.", sid, n)
+        if sample.faa_path:
+            n = rewrite_faa(
+                Path(sample.faa_path), out_dir / f"{sid}.pufprobe.faa", sid, accepted
+            )
+            log.info("%s: %d protein records renamed in FAA.", sid, n)
+    return all_changes

pufprobe/annotate/pipeline.py

@@ -0,0 +1,72 @@
+"""annotate stage pipeline.
+
+Contract implemented here:
+
+1. Load predictions and select terms whose confidence is at least
+   --min-confidence (default config rank.min_confidence_annotate).
+2. For each sample, produce new annotation files under 09_annotate/:
+   - <sample>.pufprobe.gff3: original GFF rows with the product and Dbxref
+     fields updated for matched CDS rows, plus a PUFprobe evidence note;
+   - <sample>.pufprobe.gbk when a GBK source exists;
+   - <sample>.pufprobe.faa: protein records renamed with the new product.
+3. Original files are never modified or overwritten; a mapping table
+   09_annotate/changes.tsv records every edit with the supporting term and
+   confidence.
+
+Completion marker written for annotate.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from pufprobe.io_utils import read_json
+from pufprobe.logging_utils import get_logger
+from pufprobe.models import Sample
+from pufprobe.annotate.backfill import run_backfill, select_terms
+from pufprobe.rank.fuse import load_predictions
+from pufprobe.workdir import WorkDir
+
+log = get_logger("annotate.pipeline")
+
+
+def run(
+    workdir: WorkDir,
+    config: Dict[str, Any],
+    min_confidence: Optional[float] = None,
+) -> None:
+    threshold = (
+        float(min_confidence)
+        if min_confidence is not None
+        else float(config["rank"]["min_confidence_annotate"])
+    )
+
+    predictions = load_predictions(workdir.path("rank", "predictions.json"))
+    samples_path = workdir.path("prepare", "samples.json")
+    if not samples_path.exists():
+        raise FileNotFoundError(f"missing {samples_path}; run prepare first")
+    samples = [Sample(**row) for row in read_json(samples_path)]  # type: ignore[arg-type]
+
+    accepted = select_terms(predictions, threshold)
+    log.info(
+        "annotate: %d terms pass confidence threshold %.2f across %d proteins.",
+        sum(len(edit["terms"]) for edit in accepted.values()),
+        threshold,
+        len(accepted),
+    )
+
+    out_dir = workdir.stage_dir("annotate")
+    changes = run_backfill(out_dir, samples, accepted)
+
+    changes_path = out_dir / "changes.tsv"
+    with changes_path.open("w", encoding="utf-8", newline="\n") as handle:
+        handle.write(
+            "sample\tlocus\told_product\tnew_product\tconfidence\tsupporting terms\n"
+        )
+        for row in changes:
+            handle.write(
+                f"{row['sample']}\t{row['locus']}\t{row['old_product']}\t"
+                f"{row['new_product']}\t{row['confidence']}\t{row['supporting_terms']}\n"
+            )
+
+    workdir.mark_complete("annotate")
+    log.info("annotate done: %d edits recorded in changes.tsv.", len(changes))

pufprobe/cli.py

@@ -0,0 +1,231 @@
+"""Command line interface for PUFprobe.
+
+Eight pipeline subcommands (prepare, embed, fold, search, context, rank,
+report, annotate) share global options for the working directory, threads, CPU
+fallback, configuration and logging.
+"""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import click
+
+from pufprobe import __version__
+from pufprobe.config import load_config
+from pufprobe.workdir import WorkDir
+
+
+class Context:
+    def __init__(self, workdir: WorkDir, config: Dict[str, Any]):
+        self.workdir = workdir
+        self.config = config
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="pufprobe")
+@click.option(
+    "--workdir",
+    "-w",
+    required=False,
+    type=click.Path(file_okay=False, path_type=Path),
+    envvar="PUFPROBE_WORKDIR",
+    help="Working directory for intermediate and final outputs.",
+)
+@click.option("--threads", "-t", default=1, show_default=True, help="Threads for external tools.")
+@click.option("--cpu", is_flag=True, default=False, help="Force CPU fallback models.")
+@click.option("--config", "config_path", type=click.Path(exists=True, dir_okay=False, path_type=Path), help="JSON config overriding defaults.")
+@click.option("--log-level", default="INFO", show_default=True, help="Logging level.")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    workdir: Path,
+    threads: int,
+    cpu: bool,
+    config_path: Optional[Path],
+    log_level: str,
+) -> None:
+    """Second-stage functional inference for hypothetical proteins."""
+    import sys
+
+    help_requested = any(arg in ("-h", "--help") for arg in sys.argv[1:])
+    if workdir is None:
+        if help_requested:
+            ctx.obj = None
+            return
+        if ctx.invoked_subcommand == "doctor":
+            ctx.obj = Context(None, load_config(config_path))
+            return
+        raise click.UsageError("Missing option '--workdir' / '-w'.")
+    config = load_config(config_path)
+    wd = WorkDir(workdir, cpu=cpu, threads=threads, log_level=log_level)
+    wd.write_metadata()
+    ctx.obj = Context(wd, config)
+
+
+def _resume_guard(wd: WorkDir, stage: str, force: bool) -> bool:
+    if wd.is_complete(stage) and not force:
+        click.echo(f"[skip] {stage} already complete (use --force to rerun).")
+        return True
+    return False
+
+
+@cli.command()
+@click.option("--input", "inputs", multiple=True, type=click.Path(exists=True, path_type=Path), help="Input GFF3/GBK/FAA file or directory; repeatable.")
+@click.option("--input-list", type=click.Path(exists=True, dir_okay=False, path_type=Path), help="Text file with one input path per line.")
+@click.option("--include-smorf", is_flag=True, default=False, help="Keep sub-30 aa candidates via the permissive smORF path.")
+@click.option("--force", is_flag=True, default=False, help="Ignore the completion marker.")
+@click.pass_obj
+def prepare(obj: Context, inputs: tuple, input_list: Optional[Path], include_smorf: bool, force: bool) -> None:
+    """Parse Bakta/Prokka outputs and run true-gene quality control."""
+    from pufprobe.prepare.pipeline import run
+
+    if _resume_guard(obj.workdir, "prepare", force):
+        return
+    paths = _collect_inputs(list(inputs), input_list)
+    if not paths:
+        raise click.UsageError("Provide at least one --input path or --input-list.")
+    run(obj.workdir, obj.config, paths, include_smorf=include_smorf)
+
+
+@cli.command()
+@click.option("--model", default=None, help="ESM-2 checkpoint name (defaults from config).")
+@click.option("--precomputed", type=click.Path(exists=True, path_type=Path), help="Directory or .npz with precomputed embeddings.")
+@click.option("--fallback-only", is_flag=True, default=False, help="Use sequence feature fallback without torch.")
+@click.option("--force", is_flag=True, default=False)
+@click.pass_obj
+def embed(obj: Context, model: Optional[str], precomputed: Optional[Path], fallback_only: bool, force: bool) -> None:
+    """Compute embeddings, cluster families and select representatives."""
+    from pufprobe.embed.pipeline import run
+
+    if _resume_guard(obj.workdir, "embed", force):
+        return
+    run(obj.workdir, obj.config, model=model, precomputed=precomputed, fallback_only=fallback_only)
+
+
+@cli.command()
+@click.option("--engine", type=click.Choice(["esmfold", "af2"]), default=None, help="Structure prediction engine.")
+@click.option("--precomputed", type=click.Path(exists=True, file_okay=False, path_type=Path), help="Directory of PDB files named by family id.")
+@click.option("--force", is_flag=True, default=False)
+@click.pass_obj
+def fold(obj: Context, engine: Optional[str], precomputed: Optional[Path], force: bool) -> None:
+    """Fold family representatives and apply the pLDDT quality gate."""
+    from pufprobe.fold.pipeline import run
+
+    if _resume_guard(obj.workdir, "fold", force):
+        return
+    run(obj.workdir, obj.config, engine=engine, precomputed=precomputed)
+
+
+@cli.command()
+@click.option("--channels", default=None, help="Comma-separated channels: mmseqs,foldseek,hhblits,tmvec.")
+@click.option("--dbdir", type=click.Path(exists=True, file_okay=False, path_type=Path), help="Directory holding versioned search databases.")
+@click.option("--force", is_flag=True, default=False)
+@click.pass_obj
+def search(obj: Context, channels: Optional[str], dbdir: Optional[Path], force: bool) -> None:
+    """Run structure/sequence remote-homology searches into unified evidence."""
+    from pufprobe.search.pipeline import run
+
+    if _resume_guard(obj.workdir, "search", force):
+        return
+    channel_list = [c.strip() for c in channels.split(",")] if channels else None
+    run(obj.workdir, obj.config, channels=channel_list, dbdir=dbdir)
+
+
+@cli.command()
+@click.option("--card", type=click.Path(exists=True, path_type=Path), help="CARD reference (FASTA or ARO table) for neighbourhood checks.")
+@click.option("--vfdb", type=click.Path(exists=True, path_type=Path), help="VFDB reference for neighbourhood checks.")
+@click.option("--reference-fna", "reference_fna", type=click.Path(exists=True, file_okay=False, path_type=Path), help="Directory of genome FASTA files for micro-synteny.")
+@click.option("--force", is_flag=True, default=False)
+@click.pass_obj
+def context(obj: Context, card: Optional[Path], vfdb: Optional[Path], reference_fna: Optional[Path], force: bool) -> None:
+    """Compute operon, phylogenetic-profile and micro-synteny evidence."""
+    from pufprobe.context.pipeline import run
+
+    if _resume_guard(obj.workdir, "context", force):
+        return
+    run(obj.workdir, obj.config, card=card, vfdb=vfdb, reference_fna=reference_fna)
+
+
+@cli.command()
+@click.option("--weights", type=click.Path(exists=True, path_type=Path), help="Trained fusion model weights; absent uses rule weights.")
+@click.option("--force", is_flag=True, default=False)
+@click.pass_obj
+def rank(obj: Context, weights: Optional[Path], force: bool) -> None:
+    """Fuse evidence, calibrate confidence and rank wet-lab priorities."""
+    from pufprobe.rank.pipeline import run
+
+    if _resume_guard(obj.workdir, "rank", force):
+        return
+    run(obj.workdir, obj.config, weights=weights)
+
+
+@cli.command()
+@click.option("--formats", default="json,html,md", show_default=True, help="Comma-separated output formats.")
+@click.option("--force", is_flag=True, default=False)
+@click.pass_obj
+def report(obj: Context, formats: str, force: bool) -> None:
+    """Write JSON and auditable HTML/Markdown evidence reports."""
+    from pufprobe.report.pipeline import run
+
+    if _resume_guard(obj.workdir, "report", force):
+        return
+    run(obj.workdir, obj.config, formats=[f.strip() for f in formats.split(",")])
+
+
+@cli.command()
+@click.option("--min-confidence", default=None, type=float, help="Override the annotation confidence threshold.")
+@click.option("--force", is_flag=True, default=False)
+@click.pass_obj
+def annotate(obj: Context, min_confidence: Optional[float], force: bool) -> None:
+    """Backfill high-confidence predictions into new GFF3/GBK/FAA files."""
+    from pufprobe.annotate.pipeline import run
+
+    if _resume_guard(obj.workdir, "annotate", force):
+        return
+    run(obj.workdir, obj.config, min_confidence=min_confidence)
+
+
+@cli.command()
+@click.pass_obj
+def doctor(obj: Context) -> None:
+    """Report detected external tools, Python modules and GPU availability."""
+    from pufprobe.externals import summary
+    import json
+
+    click.echo(json.dumps(summary(), indent=2, ensure_ascii=False))
+
+
+def _collect_inputs(inputs: List[Path], input_list: Optional[Path]) -> List[Path]:
+    paths = list(inputs)
+    if input_list is not None:
+        for line in input_list.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#"):
+                paths.append(Path(line))
+    expanded: List[Path] = []
+    for path in paths:
+        if not path.exists():
+            raise click.UsageError(f"Input path does not exist: {path}")
+        if path.is_dir():
+            for pattern in ("*.gff", "*.gff3"):
+                expanded.extend(sorted(path.rglob(pattern)))
+            for pattern in ("*.gbk", "*.gbff", "*.genbank"):
+                expanded.extend(sorted(path.rglob(pattern)))
+            for faa in sorted(path.rglob("*.faa")):
+                # Bakta also writes <prefix>.hypotheticals.faa (plural), a
+                # subset holding only hypothetical proteins. Indexing that
+                # subset would make every annotated protein appear unaligned,
+                # so skip it and keep the complete .faa. Both the released
+                # plural and the singular spelling are tolerated.
+                if faa.name.endswith(".hypotheticals.faa") or faa.name.endswith(
+                    ".hypothetical.faa"
+                ):
+                    continue
+                expanded.append(faa)
+        else:
+            expanded.append(path)
+    return sorted(set(expanded))
+
+
+if __name__ == "__main__":
+    cli()

pufprobe/clustering/__init__.py

@@ -0,0 +1 @@
+"""clustering backends: MMseqs2 and pure-Python graph fallback."""

pufprobe/clustering/mmseqs.py

@@ -0,0 +1,103 @@
+"""MMseqs2 sequence clustering (``createdb`` / ``cluster`` / ``createtsv``).
+
+When the ``mmseqs`` binary is detected on PATH this runs greedy cascaded
+clustering in a throw-away temp directory and returns a unified
+``{global_key: cluster_index}`` mapping. When the binary is missing the
+function returns ``None`` (after logging install guidance) so the caller can
+drop to the pure-numpy :mod:`pufprobe.clustering.pycluster` path.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Dict, Optional
+
+from pufprobe import externals
+from pufprobe.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+INSTALL_HINT = "Install MMseqs2 with `conda install -c conda-forge mmseqs2` (see https://mmseqs.com)."
+
+
+def run_mmseqs_cluster(
+    fasta_path: Path,
+    work_dir: Path,
+    identity: float,
+    coverage: float,
+    threads: int = 1,
+) -> Optional[Dict[str, int]]:
+    """Cluster sequences in ``fasta_path``; return ``{key: cluster_index}``.
+
+    Returns ``None`` when the mmseqs binary is unavailable so the caller can
+    fall back to pycluster. FASTA headers must be exactly the global keys.
+    """
+    info = externals.mmseqs()
+    if not info.available:
+        logger.warning(
+            "mmseqs binary not found; skipping MMseqs2 clustering and falling "
+            "back to pure-numpy clustering. %s", INSTALL_HINT,
+        )
+        return None
+
+    exe = info.path or "mmseqs"
+    work_dir.mkdir(parents=True, exist_ok=True)
+    tmp = Path(tempfile.mkdtemp(prefix="mmseqs_cluster_", dir=str(work_dir)))
+    qdb = tmp / "qdb"
+    cdb = tmp / "clu"
+    tsv = tmp / "clu.tsv"
+
+    cmd_base = [exe]
+    try:
+        _run(cmd_base + ["createdb", str(fasta_path), str(qdb)])
+        _run(
+            cmd_base
+            + [
+                "cluster",
+                str(qdb),
+                str(cdb),
+                str(tmp / "mm_tmp"),
+                "--min-seq-id",
+                str(identity),
+                "-c",
+                str(coverage),
+                "--threads",
+                str(threads),
+            ]
+        )
+        _run(cmd_base + ["createtsv", str(qdb), str(qdb), str(cdb), str(tsv)])
+    except (subprocess.SubprocessError, OSError) as exc:
+        logger.warning("MMseqs2 clustering failed (%s); falling back to pycluster.", exc)
+        return None
+
+    return parse_clusters_tsv(tsv)
+
+
+def parse_clusters_tsv(tsv_path: Path) -> Dict[str, int]:
+    """Parse ``createtsv`` output (rep, member per line) into key->index."""
+    mapping: Dict[str, int] = {}
+    cluster_order: Dict[str, int] = {}
+    next_index = 0
+    if not tsv_path.exists():
+        return mapping
+    with tsv_path.open("r", encoding="utf-8", errors="replace") as handle:
+        for line in handle:
+            parts = line.rstrip("\n").split("\t")
+            if len(parts) < 2:
+                continue
+            rep, member = parts[0], parts[1]
+            if rep not in cluster_order:
+                cluster_order[rep] = next_index
+                next_index += 1
+            mapping[member] = cluster_order[rep]
+    return mapping
+
+
+def _run(cmd: list) -> None:
+    completed = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    if completed.returncode != 0:
+        raise subprocess.CalledProcessError(
+            completed.returncode, cmd, completed.stdout, completed.stderr
+        )