ap-client 0.7.0.dev3__tar.gz → 0.7.0.dev5__tar.gz

{ap_client-0.7.0.dev3 → ap_client-0.7.0.dev5}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.7.0.dev3
+Version: 0.7.0.dev5
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
-Requires-Dist: irepo-artifact==0.2.4.dev1
+Requires-Dist: irepo-artifact==0.2.4
 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]<2.0.0,>=1.3.5; extra == 'all'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.4.0; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]<2.0.0,>=1.3.5; extra == 'dataset'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.4.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.7.0.dev3 → ap_client-0.7.0.dev5}/ap_client/cli.py

@@ -23,6 +23,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.dfs_commands import register as _register_dfs_commands
 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
@@ -165,6 +166,7 @@ app.add_typer(checkpoint_app, name="checkpoint")
 # ap dataset version/split/access 嵌套在 dataset 下;instance/fs 是一等资源。
 _register_dataset_commands(dataset_app)
 _register_instance_commands(app)
+_register_dfs_commands(app)
 _register_fs_commands(app)
 _register_akpool_commands(app)
 
@@ -3001,22 +3003,22 @@ def job_create(
     meta_model: Optional[str] = typer.Option(
         None,
         "--meta-model",
-        help="Meta model tag; omit to leave unset",
+        help="Target model or training project this job serves; not the called model or Judge. Values: ap meta-tag get meta-model --format json",
     ),
     meta_job_type: Optional[str] = typer.Option(
         None,
         "--meta-job-type",
-        help="Meta job type tag: Eval-Eval (default) or Others",
+        help="Business purpose of this job. Values: ap meta-tag get meta-job-type --format json",
     ),
     meta_teacher_direction: Optional[str] = typer.Option(
         None,
         "--meta-teacher-direction",
-        help="Meta teacher direction tag; omit to derive from dataset_series; options: ap meta-teacher-direction list",
+        help="Teacher direction this job serves; verify any dataset-derived value. Values: ap meta-tag get meta-teacher-direction --format json",
     ),
     meta_train_stage: Optional[str] = typer.Option(
         None,
         "--meta-train-stage",
-        help="Meta train stage tag; omit to derive from dataset run_type; options: ap meta-train-stage list",
+        help="Training stage this job serves; verify any dataset-derived value. Values: ap meta-tag get meta-train-stage --format json",
     ),
     overrides: Optional[str] = typer.Option(None, "--overrides", help="Override config (JSON)"),
     concurrency: Optional[int] = typer.Option(
@@ -3188,7 +3190,7 @@ def job_create(
     benchmark: Optional[str] = typer.Option(
         None,
         "--benchmark",
-        help="Benchmark name from the AP registry (see 'ap benchmark list')",
+        help="Prefer the registered benchmark source ID for this run; name is also accepted. Find IDs: ap benchmark list --format json; inspect by name: ap benchmark get NAME --format json",
     ),
     checkpoint_id: Optional[str] = typer.Option(
         None,
@@ -3234,6 +3236,16 @@ def job_create(
 ):
     """Submit a job.
 
+    For agents:
+    \b
+    Before submitting, resolve benchmark, target model, job purpose,
+    training stage, and teacher direction using live catalogs and task context.
+    Verify applicable inherited values: ap profile get ID --version N --format json;
+    ap group get ID --format json. Job tags do not overwrite existing Group metadata.
+    Do not infer target model from serving/Judge models or training stage from evaluation.
+    Ask the user for missing or conflicting business context before choosing values.
+    All five options remain optional; existing validation still applies.
+
     Model configuration:
         Supply template parameters through --params/-p; select a managed credential with --ak-id.
 

{ap_client-0.7.0.dev3 → ap_client-0.7.0.dev5}/ap_client/dataset_commands.py

@@ -123,7 +123,10 @@ _NO_BENCHMARK = "none"
 _FORMAT_HELP = "Output format: plain/table/json/yaml (default: AP_FORMAT or command default)"
 
 _METADATA_MODELS = ("version_first", "split_first")
-_VERSION_SPLIT_METADATA_MODEL = "version_first"
+# IR SDK >= 1.4.0.dev3 的业务入口固定 split_first：business_metadata_model 拒绝
+# version_first（仅保留给低层 legacy 读）。带 version 的 split 查询在两种模型下
+# 结果一致（实测），显式 split_first 与 SDK 归一值一致且新旧 SDK 均接受。
+_VERSION_SPLIT_METADATA_MODEL = "split_first"
 
 #: CLI **不替 SDK 决定元数据模型**:不下发 ``metadata_model``,由 SDK 按 profile 归一
 #: (当前为 ``split_first``)。
@@ -691,6 +694,74 @@ def _unversioned_split(
     return detail if detail is not None and not _version_value(detail.get("version")) else None
 
 
+def _versioned_split(
+    dataset: str, version: str, split: str, *, environment: Optional[str] = None
+) -> Optional[dict]:
+    """取指定 version 里的单个 split 记录;不存在返回 ``None``(不当作错误)。
+
+    与 ``_unversioned_split`` 同源,走 recordsvc 的 ``splits.get``(SDK 自带
+    version_first 内嵌投影的 legacy 回退)。
+    """
+    from .irepo_sdk import _reason
+
+    env = _environment(environment)
+    repo = _dataset_repo()
+    try:
+        record = repo.splits.get(
+            dataset, split, version=version, **_read_env_kwargs(repo, repo.splits, "get", env)
+        )
+    except Exception as exc:  # noqa: BLE001
+        raise _fail(
+            f"dataset {dataset} version {version} split {split}: query failed: {_reason(exc)}",
+            f"Check the dataset name and permission: ap dataset get {dataset}",
+        ) from exc
+    detail = _model_dict(record) if record is not None else None
+    return detail if detail is not None and _version_value(detail.get("version")) == version else None
+
+
+def _versioned_splits(
+    dataset: str, version: str, *, stage: str, environment: Optional[str] = None
+) -> list[dict]:
+    """读**指定 version**的 split——走 SDK ``repo.splits``(recordsvc)。
+
+    与 ``_unversioned_splits`` 同源:version 文档不内嵌 ``splits[]``(服务端只给
+    ``split_count`` 聚合,split 记录由 recordsvc 的 ``/datasets/splits`` 承载),
+    SDK ``splits.list(version=...)`` 是唯一正确读法,且自带存量 version_first
+    内嵌投影的 legacy 回退。
+    """
+    from .irepo_sdk import _reason
+
+    env = _environment(environment)
+    repo = _dataset_repo()
+    try:
+        records: list[dict] = []
+        page = 1
+        while True:
+            result = repo.splits.list(
+                dataset,
+                version=version,
+                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)
+                # 与 ``_versioned_split`` 同口径:只收 version 匹配的记录(服务端
+                # exact scope 保证;legacy 投影与 OSS 发现也会带 version)。
+                if _version_value(record.get("version")) == 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} version {version}: {stage} failed: {_reason(exc)}",
+            f"Check the version name: ap dataset version get {version} --dataset {dataset}",
+        ) from exc
+    return records
+
+
 def _split_records(detail: dict) -> list[dict]:
     """version 文档内嵌的 ``splits[]``(设计 §4.3:split 没有独立资源)。"""
     splits = detail.get("splits")
@@ -724,12 +795,12 @@ def _split_names(detail: dict) -> list[str]:
     return names
 
 
-def _dataset_repo() -> "Repo":
+def _dataset_repo(*, request_timeout: float | None = None) -> "Repo":
     """dataset 写路径统一走 InstanceRepo SDK;未装 ``dataset`` extra 时退出 2。"""
     from .irepo_sdk import SdkMissing, load_repo
 
     try:
-        return load_repo()
+        return load_repo(request_timeout=request_timeout)
     except SdkMissing as exc:
         typer.echo(str(exc), err=True)
         raise typer.Exit(2) from exc
@@ -1186,9 +1257,26 @@ def dataset_get(
             "dataset_name": dataset,
             "registered": False,
         }
-        parts = dataset.split("/")
-        if len(parts) == 2 and all(parts):
-            rendered.update(dataset_l1=parts[0], dataset_l2=parts[1])
+        from .dataset_name import (
+            DatasetNameError,
+            DatasetNameUpgradeRequired,
+            parse_dataset_name,
+        )
+
+        try:
+            name = parse_dataset_name(dataset)
+        except DatasetNameUpgradeRequired as exc:
+            raise _fail(
+                f"Failed to query dataset {dataset}: {exc}",
+                "pip install 'ap-client[dataset]' --upgrade",
+                exit_code=2,
+            ) from exc
+        except DatasetNameError:
+            # 非规范名:不凭空发明 level 字段(与历史行为一致)。
+            pass
+        else:
+            rendered["dataset_l1"] = name.l1
+            rendered["dataset_l2"] = name.l2
     else:
         rendered = _registered_dict(detail)
     _emit_detail(rendered, output_format, order=_DATASET_DETAIL_ORDER, always=("status",))
@@ -1197,7 +1285,10 @@ def dataset_get(
 
 
 def dataset_create(
-    dataset: str = typer.Argument(..., help="Dataset name (e.g. alibaba/my-bench)"),
+    dataset: str = typer.Argument(
+        ..., help="Dataset name: L1, L1/L2, or a deeper path "
+        "(e.g. my-bench, alibaba/my-bench, or gdpval/synthetic/my-bench)"
+    ),
     benchmark: str = typer.Option(..., "--benchmark", help="Benchmark name or source_id"),
     description: Optional[str] = typer.Option(None, "--description", help="Dataset description"),
     visibility: str = typer.Option(
@@ -1216,20 +1307,32 @@ def dataset_create(
 
     from instance_repo.models import DatasetSeries
 
+    from .dataset_name import (
+        DatasetNameError,
+        DatasetNameUpgradeRequired,
+        parse_dataset_name,
+    )
     from .irepo_sdk import _reason
 
-    parts = dataset.split("/")
-    if len(parts) != 2 or not all(parts):
+    try:
+        name = parse_dataset_name(dataset)
+    except DatasetNameUpgradeRequired as exc:
         raise _fail(
-            f"Failed to create dataset {dataset}: the name must be two segments <team>/<name>",
-            "e.g. your-team/my-bench",
+            f"Failed to create dataset {dataset}: {exc}",
+            "pip install 'ap-client[dataset]' --upgrade",
+            exit_code=2,
+        ) from exc
+    except DatasetNameError:
+        raise _fail(
+            f"Failed to create dataset {dataset}: the name must be one or more "
+            "canonical path segments",
+            "e.g. my-bench, your-team/my-bench, or gdpval/synthetic/my-bench",
             exit_code=2,
         )
-    l1, l2 = parts
     series = DatasetSeries(
         dataset_name=dataset,
-        dataset_l1=l1,
-        dataset_l2=l2,
+        dataset_l1=name.l1,
+        dataset_l2=name.l2,
         benchmark_id=benchmark_id,
         visibility=resolved_visibility,
         description=description or None,
@@ -1813,15 +1916,10 @@ def dataset_split_list(
     resolved_run_type = _check_choice(run_type, _RUN_TYPES, "--run-type") if run_type else ""
 
     if resolved_version:
-        detail = _fetch_version(
-            dataset,
-            resolved_version,
-            stage="split query",
-            environment=environment,
-            metadata_model=_VERSION_SPLIT_METADATA_MODEL,
+        records = _versioned_splits(
+            dataset, resolved_version, stage="split query", environment=environment
         )
-        records = _split_records(detail)
-        rows = [_split_row(record, detail) for record in records]
+        rows = [_split_row(record, {}) for record in records]
     else:
         records = _unversioned_splits(dataset, stage="split query", environment=environment)
         rows = [_split_row(record, {}) for record in records]
@@ -1848,22 +1946,26 @@ def dataset_split_get(
     resolved_version = _version_value(version)
 
     if resolved_version:
-        detail = _fetch_version(
-            dataset,
-            resolved_version,
-            stage="split query",
-            environment=environment,
-            metadata_model=_VERSION_SPLIT_METADATA_MODEL,
+        record = _versioned_split(
+            dataset, resolved_version, split, environment=environment
+        )
+        if record is not None:
+            payload = dict(record)
+            payload.setdefault("dataset", dataset)
+            payload.setdefault("version", resolved_version)
+            payload.setdefault("registered", True)
+            _emit_detail(payload, output_format)
+            return
+        known = (
+            ", ".join(
+                _split_names_of(
+                    _versioned_splits(
+                        dataset, resolved_version, stage="split query", environment=environment
+                    )
+                )
+            )
+            or "<none>"
         )
-        for record in _split_records(detail):
-            if str(record.get("name") or "") == split:
-                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>"
     else:
         record = _unversioned_split(dataset, split, environment=environment)
         if record is not None:
@@ -1920,71 +2022,40 @@ def dataset_split_create(
             exit_code=2,
         )
 
-    detail = _fetch_version(
-        dataset,
-        resolved_version,
-        stage="split create precheck",
-        environment=environment,
-        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
-    )
-
-    existing = _split_names(detail)
-    if split in existing:
+    # 版本化创建走独立 Split API（POST /datasets/splits），与 split-first 服务端
+    # 契约对齐——旧 Version PATCH（splits 全量替换 / split_run_types）已被服务端
+    # 拒绝（"split-first Version group updates are not supported"）。
+    env = _environment(environment)
+    existing = _versioned_split(dataset, resolved_version, split, environment=environment)
+    if existing is not None:
         # 幂等:已存在同名 split(设计 §4.3)。
-        for record in _split_records(detail):
-            if str(record.get("name") or "") == split:
-                payload = dict(record)
-                payload.setdefault("dataset", dataset)
-                payload.setdefault("version", resolved_version)
-                payload["created"] = False
-                _emit_detail(payload, output_format)
-                return
-        _emit_detail(
-            {"dataset": dataset, "version": resolved_version, "split": split, "created": False},
-            output_format,
-        )
+        payload = dict(existing)
+        payload.setdefault("dataset", dataset)
+        payload.setdefault("version", resolved_version)
+        payload["created"] = False
+        _emit_detail(payload, output_format)
         return
 
-    # ① splits 全量 PATCH(现有 ∪ 新增)。
-    names = existing + [split]
-    _patch_version(
-        dataset,
-        resolved_version,
-        {"splits": names},
-        stage="split create",
-        environment=environment,
-        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
-    )
+    from .instance_commands import _sdk_read_kwargs
+    from .irepo_sdk import _reason
 
-    # ② run_type 只能第二次 PATCH:服务端 splits 与 split_run_types 互斥。
+    repo = _dataset_repo()
+    create_kwargs = _sdk_read_kwargs(repo.splits, "create", environment=env, metadata_model="")
     if resolved_run_type:
-        retry = (
-            f"ap dataset split update {split} --dataset {dataset} --run-type {resolved_run_type}"
-        )
-        if resolved_version:
-            retry += f" --version {resolved_version}"
-        _patch_version(
-            dataset,
-            resolved_version,
-            {"split_run_types": [{"name": split, "run_type": resolved_run_type}]},
-            stage=f"split {split} set run_type",
-            # 第一段 PATCH 已建出 split,失败后的恢复动作是补打 run_type,不是重跑 create。
-            fallback_hint=f"split {split} was created but run_type is not set; set it now: {retry}",
-            environment=environment,
-            metadata_model=_VERSION_SPLIT_METADATA_MODEL,
-        )
-
-    _emit_detail(
-        {
-            "dataset": dataset,
-            "version": resolved_version,
-            "split": split,
-            "run_type": resolved_run_type,
-            "splits": names,
-            "created": True,
-        },
-        output_format,
-    )
+        create_kwargs["run_type"] = resolved_run_type
+    try:
+        record = repo.splits.create(dataset, split, version=resolved_version, **create_kwargs)
+    except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
+        raise _fail(
+            f"Failed to create split {split} of dataset {dataset} version {resolved_version}: {_reason(exc)}",
+            "Check the version name and write permission, then retry",
+        ) from exc
+    payload = _model_dict(record) if record is not None else {}
+    payload.setdefault("dataset", dataset)
+    payload.setdefault("version", resolved_version)
+    payload.setdefault("split", split)
+    payload["created"] = True
+    _emit_detail(payload, output_format)
 
 
 @dataset_split_app.command("update")
@@ -2064,31 +2135,48 @@ def dataset_split_update(
         )
         return
 
-    detail = _fetch_version(
-        dataset,
-        resolved_version,
-        stage="split update precheck",
-        environment=environment,
-        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
-    )
-
-    if split not in _split_names(detail):
-        known = ", ".join(_split_names(detail)) or "<none>"
-        hint = f"Create it first: ap dataset split create {split} --dataset {dataset} (existing: {known})"
+    # 版本化更新走独立 Split API（PATCH /datasets/splits/detail），预检用精确
+    # split 身份（splits.get with version）——旧实现查 Version 内嵌 splits 再
+    # PATCH Version，与独立 Split 记录不匹配，导致"已存在却报 not found"。
+    env = _environment(environment)
+    if env == "pre":
+        raise _fail(
+            f"Failed to update split {split} of dataset {dataset}: split records can only be changed in the online environment",
+            "PATCH on split records only supports online; drop --environment pre",
+            exit_code=2,
+        )
+    record = _versioned_split(dataset, resolved_version, split, environment=environment)
+    if record is None:
+        known = (
+            ", ".join(
+                _split_names_of(
+                    _versioned_splits(
+                        dataset, resolved_version, stage="split update precheck",
+                        environment=environment,
+                    )
+                )
+            )
+            or "<none>"
+        )
         raise _fail(
             f"dataset {dataset} version {_version_label(resolved_version)} split {split}: "
             f"update failed: not found",
-            hint,
+            f"Create it first: ap dataset split create {split} --dataset {dataset} "
+            f"--version {resolved_version} (existing: {known})",
         )
 
-    _patch_version(
-        dataset,
-        resolved_version,
-        {"split_run_types": [{"name": split, "run_type": resolved_run_type}]},
-        stage="split update",
-        environment=environment,
-        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
-    )
+    from .instance_commands import _sdk_read_kwargs
+    from .irepo_sdk import _reason
+
+    repo = _dataset_repo()
+    update_kwargs = _sdk_read_kwargs(repo.splits, "update", environment=env, metadata_model="")
+    try:
+        repo.splits.update(dataset, split, version=resolved_version, run_type=resolved_run_type, **update_kwargs)
+    except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
+        raise _fail(
+            f"Failed to update split {split} of dataset {dataset} version {resolved_version}: {_reason(exc)}",
+            "Write permission on this dataset is required; check the split name and the online environment, then retry",
+        ) from exc
     _emit_detail(
         {
             "dataset": dataset,

ap_client-0.7.0.dev5/ap_client/dataset_name.py

@@ -0,0 +1,104 @@
+"""DatasetName 解析 Adapter:唯一入口委托给已安装的 InstanceRepo SDK。
+
+AP CLI 不维护第三套 dataset 名解析:``instance_repo.paths.DatasetName`` 是客户端
+路径契约的唯一事实源(单段 ``A`` / 两段 ``A/B`` / 多段树形 ``A/B/C``,与
+apiserver 的 namespace guard 及 conformance 契约对齐)。SDK 缺失或过旧(没有
+``DatasetName.parse`` 能力)时,给出明确的升级提示,不静默降级、不本地重写解析规则。
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any
+
+__all__ = [
+    "DatasetNameError",
+    "DatasetNameUpgradeRequired",
+    "parse_dataset_name",
+]
+
+#: SDK 缺失/无 DatasetName 能力时的升级提示(与 irepo_sdk 的 SdkMissing 同范式)。
+_UPGRADE_HINT = (
+    "The installed instance-repo SDK does not provide DatasetName parsing "
+    "(single-segment L1 dataset names need it).\n"
+    "Install it with: pip install 'ap-client[dataset]' --upgrade"
+)
+
+#: 多段(3+)名能力的首个 SDK 版本。旧 SDK(如 1.4.0)有 parse 但只认 1-2 段,
+#: 对多段名会抛"one or two canonical segments"——此时应提示升级而非报名称非法。
+_MULTI_LEVEL_SDK_VERSION = (1, 4, 1)
+
+
+def _sdk_supports_multi_level() -> bool:
+    """已安装 instance-repo 是否支持多段数据集名(>= 1.4.1)。版本不可读时保守视为不支持。"""
+    try:
+        from importlib.metadata import version
+
+        installed = version("instance-repo")
+    except Exception:  # noqa: BLE001 - 元数据缺失与旧 SDK 同等对待
+        return False
+    match = re.match(r"(\d+)\.(\d+)\.(\d+)", str(installed))
+    if not match:
+        return False
+    return tuple(int(part) for part in match.groups()) >= _MULTI_LEVEL_SDK_VERSION
+
+
+def _is_structurally_valid_multi_level(value: str) -> bool:
+    """值是否为"新 SDK 会接受"的 3+ 段名——即每个段都合法。
+
+    旧 SDK 对非法名(空段 a//b、非法字符 a*b)与多段名报同一文案,不能只按
+    段数判断:升级 SDK 也修不好空段/非法字符,必须保留原始校验错误。
+    这里保守复刻 SDK 的非法段规则作为 gate,只放行结构上合法的多段名。
+    """
+    parts = value.split("/")
+    if len(parts) < 3 or any(not part for part in parts):
+        return False
+    for part in parts:
+        if (
+            part in {".", ".."}
+            or "\\" in part
+            or "*" in part
+            or "?" in part
+            or any(unicodedata.category(char) == "Cc" for char in part)
+        ):
+            return False
+    return True
+
+
+class DatasetNameUpgradeRequired(RuntimeError):
+    """已安装的 instance-repo SDK 缺少 DatasetName 能力,必须升级。"""
+
+
+class DatasetNameError(ValueError):
+    """Dataset 名不符合 IR DatasetName 契约(单段或两段、无非法段)。"""
+
+
+def parse_dataset_name(value: str) -> Any:
+    """Parse ``value`` through the installed IR ``DatasetName`` capability.
+
+    Returns the SDK ``DatasetName`` (``canonical`` / ``l1`` / ``l2`` /
+    ``segments`` / ``leaf``)。Raises :class:`DatasetNameUpgradeRequired` when the
+    installed SDK lacks the capability (包括只认 1-2 段的旧 SDK 拒绝多段名);
+    raises :class:`DatasetNameError` when the value is not a valid name.
+    """
+    try:
+        from instance_repo.paths import DatasetName
+    except ImportError as exc:
+        raise DatasetNameUpgradeRequired(_UPGRADE_HINT) from exc
+    parse = getattr(DatasetName, "parse", None)
+    if not callable(parse):
+        raise DatasetNameUpgradeRequired(_UPGRADE_HINT)
+    try:
+        return parse(value)
+    except Exception as exc:  # noqa: BLE001 - SDK 校验失败统一转成 CLI 契约
+        # 旧 SDK(1.4.0 及更早)只认 1-2 段:结构上合法的多段名被拒时给出
+        # 升级提示。非法名(空段/非法字符)无论新旧 SDK 都拒绝,保留原始
+        # 校验错误为 DatasetNameError——升级修不好这类名称。
+        if (
+            isinstance(value, str)
+            and _is_structurally_valid_multi_level(value)
+            and not _sdk_supports_multi_level()
+        ):
+            raise DatasetNameUpgradeRequired(_UPGRADE_HINT) from exc
+        raise DatasetNameError(str(exc)) from exc