bactopia 2.0.2__tar.gz → 2.1.0__tar.gz

{bactopia-2.0.2 → bactopia-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bactopia
-Version: 2.0.2
+Version: 2.1.0
 Summary: A Python package for working with Bactopia
 License: MIT
 License-File: LICENSE
@@ -19,6 +19,7 @@ Requires-Dist: biopython (>=1.80)
 Requires-Dist: jinja2 (>=3.1.6)
 Requires-Dist: openpyxl (>=3.1.0)
 Requires-Dist: pandas (>=2.2.0)
+Requires-Dist: psutil (>=5.9.0)
 Requires-Dist: pyyaml (>=6.0)
 Requires-Dist: rauth (>=0.7.3)
 Requires-Dist: requests (>=2.28.2)

{bactopia-2.0.2 → bactopia-2.1.0}/bactopia/cli/catalog.py

@@ -380,6 +380,29 @@ def generate_catalog(bactopia_path: Path) -> dict:
     return catalog
 
 
+def render_llms_txt(catalog: dict, template_path: Path) -> str:
+    """Render llms.txt from a Jinja2 template using catalog data.
+
+    Args:
+        catalog: Catalog dict as returned by generate_catalog().
+        template_path: Path to the Jinja2 template file.
+
+    Returns:
+        Rendered llms.txt content as a string.
+    """
+    from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+    env = Environment(
+        loader=FileSystemLoader(str(template_path.parent)),
+        undefined=StrictUndefined,
+        keep_trailing_newline=True,
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+    template = env.get_template(template_path.name)
+    return template.render(catalog=catalog)
+
+
 @click.command()
 @click.version_option(bactopia.__version__, "--version")
 @click.option(
@@ -395,13 +418,37 @@ def generate_catalog(bactopia_path: Path) -> dict:
     help="Output path for catalog.json (default: stdout)",
 )
 @click.option("--pretty", is_flag=True, help="Pretty-print JSON output.")
+@click.option(
+    "--llms-output",
+    "llms_output_path",
+    type=click.Path(),
+    default=None,
+    help="Also render llms.txt to this path. Uses the bundled template at bactopia/templates/bactopia/llms.txt.j2 unless --llms-template is provided.",
+)
+@click.option(
+    "--llms-template",
+    "llms_template_path",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Jinja2 template for llms.txt. Defaults to the template bundled inside bactopia-py.",
+)
 @click.option("--verbose", is_flag=True, help="Print debug related text.")
-def catalog(bactopia_path, output_path, pretty, verbose):
+def catalog(
+    bactopia_path,
+    output_path,
+    pretty,
+    llms_output_path,
+    llms_template_path,
+    verbose,
+):
     """Generate machine-readable catalog of all Bactopia components.
 
     Produces catalog.json containing workflows, subworkflows, and modules
     with their contracts (takes/emits), dependencies, and metadata.
     Replaces data/workflows.yml as the authoritative component index.
+
+    Optionally also renders llms.txt from a Jinja2 template when
+    --llms-output is provided.
     """
     # Setup logs
     logging.basicConfig(
@@ -445,6 +492,23 @@ def catalog(bactopia_path, output_path, pretty, verbose):
     else:
         print(output_json)
 
+    # Optionally render llms.txt
+    if llms_output_path:
+        if llms_template_path:
+            tpl = Path(llms_template_path)
+        else:
+            # Bundled template ships inside bactopia-py
+            tpl = (
+                Path(__file__).parent.parent / "templates" / "bactopia" / "llms.txt.j2"
+            )
+        tpl = tpl.resolve()
+        if not tpl.exists():
+            logging.error(f"llms.txt template not found: {tpl}")
+            sys.exit(1)
+        rendered = render_llms_txt(data, tpl)
+        Path(llms_output_path).write_text(rendered)
+        console.print(f"llms.txt written to {llms_output_path}")
+
 
 def main():
     if len(sys.argv) == 1:

bactopia-2.1.0/bactopia/cli/citations.py

@@ -0,0 +1,190 @@
+import json
+import sys
+from pathlib import Path
+
+import rich
+import rich.console
+import rich.traceback
+import rich_click as click
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.table import Table
+
+import bactopia
+from bactopia.lint.citations import validate_citations
+from bactopia.parsers.citations import parse_citations
+from bactopia.utils import validate_file
+
+# Set up Rich
+stderr = rich.console.Console(stderr=True)
+rich.traceback.install(console=stderr, width=200, word_wrap=True, extra_lines=1)
+click.rich_click.USE_RICH_MARKUP = True
+
+
+def _render_validation_report(report: dict, silent: bool, plain_text: bool) -> None:
+    """Pretty-print a validate_citations() report using Rich tables."""
+    console = Console(color_system=None if plain_text else "auto")
+    orphans = report["orphans"]
+    expected_orphans = report.get("expected_orphans", {})
+    missing = report["missing_workflow_keys"]
+    summary = report["summary"]
+
+    if summary["orphans_total"] == 0 and summary["missing_total"] == 0:
+        if not silent:
+            console.print(
+                f"[green]All {summary['yml_total']} citations are referenced "
+                "and all workflow @citation keys resolve.[/green]"
+            )
+            if summary.get("expected_orphans_total"):
+                _render_expected_orphans(console, expected_orphans)
+        return
+
+    if summary["orphans_total"]:
+        table = Table(title="Orphan citation keys", show_header=True)
+        table.add_column("Section")
+        table.add_column("Keys")
+        for section, keys in orphans.items():
+            if not keys:
+                continue
+            table.add_row(section, ", ".join(keys))
+        console.print(table)
+
+    if summary["missing_total"]:
+        table = Table(title="Workflow @citation keys not in citations.yml")
+        table.add_column("Component")
+        table.add_column("File")
+        table.add_column("Line")
+        table.add_column("Key")
+        for item in missing:
+            table.add_row(
+                item["component"],
+                item["file"],
+                str(item["line"]) if item["line"] else "?",
+                item["key"],
+            )
+        console.print(table)
+
+    if summary.get("expected_orphans_total"):
+        _render_expected_orphans(console, expected_orphans)
+
+    console.print(
+        f"\nSummary: {summary['orphans_total']} orphan key(s), "
+        f"{summary['missing_total']} workflow reference(s) unresolved."
+    )
+
+
+def _render_expected_orphans(console: Console, expected_orphans: dict) -> None:
+    """Render the provenance-only orphan bucket as an informational note."""
+    flat = sorted(key for keys in expected_orphans.values() for key in keys)
+    if not flat:
+        return
+    console.print(
+        f"[dim]Expected orphans (provenance-only, not flagged): {', '.join(flat)}[/dim]"
+    )
+
+
+@click.command()
+@click.version_option(bactopia.__version__, "--version", "-V")
+@click.option(
+    "--bactopia-path",
+    "-b",
+    required=True,
+    help="Directory where Bactopia repository is stored",
+)
+@click.option("--name", "-n", help="Only print citation matching a given name")
+@click.option("--plain-text", "-p", is_flag=True, help="Disable rich formatting")
+@click.option(
+    "--validate",
+    is_flag=True,
+    help="Validate citation integrity: orphan keys + workflow @citation references",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help="Emit validation results as JSON (use with --validate)",
+)
+@click.option(
+    "--silent",
+    is_flag=True,
+    help="Suppress non-error output when validation is clean",
+)
+def citations(
+    bactopia_path: str,
+    name: str,
+    plain_text: bool,
+    validate: bool,
+    as_json: bool,
+    silent: bool,
+) -> None:
+    """Print or validate citations used throughout Bactopia.
+
+    Default mode prints the full citation list (or one entry with --name).
+    Pass --validate to instead scan the repo for orphan keys (defined but
+    never referenced) and workflow @citation keys that don't resolve to
+    an entry in citations.yml. Module and subworkflow @citation keys are
+    validated by bactopia-lint (rules M035 and S019).
+    """
+
+    if validate:
+        # Validation mode requires the repo root so we can locate
+        # data/citations.yml and walk modules/subworkflows/workflows.
+        repo_root = Path(bactopia_path)
+        if not (repo_root / "data" / "citations.yml").exists():
+            raise click.ClickException(
+                f"{repo_root}/data/citations.yml not found. "
+                "Pass the Bactopia repo root via --bactopia-path."
+            )
+        report = validate_citations(repo_root)
+
+        if as_json:
+            click.echo(json.dumps(report, indent=2, sort_keys=True))
+        else:
+            _render_validation_report(report, silent=silent, plain_text=plain_text)
+
+        has_issues = (
+            report["summary"]["orphans_total"] or report["summary"]["missing_total"]
+        )
+        if has_issues:
+            sys.exit(1)
+        return
+
+    # Default (print) mode — unchanged behaviour.
+    citations_yml = validate_file(f"{bactopia_path}/citations.yml")
+    citations, module_citations = parse_citations(citations_yml)
+
+    markdown = []
+    if name:
+        if name.lower() in module_citations:
+            markdown.append(f"{module_citations[name.lower()]['name']}  ")
+            markdown.append(module_citations[name.lower()]["cite"].rstrip())
+        else:
+            raise KeyError(f'"{name}" does not match available citations')
+    else:
+        for group, refs in citations.items():
+            if group.startswith("datasets"):
+                markdown.append(f"# {group.replace('_', ' ').title()}")
+            else:
+                markdown.append(f"# {group.title()}")
+            for ref, vals in refs.items():
+                markdown.append(f"{vals['name']}  ")
+                markdown.append(vals["cite"])
+
+    md = None
+    if plain_text:
+        md = "\n".join(markdown)
+    else:
+        md = Markdown("\n".join(markdown))
+    console = Console(color_system=None if plain_text else "auto")
+    console.print(md)
+
+
+def main():
+    if len(sys.argv) == 1:
+        citations.main(["--help"])
+    else:
+        citations()
+
+
+if __name__ == "__main__":
+    main()

bactopia-2.1.0/bactopia/cli/docs.py

@@ -0,0 +1,208 @@
+"""bactopia-docs CLI: validate reference-doc staleness."""
+
+import json
+import sys
+from pathlib import Path
+
+import rich
+import rich.console
+import rich.traceback
+import rich_click as click
+from rich.console import Console
+from rich.table import Table
+
+import bactopia
+from bactopia.lint.docs import (
+    DEFAULT_DOCS_PATH,
+    DEFAULT_PATTERNS_FILE,
+    validate_docs,
+)
+
+stderr = rich.console.Console(stderr=True)
+rich.traceback.install(console=stderr, width=200, word_wrap=True, extra_lines=1)
+click.rich_click.USE_RICH_MARKUP = True
+
+
+def _render_report(report: dict, silent: bool, plain_text: bool) -> None:
+    """Pretty-print a validate_docs() report using Rich tables."""
+    console = Console(color_system=None if plain_text else "auto")
+    summary = report["summary"]
+    deprecated = report["deprecated_patterns"]
+    violations = report["ground_truth_violations"]
+
+    if summary["fail"] == 0 and summary["warn"] == 0:
+        if not silent:
+            console.print(
+                f"[green]All {summary['files_scanned']} docs clean. "
+                f"({summary['patterns_loaded']} deprecated patterns, "
+                f"{report['ground_truth']['cli_commands_total']} CLI commands, "
+                f"{report['ground_truth']['lint_rule_ids_total']} lint rule IDs "
+                f"checked.)[/green]"
+            )
+        return
+
+    if deprecated:
+        table = Table(title="Deprecated patterns (D0xx)", show_header=True)
+        table.add_column("Rule")
+        table.add_column("File")
+        table.add_column("Line", justify="right")
+        table.add_column("Match")
+        table.add_column("Hint")
+        for hit in deprecated:
+            table.add_row(
+                hit["rule_id"],
+                hit["file"],
+                str(hit["line"]),
+                hit["match"][:80],
+                hit.get("hint", ""),
+            )
+        console.print(table)
+
+    if violations:
+        table = Table(title="Ground-truth violations (D1xx)", show_header=True)
+        table.add_column("Rule")
+        table.add_column("File")
+        table.add_column("Line", justify="right")
+        table.add_column("Detail")
+        for hit in violations:
+            if "actual" in hit and "claim" in hit:
+                detail = f"claim: {hit['claim']} | actual: {hit['actual']}"
+            elif "reference" in hit:
+                detail = f"reference: {hit['reference']} — {hit.get('hint', '')}"
+            else:
+                detail = hit.get("hint", "")
+            table.add_row(
+                hit["rule_id"],
+                hit["file"],
+                str(hit["line"]),
+                detail[:100],
+            )
+        console.print(table)
+
+    console.print(
+        f"\nSummary: {summary['deprecated_pattern_hits']} deprecated-pattern hit(s), "
+        f"{summary['ground_truth_violations']} ground-truth violation(s) "
+        f"across {summary['files_scanned']} doc(s)."
+    )
+
+
+@click.command()
+@click.version_option(bactopia.__version__, "--version", "-V")
+@click.option(
+    "--bactopia-path",
+    "-b",
+    required=True,
+    help="Directory where Bactopia repository is stored",
+)
+@click.option(
+    "--docs-path",
+    default=DEFAULT_DOCS_PATH,
+    show_default=True,
+    help="Docs directory relative to --bactopia-path",
+)
+@click.option(
+    "--patterns-file",
+    default=DEFAULT_PATTERNS_FILE,
+    show_default=True,
+    help="Deprecated-patterns YAML relative to --bactopia-path",
+)
+@click.option(
+    "--bactopia-py-path",
+    default=None,
+    type=click.Path(file_okay=False, path_type=Path),
+    help="Path to bactopia-py repo (for D105 CLI / D106 lint-rule checks). "
+    "Defaults to <bactopia-path>/../bactopia-py.",
+)
+@click.option(
+    "--skip-path-check",
+    is_flag=True,
+    help="Skip D108 markdown-link target resolution",
+)
+@click.option(
+    "--validate",
+    is_flag=True,
+    help="Run validation (default action; flag is accepted for parity with bactopia-citations).",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    help="Emit results as JSON",
+)
+@click.option(
+    "--silent",
+    is_flag=True,
+    help="Suppress non-error output when validation is clean",
+)
+@click.option(
+    "--plain-text",
+    "-p",
+    is_flag=True,
+    help="Disable rich formatting",
+)
+def docs(
+    bactopia_path: str,
+    docs_path: str,
+    patterns_file: str,
+    bactopia_py_path: Path | None,
+    skip_path_check: bool,
+    validate: bool,
+    as_json: bool,
+    silent: bool,
+    plain_text: bool,
+) -> None:
+    """Validate reference-doc staleness across a Bactopia repo.
+
+    Two checks run against every .md file under [b]--docs-path[/b]:
+
+    [b]Deprecated patterns (D0xx)[/b]: regex matches against
+    [b]--patterns-file[/b] entries — phrases retired by past migrations
+    (e.g. ``flattenPaths``, the 4-channel emission framing).
+
+    [b]Ground-truth assertions (D1xx)[/b]: counts (D101-D103), Nextflow
+    version (D104), bactopia-py CLI references (D105), lint rule IDs
+    (D106), markdown link targets (D108).
+
+    Suppress a rule on a single line with
+    ``<!-- bactopia-docs: ignore D0xx -->`` (or a comma-separated list).
+
+    Exits 1 if any FAIL is found.
+    """
+    repo_root = Path(bactopia_path)
+    if not repo_root.is_dir():
+        raise click.ClickException(f"--bactopia-path {repo_root} is not a directory.")
+    if not (repo_root / docs_path).is_dir():
+        raise click.ClickException(
+            f"Docs directory {repo_root / docs_path} not found. "
+            "Pass --bactopia-path pointing at the Bactopia repo root."
+        )
+
+    # validate flag is decorative — there's no other mode for now.
+    _ = validate
+
+    report = validate_docs(
+        bactopia_path=repo_root,
+        docs_path=docs_path,
+        patterns_file=patterns_file,
+        bactopia_py_path=bactopia_py_path,
+        skip_path_check=skip_path_check,
+    )
+
+    if as_json:
+        click.echo(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        _render_report(report, silent=silent, plain_text=plain_text)
+
+    if report["summary"]["fail"]:
+        sys.exit(1)
+
+
+def main():
+    if len(sys.argv) == 1:
+        docs.main(["--help"])
+    else:
+        docs()
+
+
+if __name__ == "__main__":
+    main()

{bactopia-2.0.2 → bactopia-2.1.0}/bactopia/cli/helpers/merge_schemas.py

@@ -140,7 +140,7 @@ def merge_schemas(
             sys.exit(1)
 
     # parse the catalog
-    with open(f"{bactopia_path}/data/catalog.json") as fh:
+    with open(f"{bactopia_path}/catalog.json") as fh:
         catalog = json.load(fh)
 
     if wf not in catalog["workflows"]:

bactopia-2.1.0/bactopia/cli/sysinfo.py

@@ -0,0 +1,120 @@
+"""Auto-detect host resources and emit Nextflow CLI overrides for local profiles."""
+
+import psutil
+import rich
+import rich.console
+import rich.traceback
+import rich_click as click
+
+import bactopia
+
+# Set up Rich
+stderr = rich.console.Console(stderr=True)
+rich.traceback.install(console=stderr, width=200, word_wrap=True, extra_lines=1)
+click.rich_click.USE_RICH_MARKUP = True
+
+MEM_CAP = 32
+MEM_FLOOR = 4
+CPU_CAP = 12
+
+LOCAL_PROFILES = frozenset(
+    {
+        "standard",
+        "conda",
+        "mamba",
+        "docker",
+        "arm",
+        "apptainer",
+        "singularity",
+        "podman",
+        "charliecloud",
+        "shifter",
+        "wave",
+    }
+)
+
+INFORMATIONAL_FLAGS = frozenset({"--help", "-h", "--help_all", "--list_wfs"})
+
+
+def _flag_value(args, *flag_names):
+    """Return the value of the first matching flag in args, or None."""
+    for i, arg in enumerate(args):
+        for flag in flag_names:
+            if arg == flag:
+                return args[i + 1] if i + 1 < len(args) else ""
+            if arg.startswith(f"{flag}="):
+                return arg[len(flag) + 1 :]
+    return None
+
+
+def _has_flag(args, *flag_names):
+    """True if any of flag_names appears in args (bare or `flag=value`)."""
+    return _flag_value(args, *flag_names) is not None
+
+
+@click.command(
+    context_settings={"ignore_unknown_options": True, "allow_extra_args": True},
+    add_help_option=False,
+)
+@click.argument("args", nargs=-1, type=click.UNPROCESSED)
+@click.pass_context
+def sysinfo(ctx, args):
+    """Auto-detect host RAM and CPUs, emit Nextflow CLI fragments for local profiles.
+
+    Reads the bactopia wrapper's argv as a passthrough. Emits to stdout the
+    additional `--max_memory <N>.GB` / `--max_cpus <N>` flags that should be
+    appended to the `nextflow run` command line. Emits nothing when:
+
+      - a custom config is supplied (`-c` or `--nfconfig`)
+      - any `-profile` value is not in the local-executor allow-list
+      - both `--max_memory` and `--max_cpus` are already set by the user
+      - the invocation is informational (`--help`, `--help_all`, `--list_wfs`)
+    """
+    if not args or args == ("--help",) or args == ("-h",):
+        click.echo(ctx.get_help())
+        return
+    if args == ("--version",) or args == ("-V",):
+        click.echo(f"bactopia-sysinfo {bactopia.__version__}")
+        return
+
+    if any(a in INFORMATIONAL_FLAGS for a in args):
+        return
+
+    if _has_flag(args, "-c", "--nfconfig"):
+        return
+
+    profile = _flag_value(args, "-profile", "--profile")
+    profiles = set(profile.split(",")) if profile else {"standard"}
+    if not profiles.issubset(LOCAL_PROFILES):
+        return
+
+    additions = []
+
+    if not _has_flag(args, "--max_memory"):
+        total_gb = psutil.virtual_memory().total // (1024**3)
+        mem = min(total_gb - 1, MEM_CAP)
+        if mem >= MEM_FLOOR:
+            additions.append(f"--max_memory {mem}.GB")
+        else:
+            click.echo(
+                f"[bactopia-sysinfo] detected only {total_gb} GB RAM "
+                f"(below floor of {MEM_FLOOR} GB); skipping --max_memory",
+                err=True,
+            )
+
+    if not _has_flag(args, "--max_cpus"):
+        cpus = min(psutil.cpu_count(logical=True) or 1, CPU_CAP)
+        additions.append(f"--max_cpus {cpus}")
+
+    if additions:
+        line = " ".join(additions)
+        click.echo(line)
+        click.echo(f"[bactopia-sysinfo] auto-detected: {line}", err=True)
+
+
+def main():
+    sysinfo()
+
+
+if __name__ == "__main__":
+    main()

{bactopia-2.0.2 → bactopia-2.1.0}/bactopia/cli/workflows.py

@@ -95,7 +95,7 @@ def download(
     bactopia_path = str(Path(bactopia_path).absolute().resolve())
 
     # Load catalog.json
-    catalog_path = Path(f"{bactopia_path}/data/catalog.json")
+    catalog_path = Path(f"{bactopia_path}/catalog.json")
     if catalog_path.exists():
         with open(catalog_path) as fh:
             catalog = json.load(fh)