ap-client 0.6.0.dev2__tar.gz → 0.7.0.dev0__tar.gz

{ap_client-0.6.0.dev2 → ap_client-0.7.0.dev0}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.6.0.dev2
+Version: 0.7.0.dev0
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
-Requires-Dist: irepo-artifact==0.2.1
+Requires-Dist: irepo-artifact==0.2.2
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.28.0
 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]<2.0.0,>=1.3.2; extra == 'all'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.3.5; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]<2.0.0,>=1.3.2; extra == 'dataset'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.3.5; 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.6.0.dev2 → ap_client-0.7.0.dev0}/ap_client/api.py

@@ -1127,6 +1127,8 @@ class APIClient:
         ak_ids: Optional[list[str]] = None,
         priority: Optional[str] = None,
         priority_weight: Optional[int] = None,
+        transparency: Optional[Literal["whitebox", "blackbox"]] = None,
+        idempotency_key: Optional[str] = None,
     ) -> dict:
         """Create a group with optional scheduling defaults for its Jobs.
 
@@ -1134,6 +1136,10 @@ class APIClient:
         """
         if priority is not None and priority not in {"high", "medium"}:
             raise ValueError("priority must be one of high/medium")
+        if transparency is not None and transparency not in {"whitebox", "blackbox"}:
+            raise ValueError("transparency must be whitebox or blackbox")
+        if transparency == "blackbox" and not idempotency_key:
+            raise ValueError("blackbox Group creation requires a reusable idempotency_key (UUID4)")
         if ak_ids is not None and not isinstance(ak_ids, list):
             raise ValueError("ak_ids must be a list")
         references = list(ak_ids or [])
@@ -1142,6 +1148,10 @@ class APIClient:
                 raise ValueError("ak_ids entries must be nonempty strings")
         references = list(dict.fromkeys(references))
         body: dict = {}
+        if transparency is not None:
+            body["transparency"] = transparency
+        if idempotency_key is not None:
+            body["idempotency_key"] = idempotency_key
         if references:
             body["ak_ids"] = references
         if name:
@@ -1263,9 +1273,11 @@ class APIClient:
         ak_mode: str = "auto",
         instance_range: Optional[str] = None,
         profile: Optional[str] = None,
+        transparency: Optional[Literal["whitebox", "blackbox"]] = None,
     ) -> dict:
         """Create a job."""
         body = self.build_create_job_body(
+            transparency=transparency,
             template=template,
             params=params,
             params_list=params_list,
@@ -1377,8 +1389,11 @@ class APIClient:
         ak_mode: str = "auto",
         instance_range: Optional[str] = None,
         profile: Optional[str] = None,
+        transparency: Optional[Literal["whitebox", "blackbox"]] = None,
     ) -> dict:
         """Build the /jobs request body for job creation."""
