ap-client 0.3.1.dev1__tar.gz → 0.3.1.dev2__tar.gz

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.3.1.dev1
+Version: 0.3.1.dev2
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/ap_client/api.py

@@ -294,24 +294,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)``.
 

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/ap_client/cli.py

@@ -815,26 +815,45 @@ def _print_json_block(data: Any) -> None:
     typer.echo(json.dumps(data, ensure_ascii=False, indent=2))
 
 
+def _format_nested_detail(value: Any) -> str:
+    """Nested dict/list for detail views: compact one-liner, pretty JSON when long.
+
+    A detail view must not silently drop data - the manifest in ``ap instance
+    get`` used to be cut mid-JSON by the one-liner preview.
+    """
+    compact = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if len(compact) <= _PLAIN_VALUE_PREVIEW:
+        return compact
+    return json.dumps(value, ensure_ascii=False, indent=2)
+
+
 def _print_detail(data: object) -> None:
     """Render a single object as an aligned key/value detail view.
 
     Top-level scalars become key/value rows (``image`` fields shortened); nested
-    dict/list fields are shown as compact one-liners. Falls back to JSON for
+    dict/list fields are shown as compact one-liners, or pretty-printed across
+    multiple lines when the one-liner would not fit. Falls back to JSON for
     non-dict payloads.
     """
     if not isinstance(data, dict):
         _print_json(data)
         return
-    scalar_rows: list[tuple[str, Any]] = []
-    nested_rows: list[tuple[str, Any]] = []
+    rows: list[tuple[str, str]] = []
     for key, value in data.items():
         if isinstance(value, (dict, list)):
-            nested_rows.append((key, value))
+            rows.append((key, _format_nested_detail(value)))
         elif key == "image" and isinstance(value, str):
-            scalar_rows.append((key, _shorten_image(value)))
+            rows.append((key, _shorten_image(value)))
+        elif value is None:
+            continue
         else:
-            scalar_rows.append((key, value))
-    _print_key_values(scalar_rows + nested_rows, skip_empty=False)
+            rows.append((key, _format_plain_value(value, max_len=0)))
+    width = max((len(label) for label, _text in rows), default=0)
+    indent = " " * (width + 4)
+    for label, text in rows:
+        if "\n" in text:
+            text = text.replace("\n", f"\n{indent}")
+        typer.echo(f"  {label.ljust(width)}: {text}")
 
 
 def _print_template_get_plain(t: dict) -> None:
@@ -944,7 +963,7 @@ def _print_field_value(value: Any, output_format: str) -> None:
     _print_formatted(value, "json" if output_format == "plain" else output_format)
 
 
-def _format_plain_value(value: Any) -> str:
+def _format_plain_value(value: Any, *, max_len: int = _PLAIN_VALUE_PREVIEW) -> str:
     if value is None:
         return ""
     if isinstance(value, (dict, list)):
@@ -952,9 +971,9 @@ def _format_plain_value(value: Any) -> str:
     else:
         text = str(value)
     text = text.replace("\r", "\\r").replace("\n", "\\n")
-    if len(text) <= _PLAIN_VALUE_PREVIEW:
+    if not max_len or len(text) <= max_len:
         return text
-    return f"{text[: _PLAIN_VALUE_PREVIEW - 3]}..."
+    return f"{text[: max_len - 3]}..."
 
 
 def _print_key_values(rows: list[tuple[str, Any]], *, skip_empty: bool = True) -> None:

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/ap_client/dataset_commands.py

@@ -17,6 +17,8 @@ import typer
 if TYPE_CHECKING:  # pragma: no cover - 仅用于类型标注,运行时不 import
     from datetime import datetime
 
