ap-client 0.2.1.dev0__tar.gz → 0.3.0.dev0__tar.gz

{ap_client-0.2.1.dev0 → ap_client-0.3.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.2.1.dev0
+Version: 0.3.0.dev0
 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]>=0.7.0; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]>=1.0.3; extra == 'dataset'
+Requires-Dist: instance-repo[oss]>=0.7.0; 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.3.0.dev0}/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.
 
@@ -279,48 +293,6 @@ def _secret_ws_params(workspace_id: Optional[str]) -> Optional[dict]:
     return {"workspace_id": workspace_id} if workspace_id else None
 
 
-def _unwrap_data(payload: Any) -> Any:
-    """Unwrap the apiserver ``{code,message,data}`` envelope when present.
-
-    The dataset-domain detail/create/patch endpoints return a bare JSON body,
-    but the same handlers are occasionally wrapped by the generic success
-    envelope. Tolerate both so command code never has to branch: a mapping that
-    carries ``data`` alongside ``code``/``message`` is treated as an envelope,
-    anything else is returned verbatim.
-    """
-    if (
-        isinstance(payload, dict)
-        and "data" in payload
-        and ("code" in payload or "message" in payload)
-    ):
-        return payload["data"]
-    return payload
-
-
-def _split_paged(payload: Any) -> tuple[list[dict], dict]:
-    """Split a ``PagedSuccess`` envelope into ``(records, pagination)``.
-
-    ``PagedSuccess`` is ``{code,message,data:[...],pagination:{total,page,page_size}}``.
-    A bare list (or a null ``data``) yields an empty pagination dict so callers
-    can render results without probing the response shape.
-    """
-    if isinstance(payload, list):
-        return [item for item in payload if isinstance(item, dict)], {}
-    if not isinstance(payload, dict):
-        return [], {}
-    records = payload.get("data")
-    pagination = payload.get("pagination")
-    return (
-        [item for item in (records or []) if isinstance(item, dict)],
-        pagination if isinstance(pagination, dict) else {},
-    )
-
-
-def _as_record_list(payload: Any) -> list[dict]:
-    """Coerce a list-returning endpoint to ``list[dict]``, envelope or not."""
-    return _split_paged(payload)[0]
-
-
 class APIClient:
     """Agent Platform API client."""
 
@@ -872,211 +844,6 @@ class APIClient:
             "instance_ids": all_instance_ids,
         }
 