+        if transparency is not None and transparency not in {"whitebox", "blackbox"}:
+            raise ValueError("transparency must be whitebox or blackbox")
         if profile is not None and (profile_id is not None or profile_version is not None):
             raise ValueError("profile cannot be combined with profile_id or profile_version")
         _validate_credential_source_selection(
@@ -1503,8 +1518,23 @@ class APIClient:
         if experiment is not None:
             body["experiment"] = experiment
 
+        if transparency is not None:
+            body["transparency"] = transparency
         return body
 
+    def get_job_access_contact(self, job_id: str) -> dict:
+        """Discover the owner and grant contact without reading protected details."""
+        result = self._get(f"/jobs/{quote(job_id, safe='')}", params={"access_contact": True})
+        if (
+            not isinstance(result, dict)
+            or result.get("resource_type") != "job"
+            or "authorization_contact" not in result
+        ):
+            raise ConfigurationError(
+                "Server does not support access contact queries; upgrade Agent-Platform first"
+            )
+        return result
+
     def get_job(
         self,
         job_id: str,
@@ -1630,6 +1660,19 @@ class APIClient:
 
     # ==================== Group operations ====================
 
+    def get_group_access_contact(self, group_id: str) -> dict:
+        """Discover the owner and grant contact without reading protected details."""
+        result = self._get(f"/groups/{quote(group_id, safe='')}", params={"access_contact": True})
+        if (
+            not isinstance(result, dict)
+            or result.get("resource_type") != "group"
+            or "authorization_contact" not in result
+        ):
+            raise ConfigurationError(
+                "Server does not support access contact queries; upgrade Agent-Platform first"
+            )
+        return result
+
     def get_group(self, group_id: str, timeout: TimeoutType = None) -> dict:
         """Get group details."""
         return self._get(f"/groups/{quote(group_id)}", timeout=timeout)
@@ -3046,6 +3089,23 @@ class APIClient:
             return self._get(f"{self._PROFILES_BASE}/{quote(id_or_name)}/versions/{version}")
         return self._get(f"{self._PROFILES_BASE}/{quote(id_or_name)}")
 
+    def update_profile_job_meta(self, profile_id: str, patch: dict) -> dict:
+        """Patch live Job defaults without changing the Profile version.
+
+        Omitted fields stay unchanged. Set benchmark to None to clear it.
+        Tags use {"append": [...], "remove": [...]} and are applied atomically.
+        """
+        return self._request_central(
+            "PATCH", f"/profiles/{quote(profile_id, safe='')}/job-meta", json_body=patch
+        )
+
+    def replace_profile_job_meta(self, profile_id: str, job_meta: dict) -> dict:
+        """Replace all live Job defaults; {} clears benchmark and tags.
+
+        This does not change spec, Profile tags, version, verification or release.
+        """
+        return self._put_central(f"/profiles/{quote(profile_id, safe='')}/job-meta", job_meta)
+
     def update_profile(
         self,
         profile_id: str,
@@ -3054,8 +3114,13 @@ class APIClient:
         description: str = "",
         account_pool: Optional[str] = None,
         metadata: Optional[dict] = None,
+        reason: Optional[str] = None,
     ) -> dict:
-        """Update a submission profile, preserving an omitted default Pool."""
+        """Update a submission profile, preserving an omitted default Pool.
+
+        reason describes this update; omission never reuses a previous reason.
+        The server validates whether it is required and its 500-character limit.
+        """
         body: dict = {"name": name, "spec": spec}
         if description:
             body["description"] = description
@@ -3063,6 +3128,8 @@ class APIClient:
             body["account_pool"] = account_pool
         if metadata is not None:
             body["metadata"] = metadata
+        if reason is not None:
+            body["reason"] = reason
         return self._put(f"{self._PROFILES_BASE}/{quote(profile_id)}", body)
 
     def delete_profile(self, profile_id: str) -> dict:
@@ -3085,8 +3152,8 @@ class APIClient:
     ) -> dict:
         """把某个 job/group 实例的访问权授予某 user/user_group（scope=resource 绑定）。
 
-        workspace_id = 该实例所属 queue_id；apiserver 按该 WorkSpace 的 workspace-admin/
-        创建者/superuser 门控。鉴权走当前 API Key 解析出的调用者身份。
+        workspace_id = 该实例所属 queue_id；Job/Group Owner、Group Admin 或所属
+        WorkSpace 的管理员/创建者及平台管理员可授权。鉴权走当前 API Key 解析出的调用者身份。
         """
         body = {
             "scope": "resource",
@@ -3352,7 +3419,7 @@ def _response_error_detail(resp: requests.Response) -> Any:
     except Exception:
         return resp.text
     if isinstance(err_data, dict):
-        return err_data.get("detail", resp.text)
+        return err_data.get("detail", err_data.get("message", resp.text))
     return err_data
 
 

{ap_client-0.6.0.dev2 → ap_client-0.7.0.dev0}/ap_client/cli.py

@@ -17,9 +17,7 @@ from ap_client.akpool_commands import register as _register_akpool_commands
 from ap_client.api import (
     APIError,
     PaginationProtocolError,
-    _is_sensitive_key,
     _merge_meta_tags,
-    _redact_sensitive_data,
     set_cluster_override,
     set_verbose_override,
 )
@@ -207,146 +205,8 @@ def _job_create_progress():
     )
 
 
-def _shell_command(args: list[str]) -> str:
-    return " ".join(shlex.quote(str(arg)) for arg in args)
-
-
-def _retry_argument_contains_secret(raw: str) -> bool:
-    """Inspect display arguments without changing the submission payload."""
-    try:
-        value = json.loads(raw)
-    except (json.JSONDecodeError, TypeError):
-        value = raw
-
-    def contains_secret(item: Any) -> bool:
-        if isinstance(item, dict):
-            return any(
-                _is_sensitive_key(str(key)) or contains_secret(field) for key, field in item.items()
-            )
-        if isinstance(item, list):
-            return any(contains_secret(field) for field in item)
-        return _redact_sensitive_data(item) != item
-
-    return contains_secret(value)
-
-
-def _build_job_create_retry_command(
-    *,
-    template: Optional[str],
-    agenthub_ref: Optional[str],
-    instance_id: Optional[str],
-    dataset: Optional[str],
-    instance_range: Optional[str],
-    exclude_instance_ids: Optional[str],
-    params: Optional[str],
-    params_list_input: Optional[str],
-    suite_name: Optional[str],
-    group_id: Optional[str],
-    tags: Optional[str],
-    overrides: Optional[str],
-    concurrency: Optional[int],
-    batch_size: int,
-    trials: Optional[int] = None,
-    max_failure_retries: int = 0,
-    wait: bool,
-    wait_interval: float,
-    wait_timeout: Optional[float],
-    output_format: str,
-    enable_otel_tracing: Optional[bool],
-    runner: Optional[str],
-    runner_options: Optional[str],
-    model_base_url_collection: Optional[str],
-    model_base_url_file: Optional[str],
-    datasources: Optional[str],
-    account_pool: Optional[str] = None,
-    idempotency_key: str,
-    enable_post_process: bool = False,
-    group_post_process: Optional[str] = None,
-    profile: Optional[str] = None,
-    resource_profile_id: Optional[str] = None,
-    timeout: Optional[float] = None,
-    ak_id: Optional[str] = None,
-    ak_mode: str = "auto",
-) -> str:
-    args = ["ap", "job", "create"]
-    if template is not None:
-        args.append(template)
-    if ak_id is not None:
-        args.extend(["--ak-id", ak_id])
-    if ak_mode != "auto":
-        args.extend(["--ak-mode", ak_mode])
-    if profile is not None:
-        args.extend(["--profile", profile])
-    if resource_profile_id:
-        args.extend(["--resource-profile", resource_profile_id])
-    if agenthub_ref:
-        args.extend(["--agenthub-ref", agenthub_ref])
-    if instance_id:
-        args.extend(["-i", instance_id])
-    if dataset:
-        args.extend(["--dataset", dataset])
-    if instance_range:
-        args.extend(["--range", instance_range])
-    if exclude_instance_ids:
-        args.extend(["--exclude-instance-ids", exclude_instance_ids])
-    if params:
-        args.extend(["-p", params])
-    if params_list_input:
-        args.extend(["--params-list", params_list_input])
-    if suite_name:
-        args.extend(["--suite-name", suite_name])
-    if group_id:
-        args.extend(["--group-id", group_id])
-    if tags:
-        args.extend(["--tags", tags])
-    if overrides:
-        args.extend(["--overrides", overrides])
-    if concurrency is not None:
-        args.extend(["--concurrency", str(concurrency)])
-    if batch_size != 200:
-        args.extend(["--batch-size", str(batch_size)])
-    if trials is not None:
-        args.extend(["--trials", str(trials)])
-    if max_failure_retries:
-        args.extend(["--max-failure-retries", str(max_failure_retries)])
-    if wait:
-        args.append("--wait")
-        if wait_interval != 5.0:
-            args.extend(["--wait-interval", f"{wait_interval:g}"])
-        if wait_timeout is not None:
-            args.extend(["--wait-timeout", f"{wait_timeout:g}"])
-    if timeout is not None:
-        args.extend(["--timeout", f"{timeout:g}"])
-    if output_format != "plain":
-        args.extend(["--format", output_format])
-    if enable_otel_tracing is not None:
-        args.extend(["--enable-otel-tracing", str(enable_otel_tracing).lower()])
-    if runner:
-        args.extend(["--runner", runner])
-    if runner_options:
-        args.extend(["--runner-options", runner_options])
-    if model_base_url_collection:
-        args.extend(["--model-base-url-collection", model_base_url_collection])
-    if model_base_url_file:
-        args.extend(["--model-base-url-file", model_base_url_file])
-    if datasources:
-        args.extend(["--datasources", datasources])
-    if account_pool:
-        args.extend(["--account-pool", account_pool])
-    if group_post_process:
-        args.extend(["--group-post-process", group_post_process])
-    elif enable_post_process:
-        args.append("--enable-post-process")
-    if any(_retry_argument_contains_secret(str(arg)) for arg in args):
-        # A redacted command would silently retry with different credentials.
-        # Keep the original invocation private and print only the retry key.
-        return (
-            "Rerun your original command with "
-            f"--idempotency-key {shlex.quote(idempotency_key)}. "
-            "The command is omitted because it contains inline credentials."
-        )
-    args.extend(["--idempotency-key", idempotency_key])
-    return _shell_command(args)
+def _build_job_create_retry_command(*, idempotency_key: str) -> str:
+    return f"Rerun your original command with --idempotency-key {shlex.quote(idempotency_key)}"
 
 
 def _emit_idempotency_retry_hint(command: str) -> None:
@@ -1059,8 +919,26 @@ def _print_params_plain(params: Any, masked_params: list) -> None:
     _print_key_values(rows, skip_empty=False)
 
 
+def _print_content_notice(rows: list[dict]) -> None:
+    if any(
+        row.get("transparency") == "blackbox" and row.get("can_read_content") is False
+        for row in rows
+    ):
+        typer.echo("Blackbox content is hidden; Group Reader access is required.")
+
+
+def _content_columns(rows: list[dict], columns: list[str]) -> list[str]:
+    restricted = {field for row in rows for field in (row.get("restricted_fields") or [])}
+    return [
+        field
+        for field in columns
+        if field not in restricted or any(row.get(field) is not None for row in rows)
+    ]
+
+
 def _print_job_get_plain(job: dict) -> None:
     typer.echo("Job")
+    _print_content_notice([job])
     _print_key_values(
         [
             ("job_id", job.get("job_id")),
@@ -1333,6 +1211,8 @@ _DEFAULT_JOB_LIST_COLUMNS = [
 
 _JOB_LIST_AVAILABLE_COLUMNS = [
     *_DEFAULT_JOB_LIST_COLUMNS,
+    "transparency",
+    "can_read_content",
     "job_name",
     "group_id",
     "quota_id",
@@ -1494,6 +1374,8 @@ def _print_job_list_plain(
         )
     else:
         selected_columns = default_columns
+    _print_content_notice(rows)
+    selected_columns = _content_columns(rows, selected_columns)
     render = _print_rich_table if rich else _print_plain_table
     render(
         rows,
@@ -1549,6 +1431,8 @@ _GROUP_LIST_TABLE_MIN_COLUMNS = 3
 
 _GROUP_LIST_AVAILABLE_COLUMNS = [
     *_DEFAULT_GROUP_LIST_COLUMNS,
+    "transparency",
+    "can_read_content",
     "template",
     "scheduling_status",
     "profile",
@@ -1637,7 +1521,8 @@ def _prepare_group_list_rows(groups: list[dict]) -> list[dict]:
             "upstream_platform",
             "upstream_job_id",
         ):
-            row[key] = row.get(key) or "-"
+            if key not in row.get("restricted_fields", []):
+                row[key] = row.get(key) or "-"
         rows.append(row)
     return rows
 
@@ -1654,6 +1539,8 @@ def _print_group_list_plain(
         )
     else:
         selected_columns = _DEFAULT_GROUP_LIST_COLUMNS
+    _print_content_notice(rows)
+    selected_columns = _content_columns(rows, selected_columns)
     render = _print_rich_table if rich else _print_plain_table
     render(
         rows,
@@ -1688,6 +1575,7 @@ def _pick_available_columns(
 
 
 def _print_group_eval_plain(result: dict) -> None:
+    _print_content_notice([result])
     header_parts: list[str] = []
     for key in ("group_id", "name"):
         if key in result:
@@ -1761,6 +1649,7 @@ def _print_group_eval_plain(result: dict) -> None:
         rows,
         [
             ("task_id", "task_id"),
+            ("job_ids", "job_ids"),
             ("trials", "trials"),
             ("scored", "scored"),
             ("avg_score", "avg_score"),
@@ -3016,6 +2905,11 @@ def job_list(
 
 @job_app.command("create")
 def job_create(
+    transparency: Optional[str] = typer.Option(
+        None,
+        "--transparency",
+        help="whitebox or blackbox; omit to inherit the Group/Profile default",
+    ),
     template: Optional[str] = typer.Argument(None, help="Template name; optional with --profile"),
     ak_id: Optional[str] = typer.Option(
         None, "--ak-id", help="AP-managed AK ID; requires server support"
@@ -3362,6 +3256,8 @@ def job_create(
     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")
     output_format = _normalize_output_format(output_format)
     if not template and not profile:
         raise typer.BadParameter("TEMPLATE is required unless --profile is provided")
@@ -3384,6 +3280,7 @@ def job_create(
     )
     idempotency_enabled = (
         enable_idempotency
+        or transparency == "blackbox"
         or idempotency_key is not None
         or profile is not None
         or implicit_resource_profile_idempotency
@@ -3535,6 +3432,7 @@ def job_create(
 
         # Build request body via create_job (reuse existing method with profile fields)
         body = client.build_create_job_body(
+            **({"transparency": transparency} if transparency is not None else {}),
             template=template,
             params=params_dict or None,
             suite_name=suite_name,
@@ -3603,43 +3501,7 @@ def job_create(
 
         # Build retry command before submitting so it's available on failure
         profile_retry_command = (
-            _build_job_create_retry_command(
-                template=template,
-                agenthub_ref=agenthub_ref,
-                instance_id=instance_id,
-                dataset=dataset,
-                instance_range=instance_range,
-                exclude_instance_ids=None,
-                params=params,
-                params_list_input=None,
-                suite_name=suite_name,
-                group_id=group_id,
-                tags=tags,
-                overrides=overrides,
-                concurrency=concurrency,
-                batch_size=batch_size,
-                trials=trials,
-                max_failure_retries=max_failure_retries,
-                wait=wait,
-                wait_interval=wait_interval,
-                wait_timeout=wait_timeout,
-                output_format=output_format,
-                enable_otel_tracing=enable_otel_tracing,
-                runner=runner,
-                runner_options=runner_options,
-                model_base_url_collection=model_base_url_collection,
-                model_base_url_file=model_base_url_file,
-                datasources=datasources,
-                account_pool=account_pool,
-                enable_post_process=enable_post_process,
-                group_post_process=group_post_process,
-                idempotency_key=submission_idempotency_key,
-                profile=profile,
-                resource_profile_id=resource_profile_id,
-                **({"ak_id": ak_id} if ak_id is not None else {}),
-                **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
-                timeout=timeout,
-            )
+            _build_job_create_retry_command(idempotency_key=submission_idempotency_key)
             if idempotency_enabled and submission_idempotency_key is not None
             else None
         )
@@ -3655,6 +3517,7 @@ def job_create(
         try:
             with console.status("[bold green]Submitting by profile..."):
                 result = client.create_job(
+                    **({"transparency": transparency} if transparency is not None else {}),
                     template=template,
                     params=params_dict or None,
                     suite_name=suite_name,
@@ -3866,41 +3729,7 @@ def job_create(
         model_base_url_collection_list = None
 
     retry_command = (
-        _build_job_create_retry_command(
-            template=template,
-            agenthub_ref=agenthub_ref,
-            instance_id=instance_id,
-            dataset=dataset,
-            instance_range=instance_range,
-            exclude_instance_ids=exclude_instance_ids,
-            params=params,
-            params_list_input=params_list_input,
-            suite_name=suite_name,
-            group_id=group_id,
-            tags=tags,
-            overrides=overrides,
-            concurrency=concurrency,
-            batch_size=batch_size,
-            max_failure_retries=max_failure_retries,
-            wait=wait,
-            wait_interval=wait_interval,
-            wait_timeout=wait_timeout,
-            output_format=output_format,
-            enable_otel_tracing=enable_otel_tracing,
-            runner=runner,
-            runner_options=runner_options,
-            model_base_url_collection=model_base_url_collection,
-            model_base_url_file=model_base_url_file,
-            datasources=datasources,
-            account_pool=account_pool,
-            enable_post_process=enable_post_process,
-            group_post_process=group_post_process,
-            idempotency_key=submission_idempotency_key,
-            resource_profile_id=resource_profile_id,
-            **({"ak_id": ak_id} if ak_id is not None else {}),
-            **({"ak_mode": ak_mode} if ak_mode != "auto" else {}),
-            timeout=timeout,
-        )
+        _build_job_create_retry_command(idempotency_key=submission_idempotency_key)
         if not dry_run
         and not job_spec_flag
         and idempotency_enabled
@@ -4003,6 +3832,7 @@ def job_create(
 
         if job_spec_flag:
             payload = client.build_create_job_body(
+                **({"transparency": transparency} if transparency is not None else {}),
                 template=template,
                 params_list=[dict(p) for p in params_list],
                 dataset=dataset,
@@ -4046,6 +3876,7 @@ def job_create(
                 batch = build_batch(start)
                 payloads.append(
                     client.build_create_job_body(
+                        **({"transparency": transparency} if transparency is not None else {}),
                         template=template,
                         params_list=batch,
                         dataset=dataset,
@@ -4105,6 +3936,7 @@ def job_create(
                         current_stage=f"batch {batch_index + 1}: {start + 1}-{batch_end}/{total_count}",
                     )
                     batch_result = client.create_job(
+                        **({"transparency": transparency} if transparency is not None else {}),
                         template=template,
                         params_list=batch,
                         dataset=dataset,
@@ -4214,6 +4046,7 @@ def job_create(
     else:
         if job_spec_flag:
             payload = client.build_create_job_body(
+                **({"transparency": transparency} if transparency is not None else {}),
                 template=template,
                 params=params_dict,
                 dataset=dataset,
@@ -4251,6 +4084,7 @@ def job_create(
 
         if dry_run:
             payload = client.build_create_job_body(
+                **({"transparency": transparency} if transparency is not None else {}),
                 template=template,
                 params=params_dict,
                 dataset=dataset,
@@ -4300,6 +4134,7 @@ def job_create(
                     current_stage="submitting",
                 )
                 result = client.create_job(
+                    **({"transparency": transparency} if transparency is not None else {}),
                     template=template,
                     params=params_dict,
                     dataset=dataset,
@@ -4477,6 +4312,11 @@ def job_get(
         "--field",
         help="Print one field path, e.g. status, lifecycle.run_duration, params.model",
     ),
+    owner: bool = typer.Option(
+        False,
+        "--owner",
+        help="Show only the owner and authorization contact, without reading protected details",
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -4493,7 +4333,20 @@ def job_get(
         include_spec = include_spec or _field_path_requires_spec(field)
         if field == "job_spec_data.spec_yaml":
             spec_format = "yaml"
+    if owner and share_token is not None:
+        raise typer.BadParameter("--owner cannot be combined with --share-token")
     client = _read_client(share_token)
+    if owner and (include_params or include_spec or field):
+        raise typer.BadParameter(
+            "--owner cannot be combined with --include-params, --include-spec or --field"
+        )
+    if owner:
+        result = client.get_job_access_contact(job_id)
+        if output_format in {"plain", "table"}:
+            _print_detail(result)
+        else:
+            _print_formatted(result, output_format)
+        return
     result = client.get_job(
         job_id,
         include_params=include_params,
@@ -4501,6 +4354,18 @@ def job_get(
         spec_format=spec_format,
     )
     if field:
+        safe_job_name = (
+            field == "job_name"
+            and isinstance(result.get("job_id"), str)
+            and bool(result["job_id"])
+            and result.get("job_name") == result["job_id"]
+        )
+        if not safe_job_name and any(
+            field == path or field.startswith(path + ".") or field.startswith(path + "[")
+            for path in (result.get("restricted_fields") or [])
+        ):
+            _emit_error(f"field hidden: {field}; Group Reader access is required")
+            raise typer.Exit(1)
         try:
             value = _extract_field(result, field)
         except ValueError as exc:
@@ -4729,15 +4594,21 @@ _RESOURCE_ROLE_IDS = {
     ("job", "reader"): "built-in:job-reader",
     ("job", "writer"): "built-in:job-writer",
     ("group", "reader"): "built-in:group-reader",
+    ("group", "blackbox-reader"): "built-in:blackbox-reader",
     ("group", "writer"): "built-in:group-writer",
     ("group", "cloner"): "built-in:group-cloner",
+    ("group", "admin"): "built-in:group-admin",
 }
 
 
 def _resource_role_id(resource: str, role: str) -> str:
     key = (resource, (role or "").strip().lower())
     if key not in _RESOURCE_ROLE_IDS:
-        choices = "reader, writer, cloner" if resource == "group" else "reader, writer"
+        choices = (
+            "reader, writer, cloner, blackbox-reader, admin"
+            if resource == "group"
+            else "reader, writer"
+        )
         raise typer.BadParameter(f"role must be one of: {choices}")
     return _RESOURCE_ROLE_IDS[key]
 
@@ -5439,6 +5310,14 @@ def checkpoint_get(
 
 @group_app.command("create")
 def group_create(
+    transparency: Optional[str] = typer.Option(
+        None,
+        "--transparency",
+        help="whitebox or blackbox; omit to inherit the Group/Profile default",
+    ),
+    idempotency_key: Optional[str] = typer.Option(
+        None, "--idempotency-key", help="Reuse this key when retrying blackbox Group creation"
+    ),
     ak_id: Optional[list[str]] = typer.Option(
         None, "--ak-id", help="Managed AK reference (repeatable) to associate with the Group"
     ),
@@ -5591,6 +5470,8 @@ def group_create(
     ),
 ):
     """Create a Group."""
+    if transparency is not None and transparency not in {"whitebox", "blackbox"}:
+        raise typer.BadParameter("Choose whitebox or blackbox", param_hint="--transparency")
     output_format = _normalize_output_format(output_format)
     if priority is not None and priority not in {"high", "medium"}:
         raise typer.BadParameter("--priority must be one of high/medium")
@@ -5599,6 +5480,8 @@ def group_create(
             validate_ak_id(reference)
     except ValueError as exc:
         raise typer.BadParameter(str(exc), param_hint="--ak-id") from None
+    if transparency == "blackbox" and idempotency_key is None:
+        idempotency_key = str(uuid.uuid4())
     client = get_client()
     eval_config_dict = json.loads(eval_config) if eval_config else None
     group_post_process_dict = _parse_json_object(group_post_process, "--group-post-process")
@@ -5656,6 +5539,8 @@ def group_create(
 
     try:
         result = client.create_group(
+            **({"transparency": transparency} if transparency is not None else {}),
+            **({"idempotency_key": idempotency_key} if idempotency_key is not None else {}),
             ak_ids=ak_id,
             name=name,
             tags=group_tags,
@@ -5678,7 +5563,17 @@ def group_create(
             **({"priority": priority} if priority is not None else {}),
             **({"priority_weight": priority_weight} if priority_weight is not None else {}),
         )
+    except APIError:
+        if idempotency_key is not None:
+            _emit_idempotency_retry_hint(
+                f"Rerun your original command with --idempotency-key {shlex.quote(idempotency_key)}"
+            )
+        raise
     except ManagedAKProtocolError as exc:
+        if idempotency_key is not None:
+            _emit_idempotency_retry_hint(
+                _build_job_create_retry_command(idempotency_key=idempotency_key)
+            )
         _emit_error(str(exc))
         raise typer.Exit(1) from None
     if output_format == "plain":
@@ -5815,6 +5710,11 @@ def group_get(
     share_token: Optional[str] = typer.Option(
         None, "--share-token", help="Read with a share token"
     ),
+    owner: bool = typer.Option(
+        False,
+        "--owner",
+        help="Show only the owner and authorization contact, without reading protected details",
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -5823,7 +5723,16 @@ def group_get(
 ):
     """Show Group details."""
     output_format = _normalize_output_format(output_format, keep_table=True)
+    if owner and share_token is not None:
+        raise typer.BadParameter("--owner cannot be combined with --share-token")
     client = _read_client(share_token, group_id if share_token else None)
+    if owner:
+        result = client.get_group_access_contact(group_id)
+        if output_format in {"plain", "table"}:
+            _print_detail(result)
+        else:
+            _print_formatted(result, output_format)
+        return
     result = client.get_group(group_id)
     if output_format == "table":
         _print_detail(result)
@@ -6029,6 +5938,7 @@ def group_clone(
                 ("source_group_id", preview.get("source_group_id")),
                 ("target_cluster", preview.get("target_cluster")),
                 ("target_name", (preview.get("target_group") or {}).get("name")),
+                ("transparency", (preview.get("target_group") or {}).get("transparency")),
                 ("target_queue", (preview.get("target_group") or {}).get("queue_id")),
                 ("jobs", preview.get("source_job_count")),
                 ("target_jobs", preview.get("target_job_count")),
@@ -6553,7 +6463,7 @@ def group_grant(
     role: str = typer.Option(
         "reader",
         "--role",
-        help="reader (view), cloner (view+clone), or writer (view+cancel/update)",
+        help="reader (view), blackbox-reader (protected Group content), cloner (view+clone), writer (view+cancel/update), or admin (view+clone+update+grant)",
     ),
 ):
     """Grant a user/user-group access to a specific group (RBAC v2 instance delegation)."""
@@ -6567,7 +6477,9 @@ def group_revoke(
     user_group: Optional[str] = typer.Option(
         None, "--user-group", help="Revoke from this user_group_id"
     ),
-    role: str = typer.Option("reader", "--role", help="reader, cloner, or writer"),
+    role: str = typer.Option(
+        "reader", "--role", help="reader, blackbox-reader, cloner, writer, or admin"
+    ),
 ):
     """Revoke a user/user-group's instance access to a specific group."""
     _revoke_instance_access("group", group_id, role, user, user_group)
@@ -6747,6 +6659,8 @@ def main() -> None:
 
 
 def _format_api_error(exc: APIError) -> str:
+    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:
         return f"error: {exc}"
 

{ap_client-0.6.0.dev2 → ap_client-0.7.0.dev0}/ap_client/exporter.py

@@ -23,7 +23,7 @@ import requests
 if TYPE_CHECKING:
     from irepo_artifact import ArtifactClient, DownloadResult
 
-from .api import APIClient
+from .api import APIClient, APIError
 
 logger = logging.getLogger(__name__)
 
@@ -429,8 +429,9 @@ def _export_job_into_dir(
             extract_artifacts=extract_artifacts,
             skip_no_artifact=skip_no_artifact,
         )
-    from irepo_artifact import ArtifactError, ArtifactNotFound
+    from irepo_artifact import AccessDenied, ArtifactError, ArtifactNotFound
 
+    job_data = job or {}
     current_stage = "job metadata"
     selective = bool(include_files or exclude_files)
 
@@ -480,6 +481,11 @@ def _export_job_into_dir(
                 except ArtifactError as exc:
                     outcome = error = exc
 
+            # A denied refresh can retain old metadata. Never publish or delete
+            # existing export files on an authorization failure.
+            if isinstance(error, AccessDenied):
+                raise error
+
             artifact = outcome.artifacts_response
             manifest = outcome.manifest_response
             missing_manifest = (
@@ -580,6 +586,31 @@ def _export_job_into_dir(
     except Exception as exc:
         if result_callback is not None:
             result_callback(job_id, "failed", None)
+
+        if isinstance(exc, AccessDenied):
+            if (
+                job_data.get("transparency") == "blackbox"
+                and job_data.get("can_read_content") is False
+                and getattr(exc, "_request_status", None) == 403
+            ):
+                raise APIError(
+                    403,
+                    {
+                        "code": "blackbox_content_restricted",
+                        "message": "Group Reader access is required",
+                    },
+                    None,
+                    None,
+                ) from exc
+            raise RuntimeError(
+                f"Access denied while exporting job {job_id}; check your login/API key and resource permissions."
+            ) from exc
+        if (
+            isinstance(exc, APIError)
+            and isinstance(exc.detail, dict)
+            and exc.detail.get("code") == "blackbox_content_restricted"
+        ):
+            raise
         raise RuntimeError(
             f"Failed to export job {job_id} at stage '{current_stage}': {exc}"
         ) from exc

{ap_client-0.6.0.dev2 → ap_client-0.7.0.dev0}/ap_client/managed_ak.py

@@ -21,7 +21,6 @@ def validate_ak_selection(ak_id: Any, params: Any, params_list: Any, overrides:
     if isinstance(params_list, list):
         candidates.extend(params_list)
     for value in candidates:
-        parameter_ak_ids(value)
         if (
             isinstance(value, dict)
             and {"ak_id", "ak_selection_source", "user_ak_id", "key_id"} & value.keys()
@@ -31,13 +30,8 @@ def validate_ak_selection(ak_id: Any, params: Any, params_list: Any, overrides:
             )
 
 
-def parameter_ak_ids(value: Any) -> set[str]:
-    """Find explicit parameter references without resolving credential plaintext."""
-    return parameter_ak_usage(value)[0]
-
-
 def parameter_ak_usage(value: Any) -> tuple[set[str], set[tuple[str, str]]]:
-    """Return explicit IDs and every requested (selection source, tag) pair."""
+    """Collect references for receipt checks; the server validates their syntax."""
     if isinstance(value, dict):
         usages = [parameter_ak_usage(v) for v in value.values()]
         return set().union(*(ids for ids, _ in usages)), set().union(
@@ -49,6 +43,8 @@ def parameter_ak_usage(value: Any) -> tuple[set[str], set[tuple[str, str]]]:
             *(selected for _, selected in usages)
         )
     if isinstance(value, str) and "$akpool" in value:
+        # Normalize only for receipt recognition; the request keeps the original value.
+        value = re.sub(r"^\$akpool:[ \t]+", "$akpool:", value)
         match = re.fullmatch(r"\$akpool:([A-Za-z0-9][A-Za-z0-9_.-]{0,127})", value)
         if match:
             return {match[1]}, set()
@@ -64,8 +60,14 @@ def parameter_ak_usage(value: Any) -> tuple[set[str], set[tuple[str, str]]]:
                     c in ",@#.$" or c.isspace() or unicodedata.category(c) == "Cc" for c in tag
                 )
             ):
-                return set(), {("personal_default" if match[2] == "me" else "queue_default", tag)}
-        raise ValueError("Use a complete $akpool:<ak-id> parameter value or selector")
+                return set(), {
+                    (
+                        "personal_default" if match[2] == "me" else "queue_default",
+                        "" if match[2] == "me" and tag == "default" else tag,
+                    )
+                }
+        # Keep the capability check for future syntax without echoing arbitrary values.
+        return {"$akpool"}, set()
     return set(), set()
 
 
@@ -90,6 +92,20 @@ def _version_one(value: Any) -> bool:
     return type(value) in (int, float) and value == 1
 
 
+def _personal_default_alias(selectors: set[tuple[str, str]]) -> set[tuple[str, str]]:
+    """Accept the pre-alias spelling of the personal default on reused Jobs.
+
+    ``$akpool:#default@me`` is now the untagged personal default, but Jobs frozen by an
+    older version stored ``selection_tag="default"``. An idempotent resubmission returns
+    that frozen binding verbatim, so the alias must acknowledge the legacy tag as well.
+    """
+    expanded = set(selectors)
+    for source, tag in selectors:
+        if source == "personal_default" and tag in {"", "default"}:
+            expanded.add((source, "default" if tag == "" else ""))
+    return expanded
+
+
 def require_parameter_ak_ack(
     response: Any, ak_ids: set[str], selectors: set[tuple[str, str]] | None = None
 ) -> None:
@@ -102,6 +118,7 @@ def require_parameter_ak_ack(
     if selectors:
         if not _version_one(response.get("ak_selection_version")):
             raise ManagedAKProtocolError("$akpool selector", response)
+        reused_bindings: set[tuple[str, str]] = set()
         if response.get("dry_run") is True:
             preview = response.get("preview_job")
             if not response_ak_ids(preview):
@@ -113,18 +130,31 @@ def require_parameter_ak_ack(
             jobs = response.get("jobs")
             if not isinstance(jobs, list):
                 raise ManagedAKProtocolError("$akpool selector", response)
+            job_list = [job for job in jobs if isinstance(job, dict)] if jobs else []
+            aggregate = _confirmed_selectors(response.get("ak_bindings"))
             confirmed = (
+                set().union(*(_confirmed_selectors(job.get("ak_bindings")) for job in job_list))
+                if job_list
+                else aggregate
+            )
+            # Only a reused Job may answer with the legacy tag: a fresh submission must
+            # bind the alias as the untagged personal default. Large Profile receipts omit
+            # per-Job details and sample the persisted bindings at the top level, so those
+            # aggregated bindings are frozen evidence too: a fresh alias binding is always
+            # untagged, which leaves "default" only on Jobs frozen before the alias existed.
+            reused_bindings = (
                 set().union(
                     *(
                         _confirmed_selectors(job.get("ak_bindings"))
-                        for job in jobs
-                        if isinstance(job, dict)
+                        for job in job_list
+                        if job.get("reused") is True
                     )
                 )
-                if jobs
-                else _confirmed_selectors(response.get("ak_bindings"))
+                if job_list
+                else aggregate
             )
-        if not selectors <= confirmed:
+        accepted = confirmed | _personal_default_alias(reused_bindings)
+        if not selectors <= accepted:
             raise ManagedAKProtocolError("$akpool selector", response)
 
 

{ap_client-0.6.0.dev2 → ap_client-0.7.0.dev0}/ap_client/profile_commands.py

@@ -15,6 +15,7 @@ from ap_client.api import APIError  # noqa: F401
 from ap_client.config import normalize_output_format
 from rich import print
 from rich.table import Table
+from rich.text import Text
 
 
 def _import_yaml():
@@ -153,6 +154,23 @@ def _fmt_dt(value: Optional[str]) -> str:
     return dt.strftime("%Y-%m-%d %H:%M:%S")
 
 
+def _print_job_meta_plain(job_meta: dict) -> None:
+    benchmark = job_meta.get("benchmark") or "(inherit from spec)"
+    tags = ", ".join(job_meta.get("tags") or []) or "(none)"
+    typer.echo(f"  Job benchmark default: {benchmark}")
+    typer.echo(f"  Job tag defaults:      {tags}")
+
+
+def _print_job_meta_result(result: dict, output_format: str) -> None:
+    if output_format != "plain":
+        _print_formatted(result, output_format)
+        return
+    typer.echo("Profile Job defaults saved. Profile version is unchanged.")
+    payload = result.get("data", result)
+    if isinstance(payload, dict) and isinstance(payload.get("job_meta"), dict):
+        _print_job_meta_plain(payload["job_meta"])
+
+
 def _print_profile_plain(profile: dict) -> None:
     """Pretty-print a single profile in plain format."""
     pid = profile.get("profile_id") or profile.get("id", "-")
@@ -185,6 +203,10 @@ def _print_profile_plain(profile: dict) -> None:
         )
     print(f"  [bold]Created:[/]      {_fmt_dt(profile.get('created_at'))}")
     print(f"  [bold]Updated:[/]      {_fmt_dt(profile.get('updated_at'))}")
+    if profile.get("update_reason"):
+        typer.echo(f"  Update reason: {profile['update_reason']}")
+    if isinstance(profile.get("job_meta"), dict):
+        _print_job_meta_plain(profile["job_meta"])
 
     spec = profile.get("spec")
     if not isinstance(spec, dict):
@@ -277,6 +299,7 @@ def _print_versions_plain(data: dict, profile_id: str) -> None:
     table.add_column("VERIFIED")
     table.add_column("RELEASED")
     table.add_column("GROUP")
+    table.add_column("REASON")
 
     for v in items:
         ver = v.get("verification") or {}
@@ -288,6 +311,7 @@ def _print_versions_plain(data: dict, profile_id: str) -> None:
             "true" if ver else "-",
             "true" if v.get("release") else "-",
             ver.get("group_id") or "-",
+            Text(v.get("update_reason") or "-"),
         )
     print(table)
 
@@ -383,6 +407,80 @@ def profile_set_tags(
         _print_formatted(result, output_format)
 
 
+@profile_app.command("patch-job-meta")
+def profile_patch_job_meta(
+    identifier: str = typer.Argument(..., help="Profile ID or name"),
+    benchmark: Optional[str] = typer.Option(
+        None, "--benchmark", help="Set the Job benchmark default; an empty value clears it"
+    ),
+    clear_benchmark: bool = typer.Option(
+        False, "--clear-benchmark", help="Clear the live benchmark default and inherit from spec"
+    ),
+    append_tags: Optional[list[str]] = typer.Option(
+        None, "--append-tag", help="Append a Job default tag (repeatable)"
+    ),
+    remove_tags: Optional[list[str]] = typer.Option(
+        None, "--remove-tag", help="Remove an exact Job default tag (repeatable)"
+    ),
+    output_format: str = typer.Option(
+        None, "--format", help="Output format: plain/table/json/yaml (default: AP_FORMAT or plain)"
+    ),
+):
+    """Patch Job defaults without changing the Profile version.
+
+    Omitted fields stay unchanged. Remove and append tags in one request to
+    replace a keyed tag. Profile tags and spec are not changed.
+    """
+    output_format = _normalize_output_format(output_format)
+    if benchmark is not None and clear_benchmark:
+        raise typer.BadParameter("--benchmark and --clear-benchmark are mutually exclusive")
+    patch: dict = {}
+    if clear_benchmark or benchmark is not None:
+        patch["benchmark"] = None if clear_benchmark else benchmark
+    delta: dict = {}
+    if append_tags:
+        delta["append"] = append_tags
+    if remove_tags:
+        delta["remove"] = remove_tags
+    if delta:
+        patch["tags"] = delta
+    if not patch:
+        raise typer.BadParameter(
+            "provide --benchmark, --clear-benchmark, --append-tag or --remove-tag"
+        )
+    result = get_client().update_profile_job_meta(identifier, patch)
+    _print_job_meta_result(result, output_format)
+
+
+@profile_app.command("update-job-meta")
+def profile_update_job_meta(
+    identifier: str = typer.Argument(..., help="Profile ID or name"),
+    job_meta_json: str = typer.Option(
+        ..., "--json", help="Complete job_meta JSON object; '{}' clears all live defaults"
+    ),
+    output_format: str = typer.Option(
+        None, "--format", help="Output format: plain/table/json/yaml (default: AP_FORMAT or plain)"
+    ),
+):
+    """Replace all Job defaults without changing the Profile version.
+
+    Supply the full job_meta object using --json. Omitted fields are cleared;
+    '{}' clears all live defaults. Use patch-job-meta to change selected fields.
+    Profile tags and spec are not changed, and --reason is not required.
+    """
+    output_format = _normalize_output_format(output_format)
+    try:
+        job_meta = json.loads(job_meta_json)
+        # Reject non-JSON constants such as NaN before constructing a request.
+        json.dumps(job_meta, allow_nan=False)
+    except ValueError as exc:
+        raise typer.BadParameter(f"Invalid JSON: {exc}", param_hint="--json") from exc
+    if not isinstance(job_meta, dict):
+        raise typer.BadParameter("must be a JSON object", param_hint="--json")
+    result = get_client().replace_profile_job_meta(identifier, job_meta)
+    _print_job_meta_result(result, output_format)
+
+
 @profile_app.command("list")
 def profile_list(
     keyword: Optional[str] = typer.Option(None, "--keyword", "-k", help="Filter by name keyword"),
@@ -468,6 +566,9 @@ def profile_update(
         None, "--spec", "-s", help="New inline spec as JSON string"
     ),
     description: Optional[str] = typer.Option(None, "--description", "-d", help="New description"),
+    reason: str = typer.Option(
+        ..., "--reason", help="Required reason for this update (1-500 characters after trimming)"
+    ),
     account_pool: Optional[str] = typer.Option(
         None,
         "--account-pool",
@@ -488,9 +589,15 @@ def profile_update(
 
     Renaming a profile is intentionally not supported via the CLI — the
     profile name is treated as a stable handle. Provide either --file or
-    --spec to replace the spec; --description is optional.
+    --spec to replace the spec. --reason is required and must contain 1-500
+    characters after trimming. A previous version's reason is never reused.
     """
     output_format = _normalize_output_format(output_format)
+    reason = reason.strip()
+    if not reason:
+        raise typer.BadParameter("must not be empty or whitespace", param_hint="--reason")
+    if len(reason) > 500:
+        raise typer.BadParameter("must be at most 500 characters", param_hint="--reason")
     spec = _load_spec(file, spec_inline)
     metadata = _load_metadata(metadata_inline)
 
@@ -511,6 +618,7 @@ def profile_update(
         description=final_description,
         account_pool=final_account_pool,
         metadata=final_metadata,
+        reason=reason,
     )
     if output_format == "plain":
         print("[green]Profile updated:[/]")

{ap_client-0.6.0.dev2 → ap_client-0.7.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.6.0.dev2"
+version = "0.7.0.dev0"
 description = "Agent Platform API Client & CLI"
 readme = { text = "A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -14,15 +14,15 @@ dependencies = [
     "rich>=13.0.0",
     "PyYAML>=6.0",
     "websockets>=13.0",
-    "irepo-artifact==0.2.1",
+    "irepo-artifact==0.2.2",
 ]
 
 [project.optional-dependencies]
 dataset = [
-    "instance-repo[oss]>=1.3.2,<2.0.0",
+    "instance-repo[oss]>=1.3.5,<2.0.0",
 ]
 all = [
-    "instance-repo[oss]>=1.3.2,<2.0.0",
+    "instance-repo[oss]>=1.3.5,<2.0.0",
 ]
 
 [project.scripts]