+    from instance_repo import Repo
+
 __all__ = [
     "dataset_version_app",
     "dataset_split_app",
@@ -420,7 +422,7 @@ _DATASET_CODE_HINTS: dict[int, str] = {
 }
 
 
-def _resolve_benchmark_id(repo: Any, value: str) -> str:
+def _resolve_benchmark_id(repo: "Repo", value: str) -> str:
     """``--benchmark`` 接受名称或 ``source_id``,统一解析成 ``source_id``(设计 §9)。
 
     走 SDK ``benchmarks``:先按 source_id 点查,再按名称模糊搜一遍精确比对
@@ -539,7 +541,10 @@ def _fetch_version(
         detail = repo.versions.get(dataset, version, **_env_kwargs(env))
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         if version:
-            hint = f"确认版本名：ap dataset version list --dataset {dataset}"
+            hint = (
+                f"确认版本名：ap dataset version list --dataset {dataset}"
+                ";版本也可能在另一个元数据 environment,加 --environment online/pre 重试"
+            )
         else:
             hint = f"{_NO_VERSION_NOTE};要操作具体版本请加 --version <version>"
         raise _fail(
@@ -634,7 +639,7 @@ def _split_names(detail: dict) -> list[str]:
     return names
 
 
-def _dataset_repo() -> Any:
+def _dataset_repo() -> "Repo":
     """dataset 写路径统一走 InstanceRepo SDK;未装 ``dataset`` extra 时退出 2。"""
     from .irepo_sdk import SdkMissing, load_repo
 
@@ -645,6 +650,47 @@ def _dataset_repo() -> Any:
         raise typer.Exit(2) from exc
 
 
+def _dataset_available_envs(repo: "Repo", dataset: str) -> list[str]:
+    """dataset 元数据分布的 environment 候选;详情读不到时退回固定枚举。"""
+    envs: list[str] = []
+    try:
+        detail = repo.datasets.get_detail(dataset)
+    except Exception:  # noqa: BLE001 - 引导信息尽力而为,不打断主流程
+        detail = None
+    raw = detail.get("available_envs") if isinstance(detail, dict) else None
+    if isinstance(raw, list):
+        envs = [str(env).strip() for env in raw if str(env).strip()]
+    from .irepo_sdk import DATASET_ENVIRONMENTS
+
+    for fallback in DATASET_ENVIRONMENTS:
+        if fallback not in envs:
+            envs.append(fallback)
+    return envs
+
+
+def _note_environment_distribution(repo: "Repo", dataset: str, probe, *, what: str) -> None:
+    """空结果时逐 environment 探测数据分布,引导用户换 ``--environment`` 重试。
+
+    ``probe(env)`` 返回该 environment 下的条数;读失败按 -1 计。全部为空/读失败
+    (dataset 真没数据)时不提示,避免噪声。
+    """
+    counts: list[tuple[str, int]] = []
+    for env in _dataset_available_envs(repo, dataset):
+        try:
+            counts.append((env, int(probe(env))))
+        except Exception:  # noqa: BLE001 - 旧 SDK 不接受 environment 等情况
+            counts.append((env, -1))
+    if not any(count > 0 for _env, count in counts):
+        return
+    shown = ", ".join(f"{env}={count if count >= 0 else '读失败'}" for env, count in counts)
+    with_data = [env for env, count in counts if count > 0]
+    suggest = with_data[0] if len(with_data) == 1 else f"<{'/'.join(with_data)}>"
+    _note(
+        f"{what}在本次查询的 environment 下没有数据;各 environment 探测:{shown}。"
+        f"数据可能在另一个元数据 environment,加 --environment {suggest} 重试"
+    )
+
+
 def _patch_version(
     dataset: str,
     version: str,
@@ -1024,6 +1070,43 @@ def dataset_list(
         _print_formatted(payload, output_format)
 
 
+#: ``dataset get`` 尾部 environment 摘要表的列。
+_ENVIRONMENT_SUMMARY_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("environment", "ENVIRONMENT"),
+    ("versions", "VERSIONS"),
+    ("splits", "SPLITS"),
+    ("latest_version", "LATEST_VERSION"),
+)
+
+
+def _print_dataset_environments(repo: "Repo", dataset: str, detail: dict) -> None:
+    """``dataset get`` 尾部按 environment 汇总 version/split,告诉用户该去哪个 env 指定。
+
+    仅人读视图(plain/table)追加;``json``/``yaml`` 恒为服务端原样。单个 env 读失败
+    (旧 SDK 不接受 environment、权限差异)显示 ``?``,不影响主输出。
+    """
+    envs = [str(env).strip() for env in detail.get("available_envs") or [] if str(env).strip()]
+    if not envs:
+        return
+    rows: list[dict] = []
+    for env in envs:
+        try:
+            env_detail = _model_dict(repo.datasets.get_detail(dataset, environment=env))
+        except Exception:  # noqa: BLE001 - 摘要尽力而为
+            rows.append({"environment": env, "versions": "?", "splits": "?", "latest_version": "?"})
+            continue
+        rows.append(
+            {
+                "environment": env,
+                "versions": env_detail.get("version_count", ""),
+                "splits": env_detail.get("split_count", ""),
+                "latest_version": env_detail.get("latest_version") or "",
+            }
+        )
+    typer.echo("\nEnvironments (add --environment <env> to target one)")
+    _print_table(rows, _ENVIRONMENT_SUMMARY_COLUMNS, "plain")
+
+
 def dataset_get(
     dataset: str = typer.Argument(..., help="Dataset name"),
     environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
@@ -1042,12 +1125,10 @@ def dataset_get(
             f"dataset {dataset} 查询失败：{_reason(exc)}",
             f"确认 dataset 名称：ap dataset list --query {dataset}",
         ) from exc
-    _emit_detail(
-        _model_dict(detail),
-        output_format,
-        order=_DATASET_DETAIL_ORDER,
-        always=("status",),
-    )
+    rendered = _model_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)
 
 
 def dataset_create(
@@ -1534,6 +1615,29 @@ def dataset_version_list(
         ) from exc
 
     records = [_model_dict(record) for record in (getattr(result, "items", None) or [])]
+    if not records:
+        # 空结果常见根因是元数据 environment 不匹配(version 落在另一个 env),
+        # 探测一遍并引导切换,而不是只回一张空表。
+        _note_environment_distribution(
+            repo,
+            dataset,
+            lambda env: (
+                _pagination_total(
+                    _pagination_envelope(
+                        repo.versions.list_paged(
+                            dataset,
+                            status=resolved_status or None,
+                            page=1,
+                            page_size=1,
+                            environment=env,
+                        )
+                    ),
+                    fallback=0,
+                )
+                or 0
+            ),
+            what="version",
+        )
     if records and all(
         "split_count" not in record and "instance_count" not in record for record in records
     ):
@@ -1651,6 +1755,27 @@ def dataset_split_list(
         rows = [_split_row(record, {}) for record in records]
     if resolved_run_type:
         rows = [row for row in rows if str(row["run_type"]).lower() == resolved_run_type]
+    if not rows and not resolved_run_type:
+        # 空结果常见根因是元数据 environment 不匹配,探测一遍并引导切换。
+        probe_repo = _dataset_repo()
+        if resolved_version:
+
+            def _probe(env: str) -> int:
+                try:
+                    detail = probe_repo.versions.get(dataset, resolved_version, environment=env)
+                except Exception:  # noqa: BLE001 - 该 env 没有这个版本
+                    return -1
+                return len(_split_records(_model_dict(detail)))
+
+        else:
+
+            def _probe(env: str) -> int:
+                page = probe_repo.splits.list(
+                    dataset, version_scope="unversioned", page_size=1, environment=env
+                )
+                return _pagination_total(_pagination_envelope(page), fallback=0) or 0
+
+        _note_environment_distribution(probe_repo, dataset, _probe, what="split")
     _emit(
         {"dataset": dataset, "version": resolved_version, "splits": rows},
         rows,
@@ -1878,8 +2003,6 @@ def dataset_split_update(
     if split not in _split_names(detail):
         known = ", ".join(_split_names(detail)) or "<无>"
         hint = f"先创建：ap dataset split create {split} --dataset {dataset}(现有：{known})"
-        if not resolved_version:
-            hint = f"{hint}；{_NO_VERSION_NOTE}"
         raise _fail(
             f"dataset {dataset} 版本 {_version_label(resolved_version)} split {split} "
             f"更新失败：不存在",

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/ap_client/instance_commands.py

@@ -237,14 +237,18 @@ def _sdk_read_kwargs(sdk_obj: Any, method: str, *, environment: str, metadata_mo
                 accepted.add(name)
 
     kwargs: dict[str, str] = {}
+    dropped: list[str] = []
     for key, value in (("environment", environment), ("metadata_model", metadata_model)):
         # 空值不下发:CLI 不替 SDK 决定 metadata_model(见 dataset_commands._metadata_model)。
         if key in accepted and value:
             kwargs[key] = value
-    if "environment" not in accepted:
+        elif value:
+            dropped.append(key)
+    if dropped:
+        # 只有真正丢弃了调用方给的值才提示;无条件打印会暗示"想指定却被忽略"。
         _note(
-            "已安装的 instance-repo 不支持按调用指定 environment/metadata_model,"
-            "本次按 profile 派生值读取;需要精确指定请升级到 1.1.0 及以上"
+            "已安装的 instance-repo 不支持按调用指定 "
+            f"{'/'.join(dropped)},本次按 profile 派生值读取;需要精确指定请升级到 1.1.0 及以上"
         )
     return kwargs
 
@@ -467,9 +471,12 @@ def instance_get(
     _emit_detail(_instance_record(record), output_format)
 
 
+def _confirm_version_autocreate(repo, dataset: str, version: str, split: str, *, yes: bool) -> None:
+    """version 不存在时 push 会触发服务端自动创建;要求二次确认(可 ``-y/--yes`` 跳过)。
 
-def _confirm_version_autocreate(dataset: str, version: str, split: str, *, yes: bool) -> None:
-    """version 不存在时 push 会触发服务端自动创建;要求二次确认(可 ``-y/--yes`` 跳过)。"""
+    ``repo`` 由调用方构造并复用:``Repo.__init__`` 会做一次 best-effort 的
+    repo-config 自动发现(HTTP),确认与推送共用一个实例,不重复触网。
+    """
     import sys
 
     from .dataset_commands import _env_kwargs, _environment, _version_label
@@ -478,7 +485,6 @@ def _confirm_version_autocreate(dataset: str, version: str, split: str, *, yes:
     if not str(version or "").strip():
         # 无版本空间:没有"版本会被自动创建"这回事(数据面由 ingest 处理)。
         return
-    repo = _load_repo_or_exit()
     try:
         repo.versions.get(dataset, version, **_env_kwargs(_environment(None)))
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
@@ -547,10 +553,9 @@ def instance_push(
     # ② 版本不存在时 push 会在服务端自动创建;先确认,避免误建。
     #   (split 已发布不可写由**服务端**裁决——pre 环境里 ingest 产出的 split 记录状态
     #    就是 published,客户端按它预判会把正常的二次上传全拦掉。)
-    _confirm_version_autocreate(dataset, resolved, split, yes=yes)
-
-    # ③ 数据面推送。
+    # ③ 数据面推送(repo 只构造一次,确认与推送复用,见 _confirm_version_autocreate)。
     repo = _load_repo_or_exit()
+    _confirm_version_autocreate(repo, dataset, resolved, split, yes=yes)
     pushed: list[dict] = []
     failed: list[dict] = []
     unconfirmed: list[str] = []
@@ -603,7 +608,13 @@ def instance_push(
                 exc, what=f"dataset {dataset} 的 {len(targets)} 个 instance", stage="上传"
             )
         else:
-            for path, result in zip(targets, list(results_many or [])):
+            results_list = list(results_many or [])
+            if len(results_list) != len(targets):
+                _note(
+                    f"SDK 返回了 {len(results_list)}/{len(targets)} 个上传结果,摘要可能不完整;"
+                    f"用 ap instance list --dataset {dataset} --split {split} 核对实际内容"
+                )
+            for path, result in zip(targets, results_list):
                 pushed.append(_push_row(path, result))
 
     _print_push_summary(dataset, resolved, split, pushed, failed, unconfirmed, output_format)

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/ap_client/irepo_sdk.py

@@ -41,7 +41,13 @@ from .config import Config, _parse_bool
 if TYPE_CHECKING:  # pragma: no cover - 仅供类型检查,运行时不 import SDK
     from instance_repo import Repo
 
-__all__ = ["SdkMissing", "is_already_satisfied", "load_repo", "sdk_error_exit"]
+__all__ = [
+    "SdkMissing",
+    "is_already_satisfied",
+    "load_repo",
+    "sdk_error_exit",
+    "update_version_detail",
+]
 
 #: 数据集元数据的环境枚举(服务端 ``dataset environment``)。
 DATASET_ENVIRONMENTS = ("online", "pre")
@@ -57,7 +63,7 @@ _INSTALL_HINT = (
 _LEGACY_SDK_NOTE = (
     "note: installed instance-repo does not accept Repo(api_base=/cluster=); "
     "falling back to INSTANCEREPO_* environment injection. "
-    "Upgrade with: pip install -U 'instance-repo[oss]>=1.0.9' "
+    "Upgrade with: pip install -U 'instance-repo[oss]>=1.1.0' "
     "for cluster<->storage_env validation and symmetric read/write paths."
 )
 
@@ -210,7 +216,7 @@ _BIZ_CODE_RULES: dict[int, tuple[str, int]] = {
     ),
     94018: ("当前角色只读,写操作需要 writer 角色;让 admin 执行 ap dataset access grant", 1),
     94019: ("dataset 标识冲突：检查 --dataset 的取值是否与已有 dataset 重名", 1),
-    94020: ("请求未带 dataset 标识(SDK 过旧),升级：pip install -U 'instance-repo[oss]>=1.0.9'", 1),
+    94020: ("请求未带 dataset 标识(SDK 过旧),升级：pip install -U 'instance-repo[oss]>=1.1.0'", 1),
     94021: ("该 dataset 不存在,先执行：ap dataset create <dataset> --benchmark <b>", 1),
     94022: (
         "无该用户存储空间的授权,让空间主人执行：ap fs access grant --user <你的工号> --role reader",
@@ -232,7 +238,7 @@ _CODE_RULES: dict[str, tuple[str, int]] = {
     "E_DIGEST_MISMATCH": ("内容校验失败,重新拉取或重新打包该 instance 后再试", 1),
     "E_IMMUTABLE": ("已发布的版本不可修改,创建新版本再操作", 1),
     "E_FORBIDDEN": ("当前身份无权执行该操作,确认 AP_API_KEY 与 dataset 角色", 1),
-    "E_OWNER_REF_MISSING": ("缺少上游来源引用,升级：pip install -U 'instance-repo[oss]>=1.0.9'", 1),
+    "E_OWNER_REF_MISSING": ("缺少上游来源引用,升级：pip install -U 'instance-repo[oss]>=1.1.0'", 1),
     "E_LAYOUT": ("instance 目录结构不合规,先执行 ap instance validate <path> 定位问题", 1),
     "E_SCHEMA": ("instance 元数据不符合 schema,先执行 ap instance validate <path> 定位问题", 1),
     "E_CRED_EXPIRED": ("临时凭据已过期,重试该命令即可重新换取", 1),

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/ap_client/split_publish.py

@@ -44,7 +44,10 @@ def dataset_split_publish(
     if not yes:
         if not sys.stdin.isatty():
             raise _fail("非交互发布需要确认", "加 --yes 确认将该 split 发布到 online", 2)
-        if not typer.confirm(f"Publish {dataset}/{resolved_version}/{split} to online?"):
+        target = (
+            f"{dataset}/{resolved_version}/{split}" if resolved_version else f"{dataset}/{split}"
+        )
+        if not typer.confirm(f"Publish {target} to online?"):
             raise _fail("发布已取消,未提交工作流", "确认后重跑", 1)
 
     try:

{ap_client-0.3.1.dev1 → ap_client-0.3.1.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.3.1.dev1"
+version = "0.3.1.dev2"
 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"