ap-client 0.3.2.dev1__tar.gz → 0.4.0__tar.gz

{ap_client-0.3.2.dev1 → ap_client-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.3.2.dev1
+Version: 0.4.0
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
@@ -9,9 +9,9 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: websockets>=13.0
 Provides-Extra: all
-Requires-Dist: instance-repo[oss]>=0.7.0; extra == 'all'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.2; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]>=0.7.0; extra == 'dataset'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.2; extra == 'dataset'
 Description-Content-Type: text/markdown
 
 A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.

{ap_client-0.3.2.dev1 → ap_client-0.4.0}/ap_client/api.py

@@ -283,6 +283,36 @@ def _ensure_next_token_honored(response: dict, *, next_token: Optional[str], end
         )
 
 
+def _openapi_supports_instance_range(document: Any) -> bool:
+    """Check the actual POST /jobs JSON request schema, failing closed on unknown shapes."""
+
+    def resolve(node: Any) -> dict:
+        seen = set()
+        while isinstance(node, dict) and "$ref" in node:
+            ref = node["$ref"]
+            if not isinstance(ref, str) or not ref.startswith("#/") or ref in seen:
+                return {}
+            seen.add(ref)
+            node = document
+            for part in ref[2:].split("/"):
+                if not isinstance(node, dict):
+                    return {}
+                node = node.get(part.replace("~1", "/").replace("~0", "~"))
+        return node if isinstance(node, dict) else {}
+
+    try:
+        path = resolve(document["paths"]["/jobs"])
+        body = resolve(path["post"]["requestBody"])
+        schema = resolve(body["content"]["application/json"]["schema"])
+        properties = schema["properties"]
+    except (KeyError, TypeError):
+        return False
+    if not isinstance(properties, dict) or "instance_range" not in properties:
+        return False
+    field = resolve(properties["instance_range"])
+    return bool(field) and field.get("readOnly") is not True
+
+
 def _secret_ws_params(workspace_id: Optional[str]) -> Optional[dict]:
     """Build the ``?workspace_id=`` query for name-addressed secret endpoints.
 
@@ -294,6 +324,25 @@ def _secret_ws_params(workspace_id: Optional[str]) -> Optional[dict]:
     return {"workspace_id": workspace_id} if workspace_id else None
 
 
+def _split_paged(payload: Any) -> tuple[list[dict], dict]:
+    """Split a ``PagedSuccess`` envelope into ``(records, pagination)``.
+
+    ``PagedSuccess`` is ``{code,message,data:[...],pagination:{total,page,page_size}}``.
+    A bare list (or a null ``data``) yields an empty pagination dict so callers
+    can render results without probing the response shape.
+    """
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)], {}
+    if not isinstance(payload, dict):
+        return [], {}
+    records = payload.get("data")
+    pagination = payload.get("pagination")
+    return (
+        [item for item in (records or []) if isinstance(item, dict)],
+        pagination if isinstance(pagination, dict) else {},
+    )
+
+
 class APIClient:
     """Agent Platform API client."""
 
@@ -458,6 +507,28 @@ class APIClient:
         """Send a GET request."""
         return self._request("GET", path, params=params, timeout=timeout)
 
+    def ensure_profile_range_supported(self, timeout: TimeoutType = None) -> None:
+        """Check the target cluster before sending a profile range request.
+
+        Do not cache this across submissions: the server may have been rolled back.
+        Use the normal authenticated, cluster-scoped request path.
+        """
+        try:
+            document = self._get(
+                "/openapi.json", timeout=timeout if timeout is not None else (10, 30)
+            )
+        except APIError as exc:
+            raise ValueError(
+                "Cannot verify server support for --profile --range via /openapi.json; "
+                f"no jobs were submitted. Check AP_BASE_URL, AP_CLUSTER and server access. {exc}"
+            ) from exc
+        if not _openapi_supports_instance_range(document):
+            raise ValueError(
+                "Cannot confirm server support for --profile --range: /openapi.json must "
+                "declare instance_range in the POST /jobs JSON request schema. "
+                "No jobs were submitted. Upgrade the target server before using --range."
+            )
+
     def _post(self, path: str, data: Any, timeout: TimeoutType = None) -> Any:
         """Send a POST request."""
         from .managed_ak import parameter_ak_ids, require_parameter_ak_ack
@@ -714,8 +785,35 @@ class APIClient:
         return self._get(f"/templates/{quote(name)}", params=params)
 
     def list_benchmarks(self) -> list:
-        """List all active benchmarks from the local benchmark registry."""
-        return self._get("/benchmarks")
+        """List all benchmarks from the central registry, preserving legacy IDs."""
+        benchmarks = []
+        page = 1
+        page_size = 200
+        # 与 CLI dataset list 的自动翻页同口径:100 页上限,防分页异常导致死循环。
+        max_pages = 100
+        while page <= max_pages:
+            payload = self._get(
+                "/apis/v1/benchmarks", params={"page": page, "page_size": page_size}
+            )
+            records, pagination = _split_paged(payload)
+            for record in records:
+                item = dict(record)
+                if "source_id" in item:
+                    item.setdefault("id", item["source_id"])
+                benchmarks.append(item)
+            if not records or not pagination:
+                break
+            try:
+                total = int(pagination.get("total"))
+            except (TypeError, ValueError):
+                total = None
+            if total is not None:
+                if len(benchmarks) >= total:
+                    break
+            elif len(records) < page_size:
+                break
+            page += 1
+        return benchmarks
 
     def get_benchmark(self, name: str) -> dict:
         """Get a single benchmark by exact name."""
@@ -850,7 +948,16 @@ class APIClient:
             "instance_ids": all_instance_ids,
         }
 
-    # ==================== Meta operations ====================
+    # ==================== Dataset series (apiserver dataset domain) ====================
+    #
+    # 这一节对接 Go apiserver 的 dataset 领域(/apis/v1/datasets/...),与上面
+    # ossdata 目录的 /api/datasets 路由完全无关。
+    #
+    # **dataset 领域的控制面读写全部在 InstanceRepo SDK 上**(见
+    # docs/ap-cli-dataset-refactor-design.md §9.5):迁移期加进这里的 registry 方法、
+    # 以及最后三条"push 前检查 + publish-status"的旧读,都已随迁移删除。
+    # 本文件现在只服务旧 ossdata 路径(`dataset list --legacy`、弃用的
+    # `dataset versions/instances`、`job create --dataset`)。
 
     def list_meta_models(self) -> dict:
         """模型词表（apiserver 权威源 GET /apis/v1/meta-models，返回 {items:[...]}）。"""
@@ -1042,6 +1149,7 @@ class APIClient:
         benchmark: Optional[str] = None,
         experiment: Optional[str] = None,
         ak_id: Optional[str] = None,
+        instance_range: Optional[str] = None,
     ) -> dict:
         """Create a job."""
         body = self.build_create_job_body(
@@ -1079,6 +1187,7 @@ class APIClient:
             batch_size=batch_size,
             trials=trials,
             resource_profile_id=resource_profile_id,
+            instance_range=instance_range,
             meta_model=meta_model,
             meta_job_type=meta_job_type,
             upstream_platform=upstream_platform,
@@ -1150,6 +1259,7 @@ class APIClient:
         benchmark: Optional[str] = None,
         experiment: Optional[str] = None,
         ak_id: Optional[str] = None,
+        instance_range: Optional[str] = None,
     ) -> dict:
         """Build the /jobs request body for job creation."""
         _validate_credential_source_selection(
@@ -1243,6 +1353,8 @@ class APIClient:
             body["profile_version"] = profile_version
         if instances is not None:
             body["instances"] = instances
+        if instance_range is not None:
+            body["instance_range"] = instance_range
         if dataset is not None:
             body["dataset"] = dataset
         if batch_size is not None:
@@ -2580,6 +2692,8 @@ class APIClient:
         spec: dict,
         description: str = "",
         account_pool: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        tags: Optional[list[str]] = None,
     ) -> dict:
         """Create a new submission profile."""
         body: dict = {"name": name, "spec": spec}
@@ -2587,6 +2701,10 @@ class APIClient:
             body["description"] = description
         if account_pool is not None:
             body["account_pool"] = account_pool
+        if metadata is not None:
+            body["metadata"] = metadata
+        if tags is not None:
+            body["tags"] = tags
         return self._post(self._PROFILES_BASE, body)
 
     def list_profiles(
@@ -2594,6 +2712,11 @@ class APIClient:
         *,
         keyword: Optional[str] = None,
         template: Optional[str] = None,
+        dataset: Optional[str] = None,
+        scaffold: Optional[str] = None,
+        owner: Optional[str] = None,
+        profile_ids: Optional[list[str]] = None,
+        tags: Optional[list[str]] = None,
         show_all: bool = False,
         page: int = 1,
         page_size: int = 20,
@@ -2603,6 +2726,12 @@ class APIClient:
         Args:
             keyword: Filter by name keyword.
             template: Filter by template name.
+            dataset: Filter by metadata dataset using a case-insensitive substring match.
+            scaffold: Filter by metadata scaffold using a case-insensitive substring match.
+            owner: Filter by an explicit owner ID instead of the current caller.
+            profile_ids: Filter by profile IDs (maximum 100; mutually exclusive
+                with ``keyword``).
+            tags: Filter by profile tags using AND semantics (maximum 10).
             show_all: If False (default), return only profiles owned by the
                 current caller — the owner filter is resolved client-side
                 via the configured API key, mirroring how the web console
@@ -2612,21 +2741,40 @@ class APIClient:
             page_size: Number of items per page.
 
         Raises:
-            ConfigurationError: When no API key is configured. Listing
-                profiles always requires authentication, regardless of
-                ``show_all``. Also raised when ``show_all`` is False but
-                the API key cannot be resolved to a user_id.
+            ConfigurationError: When the default Mine view needs an API key
+                but none is configured, or the key cannot be resolved.
+            ValueError: When mutually exclusive filters are combined.
         """
