ap-client 0.8.0.dev4__tar.gz → 0.8.1.dev0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/PKG-INFO +3 -3
  2. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/api.py +19 -4
  3. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/cli.py +27 -6
  4. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/dfs_commands.py +25 -10
  5. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/instance_commands.py +567 -15
  6. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/ossutil_io.py +105 -7
  7. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_commands.py +3 -0
  8. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_diagnostics.py +2 -1
  9. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_references.py +3 -2
  10. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/repo_read_guard.py +0 -37
  11. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/pyproject.toml +3 -3
  12. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/__init__.py +0 -0
  13. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/akpool_commands.py +0 -0
  14. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/config.py +0 -0
  15. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/dataset_commands.py +0 -0
  16. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/dataset_name.py +0 -0
  17. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/dataset_register.py +0 -0
  18. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/exporter.py +0 -0
  19. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/fs_commands.py +0 -0
  20. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/fs_storage.py +0 -0
  21. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/fs_transfer.py +0 -0
  22. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/instance_options.py +0 -0
  23. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/irepo_sdk.py +0 -0
  24. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/managed_ak.py +0 -0
  25. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/manifest_view.py +0 -0
  26. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/ossutil_hash.py +0 -0
  27. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_all.py +0 -0
  28. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_cli.py +0 -0
  29. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_display.py +0 -0
  30. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_state.py +0 -0
  31. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/profile_display.py +0 -0
  32. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/share_api.py +0 -0
  33. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/split_publish.py +0 -0
  34. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/submission_metadata.py +0 -0
  35. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/tbb.py +0 -0
  36. {ap_client-0.8.0.dev4 → ap_client-0.8.1.dev0}/ap_client/waiter.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: ap-client
3
- Version: 0.8.0.dev4
3
+ Version: 0.8.1.dev0
4
4
  Summary: Agent Platform API Client & CLI
5
5
  Requires-Python: >=3.10
6
6
  Requires-Dist: irepo-artifact==0.2.6
@@ -10,9 +10,9 @@ Requires-Dist: rich>=13.0.0
10
10
  Requires-Dist: typer>=0.9.0
11
11
  Requires-Dist: websockets>=13.0
12
12
  Provides-Extra: all
13
- Requires-Dist: instance-repo[oss]<2.0.0,>=1.4.6; extra == 'all'
13
+ Requires-Dist: instance-repo[oss]==1.4.8.dev0; extra == 'all'
14
14
  Provides-Extra: dataset
15
- Requires-Dist: instance-repo[oss]<2.0.0,>=1.4.6; extra == 'dataset'
15
+ Requires-Dist: instance-repo[oss]==1.4.8.dev0; extra == 'dataset'
16
16
  Description-Content-Type: text/markdown
17
17
 
18
18
  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.
@@ -268,6 +268,9 @@ class APIError(Exception):
268
268
  self.request_id = request_id
269
269
  self.response = response
270
270
  self.retry_stop_reason = retry_stop_reason
271
+ self.response_request_id = (
272
+ response.headers.get("X-Request-ID") if response is not None else None
273
+ )
271
274
  self.pop_request_id = (
272
275
  response.headers.get("x-acs-request-id") if response is not None else None
273
276
  )
@@ -275,10 +278,8 @@ class APIError(Exception):
275
278
 
276
279
  def __str__(self) -> str:
277
280
  message = self._build_message()
278
- if self.retry_stop_reason:
279
- message += f" (retry_stop_reason={self.retry_stop_reason})"
280
- if self.pop_request_id:
281
- message += f" (pop_request_id={self.pop_request_id})"
281
+ for diagnostic in format_api_error_diagnostics(self):
282
+ message += f" ({diagnostic})"
282
283
  return message
283
284
 
284
285
  def _build_message(self) -> str:
@@ -287,6 +288,20 @@ class APIError(Exception):
287
288
  return f"API Error {self.status_code}: {self.detail} (request_id={self.request_id})"
288
289
 
289
290
 
291
+ def format_api_error_diagnostics(exc: APIError, *, separator: str = "=") -> list[str]:
292
+ """Render response and retry diagnostics without repeating the local request ID."""
293
+ diagnostics = []
294
+ seen = {exc.request_id}
295
+ for name in ("response_request_id", "pop_request_id"):
296
+ value = getattr(exc, name)
297
+ if value and value not in seen:
298
+ seen.add(value)
299
+ diagnostics.append(f"{name}{separator}{value}")
300
+ if exc.retry_stop_reason:
301
+ diagnostics.append(f"retry_stop_reason{separator}{exc.retry_stop_reason}")
302
+ return diagnostics
303
+
304
+
290
305
  class PaginationProtocolError(RuntimeError):
291
306
  """The server stopped honoring a pagination protocol already in use."""
292
307
 
@@ -18,6 +18,7 @@ from ap_client.api import (
18
18
  APIError,
19
19
  PaginationProtocolError,
20
20
  _merge_meta_tags,
21
+ format_api_error_diagnostics,
21
22
  set_cluster_override,
22
23
  set_verbose_override,
23
24
  )
@@ -3594,8 +3595,8 @@ def job_create(
3594
3595
  ):
3595
3596
  """Submit a job.
3596
3597
 
3597
- For agents:
3598
3598
  \b
3599
+ For agents:
3599
3600
  Before submitting, you MUST ensure these five parameters are explicitly specified:
3600
3601
  benchmark, meta-model, meta-job-type, meta-train-stage, meta-teacher-direction.
3601
3602
  Keep specified values. Fill missing parameters using available Job, Group,
@@ -5985,10 +5986,23 @@ def group_create(
5985
5986
  ):
5986
5987
  """Create a Group.
5987
5988
 
