algorithm-nexus 0.2.1__py3-none-any.whl

algorithm_nexus/commands/get.py

@@ -0,0 +1,120 @@
+# Copyright IBM Corp. 2026
+# SPDX-License-Identifier: Apache-2.0
+
+"""Get commands for Algorithm Nexus CLI."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+try:
+    import typer
+    from rich.console import Console
+except ImportError:
+    print(
+        "Error: CLI dependencies are not installed.\n"
+        "Please install them with: pip install algorithm-nexus[cli]",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+from algorithm_nexus.commands.utils import (
+    find_package_config,
+    output_benchmark_requirements_table,
+    output_requirements_txt,
+    validate_txt_only_format,
+)
+
+console = Console()
+
+
+def get_benchmark_requirements(
+    nexus_package: Annotated[
+        str,
+        typer.Argument(
+            help="Name of the Nexus package to get benchmark requirements for",
+        ),
+    ],
+    packages_root: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to the packages root directory (default: ./packages).",
+            dir_okay=True,
+            file_okay=False,
+            readable=True,
+            resolve_path=True,
+        ),
+    ] = Path("./packages"),
+    output_format: Annotated[
+        str | None,
+        typer.Option(
+            "-o",
+            "--output-format",
+            help="Output format: 'txt' (requirements file format). Default is table output.",
+        ),
+    ] = None,
+    output_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--output-file",
+            help="File path to write output to. Only used with -o txt.",
+        ),
+    ] = None,
+) -> None:
+    """Get the list of benchmark requirement specifiers for a specific Nexus package.
+
+    This command retrieves all benchmark packages registered in the specified
+    Nexus package's nexus.yaml file and displays their requirement specifiers.
+
+    Use -o txt to output in requirements.txt format (one requirement per line),
+    suitable for use with pip install -r.
+    """
+    validate_txt_only_format(output_format)
+
+    if not packages_root.is_dir():
+        console.print(f"[red]Error:[/red] {packages_root} is not a directory")
+        raise typer.Exit(code=1)
+
+    # Find and load the package configuration
+    result = find_package_config(nexus_package, packages_root)
+    if result is None:
+        console.print(
+            f"[red]Error:[/red] Nexus package '{nexus_package}' not found in {packages_root}"
+        )
+        raise typer.Exit(code=1)
+
+    package_dir, package_config = result
+
+    # Check if package has benchmark packages
+    if not package_config.package.benchmark_packages:
+        console.print(
+            f"\n[yellow]No benchmark packages found for Nexus package '{nexus_package}'[/yellow]\n"
+        )
+        return
+
+    # Handle txt format (requirements.txt style)
+    if output_format == "txt":
+        requirements = [
+            bench_pkg.requirement_specifier
+            for bench_pkg in package_config.package.benchmark_packages
+        ]
+        output_requirements_txt(requirements, output_file)
+        return
+
+    # Handle table output (default) and other formats
+    output_benchmark_requirements_table(
+        package_config.package.benchmark_packages,
+        nexus_package,
+        output_format,
+        output_file,
+    )
+
+    if not output_format:
+        console.print(
+            f"\n[bold]Total:[/bold] {len(package_config.package.benchmark_packages)} benchmark requirement(s)\n"
+        )
+
+
+# Made with Bob

algorithm_nexus/commands/list.py

@@ -0,0 +1,349 @@
+# Copyright IBM Corp. 2026
+# SPDX-License-Identifier: Apache-2.0
+
+"""List commands for Algorithm Nexus CLI."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+try:
+    import typer
+    from rich.console import Console
+except ImportError:
+    print(
+        "Error: CLI dependencies are not installed.\n"
+        "Please install them with: pip install algorithm-nexus[cli]",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+from algorithm_nexus.commands.utils import (
+    collect_benchmark_data,
+    output_data,
+    try_load_package_config,
+    validate_output_format,
+)
+
+console = Console()
+
+
+def list_packages(
+    packages_root: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to the packages root directory (default: ./packages).",
+            dir_okay=True,
+            file_okay=False,
+            readable=True,
+            resolve_path=True,
+        ),
+    ] = Path("./packages"),
+    output_format: Annotated[
+        str | None,
+        typer.Option(
+            "-o",
+            "--output-format",
+            help="Output format: 'csv' or 'json'. Default is table output.",
+        ),
+    ] = None,
+    output_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--output-file",
+            help="File path to write output to. Only used with -o csv or json.",
+        ),
+    ] = None,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Warn on stderr when packages fail to load due to invalid YAML or schema errors.",
+        ),
+    ] = False,
+) -> None:
+    """List all Nexus packages discovered in the packages directory."""
+    validate_output_format(output_format)
+
+    if not packages_root.is_dir():
+        console.print(f"[red]Error:[/red] {packages_root} is not a directory")
+        raise typer.Exit(code=1)
+
+    # Collect all nexus packages
+    nexus_packages: list[str] = []
+
+    for package_dir in packages_root.iterdir():
+        if not package_dir.is_dir() or package_dir.name.startswith("."):
+            continue
+
+        package_config = try_load_package_config(package_dir, warn_on_error=strict)
+        if package_config:
+            nexus_packages.append(package_config.package.name)
+
+    if not nexus_packages:
+        console.print("\n[yellow]No Nexus packages found[/yellow]\n")
+        return
+
+    # Prepare data for output
+    data = [{"Nexus Package": pkg} for pkg in sorted(nexus_packages)]
+    headers = ["Nexus Package"]
+
+    output_data(
+        data=data,
+        headers=headers,
+        output_format=output_format,
+        output_file=output_file,
+        table_title="Discovered Nexus Packages",
+    )
+
+    if not output_format:
+        console.print(f"\n[bold]Total:[/bold] {len(nexus_packages)} packages\n")
+
+
+def list_benchmark_packages(
+    packages_root: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to the packages root directory (default: ./packages).",
+            dir_okay=True,
+            file_okay=False,
+            readable=True,
+            resolve_path=True,
+        ),
+    ] = Path("./packages"),
+    nexus_package: Annotated[
+        str | None,
+        typer.Option(
+            "--nexus-package",
+            help="Filter results to show only benchmark packages used by the specified nexus package",
+        ),
+    ] = None,
+    output_format: Annotated[
+        str | None,
+        typer.Option(
+            "-o",
+            "--output-format",
+            help="Output format: 'csv' or 'json'. Default is table output.",
+        ),
+    ] = None,
+    output_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--output-file",
+            help="File path to write output to. Only used with -o csv or json.",
+        ),
+    ] = None,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Warn on stderr when packages fail to load due to invalid YAML or schema errors.",
+        ),
+    ] = False,
+) -> None:
+    """List all benchmark packages discovered across all Nexus packages.
+
+    By default, shows a deduplicated table of benchmark packages with the nexus
+    packages that use them. Use --nexus-package to filter results for a specific
+    nexus package.
+    """
+    validate_output_format(output_format)
+
+    if not packages_root.is_dir():
+        console.print(f"[red]Error:[/red] {packages_root} is not a directory")
+        raise typer.Exit(code=1)
+
+    # Collect all benchmark data
+    benchmark_data = collect_benchmark_data(packages_root, warn_on_error=strict)
+
+    if not benchmark_data:
+        console.print(
+            "\n[yellow]No benchmark packages found in any packages[/yellow]\n"
+        )
+        return
+
+    # Filter by nexus package if specified
+    title = "Discovered Benchmark Packages"
+    if nexus_package:
+        filtered_data: dict[str, dict[str, list[str]]] = {}
+        for bench_pkg, experiments in benchmark_data.items():
+            for exp_id, pkg_list in experiments.items():
+                if nexus_package in pkg_list:
+                    if bench_pkg not in filtered_data:
+                        filtered_data[bench_pkg] = {}
+                    filtered_data[bench_pkg][exp_id] = [nexus_package]
+
+        if not filtered_data:
+            console.print(
+                f"\n[yellow]No benchmark packages found for nexus package '{nexus_package}'[/yellow]\n"
+            )
+            return
+
+        benchmark_data = filtered_data
+        title = f"Benchmark Packages for Nexus Package: {nexus_package}"
+
+    # Prepare data for output
+    if nexus_package:
+        headers = ["Benchmark Package"]
+        data = [
+            {"Benchmark Package": bench_pkg}
+            for bench_pkg in sorted(benchmark_data.keys())
+        ]
+    else:
+        headers = ["Benchmark Package", "Registered By"]
+        data = []
+        for bench_pkg in sorted(benchmark_data.keys()):
+            all_packages = set()
+            for exp_packages in benchmark_data[bench_pkg].values():
+                all_packages.update(exp_packages)
+            data.append(
+                {
+                    "Benchmark Package": bench_pkg,
+                    "Registered By": ", ".join(sorted(all_packages)),
+                }
+            )
+
+    output_data(
+        data=data,
+        headers=headers,
+        output_format=output_format,
+        output_file=output_file,
+        table_title=title,
+    )
+
+    if not output_format:
+        console.print(
+            f"\n[bold]Total:[/bold] {len(benchmark_data)} benchmark packages\n"
+        )
+
+
+def list_benchmark_experiments(
+    packages_root: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to the packages root directory (default: ./packages).",
+            dir_okay=True,
+            file_okay=False,
+            readable=True,
+            resolve_path=True,
+        ),
+    ] = Path("./packages"),
+    nexus_package: Annotated[
+        str | None,
+        typer.Option(
+            "--nexus-package",
+            help="Filter results to show only experiments used by the specified nexus package",
+        ),
+    ] = None,
+    output_format: Annotated[
+        str | None,
+        typer.Option(
+            "-o",
+            "--output-format",
+            help="Output format: 'csv' or 'json'. Default is table output.",
+        ),
+    ] = None,
+    output_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--output-file",
+            help="File path to write output to. Only used with -o csv or json.",
+        ),
+    ] = None,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Warn on stderr when packages fail to load due to invalid YAML or schema errors.",
+        ),
+    ] = False,
+) -> None:
+    """List all benchmark experiments discovered across all Nexus packages.
+
+    By default, shows a unified table with experiments and their nexus packages.
+    Use --nexus-package to filter results for a specific nexus package.
+    """
+    validate_output_format(output_format)
+
+    if not packages_root.is_dir():
+        console.print(f"[red]Error:[/red] {packages_root} is not a directory")
+        raise typer.Exit(code=1)
+
+    # Collect all benchmark data
+    benchmark_data = collect_benchmark_data(packages_root, warn_on_error=strict)
+
+    if not benchmark_data:
+        console.print(
+            "\n[yellow]No benchmark experiments found in any packages[/yellow]\n"
+        )
+        return
+
+    # Filter by nexus package if specified
+    if nexus_package:
+        filtered_data: dict[str, dict[str, list[str]]] = {}
+        for bench_pkg, experiments in benchmark_data.items():
+            for exp_id, pkg_list in experiments.items():
+                if nexus_package in pkg_list:
+                    if bench_pkg not in filtered_data:
+                        filtered_data[bench_pkg] = {}
+                    filtered_data[bench_pkg][exp_id] = [nexus_package]
+
+        if not filtered_data:
+            console.print(
+                f"\n[yellow]No benchmark experiments found for nexus package '{nexus_package}'[/yellow]\n"
+            )
+            return
+
+        benchmark_data = filtered_data
+
+    # Prepare data for output
+    if nexus_package:
+        headers = ["Experiment ID", "Benchmark Package"]
+        title = f"Benchmark Experiments for Nexus Package: {nexus_package}"
+        data = [
+            {
+                "Experiment ID": exp_id,
+                "Benchmark Package": bench_pkg,
+            }
+            for bench_pkg in sorted(benchmark_data.keys())
+            for exp_id in sorted(benchmark_data[bench_pkg].keys())
+        ]
+    else:
+        headers = ["Experiment ID", "Benchmark Package", "Used By"]
+        title = "Discovered Benchmark Experiments"
+        data = []
+        for bench_pkg in sorted(benchmark_data.keys()):
+            for exp_id in sorted(benchmark_data[bench_pkg].keys()):
+                nexus_packages = sorted(benchmark_data[bench_pkg][exp_id])
+                data.append(
+                    {
+                        "Experiment ID": exp_id,
+                        "Benchmark Package": bench_pkg,
+                        "Used By": ", ".join(nexus_packages),
+                    }
+                )
+
+    output_data(
+        data=data,
+        headers=headers,
+        output_format=output_format,
+        output_file=output_file,
+        table_title=title,
+    )
+
+    if not output_format:
+        console.print(
+            f"\n[bold]Total:[/bold] {len(data)} experiments across {len(benchmark_data)} benchmark packages\n"
+        )
+
+        # Add instructions for getting more details
+        console.print("[bold]For further details on each experiment:[/bold]")
+        console.print("1. Install the Benchmark package the experiment belongs to")
+        console.print("   [cyan]uv pip install <benchmark_package>[/cyan]")
+        console.print("2. Describe the experiment")
+        console.print("   [cyan]ado describe experiment <experiment_id>[/cyan]\n")
+
+
+# Made with Bob