-    # ==================== Dataset series (apiserver dataset domain) ====================
-    #
-    # 这一节对接 Go apiserver 的 dataset 领域(/apis/v1/datasets/...),与上面
-    # ossdata 目录的 /api/datasets 路由完全无关。方法名统一带 `_series`,
-    # 以免和 `ap job create --dataset` 依赖的 list_all_datasets /
-    # list_dataset_versions / list_all_dataset_instances 混淆。
-    #
-    # 列表端点返回 PagedSuccess envelope:
-    #   {"code":0,"message":"ok","data":[...],"pagination":{"total","page","page_size"}}
-    # 详情/创建/更新端点返回裸 JSON body。
-
-    _DATASET_SERIES_BASE = "/apis/v1/datasets/series"
-    _DATASET_VERSIONS_BASE = "/apis/v1/datasets/versions"
-    _DATASET_INSTANCES_BASE = "/apis/v1/datasets/instances"
-
-    def list_dataset_series_page(
-        self,
-        *,
-        q: Optional[str] = None,
-        keyword: Optional[str] = None,
-        visibility: Optional[str] = None,
-        benchmark_id: Optional[str] = None,
-        include_deprecated: bool = False,
-        environment: Optional[str] = None,
-        page: int = 1,
-        page_size: int = 20,
-    ) -> dict:
-        """一页 dataset series(原始 PagedSuccess envelope)。
-
-        服务端没有 owner/mine/l1 过滤参数,调用方需要时只能在客户端做页内过滤。
-        """
-        params: dict = {"page": page, "page_size": page_size}
-        if q:
-            params["q"] = q
-        if keyword:
-            params["keyword"] = keyword
-        if visibility:
-            params["visibility"] = visibility
-        if benchmark_id:
-            params["benchmark_id"] = benchmark_id
-        if include_deprecated:
-            params["include_deprecated"] = "true"
-        if environment:
-            params["environment"] = environment
-        return self._get(self._DATASET_SERIES_BASE, params=params)
-
-    def list_dataset_series(self, **kw) -> tuple[list[dict], dict]:
-        """列出 dataset series,返回 ``(records, pagination)``。"""
-        return _split_paged(self.list_dataset_series_page(**kw))
-
-    def get_dataset_series(self, dataset_name: str, *, environment: Optional[str] = None) -> dict:
-        """按名字取 dataset series 详情(含 dataset_id / claimable / stats)。"""
-        params: dict = {"dataset_name": dataset_name}
-        if environment:
-            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(
-            self._request(
-                "PATCH",
-                f"{self._DATASET_SERIES_BASE}/detail",
-                params={"dataset_name": dataset_name},
-                json_body=body,
-            )
-        )
-
-    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"))
-
-    # ---- dataset versions ----
-
-    def list_dataset_series_versions(
-        self,
-        dataset_name: str,
-        *,
-        status: Optional[str] = None,
-        page: int = 1,
-        page_size: int = 20,
-        environment: Optional[str] = None,
-    ) -> tuple[list[dict], dict]:
-        """列出某 dataset 的版本,返回 ``(records, pagination)``。列表项不含 splits 数组。"""
-        params: dict = {"dataset_name": dataset_name, "page": page, "page_size": page_size}
-        if status:
-            params["status"] = status
-        if environment:
-            params["environment"] = environment
-        return _split_paged(self._get(self._DATASET_VERSIONS_BASE, params=params))
-
-    def get_dataset_series_version(
-        self,
-        dataset_name: str,
-        version: str,
-        *,
-        environment: Optional[str] = None,
-    ) -> dict:
-        """取单个版本详情(含 run_type / splits[] / manifest / published_at)。
-
-        ``version=""`` 表示 split_first 的**无版本空间**,原样下发空串——绝不隐式取 latest。
-        """
-        params: dict = {"dataset_name": dataset_name, "version": version}
-        if environment:
-            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(
-        self,
-        dataset_name: str,
-        *,
-        version: Optional[str] = None,
-        split: Optional[str] = None,
-        instance_id: Optional[str] = None,
-        page: int = 1,
-        page_size: int = 50,
-        environment: Optional[str] = None,
-    ) -> tuple[list[dict], dict]:
-        """列出 instance 元数据,返回 ``(records, pagination)``。
-
-        ``version=""`` / ``split=""`` 原样下发(无版本空间语义),``None`` 才省略该参数。
-        """
-        params: dict = {"dataset_name": dataset_name, "page": page, "page_size": page_size}
-        if version is not None:
-            params["version"] = version
-        if split is not None:
-            params["split"] = split
-        if instance_id:
-            params["instance_id"] = instance_id
-        if environment:
-            params["environment"] = environment
-        return _split_paged(self._get(self._DATASET_INSTANCES_BASE, params=params))
-
-    def get_dataset_series_instance(
-        self,
-        dataset_name: str,
-        version: str,
-        split: str,
-        instance_id: str,
-        *,
-        environment: Optional[str] = None,
-    ) -> dict:
-        """取单个 instance 的元数据详情。``version=""`` 表示无版本空间。"""
-        params: dict = {
-            "dataset_name": dataset_name,
-            "version": version,
-            "split": split,
-            "instance_id": instance_id,
-        }
-        if environment:
-            params["environment"] = environment
-        return _unwrap_data(self._get(f"{self._DATASET_INSTANCES_BASE}/detail", params=params))
-
-    # ---- permissions ----
-
-    def get_my_resource_permissions(self, resource_type: str, resource_id: str) -> list[str]:
-        """当前用户在某资源上的 action 列表(``{"actions":[...]}``)。"""
-        payload = self._get(
-            "/apis/v1/me/resource-permissions",
-            params={"resource_type": resource_type, "resource_id": resource_id},
-        )
-        payload = _unwrap_data(payload)
-        if isinstance(payload, dict):
-            actions = payload.get("actions")
-            if isinstance(actions, list):
-                return [str(action) for action in actions]
-        return []
-
     # ==================== Meta operations ====================
 
     def list_meta_models(self) -> dict:
@@ -1224,6 +991,7 @@ class APIClient:
         runner: Optional[str] = None,
         runner_options: Optional[dict] = None,
         idempotency_key: Optional[str] = None,
+        max_failure_retries: int = 0,
         # ─── Scheduling hints ─────────────────────────────────────────
         priority: Optional[str] = None,
         priority_weight: Optional[int] = None,
@@ -1276,6 +1044,7 @@ class APIClient:
             runner=runner,
             runner_options=runner_options,
             idempotency_key=idempotency_key,
+            max_failure_retries=max_failure_retries,
             priority=priority,
             priority_weight=priority_weight,
             resource_mode=resource_mode,
@@ -1326,6 +1095,7 @@ class APIClient:
         runner: Optional[str] = None,
         runner_options: Optional[dict] = None,
         idempotency_key: Optional[str] = None,
+        max_failure_retries: int = 0,
         # ─── Scheduling hints ─────────────────────────────────────────
         priority: Optional[str] = None,
         priority_weight: Optional[int] = None,
@@ -1412,6 +1182,8 @@ class APIClient:
             body["runner_options"] = runner_options
         if idempotency_key is not None:
             body["idempotency_key"] = idempotency_key
+        if max_failure_retries:
+            body["max_failure_retries"] = max_failure_retries
 
         # Scheduling hints
         if priority is not None:
@@ -1514,6 +1286,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 +1346,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 +1545,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 +1571,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 +2058,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 +2091,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
+            if mode is None:
+                mode = "cursor" if has_token_field else "offset"
 
-            skip += len(page_artifacts)
-
-        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."""