ap-client 0.2.1.dev0__tar.gz → 0.2.2.dev1__tar.gz

{ap_client-0.2.1.dev0 → ap_client-0.2.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.2.1.dev0
+Version: 0.2.2.dev1
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
@@ -9,9 +9,9 @@ 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.0.3; extra == 'all'
+Requires-Dist: instance-repo[oss]>=1.0.9; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]>=1.0.3; extra == 'dataset'
+Requires-Dist: instance-repo[oss]>=1.0.9; 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.2.1.dev0 → ap_client-0.2.2.dev1}/ap_client/api.py

@@ -268,6 +268,20 @@ class APIError(Exception):
         return f"API Error {self.status_code}: {self.detail} (request_id={self.request_id})"
 
 
+class PaginationProtocolError(RuntimeError):
+    """The server stopped honoring a pagination protocol already in use."""
+
+
+def _ensure_next_token_honored(response: dict, *, next_token: Optional[str], endpoint: str) -> None:
+    # An old server ignores the unknown next_token param and answers with its
+    # default first page, so a `response.get("next_token")` loop would silently
+    # repeat that page and drop the rest of the collection.
+    if next_token and "next_token" not in response:
+        raise PaginationProtocolError(
+            f"server stopped returning next_token while paginating {endpoint}; upgrade the server"
+        )
+
+
 def _secret_ws_params(workspace_id: Optional[str]) -> Optional[dict]:
     """Build the ``?workspace_id=`` query for name-addressed secret endpoints.
 
@@ -736,8 +750,35 @@ class APIClient:
         return self._get(f"/templates/{quote(name)}", params=params)
 
     def list_benchmarks(self) -> list:
-        """List all active benchmarks from the local benchmark registry."""
-        return self._get("/benchmarks")
+        """List all benchmarks from the central registry, preserving legacy IDs."""
+        benchmarks = []
+        page = 1
+        page_size = 200
+        # 与 CLI dataset list 的自动翻页同口径:100 页上限,防分页异常导致死循环。
+        max_pages = 100
+        while page <= max_pages:
+            payload = self._get(
+                "/apis/v1/benchmarks", params={"page": page, "page_size": page_size}
+            )
+            records, pagination = _split_paged(payload)
+            for record in records:
+                item = dict(record)
+                if "source_id" in item:
+                    item.setdefault("id", item["source_id"])
+                benchmarks.append(item)
+            if not records or not pagination:
+                break
+            try:
+                total = int(pagination.get("total"))
+            except (TypeError, ValueError):
+                total = None
+            if total is not None:
+                if len(benchmarks) >= total:
+                    break
+            elif len(records) < page_size:
+                break
+            page += 1
+        return benchmarks
 
     def get_benchmark(self, name: str) -> dict:
         """Get a single benchmark by exact name."""
@@ -929,10 +970,6 @@ class APIClient:
             params["environment"] = environment
         return _unwrap_data(self._get(f"{self._DATASET_SERIES_BASE}/detail", params=params))
 
-    def create_dataset_series(self, body: dict) -> dict:
-        """创建 dataset series。owner 由服务端按调用者身份填充。"""
-        return _unwrap_data(self._post(self._DATASET_SERIES_BASE, body))
-
     def update_dataset_series(self, dataset_name: str, body: dict) -> dict:
         """PATCH dataset series 元数据(visibility/status 需要 dataset-admin)。"""
         return _unwrap_data(
@@ -944,12 +981,6 @@ class APIClient:
             )
         )
 
-    def claim_dataset_series(self, dataset_id: str, body: dict) -> dict:
-        """认领 dataset series(``workspace_id`` 服务端必填);成功后调用方成为 dataset admin。"""
-        return _unwrap_data(
-            self._post(f"{self._DATASET_SERIES_BASE}/{quote(dataset_id, safe='')}/claim", body)
-        )
-
     def list_claim_workspaces(self) -> list[dict]:
         """列出当前用户可用于认领的 workspace。"""
         return _as_record_list(self._get("/apis/v1/datasets/claim-workspaces"))
@@ -989,31 +1020,6 @@ class APIClient:
             params["environment"] = environment
         return _unwrap_data(self._get(f"{self._DATASET_VERSIONS_BASE}/detail", params=params))
 
-    def create_dataset_series_version(self, dataset_name: str, body: dict) -> dict:
-        """创建版本(``version``/``storage_type``/``storage_path``/``splits``/``status``)。"""
-        return _unwrap_data(
-            self._request(
-                "POST",
-                self._DATASET_VERSIONS_BASE,
-                params={"dataset_name": dataset_name},
-                json_body=body,
-            )
-        )
-
-    def update_dataset_series_version(self, dataset_name: str, version: str, body: dict) -> dict:
-        """PATCH 版本(``status``/``splits``/``manifest``/``run_type``/``split_run_types``)。
-
-        服务端要求 ``splits`` 与 ``split_run_types`` 互斥,调用方需分两次 PATCH。
-        """
-        return _unwrap_data(
-            self._request(
-                "PATCH",
-                f"{self._DATASET_VERSIONS_BASE}/detail",
-                params={"dataset_name": dataset_name, "version": version},
-                json_body=body,
-            )
-        )
-
     # ---- dataset instances (metadata only) ----
 
     def list_dataset_series_instances(
@@ -1062,6 +1068,19 @@ class APIClient:
             params["environment"] = environment
         return _unwrap_data(self._get(f"{self._DATASET_INSTANCES_BASE}/detail", params=params))
 
+    def get_dataset_series_split(self, dataset_name: str, version: str, split: str) -> dict:
+        """Read the selected split's lifecycle without a version-level aggregate."""
+        return _unwrap_data(
+            self._get(
+                "/apis/v1/datasets/splits/detail",
+                params={"dataset_name": dataset_name, "version": version, "split": split},
+            )
+        )
+
+    def get_dataset_split_release(self, workflow_id: str) -> dict:
+        """Read a release workflow, including approval and per-step outcomes."""
+        return _unwrap_data(self._get(f"/apis/v1/workflows/{quote(workflow_id, safe='')}"))
+
     # ---- permissions ----
 
     def get_my_resource_permissions(self, resource_type: str, resource_id: str) -> list[str]:
