ap-client 0.5.3.dev7__tar.gz → 0.5.3.dev8__tar.gz

{ap_client-0.5.3.dev7 → ap_client-0.5.3.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.5.3.dev7
+Version: 0.5.3.dev8
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0.0

{ap_client-0.5.3.dev7 → ap_client-0.5.3.dev8}/ap_client/instance_commands.py

@@ -1,23 +1,8 @@
-"""``ap instance`` 命令族(实现设计 §4.4)。
+"""Instance metadata, directory browsing, transfer and source-hash commands.
 
-``ap instance``(设计 §4.4):
-
-* ``validate <path>...`` —— ``repo.instances.validate``,纯本地,不发远端请求;
-* ``list`` / ``get`` —— **控制面**,走 ``api.list_dataset_series_instances`` /
-  ``api.get_dataset_series_instance``,``--split`` 必填,不需要 SDK;
-* ``push`` / ``pull`` —— 数据面,走 ``repo.instances.push_many`` / ``pull``。
-
-分层约束(设计 §2):``instance list/get`` 属控制面,必须在没装
-``ap-client[dataset]`` 时照常工作——所以 SDK 只能在**需要它的那几个命令函数
-内部**懒加载:
-
-    from .irepo_sdk import SdkMissing, load_repo, sdk_error_exit
-
-``SdkMissing`` → 打印 ``str(exc)`` 到 stderr 并 ``typer.Exit(2)``(缺依赖是使用
-错误);SDK 抛出的业务异常 → ``sdk_error_exit(exc, what=..., stage=...)``。
-
-渲染与退出码沿用 ``ap_client.cli`` 的既有 helper,同样函数内部 import 以避免与
-``cli`` 循环依赖。默认列:``INSTANCE SPLIT VERSION DIGEST UPDATED_AT REGISTERED``。
+SDK imports are lazy so help remains available without Dataset support.
+Local validation and hashing do not construct a Repo or contact AP.
+Remote operations share SDK configuration and the CLI output/error contract.
 """
 
 from __future__ import annotations
@@ -63,6 +48,7 @@ _VERSION_HELP = (
 )
 
 
+from . import instance_options  # noqa: E402
 from .dataset_commands import (  # noqa: E402
     _ENVIRONMENT_HELP,
     _METADATA_MODEL_HELP,
@@ -124,6 +110,22 @@ def _fail(message: str, hint: str, exit_code: int = 1) -> "typer.Exit":
     return typer.Exit(exit_code)
 
 
+def _path_value(value: Optional[str]) -> Optional[str]:
+    try:
+        return instance_options.relative_path(value)
+    except ValueError as exc:
+        raise _fail(str(exc), "Use --path solution, --path tests/sealed, or --path .", 2) from exc
+
+
+def _enhanced_options(owner: Any, method: str, options: dict[str, Any]) -> dict[str, Any]:
+    try:
+        return instance_options.sdk_options(owner, method, options)
+    except (TypeError, ValueError) as exc:
+        raise _fail(
+            str(exc), "Upgrade Dataset support: pip install --upgrade 'ap-client[dataset]'", 2
+        ) from exc
+
+
 def _load_repo_or_exit():
     """懒加载 SDK;缺 extra → 安装提示 + 退出码 2(设计 §2)。
 
@@ -464,15 +466,40 @@ def instance_get(
     metadata_model: Optional[str] = typer.Option(
         None, "--metadata-model", help=_METADATA_MODEL_HELP
     ),
+    path: Optional[str] = typer.Option(
+        None,
+        "--path",
+        help="List a subdirectory relative to the instance assets; use '.' for the root",
+    ),
+    page_size: int = typer.Option(
+        100, "--page-size", min=1, max=1000, help="Directory listing page size"
+    ),
+    max_pages: int = typer.Option(50, "--max-pages", min=1, help="Maximum directory listing pages"),
     output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
 ):
-    """Show full instance metadata (SDK-backed)."""
+    """Show instance metadata and root assets; use --path to browse a directory."""
     from .irepo_sdk import _reason
 
     output_format = _fmt(output_format)
+    resolved_path = _path_value(path)
     resolved_version = _version_value(version)
     repo = _load_repo_or_exit()
     env = _environment(environment)
+    if resolved_path is not None:
+        _list_instance_objects(
+            repo,
+            dataset,
+            resolved_version,
+            instance,
+            split,
+            resolved_path,
+            env,
+            _metadata_model_for_split(metadata_model, split=split),
+            page_size,
+            max_pages,
+            output_format,
+        )
+        return
     read_kwargs = _sdk_read_kwargs(
         repo.instances,
         "get",
@@ -498,17 +525,99 @@ def instance_get(
             f"Failed to query instance {instance}: not found",
             f"Check the instance id: ap instance list --dataset {dataset} --split {split}",
         )
-    payload = _instance_record(record)
-    manifest = payload.get("manifest")
-    if output_format in ("json", "yaml") or not isinstance(manifest, list):
-        _emit_detail(payload, output_format)
-        return
-    from .manifest_view import manifest_lines
+    _list_instance_objects(
+        repo,
+        dataset,
+        resolved_version,
+        instance,
+        split,
+        "",
+        env,
+        _metadata_model_for_split(metadata_model, split=split),
+        page_size,
+        max_pages,
+        output_format,
+        metadata=_instance_record(record),
+    )
 
-    _emit_detail({key: value for key, value in payload.items() if key != "manifest"}, output_format)
-    typer.echo()
-    for line in manifest_lines(manifest):
-        typer.echo(line)
+
+def _list_instance_objects(
+    repo: Any,
+    dataset: str,
+    version: str,
+    instance: str,
+    split: str,
+    path: str,
+    environment: str,
+    metadata_model: str,
+    page_size: int,
+    max_pages: int,
+    output_format: str,
+    *,
+    metadata: dict | None = None,
+) -> None:
+    from .irepo_sdk import _reason
+
+    kwargs = _enhanced_options(
+        repo.instances,
+        "list_objects",
+        {
+            "version": version,
+            "path": path,
+            "page_size": page_size,
+            "max_pages": max_pages,
+        },
+    )
+    kwargs.update(
+        _sdk_read_kwargs(
+            repo.instances, "list_objects", environment=environment, metadata_model=metadata_model
+        )
+    )
+    try:
+        result = repo.instances.list_objects(dataset, instance, split=split, **kwargs)
+    except Exception as exc:  # noqa: BLE001
+        raise _fail(
+            f"Failed to list instance {instance} directory {path or '.'}: {_reason(exc)}",
+            "Check the instance, directory, environment and read permission",
+        ) from exc
+    payload = _model_dict(result)
+    payload.update(instance=instance, path=path or ".")
+    rows = [dict(item, type="directory", size_bytes="") for item in payload.get("directories", [])]
+    rows.extend(dict(item, type="file") for item in payload.get("files", []))
+    from .manifest_view import _visible
+
+    rows = [
+        {key: _visible(value) if isinstance(value, str) else value for key, value in row.items()}
+        for row in rows
+    ]
+    if metadata is not None and output_format in ("json", "yaml"):
+        _emit_detail(dict(metadata, objects=payload), output_format)
+    else:
+        if metadata is not None:
+            manifest = metadata.get("manifest")
+            if isinstance(manifest, list):
+                from .manifest_view import manifest_lines
+
+                _emit_detail(
+                    {key: value for key, value in metadata.items() if key != "manifest"},
+                    output_format,
+                )
+                typer.echo()
+                for line in manifest_lines(manifest):
+                    typer.echo(line)
+            else:
+                _emit_detail(metadata, output_format)
+            typer.echo("\nassets: .")
+        _emit(
+            payload,
+            rows,
+            (("type", "TYPE"), ("name", "NAME"), ("path", "PATH"), ("size_bytes", "BYTES")),
+            output_format,
+        )
+    if payload.get("truncated"):
+        typer.echo(
+            "warning: directory listing is incomplete; increase --max-pages and retry", err=True
+        )
 
 
 def _check_version_autocreate(repo, dataset: str, version: str, *, environment: str) -> bool:
@@ -538,7 +647,14 @@ def _check_version_autocreate(repo, dataset: str, version: str, *, environment:
 
 
 def _confirm_upload(
-    dataset: str, version: str, split: str, count: int, *, yes: bool, auto_create: bool
+    dataset: str,
+    version: str,
+    split: str,
+    count: int,
+    *,
+    yes: bool,
+    auto_create: bool,
+    prune: bool = False,
 ) -> None:
     """push 写远端前统一二次确认(可 ``-y/--yes`` 跳过),与 split publish 同口径。"""
     if yes:
@@ -546,6 +662,10 @@ def _confirm_upload(
     label = _version_label(version)
     target = f"dataset {dataset} version {label} split {split}"
     note = f" Version {label} does not exist and will be auto-created." if auto_create else ""
+    if prune:
+        note += (
+            " Remote instance records absent from these paths will be removed; OSS files remain."
+        )
     if not sys.stdin.isatty():
         raise _fail(
             f"Uploading {count} instance(s) to {target} requires confirmation.{note}",
@@ -568,6 +688,29 @@ def instance_push(
     version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
     environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
     overwrite: bool = typer.Option(False, "--overwrite", help="Allow overwriting existing objects"),
+    skip_unchanged: bool = typer.Option(
+        False, "--skip-unchanged", help="Skip cases with matching source hashes"
+    ),
+    content_hashes: Optional[str] = typer.Option(
+        None, "--content-hashes", help="JSON file mapping instance IDs to source hashes"
+    ),
+    compress_level: Optional[int] = typer.Option(
+        None,
+        "--compress-level",
+        min=1,
+        max=9,
+        help="Gzip compression level; 1 is fastest, 9 is smallest",
+    ),
+    concurrency: int = typer.Option(8, "--concurrency", min=1, help="Concurrent instance uploads"),
+    continue_on_error: bool = typer.Option(
+        False, "--continue-on-error", help="Finish other uploads and report failed cases"
+    ),
+    progress: bool = typer.Option(False, "--progress", help="Write SDK upload progress to stderr"),
+    prune: bool = typer.Option(
+        False,
+        "--prune",
+        help="After delivery, remove remote metadata absent from the supplied cases; OSS files remain",
+    ),
     yes: bool = typer.Option(
         False,
         "--yes",
@@ -594,6 +737,22 @@ def instance_push(
             f"{len(broken)}/{len(results)} instances failed local validation; nothing was uploaded",
             "Run ap instance validate <path>... to fix the issues, then retry",
         )
+    try:
+        hashes = instance_options.upload_hashes(
+            results, instance_options.read_hashes(content_hashes), skip_unchanged
+        )
+        if prune:
+            if not resolved:
+                raise ValueError("--prune requires an explicit --version")
+            if any(not Path(record["path"]).is_dir() for record in results):
+                raise ValueError("--prune requires a collection of instance directories")
+            instance_options.require_working_prune()
+        if skip_unchanged or prune:
+            ids = [record["instance"] for record in results]
+            if len(ids) != len(set(ids)):
+                raise ValueError("Each supplied path must have a distinct instance ID")
+    except (ImportError, OSError, ValueError) as exc:
+        raise _fail(str(exc), "Check the hashes, input paths and installed Dataset SDK", 2) from exc
 
     # ② 写远端前统一二次确认(-y/--yes 跳过);版本不存在时提示将被自动创建。
     #   (split 已发布不可写由**服务端**裁决——pre 环境里 ingest 产出的 split 记录状态
@@ -604,13 +763,41 @@ def instance_push(
 
     repo = _load_repo_or_exit()
     _check_storage_side(repo, env)
+    enhanced: dict[str, Any] = {}
+    if skip_unchanged:
+        enhanced["skip_unchanged"] = True
+    if compress_level is not None:
+        enhanced["compress_level"] = compress_level
+    # The SDK batch path compares stored hashes before selecting format-specific uploads.
+    batch = len(targets) > 1 or prune or skip_unchanged
+    if hashes:
+        if batch:
+            enhanced["content_hashes"] = hashes
+        else:
+            source_hash = hashes.get(results[0]["instance"])
+            if source_hash:
+                enhanced["content_hash"] = source_hash
+    if batch and progress:
+        enhanced["progress_callback"] = instance_options.progress_callback
+    if batch and concurrency != 8:
+        enhanced["concurrency"] = concurrency
+    owner, method = (
+        (repo, "deliver") if prune else (repo.instances, "push_many" if batch else "push")
+    )
+    if prune:
+        enhanced["prune"] = True
+    if enhanced:
+        _enhanced_options(owner, method, enhanced)
     auto_create = _check_version_autocreate(repo, dataset, resolved, environment=env)
-    _confirm_upload(dataset, resolved, split, len(targets), yes=yes, auto_create=auto_create)
+    _confirm_upload(
+        dataset, resolved, split, len(targets), yes=yes, auto_create=auto_create, prune=prune
+    )
     pushed: list[dict] = []
+    skipped: list[dict] = []
     failed: list[dict] = []
     unconfirmed: list[str] = []
     result_count_mismatch = False
-    if len(targets) == 1:
+    if not batch:
         try:
             result = repo.instances.push(
                 targets[0],
@@ -620,6 +807,7 @@ def instance_push(
                 push_image=False,
                 overwrite=overwrite,
                 register=True,
+                **enhanced,
             )
         except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
             failed.append({"path": targets[0], "error": _describe(exc)})
@@ -628,20 +816,41 @@ def instance_push(
             )
             sdk_error_exit(exc, what=f"instance {targets[0]}", stage="upload")
         else:
-            pushed.append(_push_row(targets[0], result))
+            row = _push_row(targets[0], result)
+            (skipped if row["skipped"] else pushed).append(row)
+            if progress:
+                instance_options.progress_callback(1, 1, result)
     else:
         # 多路径:``continue_on_error=False`` 是"全或无",首个失败即抛 ItemError。
         try:
-            results_many = repo.instances.push_many(
-                targets,
-                dataset,
-                resolved,
-                split=split,
-                push_image=False,
-                overwrite=overwrite,
-                register=True,
-                continue_on_error=False,
-            )
+            if prune:
+                delivered = repo.deliver(
+                    dataset,
+                    resolved,
+                    targets,
+                    split=split,
+                    push_image=False,
+                    overwrite=overwrite,
+                    continue_on_error=continue_on_error,
+                    **enhanced,
+                )
+                results_many = [
+                    *delivered.get("pushed", []),
+                    *delivered.get("skipped", []),
+                    *delivered.get("failed", []),
+                ]
+            else:
+                results_many = repo.instances.push_many(
+                    targets,
+                    dataset,
+                    resolved,
+                    split=split,
+                    push_image=False,
+                    overwrite=overwrite,
+                    register=True,
+                    continue_on_error=continue_on_error,
+                    **enhanced,
+                )
         except Exception as exc:  # noqa: BLE001
             item = getattr(exc, "item", None)
             cause = getattr(exc, "error", None) or exc
@@ -661,17 +870,61 @@ def instance_push(
         else:
             results_list = list(results_many or [])
             result_count_mismatch = len(results_list) != len(targets)
-            if len(results_list) < len(targets):
-                unconfirmed.extend(targets[len(results_list) :])
-            for path, result in zip(targets, results_list):
-                pushed.append(_push_row(path, result))
+            pushed, skipped, failed, unconfirmed = _collect_upload_results(
+                targets, results, results_list, by_id=skip_unchanged or prune
+            )
 
-    _print_push_summary(dataset, resolved, split, pushed, failed, unconfirmed, output_format)
-    if result_count_mismatch:
+    _print_push_summary(
+        dataset,
+        resolved,
+        split,
+        pushed,
+        failed,
+        unconfirmed,
+        output_format,
+        skipped=skipped if skip_unchanged or skipped else None,
+    )
+    if result_count_mismatch or unconfirmed:
         raise _fail(
             f"SDK returned {len(results_list)}/{len(targets)} upload results; cannot confirm the full write state",
             f"Verify the actual content with ap instance list --dataset {dataset} --split {split}",
         )
+    if failed:
+        raise _fail(
+            f"{len(failed)} instance upload(s) failed",
+            "Check the failure summary and retry the failed paths",
+        )
+
+
+def _collect_upload_results(
+    targets: list[str],
+    records: list[dict],
+    values: list[Any],
+    *,
+    by_id: bool,
+) -> tuple[list[dict], list[dict], list[dict], list[str]]:
+    remaining = list(targets)
+    paths_by_id = {record["instance"]: record["path"] for record in records}
+    pushed, skipped, failed = [], [], []
+    for value in values:
+        if isinstance(value, BaseException):
+            item = str(getattr(value, "item", ""))
+            path = next((raw for raw in remaining if Path(raw) == Path(item)), "") if item else ""
+            if path:
+                remaining.remove(path)
+            failed.append({"path": path, "error": _describe(getattr(value, "error", value))})
+            continue
+        path = (
+            paths_by_id.get(getattr(value, "instance_id", ""), "")
+            if by_id
+            else (remaining[0] if remaining else "")
+        )
+        if path not in remaining:
+            continue
+        remaining.remove(path)
+        row = _push_row(path, value)
+        (skipped if row["skipped"] else pushed).append(row)
+    return pushed, skipped, failed, remaining
 
 
 def _push_row(path: str, result: Any) -> dict:
@@ -691,6 +944,8 @@ def _print_push_summary(
     failed: list[dict],
     unconfirmed: list[str],
     output_format: str,
+    *,
+    skipped: Optional[list[dict]] = None,
 ) -> None:
     payload = {
         "dataset": dataset,
@@ -701,6 +956,9 @@ def _print_push_summary(
         "unconfirmed": unconfirmed,
     }
     rows = [dict(row, status="pushed", error="") for row in pushed]
+    if skipped is not None:
+        payload["skipped"] = skipped
+        rows += [dict(row, status="skipped", error="") for row in skipped]
     rows += [
         {"path": row["path"], "instance": "", "status": "failed", "error": row["error"]}
         for row in failed
@@ -728,12 +986,18 @@ def instance_pull(
         None, "--output", "-o", help="Output directory (default: current directory)"
     ),
     overwrite: bool = typer.Option(False, "--overwrite", help="Allow overwriting the target"),
+    path: Optional[str] = typer.Option(
+        None,
+        "--path",
+        help="Download a relative subdirectory (Custom/OSS assets); use '.' for all assets",
+    ),
     output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
 ):
     """Download instance content and metadata into <output>/<instance>/."""
     from .irepo_sdk import sdk_error_exit
 
     output_format = _fmt(output_format)
+    resolved_path = _path_value(path)
     resolved = _version_value(version)
     root = Path(output or ".")
     target = root / instance
@@ -744,6 +1008,9 @@ def instance_pull(
         )
 
     repo = _load_repo_or_exit()
+    pull_options = {}
+    if resolved_path is not None:
+        pull_options = _enhanced_options(repo.instances, "pull", {"path": resolved_path})
     try:
         private_endpoint_reachable = _probe_pull_private_endpoint(repo, dataset)
     except Exception as exc:  # noqa: BLE001
@@ -760,10 +1027,17 @@ def instance_pull(
     staging = Path(tempfile.mkdtemp(prefix=f"ap-pull-{instance}-"))
     try:
         try:
-            written = repo.instances.pull(dataset, resolved, instance, staging, split)
+            written = repo.instances.pull(
+                dataset, resolved, instance, staging, split, **pull_options
+            )
         except Exception as exc:  # noqa: BLE001
             sdk_error_exit(exc, what=f"instance {instance}", stage="pull")
         staged = _place_under_target(Path(str(written)), staging / instance)
+        if resolved_path and not (staging / instance / resolved_path).is_dir():
+            raise _fail(
+                f"No files were downloaded for instance subdirectory {resolved_path}",
+                "Check the directory with ap instance get --path; the SDK must support this instance format",
+            )
         root.mkdir(parents=True, exist_ok=True)
         if target.exists():
             if not overwrite:
@@ -786,6 +1060,8 @@ def instance_pull(
         "output": str(target),
         "content": str(target / staged.name),
     }
+    if resolved_path is not None:
+        payload["path"] = resolved_path or "."
     _emit_detail(payload, output_format)
 
 
@@ -808,3 +1084,158 @@ def _place_under_target(written: Path, target: Path) -> Path:
             final.unlink()
     shutil.move(str(written), str(final))
     return final
+
+
+@instance_app.command("hash")
+def instance_hash(
+    paths: List[str] = typer.Argument(..., help="Local instance directories"),
+    output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
+):
+    """Compute source hashes locally without contacting AP."""
+    output_format = _fmt(output_format)
+    try:
+        from instance_repo import compute_source_hash
+    except ImportError as exc:
+        raise _fail(
+            "Source hashing requires instance-repo 1.3.5.dev1 or newer",
+            "Install Dataset support: pip install --upgrade 'ap-client[dataset]'",
+            2,
+        ) from exc
+    hashes, failed = [], []
+    for raw in paths:
+        path = Path(raw)
+        try:
+            if not path.is_dir():
+                raise ValueError("source hashing requires an existing instance directory")
+            hashes.append(
+                {"path": raw, "instance": path.name, "source_hash": compute_source_hash(path)}
+            )
+        except (OSError, ValueError) as exc:
+            failed.append({"path": raw, "error": _describe(exc)})
+    _emit(
+        {"hashes": hashes, "failed": failed},
+        hashes,
+        (("path", "PATH"), ("instance", "INSTANCE"), ("source_hash", "SOURCE_HASH")),
+        output_format,
+    )
+    if failed:
+        raise _fail(f"{len(failed)} instance directory hash(es) failed", "Check the local paths")
+
+
+@instance_app.command("hashes")
+def instance_hashes(
+    dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
+    split: str = typer.Option(..., "--split", help="Split name"),
+    version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
+    environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
+    metadata_model: Optional[str] = typer.Option(
+        None, "--metadata-model", help=_METADATA_MODEL_HELP
+    ),
+    output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
+):
+    """List source hashes stored on remote instances."""
+    output_format = _fmt(output_format)
+    resolved = _version_value(version)
+    env = _environment(environment)
+    repo = _load_repo_or_exit()
+    _enhanced_options(repo.instances, "list_content_hashes", {})
+    kwargs = _sdk_read_kwargs(
+        repo.instances,
+        "list_content_hashes",
+        environment=env,
+        metadata_model=_metadata_model_for_split(metadata_model, split=split),
+    )
+    try:
+        try:
+            fallback = oss_fallback_kwargs(repo, repo.instances, "list_content_hashes", env)
+        except RuntimeError:
+            # This SDK helper cannot disable its inner list() discovery yet.
+            list_kwargs = _sdk_read_kwargs(
+                repo.instances,
+                "list",
+                environment=env,
+                metadata_model=_metadata_model_for_split(metadata_model, split=split),
+            )
+            list_kwargs.update(oss_fallback_kwargs(repo, repo.instances, "list", env))
+            records = repo.instances.list(dataset, resolved, split=split, **list_kwargs)
+            hashes = {}
+            for record in records:
+                served = _model_dict(record)
+                source_hash = (served.get("extend_meta") or {}).get("source_hash")
+                if source_hash:
+                    hashes[served["instance_id"]] = source_hash
+        else:
+            hashes = repo.instances.list_content_hashes(
+                dataset, resolved, split=split, **kwargs, **fallback
+            )
+    except Exception as exc:  # noqa: BLE001
+        raise _fail(
+            f"Failed to list source hashes of dataset {dataset}: {_describe(exc)}",
+            "Check the environment, bound storage and read permission",
+        ) from exc
+    rows = [
+        {"instance": instance, "source_hash": value} for instance, value in sorted(hashes.items())
+    ]
+    _emit(
+        {"dataset": dataset, "version": resolved, "split": split, "hashes": hashes},
+        rows,
+        (("instance", "INSTANCE"), ("source_hash", "SOURCE_HASH")),
+        output_format,
+    )
+
+
+@instance_app.command("delete")
+def instance_delete(
+    instance: str = typer.Argument(..., help="Instance id"),
+    dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
+    version: str = typer.Option(..., "--version", help="Dataset version containing the instance"),
+    split: str = typer.Option(..., "--split", help="Split name"),
+    environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
+    metadata_model: Optional[str] = typer.Option(
+        None, "--metadata-model", help=_METADATA_MODEL_HELP
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Confirm deleting instance metadata"),
+    output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
+):
+    """Delete instance metadata. OSS content remains available to later ingest."""
+    from .irepo_sdk import sdk_error_exit
+
+    output_format = _fmt(output_format)
+    env = _environment(environment)
+    resolved = _version_value(version)
+    if not resolved:
+        raise _fail(
+            "--version must be nonempty for metadata deletion", "Specify the dataset version", 2
+        )
+    repo = _load_repo_or_exit()
+    _enhanced_options(repo.instances, "delete", {})
+    kwargs = _sdk_read_kwargs(
+        repo.instances,
+        "delete",
+        environment=env,
+        metadata_model=_metadata_model_for_split(metadata_model, split=split),
+    )
+    if not yes:
+        if not sys.stdin.isatty():
+            raise _fail("Deleting instance metadata requires confirmation", "Add --yes (-y)", 2)
+        if not typer.confirm(
+            f"Delete metadata for {dataset} version {resolved} split {split} instance {instance}? OSS files remain."
+        ):
+            raise _fail(
+                "Metadata deletion canceled", "Rerun when you want to delete the instance record"
+            )
+    try:
+        repo.instances.delete(dataset, resolved, instance, split=split, **kwargs)
+    except Exception as exc:  # noqa: BLE001
+        sdk_error_exit(exc, what=f"instance {instance}", stage="metadata deletion")
+    _emit_detail(
+        {
+            "dataset": dataset,
+            "version": resolved,
+            "split": split,
+            "instance": instance,
+            "deleted": True,
+            "content_deleted": False,
+        },
+        output_format,
+    )

ap_client-0.5.3.dev8/ap_client/instance_options.py

@@ -0,0 +1,94 @@
+"""Local option parsing for instance directory reads and uploads."""
+
+from __future__ import annotations
+
+import inspect
+import json
+from importlib import metadata
+from pathlib import Path
+from typing import Any
+
+import typer
+
+
+def relative_path(value: str | None) -> str | None:
+    if value is None:
+        return None
+    path = value.strip().rstrip("/")
+    if path in ("", ".") and not value.strip().startswith("/"):
+        return ""
+    if (
+        path.startswith("/")
+        or "\\" in path
+        or ":" in path
+        or any(ord(char) < 32 or ord(char) == 127 for char in path)
+        or any(part in ("", ".", "..") for part in path.split("/"))
+    ):
+        raise ValueError("--path must be relative to the instance root; use '.' for the root")
+    return path
+
+
+def sdk_options(owner: Any, method: str, options: dict[str, Any]) -> dict[str, Any]:
+    function = getattr(owner, method, None)
+    if not callable(function):
+        raise ValueError(f"The installed instance-repo does not support {method}")
+    parameters = inspect.signature(function).parameters
+    if not any(p.kind is inspect.Parameter.VAR_KEYWORD for p in parameters.values()):
+        missing = set(options) - set(parameters)
+        if missing:
+            raise ValueError(
+                f"The installed instance-repo does not support {method} options: "
+                + ", ".join(sorted(missing))
+            )
+    return options
+
+
+def read_hashes(path: str | None) -> dict[str, str]:
+    if path is None:
+        return {}
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, dict) or any(
+        not isinstance(key, str) or not key.strip() or not isinstance(item, str) or not item.strip()
+        for key, item in value.items()
+    ):
+        raise ValueError(
+            "--content-hashes must contain a JSON object of instance IDs to nonempty hashes"
+        )
+    return value
+
+
+def upload_hashes(records: list[dict], supplied: dict[str, str], skip: bool) -> dict[str, str]:
+    hashes = dict(supplied)
+    if not skip:
+        return hashes
+    from instance_repo import compute_source_hash
+
+    for record in records:
+        instance = record["instance"]
+        path = Path(record["path"])
+        if not path.is_dir():
+            raise ValueError("--skip-unchanged currently supports instance directories only")
+        if instance in hashes:
+            continue
+        hashes[instance] = compute_source_hash(path)
+    return hashes
+
+
+def require_working_prune() -> None:
+    try:
+        version = metadata.version("instance-repo")
+    except metadata.PackageNotFoundError:
+        return
+    if version in {"1.3.5.dev1", "1.3.5.dev2"}:
+        raise ValueError(
+            f"instance-repo {version} cannot complete --prune; upgrade to a fixed SDK before uploading"
+        )
+
+
+def progress_callback(completed: int, total: int, result: Any) -> None:
+    instance = str(getattr(result, "instance_id", "") or type(result).__name__)
+    instance = "".join(char if char.isprintable() else repr(char)[1:-1] for char in instance)
+    status = "skipped" if getattr(result, "skipped", False) else "uploaded"
+    if isinstance(result, BaseException):
+        status = "failed"
+    typer.echo(f"progress: {completed}/{total} {instance} {status}", err=True)

{ap_client-0.5.3.dev7 → ap_client-0.5.3.dev8}/ap_client/irepo_sdk.py

@@ -951,10 +951,28 @@ def load_repo(
         _setdefault_env(_LEGACY_STORAGE_ENV_VAR, effective_storage_env)
 
     repo = _Repo(**kwargs)
+    _bind_dataset_profile(repo)
     _install_oss_probe_cache(repo, verbose=cfg.verbose)
     return repo
 
 
+def _bind_dataset_profile(repo: Any) -> None:
+    """Supply the configured context missing from SDK 1.3.5 dataset discovery.
+
+    Its environment check reads ``_p``, but its constructor does not initialize
+    that field. Bind only a missing field to this Repo's resolved profile;
+    SDKs that initialize it retain their own context.
+    """
+    client = getattr(repo, "datasets", None)
+    profile = getattr(repo, "profile", None)
+    if (
+        profile is not None
+        and callable(getattr(client, "_discovery_env_match", None))
+        and not hasattr(client, "_p")
+    ):
+        client._p = profile
+
+
 def _init_parameters(repo_cls: type) -> frozenset[str]:
     """``Repo.__init__`` 接受的关键字参数名;签名不可读时返回空集合。"""
     try:

{ap_client-0.5.3.dev7 → ap_client-0.5.3.dev8}/pyproject.toml

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