5988
- Dataset -> Benchmark -> teacher direction links are candidates. Check this
5989
- Group's business purpose before adopting them. Rollout using A's Dataset
5990
- for B may have different attribution from input A; a downstream mention of B
5991
- alone does not establish that B is this Group's Benchmark.
5989
+ \b
5990
+ For agents:
5991
+ Before creating, you MUST ensure these five parameters are explicitly specified:
5992
+ benchmark, meta-model, meta-job-type, meta-train-stage, meta-teacher-direction.
5993
+ Keep specified values. Fill missing parameters using available Job, Group,
5994
+ Profile, Dataset, Template, or other relevant information.
5995
+ Check available Dataset -> Benchmark -> teacher direction links as candidates.
5996
+ Adopt them only when they match this Group's business purpose.
5997
+ Separate the input-data source from this Group's business attribution.
5998
+ For rollout using A's Dataset to produce data for B, use B only when B is
5999
+ this Group's intended attribution; do not automatically inherit A's labels
6000
+ or choose B merely because it is a downstream consumer.
6001
+ If a missing value cannot be inferred, use default for benchmark
6002
+ or Others for the corresponding meta parameter.
6003
+ Do not ask the user for these values.
6004
+ The server may derive some omitted meta values or default meta-job-type to Eval-Eval;
6005
+ explicitly specify and verify all five values rather than relying on implicit attribution.
5992
6006
  """
5993
6007
  if transparency is not None and transparency not in {"whitebox", "blackbox"}:
5994
6008
  raise typer.BadParameter("Choose whitebox or blackbox", param_hint="--transparency")
@@ -7360,7 +7374,13 @@ def _format_api_error(exc: APIError) -> str:
7360
7374
  if profile_error := format_profile_error(exc):
7361
7375
  return profile_error
7362
7376
  if isinstance(exc.detail, dict) and exc.detail.get("code") == "blackbox_content_restricted":
7363
- return f"error: Blackbox content is hidden; Group Reader access is required. (request_id={exc.request_id})"
7377
+ diagnostics = "".join(
7378
+ f" ({diagnostic})" for diagnostic in format_api_error_diagnostics(exc)
7379
+ )
7380
+ return (
7381
+ "error: Blackbox content is hidden; Group Reader access is required. "
7382
+ f"(request_id={exc.request_id}){diagnostics}"
7383
+ )
7364
7384
  if str(exc.detail) != _NON_JSON_RESPONSE_DETAIL:
7365
7385
  return f"error: {exc}"
7366
7386
 
@@ -7370,6 +7390,7 @@ def _format_api_error(exc: APIError) -> str:
7370
7390
  f"hint: {_NON_JSON_RESPONSE_HINT}",
7371
7391
  f"request_id: {exc.request_id}",
7372
7392
  ]
7393
+ lines.extend(format_api_error_diagnostics(exc, separator=": "))
7373
7394
  if exc.response is not None:
7374
7395
  content_type = exc.response.headers.get("Content-Type") or "<missing>"
7375
7396
  lines.extend(
@@ -12,7 +12,7 @@ from urllib.parse import unquote, urlsplit
12
12
 
13
13
  import typer
14
14
 
15
- from .ossutil_io import OssBinding, OssFiles, OssUsageError, _relative, safe_error
15
+ from .ossutil_io import OssBinding, OssFiles, OssPathNotFound, OssUsageError, _relative, safe_error
16
16
 
17
17
  dfs_app = typer.Typer(
18
18
  help=(
@@ -288,7 +288,7 @@ def dfs_ls(
288
288
  False,
289
289
  "--recursive",
290
290
  "-r",
291
- help="Expand all directory levels; PATH must end with a trailing slash (/)",
291
+ help="Expand all directory levels; PATH is treated as a directory (a trailing / is added if omitted)",
292
292
  ),
293
293
  short: bool = typer.Option(False, "--short-format", "-s", help="Print only paths"),
294
294
  limited_num: Optional[int] = typer.Option(None, "--limited-num", min=1),
@@ -304,9 +304,10 @@ def dfs_ls(
304
304
  """List remote paths, without reading object content; default is one level, -r expands all.
305
305
 
306
306
  Accepts ans://, repo-relative paths or full oss:// URIs. Paths outside the Dataset root use full URIs.
307
- With -r/--recursive, PATH must explicitly end with /. Without -r, the slash is optional.
308
- Listing includes only descendants of that directory.
309
- Sibling keys with the same text prefix are excluded, including with -r.
307
+ Default listing accepts an exact file or directory (directory wins if both exist).
308
+ A trailing slash or -d selects only a directory. Missing paths fail explicitly.
309
+ With -r/--recursive, PATH denotes a directory; a missing trailing / is added before
310
+ credentials are requested. Listing includes only descendants, never sibling keys.
310
311
  Uses AP-managed reader/list-only credentials; listing prefers private networking with
311
312
  a public endpoint fallback. Example: ap dfs ls ans://team/bench/train/ -r --format json.