@@ -1514,6 +1533,9 @@ class APIClient:
         meta_job_type: Optional[str] = None,
         upstream_platform: Optional[str] = None,
         upstream_job_id: Optional[str] = None,
+        next_token: Optional[str] = None,
+        pagination: Optional[str] = None,
+        include_total: bool = True,
     ) -> dict:
         """List jobs."""
         params = {"skip": skip, "limit": limit}
@@ -1571,7 +1593,15 @@ class APIClient:
             params["created_at_sort"] = created_at_sort
         if finished_at_sort is not None:
             params["finished_at_sort"] = finished_at_sort
-        return self._get("/jobs", params=params)
+        if next_token:
+            params["next_token"] = next_token
+        if pagination:
+            params["pagination"] = pagination
+        if not include_total:
+            params["include_total"] = False
+        response = self._get("/jobs", params=params)
+        _ensure_next_token_honored(response, next_token=next_token, endpoint="/jobs")
+        return response
 
     # ==================== Group operations ====================
 
@@ -1762,6 +1792,9 @@ class APIClient:
         meta_job_type: Optional[str] = None,
         upstream_platform: Optional[str] = None,
         upstream_job_id: Optional[str] = None,
+        next_token: Optional[str] = None,
+        pagination: Optional[str] = None,
+        include_total: bool = True,
     ) -> dict:
         """List jobs in a group."""
         params: dict = {"skip": skip, "limit": limit}
@@ -1785,7 +1818,16 @@ class APIClient:
             params["upstream_job_id"] = upstream_job_id
         if include_post_process:
             params["include_post_process"] = True
