SDK-91: Refactor CLI into modular subcommands for eval, unlearning, and dataset-qa

docs/hirundo.cli_dataset_qa.rst

@@ -0,0 +1,10 @@
+.. meta::
+   :http-equiv=Content-Security-Policy: default-src 'self', frame-ancestors 'none'
+
+hirundo.cli_dataset_qa module
+=============================
+
+.. automodule:: hirundo.cli_dataset_qa
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/hirundo.cli_eval.rst

@@ -0,0 +1,10 @@
+.. meta::
+   :http-equiv=Content-Security-Policy: default-src 'self', frame-ancestors 'none'
+
+hirundo.cli_eval module
+=======================
+
+.. automodule:: hirundo.cli_eval
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/hirundo.cli_unlearning.rst

@@ -0,0 +1,10 @@
+.. meta::
+   :http-equiv=Content-Security-Policy: default-src 'self', frame-ancestors 'none'
+
+hirundo.cli_unlearning module
+=============================
+
+.. automodule:: hirundo.cli_unlearning
+   :members:
+   :undoc-members:
+   :show-inheritance:

hirundo/_cli_common.py

@@ -0,0 +1,73 @@
+import re
+import sys
+from collections.abc import Callable
+from enum import Enum
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+_RUN_ID_RE = re.compile(r"^[a-zA-Z0-9_-]+$")
+
+docs = "sphinx" in sys.modules
+hirundo_epilog = (
+    None
+    if docs
+    else "Made with ❤️ by Hirundo. Visit https://www.hirundo.io for more information."
+)
+
+console = Console()
+
+
+def make_app(name: str, help_text: str) -> typer.Typer:
+    return typer.Typer(
+        name=name,
+        no_args_is_help=True,
+        rich_markup_mode="rich",
+        epilog=hirundo_epilog,
+        help=help_text,
+    )
+
+
+def validate_run_id(run_id: str) -> str:
+    if not _RUN_ID_RE.fullmatch(run_id):
+        console.print(
+            f"[red]Invalid run ID '{run_id}'. "
+            "Run IDs may only contain alphanumeric characters, hyphens, and underscores.[/red]"
+        )
+        raise typer.Exit(code=1) from None
+    return run_id
+
+
+def validate_enum(value: str, enum_cls: type[Enum], label: str) -> Any:
+    try:
+        return enum_cls(value.upper())
+    except ValueError:
+        valid = ", ".join(member.value for member in enum_cls)
+        console.print(f"[red]Invalid {label} '{value}'. Valid options: {valid}[/red]")
+        raise typer.Exit(code=1) from None
+
+
+def wait_or_notify(
+    run_id: str, check_fn: Callable[[str], Any], cmd_name: str, wait: bool
+) -> Any:
+    if wait:
+        return check_fn(run_id)
+    console.print(
+        f"Use [bold]hirundo {cmd_name} check[/bold] [italic]<run_id>[/italic] to monitor progress."
+    )
+    return None
+
+
+def print_runs_table(
+    title: str,
+    columns: tuple[str, ...],
+    rows: list[tuple[str | None, ...]],
+) -> None:
+    table = Table(title=title, expand=True)
+    for col in columns:
+        table.add_column(col, overflow="fold")
+    for row in rows:
+        table.add_row(*row)
+    console.print(table)

hirundo/cli.py

@@ -1,23 +1,16 @@
 import os
 import re
-import sys
 from pathlib import Path
 from typing import Annotated
 from urllib.parse import urlparse
 
 import typer
-from rich.console import Console
-from rich.table import Table
 
+from hirundo._cli_common import docs, hirundo_epilog, validate_run_id
 from hirundo._env import API_HOST, EnvLocation
-
-docs = "sphinx" in sys.modules
-hirundo_epilog = (
-    None
-    if docs
-    else "Made with ❤️ by Hirundo. Visit https://www.hirundo.io for more information."
-)
-
+from hirundo.cli_dataset_qa import dataset_qa_app, dataset_qa_list
+from hirundo.cli_eval import eval_app
+from hirundo.cli_unlearning import unlearning_app
 
 app = typer.Typer(
     name="hirundo",
@@ -26,6 +19,10 @@
     epilog=hirundo_epilog,
 )
 
