ap-client 0.7.0.dev11__tar.gz → 0.7.1.dev1__tar.gz

{ap_client-0.7.0.dev11 → ap_client-0.7.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.7.0.dev11
+Version: 0.7.1.dev1
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: irepo-artifact==0.2.4

{ap_client-0.7.0.dev11 → ap_client-0.7.1.dev1}/ap_client/api.py

@@ -2963,6 +2963,8 @@ class APIClient:
         account_pool: Optional[str] = None,
         metadata: Optional[dict] = None,
         tags: Optional[list[str]] = None,
+        parents: Optional[list[str | dict]] = None,
+        auto_follow_parents: Optional[list[str]] = None,
     ) -> dict:
         """Create a new submission profile."""
         body: dict = {"name": name, "spec": spec}
@@ -2974,6 +2976,10 @@ class APIClient:
             body["metadata"] = metadata
         if tags is not None:
             body["tags"] = tags
+        if parents is not None:
+            body["parents"] = parents
+        if auto_follow_parents is not None:
+            body["auto_follow_parents"] = auto_follow_parents
         return self._post(self._PROFILES_BASE, body)
 
     def list_profiles(
@@ -3115,6 +3121,9 @@ class APIClient:
         account_pool: Optional[str] = None,
         metadata: Optional[dict] = None,
         reason: Optional[str] = None,
+        version: Optional[int] = None,
+        parents: Optional[list[str | dict]] = None,
+        auto_follow_parents: Optional[list[str]] = None,
     ) -> dict:
         """Update a submission profile, preserving an omitted default Pool.
 
@@ -3130,7 +3139,108 @@ class APIClient:
             body["metadata"] = metadata
         if reason is not None:
             body["reason"] = reason
-        return self._put(f"{self._PROFILES_BASE}/{quote(profile_id)}", body)
+        if version is not None:
+            if type(version) is not int or version < 1:
+                raise ValueError("version must be a positive integer")
+            body["version"] = version
+        if parents is not None:
+            body["parents"] = parents
+        if auto_follow_parents is not None:
+            body["auto_follow_parents"] = auto_follow_parents
+        return self._put(f"{self._PROFILES_BASE}/{quote(profile_id, safe='')}", body)
+
+    def patch_profile(self, profile_id: str, fields: dict) -> dict:
+        """Patch own definition; callers should supply their original version."""
+        return self._request(
+            "PATCH", f"{self._PROFILES_BASE}/{quote(profile_id, safe='')}", json_body=fields
+        )
+
+    def resolve_profile(self, identifier: str, *, version: Optional[int] = None) -> dict:
+        return self._get(
+            f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/resolved",
+            params={"version": version} if version is not None else None,
+        )
+
+    def preview_profile(self, draft: dict) -> dict:
+        return self._post(f"{self._PROFILES_BASE}/resolve", draft)
+
+    def profile_children(
+        self,
+        identifier: str,
+        *,
+        page: int = 1,
+        page_size: int = 20,
+        target_version: Optional[int] = None,
+        eligible_only: bool = False,
+        current_only: bool = False,
+    ) -> dict:
+        params = {"page": page, "page_size": page_size}
+        if target_version is not None:
+            params["target_version"] = target_version
+        if eligible_only:
+            params["eligible_only"] = "true"
+        if current_only:
+            params["current_only"] = "true"
+        return self._get(
+            f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/children",
+            params=params,
+        )
+
+    def profile_diff(
+        self,
+        identifier: str,
+        from_version: Optional[int] = None,
+        to_version: Optional[int] = None,
+        view: str = "own",
+        *,
+        compare_to: Optional[str] = None,
+    ) -> dict:
+        """Compare versions of one Profile, or two Profiles (omitted versions use current)."""
+        params = {"from": from_version, "to": to_version, "view": view}
+        if compare_to is not None:
+            params["compare_to"] = compare_to
+        result = self._get(
+            f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/diff",
+            params=params,
+        )
+        if compare_to is not None:
+            # Older servers ignore unknown query fields. Do not present their
+            # single-Profile response as a successful cross-Profile comparison.
+            for field in ("from_profile", "to_profile"):
+                ref = result.get(field) if isinstance(result, dict) else None
+                if (
+                    not isinstance(ref, dict)
+                    or not isinstance(ref.get("profile_id"), str)
+                    or not ref["profile_id"].startswith("sp-")
+                    or type(ref.get("version")) is not int
+                    or ref["version"] < 1
+                ):
+                    raise APIError(
+                        200,
+                        "Server did not confirm cross-Profile diff support; upgrade the server before comparing different Profiles",
+                        None,
+                        None,
+                    )
+        return result
+
+    def cascade_profiles(self, identifier: str, request: dict) -> dict:
+        return self._post(f"{self._PROFILES_BASE}/{quote(identifier, safe='')}/cascades", request)
+
+    def get_profile_cascade(self, operation_id: str) -> dict:
+        return self._get(f"/apis/v1/profile-cascades/{quote(operation_id, safe='')}")
+
+    def profile_cascade_history(
+        self, profile_id: str, *, page: int = 1, page_size: int = 20
+    ) -> dict:
+        return self._get(
+            f"{self._PROFILES_BASE}/{quote(profile_id, safe='')}/cascades",
+            params={"page": page, "page_size": page_size},
+        )
+
+    def retry_profile_cascade(self, operation_id: str, items: list[dict]) -> dict:
+        return self._post(
+            f"/apis/v1/profile-cascades/{quote(operation_id, safe='')}/retry", {"items": items}
+        )
 
     def delete_profile(self, profile_id: str) -> dict:
         """Delete a submission profile."""

{ap_client-0.7.0.dev11 → ap_client-0.7.1.dev1}/ap_client/cli.py

@@ -3003,22 +3003,22 @@ def job_create(
     meta_model: Optional[str] = typer.Option(
         None,
         "--meta-model",
-        help="Target model or training project this job serves; not the called model or Judge. Values: ap meta-tag get meta-model --format json",
+        help="Meta model tag; omit to leave unset",
     ),
     meta_job_type: Optional[str] = typer.Option(
         None,
         "--meta-job-type",
-        help="Business purpose of this job. Values: ap meta-tag get meta-job-type --format json",
+        help="Meta job type tag: Eval-Eval (default) or Others",
     ),
     meta_teacher_direction: Optional[str] = typer.Option(
         None,
         "--meta-teacher-direction",
-        help="Teacher direction this job serves; verify any dataset-derived value. Values: ap meta-tag get meta-teacher-direction --format json",
+        help="Meta teacher direction tag; omit to derive from dataset_series; options: ap meta-teacher-direction list",
     ),
     meta_train_stage: Optional[str] = typer.Option(
         None,
         "--meta-train-stage",
-        help="Training stage this job serves; verify any dataset-derived value. Values: ap meta-tag get meta-train-stage --format json",
+        help="Meta train stage tag; omit to derive from dataset run_type; options: ap meta-train-stage list",
     ),
     overrides: Optional[str] = typer.Option(None, "--overrides", help="Override config (JSON)"),
     concurrency: Optional[int] = typer.Option(
@@ -3190,7 +3190,7 @@ def job_create(
     benchmark: Optional[str] = typer.Option(
         None,
         "--benchmark",
-        help="Prefer the registered benchmark source ID for this run; name is also accepted. Find IDs: ap benchmark list --format json; inspect by name: ap benchmark get NAME --format json",
+        help="Benchmark name from the AP registry (see 'ap benchmark list')",
     ),
     checkpoint_id: Optional[str] = typer.Option(
         None,
@@ -3236,41 +3236,46 @@ def job_create(
 ):
     """Submit a job.
 
