ap-client 0.8.0.dev5__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.dev5 → ap_client-0.8.1.dev0}/PKG-INFO +3 -3
  2. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/instance_commands.py +557 -4
  3. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/pyproject.toml +3 -3
  4. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/__init__.py +0 -0
  5. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/akpool_commands.py +0 -0
  6. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/api.py +0 -0
  7. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/cli.py +0 -0
  8. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/config.py +0 -0
  9. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/dataset_commands.py +0 -0
  10. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/dataset_name.py +0 -0
  11. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/dataset_register.py +0 -0
  12. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/dfs_commands.py +0 -0
  13. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/exporter.py +0 -0
  14. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/fs_commands.py +0 -0
  15. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/fs_storage.py +0 -0
  16. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/fs_transfer.py +0 -0
  17. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/instance_options.py +0 -0
  18. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/irepo_sdk.py +0 -0
  19. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/managed_ak.py +0 -0
  20. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/manifest_view.py +0 -0
  21. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/ossutil_hash.py +0 -0
  22. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/ossutil_io.py +0 -0
  23. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_all.py +0 -0
  24. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_cli.py +0 -0
  25. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_display.py +0 -0
  26. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_cascade_state.py +0 -0
  27. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_commands.py +0 -0
  28. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_diagnostics.py +0 -0
  29. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_display.py +0 -0
  30. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/profile_references.py +0 -0
  31. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/repo_read_guard.py +0 -0
  32. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/share_api.py +0 -0
  33. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/split_publish.py +0 -0
  34. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/submission_metadata.py +0 -0
  35. {ap_client-0.8.0.dev5 → ap_client-0.8.1.dev0}/ap_client/tbb.py +0 -0
  36. {ap_client-0.8.0.dev5 → 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.dev5
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.7; 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.7; 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.
@@ -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", []))
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "ap-client"
7
- version = "0.8.0.dev5"
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.7,<2.0.0",
22
+ "instance-repo[oss]==1.4.8.dev0",
23
23
  ]
24
24
  all = [
25
- "instance-repo[oss]>=1.4.7,<2.0.0",
25
+ "instance-repo[oss]==1.4.8.dev0",
26
26
  ]
27
27
 
28
28
  [project.scripts]