+app.add_typer(eval_app, name="eval")
+app.add_typer(dataset_qa_app, name="dataset-qa")
+app.add_typer(unlearning_app, name="unlearning")
+
 
 def _upsert_env(dotenv_filepath: str | Path, var_name: str, var_value: str):
     """
@@ -197,45 +194,17 @@ def check_run(
     """
     from hirundo.dataset_qa import QADataset
 
-    results = QADataset.check_run_by_id(run_id)
-    print(f"Run results saved to {results.cached_zip_path}")
+    results = QADataset.check_run_by_id(validate_run_id(run_id))
+    if results is not None:
+        print(f"Run results saved to {results.cached_zip_path}")
 
 
 @app.command("list-runs", epilog=hirundo_epilog)
 def list_runs():
     """
     List all runs available.
     """
-    from hirundo.dataset_qa import QADataset
-
-    runs = QADataset.list_runs()
-
-    console = Console()
-    table = Table(
-        title="Runs:",
-        expand=True,
-    )
-    cols = (
-        "Dataset name",
-        "Run ID",
-        "Status",
-        "Created At",
-        "Run Args",
-    )
-    for col in cols:
-        table.add_column(
-            col,
-            overflow="fold",
-        )
-    for run in runs:
-        table.add_row(
-            str(run.name),
-            str(run.id),
-            str(run.status),
-            run.created_at.isoformat(),
-            run.run_args.model_dump_json() if run.run_args else None,
-        )
-    console.print(table)
+    dataset_qa_list(archived=False)
 
 
 typer_click_object = typer.main.get_command(app)

hirundo/cli_dataset_qa.py

@@ -0,0 +1,80 @@
+from typing import Annotated
+
+import typer
+
+from hirundo._cli_common import (
+    console,
+    hirundo_epilog,
+    make_app,
+    print_runs_table,
+    validate_run_id,
+    wait_or_notify,
+)
+
+dataset_qa_app = make_app("dataset-qa", "Launch and monitor Dataset QA runs.")
+
+
+@dataset_qa_app.command("run", epilog=hirundo_epilog)
+def dataset_qa_run(
+    dataset_id: Annotated[int, typer.Argument(help="ID of the dataset to run QA on.")],
+    wait: Annotated[
+        bool,
+        typer.Option(
+            "--wait/--no-wait", help="Wait for the run to complete and stream progress."
+        ),
+    ] = True,
+):
+    """
+    Launch a Dataset QA run on the dataset with the given ID.
+    """
+    from hirundo.dataset_qa import QADataset
+
+    run_id = QADataset.launch_qa_run(dataset_id)
+    console.print(f"Dataset QA run started. Run ID: [bold]{run_id}[/bold]")
+
+    results = wait_or_notify(run_id, QADataset.check_run_by_id, "dataset-qa", wait)
+    if results is not None:
+        console.print(f"Run results saved to {results.cached_zip_path}")
+
+
+@dataset_qa_app.command("list", epilog=hirundo_epilog)
+def dataset_qa_list(
+    archived: Annotated[
+        bool,
+        typer.Option("--archived/--no-archived", help="Include archived runs."),
+    ] = False,
+):
+    """
+    List Dataset QA runs.
+    """
+    from hirundo.dataset_qa import QADataset
+
+    runs = QADataset.list_runs(archived=archived)
+    print_runs_table(
+        "Dataset QA Runs:",
+        ("Dataset Name", "Run ID", "Status", "Created At", "Run Args"),
+        [
+            (
+                str(run.name),
+                str(run.run_id),
+                str(run.status),
+                run.created_at.isoformat(),
+                run.run_args.model_dump_json() if run.run_args else None,
+            )
+            for run in runs
+        ],
+    )
+
+
+@dataset_qa_app.command("check", epilog=hirundo_epilog)
+def dataset_qa_check(
+    run_id: Annotated[str, typer.Argument(help="The run ID to check.")],
+):
+    """
+    Check the status of a Dataset QA run and stream progress.
+    """
+    from hirundo.dataset_qa import QADataset
+
+    results = QADataset.check_run_by_id(validate_run_id(run_id))
+    if results is not None:
+        console.print(f"Run results saved to {results.cached_zip_path}")