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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.2.0.dev0
+Version: 0.2.1.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]>=0.7.0; extra == 'all'
+Requires-Dist: instance-repo[oss]>=1.0.3; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]>=0.7.0; extra == 'dataset'
+Requires-Dist: instance-repo[oss]>=1.0.3; 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.0.dev0 → ap_client-0.2.1.dev0}/ap_client/api.py

@@ -279,6 +279,48 @@ 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."""
 
@@ -830,6 +872,211 @@ 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:

{ap_client-0.2.0.dev0 → ap_client-0.2.1.dev0}/ap_client/cli.py

@@ -21,8 +21,10 @@ from ap_client.api import (
     set_verbose_override,
 )
 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.irepo_commands import register as _register_dataset_repo
+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.profile_commands import profile_app
 from ap_client.waiter import (
     WaitTimeoutError,
@@ -143,8 +145,11 @@ app.add_typer(meta_job_type_app, name="meta-job-type")
 app.add_typer(benchmark_app, name="benchmark")
 app.add_typer(checkpoint_app, name="checkpoint")
 
-# ap dataset repo:透传 instance_repo CLI(见 ap_client/irepo_commands.py)
-_register_dataset_repo(dataset_app)
+# Dataset 领域(见 docs/ap-cli-dataset-refactor-design.md):
+# ap dataset version/split/access 嵌套在 dataset 下;instance/fs 是一等资源。
+_register_dataset_commands(dataset_app)
+_register_instance_commands(app)
+_register_fs_commands(app)
 
 _PAI_RUNTIME_ENV_TAGS: tuple[tuple[str, str], ...] = (
     ("DLC_JOB_ID", "dlc_job_id"),
@@ -923,7 +928,10 @@ 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)
-        if str(key) in masked_paths and value == "***":
+        # 直接信任 masked_params 路径：服务端掩码形态已扩展为保留首尾（如
+        # sk-***890 / ****），不能再按值严格等于 "***" 判断，否则形态变化后
+        # (masked) 标识静默丢失
+        if str(key) in masked_paths:
             display_value = f"{display_value} (masked)"
         rows.append((str(key), display_value))
     _print_key_values(rows, skip_empty=False)
@@ -2014,24 +2022,17 @@ def template_fetch(
 
 # ==================== Dataset operations ====================
 
-
-@dataset_app.command("list")
-def dataset_list(
-    search: Optional[str] = typer.Argument(None, help="Search keyword"),
-    output_format: str = typer.Option(
-        None,
-        "--format",
-        help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
-    ),
-):
-    """List all datasets."""
-    output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
-    result = client.list_all_datasets(search)
-    if output_format == "table":
-        _print_records_table(result)
-    else:
-        _print_formatted(result, output_format)
+# 设计 §6 / 上游 §13.2:`ap dataset versions` 与 `ap dataset instances` 行为保持不变
+# (仍打 ossdata 路由,`ap job create` 的配套流程依赖它们),只追加固定弃用文案。
+# 文案**只写 stderr**——JSON/YAML 的 stdout 必须仍可被 json.loads 直接消费。
+_DATASET_VERSIONS_DEPRECATION = (
+    "Warning: `ap dataset versions` is deprecated.\n"
+    "Use `ap dataset version list --dataset <dataset>` instead."
+)
+_DATASET_INSTANCES_DEPRECATION = (
+    "Warning: `ap dataset instances` is deprecated.\n"
+    "Use `ap instance list --dataset <dataset> --split <split> [--version <version>]` instead."
+)
 
 
 @dataset_app.command("versions")
@@ -2043,8 +2044,9 @@ def dataset_versions(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List dataset versions."""
+    """List dataset versions (deprecated: use 'ap dataset version list')."""
     output_format = _normalize_output_format(output_format, keep_table=True)
+    _emit_progress(_DATASET_VERSIONS_DEPRECATION)
     client = get_client()
     versions = client.list_dataset_versions(dataset)
     if output_format == "table":
@@ -2064,8 +2066,9 @@ def dataset_instances(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List dataset instances."""
+    """List dataset instances (deprecated: use 'ap instance list')."""
     output_format = _normalize_output_format(output_format, keep_table=True)
+    _emit_progress(_DATASET_INSTANCES_DEPRECATION)
     client = get_client()
     result = client.list_all_dataset_instances(dataset_version)
     if output_format == "table":