-    For agents:
-    \b
-    Before submitting, you MUST ensure these five parameters are explicitly specified:
-    benchmark, meta-model, meta-job-type, meta-train-stage, meta-teacher-direction.
-    Keep specified values. Fill missing parameters using available Job, Group,
-    Profile, Dataset, Template, or other relevant information.
-    If a missing value cannot be inferred, use default for benchmark
-    or Others for the corresponding meta parameter.
-    Do not ask the user for these values.
-
     Model configuration:
         Supply template parameters through --params/-p; select a managed credential with --ak-id.
 
     Examples:
-        Use catalog/context-selected values for the metadata variables below.
-
-        \b
-        # Profile submission (PROFILE_REF is ID:vN)
-        ap job create --profile "$PROFILE_REF" -i "$INSTANCE_ID" \\
-          --benchmark "$BENCHMARK_ID" \\
-          --meta-model "$META_MODEL" \\
-          --meta-job-type "$META_JOB_TYPE" \\
-          --meta-train-stage "$META_TRAIN_STAGE" \\
-          --meta-teacher-direction "$META_TEACHER_DIRECTION"
-
-        \b
-        # Batch jobs from a Dataset (first 3 instances)
-        ap job create claw-eval-task --dataset "$DATASET_PATH" --range 0,3 \\
-          -p '{"model":"qwen-max"}' \\
-          --benchmark "$BENCHMARK_ID" \\
-          --meta-model "$META_MODEL" \\
-          --meta-job-type "$META_JOB_TYPE" \\
-          --meta-train-stage "$META_TRAIN_STAGE" \\
-          --meta-teacher-direction "$META_TEACHER_DIRECTION"
+        # Single job - full parameters
+        ap job create claw-eval-task -p '{"task_id":"T02_email_triage","model":"qwen-max"}'
+
+        # Single job - instance_id + shared params
+        ap job create claw-eval-task -i T02_email_triage -p '{"model":"qwen-max"}'
+
+        # Batch jobs - multiple instance_ids + shared params
+        ap job create claw-eval-task -i T02_email_triage,T03zh_calendar_scheduling,T04_calendar_scheduling -p '{"model":"qwen-max"}'
 