algorithm_nexus/commands/run.py

@@ -0,0 +1,162 @@
+# Copyright IBM Corp. 2026
+# SPDX-License-Identifier: Apache-2.0
+
+"""Run commands for Algorithm Nexus CLI."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+from algorithm_nexus.commands.benchmark_manager import BenchmarkManager
+from algorithm_nexus.commands.utils import (
+    determine_output_format,
+    print_human_readable_results,
+    print_structured_results,
+    validate_output_format,
+    write_results_to_file,
+)
+
+try:
+    import typer
+    from rich.console import Console
+except ImportError:
+    print(
+        "Error: CLI dependencies are not installed.\n"
+        "Please install them with: pip install algorithm-nexus[cli]",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+console = Console()
+console_err = Console(stderr=True)
+
+
+def run_benchmarks(
+    pr: Annotated[
+        str,
+        typer.Option(
+            "--pr",
+            help="GitHub Pull Request URL (e.g., https://github.com/IBM/algorithm-nexus/pull/123)",
+        ),
+    ],
+    remote: Annotated[
+        Path | None,
+        typer.Option(
+            "--remote",
+            help="Execute operations on remote Ray cluster using the specified context file",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ] = None,
+    context: Annotated[
+        Path | None,
+        typer.Option(
+            "--context",
+            help="Path to ADO context YAML file (samplestore context)",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            readable=True,
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run",
+            help="List benchmarks without executing them (dry run)",
+        ),
+    ] = False,
+    output_file: Annotated[
+        Path | None,
+        typer.Option(
+            "--output-file",
+            help="Output file path for execution results. If not specified, results are printed to screen.",
+            dir_okay=False,
+            writable=True,
+        ),
+    ] = None,
+    output_format: Annotated[
+        str | None,
+        typer.Option(
+            "-o",
+            "--output-format",
+            help="Output format: 'json' or 'yaml'. Only used with --output-file.",
+        ),
+    ] = None,
+    actuator_configuration_mappings: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--use-actuator-configuration",
+            help=(
+                "Map an actuatorIdentifier to an actuatorConfigurationId using the format "
+                "'actuator-id=config-id'. Pass multiple mappings either by repeating the flag "
+                "or as a comma-separated list: 'id1=cfg-1,id2=cfg-2'. "
+                "Experiments whose actuatorIdentifier matches a key will have the "
+                "corresponding actuatorConfigurationId added to the operation's "
+                "actuatorConfigurationIdentifiers list."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """Execute benchmarks from a GitHub Pull Request.
+
+    Identifies new or changed benchmark instances in a PR and optionally
+    executes them using the ADO CLI. When executing with --remote flag,
+    automatically installs required benchmark packages in the Ray environment.
+
+    The command automatically checks if the local repository is on the same
+    commit as the PR. If not, it will checkout the PR code in a temporary
+    directory.
+    """
+    # Validate output format if specified
+    if output_format:
+        validate_output_format(output_format, allow_yaml=True, allow_csv=False)
+
+    actuator_configuration_id_map: dict[str, str] = {}
+    for entry in actuator_configuration_mappings or []:
+        for pair in entry.split(","):
+            if "=" not in pair:
+                raise typer.BadParameter(
+                    f"Invalid format '{pair}': expected 'actuator-id=config-id'",
+                    param_hint="--use-actuator-configuration",
+                )
+            key, _, value = pair.partition("=")
+
+            actuator_configuration_id_map[key] = value
+
+    try:
+        manager = BenchmarkManager(
+            pr_url=pr,
+            execute=not dry_run,
+            remote_context_file=remote,
+            context_file=context,
+            actuator_configuration_id_map=actuator_configuration_id_map or None,
+        )
+        results = manager.run()
+
+        # Output results
+        fmt = determine_output_format(output_format, output_file, default="table")
+
+        if output_file:
+            write_results_to_file(results, output_file, fmt)
+        elif fmt in ("json", "yaml"):
+            print_structured_results(results, fmt)
+        else:
+            print_human_readable_results(results)
+
+        if not dry_run and results.get("summary") and results["summary"]["failed"] > 0:
+            raise typer.Exit(code=1)
+
+    except KeyboardInterrupt:
+        console_err.print("\n[yellow]Interrupted by user[/yellow]")
+        raise typer.Exit(code=130)
+    except Exception as e:
+        console_err.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(code=1)
+
+
+# Made with Bob