312
313
  """
@@ -316,14 +317,20 @@ def dfs_ls(
316
317
  if recursive and directory:
317
318
  raise OssUsageError("Use either --recursive or --directory")
318
319
  path = _read_operand(path, encoding_type, directory=True)
319
- if recursive and not path.endswith("/"):
320
- raise OssUsageError(
321
- "Recursive listing requires PATH to end with /; append / to the directory path"
322
- )
320
+ if recursive and not _decoded_path(path, encoding_type).endswith("/"):
321
+ # Treat recursive PATH as a directory at the CLI boundary. This keeps the
322
+ # request slash-bounded and lets the API reject raw ambiguous requests
323
+ # before issuing credentials, without making users type the final slash.
324
+ path += "/"
323
325
  marker = _read_operand(marker, encoding_type, directory=True, allow_empty=True)
324
326
  files = _files()
325
327
  _configure(files, encoding_type, payer)
326
328
  remote = files.resolve(path, directory=True)
329
+ file_candidate = (
330
+ files.resolve(path) if not recursive and not directory
331
+ and remote.key != files.binding.prefix
332
+ and not _decoded_path(path, encoding_type).endswith("/") else None
333
+ )
327
334
  _emit(
328
335
  files.list(
329
336
  remote,
@@ -332,6 +339,7 @@ def dfs_ls(
332
339
  marker=marker,
333
340
  include=tuple(include or ()),
334
341
  exclude=tuple(exclude or ()),
342
+ file_candidate=file_candidate,
335
343
  ),
336
344
  fmt,
337
345
  short=short,
@@ -693,7 +701,14 @@ def dfs_hash(
693
701
  local = _local_operand(path)
694
702
  from .ossutil_hash import hash_local
695
703
 
696
- result = hash_local(local, algorithm, base64_output=base64_output, recursive=recursive)
704
+ absent = False
705
+ try:
706
+ result = hash_local(local, algorithm, base64_output=base64_output, recursive=recursive)
707
+ except FileNotFoundError:
708
+ # Only the actual local hash read is classified, never config/checkpoints.
709
+ absent = True
710
+ if absent:
711
+ raise OssPathNotFound(local=True)
697
712
  _emit(result, fmt)
698
713
  if result.get("failed_count"):
699
714
  raise typer.Exit(1)
@@ -8,6 +8,8 @@ Remote operations share SDK configuration and the CLI output/error contract.
8
8
  from __future__ import annotations
9
9
 
10
10
  import inspect
11
+ import json
12
+ import os
11
13
  import shutil
12
14
  import sys
13
15
  import tempfile
@@ -19,6 +21,8 @@ import typer
19
21
  __all__ = ["instance_app", "register"]
20
22
 
21
23
  instance_app = typer.Typer(help="Dataset instance operations")
24
+ tag_app = typer.Typer(help="Read and modify instance tags (non-atomic whole-map updates)")
25
+ instance_app.add_typer(tag_app, name="tag")
22
26
 
23
27
 
24
28
  def register(app: typer.Typer) -> None:
@@ -375,13 +379,230 @@ def instance_validate(
375
379
  )
376
380
 
377
381
 
382
+ def _tag_values(raw: str, *, expression: str) -> list[str]:
383
+ values = [value.strip() for value in raw.split(",")]
384
+ if not raw.strip() or any(not value for value in values):
385
+ raise ValueError(f"invalid tag expression {expression!r}: values must be nonempty")
386
+ return values
387
+
388
+
389
+ def _parse_tag_filters(expressions: Optional[List[str]]) -> dict[str, Any]:
390
+ """Parse k=v, k=v1,v2 and k=all(v1,v2); conditions across keys are ANDed."""
391
+ filters: dict[str, Any] = {}
392
+ for expression in expressions or []:
393
+ key, separator, raw = expression.partition("=")
394
+ key = key.strip()
395
+ raw = raw.strip()
396
+ if not separator or not key:
397
+ raise ValueError(f"invalid tag expression {expression!r}: expected k=v")
398
+ if key in filters:
399
+ raise ValueError(f"duplicate tag filter key {key!r}")
400
+ if raw.startswith("all("):
401
+ if not raw.endswith(")"):
402
+ raise ValueError(f"invalid tag expression {expression!r}: unclosed all()")
403
+ inner = raw[4:-1]
404
+ if "(" in inner or ")" in inner:
405
+ raise ValueError(
406
+ f"invalid tag expression {expression!r}: all() needs one complete outer pair"
407
+ )
408
+ values = _tag_values(inner, expression=expression)
409
+ filters[key] = {"all": values}
410
+ continue
411
+ if "(" in raw or ")" in raw:
412
+ raise ValueError(f"invalid tag expression {expression!r}: unexpected parentheses")
413
+ values = _tag_values(raw, expression=expression)
414
+ filters[key] = values[0] if len(values) == 1 else {"any": values}
415
+ return filters
416
+
417
+
418
+ def _parse_tag_assignments(expressions: Optional[List[str]]) -> dict[str, str | list[str]]:
419
+ assignments: dict[str, str | list[str]] = {}
420
+ for expression in expressions or []:
421
+ key, separator, raw = expression.partition("=")
422
+ key = key.strip()
423
+ if not separator or not key:
424
+ raise ValueError(f"invalid tag expression {expression!r}: expected k=v")
425
+ if key in assignments:
426
+ raise ValueError(f"duplicate tag key {key!r}")
427
+ raw = raw.strip()
428
+ if "(" in raw or ")" in raw:
429
+ raise ValueError(f"invalid tag expression {expression!r}: unexpected parentheses")
430
+ values = _tag_values(raw, expression=expression)
431
+ assignments[key] = values[0] if len(values) == 1 else values
432
+ return assignments
433
+
434
+
435
+ def _validate_tag_map(value: Any) -> dict[str, str | list[str]]:
436
+ if not isinstance(value, dict) or not value:
437
+ raise ValueError("tags must be a nonempty JSON object")
438
+ tags: dict[str, str | list[str]] = {}
439
+ for raw_key, item in value.items():
440
+ if not isinstance(raw_key, str) or not raw_key.strip():
441
+ raise ValueError("tag keys must be nonempty strings")
442
+ key = raw_key.strip()
443
+ if key in tags:
444
+ raise ValueError(f"duplicate tag key {key!r} after trimming")
445
+ if isinstance(item, str):
446
+ normalized = item.strip()
447
+ if not normalized:
448
+ raise ValueError(f"tag {key!r} values must be nonempty")
449
+ tags[key] = normalized
450
+ elif isinstance(item, list) and all(isinstance(entry, str) for entry in item):
451
+ values: list[str] = []
452
+ for entry in item:
453
+ normalized = entry.strip()
454
+ if not normalized:
455
+ raise ValueError(f"tag {key!r} values must be nonempty")
456
+ if normalized not in values:
457
+ values.append(normalized)
458
+ tags[key] = values
459
+ else:
460
+ raise ValueError(f"tag {key!r} must be a string or a string array")
461
+ return tags
462
+
463
+
464
+ def _require_tag_filter_capability(repo: Any) -> None:
465
+ """Fail loudly before an old SDK can coerce JSON filters into legacy CSV."""
466
+ method_names = ("list_tags", "set_tags", "append_tags", "remove_tags", "clear_tags")
467
+ if not all(callable(getattr(repo.instances, name, None)) for name in method_names):
468
+ raise _fail(
469
+ "The installed InstanceRepository SDK does not support JSON instance tag filters",
470
+ "Upgrade to an InstanceRepository SDK with instance tag support: "
471
+ "pip install --upgrade 'ap-client[dataset]'",
472
+ 2,
473
+ )
474
+ _enhanced_options(repo.instances, "list_paged", {"tags": {}})
475
+
476
+
477
+ _EXPORT_PAGE_SIZE = 200
478
+
479
+
480
+ def _export_instance_ids(
481
+ repo: Any,
482
+ dataset: str,
483
+ version: str,
484
+ split: str,
485
+ filters: dict[str, Any],
486
+ read_kwargs: dict[str, Any],
487
+ export: str,
488
+ output_format: str,
489
+ ) -> None:
490
+ from .irepo_sdk import _reason
491
+
492
+ instance_ids: list[str] = []
493
+ seen_ids: set[str] = set()
494
+ seen_pages: set[tuple[str, ...]] = set()
495
+ page = 1
496
+ while True:
497
+ try:
498
+ query_kwargs = {"tags": filters} if filters else {}
499
+ result = repo.instances.list_paged(
500
+ dataset,
501
+ version,
502
+ split=split,
503
+ page=page,
504
+ page_size=_EXPORT_PAGE_SIZE,
505
+ **query_kwargs,
506
+ **read_kwargs,
507
+ )
508
+ except Exception as exc: # noqa: BLE001 - same CLI error contract as instance list
509
+ raise _fail(
510
+ f"Failed to export instances of dataset {dataset} version {_version_label(version)}: "
511
+ f"{_reason(exc)}",
512
+ "Check --dataset/--version/--split, tag filters and read permission, then retry",
513
+ ) from exc
514
+ items = list(getattr(result, "items", None) or [])
515
+ page_ids = [str(getattr(item, "instance_id", "") or "") for item in items]
516
+ if any(not instance_id.strip() for instance_id in page_ids):
517
+ raise _fail(
518
+ f"Instance export stopped at page {page}; server pagination returned incomplete data: "
519
+ "record(s) have a missing or blank instance_id",
520
+ "Retry the export; no partial file was written",
521
+ )
522
+ if items:
523
+ signature = tuple(page_ids)
524
+ if signature in seen_pages:
525
+ raise _fail(
526
+ f"Instance export stopped at repeated page {page}; the server pagination is not advancing",
527
+ "Retry the export; no partial file was written",
528
+ )
529
+ seen_pages.add(signature)
530
+ for instance_id in page_ids:
531
+ if instance_id and instance_id not in seen_ids:
532
+ seen_ids.add(instance_id)
533
+ instance_ids.append(instance_id)
534
+ total = getattr(result, "total", -1)
535
+ has_total = isinstance(total, (int, float)) and total >= 0
536
+ consumed = (page - 1) * _EXPORT_PAGE_SIZE + len(items)
537
+ if len(items) < _EXPORT_PAGE_SIZE:
538
+ if has_total and total > consumed:
539
+ raise _fail(
540
+ f"Instance export stopped at page {page}; server pagination is inconsistent: "
541
+ f"total {total} exceeds the {consumed} record(s) read",
542
+ "Retry the export; no partial file was written",
543
+ )
544
+ break
545
+ if has_total and consumed >= total:
546
+ break
547
+ if page >= 100000:
548
+ raise _fail(
549
+ "Instance export exceeded 100000 pages",
550
+ "Narrow the tag filters; no partial file was written",
551
+ )
552
+ page += 1
553
+
554
+ target = Path(export)
555
+ temporary: Optional[Path] = None
556
+ try:
557
+ with tempfile.NamedTemporaryFile(
558
+ mode="w",
559
+ encoding="utf-8",
560
+ dir=target.parent,
561
+ prefix=f".{target.name}.",
562
+ suffix=".tmp",
563
+ delete=False,
564
+ ) as stream:
565
+ temporary = Path(stream.name)
566
+ stream.writelines(f"{instance_id}\n" for instance_id in instance_ids)
567
+ os.replace(temporary, target)
568
+ temporary = None
569
+ except OSError as exc:
570
+ raise _fail(f"Failed to write instance export {export}: {exc}", "Check the output path") from exc
571
+ finally:
572
+ if temporary is not None:
573
+ try:
574
+ temporary.unlink()
575
+ except OSError:
576
+ pass
577
+ payload = {
578
+ "dataset": dataset,
579
+ "version": version,
580
+ "split": split,
581
+ "export": {"path": export, "count": len(instance_ids)},
582
+ }
583
+ if output_format in ("json", "yaml"):
584
+ from .cli import _print_formatted
585
+
586
+ _print_formatted(payload, output_format)
587
+ else:
588
+ typer.echo(f"exported {len(instance_ids)} instance(s) to {export}")
589
+
590
+
378
591
  @instance_app.command("list")
379
592
  def instance_list(
380
593
  dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
381
594
  split: str = typer.Option(..., "--split", help="Split name (required for remote operations)"),
382
595
  version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
383
- page: int = typer.Option(1, "--page", help="Page number"),
384
- page_size: int = typer.Option(50, "--page-size", help="Page size"),
596
+ page: Optional[int] = typer.Option(None, "--page", help="Page number"),
597
+ page_size: Optional[int] = typer.Option(None, "--page-size", help="Page size"),
598
+ tags: Optional[List[str]] = typer.Option(
599
+ None,
600
+ "--tag",
601
+ help="Tag filter: k=v (equals/member), k=v1,v2 (any), or k=all(v1,v2); repeatable AND",
602
+ ),
603
+ export: Optional[str] = typer.Option(
604
+ None, "--export", help="Export all filtered instance IDs, one per line"
605
+ ),
385
606
  environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
386
607
  metadata_model: Optional[str] = typer.Option(
387
608
  None, "--metadata-model", help=_METADATA_MODEL_HELP
@@ -393,6 +614,16 @@ def instance_list(
393
614
 
394
615
  output_format = _fmt(output_format)
395
616
  resolved_version = _version_value(version)
617
+ try:
618
+ filters = _parse_tag_filters(tags)
619
+ except ValueError as exc:
620
+ raise _fail(str(exc), "Use --tag k=v, --tag k=v1,v2, or --tag 'k=all(v1,v2)'", 2) from exc
621
+ if export and (page is not None or page_size is not None):
622
+ raise _fail(
623
+ "--page and --page-size cannot be used with --export",
624
+ "Export always traverses all filtered pages; remove explicit pagination",
625
+ 2,
626
+ )
396
627
  repo = _load_repo_or_exit()
397
628
  env = _environment(environment)
398
629
  read_kwargs = _sdk_read_kwargs(
@@ -401,14 +632,31 @@ def instance_list(
401
632
  environment=env,
402
633
  metadata_model=_metadata_model_for_split(metadata_model, split=split),
403
634
  )
635
+ if filters:
636
+ _require_tag_filter_capability(repo)
637
+ if export:
638
+ try:
639
+ read_kwargs.update(oss_fallback_kwargs(repo, repo.instances, "list_paged", env))
640
+ except Exception as exc: # noqa: BLE001 - same CLI error contract as export reads
641
+ raise _fail(
642
+ f"Failed to export instances of dataset {dataset} version {_version_label(resolved_version)}: "
643
+ f"{_reason(exc)}",
644
+ "Check --dataset/--version/--split, tag filters and read permission, then retry",
645
+ ) from exc
646
+ _export_instance_ids(
647
+ repo, dataset, resolved_version, split, filters, read_kwargs, export, output_format
648
+ )
649
+ return
404
650
  try:
405
651
  read_kwargs.update(oss_fallback_kwargs(repo, repo.instances, "list_paged", env))
652
+ query_kwargs = {"tags": filters} if filters else {}
406
653
  result = repo.instances.list_paged(
407
654
  dataset,
408
655
  resolved_version,
409
656
  split=split,
410
- page=page,
411
- page_size=page_size,
657
+ page=page if page is not None else 1,
658
+ page_size=page_size if page_size is not None else 50,
659
+ **query_kwargs,
412
660
  **read_kwargs,
413
661
  )
414
662
  except Exception as exc: # noqa: BLE001 - 统一走设计 §5.1 的映射
@@ -430,6 +678,306 @@ def instance_list(
430
678
  _emit(payload, rows, _INSTANCE_COLUMNS, output_format)
431
679
 
432
680
 
681
+ def _tag_payload(dataset: str, version: str, split: str, instance: str, tags: Any) -> dict:
682
+ return {
683
+ "dataset": dataset,
684
+ "version": version,
685
+ "split": split,
686
+ "instance_id": instance,
687
+ "tags": tags,
688
+ }
689
+
690
+
691
+ def _tag_method(repo: Any, operation: str, read_kwargs: dict[str, Any]):
692
+ method_name = f"{operation}_tags"
693
+ _enhanced_options(repo.instances, method_name, read_kwargs)
694
+ return getattr(repo.instances, method_name)
695
+
696
+
697
+ def _run_tag_file(
698
+ repo: Any,
699
+ operation: str,
700
+ dataset: str,
701
+ version: str,
702
+ split: str,
703
+ from_file: str,
704
+ read_kwargs: dict[str, Any],
705
+ output_format: str,
706
+ ) -> None:
707
+ try:
708
+ lines = Path(from_file).read_text(encoding="utf-8").splitlines()
709
+ except (OSError, UnicodeError) as exc:
710
+ raise _fail(f"Failed to read --from-file {from_file}: {exc}", "Use a UTF-8 JSONL file", 2) from exc
711
+
712
+ method = _tag_method(repo, operation, read_kwargs)
713
+ results: list[dict[str, Any]] = []
714
+ for line_number, raw in enumerate(lines, start=1):
715
+ if not raw.strip():
716
+ continue
717
+ row: dict[str, Any] = {"line": line_number, "instance": "", "status": "failed", "error": ""}
718
+ try:
719
+ try:
720
+ value = json.loads(raw)
721
+ except json.JSONDecodeError as exc:
722
+ raise ValueError(f"invalid JSON: {exc.msg}") from exc
723
+ if not isinstance(value, dict):
724
+ raise ValueError("each JSONL line must be an object")
725
+ instance = value.get("instance_id")
726
+ if not isinstance(instance, str) or not instance.strip():
727
+ raise ValueError("instance_id must be a nonempty string")
728
+ row["instance"] = instance
729
+ if operation == "clear":
730
+ keys = value.get("keys")
731
+ if (not isinstance(keys, list) or not keys
732
+ or not all(isinstance(key, str) and key.strip() for key in keys)):
733
+ raise ValueError("clear requires keys: a nonempty string array")
734
+ clear_keys = [key.strip() for key in keys]
735
+ updated = method(
736
+ dataset, version, instance, clear_keys, split=split, **read_kwargs
737
+ )
738
+ else:
739
+ tags = _validate_tag_map(value.get("tags"))
740
+ updated = method(
741
+ dataset, version, instance, tags, split=split, **read_kwargs
742
+ )
743
+ row["status"] = "succeeded"
744
+ row["tags"] = getattr(updated, "tags", {}) or {}
745
+ except Exception as exc: # noqa: BLE001 - report every JSONL item and continue
746
+ row["error"] = _describe(exc)
747
+ results.append(row)
748
+
749
+ succeeded = sum(row["status"] == "succeeded" for row in results)
750
+ failed = len(results) - succeeded
751
+ payload = {
752
+ "dataset": dataset,
753
+ "version": version,
754
+ "split": split,
755
+ "operation": operation,
756
+ "results": results,
757
+ "succeeded": succeeded,
758
+ "failed": failed,
759
+ }
760
+ _emit(
761
+ payload,
762
+ results,
763
+ (("line", "LINE"), ("instance", "INSTANCE"), ("status", "STATUS"), ("error", "ERROR")),
764
+ output_format,
765
+ )
766
+ if failed:
767
+ raise _fail(
768
+ f"{failed}/{len(results)} tag updates failed",
769
+ "Fix the failed JSONL lines and retry; successful updates were not rolled back",
770
+ )
771
+
772
+
773
+ def _run_tag_mutation(
774
+ operation: str,
775
+ instance: Optional[str],
776
+ dataset: str,
777
+ split: str,
778
+ version: Optional[str],
779
+ expressions: Optional[List[str]],
780
+ keys: Optional[List[str]],
781
+ from_file: Optional[str],
782
+ environment: Optional[str],
783
+ metadata_model: Optional[str],
784
+ output_format: Optional[str],
785
+ ) -> None:
786
+ from .irepo_sdk import _reason
787
+
788
+ output_format = _fmt(output_format)
789
+ if from_file and (instance or expressions or keys):
790
+ raise _fail(
791
+ "--from-file cannot be combined with an instance ID, --tag, or --key",
792
+ "Put every instance and tag payload in the JSONL file",
793
+ 2,
794
+ )
795
+ if not from_file:
796
+ if not instance:
797
+ raise _fail("An instance ID is required without --from-file", "Pass INSTANCE or --from-file", 2)
798
+ if operation == "clear" and not keys:
799
+ raise _fail("--key is required for tag clear", "Repeat --key to clear multiple keys", 2)
800
+ if operation != "clear" and not expressions:
801
+ raise _fail("--tag is required", "Use --tag k=v or --tag k=v1,v2", 2)
802
+ try:
803
+ assignments = _parse_tag_assignments(expressions) if operation != "clear" else {}
804
+ clear_keys = [key.strip() for key in (keys or [])]
805
+ if operation == "clear" and not from_file and any(not key for key in clear_keys):
806
+ raise ValueError("clear keys must be nonempty")
807
+ except ValueError as exc:
808
+ hint = (
809
+ "Use --key to name a nonempty tag key"
810
+ if operation == "clear"
811
+ else "Use --tag k=v or --tag k=v1,v2"
812
+ )
813
+ raise _fail(str(exc), hint, 2) from exc
814
+
815
+ resolved_version = _version_value(version)
816
+ repo = _load_repo_or_exit()
817
+ env = _environment(environment)
818
+ method_name = f"{operation}_tags"
819
+ read_kwargs = _sdk_read_kwargs(
820
+ repo.instances,
821
+ method_name,
822
+ environment=env,
823
+ metadata_model=_metadata_model_for_split(metadata_model, split=split),
824
+ )
825
+ typer.echo(
826
+ "warning: tag update is not atomic; it replaces the whole map after reading, "
827
+ "so concurrent changes may be overwritten (last writer wins)",
828
+ err=True,
829
+ )
830
+ if from_file:
831
+ _run_tag_file(
832
+ repo, operation, dataset, resolved_version, split, from_file, read_kwargs, output_format
833
+ )
834
+ return
835
+
836
+ method = _tag_method(repo, operation, read_kwargs)
837
+ try:
838
+ if operation == "clear":
839
+ updated = method(
840
+ dataset, resolved_version, instance, clear_keys, split=split, **read_kwargs
841
+ )
842
+ else:
843
+ updated = method(
844
+ dataset, resolved_version, instance, assignments, split=split, **read_kwargs
845
+ )
846
+ except Exception as exc: # noqa: BLE001 - unified SDK-to-CLI error mapping
847
+ raise _fail(
848
+ f"Failed to {operation} tags for instance {instance}: {_reason(exc)}",
849
+ "Check --dataset/--version/--split, the instance ID and write permission",
850
+ ) from exc
851
+ _emit_detail(
852
+ _tag_payload(
853
+ dataset, resolved_version, split, instance, getattr(updated, "tags", {}) or {}
854
+ ),
855
+ output_format,
856
+ )
857
+
858
+
859
+ @tag_app.command("set")
860
+ def instance_tag_set(
861
+ instance: Optional[str] = typer.Argument(None, help="Instance id"),
862
+ dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
863
+ split: str = typer.Option(..., "--split", help="Split name"),
864
+ version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
865
+ tags: Optional[List[str]] = typer.Option(None, "--tag", help="Set k=v or k=v1,v2; repeatable"),
866
+ from_file: Optional[str] = typer.Option(None, "--from-file", help="JSONL: {instance_id, tags}"),
867
+ environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
868
+ metadata_model: Optional[str] = typer.Option(
869
+ None, "--metadata-model", help=_METADATA_MODEL_HELP
870
+ ),
871
+ output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
872
+ ):
873
+ """Set tag keys while preserving all unspecified keys, including language."""
874
+ _run_tag_mutation(
875
+ "set", instance, dataset, split, version, tags, None, from_file, environment,
876
+ metadata_model, output_format,
877
+ )
878
+
879
+
880
+ @tag_app.command("append")
881
+ def instance_tag_append(
882
+ instance: Optional[str] = typer.Argument(None, help="Instance id"),
883
+ dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
884
+ split: str = typer.Option(..., "--split", help="Split name"),
885
+ version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
886
+ tags: Optional[List[str]] = typer.Option(None, "--tag", help="Append k=v or k=v1,v2; repeatable"),
887
+ from_file: Optional[str] = typer.Option(None, "--from-file", help="JSONL: {instance_id, tags}"),
888
+ environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
889
+ metadata_model: Optional[str] = typer.Option(
890
+ None, "--metadata-model", help=_METADATA_MODEL_HELP
891
+ ),
892
+ output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
893
+ ):
894
+ """Append unique values; scalar values become arrays and duplicates are ignored."""
895
+ _run_tag_mutation(
896
+ "append", instance, dataset, split, version, tags, None, from_file, environment,
897
+ metadata_model, output_format,
898
+ )
899
+
900
+
901
+ @tag_app.command("remove")
902
+ def instance_tag_remove(
903
+ instance: Optional[str] = typer.Argument(None, help="Instance id"),
904
+ dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
905
+ split: str = typer.Option(..., "--split", help="Split name"),
906
+ version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
907
+ tags: Optional[List[str]] = typer.Option(None, "--tag", help="Remove k=v or k=v1,v2; repeatable"),
908
+ from_file: Optional[str] = typer.Option(None, "--from-file", help="JSONL: {instance_id, tags}"),
909
+ environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
910
+ metadata_model: Optional[str] = typer.Option(
911
+ None, "--metadata-model", help=_METADATA_MODEL_HELP
912
+ ),
913
+ output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
914
+ ):
915
+ """Remove values; an array with one remaining value stays an array."""
916
+ _run_tag_mutation(
917
+ "remove", instance, dataset, split, version, tags, None, from_file, environment,
918
+ metadata_model, output_format,
919
+ )
920
+
921
+
922
+ @tag_app.command("clear")
923
+ def instance_tag_clear(
924
+ instance: Optional[str] = typer.Argument(None, help="Instance id"),
925
+ dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
926
+ split: str = typer.Option(..., "--split", help="Split name"),
927
+ version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
928
+ keys: Optional[List[str]] = typer.Option(None, "--key", help="Delete an entire tag key; repeatable"),
929
+ from_file: Optional[str] = typer.Option(None, "--from-file", help="JSONL: {instance_id, keys}"),
930
+ environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
931
+ metadata_model: Optional[str] = typer.Option(
932
+ None, "--metadata-model", help=_METADATA_MODEL_HELP
933
+ ),
934
+ output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
935
+ ):
936
+ """Delete complete tag keys while preserving every other key."""
937
+ _run_tag_mutation(
938
+ "clear", instance, dataset, split, version, None, keys, from_file, environment,
939
+ metadata_model, output_format,
940
+ )
941
+
942
+
943
+ @tag_app.command("list")
944
+ def instance_tag_list(
945
+ instance: str = typer.Argument(..., help="Instance id"),
946
+ dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
947
+ split: str = typer.Option(..., "--split", help="Split name"),
948
+ version: Optional[str] = typer.Option(None, "--version", help=_VERSION_HELP),
949
+ environment: Optional[str] = typer.Option(None, "--environment", help=_ENVIRONMENT_HELP),
950
+ metadata_model: Optional[str] = typer.Option(
951
+ None, "--metadata-model", help=_METADATA_MODEL_HELP
952
+ ),
953
+ output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
954
+ ):
955
+ """List the complete tag map for one instance."""
956
+ from .irepo_sdk import _reason
957
+
958
+ output_format = _fmt(output_format)
959
+ resolved_version = _version_value(version)
960
+ repo = _load_repo_or_exit()
961
+ env = _environment(environment)
962
+ read_kwargs = _sdk_read_kwargs(
963
+ repo.instances,
964
+ "list_tags",
965
+ environment=env,
966
+ metadata_model=_metadata_model_for_split(metadata_model, split=split),
967
+ )
968
+ try:
969
+ method = _tag_method(repo, "list", read_kwargs)
970
+ tags = method(dataset, resolved_version, instance, split=split, **read_kwargs)
971
+ except typer.Exit:
972
+ raise
973
+ except Exception as exc: # noqa: BLE001 - unified SDK-to-CLI error mapping
974
+ raise _fail(
975
+ f"Failed to list tags for instance {instance}: {_reason(exc)}",
976
+ "Check --dataset/--version/--split, the instance ID and read permission",
977
+ ) from exc
978
+ _emit_detail(_tag_payload(dataset, resolved_version, split, instance, tags or {}), output_format)
979
+
980
+
433
981
  @instance_app.command("get")
434
982
  def instance_get(
435
983
  instance: str = typer.Argument(..., help="Instance id"),
@@ -555,6 +1103,11 @@ def _list_instance_objects(
555
1103
  "Check the instance, directory, environment and read permission",
556
1104
  ) from exc
557
1105
  payload = _model_dict(result)
1106
+ # objects 契约:空 files 与 truncated=false 必须显式输出(truncated 是分页
1107
+ # 完整性字段),不随通用 omitempty 清洗省略;其它字段的清洗策略不变。
1108
+ raw_objects = result.to_dict() if hasattr(result, "to_dict") else dict(result)
1109
+ payload["files"] = raw_objects.get("files") or []
1110
+ payload["truncated"] = raw_objects.get("truncated", False)
558
1111
  payload.update(instance=instance, path=path or ".")
559
1112
  rows = [dict(item, type="directory", size_bytes="") for item in payload.get("directories", [])]
560
1113
  rows.extend(dict(item, type="file") for item in payload.get("files", []))
@@ -984,17 +1537,14 @@ def instance_pull(
984
1537
  )
985
1538
 
986
1539
  repo = _load_repo_or_exit()
987
- from .repo_read_guard import pull_client
988
-
989
- try:
990
- client = pull_client(repo.instances, env)
991
- pull_options = oss_fallback_kwargs(repo, client, "pull", env)
992
- except (TypeError, ValueError, RuntimeError) as exc:
993
- raise _fail(
994
- str(exc), "Upgrade Dataset support: pip install --upgrade 'ap-client[dataset]'", 2
995
- ) from exc
1540
+ requested_options = {}
1541
+ if env != "auto": # auto 是 CLI 侧哨兵,与 _sdk_read_kwargs/_env_kwargs 同口径:不下发
1542
+ requested_options["environment"] = env
1543
+ # 与其它读路径同口径:显式环境异侧时关闭跨环境 OSS 回退
1544
+ requested_options.update(oss_fallback_kwargs(repo, repo.instances, "pull", env))
996
1545
  if resolved_path is not None:
997
- pull_options.update(_enhanced_options(client, "pull", {"path": resolved_path}))
1546
+ requested_options["path"] = resolved_path
1547
+ pull_options = _enhanced_options(repo.instances, "pull", requested_options)
998
1548
  try:
999
1549
  private_endpoint_reachable = _probe_pull_private_endpoint(repo, dataset)
1000
1550
  except Exception as exc: # noqa: BLE001
@@ -1011,7 +1561,9 @@ def instance_pull(
1011
1561
  staging = Path(tempfile.mkdtemp(prefix=f"ap-pull-{instance}-"))
1012
1562
  try:
1013
1563
  try:
1014
- written = client.pull(dataset, resolved, instance, staging, split, **pull_options)
1564
+ written = repo.instances.pull(
1565
+ dataset, resolved, instance, staging, split, **pull_options
1566
+ )
1015
1567
  except Exception as exc: # noqa: BLE001
1016
1568
  sdk_error_exit(exc, what=f"instance {instance}", stage="pull")
1017
1569
  staged = _place_under_target(Path(str(written)), staging / instance)
@@ -29,6 +29,16 @@ class OssOperationError(RuntimeError):
29
29
  """A failed operation with a safe user-facing explanation."""
30
30
 
31
31
 
32
+ class OssPathNotFound(OssOperationError):
33
+ """A positively observed missing source, without retaining upstream details."""
34
+
35
+ def __init__(self, *, local: bool = False):
36
+ super().__init__("No such file or directory" if local else "No such object")
37
+ # Existing optional-target checks (mkdir/overwrite) still recognize absence.
38
+ self.code = None if local else "NoSuchKey"
39
+ self.status = None if local else 404
40
+
41
+
32
42
  def _relative(value: str, *, allow_empty: bool = False) -> str:
33
43
  if not isinstance(value, str) or (not value and not allow_empty):
34
44
  raise OssUsageError("A non-empty remote path is required")
@@ -239,6 +249,7 @@ class _RoutingBucket:
239
249
  return value
240
250
 
241
251
  def call(*args, **kwargs):
252
+ missing = False
242
253
  try:
243
254
  if self.owner.payer and name not in ("sign_url",):
244
255
  headers = dict(kwargs.get("headers") or {})
@@ -247,7 +258,16 @@ class _RoutingBucket:
247
258
  return value(*args, **kwargs)
248
259
  except Exception as exc:
249
260
  self.owner.invalidate_network(exc, self._ossutil_endpoint)
250
- raise
261
+ native = getattr(getattr(self.owner.oss, "exceptions", None), "NoSuchKey", None)
262
+ status = getattr(exc, "status", None)
263
+ if (isinstance(native, type) and isinstance(exc, native)
264
+ and (status is None or type(status) is int and status == 404)):
265
+ missing = True
266
+ else:
267
+ raise
268
+ if missing:
269
+ # Outside except: neither the raw response nor its cause is retained.
270
+ raise OssPathNotFound()
251
271
 
252
272
  return call
253
273
 
@@ -473,15 +493,26 @@ class OssFiles:
473
493
  marker: str = "",
474
494
  include: tuple[str, ...] = (),
475
495
  exclude: tuple[str, ...] = (),
496
+ file_candidate: RemotePath | None = None,
476
497
  ) -> dict:
477
498
  # A path grant lists descendants at a slash boundary, never sibling keys.
478
499
  remote = self.binding.resolve_key(remote.key, directory=True)
500
+ if file_candidate is not None and (
501
+ not isinstance(file_candidate, RemotePath)
502
+ # RemotePath is already decoded; preserve literal percent bytes.
503
+ or file_candidate != self.binding.resolve_key(file_candidate.key)
504
+ or remote.key != file_candidate.key + "/"
505
+ ):
506
+ raise OssUsageError("File listing candidate must match the requested directory")
507
+ resumed = bool(marker)
479
508
  if marker:
480
509
  marker = self.resolve(marker, prefix=True).key
481
510
  if not marker.startswith(remote.key):
482
511
  raise OssUsageError("--marker must be within the listed prefix")
512
+ start_marker = marker
483
513
  bucket = self.bucket(remote.key, "reader", list_only=True)
484
514
  entries = []
515
+ observed = False
485
516
  while limit is None or len(entries) < limit:
486
517
  result = bucket.list_objects(
487
518
  prefix=remote.key,
@@ -489,6 +520,7 @@ class OssFiles:
489
520
  marker=marker,
490
521
  max_keys=min(1000, limit - len(entries)) if limit is not None else 1000,
491
522
  )
523
+ observed = observed or bool(result.object_list or result.prefix_list)
492
524
  for item in result.object_list:
493
525
  path = self._listed_path(item.key, remote.key)
494
526
  if not matches(item.key.removeprefix(self.binding.prefix), include, exclude):
@@ -507,6 +539,20 @@ class OssFiles:
507
539
  if matches(key.removeprefix(self.binding.prefix), include, exclude):
508
540
  entries.append({"path": path, "type": "directory"})
509
541
  if not result.is_truncated:
542
+ if not observed and remote.key != self.binding.prefix:
543
+ if resumed and self._prefix_exists(bucket, remote.key):
544
+ pass
545
+ elif file_candidate is not None:
546
+ row = self._exact_file_entry(file_candidate)
547
+ if row is None:
548
+ raise OssPathNotFound()
549
+ # Filters apply to the exact file too, without erasing existence.
550
+ if (not start_marker or file_candidate.key > start_marker) and matches(
551
+ row["path"], include, exclude
552
+ ):
553
+ entries.append(row)
554
+ else:
555
+ raise OssPathNotFound()
510
556
  return {"entries": entries, "is_truncated": False, "next_marker": ""}
511
557
  next_marker = result.next_marker
512
558
  if not next_marker or next_marker == marker:
@@ -518,6 +564,37 @@ class OssFiles:
518
564
  "next_marker": self.binding.uri_for_key(marker),
519
565
  }
520
566
 
567
+ def _prefix_exists(self, bucket, prefix: str) -> bool:
568
+ """One list-only observation, independent of output filters/resume marker."""
569
+ result = bucket.list_objects(prefix=prefix, delimiter="", marker="", max_keys=1)
570
+ if len(result.object_list) + len(result.prefix_list) > 1:
571
+ raise OssOperationError("OSS returned an invalid path existence listing")
572
+ for item in result.object_list:
573
+ self._listed_path(item.key, prefix)
574
+ for key in result.prefix_list:
575
+ self._listed_path(key, prefix)
576
+ if not result.object_list and not result.prefix_list and result.is_truncated:
577
+ raise OssOperationError("OSS listing could not establish path existence")
578
+ return bool(result.object_list or result.prefix_list)
579
+
580
+ def _exact_file_entry(self, remote: RemotePath) -> dict | None:
581
+ # A directory-scoped credential cannot authorize its sibling exact file.
582
+ bucket = self.bucket(remote.key, "reader", list_only=True)
583
+ result = bucket.list_objects(prefix=remote.key, delimiter="", marker="", max_keys=1)
584
+ if result.prefix_list or len(result.object_list) > 1:
585
+ raise OssOperationError("OSS returned an invalid exact-file listing")
586
+ if not result.object_list:
587
+ if result.is_truncated:
588
+ raise OssOperationError("OSS listing could not establish path existence")
589
+ return None
590
+ item = result.object_list[0]
591
+ path = self._listed_path(item.key, remote.key)
592
+ # OSS lists keys in lexical order; the exact prefix sorts before siblings.
593
+ if item.key != remote.key:
594
+ return None
595
+ return {"path": path, "type": "file", "size": item.size,
596
+ "etag": item.etag, "last_modified": item.last_modified}
597
+
521
598
  def _listed_path(self, key: str, prefix: str) -> str:
522
599
  if not key.startswith(prefix):
523
600
  raise OssOperationError("OSS listing returned an object outside the requested prefix")
@@ -852,10 +929,15 @@ class OssFiles:
852
929
 
853
930
  def _objects(self, bucket, prefix: str):
854
931
  token = ""
932
+ observed = False
855
933
  while True:
856
934
  result = bucket.list_objects_v2(prefix=prefix, continuation_token=token, max_keys=1000)
935
+ for key in getattr(result, "prefix_list", ()):
936
+ self._listed_path(key, prefix)
937
+ observed = True
857
938
  for item in result.object_list:
858
939
  self._listed_path(item.key, prefix)
940
+ observed = True
859
941
  if item.key != prefix and not item.key.endswith("/"):
860
942
  yield item.key
861
943
  if not result.is_truncated:
@@ -864,6 +946,8 @@ class OssFiles:
864
946
  if not new_token or new_token == token:
865
947
  raise OssOperationError("OSS returned an invalid pagination token")
866
948
  token = new_token
949
+ if not observed and prefix != self.binding.prefix:
950
+ raise OssPathNotFound()
867
951
 
868
952
  def cp(
869
953
  self,
@@ -905,7 +989,16 @@ class OssFiles:
905
989
  )
906
990
  if direction == "upload":
907
991
  local = Path(src)
908
- if local.is_symlink() or not (local.is_dir() if recursive else local.is_file()):
992
+ if local.is_symlink():
993
+ raise OssUsageError("Upload source must be a regular file or a directory with -r")
994
+ absent = False
995
+ try:
996
+ mode = local.stat().st_mode
997
+ except FileNotFoundError:
998
+ absent = True
999
+ if absent:
1000
+ raise OssPathNotFound(local=True)
1001
+ if not (stat.S_ISDIR(mode) if recursive else stat.S_ISREG(mode)):
909
1002
  raise OssUsageError("Upload source must be a regular file or a directory with -r")
910
1003
  if self.byte_range is not None and (direction != "download" or recursive):
911
1004
  raise OssUsageError("--range requires a single-object download")
@@ -1035,11 +1128,16 @@ class OssFiles:
1035
1128
  return False
1036
1129
  if not matches(path, include, exclude):
1037
1130
  return False
1038
- modified = (
1039
- source.stat().st_mtime
1040
- if direction == "upload"
1041
- else bucket.head_object(source.key).last_modified
1042
- )
1131
+ absent = False
1132
+ try:
1133
+ modified = (source.stat().st_mtime if direction == "upload"
1134
+ else bucket.head_object(source.key).last_modified)
1135
+ except FileNotFoundError:
1136
+ if direction != "upload":
1137
+ raise
1138
+ absent = True
1139
+ if absent:
1140
+ raise OssPathNotFound(local=True)
1043
1141
  if (
1044
1142
  start_time is not None
1045
1143
  and modified < start_time
@@ -983,6 +983,9 @@ def profile_versions(
983
983
  "updated_at",
984
984
  )
985
985
  current_item = {k: current[k] for k in fields if k in current}
986
+ # Both arrays are required by the summary contract; older GETs may omit them.
987
+ current_item["parents"] = current.get("parents") or []
988
+ current_item["auto_follow_parents"] = current.get("auto_follow_parents") or []
986
989
  result[items_key] = [current_item] + items
987
990
  # Adjust total count (+1 for current version)
988
991
  if "pagination" in result:
@@ -4,7 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from urllib.parse import urlsplit
6
6
 
7
- from ap_client.api import APIError
7
+ from ap_client.api import APIError, format_api_error_diagnostics
8
8
 
9
9
 
10
10
  def source_label(source: dict | str) -> str:
@@ -118,4 +118,5 @@ def format_profile_error(exc: APIError) -> str | None:
118
118
  if isinstance(issues, list):
119
119
  lines.extend(issue_lines(issues))
120
120
  lines.append(f"request_id: {exc.request_id}")
121
+ lines.extend(format_api_error_diagnostics(exc, separator=": "))
121
122
  return "\n".join(lines)
@@ -27,8 +27,9 @@ def profile_output(value: Any) -> Any:
27
27
  result = dict(value)
28
28
  if isinstance(result.get("parents"), list):
29
29
  result["parents"] = [parent_reference(parent) for parent in result["parents"]]
30
- if isinstance(result.get("data"), list):
31
- result["data"] = [profile_output(row) for row in result["data"]]
30
+ for items_key in ("data", "items", "versions"):
31
+ if isinstance(result.get(items_key), list):
32
+ result[items_key] = [profile_output(row) for row in result[items_key]]
32
33
  if isinstance(result.get("changes"), list):
33
34
  result["changes"] = []
34
35
  for change in value["changes"]:
@@ -3,8 +3,6 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import inspect
6
- from copy import copy
7
- from functools import partial
8
6
  from typing import Any
9
7
 
10
8
  STORAGE_SIDES = {
@@ -15,41 +13,6 @@ STORAGE_SIDES = {
15
13
  }
16
14
 
17
15
 
18
- class _PullMetadataProfile:
19
- def __init__(self, profile: Any, environment: str) -> None:
20
- self._profile = profile
21
- self.dataset_environment = environment
22
-
23
- def __getattr__(self, name: str) -> Any:
24
- return getattr(self._profile, name)
25
-
26
-
27
- def pull_client(client: Any, environment: str) -> Any:
28
- """Scope SDK 1.4.x pull metadata reads without changing its storage binding.
29
-
30
- pull has no environment argument, although its registry supports one.
31
- Copy both objects so other operations on the Repo keep their original context.
32
- """
33
- if environment == "auto":
34
- return client
35
- registry = getattr(client, "_reg", None)
36
- get = getattr(registry, "get", None)
37
- if not callable(get) or "environment" not in inspect.signature(get).parameters:
38
- raise ValueError(
39
- "The installed instance-repo cannot scope pull metadata reads; "
40
- "upgrade 'ap-client[dataset]'"
41
- )
42
- scoped = copy(client)
43
- scoped._reg = copy(registry)
44
- scoped._reg.get = partial(get, environment=environment)
45
- profile = getattr(client, "_p", None)
46
- if profile is not None:
47
- # Directory manifests also use list_objects, which reads its environment
48
- # from the profile. Delegate all storage/layout settings unchanged.
49
- scoped._p = _PullMetadataProfile(profile, environment)
50
- return scoped
51
-
52
-
53
16
  def oss_fallback_kwargs(repo: Any, client: Any, method: str, environment: str) -> dict:
54
17
  """Allow API reads across environments; disable unsafe storage fallback.
55
18
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "ap-client"
7
- version = "0.8.0.dev4"
7
+ version = "0.8.1.dev0"
8
8
  description = "Agent Platform API Client & CLI"
9
9
  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" }
10
10
  requires-python = ">=3.10"
@@ -19,10 +19,10 @@ dependencies = [
19
19
 
20
20
  [project.optional-dependencies]
21
21
  dataset = [
22
- "instance-repo[oss]>=1.4.6,<2.0.0",
22
+ "instance-repo[oss]==1.4.8.dev0",
23
23
  ]
24
24
  all = [
25
- "instance-repo[oss]>=1.4.6,<2.0.0",
25
+ "instance-repo[oss]==1.4.8.dev0",
26
26
  ]
27
27
 
28
28
  [project.scripts]