-        return self._get(f"/groups/{quote(group_id)}/jobs", params=params)
+        if next_token:
+            params["next_token"] = next_token
+        if pagination:
+            params["pagination"] = pagination
+        if not include_total:
+            params["include_total"] = False
+        endpoint = f"/groups/{quote(group_id)}/jobs"
+        response = self._get(endpoint, params=params)
+        _ensure_next_token_honored(response, next_token=next_token, endpoint=endpoint)
+        return response
 
     def get_group_post_process_job_id(
         self, group_id: str, timeout: TimeoutType = None
@@ -2263,19 +2305,30 @@ class APIClient:
         skip: int = 0,
         limit: int = _GROUP_ARTIFACTS_PAGE_SIZE,
         include_post_process: bool = False,
+        next_token: Optional[str] = None,
+        pagination: Optional[str] = None,
+        include_total: bool = True,
     ) -> dict:
         """Get one page of artifact download links for a group."""
         params: dict[str, object] = {"skip": skip, "limit": limit}
         if include_post_process:
             params["include_post_process"] = True
-        return self._get(
-            f"/groups/{quote(group_id)}/artifacts",
-            params=params,
-        )
+        if next_token:
+            params["next_token"] = next_token
+        if pagination:
+            params["pagination"] = pagination
+        if not include_total:
+            params["include_total"] = False
+        endpoint = f"/groups/{quote(group_id)}/artifacts"
+        response = self._get(endpoint, params=params)
+        _ensure_next_token_honored(response, next_token=next_token, endpoint=endpoint)
+        return response
 
     def get_group_artifacts(self, group_id: str, include_post_process: bool = False) -> dict:
         """Get artifact download links for a group."""
+        next_token: str | None = None
         skip = 0
+        mode: str | None = None
         artifacts: list[dict] = []
         last_page: dict | None = None
 
@@ -2285,25 +2338,41 @@ class APIClient:
                 skip=skip,
                 limit=_GROUP_ARTIFACTS_PAGE_SIZE,
                 include_post_process=include_post_process,
+                next_token=next_token,
+                pagination="cursor" if mode in {None, "cursor"} else None,
+                include_total=False,
             )
             last_page = page
             page_artifacts = page.get("artifacts") or []
             artifacts.extend(page_artifacts)
+            has_token_field = "next_token" in page
 
-            total = page.get("total")
-            if total is not None and len(artifacts) >= total:
-                break
-            if len(page_artifacts) < _GROUP_ARTIFACTS_PAGE_SIZE:
-                break
-
-            skip += len(page_artifacts)
+            if mode is None:
+                mode = "cursor" if has_token_field else "offset"
 
-        return {
-            **last_page,
-            "skip": 0,
-            "limit": len(artifacts),
-            "artifacts": artifacts,
-        }
+            if mode == "cursor":
+                next_token = page.get("next_token")
+                if not next_token:
+                    break
+            else:
+                skip += len(page_artifacts)
+                total = page.get("total")
+                if not page_artifacts or len(page_artifacts) < _GROUP_ARTIFACTS_PAGE_SIZE:
+                    break
+                if total is not None and skip >= total:
+                    break
+
+        result = dict(last_page or {})
+        result.pop("next_token", None)
+        result.update(
+            {
+                "total": len(artifacts),
+                "skip": 0,
+                "limit": len(artifacts),
+                "artifacts": artifacts,
+            }
+        )
+        return result
 
     def get_job_artifacts(self, job_ids: list) -> list:
         """Get artifact download links for one or more jobs."""

{ap_client-0.2.1.dev0 → ap_client-0.2.2.dev1}/ap_client/cli.py

