feat: Add CLI commands for browsing and searching OpenML flows (models)

Author: agnik

openml/cli.py

@@ -1,4 +1,4 @@
-"""Command Line Interface for `openml` to configure its settings."""
+"""Command Line Interface for `openml` to configure settings and browse models."""
 
 from __future__ import annotations
 
@@ -9,6 +9,7 @@
 from typing import Callable
 from urllib.parse import urlparse
 
+import openml
 from openml import config
 
 
@@ -327,12 +328,144 @@ def not_supported_yet(_: str) -> None:
             set_field_function(args.value)
 
 
+def models_list(args: argparse.Namespace) -> None:
+    """List flows (models) from OpenML with optional filtering."""
+    try:
+        flows_df = openml.flows.list_flows(
+            offset=args.offset,
+            size=args.size,
+            tag=args.tag,
+            uploader=args.uploader,
+        )
+
+        if flows_df.empty:
+            print("No flows found matching the criteria.")
+            return
+
+        # Display flows in a readable format
+        if args.format == "table":
+            # Print as a formatted table
+            print(f"\nFound {len(flows_df)} flow(s):\n")
+            print(flows_df.to_string(index=False))
+        else:
+            # Print in a more compact format
+            print(f"\nFound {len(flows_df)} flow(s):\n")
+            for _, row in flows_df.iterrows():
+                print(f"ID: {row['id']:>6} | {row['name']:<40} | Version: {row['version']}")
+                if args.verbose:
+                    print(f"      Full Name: {row['full_name']}")
+                    print(f"      External Version: {row['external_version']}")
+                    print(f"      Uploader: {row['uploader']}")
+                    print()
+
+    except Exception as e:  # noqa: BLE001
+        print(f"Error listing flows: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def models_info(args: argparse.Namespace) -> None:
+    """Display detailed information about a specific flow (model)."""
+    try:
+        flow_id = int(args.flow_id)
+        flow = openml.flows.get_flow(flow_id)
+
+        # Display flow information using its __repr__ method
+        print(flow)
+
+        # Additional information
+        if flow.parameters:
+            print("\nParameters:")
+            for param_name, param_value in flow.parameters.items():
+                meta_info = flow.parameters_meta_info.get(param_name, {})
+                param_desc = meta_info.get("description", "No description")
+                param_type = meta_info.get("data_type", "unknown")
+                print(f"  {param_name}: {param_value} ({param_type})")
+                if param_desc != "No description":
+                    print(f"    Description: {param_desc}")
+
+        if flow.components:
+            print(f"\nComponents: {len(flow.components)}")
+            for comp_name, comp_flow in flow.components.items():
+                comp_id = comp_flow.flow_id if comp_flow.flow_id else "Not uploaded"
+                print(f"  {comp_name}: Flow ID {comp_id}")
+
+        if flow.tags:
+            print(f"\nTags: {', '.join(flow.tags)}")
+
+    except ValueError:
+        print(
+            f"Error: '{args.flow_id}' is not a valid flow ID. Please provide a number.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    except Exception as e:  # noqa: BLE001
+        print(f"Error retrieving flow information: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def models_search(args: argparse.Namespace) -> None:
+    """Search for flows (models) by name."""
+    try:
+        # Get all flows (or a reasonable subset)
+        flows_df = openml.flows.list_flows(
+            offset=0,
+            size=args.max_results if args.max_results else 1000,
+            tag=args.tag,
+        )
+
+        if flows_df.empty:
+            print("No flows found.")
+            return
+
+        # Filter by search query (case-insensitive)
+        query_lower = args.query.lower()
+        matching_flows = flows_df[
+            flows_df["name"].str.lower().str.contains(query_lower, na=False)
+            | flows_df["full_name"].str.lower().str.contains(query_lower, na=False)
+        ]
+
+        if matching_flows.empty:
+            print(f"No flows found matching '{args.query}'.")
+            return
+
+        print(f"\nFound {len(matching_flows)} flow(s) matching '{args.query}':\n")
+        for _, row in matching_flows.iterrows():
+            print(f"ID: {row['id']:>6} | {row['name']:<40} | Version: {row['version']}")
+            if args.verbose:
+                print(f"      Full Name: {row['full_name']}")
+                print(f"      External Version: {row['external_version']}")
+                print(f"      Uploader: {row['uploader']}")
+                print()
+
+    except Exception as e:  # noqa: BLE001
+        print(f"Error searching flows: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def models(args: argparse.Namespace) -> None:
+    """Handle models subcommands."""
+    subcommands = {
+        "list": models_list,
+        "info": models_info,
+        "search": models_search,
+    }
+
+    if args.models_subcommand in subcommands:
+        subcommands[args.models_subcommand](args)
+    else:
+        print(f"Unknown models subcommand: {args.models_subcommand}")
+        sys.exit(1)
+
+
 def main() -> None:
-    subroutines = {"configure": configure}
+    subroutines = {"configure": configure, "models": models}
 
-    parser = argparse.ArgumentParser()
-    subparsers = parser.add_subparsers(dest="subroutine")
+    parser = argparse.ArgumentParser(
+        description="OpenML Python CLI - Access OpenML datasets, tasks, flows, and more.",
+    )
+    subparsers = parser.add_subparsers(dest="subroutine", help="Available commands")
 
+    # Configure command
     parser_configure = subparsers.add_parser(
         "configure",
         description="Set or read variables in your configuration file. For more help also see "
@@ -360,8 +493,105 @@ def main() -> None:
         help="The value to set the FIELD to.",
     )
 
+    # Models command
+    parser_models = subparsers.add_parser(
+        "models",
+        description="Browse and search OpenML flows (models).",
+    )
+
+    models_subparsers = parser_models.add_subparsers(
+        dest="models_subcommand",
+        help="Available models subcommands",
+    )
+
+    # Models list command
+    parser_models_list = models_subparsers.add_parser(
+        "list",
+        description="List flows (models) from OpenML.",
+    )
+    parser_models_list.add_argument(
+        "--offset",
+        type=int,
+        default=None,
+        help="Number of flows to skip (for pagination).",
+    )
+    parser_models_list.add_argument(
+        "--size",
+        type=int,
+        default=None,
+        help="Maximum number of flows to return.",
+    )
+    parser_models_list.add_argument(
+        "--tag",
+        type=str,
+        default=None,
+        help="Filter flows by tag.",
+    )
+    parser_models_list.add_argument(
+        "--uploader",
+        type=str,
+        default=None,
+        help="Filter flows by uploader ID.",
+    )
+    parser_models_list.add_argument(
+        "--format",
+        type=str,
+        choices=["table", "compact"],
+        default="compact",
+        help="Output format (default: compact).",
+    )
+    parser_models_list.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show detailed information for each flow.",
+    )
+
+    # Models info command
+    parser_models_info = models_subparsers.add_parser(
+        "info",
+        description="Display detailed information about a specific flow (model).",
+    )
+    parser_models_info.add_argument(
+        "flow_id",
+        type=str,
+        help="The ID of the flow to display.",
+    )
+
+    # Models search command
+    parser_models_search = models_subparsers.add_parser(
+        "search",
+        description="Search for flows (models) by name.",
+    )
+    parser_models_search.add_argument(
+        "query",
+        type=str,
+        help="Search query (searches in flow names).",
+    )
+    parser_models_search.add_argument(
+        "--max-results",
+        type=int,
+        default=None,
+        help="Maximum number of results to search through (default: 1000).",
+    )
+    parser_models_search.add_argument(
+        "--tag",
+        type=str,
+        default=None,
+        help="Filter flows by tag before searching.",
+    )
+    parser_models_search.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Show detailed information for each flow.",
+    )
+
     args = parser.parse_args()
-    subroutines.get(args.subroutine, lambda _: parser.print_help())(args)
+    if args.subroutine:
+        subroutines.get(args.subroutine, lambda _: parser.print_help())(args)
+    else:
+        parser.print_help()
 
 
 if __name__ == "__main__":