+        # Batch jobs - dataset + shared params
+        ap job create claw-eval-task --dataset claw-eval/claw-eval/v1@0 -p '{"model":"qwen-max"}'
+
+        # Batch jobs - dataset subset with exclusions
+        ap job create claw-eval-task --dataset claw-eval/claw-eval/v1@0 --range 0,10,2 --exclude-instance-ids T03zh_calendar_scheduling
+
+        # Batch jobs from a params list(inline JSON) with shared base params (-p merged into each item)
+        ap job create claw-eval-task --params-list '[{"task_id":"T02_email_triage"},{"task_id":"T03zh_calendar_scheduling"}]' -p '{"model":"qwen-max"}'
+
+        # Batch jobs from a params list file (also supports -p for shared base params)
+        ap job create claw-eval-task --params-list params.json -p '{"model":"qwen-max"}'
+
+        # Debug mode - keep pod alive for interactive debugging (Pod Login)
+        ap job create stress-test -p '{"duration":60}' --debug
+
+        # Debug mode with custom keep-alive duration
+        ap job create stress-test -p '{"duration":60}' --debug --debug-keep-alive-seconds 7200
+
+        # Apply per-instance resource settings from a Resource Profile
+        ap job create claw-eval-task --dataset claw-eval/v1 --resource-profile rp-123
+
+    Note: benchmark+ckpt metadata (--benchmark/--checkpoint-*/--experiment) on a
+    standalone single job needs no client-side group handling — the server
+    auto-creates a Group (auto_created_benchmark_group) to persist the
+    Group-level fields. Generating a group_id client-side would break
+    idempotent retries: the server rejects a same idempotency_key with a
+    different requested group_id (409 idempotency_conflict).
     """
     if transparency is not None and transparency not in {"whitebox", "blackbox"}:
         raise typer.BadParameter("Choose whitebox or blackbox", param_hint="--transparency")
@@ -6675,6 +6680,10 @@ def main() -> None:
 
 
 def _format_api_error(exc: APIError) -> str:
+    from ap_client.profile_diagnostics import format_profile_error
+
+    if profile_error := format_profile_error(exc):
+        return profile_error
     if isinstance(exc.detail, dict) and exc.detail.get("code") == "blackbox_content_restricted":
         return f"error: Blackbox content is hidden; Group Reader access is required. (request_id={exc.request_id})"
     if str(exc.detail) != _NON_JSON_RESPONSE_DETAIL:

{ap_client-0.7.0.dev11 → ap_client-0.7.1.dev1}/ap_client/dataset_commands.py

@@ -695,20 +695,31 @@ def _unversioned_split(
 
 
 def _versioned_split(
-    dataset: str, version: str, split: str, *, environment: Optional[str] = None
+    dataset: str,
+    version: str,
+    split: str,
+    *,
+    environment: Optional[str] = None,
+    oss_fallback: bool = True,
 ) -> Optional[dict]:
     """取指定 version 里的单个 split 记录;不存在返回 ``None``(不当作错误)。
 
     与 ``_unversioned_split`` 同源,走 recordsvc 的 ``splits.get``(SDK 自带
-    version_first 内嵌投影的 legacy 回退)。
+    version_first 内嵌投影的 legacy 回退)。``split get`` 保持默认 OSS 发现回退;
+    ``split create`` 的幂等检查须传 ``oss_fallback=False``:dataset 刚创建或
+    尚未上传时 OSS prefix 不存在,``_discover_split`` 会把"split 不存在"误报为
+    查询失败,404 → legacy 回退 → None 即可判定"不存在 → 走 create"。
     """
     from .irepo_sdk import _reason
 
     env = _environment(environment)
     repo = _dataset_repo()
+    read_kwargs = _read_env_kwargs(repo, repo.splits, "get", env)
+    if not oss_fallback:
+        read_kwargs["fallback_to_oss"] = False
     try:
         record = repo.splits.get(
-            dataset, split, version=version, **_read_env_kwargs(repo, repo.splits, "get", env)
+            dataset, split, version=version, **read_kwargs
         )
     except Exception as exc:  # noqa: BLE001
         raise _fail(
@@ -716,7 +727,9 @@ def _versioned_split(
             f"Check the dataset name and permission: ap dataset get {dataset}",
         ) from exc
     detail = _model_dict(record) if record is not None else None
-    return detail if detail is not None and _version_value(detail.get("version")) == version else None
+    return (
+        detail if detail is not None and _version_value(detail.get("version")) == version else None
+    )
 
 
 def _versioned_splits(
@@ -1286,8 +1299,9 @@ def dataset_get(
 
 def dataset_create(
     dataset: str = typer.Argument(
-        ..., help="Dataset name: L1, L1/L2, or a deeper path "
-        "(e.g. my-bench, alibaba/my-bench, or gdpval/synthetic/my-bench)"
+        ...,
+        help="Dataset name: L1, L1/L2, or a deeper path "
+        "(e.g. my-bench, alibaba/my-bench, or gdpval/synthetic/my-bench)",
     ),
     benchmark: str = typer.Option(..., "--benchmark", help="Benchmark name or source_id"),
     description: Optional[str] = typer.Option(None, "--description", help="Dataset description"),
@@ -1946,9 +1960,7 @@ def dataset_split_get(
     resolved_version = _version_value(version)
 
     if resolved_version:
-        record = _versioned_split(
-            dataset, resolved_version, split, environment=environment
-        )
+        record = _versioned_split(dataset, resolved_version, split, environment=environment)
         if record is not None:
             payload = dict(record)
             payload.setdefault("dataset", dataset)
@@ -2026,7 +2038,12 @@ def dataset_split_create(
     # 契约对齐——旧 Version PATCH（splits 全量替换 / split_run_types）已被服务端
     # 拒绝（"split-first Version group updates are not supported"）。
     env = _environment(environment)
-    existing = _versioned_split(dataset, resolved_version, split, environment=environment)
+    # 幂等预检禁用 OSS 发现回退：dataset 刚创建或尚未上传时 OSS prefix 不存在，
+    # _discover_split 会把"split 不存在"误报为查询失败("not found in OSS")；
+    # recordsvc 404 → legacy 回退 → None 即判定"不存在 → 走 create"。
+    existing = _versioned_split(
+        dataset, resolved_version, split, environment=environment, oss_fallback=False
+    )
     if existing is not None:
         # 幂等:已存在同名 split(设计 §4.3)。
         payload = dict(existing)
@@ -2151,7 +2168,9 @@ def dataset_split_update(
             ", ".join(
                 _split_names_of(
                     _versioned_splits(
-                        dataset, resolved_version, stage="split update precheck",
+                        dataset,
+                        resolved_version,
+                        stage="split update precheck",
                         environment=environment,
                     )
                 )
@@ -2171,7 +2190,9 @@ def dataset_split_update(
     repo = _dataset_repo()
     update_kwargs = _sdk_read_kwargs(repo.splits, "update", environment=env, metadata_model="")
     try:
-        repo.splits.update(dataset, split, version=resolved_version, run_type=resolved_run_type, **update_kwargs)
+        repo.splits.update(
+            dataset, split, version=resolved_version, run_type=resolved_run_type, **update_kwargs
+        )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         raise _fail(
             f"Failed to update split {split} of dataset {dataset} version {resolved_version}: {_reason(exc)}",

{ap_client-0.7.0.dev11 → ap_client-0.7.1.dev1}/ap_client/dataset_register.py

@@ -121,8 +121,7 @@ def _create_owned_dataset(repo: Any, dataset: str, benchmark_id: str) -> dict:
         raise datasets._fail(
             f"Failed to create dataset {dataset}: the name must be one or more "
             "canonical path segments",
-            "Use a dataset name such as my-bench, your-team/my-bench, "
-            "or gdpval/synthetic/my-bench",
+            "Use a dataset name such as my-bench, your-team/my-bench, or gdpval/synthetic/my-bench",
             exit_code=2,
         )
 

ap_client-0.7.1.dev1/ap_client/profile_cascade_all.py

@@ -0,0 +1,149 @@
+"""Bounded all-Child discovery and replayable client-side cascade batches."""
+
+from __future__ import annotations
+
+import uuid
+from copy import deepcopy
+
+from ap_client.api import APIClient
+
+BATCH_SIZE = 100
+
+
+def preview_all(client: APIClient, identifier: str, target_version: int) -> dict:
+    batches: list[dict] = []
+    after = end = ""
+    base_id = None
+    seen: set[str] = set()
+    while True:
+        body = {"dry_run": True, "all": True, "target_version": target_version}
+        if after:
+            body.update(after=after, selection_end=end)
+        value = client.cascade_profiles(base_id or identifier, body)
+        if (
+            value.get("all") is not True
+            or value.get("dry_run") is not True
+            or not value.get("base_profile_id")
+            or value.get("target_version") != target_version
+            or (base_id and value["base_profile_id"] != base_id)
+        ):
+            raise ValueError(
+                "Invalid all-Children preview response; update the server and preview again"
+            )
+        base_id = value["base_profile_id"]
+        next_end = value.get("selection_end", "")
+        if after and next_end != end:
+            raise ValueError("The all-Children selection boundary changed; preview again")
+        end = next_end
+        items = value.get("items")
+        if not isinstance(items, list) or len(items) > BATCH_SIZE:
+            raise ValueError("Invalid preview batch size")
+        ids = [item.get("child_id") for item in items]
+        if (
+            any(not isinstance(i, str) or not i or i <= after or (end and i > end) for i in ids)
+            or ids != sorted(ids)
+            or len(set(ids)) != len(ids)
+            or seen.intersection(ids)
+        ):
+            raise ValueError("Invalid preview cursor or duplicate Child")
+        seen.update(ids)
+        if items:
+            batches.append(value)
+        cursor = value.get("next_cursor", "")
+        if not cursor:
+            break
+        if not ids or cursor != ids[-1] or cursor <= after or cursor >= end:
+            raise ValueError("Invalid preview cursor")
+        after = cursor
+    return {
+        "dry_run": True,
+        "all": True,
+        "base_profile_id": base_id,
+        "target_version": target_version,
+        "selection_end": end,
+        "batches": batches,
+    }
+
+
+def execution_targets(
+    items: list[dict], base_id: str, target: int, seen: set[str]
+) -> tuple[list[dict], int]:
+    """Use the same selection rules for manual and all-Child execution."""
+    if not isinstance(items, list) or len(items) > BATCH_SIZE:
+        raise ValueError("Each preview batch must have at most 100 Children")
+    targets, excluded = [], 0
+    for item in items:
+        if not isinstance(item, dict):
+            raise ValueError("Invalid Child in saved preview")
+        child_id = item.get("child_id")
+        if not isinstance(child_id, str) or not child_id.startswith("sp-") or child_id in seen:
+            raise ValueError("Invalid or duplicate Child in saved preview")
+        seen.add(child_id)
+        if item.get("valid") is not True:
+            excluded += 1
+            continue
+        baseline = item.get("target")
+        if not isinstance(baseline, dict) or set(baseline) != {
+            "child_id",
+            "expected_child_version",
+            "expected_parent",
+        }:
+            raise ValueError(
+                "Every valid Child requires a complete target; upgrade the server and preview again"
+            )
+        parent, version = baseline.get("expected_parent"), baseline.get("expected_child_version")
+        if (
+            baseline.get("child_id") != child_id
+            or type(version) is not int
+            or version < 1
+            or not isinstance(parent, dict)
+            or set(parent) != {"profile_id", "version"}
+            or parent.get("profile_id") != base_id
+            or type(parent.get("version")) is not int
+            or parent["version"] < 1
+        ):
+            raise ValueError("Every valid Child requires a complete preview baseline")
+        if parent["version"] >= target:
+            excluded += 1
+            continue
+        # Send the server's target unchanged, independent of display filters.
+        targets.append(deepcopy(baseline))
+    return targets, excluded
+
+
+def validate_preview_identity(preview: dict) -> tuple[str, int]:
+    if not isinstance(preview, dict) or preview.get("dry_run") is not True:
+        raise ValueError("Expected a saved dry-run preview")
+    base_id, target = preview.get("base_profile_id"), preview.get("target_version")
+    if (
+        not isinstance(base_id, str)
+        or not base_id.startswith("sp-")
+        or type(target) is not int
+        or target < 1
+    ):
+        raise ValueError("Invalid saved preview identity")
+    return base_id, target
+
+
+def execution_batches(preview: dict, root_key: str) -> tuple[list[dict], int]:
+    """Validate the whole saved plan before any writes; each batch gets a stable UUID."""
+    root = uuid.UUID(root_key)
+    base_id, target = validate_preview_identity(preview)
+    if preview.get("all") is not True or not isinstance(preview.get("batches"), list):
+        raise ValueError("Expected an --all preview file")
+    requests, seen, excluded = [], set(), 0
+    for index, batch in enumerate(preview["batches"]):
+        if not isinstance(batch, dict) or validate_preview_identity(batch) != (base_id, target):
+            raise ValueError("Preview batches must use the same fixed Base and target")
+        targets, skipped = execution_targets(batch.get("items"), base_id, target, seen)
+        excluded += skipped
+        if targets:
+            requests.append(
+                {
+                    "dry_run": False,
+                    "request_key": str(uuid.uuid5(root, f"profile-cascade-batch:{index}")),
+                    "target_version": target,
+                    "targets": targets,
+                }
+            )
+    return requests, excluded