ap-client 0.5.0.dev0__tar.gz → 0.5.1.dev0__tar.gz

{ap_client-0.5.0.dev0 → ap_client-0.5.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.5.0.dev0
+Version: 0.5.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]<2.0.0,>=1.1.4; extra == 'all'
+Requires-Dist: instance-repo[oss]==1.3.2.dev0; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.4; extra == 'dataset'
+Requires-Dist: instance-repo[oss]==1.3.2.dev0; 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.0.dev0 → ap_client-0.5.1.dev0}/ap_client/akpool_commands.py

@@ -63,9 +63,7 @@ def _fmt(output_format: Optional[str]) -> str:
 def _check_time_range(value: str) -> str:
     normalized = str(value or "").strip().lower()
     if not _TIME_RANGE_RE.fullmatch(normalized):
-        raise typer.BadParameter(
-            f"--time-range must be a duration like 30s/5m/1h, got {value!r}"
-        )
+        raise typer.BadParameter(f"--time-range must be a duration like 30s/5m/1h, got {value!r}")
     return normalized
 
 

{ap_client-0.5.0.dev0 → ap_client-0.5.1.dev0}/ap_client/api.py

@@ -123,14 +123,6 @@ _UNSET: Any = object()
 # when aggregation runs later.
 EXTRA_AGG_OPS = ("avg", "sum")
 
-# Others 占位：apiserver 词表不返回，CLI 展示与 get_meta_model("Others") 兜底用。
-_OTHERS_MODEL = {
-    "name": "Others",
-    "series_name": "",
-    "source_id": "",
-    "series_id": "",
-}
-
 
 def _merge_meta_tags(
     tags: Optional[list],
@@ -976,18 +968,19 @@ class APIClient:
     # `dataset versions/instances`、`job create --dataset`)。
 
     def list_meta_models(self) -> dict:
-        """模型词表（apiserver 权威源 GET /apis/v1/meta-models，返回 {items:[...]}）。"""
-        return self._get_central("/meta-models")
+        """从 meta-model 标签目录获取可用模型，保留 list 的 items 响应形状。"""
+        items = self.get_meta_tags("meta-model").get("items") or []
+        return {
+            "items": [
+                {**item, "name": item["value"]}
+                for item in items
+                if item.get("value") and item.get("is_enabled", True)
+            ]
+        }
 
     def get_meta_model(self, name: str) -> dict:
-        """单个模型详情（按 name 或 source_id 从 apiserver list 过滤；Others 返回占位）。
-
-        apiserver 没有单模型详情接口，客户端从 list 结果过滤；找不到 raise
-        APIError 404，与原 cluster AP /meta/models/{name} 行为一致。
-        """
-        if name == "Others":
-            return dict(_OTHERS_MODEL)
-        result = self._get_central("/meta-models")
+        """从启用的 meta-model 标签值中按 value 或 source_id 查找。"""
+        result = self.list_meta_models()
         for item in result.get("items") or []:
             if item.get("name") == name or item.get("source_id") == name:
                 return item
@@ -1053,43 +1046,13 @@ class APIClient:
         return result
 
     def list_meta_job_types(self) -> dict:
-        """任务类型词表（目录驱动：GET /apis/v1/meta-tags?key=meta-job-type）。
-
-        仅取目录中 ``is_enabled`` 的值（缺失按启用解析）+ 末尾 ``Others``
-        兜底行；``default`` 为 ``Eval-Eval``（在目录中时，否则空串）。
-        目录请求失败或为空 → 回退本地常量（Eval-Eval + Others，fail-open），
-        并在 stderr 打一行告警，词表降级可见但不阻塞命令。
-        """
-        error: Exception | None = None
-        try:
-            items = self.get_meta_tags("meta-job-type").get("items") or []
-        except Exception as exc:  # fail-open：目录不可用不阻塞词表命令
-            error = exc
-            items = []
-        if items:
-            options = []
-            for item in items:
-                value = str(item.get("value") or "").strip()
-                if value and item.get("is_enabled", True):
-                    options.append({"value": value})
-            if options:
-                default = "Eval-Eval" if any(o["value"] == "Eval-Eval" for o in options) else ""
-                return {
-                    "meta_job_type": {
-                        "default": default,
-                        "options": [*options, {"value": "Others"}],
-                    }
-                }
-        _write_stderr(
-            [
-                "warning: meta-job-type catalog unavailable or empty, "
-                f"falling back to local constants (reason={error or 'empty catalog'})"
-            ]
-        )
+        """从 meta-job-type 标签目录获取启用的任务类型，不补本地展示值。"""
+        items = self.get_meta_tags("meta-job-type").get("items") or []
         return {
             "meta_job_type": {
-                "default": "Eval-Eval",
-                "options": [{"value": "Eval-Eval"}, {"value": "Others"}],
+                "options": [
+                    item for item in items if item.get("value") and item.get("is_enabled", True)
+                ],
             }
         }
 
@@ -1283,6 +1246,7 @@ class APIClient:
         benchmark: Optional[str] = None,
         experiment: Optional[str] = None,
         ak_id: Optional[str] = None,
+        ak_mode: str = "auto",
         instance_range: Optional[str] = None,
         profile: Optional[str] = None,
     ) -> dict:
@@ -1334,6 +1298,7 @@ class APIClient:
             benchmark=benchmark,
             experiment=experiment,
             ak_id=ak_id,
+            ak_mode=ak_mode,
         )
 
         result = self._post("/jobs", body, timeout=timeout)
@@ -1395,6 +1360,7 @@ class APIClient:
         benchmark: Optional[str] = None,
         experiment: Optional[str] = None,
         ak_id: Optional[str] = None,
+        ak_mode: str = "auto",
         instance_range: Optional[str] = None,
         profile: Optional[str] = None,
     ) -> dict:
@@ -1410,11 +1376,15 @@ class APIClient:
         if not template and not profile_id and profile is None:
             raise ValueError("Either template, profile or profile_id is required")
         validate_ak_selection(ak_id, params, params_list, overrides)
+        if ak_mode not in {"auto", "manual", "synced"}:
+            raise ValueError("ak_mode must be auto, manual or synced")
         body: dict = {}
         if template is not None:
             body["template"] = template
         if ak_id is not None:
             body["ak_id"] = ak_id
+        if ak_mode != "auto":
+            body["ak_mode"] = ak_mode
 
         if params is not None:
             body["params"] = params

{ap_client-0.5.0.dev0 → ap_client-0.5.1.dev0}/ap_client/cli.py

