ap-client 0.5.1.dev5__tar.gz → 0.5.3.dev0__tar.gz

{ap_client-0.5.1.dev5 → ap_client-0.5.3.dev0}/PKG-INFO

@@ -1,17 +1,18 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.5.1.dev5
+Version: 0.5.3.dev0
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
+Requires-Dist: irepo-artifact==0.2.1
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.28.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: websockets>=13.0
 Provides-Extra: all
-Requires-Dist: instance-repo[oss]==1.3.2.dev5; extra == 'all'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.3.5.dev2; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]==1.3.2.dev5; extra == 'dataset'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.3.5.dev2; extra == 'dataset'
 Description-Content-Type: text/markdown
 
 A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.

{ap_client-0.5.1.dev5 → ap_client-0.5.3.dev0}/ap_client/api.py

@@ -539,11 +539,11 @@ class APIClient:
 
     def _post(self, path: str, data: Any, timeout: TimeoutType = None) -> Any:
         """Send a POST request."""
-        from .managed_ak import parameter_ak_ids, require_parameter_ak_ack
+        from .managed_ak import parameter_ak_usage, require_parameter_ak_ack
 
-        references = parameter_ak_ids(data) if path == "/jobs" else set()
+        references, selectors = parameter_ak_usage(data) if path == "/jobs" else (set(), set())
         result = self._request("POST", path, json_body=data, timeout=timeout)
-        require_parameter_ak_ack(result, references)
+        require_parameter_ak_ack(result, references, selectors)
         return result
 
     def _delete(self, path: str, *, params: Optional[dict] = None) -> Any:
@@ -709,13 +709,16 @@ class APIClient:
         request_id: str,
         duration_ms: float,
         exc: Exception,
+        *,
+        error_detail: str | None = None,
     ) -> None:
+        detail = str(exc) if error_detail is None else error_detail
         _write_stderr(
             [
                 f"!! Error {method} {url}",
                 f"   request_id={request_id}",
                 f"   duration_ms={duration_ms:.1f}",
-                f"   error={type(exc).__name__}: {exc}",
+                f"   error={type(exc).__name__}: {detail}",
             ]
         )
 
@@ -1878,9 +1881,12 @@ class APIClient:
         meta_job_type: Optional[str] = None,
         meta_teacher_direction: Optional[str] = None,
         meta_train_stage: Optional[str] = None,
+        benchmark: Optional[str] = None,
     ) -> dict:
         """Update group properties.
 
+        ``benchmark`` is omitted when None; pass an empty string to clear it.
+
         ``tags``（`key:value` 数组）在客户端先与 Group 现有 tags 合并，再以
         全量替换语义提交（服务端 PATCH 是整体替换）；同名 key 覆盖，未提及
         的 key 保留。服务端会从 tags 同步 meta_* 等派生字段。
@@ -1903,6 +1909,8 @@ class APIClient:
             body["model"] = model
         if scaffold is not None:
             body["scaffold"] = scaffold
+        if benchmark is not None:
+            body["benchmark"] = benchmark
         meta_attr_tags = _merge_meta_tags(
             None,
             meta_model=meta_model,

{ap_client-0.5.1.dev5 → ap_client-0.5.3.dev0}/ap_client/cli.py

@@ -25,7 +25,7 @@ from ap_client.api import (
 )
 from ap_client.config import ENV_VAR_SPECS, ConfigurationError, _parse_bool, normalize_output_format
 from ap_client.dataset_commands import register as _register_dataset_commands
-from ap_client.exporter import export_group, export_job
+from ap_client.exporter import export_group, export_job, export_jobs
 from ap_client.fs_commands import register as _register_fs_commands
 from ap_client.instance_commands import register as _register_instance_commands
 from ap_client.managed_ak import (
@@ -35,6 +35,7 @@ from ap_client.managed_ak import (
     validate_ak_id,
     validate_ak_selection,
 )
+from ap_client.ossutil_commands import register as _register_ossutil_commands
 from ap_client.profile_commands import profile_app
 from ap_client.waiter import (
     WaitTimeoutError,
@@ -167,6 +168,7 @@ app.add_typer(checkpoint_app, name="checkpoint")
 # ap dataset version/split/access 嵌套在 dataset 下;instance/fs 是一等资源。
 _register_dataset_commands(dataset_app)
 _register_instance_commands(app)
+_register_ossutil_commands(app)
 _register_fs_commands(app)
 _register_akpool_commands(app)
 
@@ -359,6 +361,22 @@ def _emit_error(message: str) -> None:
     error_console.print(f"[red]error: {message}[/]")
 
 
+def _read_client(share_token: Optional[str] = None, group_id: Optional[str] = None):
+    if group_id and not share_token:
+        raise typer.BadParameter("--group-id requires --share-token")
+    client = get_client()
+    if share_token is None:
+        return client
+    from ap_client.share_api import ShareAPIClient
+
+    # Typer verbose tracebacks must not render the share token in locals.
+    app.pretty_exceptions_show_locals = False
+    try:
+        return ShareAPIClient.from_client(client, share_token, group_id=group_id)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
 def _reject_account_pool_template_credential_cli(
     account_pool: Optional[str],
     *credential_types: Any,
@@ -3564,8 +3582,8 @@ def job_create(
         if dry_run:
             _emit_dry_run_warnings(dry_run_warnings)
             body["dry_run"] = True
-            result = client._post("/jobs", body, timeout=timeout)
             try:
+                result = client._post("/jobs", body, timeout=timeout)
                 require_managed_ak_ack(result, ak_id)
             except ManagedAKProtocolError as exc:
                 _emit_error(str(exc))
@@ -4427,6 +4445,9 @@ def job_create(
 @job_app.command("get")
 def job_get(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     include_params: bool = typer.Option(
         False,
         "--include-params",
@@ -4463,7 +4484,7 @@ def job_get(
         include_spec = include_spec or _field_path_requires_spec(field)
         if field == "job_spec_data.spec_yaml":
             spec_format = "yaml"
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job(
         job_id,
         include_params=include_params,
@@ -4489,6 +4510,9 @@ def job_get(
 @job_app.command("containers")
 def job_containers(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -4497,7 +4521,7 @@ def job_containers(
 ):
     """List container names for a job."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job_containers(job_id)
     if output_format == "table":
         _print_records_table(result)