@@ -16,6 +16,7 @@ from ap_client import __version__, get_client, get_config, tbb
 from ap_client.api import (
     _OTHERS_MODEL,
     APIError,
+    PaginationProtocolError,
     _merge_meta_tags,
     set_cluster_override,
     set_verbose_override,
@@ -928,10 +929,7 @@ def _print_params_plain(params: Any, masked_params: list) -> None:
     rows: list[tuple[str, Any]] = []
     for key, value in params.items():
         display_value = _format_plain_value(value)
-        # 直接信任 masked_params 路径：服务端掩码形态已扩展为保留首尾（如
-        # sk-***890 / ****），不能再按值严格等于 "***" 判断，否则形态变化后
-        # (masked) 标识静默丢失
-        if str(key) in masked_paths:
+        if str(key) in masked_paths and value == "***":
             display_value = f"{display_value} (masked)"
         rows.append((str(key), display_value))
     _print_key_values(rows, skip_empty=False)
@@ -2636,6 +2634,21 @@ def job_list(
     desc: bool = typer.Option(False, "--desc", help="Sort descending; requires --sort"),
     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"),
+    next_token: Optional[str] = typer.Option(
+        None,
+        "--next-token",
+        help="Opaque token returned by the previous exact-group job list page; requires --group-id",
+    ),
+    cursor: bool = typer.Option(
+        False,
+        "--cursor",
+        help="Opt this page into next-token pagination; requires --group-id",
+    ),
+    no_total: bool = typer.Option(
+        False,
+        "--no-total",
+        help="Skip the server-side count; total becomes null in json/yaml output",
+    ),
     columns: Optional[str] = typer.Option(
         None,
         "--columns",
@@ -2661,7 +2674,16 @@ def job_list(
         raise typer.BadParameter("--tag-pattern cannot be used with --tag")
     if normalized_tag_logic != "and" and not tag:
         raise typer.BadParameter("--tag-logic requires --tag")
+    if next_token and not group_id:
+        raise typer.BadParameter("--next-token requires --group-id")
+    if cursor and not group_id:
+        raise typer.BadParameter("--cursor requires --group-id")
+    if next_token and skip > 0:
+        raise typer.BadParameter("--next-token cannot be used with --skip greater than 0")
+    if cursor and skip > 0:
+        raise typer.BadParameter("--cursor cannot be used with --skip greater than 0")
     sort_kwargs = _job_list_sort_kwargs(sort, asc=asc, desc=desc)
+    cursor_request = bool(next_token) or cursor
     client = get_client()
     result = client.list_jobs(
         template=template,
@@ -2685,6 +2707,9 @@ def job_list(
         **({"meta_model": meta_model} if meta_model is not None else {}),
         **({"meta_job_type": meta_job_type} if meta_job_type is not None else {}),
         **sort_kwargs,
+        **({"next_token": next_token} if next_token else {}),
+        **({"pagination": "cursor"} if cursor_request else {}),
+        include_total=not no_total,
         skip=skip,
         limit=limit,
     )
@@ -2694,6 +2719,9 @@ def job_list(
         _print_job_list_plain(result, columns=selected_columns)
     else:
         _print_formatted(result, output_format)
+    next_token = result.get("next_token")
+    if output_format in {"table", "plain"} and next_token:
+        typer.echo(f"Next token: {next_token}", err=True)
 
 
 @job_app.command("create")
@@ -4751,7 +4779,7 @@ def benchmark_list(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List benchmarks from the local benchmark registry."""
+    """List benchmarks from the central benchmark registry."""
     output_format = _normalize_output_format(output_format, keep_table=True)
     client = get_client()
     result = client.list_benchmarks()
@@ -5746,6 +5774,21 @@ def group_jobs(
     ),
     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"),
+    next_token: Optional[str] = typer.Option(
+        None,
+        "--next-token",
+        help="Opaque token returned by the previous Group jobs page",
+    ),
+    cursor: bool = typer.Option(
+        False,
+        "--cursor",
+        help="Opt this page into next-token pagination",
+    ),
+    no_total: bool = typer.Option(
+        False,
+        "--no-total",
+        help="Skip the server-side count; total becomes null in json/yaml output",
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -5754,6 +5797,11 @@ def group_jobs(
 ):
     """List jobs in a Group."""
     output_format = _normalize_output_format(output_format, keep_table=True)
+    if next_token and skip > 0:
+        raise typer.BadParameter("--next-token cannot be used with --skip greater than 0")
+    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,
@@ -5761,6 +5809,9 @@ def group_jobs(
         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)
@@ -5768,6 +5819,9 @@ def group_jobs(
         _print_job_list_plain(result)
     else:
         _print_formatted(result, output_format)
+    following_token = result.get("next_token")
+    if output_format in {"table", "plain"} and following_token:
+        typer.echo(f"Next token: {following_token}", err=True)
 
 
 @group_app.command("stats")
@@ -6038,7 +6092,7 @@ def main() -> None:
     except APIError as exc:
         typer.echo(_format_api_error(exc), err=True)
         raise SystemExit(1) from None
-    except ConfigurationError as exc:
+    except (ConfigurationError, PaginationProtocolError) as exc:
         typer.echo(f"error: {exc}", err=True)
         raise SystemExit(1) from None