@@ -15,7 +15,6 @@ import typer
 from ap_client import __version__, get_client, get_config, tbb
 from ap_client.akpool_commands import register as _register_akpool_commands
 from ap_client.api import (
-    _OTHERS_MODEL,
     APIError,
     PaginationProtocolError,
     _is_sensitive_key,
@@ -267,12 +266,15 @@ def _build_job_create_retry_command(
     resource_profile_id: Optional[str] = None,
     timeout: Optional[float] = None,
     ak_id: Optional[str] = None,
+    ak_mode: str = "auto",
 ) -> str:
     args = ["ap", "job", "create"]
     if template is not None:
         args.append(template)
     if ak_id is not None:
         args.extend(["--ak-id", ak_id])
+    if ak_mode != "auto":
+        args.extend(["--ak-mode", ak_mode])
     if profile is not None:
         args.extend(["--profile", profile])
     if resource_profile_id:
@@ -1240,6 +1242,7 @@ def _idempotency_item_key(
     resource_profile_id: Optional[str] = None,
     max_failure_retries: int = 0,
     ak_id: Optional[str] = None,
+    ak_mode: str = "auto",
 ) -> str:
     # Client-supplied item keys are authoritative; server hashing is only a
     # fallback for non-CLI callers, so this payload intentionally need not
@@ -1259,6 +1262,8 @@ def _idempotency_item_key(
     }
     if ak_id is not None:
         payload_data["ak_id"] = ak_id
+    if ak_mode != "auto":
+        payload_data["ak_mode"] = ak_mode
     if resource_profile_id is not None:
         payload_data["resource_profile_id"] = resource_profile_id
     if max_failure_retries:
@@ -2683,23 +2688,22 @@ def meta_model_list(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List meta model options (apiserver data + Others as the last row)."""
+    """List enabled meta-model tag values."""
     output_format = _normalize_output_format(output_format, keep_table=True)
     result = get_client().list_meta_models()
     items = result.get("items") or []
-    options = [*items, dict(_OTHERS_MODEL)]  # 末尾固定追加 Others 兜底手动输入
+    options = items
     if output_format in ("plain", "table"):
         rows = [
             {
                 "name": m.get("name") or "-",
-                "series": m.get("series_name") or "-",
+                "desc": m.get("desc_l1") or "-",
             }
             for m in options
         ]
-        _print_plain_table(rows, [("name", "name"), ("series", "series")])
+        _print_plain_table(rows, [("name", "name"), ("desc", "desc")])
     else:
-        # json/yaml 包装成 {meta_model:{options}}（原 cluster AP 格式；
-        # default 已随 meta-models default 逻辑移除而下线）
+        # JSON/YAML 保持 {meta_model:{options}}；每项保留目录字段及 name 别名。
         _print_formatted({"meta_model": {"options": options}}, output_format)
 
 
@@ -2790,21 +2794,20 @@ def meta_job_type_list(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List meta job type options (catalog-driven; falls back to Eval-Eval/Others)."""
+    """List enabled meta-job-type tag values."""
     output_format = _normalize_output_format(output_format, keep_table=True)
     result = get_client().list_meta_job_types()
     info = result.get("meta_job_type") or {}
     options = info.get("options") or []
-    default = info.get("default") or ""
     if output_format in ("plain", "table"):
         rows = [
             {
                 "value": o.get("value") or "-",
-                "default": "*" if o.get("value") and o.get("value") == default else "",
+                "desc": o.get("desc_l1") or "-",
             }
             for o in options
         ]
-        _print_plain_table(rows, [("value", "value"), ("default", "default")])
+        _print_plain_table(rows, [("value", "value"), ("desc", "desc")])
     else:
         _print_formatted(result, output_format)
 
@@ -2990,6 +2993,9 @@ def job_create(
     ak_id: Optional[str] = typer.Option(
         None, "--ak-id", help="AP-managed AK ID; requires server support"
     ),
+    ak_mode: str = typer.Option(
+        "auto", "--ak-mode", help="AK credential source: auto, manual or synced"
+    ),
     agenthub_ref: Optional[str] = typer.Option(
         None, "--agenthub-ref", help="Agent-Hub branch/commit; overrides AP_AGENTHUB_REF"
     ),
@@ -3332,6 +3338,8 @@ def job_create(
     output_format = _normalize_output_format(output_format)
     if not template and not profile:
         raise typer.BadParameter("TEMPLATE is required unless --profile is provided")
+    if ak_mode not in {"auto", "manual", "synced"}:
+        raise typer.BadParameter("Choose auto, manual or synced", param_hint="--ak-mode")
     try:
         validate_ak_id(ak_id)
         resource_profile_id = _normalize_resource_profile_id(resource_profile_id)
@@ -3528,6 +3536,7 @@ def job_create(
             profile=profile,
             resource_profile_id=resource_profile_id,
             **({"ak_id": ak_id} if ak_id is not None else {}),
+            **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
             instances=instances_list,
             instance_range=instance_range,
             dataset=dataset,
@@ -3601,6 +3610,7 @@ def job_create(
                 profile=profile,
                 resource_profile_id=resource_profile_id,
                 **({"ak_id": ak_id} if ak_id is not None else {}),
+                **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                 timeout=timeout,
             )
             if idempotency_enabled and submission_idempotency_key is not None
@@ -3645,6 +3655,7 @@ def job_create(
                     profile=profile,
                     resource_profile_id=resource_profile_id,
                     **({"ak_id": ak_id} if ak_id is not None else {}),
+                    **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                     instances=instances_list,
                     instance_range=instance_range,
                     dataset=dataset,
@@ -3860,6 +3871,7 @@ def job_create(
             idempotency_key=submission_idempotency_key,
             resource_profile_id=resource_profile_id,
             **({"ak_id": ak_id} if ak_id is not None else {}),
+            **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
             timeout=timeout,
         )
         if not dry_run
@@ -3956,6 +3968,7 @@ def job_create(
                         account_pool=account_pool,
                         resource_profile_id=resource_profile_id,
                         **({"ak_id": ak_id} if ak_id is not None else {}),
+                        **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                         max_failure_retries=max_failure_retries,
                     )
                 batch.append(item)
@@ -3989,6 +4002,7 @@ def job_create(
                 account_pool=account_pool,
                 resource_profile_id=resource_profile_id,
                 **({"ak_id": ak_id} if ak_id is not None else {}),
+                **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                 checkpoint_id=checkpoint_id,
                 checkpoint_path=checkpoint_path,
                 checkpoint=checkpoint_dict,
@@ -4032,6 +4046,7 @@ def job_create(
                         account_pool=account_pool,
                         resource_profile_id=resource_profile_id,
                         **({"ak_id": ak_id} if ak_id is not None else {}),
+                        **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                         checkpoint_id=checkpoint_id,
                         checkpoint_path=checkpoint_path,
                         checkpoint=checkpoint_dict,
@@ -4089,6 +4104,7 @@ def job_create(
                         account_pool=account_pool,
                         resource_profile_id=resource_profile_id,
                         **({"ak_id": ak_id} if ak_id is not None else {}),
+                        **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                         checkpoint_id=checkpoint_id,
                         checkpoint_path=checkpoint_path,
                         checkpoint=checkpoint_dict,
@@ -4195,6 +4211,7 @@ def job_create(
                 account_pool=account_pool,
                 resource_profile_id=resource_profile_id,
                 **({"ak_id": ak_id} if ak_id is not None else {}),
+                **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                 checkpoint_id=checkpoint_id,
                 checkpoint_path=checkpoint_path,
                 checkpoint=checkpoint_dict,
@@ -4232,6 +4249,7 @@ def job_create(
                 account_pool=account_pool,
                 resource_profile_id=resource_profile_id,
                 **({"ak_id": ak_id} if ak_id is not None else {}),
+                **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                 checkpoint_id=checkpoint_id,
                 checkpoint_path=checkpoint_path,
                 checkpoint=checkpoint_dict,
@@ -4279,6 +4297,7 @@ def job_create(
                     account_pool=account_pool,
                     resource_profile_id=resource_profile_id,
                     **({"ak_id": ak_id} if ak_id is not None else {}),
+                    **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
                     checkpoint_id=checkpoint_id,
                     checkpoint_path=checkpoint_path,
                     checkpoint=checkpoint_dict,

{ap_client-0.5.0.dev0 → ap_client-0.5.1.dev0}/ap_client/dataset_commands.py

@@ -50,18 +50,15 @@ def register(dataset_app: typer.Typer) -> None:
 
 
 def _register_dataset_commands(dataset_app: typer.Typer) -> None:
-    """挂载 dataset 级命令(``list`` / ``get`` / ``create`` / ``update`` / ``claim``)。
+    """挂载 dataset 级命令。"""
+    from .dataset_register import dataset_register
 
-    实现方式:把命令写成本模块的模块级函数,再在这里用
-    ``dataset_app.command("<name>")(<func>)`` 挂上去。``list`` 需要**替换**
-    ``cli.py`` 里现存的 ossdata 版本(设计 §4.1),挂载时用同名 ``"list"`` 覆盖,
-    并同步删掉 ``cli.py`` 中的旧实现。
-    """
     dataset_app.command("list")(dataset_list)
     dataset_app.command("get")(dataset_get)
     dataset_app.command("create")(dataset_create)
     dataset_app.command("update")(dataset_update)
     dataset_app.command("claim")(dataset_claim)
+    dataset_app.command("register")(dataset_register)
 
 
 # ---------------------------------------------------------------------------
@@ -86,6 +83,7 @@ _VERSION_COLUMNS: tuple[tuple[str, str], ...] = (
     ("splits", "SPLITS"),
     ("instances", "INSTANCES"),
     ("updated_at", "UPDATED_AT"),
+    ("registered", "REGISTERED"),
 )
 
 #: 上游 §8.2 的默认列(设计 §5)。
@@ -94,6 +92,7 @@ _SPLIT_COLUMNS: tuple[tuple[str, str], ...] = (
     ("run_type", "RUN_TYPE"),
     ("instances", "INSTANCES"),
     ("updated_at", "UPDATED_AT"),
+    ("registered", "REGISTERED"),
 )
 
 _ACCESS_COLUMNS: tuple[tuple[str, str], ...] = (
@@ -398,6 +397,7 @@ def _model_dict(record: Any) -> dict:
     ``{}`` / 缺省都不会出现在响应里),而 SDK 模型会把它们补成默认值;留着这些默认值会让
     JSON 凭空多出字段(迁移前是原样透出服务端响应,契约必须一致)。
 
+    ``registered`` 是显式注册状态，必须保留 ``false``。
     只清洗**顶层**:嵌套结构(如 version 详情里的 ``splits[].is_default``)按模型原样输出,
     服务端在那里确实是显式返回 ``false``。
     """
@@ -412,13 +412,24 @@ def _model_dict(record: Any) -> dict:
         return {}
     if not isinstance(payload, dict):
         return {}
+    registered = getattr(record, "registered", None)
+    if isinstance(registered, bool):
+        payload = {**payload, "registered": registered}
     return {
         key: value
         for key, value in payload.items()
-        if not (value is None or value is False or value == "" or value == [] or value == {})
+        if value is not None
+        and (key == "registered" or not (value is False or value == "" or value == [] or value == {}))
     }
 
 
+def _registered_dict(record: Any) -> dict:
+    """Preserve SDK registration state; older metadata-only SDK reads imply true."""
+    payload = _model_dict(record)
+    payload.setdefault("registered", True)
+    return payload
+
+
 def _api_biz_code(exc: BaseException) -> Optional[int]:
     """从 ``APIError`` 里取 apiserver 业务码(设计 §5.1),不 import 数值异常类。
 
@@ -814,6 +825,7 @@ def _version_row(record: dict) -> dict:
         "splits": splits,
         "instances": record.get("instance_count", ""),
         "updated_at": record.get("updated_at") or "",
+        "registered": record.get("registered", True),
     }
 
 
@@ -833,6 +845,7 @@ def _split_row(record: dict, detail: dict) -> dict:
         "run_type": record.get("run_type") or detail.get("run_type") or "",
         "instances": "" if instances is None else instances,
         "updated_at": record.get("updated_at") or detail.get("updated_at") or "",
+        "registered": record.get("registered", detail.get("registered", True)),
     }
 
 
@@ -1144,11 +1157,22 @@ def dataset_get(
     try:
         detail = repo.datasets.get_detail(dataset, **_env_kwargs(env))
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
-        raise _fail(
-            f"Failed to query dataset {dataset}: {_reason(exc)}",
-            f"Check the dataset name: ap dataset list --query {dataset}",
-        ) from exc
-    rendered = _model_dict(detail)
+        if _business_code(exc) not in (92001, 94021):
+            raise _fail(
+                f"Failed to query dataset {dataset}: {_reason(exc)}",
+                f"Check the dataset name: ap dataset list --query {dataset}",
+            ) from exc
+        detail = None
+    if detail is None:
+        l1, _, l2 = dataset.partition("/")
+        rendered = {
+            "dataset_name": dataset,
+            "dataset_l1": l1,
+            "dataset_l2": l2,
+            "registered": False,
+        }
+    else:
+        rendered = _registered_dict(detail)
     _emit_detail(rendered, output_format, order=_DATASET_DETAIL_ORDER, always=("status",))
     if output_format not in ("json", "yaml"):
         _print_dataset_environments(repo, dataset, rendered)
@@ -1642,7 +1666,7 @@ def dataset_version_list(
             f"Check the dataset name: ap dataset list --query {dataset}",
         ) from exc
 
-    records = [_model_dict(record) for record in (getattr(result, "items", None) or [])]
+    records = [_registered_dict(record) for record in (getattr(result, "items", None) or [])]
     rows = [_version_row(record) for record in records]
     _emit(
         {"dataset": dataset, "versions": records, "pagination": _pagination_envelope(result)},
@@ -1663,7 +1687,7 @@ def dataset_version_get(
     output_format = _fmt(output_format)
     resolved = _version_value(version)
     detail = _fetch_version(dataset, resolved, stage="query", environment=environment)
-    _emit_detail(detail, output_format, order=_VERSION_DETAIL_ORDER)
+    _emit_detail(_registered_dict(detail), output_format, order=_VERSION_DETAIL_ORDER)
 
 
 @dataset_version_app.command("create")
@@ -1810,6 +1834,7 @@ def dataset_split_get(
                 payload = dict(record)
                 payload.setdefault("dataset", dataset)
                 payload.setdefault("version", resolved_version)
+                payload.setdefault("registered", detail.get("registered", True))
                 _emit_detail(payload, output_format)
                 return
         known = ", ".join(_split_names(detail)) or "<none>"
@@ -1819,6 +1844,7 @@ def dataset_split_get(
             payload = dict(record)
             payload.setdefault("dataset", dataset)
             payload.setdefault("version", "")
+            payload.setdefault("registered", True)
             _emit_detail(payload, output_format)
             return
         known = (

ap_client-0.5.1.dev0/ap_client/dataset_register.py

@@ -0,0 +1,320 @@
+"""Dataset metadata registration command backed by Instance Repo ingest."""
+
+from __future__ import annotations
+
+import json
+import math
+import sys
+from typing import Any, List, Optional
+from urllib.parse import quote
+
+import typer
+
+from . import dataset_commands as datasets
+
+_TERMINAL_SUCCESS = {"completed"}
+_TERMINAL_FAILURE = {"failed"}
+_TERMINAL_CANCELED = {"canceled", "cancelled"}
+
+
+def _payload(outcome: str, dataset: str, result: Any) -> dict:
+    return {**datasets._model_dict(result), "outcome": outcome, "dataset": dataset}
+
+
+def _emit_preview_stderr(payload: dict, output_format: str) -> None:
+    typer.echo("Preview:", err=True)
+    if output_format == "yaml":
+        try:
+            import yaml
+        except ImportError as exc:
+            raise typer.BadParameter("--format yaml requires PyYAML to be installed") from exc
+        typer.echo(yaml.safe_dump(payload, allow_unicode=True, sort_keys=False).rstrip(), err=True)
+        return
+    typer.echo(json.dumps(payload, ensure_ascii=False, indent=2), err=True)
+
+
+def _confirm(dataset: str, *, yes: bool) -> None:
+    if yes:
+        return
+    if not sys.stdin.isatty():
+        raise datasets._fail(
+            f"Registering dataset {dataset} requires confirmation after preview",
+            "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):
+        raise datasets._fail(
+            "Registration canceled; nothing was written remotely",
+            "Rerun the command and confirm, or add --yes (-y)",
+        )
+
+
+def _claim_without_workspace(
+    repo: Any, dataset_id: str, current_user: str, benchmark_id: str
+) -> dict:
+    body = {"owner": current_user}
+    if benchmark_id:
+        body["benchmark_id"] = benchmark_id
+    return repo.transport.post(
+        f"/apis/v1/datasets/series/{quote(dataset_id, safe='')}/claim",
+        body,
+    )
+
+
+def _create_owned_dataset(repo: Any, dataset: str, benchmark_id: str) -> dict:
+    parts = dataset.split("/")
+    if len(parts) != 2 or not all(parts):
+        raise datasets._fail(
+            f"Failed to create dataset {dataset}: the name must be two segments <team>/<name>",
+            "Use a dataset name such as your-team/my-bench",
+            exit_code=2,
+        )
+
+    from instance_repo.models import DatasetSeries
+
+    fields: dict[str, Any] = {
+        "dataset_name": dataset,
+        "dataset_l1": parts[0],
+        "dataset_l2": parts[1],
+        "visibility": "private",
+    }
+    if benchmark_id:
+        fields["benchmark_id"] = benchmark_id
+    record = repo.datasets.create(DatasetSeries(**fields), require_benchmark=False)
+    return datasets._model_dict(record)
+
+
+def _ensure_current_user_owns(
+    repo: Any, dataset: str, environment: str, benchmark: Optional[str]
+) -> None:
+    from . import cli
+    from .irepo_sdk import _reason
+
+    try:
+        current_user = cli.get_client()._resolve_self_user_id()
+    except Exception as exc:  # noqa: BLE001 - keep the CLI error contract
+        raise datasets._fail(
+            f"Failed to resolve the current user: {_reason(exc)}",
+            "Check AP_API_KEY and the current cluster, then retry",
+        ) from exc
+    if not current_user:
+        raise datasets._fail(
+            "Failed to resolve the current user for --owner @me",
+            "Check AP_API_KEY and the current cluster, then retry",
+        )
+
+    missing = False
+    try:
+        raw_detail = repo.datasets.get_detail(dataset, **datasets._env_kwargs(environment))
+        detail = datasets._model_dict(raw_detail)
+        missing = raw_detail is None or detail.get("registered") is False
+    except Exception as exc:  # noqa: BLE001 - dataset absence permits create
+        if datasets._business_code(exc) not in (92001, 94021):
+            raise datasets._fail(
+                f"Failed to inspect ownership for dataset {dataset}: {_reason(exc)}",
+                f"Check access with: ap dataset get {dataset}",
+            ) from exc
+        missing = True
+        detail = {}
+    if missing:
+        benchmark_id = datasets._resolve_benchmark_id(repo, benchmark) if benchmark else ""
+        try:
+            created = _create_owned_dataset(repo, dataset, benchmark_id)
+        except typer.Exit:
+            raise
+        except Exception as create_exc:  # noqa: BLE001 - server remains authoritative
+            raise datasets._fail(
+                f"Failed to create dataset {dataset}: {_reason(create_exc)}",
+                f"Check the name and benchmark, then inspect: ap dataset get {dataset}",
+            ) from create_exc
+        created_owner = str(created.get("owner") or "").strip()
+        if created_owner != current_user:
+            shown_owner = created_owner or "<unknown>"
+            raise datasets._fail(
+                f"Dataset {dataset} was created or claimed concurrently by {shown_owner}",
+                "Do not retry with --owner @me; ask the current dataset admin for access",
+            )
+        return
+
+    owner = str(detail.get("owner") or "").strip()
+    if owner == current_user:
+        return
+    if owner:
+        raise datasets._fail(
+            f"Dataset {dataset} is owned by {owner}; --owner @me cannot take it over",
+            "Ask the existing dataset admin to run the registration or grant access",
+        )
+    if not detail.get("claimable", False):
+        raise datasets._fail(
+            f"Dataset {dataset} cannot be claimed because it already has an admin",
+            "Ask an existing dataset admin to run the registration or grant access",
+        )
+    dataset_id = str(detail.get("dataset_id") or "").strip()
+    if not dataset_id:
+        raise datasets._fail(
+            f"Failed to claim dataset {dataset}: the server returned no dataset_id",
+            f"Inspect the dataset with: ap dataset get {dataset}",
+        )
+    benchmark_id = datasets._resolve_benchmark_id(repo, benchmark) if benchmark else ""
+    try:
+        _claim_without_workspace(repo, dataset_id, current_user, benchmark_id)
+    except Exception as exc:  # noqa: BLE001 - preserve SDK transport error mapping
+        hint = datasets._DATASET_CODE_HINTS.get(datasets._business_code(exc)) or (
+            "Ask an existing dataset admin for access, or verify that the dataset is still claimable"
+        )
+        raise datasets._fail(
+            f"Failed to claim dataset {dataset}: {_reason(exc)}",
+            hint,
+        ) from exc
+
+
+def dataset_register(
+    dataset: str = typer.Argument(..., help="Dataset name"),
+    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"
+    ),
+    environment: Optional[str] = typer.Option(
+        None, "--environment", help=datasets._ENVIRONMENT_HELP
+    ),
+    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"),
+    output_format: Optional[str] = typer.Option(None, "--format", help=datasets._FORMAT_HELP),
+    owner: Optional[str] = typer.Option(
+        None, "--owner", help="Ensure ownership before ingest; the only supported value is @me"
+    ),
+    benchmark: Optional[str] = typer.Option(
+        None, "--benchmark", help="Benchmark for create/claim when using --owner @me"
+    ),
+) -> None:
+    """Preview and register existing dataset data through an ingest task."""
+    from .irepo_sdk import _reason
+
+    fmt = datasets._fmt(output_format)
+    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:
+        raise datasets._fail(
+            "--version and --unversioned are mutually exclusive",
+            "Choose a version or the version-less space",
+            exit_code=2,
+        )
+    if unversioned and not selected_splits:
+        raise datasets._fail(
+            "--unversioned requires at least one --split",
+            "Repeat --split for each version-less split to register",
+            exit_code=2,
+        )
+    if owner is not None and owner != "@me":
+        raise datasets._fail(
+            "--owner only supports @me",
+            "Use --owner @me or omit --owner to leave ownership unchanged",
+            exit_code=2,
+        )
+    if benchmark and owner != "@me":
+        raise datasets._fail(
+            "--benchmark requires --owner @me because it is only used during create or claim",
+            "Add --owner @me or omit --benchmark",
+            exit_code=2,
+        )
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise datasets._fail(
+            "--timeout must be a positive finite number",
+            "Pass a positive number of seconds",
+            exit_code=2,
+        )
+
+    env = datasets._environment(environment)
+    repo = datasets._dataset_repo()
+    datasets._check_storage_side(repo, env)
+    ingest = getattr(getattr(repo, "versions", None), "ingest", None)
+    if not callable(ingest):
+        raise datasets._fail(
+            "The installed Instance Repo SDK does not support dataset ingest",
+            "Install or upgrade ap-client[dataset] to a version with versions.ingest",
+            exit_code=2,
+        )
+
+    kwargs = {
+        "splits": selected_splits or None,
+        **datasets._env_kwargs(env),
+        "allow_layout_inference": selected_version is None and not selected_splits,
+        "dry_run": True,
+        "wait": False,
+        "timeout_sec": timeout,
+        "raise_on_failure": False,
+    }
+    try:
+        preview = datasets._model_dict(ingest(dataset, selected_version, **kwargs))
+    except Exception as exc:  # noqa: BLE001 - SDK failures use the CLI contract
+        raise datasets._fail(
+            f"Failed to preview registration for dataset {dataset}: {_reason(exc)}",
+            "Check the dataset scope, cluster storage, and environment, then retry",
+        ) from exc
+
+    preview_payload = _payload("preview", dataset, preview)
+    if dry_run:
+        datasets._emit_detail(preview_payload, fmt)
+        return
+
+    _emit_preview_stderr(preview_payload, fmt)
+    _confirm(dataset, yes=yes)
+    if owner == "@me":
+        _ensure_current_user_owns(repo, dataset, env, benchmark)
+
+    submission_kwargs = {**kwargs, "dry_run": False, "wait": wait}
+    if wait:
+        typer.echo(
+            f"Waiting up to {timeout:g} seconds for the registration task to finish...",
+            err=True,
+        )
+    try:
+        result = datasets._model_dict(ingest(dataset, selected_version, **submission_kwargs))
+    except Exception as exc:  # noqa: BLE001 - SDK failures use the CLI contract
+        if wait:
+            failed_job = datasets._model_dict(getattr(exc, "job", None))
+            ingest_id = str(failed_job.get("ingest_id") or failed_job.get("id") or "").strip()
+            task_hint = f" task {ingest_id}" if ingest_id else " the task"
+            raise datasets._fail(
+                f"Failed to submit or wait for registration of dataset {dataset}: {_reason(exc)}",
+                f"The request may have been accepted and{task_hint} may still be running; "
+                "inspect dataset metadata before deciding whether to submit again",
+            ) from exc
+        raise datasets._fail(
+            f"Failed to submit registration for dataset {dataset}: {_reason(exc)}",
+            "The preview did not write metadata; inspect the error and retry the command",
+        ) from exc
+
+    status = str(result.get("status") or "").strip().lower()
+    if status in _TERMINAL_SUCCESS:
+        outcome = "completed"
+    elif status in _TERMINAL_FAILURE:
+        outcome = "failed"
+    elif status in _TERMINAL_CANCELED:
+        outcome = "canceled"
+    elif wait:
+        outcome = "timed_out"
+    else:
+        outcome = "submitted"
+
+    datasets._emit_detail(_payload(outcome, dataset, result), fmt)
+    ingest_id = str(result.get("ingest_id") or result.get("id") or "").strip()
+    if outcome == "failed":
+        raise datasets._fail(
+            f"Registration task {ingest_id or '<unknown>'} failed: "
+            f"{result.get('error_message') or ''}",
+            "Fix the reported data or metadata issue, then run the same registration command again",
+        )
+    if outcome == "canceled":
+        raise datasets._fail(
+            f"Registration task {ingest_id or '<unknown>'} was canceled",
+            "Inspect the dataset metadata before deciding whether to submit again",
+        )
+    if outcome == "timed_out":
+        raise datasets._fail(
+            "Registration wait timed out; the background task continues running",
+            f"Inspect dataset metadata after task {ingest_id or '<unknown>'} finishes",
+        )

{ap_client-0.5.0.dev0 → ap_client-0.5.1.dev0}/ap_client/instance_commands.py

@@ -17,7 +17,7 @@
 错误);SDK 抛出的业务异常 → ``sdk_error_exit(exc, what=..., stage=...)``。
 
 渲染与退出码沿用 ``ap_client.cli`` 的既有 helper,同样函数内部 import 以避免与
-``cli`` 循环依赖。默认列(设计 §5):``INSTANCE SPLIT VERSION DIGEST UPDATED_AT``。
+``cli`` 循环依赖。默认列:``INSTANCE SPLIT VERSION DIGEST UPDATED_AT REGISTERED``。
 """
 
 from __future__ import annotations
@@ -52,6 +52,7 @@ _INSTANCE_COLUMNS: tuple[tuple[str, str], ...] = (
     ("version", "VERSION"),
     ("digest", "DIGEST"),
     ("updated_at", "UPDATED_AT"),
+    ("registered", "REGISTERED"),
 )
 
 _FORMAT_HELP = "Output format: plain/table/json/yaml (default: AP_FORMAT or command default)"
@@ -292,6 +293,7 @@ def _instance_record(instance: Any) -> dict:
         "manifest": served.get("manifest") or [],
         "created_at": served.get("created_at"),
         "updated_at": served.get("updated_at"),
+        "registered": served.get("registered", True),
     }
     if split and split != "default":  # SDK 的 default 哨兵 = 无 split,服务端不返回该键
         record["split"] = split
@@ -309,6 +311,7 @@ def _instance_row(record: dict) -> dict:
         "version": record.get("dataset_version") or record.get("version") or "",
         "digest": _record_digest(record),
         "updated_at": record.get("updated_at") or "",
+        "registered": record.get("registered", True),
     }
 
 

{ap_client-0.5.0.dev0 → ap_client-0.5.1.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.5.0.dev0"
+version = "0.5.1.dev0"
 description = "Agent Platform API Client & CLI"
 readme = { text = "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.", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -18,10 +18,10 @@ dependencies = [
 
 [project.optional-dependencies]
 dataset = [
-    "instance-repo[oss]>=1.1.4,<2.0.0",
+    "instance-repo[oss]==1.3.2.dev0",
 ]
 all = [
-    "instance-repo[oss]>=1.1.4,<2.0.0",
+    "instance-repo[oss]==1.3.2.dev0",
 ]
 
 [project.scripts]