@@ -4559,6 +4583,9 @@ def _print_tail_logs(logs, tail: int) -> None:
 @job_app.command("logs")
 def job_logs(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     container: Optional[str] = typer.Option("main", "--container", "-c", help="Container name"),
     tail: Optional[int] = typer.Option(None, "--tail", "-n", help="Show only the last N log lines"),
     follow: bool = typer.Option(
@@ -4570,7 +4597,7 @@ def job_logs(
     ),
 ):
     """Show job logs."""
-    client = get_client()
+    client = _read_client(share_token)
 
     if tail is not None:
         if tail <= 0:
@@ -4634,6 +4661,9 @@ def job_logs(
 @job_app.command("events")
 def job_events(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     container: Optional[str] = typer.Option(None, "--container", "-c", help="Container name"),
     output_format: str = typer.Option(
         None,
@@ -4643,7 +4673,7 @@ def job_events(
 ):
     """Show job events."""
     output_format = _normalize_output_format(output_format)
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job_events(job_id, container=container)
     if output_format == "plain":
         _print_job_events_plain(result)
@@ -4654,6 +4684,9 @@ def job_events(
 @job_app.command("metrics")
 def job_metrics(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -4662,7 +4695,7 @@ def job_metrics(
 ):
     """Show job metrics."""
     output_format = _normalize_output_format(output_format)
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job_metrics(job_id)
     if output_format == "plain":
         _print_json(result)
@@ -4859,6 +4892,9 @@ def job_retry(
 @job_app.command("artifacts")
 def job_artifacts(
     job_ids: str = typer.Argument(..., help="Job IDs (comma-separated for multiple)"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -4867,7 +4903,7 @@ def job_artifacts(
 ):
     """Show job artifact download links."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token)
     ids = [jid.strip() for jid in job_ids.split(",")]
     results = client.get_job_artifacts(ids)
     if output_format == "table":
@@ -4876,10 +4912,50 @@ def job_artifacts(
         _print_formatted(results, output_format)
 
 
+def _validate_export_timeout(value: float) -> float:
+    import math
+
+    if not math.isfinite(value) or value <= 0:
+        raise typer.BadParameter("Timeout must be a finite number greater than zero")
+    return value
+
+
+def _export_channel_reporter(emit):
+    """Report completed Jobs, including callbacks from Group worker threads."""
+    from threading import Lock
+
+    from rich.text import Text
+
+    counts = {"oss": 0, "proxy": 0}
+    lock = Lock()
+
+    def report(job_id, status, channel):
+        with lock:
+            suffix = ""
+            if status == "downloaded" and channel in counts:
+                counts[channel] += 1
+                suffix = f"  channel={channel}"
+            emit(Text(f"{job_id}  {status}{suffix}"))
+
+    return report, counts
+
+
 @job_app.command("export")
 def job_export(
-    job_id: str = typer.Argument(..., help="Job ID"),
+    job_id: str = typer.Argument(..., help="Job ID or comma-separated Job IDs"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Export with a share token"
+    ),
     output: Optional[Path] = typer.Option(None, "--output", "-o", help="Export directory"),
+    workers: int = typer.Option(
+        1, "--workers", "-w", min=1, help="Number of concurrent export workers"
+    ),
+    timeout: float = typer.Option(
+        300,
+        "--timeout",
+        callback=_validate_export_timeout,
+        help="SDK request timeout in seconds, not the total export duration",
+    ),
     logs: bool = typer.Option(False, "--logs", help="Include container logs"),
     events: bool = typer.Option(False, "--events", help="Include events"),
     no_extract_artifacts: bool = typer.Option(
@@ -4889,17 +4965,50 @@ def job_export(
     ),
 ):
     """Export job artifacts to a local directory. Use --logs/--events to include logs and events."""
-    client = get_client()
+    ids = list(dict.fromkeys(value.strip() for value in job_id.split(",")))
+    if not all(ids):
+        raise typer.BadParameter("Job IDs must not be empty", param_hint="job_id")
+    client = _read_client(share_token)
+    if len(ids) > 1:
+        report, channels = _export_channel_reporter(print)
+        dest, summary = export_jobs(
+            client,
+            ids,
+            output,
+            workers=workers,
+            result_callback=report,
+            timeout=timeout,
+            include_logs=logs,
+            include_events=events,
+            extract_artifacts=not no_extract_artifacts,
+        )
+        print(
+            f"Jobs exported: downloaded={summary.downloaded} "
+            f"skipped={summary.skipped} failed={len(summary.failures)}"
+        )
+        print(f"channels: oss={channels['oss']} proxy={channels['proxy']}")
+        print(f"  path: {dest}")
+        for failed_id, error in summary.failures.items():
+            print(f"[red]Failed job {failed_id}:[/] {error}")
+        if summary.failures:
+            raise typer.Exit(code=1)
+        return
+    job_id = ids[0]
+    result = {}
     dest = export_job(
         client,
         job_id,
         output,
+        result_callback=lambda jid, status, channel: result.update(status=status, channel=channel),
+        timeout=timeout,
         include_logs=logs,
         include_events=events,
         extract_artifacts=not no_extract_artifacts,
     )
     print(f"[green]Job exported:[/] {job_id}")
     print(f"  path: {dest}")
+    if result.get("channel") in {"oss", "proxy"} and result.get("status") == "downloaded":
+        print(f"  channel: {result['channel']}")
 
 
 @job_app.command("wait")
@@ -5674,6 +5783,9 @@ def group_list(
 @group_app.command("get")
 def group_get(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -5682,7 +5794,7 @@ def group_get(
 ):
     """Show Group details."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token, group_id if share_token else None)
     result = client.get_group(group_id)
     if output_format == "table":
         _print_detail(result)
@@ -5956,6 +6068,9 @@ def group_update(
     scaffold: Optional[str] = typer.Option(
         None, "--scaffold", "-s", help="Scaffold/agent name (benchmark perspective)"
     ),
+    benchmark: Optional[str] = typer.Option(
+        None, "--benchmark", help="Benchmark name; pass an empty string to clear"
+    ),
     tags: Optional[str] = typer.Option(
         None,
         "--tags",
@@ -6017,6 +6132,7 @@ def group_update(
             dataset,
             model_name,
             scaffold,
+            benchmark,
             tags_list,
         )
     ):
@@ -6031,6 +6147,7 @@ def group_update(
         dataset=dataset,
         model=model_name,
         scaffold=scaffold,
+        **({"benchmark": benchmark} if benchmark is not None else {}),
         **({"tags": tags_list} if tags_list is not None else {}),
     )
     if output_format == "plain":
@@ -6045,6 +6162,7 @@ def group_update(
                 "dataset",
                 "model",
                 "scaffold",
+                "benchmark",
                 "updated_at",
             ],
         )
@@ -6162,6 +6280,9 @@ def group_resume(
 @group_app.command("jobs")
 def group_jobs(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     tag: Optional[list[str]] = typer.Option(
         None, "--tag", help="Filter by tag (repeatable; multiple tags are combined with AND)"
     ),
@@ -6200,17 +6321,36 @@ def group_jobs(
     if cursor and skip > 0:
         raise typer.BadParameter("--cursor cannot be used with --skip greater than 0")
     cursor_request = bool(next_token) or cursor
-    client = get_client()
-    result = client.list_group_jobs(
-        group_id,
-        tag=tag,
-        include_post_process=include_post_process,
-        skip=skip,
-        limit=limit,
-        **({"next_token": next_token} if next_token else {}),
-        **({"pagination": "cursor"} if cursor_request else {}),
-        include_total=not no_total,
-    )
+    if share_token is not None:
+        unsupported = (
+            ("--tag", bool(tag)),
+            ("--include-post-process", include_post_process),
+            ("--next-token", bool(next_token)),
+            ("--cursor", cursor),
+            ("--no-total", no_total),
+        )
+        for option, used in unsupported:
+            if used:
+                _emit_error(f"{option} is not supported with --share-token")
+                raise typer.Exit(1)
+        if skip < 0 or not 1 <= limit <= 500:
+            raise typer.BadParameter(
+                "share pagination requires --skip >= 0 and 1 <= --limit <= 500"
+            )
+        client = _read_client(share_token, group_id if share_token else None)
+        result = client.list_jobs(group_id=group_id, skip=skip, limit=limit)
+    else:
+        client = get_client()
+        result = client.list_group_jobs(
+            group_id,
+            tag=tag,
+            include_post_process=include_post_process,
+            skip=skip,
+            limit=limit,
+            **({"next_token": next_token} if next_token else {}),
+            **({"pagination": "cursor"} if cursor_request else {}),
+            include_total=not no_total,
+        )
     if output_format == "table":
         _print_job_list_plain(result, rich=True)
     elif output_format == "plain":
@@ -6225,6 +6365,9 @@ def group_jobs(
 @group_app.command("stats")
 def group_stats(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -6233,7 +6376,7 @@ def group_stats(
 ):
     """Show Group progress."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token, group_id if share_token else None)
     result = client.get_group_stats(group_id)
     if output_format == "table":
         _print_detail(result)
@@ -6244,6 +6387,9 @@ def group_stats(
 @group_app.command("eval")
 def group_eval(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     summary_only: bool = typer.Option(
         False,
         "--summary-only",
@@ -6257,7 +6403,7 @@ def group_eval(
 ):
     """Show Group aggregated evaluation results."""
     output_format = _normalize_output_format(output_format)
-    client = get_client()
+    client = _read_client(share_token, group_id if share_token else None)
     result = (
         client.get_group_eval_summary(group_id) if summary_only else client.get_group_eval(group_id)
     )
@@ -6370,10 +6516,19 @@ def group_access_list(group_id: str = typer.Argument(..., help="Group ID")):
 @group_app.command("export")
 def group_export(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Export with a share token"
+    ),
     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"
     ),
+    timeout: float = typer.Option(
+        300,
+        "--timeout",
+        callback=_validate_export_timeout,
+        help="SDK request timeout in seconds, not the total export duration",
+    ),
     logs: bool = typer.Option(False, "--logs", help="Include container logs"),
     events: bool = typer.Option(False, "--events", help="Include events"),
     no_extract_artifacts: bool = typer.Option(
@@ -6405,7 +6560,11 @@ def group_export(
         _emit_error("--include-files/--exclude-files cannot be used with --no-extract-artifacts")
         raise typer.Exit(1)
 
-    client = get_client()
+    if share_token is not None and (include_file_selectors or exclude_file_selectors):
+        _emit_error("--include-files/--exclude-files are not supported with --share-token")
+        raise typer.Exit(1)
+
+    client = _read_client(share_token, group_id if share_token else None)
     from rich.progress import BarColumn, Progress, TaskProgressColumn, TextColumn
 
     with Progress(
@@ -6434,12 +6593,15 @@ def group_export(
                 current_stage=current_stage,
             )
 
+        report, channels = _export_channel_reporter(progress.console.print)
         dest, summary = export_group(
             client,
             group_id,
             output,
             progress_callback=_on_progress,
             workers=workers,
+            result_callback=report,
+            timeout=timeout,
             include_logs=logs,
             include_events=events,
             extract_artifacts=not no_extract_artifacts,
@@ -6452,6 +6614,7 @@ def group_export(
         f"  [green]{summary.downloaded}[/] jobs downloaded, "
         f"[yellow]{summary.skipped}[/] jobs skipped (no artifact)"
     )
+    print(f"channels: oss={channels['oss']} proxy={channels['proxy']}")
     if summary.skipped_job_names:
         print(f"  Skipped: {', '.join(summary.skipped_job_names)}")