ap-client 0.5.1.dev4__tar.gz → 0.6.0.dev0__tar.gz

{ap_client-0.5.1.dev4 → ap_client-0.6.0.dev0}/PKG-INFO

@@ -1,17 +1,18 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.5.1.dev4
+Version: 0.6.0.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.2; 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.2; 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.dev4 → ap_client-0.6.0.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:

{ap_client-0.5.1.dev4 → ap_client-0.6.0.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 (
@@ -3564,8 +3564,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))
@@ -4876,10 +4876,47 @@ 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"),
     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 +4926,50 @@ def job_export(
     ),
 ):
     """Export job artifacts to a local directory. Use --logs/--events to include logs and events."""
+    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 = get_client()
+    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")
@@ -6374,6 +6444,12 @@ def group_export(
     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(
@@ -6434,12 +6510,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 +6531,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)}")
 

{ap_client-0.5.1.dev4 → ap_client-0.6.0.dev0}/ap_client/dataset_commands.py

@@ -15,6 +15,9 @@ from typing import TYPE_CHECKING, Any, List, Optional
 
 import typer
 
+from .repo_read_guard import STORAGE_SIDES as _STORAGE_SIDES
+from .repo_read_guard import oss_fallback_kwargs
+
 if TYPE_CHECKING:  # pragma: no cover - 仅用于类型标注,运行时不 import
     from datetime import datetime
 
@@ -316,13 +319,8 @@ def _env_kwargs(environment: str) -> dict:
     return {"environment": environment} if environment and environment != "auto" else {}
 
 
-#: 集群绑定存储 → 环境侧(dev 三个变体都是 pre 侧;元数据层它们归并到同一个 pre 集合)。
-_STORAGE_SIDES = {
-    "dev": "pre",
-    "internal-dev": "pre",
-    "external-dev": "pre",
-    "prod": "online",
-}
+def _read_env_kwargs(repo: Any, client: Any, method: str, environment: str) -> dict:
+    return {**_env_kwargs(environment), **oss_fallback_kwargs(repo, client, method, environment)}
 
 
 def _check_storage_side(repo: Any, environment: str) -> None:
@@ -419,7 +417,9 @@ def _model_dict(record: Any) -> dict:
         key: value
         for key, value in payload.items()
         if value is not None
-        and (key == "registered" or not (value is False or value == "" or value == [] or value == {}))
+        and (
+            key == "registered" or not (value is False or value == "" or value == [] or value == {})
+        )
     }
 
 
