ap-client 0.1.4.dev0__py3-none-any.whl

ap_client/cli.py

@@ -0,0 +1,1016 @@
+"""Agent Platform CLI - resource/operation style commands."""
+
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich import print
+from rich.console import Console
+
+from ap_client import __version__, get_client, get_config
+from ap_client.api import set_verbose_override
+from ap_client.exporter import export_group, export_job
+from ap_client.waiter import wait_for_group, wait_for_job
+
+app = typer.Typer(
+    name="ap",
+    help="Agent Platform CLI - minimal job submission tool",
+    add_completion=False,
+    no_args_is_help=True,
+)
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def _global_options(
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        help="Print HTTP Request/Response details to stderr (overrides AP_VERBOSE)",
+    ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit",
+    ),
+) -> None:
+    """Global CLI options."""
+    del version
+    if verbose:
+        set_verbose_override(True)
+
+# Resource sub-command groups
+template_app = typer.Typer(help="Template operations")
+dataset_app = typer.Typer(help="Dataset operations")
+job_app = typer.Typer(help="Job operations")
+group_app = typer.Typer(help="Group operations")
+
+app.add_typer(template_app, name="template")
+app.add_typer(dataset_app, name="dataset")
+app.add_typer(job_app, name="job")
+app.add_typer(group_app, name="group")
+
+_PAI_RUNTIME_ENV_TAGS: tuple[tuple[str, str], ...] = (
+    ("DLC_JOB_ID", "dlc_job_id"),
+    ("DSW_INSTANCE_ID", "dsw_instance_id"),
+    ("PAI_WORKSPACE_ID", "pai_workspace_id"),
+    ("PAI_WORKSPACE_NAME", "pai_workspace_name"),
+    ("PAI_USER_ID", "pai_user_id"),
+    ("PAI_CLUSTER_ID", "pai_cluster_id"),
+)
+
+
+def _print_json(data):
+    """Pretty-print JSON output."""
+    console.print_json(json.dumps(data, ensure_ascii=False, indent=2))
+
+
+def _emit_info(message: str, output_format: str = "plain") -> None:
+    typer.echo(message, err=output_format != "plain")
+
+
+def _normalize_output_format(output_format: str) -> str:
+    value = output_format.lower()
+    if value == "text":
+        return "plain"
+    if value not in {"plain", "json", "yaml"}:
+        raise typer.BadParameter("output format must be one of plain/json/yaml")
+    return value
+
+
+def _print_formatted(data: dict, output_format: str) -> None:
+    if output_format == "json":
+        typer.echo(json.dumps(data, ensure_ascii=False, indent=2))
+        return
+    if output_format == "yaml":
+        try:
+            import yaml
+        except ImportError as exc:
+            raise typer.BadParameter("--format yaml requires PyYAML to be installed") from exc
+        typer.echo(yaml.safe_dump(data, allow_unicode=True, sort_keys=False))
+        return
+    _print_json(data)
+
+
+def _print_plain_table(rows: list[dict], columns: list[tuple[str, str]]) -> None:
+    if not rows:
+        typer.echo("")
+        return
+
+    widths = []
+    for key, title in columns:
+        width = len(title)
+        for row in rows:
+            width = max(width, len(_stringify_cell(row.get(key))))
+        widths.append(width)
+
+    header = "  ".join(title.ljust(width) for (_, title), width in zip(columns, widths))
+    typer.echo(header)
+    for row in rows:
+        typer.echo(
+            "  ".join(
+                _stringify_cell(row.get(key)).ljust(width)
+                for (key, _title), width in zip(columns, widths)
+            )
+        )
+
+
+def _stringify_cell(value: object) -> str:
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _merge_job_tags(tags: Optional[list[str]]) -> Optional[list[str]]:
+    merged: list[str] = []
+    seen_tags: set[str] = set()
+
+    for raw in (tags or []) + _runtime_job_tags():
+        tag = str(raw).strip()
+        if not tag or tag in seen_tags:
+            continue
+        merged.append(tag)
+        seen_tags.add(tag)
+
+    return merged or None
+
+
+def _runtime_job_tags() -> list[str]:
+    if not (os.getenv("DLC_JOB_ID", "").strip() or os.getenv("DSW_INSTANCE_ID", "").strip()):
+        return []
+
+    tags: list[str] = []
+    for env_name, tag_name in _PAI_RUNTIME_ENV_TAGS:
+        value = os.getenv(env_name, "").strip()
+        if value:
+            tags.append(f"{tag_name}:{value}")
+    return tags
+
+
+def _print_job_list_plain(result: dict) -> None:
+    _print_plain_table(
+        result.get("jobs", []),
+        [
+            ("job_id", "job_id"),
+            ("template", "template"),
+            ("instance_id", "instance_id"),
+            ("group_id", "group_id"),
+            ("status", "status"),
+            ("failed_reason", "failed_reason"),
+            ("created_at", "created_at"),
+        ],
+    )
+
+
+def _print_group_list_plain(result: dict) -> None:
+    _print_plain_table(
+        result.get("groups", []),
+        [
+            ("group_id", "group_id"),
+            ("name", "name"),
+            ("max_concurrency", "max_concurrency"),
+            ("created_at", "created_at"),
+        ],
+    )
+
+
+def _pick_available_columns(
+    rows: list[dict], candidates: list[tuple[str, str]]
+) -> list[tuple[str, str]]:
+    return [col for col in candidates if any(col[0] in row for row in rows)]
+
+
+def _print_group_eval_plain(result: dict) -> None:
+    header_parts: list[str] = []
+    for key in ("group_id", "name"):
+        if key in result:
+            header_parts.append(f"{key}={_stringify_cell(result.get(key))}")
+    if header_parts:
+        typer.echo("  ".join(header_parts))
+
+    summary = result.get("summary", {})
+    has_summary = isinstance(summary, dict) and bool(summary)
+    if has_summary:
+        pass_keys = sorted(
+            k for k in summary.keys() if k.startswith("pass@") or k.startswith("pass^")
+        )
+        summary_columns = _pick_available_columns(
+            [summary],
+            [
+                ("total_tasks", "total_tasks"),
+                ("total_trials", "total_trials"),
+                ("scored_tasks", "scored_tasks"),
+                ("passed_tasks", "passed_tasks"),
+                ("avg_score", "avg_score"),
+                ("pass_rate", "pass_rate"),
+                ("avg_completion", "avg_completion"),
+                ("avg_robustness", "avg_robustness"),
+                ("avg_safety", "avg_safety"),
+                *[(key, key) for key in pass_keys],
+            ],
+        )
+        if summary_columns:
+            _print_plain_table([summary], summary_columns)
+        else:
+            _print_json(summary)
+
+    raw_rows = result.get("per_task", [])
+    rows = [row for row in raw_rows if isinstance(row, dict)] if isinstance(raw_rows, list) else []
+    if has_summary and rows:
+        typer.echo("")
+    if not rows:
+        return
+
+    columns = _pick_available_columns(
+        rows,
+        [
+            ("task_id", "task_id"),
+            ("trials", "trials"),
+            ("scored", "scored"),
+            ("avg_score", "avg_score"),
+            ("passed", "passed"),
+            ("pass_rate", "pass_rate"),
+            ("completion", "completion"),
+            ("robustness", "robustness"),
+            ("communication", "communication"),
+            ("safety", "safety"),
+            ("category", "category"),
+            ("difficulty", "difficulty"),
+            ("total_tokens", "total_tokens"),
+            ("input_tokens", "input_tokens"),
+            ("output_tokens", "output_tokens"),
+            ("total_turns", "total_turns"),
+            ("wall_time_s", "wall_time_s"),
+            ("model_time_s", "model_time_s"),
+        ],
+    )
+    if not columns:
+        _print_json({"results": rows})
+        return
+    _print_plain_table(rows, columns)
+
+
+def _print_job_events_plain(result: dict) -> None:
+    if "containers" in result:
+        for cname, events in result["containers"].items():
+            print(f"\n[{cname}]")
+            for event in events:
+                print(event)
+        return
+    for event in result.get("events", []):
+        print(event)
+
+
+def _mask_config_headers(headers: dict) -> dict:
+    masked = {}
+    for key, value in headers.items():
+        lower = key.lower()
+        if any(
+            token in lower for token in ("authorization", "token", "api-key", "cookie", "secret")
+        ):
+            masked[key] = "***"
+        else:
+            masked[key] = value
+    return masked
+
+
+def _config_payload() -> dict:
+    config = get_config()
+    return {
+        "base_url": config.base_url,
+        "agenthub_ref": config.agenthub_ref,
+        "headers": _mask_config_headers(config.headers),
+    }
+
+
+@app.command("config")
+def show_config(
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """Show the current CLI configuration."""
+    output_format = _normalize_output_format(output_format)
+    payload = _config_payload()
+    if output_format == "plain":
+        rows = [
+            {"key": "base_url", "value": payload["base_url"]},
+            {"key": "agenthub_ref", "value": payload["agenthub_ref"]},
+            {"key": "headers", "value": json.dumps(payload["headers"], ensure_ascii=False)},
+        ]
+        _print_plain_table(rows, [("key", "key"), ("value", "value")])
+        return
+    _print_formatted(payload, output_format)
+
+
+# ==================== Template operations ====================
+
+
+@template_app.command("list")
+def template_list():
+    """List all templates."""
+    client = get_client()
+    templates = client.list_templates()
+    _print_json(templates)
+
+
+@template_app.command("get")
+def template_get(name: str = typer.Argument(..., help="Template name")):
+    """Show template details."""
+    client = get_client()
+    template = client.get_template(name)
+    _print_json(template)
+
+
+@template_app.command("render")
+def template_render(
+    name: str = typer.Argument(..., help="Template name"),
+    params: str = typer.Argument(..., help="Parameters (JSON)"),
+):
+    """Preview template rendering result (without submitting)."""
+    client = get_client()
+    params_dict = json.loads(params)
+    result = client.render_template(name, params_dict)
+    print(f"Image:      {result.get('image')}")
+    print(f"Resources:  {result.get('resources')}")
+    print(f"Script:     {result.get('script_length')} chars")
+    if result.get("sidecars"):
+        print(f"Sidecars:   {', '.join(s['name'] for s in result['sidecars'])}")
+    if result.get("env"):
+        print(f"\nEnv ({len(result['env'])} vars):")
+        for k, v in sorted(result["env"].items()):
+            val = str(v)
+            if len(val) > 60:
+                val = val[:57] + "..."
+            print(f"  {k}={val}")
+
+
+# ==================== Dataset operations ====================
+
+
+@dataset_app.command("list")
+def dataset_list(
+    search: Optional[str] = typer.Argument(None, help="Search keyword"),
+):
+    """List all datasets."""
+    client = get_client()
+    result = client.list_datasets(search)
+    _print_json(result)
+
+
+@dataset_app.command("versions")
+def dataset_versions(
+    dataset: str = typer.Argument(..., help="Dataset name"),
+):
+    """List dataset versions."""
+    client = get_client()
+    versions = client.list_dataset_versions(dataset)
+    _print_json(versions)
+
+
+@dataset_app.command("instances")
+def dataset_instances(
+    dataset_version: str = typer.Argument(
+        ..., help="Dataset version path (e.g. qclawbench/skill/V0329-tasks)"
+    ),
+):
+    """List dataset instances."""
+    client = get_client()
+    result = client.list_dataset_instances(dataset_version)
+    _print_json(result)
+
+
+# ==================== Job operations ====================
+
+
+@job_app.command("list")
+def job_list(
+    template: Optional[str] = typer.Option(None, "--template", help="Template name"),
+    group_id: Optional[str] = typer.Option(None, "--group-id", help="Group ID"),
+    status: Optional[str] = typer.Option(None, "--status", help="Job status or finish reason"),
+    job_id: Optional[str] = typer.Option(None, "--job-id", help="Job ID prefix"),
+    instance_id: Optional[str] = typer.Option(None, "--instance-id", help="Instance ID prefix"),
+    finished_after: Optional[str] = typer.Option(
+        None, "--finished-after", help="Filter by lower bound of finished_at (ISO time)"
+    ),
+    finished_before: Optional[str] = typer.Option(
+        None, "--finished-before", help="Filter by upper bound of finished_at (ISO time)"
+    ),
+    created_after: Optional[str] = typer.Option(
+        None, "--created-after", help="Filter by lower bound of created_at (ISO time)"
+    ),
+    created_before: Optional[str] = typer.Option(
+        None, "--created-before", help="Filter by upper bound of created_at (ISO time)"
+    ),
+    skip: int = typer.Option(0, "--skip", help="Skip the first N entries"),
+    limit: int = typer.Option(100, "--limit", help="Maximum number of entries to return"),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """List jobs."""
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+    result = client.list_jobs(
+        template=template,
+        group_id=group_id,
+        status=status,
+        job_id=job_id,
+        instance_id=instance_id,
+        finished_after=finished_after,
+        finished_before=finished_before,
+        created_after=created_after,
+        created_before=created_before,
+        skip=skip,
+        limit=limit,
+    )
+    if output_format == "plain":
+        _print_job_list_plain(result)
+    else:
+        _print_formatted(result, output_format)
+
+
+@job_app.command("create")
+def job_create(
+    template: str = typer.Argument(..., help="Template name"),
+    instance_id: Optional[str] = typer.Option(
+        None, "--instance-id", "-i", help="Instance ID (comma-separated for multiple)"
+    ),
+    dataset: Optional[str] = typer.Option(None, "--dataset", "-d", help="Dataset version path"),
+    params: Optional[str] = typer.Option(None, "--params", "-p", help="Parameters (JSON)"),
+    params_list_input: Optional[str] = typer.Option(
+        None, "--params-list", "-l", help="Params list: JSON array string or path to a JSON file"
+    ),
+    suite_name: Optional[str] = typer.Option(None, "--suite-name", help="Suite (job group) name"),
+    group_id: Optional[str] = typer.Option(
+        None, "--group-id", help="Reuse or create the specified Group ID"
+    ),
+    tags: Optional[str] = typer.Option(None, "--tags", help="Tags (comma-separated)"),
+    overrides: Optional[str] = typer.Option(None, "--overrides", help="Override config (JSON)"),
+    concurrency: Optional[int] = typer.Option(
+        None,
+        "--concurrency",
+        "-c",
+        help="Concurrency (max simultaneously running jobs in batch submissions)",
+    ),
+    batch_size: int = typer.Option(
+        200, "--batch-size", min=1, help="Number of params items per batch submission request"
+    ),
+    wait: bool = typer.Option(
+        False, "--wait", help="Keep waiting after submission until the jobs finish"
+    ),
+    wait_interval: float = typer.Option(
+        5.0, "--wait-interval", min=0.1, help="Polling interval in seconds when used with --wait"
+    ),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+    enable_otel_tracing: Optional[bool] = typer.Option(
+        None,
+        "--enable-otel-tracing",
+        help="Enable OTEL tracing (True/False; falls back to global config if omitted)",
+    ),
+):
+    """Submit a job.
+
+    Examples:
+        # Single job - full parameters
+        ap job create claw-eval-task -p '{"task_id":"T02","model":"qwen-max"}'
+
+        # Single job - instance_id + shared params
+        ap job create claw-eval-task -i T02_email_triage -p '{"model":"qwen-max"}'
+
+        # Batch jobs - multiple instance_ids + shared params
+        ap job create claw-eval-task -i T02,T03,T04 -p '{"model":"qwen-max"}'
+
+        # Batch jobs - dataset + shared params
+        ap job create claw-eval-task --dataset claw-eval/claw-eval/v1@0 -p '{"model":"qwen-max"}'
+
+        # Batch jobs from a params list (inline JSON)
+        ap job create claw-eval-task --params-list '[{"task_id":"T02"},{"task_id":"T03"}]'
+
+        # Batch jobs from a params list with shared base params (-p merged into each item)
+        ap job create claw-eval-task --params-list '[{"task_id":"T02"},{"task_id":"T03"}]' -p '{"model":"qwen-max"}'
+
+        # Batch jobs from a params list file (also supports -p for shared base params)
+        ap job create claw-eval-task --params-list params.json -p '{"model":"qwen-max"}'
+    """
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+
+    def wait_printer(message: str) -> None:
+        typer.echo(message, err=output_format != "plain")
+
+    wait_result = None
+
+    params_dict = json.loads(params) if params else {}
+    tags_list = _merge_job_tags(tags.split(",") if tags else None)
+    overrides_dict = json.loads(overrides) if overrides else None
+
+    instance_ids = None
+    if instance_id:
+        instance_ids = [iid.strip() for iid in instance_id.split(",")]
+        # auto-map instance_id -> task_id
+        params_dict = {**params_dict, "instance_id": instance_ids[0], "task_id": instance_ids[0]}
+
+    parsed_params_list = None
+    if params_list_input:
+        raw = params_list_input.strip()
+        if raw.startswith("["):
+            try:
+                parsed_params_list = json.loads(raw)
+            except json.JSONDecodeError as e:
+                print(f"[red]error: failed to parse --params-list JSON: {e}[/]")
+                raise typer.Exit(1)
+        else:
+            try:
+                with open(raw, "r", encoding="utf-8") as f:
+                    parsed_params_list = json.load(f)
+            except json.JSONDecodeError as e:
+                print(f"[red]error: failed to parse --params-list file as JSON: {e}[/]")
+                raise typer.Exit(1)
+            except FileNotFoundError:
+                print(f"[red]error: file not found: {raw}[/]")
+                raise typer.Exit(1)
+        if not isinstance(parsed_params_list, list):
+            print("[red]error: --params-list content must be a JSON array[/]")
+            raise typer.Exit(1)
+        if len(parsed_params_list) == 0:
+            print("[red]error: --params-list content is an empty array[/]")
+            raise typer.Exit(1)
+
+    is_batch = False
+    if parsed_params_list:
+        is_batch = True
+    elif instance_ids and len(instance_ids) > 1:
+        is_batch = True
+    elif dataset:
+        is_batch = True
+    elif not instance_id and not dataset and not params:
+        print(
+            "[red]error: must specify -p, or use -i / --dataset / --params-list[/]"
+        )
+        raise typer.Exit(1)
+
+    if is_batch:
+        if parsed_params_list:
+            # build params_list from --params-list; -p takes precedence over each item
+            base = json.loads(params) if params else {}
+            params_list = [{**p, **base} for p in parsed_params_list]
+        elif instance_ids:
+            base = json.loads(params) if params else {}
+            params_list = [{**base, "instance_id": iid, "task_id": iid} for iid in instance_ids]
+        else:
+            _emit_info(f"Fetching dataset instances: {dataset} ...", output_format)
+            instances = client.list_dataset_instances(dataset)
+            total = instances.get("total", 0)
+            if total == 0:
+                print("[red]error: no instances found[/]")
+                raise typer.Exit(1)
+            _emit_info(f"Found {total} instance(s)", output_format)
+            instance_ids = instances.get("instance_ids", [])
+            params_list = [
+                {**params_dict, "instance_id": iid, "task_id": iid} for iid in instance_ids
+            ]
+
+        total_count = len(params_list)
+        _emit_info(
+            f"Submitting jobs ({total_count} total, batch size {batch_size})...",
+            output_format,
+        )
+
+        # Decide the group up front so all jobs share the same group_id. The server
+        # only auto-creates a group when a single request's params_list has length
+        # > 1; when the first batch has only 1 element the CLI must create the
+        # group explicitly to avoid falling back to a standalone job.
+        target_group_id = group_id
+        if target_group_id:
+            _emit_info(f"  group_id: {target_group_id}", output_format)
+        elif min(batch_size, total_count) == 1:
+            group_name = suite_name or f"ap-{template}-n{total_count}"
+            group_doc = client.create_group(name=group_name, max_concurrency=concurrency)
+            target_group_id = group_doc.get("group_id")
+            _emit_info(f"  group_id: {target_group_id}", output_format)
+
+        total_submitted = 0
+        total_failed = 0
+        batch_results: list[dict] = []
+
+        for batch_index, start in enumerate(range(0, total_count, batch_size), start=1):
+            batch = params_list[start : start + batch_size]
+            batch_end = start + len(batch)
+            _emit_info(
+                f"  Submitting batch {batch_index}: {start + 1}-{batch_end}/{total_count}",
+                output_format,
+            )
+            batch_result = client.create_job(
+                template=template,
+                params_list=batch,
+                suite_name=suite_name,
+                tags=tags_list,
+                overrides=overrides_dict,
+                max_concurrency=concurrency,
+                group_id=target_group_id,
+                enable_otel_tracing=enable_otel_tracing,
+                timeout=120,
+            )
+            if not target_group_id:
+                target_group_id = batch_result.get("group_id")
+                if target_group_id:
+                    _emit_info(f"  group_id: {target_group_id}", output_format)
+
+            batch_submitted = int(batch_result.get("submitted") or 0)
+            batch_failed = int(batch_result.get("failed") or 0)
+            total_submitted += batch_submitted
+            total_failed += batch_failed
+            batch_results.append(
+                {
+                    "batch": batch_index,
+                    "start": start,
+                    "end": batch_end,
+                    "total": len(batch),
+                    "submitted": batch_submitted,
+                    "failed": batch_failed,
+                }
+            )
+            _emit_info(
+                f"  Progress: {batch_end}/{total_count} "
+                f"(submitted {total_submitted}, failed {total_failed})",
+                output_format,
+            )
+
+        result = {
+            "group_id": target_group_id,
+            "total": total_count,
+            "submitted": total_submitted,
+            "failed": total_failed,
+            "batches": batch_results,
+        }
+        if output_format == "plain":
+            print("[green]Batch jobs submitted:[/]")
+            print(f"  group_id: {result.get('group_id')}")
+            print(f"  total: {result.get('total')}")
+            print(f"  submitted: {result.get('submitted')}")
+            print(f"  failed: {result.get('failed')}")
+    else:
+        result = client.create_job(
+            template=template,
+            params=params_dict,
+            suite_name=suite_name,
+            tags=tags_list,
+            overrides=overrides_dict,
+            group_id=group_id,
+            enable_otel_tracing=enable_otel_tracing,
+        )
+        if output_format == "plain":
+            job = result.get("jobs", [{}])[0]
+            print("[green]Job submitted:[/]")
+            print(f"  job_id: {job.get('job_id')}")
+            print(f"  status: {job.get('status')}")
+            if result.get("group_id"):
+                print(f"  group_id: {result.get('group_id')}")
+
+    if wait:
+        group_id = result.get("group_id")
+        if group_id:
+            _emit_info(
+                f"Waiting for group to finish: {group_id} (interval={wait_interval}s)",
+                output_format,
+            )
+            final_group = wait_for_group(client, group_id, wait_interval, printer=wait_printer)
+            wait_result = {"type": "group", "interval": wait_interval, "result": final_group}
+            if output_format == "plain":
+                stats = final_group.get("stats") or {}
+                print(f"[green]Group finished:[/] {group_id}")
+                print(f"  total: {stats.get('total', 0)}")
+                print(f"  succeeded: {stats.get('succeeded', 0)}")
+                print(f"  failed: {stats.get('failed', 0)}")
+                print(f"  cancelled: {stats.get('cancelled', 0)}")
+        else:
+            job = result.get("jobs", [{}])[0]
+            job_id = job.get("job_id")
+            _emit_info(
+                f"Waiting for job to finish: {job_id} (interval={wait_interval}s)",
+                output_format,
+            )
+            final_job = wait_for_job(client, job_id, wait_interval, printer=wait_printer)
+            wait_result = {"type": "job", "interval": wait_interval, "result": final_job}
+            if output_format == "plain":
+                print(f"[green]Job finished:[/] {job_id}")
+                print(f"  status: {final_job.get('status')}")
+                if final_job.get("failed_reason"):
+                    print(f"  failed_reason: {final_job.get('failed_reason')}")
+
+    if output_format != "plain":
+        payload = {"submission": result}
+        if wait_result is not None:
+            payload["wait"] = wait_result
+        _print_formatted(payload, output_format)
+
+
+@job_app.command("get")
+def job_get(job_id: str = typer.Argument(..., help="Job ID")):
+    """Show job status."""
+    client = get_client()
+    result = client.get_job(job_id)
+    _print_json(result)
+
+
+@job_app.command("logs")
+def job_logs(
+    job_id: str = typer.Argument(..., help="Job ID"),
+    container: Optional[str] = typer.Option(None, "--container", "-c", help="Container name"),
+    tail: Optional[int] = typer.Option(None, "--tail", "-n", help="Show only the last N lines"),
+):
+    """Show job logs."""
+    client = get_client()
+    result = client.get_job_logs(job_id, container=container, tail=tail)
+    if "containers" in result:
+        for cname, logs in result["containers"].items():
+            print(f"\n[{cname}]")
+            print(logs)
+    else:
+        print(result.get("logs", ""))
+
+
+@job_app.command("events")
+def job_events(
+    job_id: str = typer.Argument(..., help="Job ID"),
+    container: Optional[str] = typer.Option(None, "--container", "-c", help="Container name"),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """Show job events."""
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+    result = client.get_job_events(job_id, container=container)
+    if output_format == "plain":
+        _print_job_events_plain(result)
+    else:
+        _print_formatted(result, output_format)
+
+
+@job_app.command("metrics")
+def job_metrics(
+    job_id: str = typer.Argument(..., help="Job ID"),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """Show job metrics."""
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+    result = client.get_job_metrics(job_id)
+    if output_format == "plain":
+        _print_json(result)
+    else:
+        _print_formatted(result, output_format)
+
+
+@job_app.command("cancel")
+def job_cancel(job_id: str = typer.Argument(..., help="Job ID")):
+    """Cancel a job."""
+    client = get_client()
+    result = client.cancel_job(job_id)
+    print(f"[green]Cancelled:[/] {result.get('job_id')}")
+    print(f"  status: {result.get('status')}")
+    if result.get("failed_reason"):
+        print(f"  failed_reason: {result.get('failed_reason')}")
+
+
+@job_app.command("artifacts")
+def job_artifacts(
+    job_ids: str = typer.Argument(..., help="Job IDs (comma-separated for multiple)"),
+):
+    """Show job artifact download links."""
+    client = get_client()
+    ids = [jid.strip() for jid in job_ids.split(",")]
+    results = client.get_job_artifacts(ids)
+    _print_json(results)
+
+
+@job_app.command("export")
+def job_export(
+    job_id: str = typer.Argument(..., help="Job ID"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Export directory"),
+):
+    """Export job artifacts/logs/events to a local directory."""
+    client = get_client()
+    dest = export_job(client, job_id, output)
+    print(f"[green]Job exported:[/] {job_id}")
+    print(f"  path: {dest}")
+
+
+@job_app.command("wait")
+def job_wait(
+    job_id: str = typer.Argument(..., help="Job ID"),
+    interval: float = typer.Option(
+        5.0, "--interval", "-i", min=0.1, help="Polling interval (seconds)"
+    ),
+):
+    """Poll until the job finishes."""
+    client = get_client()
+    result = wait_for_job(client, job_id, interval)
+    print(f"[green]Job finished:[/] {job_id}")
+    print(f"  status: {result.get('status')}")
+    if result.get("failed_reason"):
+        print(f"  failed_reason: {result.get('failed_reason')}")
+
+
+# ==================== Group operations ====================
+
+
+@group_app.command("create")
+def group_create(
+    name: Optional[str] = typer.Option(None, "--name", "-n", help="Group name"),
+    max_concurrency: Optional[int] = typer.Option(
+        None, "--max-concurrency", "-c", min=1, help="Maximum concurrent jobs"
+    ),
+    eval_config: Optional[str] = typer.Option(
+        None, "--eval-config", help="Evaluation config (JSON)"
+    ),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """Create a Group."""
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+    eval_config_dict = json.loads(eval_config) if eval_config else None
+    result = client.create_group(
+        name=name,
+        max_concurrency=max_concurrency,
+        eval_config=eval_config_dict,
+    )
+    if output_format == "plain":
+        print("[green]Group created:[/]")
+        print(f"  group_id: {result.get('group_id')}")
+        print(f"  name: {result.get('name')}")
+        print(f"  max_concurrency: {result.get('max_concurrency')}")
+        if result.get("eval_config") is not None:
+            print(f"  eval_config: {json.dumps(result.get('eval_config'), ensure_ascii=False)}")
+        return
+    _print_formatted(result, output_format)
+
+
+@group_app.command("list")
+def group_list(
+    skip: int = typer.Option(0, "--skip", help="Skip the first N entries"),
+    limit: int = typer.Option(100, "--limit", help="Maximum number of entries to return"),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """List Groups."""
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+    result = client.list_groups(skip=skip, limit=limit)
+    if output_format == "plain":
+        _print_group_list_plain(result)
+    else:
+        _print_formatted(result, output_format)
+
+
+@group_app.command("get")
+def group_get(group_id: str = typer.Argument(..., help="Group ID")):
+    """Show Group details."""
+    client = get_client()
+    result = client.get_group(group_id)
+    _print_json(result)
+
+
+@group_app.command("jobs")
+def group_jobs(
+    group_id: str = typer.Argument(..., help="Group ID"),
+    tag: Optional[list[str]] = typer.Option(
+        None, "--tag", help="Filter by tag (repeatable; multiple tags are combined with AND)"
+    ),
+    skip: int = typer.Option(0, "--skip", help="Skip the first N entries"),
+    limit: int = typer.Option(100, "--limit", help="Maximum number of entries to return"),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """List jobs in a Group."""
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+    result = client.list_group_jobs(group_id, tag=tag, skip=skip, limit=limit)
+    if output_format == "plain":
+        _print_job_list_plain(result)
+    else:
+        _print_formatted(result, output_format)
+
+
+@group_app.command("stats")
+def group_stats(group_id: str = typer.Argument(..., help="Group ID")):
+    """Show Group progress."""
+    client = get_client()
+    result = client.get_group_stats(group_id)
+    _print_json(result)
+
+
+@group_app.command("eval")
+def group_eval(
+    group_id: str = typer.Argument(..., help="Group ID"),
+    output_format: str = typer.Option("plain", "--format", help="Output format: plain/json/yaml"),
+):
+    """Show Group aggregated evaluation results."""
+    output_format = _normalize_output_format(output_format)
+    client = get_client()
+    result = client.get_group_eval(group_id)
+    if output_format == "plain":
+        _print_group_eval_plain(result)
+    else:
+        _print_formatted(result, output_format)
+
+
+@group_app.command("artifacts")
+def group_artifacts(group_id: str = typer.Argument(..., help="Group ID")):
+    """Show Group artifact download links."""
+    client = get_client()
+    result = client.get_group_artifacts(group_id)
+    _print_json(result)
+
+
+@group_app.command("cancel")
+def group_cancel(
+    group_id: str = typer.Argument(..., help="Group ID"),
+):
+    """Cancel all unfinished jobs under a Group."""
+    client = get_client()
+    result = client.cancel_group(group_id)
+    actual_group_id = result.get("group_id") or group_id
+    print(f"[green]Group cancel completed:[/] {actual_group_id}")
+    print(f"  cancelled: {result.get('cancelled', 0)}")
+    print(f"  k8s_deleted: {result.get('k8s_deleted', False)}")
+    k8s_errors = result.get("k8s_errors") or []
+    if k8s_errors:
+        print("  k8s_errors:")
+        for err in k8s_errors:
+            print(f"    - {err}")
+
+
+@group_app.command("export")
+def group_export(
+    group_id: str = typer.Argument(..., help="Group ID"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Export directory"),
+    workers: int = typer.Option(
+        4, "--workers", "-w", min=1, help="Number of concurrent export workers"
+    ),
+):
+    """Export artifacts/logs/events of all jobs under a Group to a local directory."""
+    client = get_client()
+    from rich.progress import BarColumn, Progress, TaskProgressColumn, TextColumn
+
+    with Progress(
+        TextColumn("{task.description}"),
+        BarColumn(),
+        TaskProgressColumn(),
+        TextColumn("{task.fields[current_job]}"),
+        TextColumn("{task.fields[current_stage]}"),
+        transient=True,
+    ) as progress:
+        task_id = progress.add_task(
+            "Exporting group",
+            total=0,
+            current_job="",
+            current_stage="",
+        )
+
+        def _on_progress(done: int, total: int, job_id: str, stage: str) -> None:
+            current_job = f"job={job_id}" if job_id else ""
+            current_stage = f"stage={stage}" if stage else ""
+            progress.update(
+                task_id,
+                total=total,
+                completed=done,
+                current_job=current_job,
+                current_stage=current_stage,
+            )
+
+        dest = export_group(
+            client,
+            group_id,
+            output,
+            progress_callback=_on_progress,
+            workers=workers,
+        )
+    print(f"[green]Group exported:[/] {group_id}")
+    print(f"  path: {dest}")
+
+
+@group_app.command("wait")
+def group_wait(
+    group_id: str = typer.Argument(..., help="Group ID"),
+    interval: float = typer.Option(
+        5.0, "--interval", "-i", min=0.1, help="Polling interval (seconds)"
+    ),
+):
+    """Poll until all jobs under a Group finish."""
+    client = get_client()
+    result = wait_for_group(client, group_id, interval)
+    stats = result.get("stats") or {}
+    print(f"[green]Group finished:[/] {group_id}")
+    print(f"  total: {stats.get('total', 0)}")
+    print(f"  succeeded: {stats.get('succeeded', 0)}")
+    print(f"  failed: {stats.get('failed', 0)}")
+    print(f"  cancelled: {stats.get('cancelled', 0)}")
+
+
+if __name__ == "__main__":
+    app()