-        if not self.config.token_key:
-            raise ConfigurationError(
-                "Cannot list profiles without authentication. Set AP_API_KEY environment variable."
-            )
+        if keyword and profile_ids:
+            raise ValueError("profile_ids and keyword are mutually exclusive")
+        if owner and show_all:
+            raise ValueError("owner and show_all are mutually exclusive")
+        if profile_ids and len(profile_ids) > 100:
+            raise ValueError("profile_ids accepts at most 100 values")
+        if tags and len(tags) > 10:
+            raise ValueError("tags accepts at most 10 values")
+
         params: dict = {"page": page, "page_size": page_size}
         if keyword:
             params["keyword"] = keyword
         if template:
             params["template"] = template
-        if not show_all:
+        if dataset:
+            params["dataset"] = dataset
+        if scaffold:
+            params["scaffold"] = scaffold
+        if profile_ids:
+            params["profile_ids"] = ",".join(profile_ids)
+        if tags:
+            params["tags"] = ",".join(tags)
+        if owner:
+            params["owner"] = owner
+        elif not show_all:
+            if not self.config.token_key:
+                raise ConfigurationError(
+                    "Cannot list own profiles without authentication. "
+                    "Set AP_API_KEY environment variable or use --all."
+                )
             try:
                 owner_id = self._resolve_self_user_id()
             except APIError as exc:
@@ -2642,6 +2790,27 @@ class APIClient:
             params["owner"] = owner_id
         return self._get(self._PROFILES_BASE, params=params)
 
+    def list_profile_tags(
+        self,
+        *,
+        query: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> dict:
+        """List distinct tags for SDK consumers building tag selectors or completion UIs."""
+        params: dict = {}
+        if query:
+            params["q"] = query
+        if limit is not None:
+            params["limit"] = limit
+        return self._get(f"{self._PROFILES_BASE}/tags", params=params)
+
+    def replace_profile_tags(self, profile_id: str, tags: list[str]) -> dict:
+        """Replace all tags on a submission profile; an empty list clears them."""
+        return self._put(
+            f"{self._PROFILES_BASE}/{quote(profile_id)}/tags",
+            {"tags": tags},
+        )
+
     def get_profile(self, id_or_name: str, *, version: Optional[int] = None) -> dict:
         """Get a submission profile by ID or name.
 
@@ -2658,6 +2827,7 @@ class APIClient:
         spec: dict,
         description: str = "",
         account_pool: Optional[str] = None,
+        metadata: Optional[dict] = None,
     ) -> dict:
         """Update a submission profile, preserving an omitted default Pool."""
         body: dict = {"name": name, "spec": spec}
@@ -2665,6 +2835,8 @@ class APIClient:
             body["description"] = description
         if account_pool is not None:
             body["account_pool"] = account_pool
+        if metadata is not None:
+            body["metadata"] = metadata
         return self._put(f"{self._PROFILES_BASE}/{quote(profile_id)}", body)
 
     def delete_profile(self, profile_id: str) -> dict:

{ap_client-0.3.2.dev1 → ap_client-0.4.0}/ap_client/cli.py

@@ -24,8 +24,10 @@ from ap_client.api import (
     set_verbose_override,
 )
 from ap_client.config import ENV_VAR_SPECS, ConfigurationError, _parse_bool, normalize_output_format
+from ap_client.dataset_commands import register as _register_dataset_commands
 from ap_client.exporter import export_group, export_job
-from ap_client.irepo_commands import register as _register_dataset_repo
+from ap_client.fs_commands import register as _register_fs_commands
+from ap_client.instance_commands import register as _register_instance_commands
 from ap_client.managed_ak import (
     ManagedAKProtocolError,
     require_managed_ak_ack,
@@ -139,7 +141,7 @@ app.add_typer(config_app, name="config")
 app.add_typer(template_app, name="template")
 app.add_typer(dataset_app, name="dataset")
 app.add_typer(job_app, name="job")
-app.add_typer(job_tbb_app, name="job-tbb")
+job_app.add_typer(job_tbb_app, name="tbb")
 app.add_typer(group_app, name="group")
 app.add_typer(plan_app, name="plan")
 app.add_typer(datasource_app, name="datasource")
@@ -153,8 +155,11 @@ app.add_typer(meta_job_type_app, name="meta-job-type")
 app.add_typer(benchmark_app, name="benchmark")
 app.add_typer(checkpoint_app, name="checkpoint")
 
-# ap dataset repo:透传 instance_repo CLI(见 ap_client/irepo_commands.py)
-_register_dataset_repo(dataset_app)
+# Dataset 领域(见 docs/ap-cli-dataset-refactor-design.md):
+# ap dataset version/split/access 嵌套在 dataset 下;instance/fs 是一等资源。
+_register_dataset_commands(dataset_app)
+_register_instance_commands(app)
+_register_fs_commands(app)
 
 _PAI_RUNTIME_ENV_TAGS: tuple[tuple[str, str], ...] = (
     ("DLC_JOB_ID", "dlc_job_id"),
@@ -810,26 +815,43 @@ def _print_json_block(data: Any) -> None:
     typer.echo(json.dumps(data, ensure_ascii=False, indent=2))
 
 
+def _format_nested_detail(value: Any) -> str:
+    """Nested dict/list for detail views: compact one-liner, pretty JSON when long.
+
+    A detail view must not silently drop data - the manifest in ``ap instance
+    get`` used to be cut mid-JSON by the one-liner preview.
+    """
+    compact = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if len(compact) <= _PLAIN_VALUE_PREVIEW:
+        return compact
+    return json.dumps(value, ensure_ascii=False, indent=2)
+
+
 def _print_detail(data: object) -> None:
     """Render a single object as an aligned key/value detail view.
 
     Top-level scalars become key/value rows (``image`` fields shortened); nested
-    dict/list fields are shown as compact one-liners. Falls back to JSON for
+    dict/list fields are shown as compact one-liners, or pretty-printed across
+    multiple lines when the one-liner would not fit. Falls back to JSON for
     non-dict payloads.
     """
     if not isinstance(data, dict):
         _print_json(data)
         return
-    scalar_rows: list[tuple[str, Any]] = []
-    nested_rows: list[tuple[str, Any]] = []
+    rows: list[tuple[str, str]] = []
     for key, value in data.items():
         if isinstance(value, (dict, list)):
-            nested_rows.append((key, value))
+            rows.append((key, _format_nested_detail(value)))
         elif key == "image" and isinstance(value, str):
-            scalar_rows.append((key, _shorten_image(value)))
+            rows.append((key, _shorten_image(value)))
         else:
-            scalar_rows.append((key, value))
-    _print_key_values(scalar_rows + nested_rows, skip_empty=False)
+            rows.append((key, _format_plain_value(value, max_len=0)))
+    width = max((len(label) for label, _text in rows), default=0)
+    indent = " " * (width + 4)
+    for label, text in rows:
+        if "\n" in text:
+            text = text.replace("\n", f"\n{indent}")
+        typer.echo(f"  {label.ljust(width)}: {text}")
 
 
 def _print_template_get_plain(t: dict) -> None:
@@ -939,7 +961,7 @@ def _print_field_value(value: Any, output_format: str) -> None:
     _print_formatted(value, "json" if output_format == "plain" else output_format)
 
 
-def _format_plain_value(value: Any) -> str:
+def _format_plain_value(value: Any, *, max_len: int = _PLAIN_VALUE_PREVIEW) -> str:
     if value is None:
         return ""
     if isinstance(value, (dict, list)):
@@ -947,9 +969,9 @@ def _format_plain_value(value: Any) -> str:
     else:
         text = str(value)
     text = text.replace("\r", "\\r").replace("\n", "\\n")
-    if len(text) <= _PLAIN_VALUE_PREVIEW:
+    if not max_len or len(text) <= max_len:
         return text
-    return f"{text[: _PLAIN_VALUE_PREVIEW - 3]}..."
+    return f"{text[: max_len - 3]}..."
 
 
 def _print_key_values(rows: list[tuple[str, Any]], *, skip_empty: bool = True) -> None:
@@ -2068,24 +2090,17 @@ def template_fetch(
 
 # ==================== Dataset operations ====================
 
-
-@dataset_app.command("list")
-def dataset_list(
-    search: Optional[str] = typer.Argument(None, help="Search keyword"),
-    output_format: str = typer.Option(
-        None,
-        "--format",
-        help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
-    ),
-):
-    """List all datasets."""
-    output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
-    result = client.list_all_datasets(search)
-    if output_format == "table":
-        _print_records_table(result)
-    else:
-        _print_formatted(result, output_format)
+# 设计 §6 / 上游 §13.2:`ap dataset versions` 与 `ap dataset instances` 行为保持不变
+# (仍打 ossdata 路由,`ap job create` 的配套流程依赖它们),只追加固定弃用文案。
+# 文案**只写 stderr**——JSON/YAML 的 stdout 必须仍可被 json.loads 直接消费。
+_DATASET_VERSIONS_DEPRECATION = (
+    "Warning: `ap dataset versions` is deprecated.\n"
+    "Use `ap dataset version list --dataset <dataset>` instead."
+)
+_DATASET_INSTANCES_DEPRECATION = (
+    "Warning: `ap dataset instances` is deprecated.\n"
+    "Use `ap instance list --dataset <dataset> --split <split> [--version <version>]` instead."
+)
 
 
 @dataset_app.command("versions")
@@ -2097,8 +2112,9 @@ def dataset_versions(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List dataset versions."""
+    """List dataset versions (deprecated: use 'ap dataset version list')."""
     output_format = _normalize_output_format(output_format, keep_table=True)
+    _emit_progress(_DATASET_VERSIONS_DEPRECATION)
     client = get_client()
     versions = client.list_dataset_versions(dataset)
     if output_format == "table":
@@ -2118,8 +2134,9 @@ def dataset_instances(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List dataset instances."""
+    """List dataset instances (deprecated: use 'ap instance list')."""
     output_format = _normalize_output_format(output_format, keep_table=True)
+    _emit_progress(_DATASET_INSTANCES_DEPRECATION)
     client = get_client()
     result = client.list_all_dataset_instances(dataset_version)
     if output_format == "table":
@@ -2424,7 +2441,7 @@ def job_tbb_list(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ) -> None:
-    """List pipeline jobs created by ap job-tbb run."""
+    """List pipeline jobs created by ap job tbb run."""
     output_format = _normalize_output_format(output_format, keep_table=True)
     selected_columns = (
         _parse_columns_option(columns) if output_format in {"plain", "table"} else None
@@ -2804,7 +2821,8 @@ def job_create(
         "--range",
         help=(
             "Select a positional subset of instance IDs. Supports END, START,END, "
-            "START,END,STEP. Also accepts START:END[:STEP] and range(START, END, STEP)"
+            "START,END,STEP. Also accepts START:END[:STEP] and range(START, END, STEP). "
+            "With --profile, the server slices instances before trials expansion"
         ),
     ),
     exclude_instance_ids: Optional[str] = typer.Option(
@@ -3261,9 +3279,12 @@ def job_create(
                 "--profile is incompatible with --params-list (profile expands params server-side)"
             )
             raise typer.Exit(1)
-        if instance_range:
-            _emit_error("--profile is incompatible with --range")
-            raise typer.Exit(1)
+        if instance_range is not None:
+            try:
+                _parse_instance_range(instance_range)
+            except ValueError as exc:
+                _emit_error(str(exc))
+                raise typer.Exit(1)
         if exclude_instance_ids:
             _emit_error("--profile is incompatible with --exclude-instance-ids")
             raise typer.Exit(1)
@@ -3279,7 +3300,7 @@ def job_create(
 
             suite_name = f"{template or 'profile'}-sp-{profile}-{_dt.now().strftime('%m%d-%H%M')}"
 
-        # Parse instances from -i (simple comma split, no range/exclude expansion)
+        # Parse IDs only; Profile range selection happens on the server.
         instances_list: Optional[list[str]] = None
         if instance_id:
             try:
@@ -3320,6 +3341,7 @@ def job_create(
             **({"ak_id": ak_id} if ak_id is not None else {}),
             profile_version=profile_version_req,
             instances=instances_list,
+            instance_range=instance_range,
             dataset=dataset,
             batch_size=batch_size,
             trials=trials,
@@ -3335,6 +3357,13 @@ def job_create(
             _print_formatted(body, "json" if output_format == "plain" else output_format)
             return
 
+        if instance_range is not None:
+            try:
+                client.ensure_profile_range_supported(timeout=timeout)
+            except (ValueError, ConfigurationError) as exc:
+                _emit_error(str(exc))
+                raise typer.Exit(1) from None
+
         if dry_run:
             _emit_dry_run_warnings(dry_run_warnings)
             body["dry_run"] = True
@@ -3354,7 +3383,7 @@ def job_create(
                 agenthub_ref=agenthub_ref,
                 instance_id=instance_id,
                 dataset=dataset,
-                instance_range=None,
+                instance_range=instance_range,
                 exclude_instance_ids=None,
                 params=params,
                 params_list_input=None,
@@ -3429,6 +3458,7 @@ def job_create(
                     **({"ak_id": ak_id} if ak_id is not None else {}),
                     profile_version=profile_version_req,
                     instances=instances_list,
+                    instance_range=instance_range,
                     dataset=dataset,
                     batch_size=batch_size,
                     trials=trials,
@@ -4912,7 +4942,7 @@ def benchmark_list(
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """List benchmarks from the local benchmark registry."""
+    """List benchmarks from the central benchmark registry."""
     output_format = _normalize_output_format(output_format, keep_table=True)
     client = get_client()
     result = client.list_benchmarks()