@@ -609,7 +609,7 @@ def _fetch_version(
         detail = repo.versions.get(
             dataset,
             version,
-            **_env_kwargs(env),
+            **_read_env_kwargs(repo, repo.versions, "get", env),
             **({"metadata_model": metadata_model} if metadata_model else {}),
         )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
@@ -646,19 +646,30 @@ def _unversioned_splits(
     env = _environment(environment)
     repo = _dataset_repo()
     try:
-        result = repo.splits.list(
-            dataset,
-            # CLI 语义:省略 --version 就是无版本空间。SDK 的缺省是 all(跨全部版本),不一样。
-            version_scope="unversioned",
-            page_size=_SPLIT_PAGE_SIZE,
-            **_env_kwargs(env),
-        )
+        records: list[dict] = []
+        page = 1
+        while True:
+            result = repo.splits.list(
+                dataset,
+                version_scope="unversioned",
+                page_size=_SPLIT_PAGE_SIZE,
+                **({"page": page} if page > 1 else {}),
+                **_read_env_kwargs(repo, repo.splits, "list", env),
+            )
+            items = getattr(result, "items", None) or []
+            for item in items:
+                record = _model_dict(item)
+                if not _version_value(record.get("version")):
+                    records.append(record)
+            if not items or getattr(result, "has_more", False) is not True:
+                break
+            page += 1
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         raise _fail(
             f"dataset {dataset} (no version space): {stage} failed: {_reason(exc)}",
             f"Check the dataset name and permission: ap dataset get {dataset}",
         ) from exc
-    return [_model_dict(item) for item in (getattr(result, "items", None) or [])]
+    return records
 
 
 def _unversioned_split(
@@ -670,13 +681,14 @@ def _unversioned_split(
     env = _environment(environment)
     repo = _dataset_repo()
     try:
-        record = repo.splits.get(dataset, split, **_env_kwargs(env))
+        record = repo.splits.get(dataset, split, **_read_env_kwargs(repo, repo.splits, "get", env))
     except Exception as exc:  # noqa: BLE001
         raise _fail(
             f"dataset {dataset} (no version space) split {split}: query failed: {_reason(exc)}",
             f"Check the dataset name and permission: ap dataset get {dataset}",
         ) from exc
-    return _model_dict(record) if record is not None else None
+    detail = _model_dict(record) if record is not None else None
+    return detail if detail is not None and not _version_value(detail.get("version")) else None
 
 
 def _split_records(detail: dict) -> list[dict]:
@@ -1120,7 +1132,11 @@ def _print_dataset_environments(repo: "Repo", dataset: str, detail: dict) -> Non
     rows: list[dict] = []
     for env in envs:
         try:
-            env_detail = _model_dict(repo.datasets.get_detail(dataset, environment=env))
+            env_detail = _model_dict(
+                repo.datasets.get_detail(
+                    dataset, **_read_env_kwargs(repo, repo.datasets, "get_detail", env)
+                )
+            )
         except Exception:  # noqa: BLE001 - 摘要尽力而为
             rows.append({"environment": env, "versions": "?", "splits": "?", "latest_version": "?"})
             continue
@@ -1155,7 +1171,9 @@ def dataset_get(
     env = _environment(environment)
     repo = _dataset_repo()
     try:
-        detail = repo.datasets.get_detail(dataset, **_env_kwargs(env))
+        detail = repo.datasets.get_detail(
+            dataset, **_read_env_kwargs(repo, repo.datasets, "get_detail", env)
+        )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         if _business_code(exc) not in (92001, 94021):
             raise _fail(
@@ -1164,13 +1182,13 @@ def dataset_get(
             ) from exc
         detail = None
     if detail is None:
-        l1, _, l2 = dataset.partition("/")
         rendered = {
             "dataset_name": dataset,
-            "dataset_l1": l1,
-            "dataset_l2": l2,
             "registered": False,
         }
+        parts = dataset.split("/")
+        if len(parts) == 2 and all(parts):
+            rendered.update(dataset_l1=parts[0], dataset_l2=parts[1])
     else:
         rendered = _registered_dict(detail)
     _emit_detail(rendered, output_format, order=_DATASET_DETAIL_ORDER, always=("status",))
@@ -1294,7 +1312,11 @@ def dataset_claim(
     env = _environment(environment)
     repo = _dataset_repo()
     try:
-        detail = _model_dict(repo.datasets.get_detail(dataset, **_env_kwargs(env)))
+        detail = _model_dict(
+            repo.datasets.get_detail(
+                dataset, **_read_env_kwargs(repo, repo.datasets, "get_detail", env)
+            )
+        )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         raise _fail(
             f"dataset {dataset}: pre-claim query failed: {_reason(exc)}",
@@ -1372,7 +1394,11 @@ def dataset_claim(
             owner = str(detail.get("owner") or "").strip()
             if not owner:
                 try:
-                    fresh = _model_dict(repo.datasets.get_detail(dataset, **_env_kwargs(env)))
+                    fresh = _model_dict(
+                        repo.datasets.get_detail(
+                            dataset, **_read_env_kwargs(repo, repo.datasets, "get_detail", env)
+                        )
+                    )
                     owner = str(fresh.get("owner") or "").strip()
                 except Exception:  # noqa: BLE001 - 取不到 owner 不影响幂等退出
                     owner = ""
@@ -1658,7 +1684,7 @@ def dataset_version_list(
             page=page,
             page_size=page_size,
             **({"metadata_model": model} if model else {}),
-            **_env_kwargs(env),
+            **_read_env_kwargs(repo, repo.versions, "list_paged", env),
         )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         raise _fail(

{ap_client-0.5.1.dev4 → ap_client-0.6.0.dev0}/ap_client/dataset_register.py

@@ -42,7 +42,9 @@ def _confirm(dataset: str, *, yes: bool) -> None:
             "Add --yes (-y) to confirm the registration",
             exit_code=2,
         )
-    if not typer.confirm(f"Register the previewed data for dataset {dataset}?", default=False, err=True):
+    if not typer.confirm(
+        f"Register the previewed data for dataset {dataset}?", default=False, err=True
+    ):
         raise datasets._fail(
             "Registration canceled; nothing was written remotely",
             "Rerun the command and confirm, or add --yes (-y)",
@@ -52,6 +54,8 @@ def _confirm(dataset: str, *, yes: bool) -> None:
 def _claim_without_workspace(
     repo: Any, dataset_id: str, current_user: str, benchmark_id: str
 ) -> dict:
+    # API allows omitted workspace (ClaimAllowsOmittedWorkspace). SDK 1.3.2's
+    # claim() still rejects it locally, so keep the authenticated transport shim.
     body = {"owner": current_user}
     if benchmark_id:
         body["benchmark_id"] = benchmark_id
@@ -128,6 +132,22 @@ def _ensure_current_user_owns(
                 f"Check the name and benchmark, then inspect: ap dataset get {dataset}",
             ) from create_exc
         created_owner = str(created.get("owner") or "").strip()
+        if not created_owner:
+            try:
+                refreshed = datasets._model_dict(
+                    repo.datasets.get_detail(dataset, **datasets._env_kwargs(environment))
+                )
+                created_owner = str(refreshed.get("owner") or "").strip()
+            except Exception as exc:  # noqa: BLE001 - creation may already have succeeded
+                raise datasets._fail(
+                    f"Dataset {dataset} was created, but ownership could not be verified: {_reason(exc)}",
+                    f"Inspect ownership before registering again: ap dataset get {dataset}",
+                ) from exc
+            if not created_owner:
+                raise datasets._fail(
+                    f"Dataset {dataset} was created, but the server returned no owner",
+                    f"Verify ownership before registering again: ap dataset get {dataset}",
+                )
         if created_owner != current_user:
             shown_owner = created_owner or "<unknown>"
             raise datasets._fail(
@@ -173,12 +193,16 @@ def dataset_register(
     version: Optional[str] = typer.Option(None, "--version", help=datasets._VERSION_HELP),
     splits: Optional[List[str]] = typer.Option(None, "--split", help="Split to scan; repeatable"),
     unversioned: bool = typer.Option(
-        False, "--unversioned", help="Scan the version-less space; mutually exclusive with --version"
+        False,
+        "--unversioned",
+        help="Scan the version-less space; mutually exclusive with --version",
     ),
     environment: Optional[str] = typer.Option(
         None, "--environment", help=datasets._ENVIRONMENT_HELP
     ),
-    dry_run: bool = typer.Option(False, "--dry-run", help="Preview without submitting registration"),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Preview without submitting registration"
+    ),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip the registration confirmation"),
     wait: bool = typer.Option(False, "--wait", help="Wait for the ingest task to finish"),
     timeout: float = typer.Option(1800.0, "--timeout", help="Local wait timeout in seconds"),
@@ -194,6 +218,13 @@ def dataset_register(
     from .irepo_sdk import _reason
 
     fmt = datasets._fmt(output_format)
+    dataset = dataset.strip()
+    if not dataset:
+        raise datasets._fail(
+            "Failed to register dataset: name is empty",
+            "Pass a non-empty dataset name, e.g. ap dataset register alibaba/a",
+            exit_code=2,
+        )
     selected_version = str(version or "").strip() or None
     selected_splits = [str(value).strip() for value in (splits or []) if str(value).strip()]
     if selected_version and unversioned:
@@ -258,9 +289,25 @@ def dataset_register(
     preview_payload = _payload("preview", dataset, preview)
     if dry_run:
         datasets._emit_detail(preview_payload, fmt)
+    else:
+        _emit_preview_stderr(preview_payload, fmt)
+    preview_status = str(preview.get("status") or "").strip().lower()
+    if preview_status in _TERMINAL_FAILURE | _TERMINAL_CANCELED:
+        raise datasets._fail(
+            f"Registration preview {preview_status}: "
+            f"{preview.get('error_message') or preview.get('error_msg') or 'no details returned'}",
+            "Fix the preview error before submitting registration",
+        )
+    if dry_run:
         return
-
-    _emit_preview_stderr(preview_payload, fmt)
+    counts = preview.get("counts")
+    if preview.get("instance_count") == 0 or (
+        isinstance(counts, dict) and counts.get("instances") == 0
+    ):
+        raise datasets._fail(
+            "Registration preview found no instances",
+            "Check the dataset scope and storage layout before submitting registration",
+        )
     _confirm(dataset, yes=yes)
     if owner == "@me":
         _ensure_current_user_owns(repo, dataset, env, benchmark)
@@ -305,7 +352,7 @@ def dataset_register(
     if outcome == "failed":
         raise datasets._fail(
             f"Registration task {ingest_id or '<unknown>'} failed: "
-            f"{result.get('error_message') or ''}",
+            f"{result.get('error_message') or result.get('error_msg') or 'no details returned'}",
             "Fix the reported data or metadata issue, then run the same registration command again",
         )
     if outcome == "canceled":