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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.6.0.dev0
+Version: 0.6.0.dev2
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: irepo-artifact==0.2.1

{ap_client-0.6.0.dev0 → ap_client-0.6.0.dev2}/ap_client/api.py

@@ -709,13 +709,16 @@ class APIClient:
         request_id: str,
         duration_ms: float,
         exc: Exception,
+        *,
+        error_detail: str | None = None,
     ) -> None:
+        detail = str(exc) if error_detail is None else error_detail
         _write_stderr(
             [
                 f"!! Error {method} {url}",
                 f"   request_id={request_id}",
                 f"   duration_ms={duration_ms:.1f}",
-                f"   error={type(exc).__name__}: {exc}",
+                f"   error={type(exc).__name__}: {detail}",
             ]
         )
 
@@ -1122,8 +1125,15 @@ class APIClient:
         benchmark: Optional[str] = None,
         experiment: Optional[str] = None,
         ak_ids: Optional[list[str]] = None,
+        priority: Optional[str] = None,
+        priority_weight: Optional[int] = None,
     ) -> dict:
-        """Create a group."""
+        """Create a group with optional scheduling defaults for its Jobs.
+
+        Omitted priority fields use the server defaults: medium and weight 0.
+        """
+        if priority is not None and priority not in {"high", "medium"}:
+            raise ValueError("priority must be one of high/medium")
         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 [])
@@ -1161,6 +1171,10 @@ class APIClient:
             body["queue_id"] = effective_queue_id
         if max_concurrency is not None:
             body["max_concurrency"] = max_concurrency
+        if priority is not None:
+            body["priority"] = priority
+        if priority_weight is not None:
+            body["priority_weight"] = priority_weight
         if eval_config is not None:
             body["eval_config"] = eval_config
         if model_base_url_collection is not None:
@@ -1878,9 +1892,15 @@ class APIClient:
         meta_job_type: Optional[str] = None,
         meta_teacher_direction: Optional[str] = None,
         meta_train_stage: Optional[str] = None,
+        benchmark: Optional[str] = None,
+        priority: Optional[str] = None,
+        priority_weight: Optional[int] = None,
+        priority_update_mode: Optional[str] = None,
     ) -> dict:
         """Update group properties.
 
+        ``benchmark`` is omitted when None; pass an empty string to clear it.
+
         ``tags``（`key:value` 数组）在客户端先与 Group 现有 tags 合并，再以
         全量替换语义提交（服务端 PATCH 是整体替换）；同名 key 覆盖，未提及
         的 key 保留。服务端会从 tags 同步 meta_* 等派生字段。
@@ -1888,7 +1908,19 @@ class APIClient:
         ``meta_*`` 独立属性为部分更新（传了才改，不支持清除）；新服务端
         优先读属性，老服务端忽略属性——因此过渡期内同时也会将属性合并进
         tags 轨（双写）。
+
+        Priority changes update the Group defaults. The default existing mode
+        also updates all current Jobs, including PostProcess; incremental mode
+        changes only the defaults for future Jobs. Updating priority alone uses
+        weight 0; updating only weight preserves the current priority tier.
         """
+        if priority is not None and priority not in {"high", "medium"}:
+            raise ValueError("priority must be one of high/medium")
+        if priority_update_mode is not None:
+            if priority_update_mode not in {"existing", "incremental"}:
+                raise ValueError("priority_update_mode must be one of existing/incremental")
+            if priority is None and priority_weight is None:
+                raise ValueError("priority_update_mode requires priority or priority_weight")
         body: dict = {}
 
         if max_concurrency is not None:
@@ -1903,6 +1935,14 @@ class APIClient:
             body["model"] = model
         if scaffold is not None:
             body["scaffold"] = scaffold
+        if benchmark is not None:
+            body["benchmark"] = benchmark
+        if priority is not None:
+            body["priority"] = priority
+        if priority_weight is not None:
+            body["priority_weight"] = priority_weight
+        if priority_update_mode is not None:
+            body["priority_update_mode"] = priority_update_mode
         meta_attr_tags = _merge_meta_tags(
             None,
             meta_model=meta_model,

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

@@ -359,6 +359,22 @@ def _emit_error(message: str) -> None:
     error_console.print(f"[red]error: {message}[/]")
 
 
+def _read_client(share_token: Optional[str] = None, group_id: Optional[str] = None):
+    if group_id and not share_token:
+        raise typer.BadParameter("--group-id requires --share-token")
+    client = get_client()
+    if share_token is None:
+        return client
+    from ap_client.share_api import ShareAPIClient
+
+    # Typer verbose tracebacks must not render the share token in locals.
+    app.pretty_exceptions_show_locals = False
+    try:
+        return ShareAPIClient.from_client(client, share_token, group_id=group_id)
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
 def _reject_account_pool_template_credential_cli(
     account_pool: Optional[str],
     *credential_types: Any,
@@ -626,7 +642,18 @@ def _print_formatted(data: dict, output_format: str) -> None:
             import yaml
         except ImportError as exc:
             raise typer.BadParameter("--format yaml requires PyYAML to be installed") from exc
-        typer.echo(yaml.safe_dump(data, allow_unicode=True, sort_keys=False))
+
+        class LosslessDumper(yaml.SafeDumper):
+            pass
+
+        def represent_string(dumper, value):
+            # YAML normalizes literal NEL/line separators in unquoted scalars.
+            # Double quotes make the emitter escape them while keeping Chinese readable.
+            style = '"' if any(character in value for character in "\x85\u2028\u2029") else None
+            return dumper.represent_scalar("tag:yaml.org,2002:str", value, style=style)
+
+        LosslessDumper.add_representer(str, represent_string)
+        typer.echo(yaml.dump(data, Dumper=LosslessDumper, allow_unicode=True, sort_keys=False))
         return
     _print_json(data)
 
@@ -3203,12 +3230,12 @@ def job_create(
     priority: Optional[str] = typer.Option(
         None,
         "--priority",
-        help="Scheduling priority tier: high or medium (default: medium)",
+        help="Scheduling tier: high or medium. Omit both priority flags to inherit Group defaults; otherwise an omitted tier is medium",
     ),
     priority_weight: Optional[int] = typer.Option(
         None,
         "--priority-weight",
-        help="Fine-grained priority weight within tier, 0-10 (default: 0)",
+        help="Priority weight, 0-10. Omit both priority flags to inherit Group defaults; otherwise an omitted weight is 0",
     ),
     resource_mode: Optional[str] = typer.Option(
         None,
@@ -4427,6 +4454,9 @@ def job_create(
 @job_app.command("get")
 def job_get(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     include_params: bool = typer.Option(
         False,
         "--include-params",
@@ -4463,7 +4493,7 @@ def job_get(
         include_spec = include_spec or _field_path_requires_spec(field)
         if field == "job_spec_data.spec_yaml":
             spec_format = "yaml"
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job(
         job_id,
         include_params=include_params,
@@ -4489,6 +4519,9 @@ def job_get(
 @job_app.command("containers")
 def job_containers(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -4497,7 +4530,7 @@ def job_containers(
 ):
     """List container names for a job."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job_containers(job_id)
     if output_format == "table":
         _print_records_table(result)
@@ -4559,6 +4592,9 @@ def _print_tail_logs(logs, tail: int) -> None:
 @job_app.command("logs")
 def job_logs(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     container: Optional[str] = typer.Option("main", "--container", "-c", help="Container name"),
     tail: Optional[int] = typer.Option(None, "--tail", "-n", help="Show only the last N log lines"),
     follow: bool = typer.Option(
@@ -4570,7 +4606,7 @@ def job_logs(
     ),
 ):
     """Show job logs."""
-    client = get_client()
+    client = _read_client(share_token)
 
     if tail is not None:
         if tail <= 0:
@@ -4634,6 +4670,9 @@ def job_logs(
 @job_app.command("events")
 def job_events(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     container: Optional[str] = typer.Option(None, "--container", "-c", help="Container name"),
     output_format: str = typer.Option(
         None,
@@ -4643,7 +4682,7 @@ def job_events(
 ):
     """Show job events."""
     output_format = _normalize_output_format(output_format)
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job_events(job_id, container=container)
     if output_format == "plain":
         _print_job_events_plain(result)
@@ -4654,6 +4693,9 @@ def job_events(
 @job_app.command("metrics")
 def job_metrics(
     job_id: str = typer.Argument(..., help="Job ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -4662,7 +4704,7 @@ def job_metrics(
 ):
     """Show job metrics."""
     output_format = _normalize_output_format(output_format)
-    client = get_client()
+    client = _read_client(share_token)
     result = client.get_job_metrics(job_id)
     if output_format == "plain":
         _print_json(result)
@@ -4859,6 +4901,9 @@ def job_retry(
 @job_app.command("artifacts")
 def job_artifacts(
     job_ids: str = typer.Argument(..., help="Job IDs (comma-separated for multiple)"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -4867,7 +4912,7 @@ def job_artifacts(
 ):
     """Show job artifact download links."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token)
     ids = [jid.strip() for jid in job_ids.split(",")]
     results = client.get_job_artifacts(ids)
     if output_format == "table":
@@ -4907,6 +4952,9 @@ def _export_channel_reporter(emit):
 @job_app.command("export")
 def job_export(
     job_id: str = typer.Argument(..., help="Job ID or comma-separated Job IDs"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Export with a share token"
+    ),
     output: Optional[Path] = typer.Option(None, "--output", "-o", help="Export directory"),
     workers: int = typer.Option(
         1, "--workers", "-w", min=1, help="Number of concurrent export workers"
@@ -4929,7 +4977,7 @@ def job_export(
     ids = list(dict.fromkeys(value.strip() for value in job_id.split(",")))
     if not all(ids):
         raise typer.BadParameter("Job IDs must not be empty", param_hint="job_id")
-    client = get_client()
+    client = _read_client(share_token)
     if len(ids) > 1:
         report, channels = _export_channel_reporter(print)
         dest, summary = export_jobs(
@@ -5420,6 +5468,18 @@ def group_create(
         min=1,
         help="Maximum concurrent jobs. Server default: 50.",
     ),
+    priority: Optional[str] = typer.Option(
+        None,
+        "--priority",
+        help="Default priority inherited by Jobs: high or medium (server default: medium)",
+    ),
+    priority_weight: Optional[int] = typer.Option(
+        None,
+        "--priority-weight",
+        min=0,
+        max=10,
+        help="Default priority weight inherited by Jobs, 0-10 (server default: 0)",
+    ),
     eval_config: Optional[str] = typer.Option(
         None, "--eval-config", help="Evaluation config (JSON)"
     ),
@@ -5532,6 +5592,8 @@ def group_create(
 ):
     """Create a Group."""
     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")
     try:
         for reference in ak_id or []:
             validate_ak_id(reference)
@@ -5613,6 +5675,8 @@ def group_create(
             checkpoint=checkpoint_dict,
             benchmark=benchmark,
             experiment=experiment,
+            **({"priority": priority} if priority is not None else {}),
+            **({"priority_weight": priority_weight} if priority_weight is not None else {}),
         )
     except ManagedAKProtocolError as exc:
         _emit_error(str(exc))
@@ -5625,6 +5689,10 @@ def group_create(
             print(f"  ak_ids: {response_ak_ids(result)}")
         if result.get("queue_id") is not None:
             print(f"  queue_id: {result.get('queue_id')}")
+        if result.get("priority") is not None:
+            print(f"  priority: {result.get('priority')}")
+        if result.get("priority_weight") is not None:
+            print(f"  priority_weight: {result.get('priority_weight')}")
         if result.get("template") is not None:
             print(f"  template: {result.get('template')}")
         if result.get("agenthub_revision") is not None:
@@ -5744,6 +5812,9 @@ def group_list(
 @group_app.command("get")
 def group_get(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -5752,7 +5823,7 @@ def group_get(
 ):
     """Show Group details."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token, group_id if share_token else None)
     result = client.get_group(group_id)
     if output_format == "table":
         _print_detail(result)
@@ -6026,6 +6097,9 @@ def group_update(
     scaffold: Optional[str] = typer.Option(
         None, "--scaffold", "-s", help="Scaffold/agent name (benchmark perspective)"
     ),
+    benchmark: Optional[str] = typer.Option(
+        None, "--benchmark", help="Benchmark name; pass an empty string to clear"
+    ),
     tags: Optional[str] = typer.Option(
         None,
         "--tags",
@@ -6045,14 +6119,40 @@ def group_update(
         "--meta-train-stage",
         help="Set meta_train_stage tag (options: ap meta-train-stage list)",
     ),
+    priority: Optional[str] = typer.Option(
+        None,
+        "--priority",
+        help="Group priority default: high or medium; --priority alone sets weight to 0",
+    ),
+    priority_weight: Optional[int] = typer.Option(
+        None,
+        "--priority-weight",
+        min=0,
+        max=10,
+        help="Group priority weight default, 0-10; weight alone preserves the current tier",
+    ),
+    priority_update_mode: Optional[str] = typer.Option(
+        None,
+        "--priority-update-mode",
+        help="existing updates defaults and all current Jobs (including PostProcess); incremental updates only defaults (server default: existing)",
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
         help="Output format: plain/table/json/yaml (default: AP_FORMAT or command default)",
     ),
 ):
-    """Update Group properties."""
+    """Update Group properties and scheduling defaults inherited by Jobs."""
     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")
+    if priority_update_mode is not None:
+        if priority_update_mode not in {"existing", "incremental"}:
+            raise typer.BadParameter("--priority-update-mode must be one of existing/incremental")
+        if priority is None and priority_weight is None:
+            raise typer.BadParameter(
+                "--priority-update-mode requires --priority or --priority-weight"
+            )
     eval_config_dict = _parse_json_object(eval_config, "--eval-config")
     model_base_url_collection_list = _parse_model_base_url_collection_option(
         model_base_url_collection, model_base_url_file
@@ -6087,7 +6187,10 @@ def group_update(
             dataset,
             model_name,
             scaffold,
+            benchmark,
             tags_list,
+            priority,
+            priority_weight,
         )
     ):
         raise typer.BadParameter("At least one field must be provided to update")
@@ -6101,7 +6204,15 @@ def group_update(
         dataset=dataset,
         model=model_name,
         scaffold=scaffold,
+        **({"benchmark": benchmark} if benchmark is not None else {}),
         **({"tags": tags_list} if tags_list is not None else {}),
+        **({"priority": priority} if priority is not None else {}),
+        **({"priority_weight": priority_weight} if priority_weight is not None else {}),
+        **(
+            {"priority_update_mode": priority_update_mode}
+            if priority_update_mode is not None
+            else {}
+        ),
     )
     if output_format == "plain":
         _print_group_action_plain(
@@ -6115,6 +6226,9 @@ def group_update(
                 "dataset",
                 "model",
                 "scaffold",
+                "benchmark",
+                "priority",
+                "priority_weight",
                 "updated_at",
             ],
         )
@@ -6232,6 +6346,9 @@ def group_resume(
 @group_app.command("jobs")
 def group_jobs(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     tag: Optional[list[str]] = typer.Option(
         None, "--tag", help="Filter by tag (repeatable; multiple tags are combined with AND)"
     ),
@@ -6270,17 +6387,36 @@ def group_jobs(
     if cursor and skip > 0:
         raise typer.BadParameter("--cursor cannot be used with --skip greater than 0")
     cursor_request = bool(next_token) or cursor
-    client = get_client()
-    result = client.list_group_jobs(
-        group_id,
-        tag=tag,
-        include_post_process=include_post_process,
-        skip=skip,
-        limit=limit,
-        **({"next_token": next_token} if next_token else {}),
-        **({"pagination": "cursor"} if cursor_request else {}),
-        include_total=not no_total,
-    )
+    if share_token is not None:
+        unsupported = (
+            ("--tag", bool(tag)),
+            ("--include-post-process", include_post_process),
+            ("--next-token", bool(next_token)),
+            ("--cursor", cursor),
+            ("--no-total", no_total),
+        )
+        for option, used in unsupported:
+            if used:
+                _emit_error(f"{option} is not supported with --share-token")
+                raise typer.Exit(1)
+        if skip < 0 or not 1 <= limit <= 500:
+            raise typer.BadParameter(
+                "share pagination requires --skip >= 0 and 1 <= --limit <= 500"
+            )
+        client = _read_client(share_token, group_id if share_token else None)
+        result = client.list_jobs(group_id=group_id, skip=skip, limit=limit)
+    else:
+        client = get_client()
+        result = client.list_group_jobs(
+            group_id,
+            tag=tag,
+            include_post_process=include_post_process,
+            skip=skip,
+            limit=limit,
+            **({"next_token": next_token} if next_token else {}),
+            **({"pagination": "cursor"} if cursor_request else {}),
+            include_total=not no_total,
+        )
     if output_format == "table":
         _print_job_list_plain(result, rich=True)
     elif output_format == "plain":
@@ -6295,6 +6431,9 @@ def group_jobs(
 @group_app.command("stats")
 def group_stats(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -6303,7 +6442,7 @@ def group_stats(
 ):
     """Show Group progress."""
     output_format = _normalize_output_format(output_format, keep_table=True)
-    client = get_client()
+    client = _read_client(share_token, group_id if share_token else None)
     result = client.get_group_stats(group_id)
     if output_format == "table":
         _print_detail(result)
@@ -6314,6 +6453,9 @@ def group_stats(
 @group_app.command("eval")
 def group_eval(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Read with a share token"
+    ),
     summary_only: bool = typer.Option(
         False,
         "--summary-only",
@@ -6327,7 +6469,7 @@ def group_eval(
 ):
     """Show Group aggregated evaluation results."""
     output_format = _normalize_output_format(output_format)
-    client = get_client()
+    client = _read_client(share_token, group_id if share_token else None)
     result = (
         client.get_group_eval_summary(group_id) if summary_only else client.get_group_eval(group_id)
     )
@@ -6440,6 +6582,9 @@ def group_access_list(group_id: str = typer.Argument(..., help="Group ID")):
 @group_app.command("export")
 def group_export(
     group_id: str = typer.Argument(..., help="Group ID"),
+    share_token: Optional[str] = typer.Option(
+        None, "--share-token", help="Export with a share token"
+    ),
     output: Optional[Path] = typer.Option(None, "--output", "-o", help="Export directory"),
     workers: int = typer.Option(
         4, "--workers", "-w", min=1, help="Number of concurrent export workers"
@@ -6481,7 +6626,11 @@ def group_export(
         _emit_error("--include-files/--exclude-files cannot be used with --no-extract-artifacts")
         raise typer.Exit(1)
 
-    client = get_client()
+    if share_token is not None and (include_file_selectors or exclude_file_selectors):
+        _emit_error("--include-files/--exclude-files are not supported with --share-token")
+        raise typer.Exit(1)
+
+    client = _read_client(share_token, group_id if share_token else None)
     from rich.progress import BarColumn, Progress, TaskProgressColumn, TextColumn
 
     with Progress(

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

@@ -6,16 +6,20 @@ import concurrent.futures
 import json
 import logging
 import os
+import re
 import shutil
 import sys
+import tarfile
 import tempfile
 import threading
 import uuid
 from contextlib import nullcontext
 from dataclasses import dataclass, field
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING, Callable, Optional
 
+import requests
+
 if TYPE_CHECKING:
     from irepo_artifact import ArtifactClient, DownloadResult
 
@@ -30,6 +34,10 @@ StageCallback = Callable[[str], None]
 ResultCallback = Callable[[str, str, Optional[str]], None]
 
 
+def _is_share_client(client: APIClient) -> bool:
+    return getattr(client, "is_share", False) is True
+
+
 @dataclass
 class ExportSummary:
     """Summary of a group export operation."""
@@ -109,6 +117,30 @@ def export_jobs(
         parent = parent.parent
     summary = BatchExportSummary()
     ids = list(dict.fromkeys(job_ids))
+    if _is_share_client(client):
+        root.mkdir(parents=True, exist_ok=True)
+        for job_id in ids:
+            try:
+                skipped = _export_job_into_dir(
+                    client,
+                    job_id,
+                    root / "jobs" / job_id,
+                    timeout=timeout,
+                    result_callback=result_callback,
+                    include_logs=include_logs,
+                    include_events=include_events,
+                    extract_artifacts=extract_artifacts,
+                    skip_no_artifact=True,
+                )
+            except Exception as exc:
+                summary.failures[job_id] = str(exc)
+            else:
+                if skipped is not None:
+                    summary.skipped += 1
+                    summary.skipped_job_names.append(skipped)
+                else:
+                    summary.downloaded += 1
+        return root, summary
     with tempfile.TemporaryDirectory(prefix=".artifact-export-", dir=parent) as temporary:
         results = _new_artifact_client(client, timeout=timeout).download_many(
             ids,
@@ -166,6 +198,8 @@ def export_group(
     exclude_files = _normalize_file_selectors(exclude_files)
     if not extract_artifacts and (include_files or exclude_files):
         raise ValueError("file filters cannot be used when artifact extraction is disabled")
+    if _is_share_client(client) and (include_files or exclude_files):
+        raise ValueError("file filters are not supported with a share token")
 
     dest = Path(output_dir) if output_dir else default_group_export_dir(group_id)
     dest.mkdir(parents=True, exist_ok=True)
@@ -176,7 +210,8 @@ def export_group(
         group_eval = client.get_group_eval(group_id)
         _write_json(dest / "eval.json", group_eval)
         _write_json(dest / "eval_summary.json", group_eval.get("summary", {}))
-        _write_json(dest / "eval_tasks.json", group_eval.get("results", []))
+        task_key = "per_task" if _is_share_client(client) else "results"
+        _write_json(dest / "eval_tasks.json", group_eval.get(task_key, []))
     except Exception:
         # Some groups are non-eval workloads, or older servers may not expose eval endpoints.
         pass
@@ -217,7 +252,7 @@ def export_group(
                 client,
                 job_id,
                 jobs_dir / job_id,
-                job=job,
+                job=None if _is_share_client(client) else job,
                 stage_callback=lambda stage, current_job_id=job_id: _notify(current_job_id, stage),
                 timeout=timeout,
                 result_callback=result_callback,
@@ -243,7 +278,7 @@ def export_group(
         future_map = {
             executor.submit(
                 _export_job_with_fresh_client,
-                client.config,
+                client,
                 job,
                 jobs_dir / job["job_id"],
                 lambda stage, current_job_id=job["job_id"]: _notify(current_job_id, stage),
@@ -319,7 +354,7 @@ def _list_group_jobs(client: APIClient, group_id: str) -> list[dict]:
 
 
 def _export_job_with_fresh_client(
-    config,
+    client: APIClient,
     job: dict,
     dest: Path,
     stage_callback: Optional[StageCallback] = None,
@@ -334,12 +369,19 @@ def _export_job_with_fresh_client(
     exclude_files: Optional[list[str]] = None,
 ) -> Optional[str]:
     """Export one job with a dedicated client/session for thread safety."""
-    worker_client = APIClient(config)
+    if _is_share_client(client):
+        from .share_api import ShareAPIClient
+
+        worker_client = ShareAPIClient(
+            client.config, client.share_token, group_id=client.share_group_id
+        )
+    else:
+        worker_client = APIClient(client.config)
     return _export_job_into_dir(
         worker_client,
         job["job_id"],
         dest,
-        job=job,
+        job=None if _is_share_client(client) else job,
         stage_callback=stage_callback,
         timeout=timeout,
         result_callback=result_callback,
@@ -371,9 +413,22 @@ def _export_job_into_dir(
 ) -> Optional[str]:
     """Export SDK-managed artifacts alongside AP metadata.
 
-    The SDK is the only caller of artifact endpoints. Its result or exception
-    carries the original responses needed for AP's metadata files and skip policy.
+    Ordinary exports use the SDK for artifacts. Share exports use the share
+    endpoint's signed archive URL because the SDK uses authenticated routes.
     """
+    if _is_share_client(client):
+        return _export_shared_job_into_dir(
+            client,
+            job_id,
+            dest,
+            stage_callback=stage_callback,
+            timeout=timeout,
+            result_callback=result_callback,
+            include_logs=include_logs,
+            include_events=include_events,
+            extract_artifacts=extract_artifacts,
+            skip_no_artifact=skip_no_artifact,
+        )
     from irepo_artifact import ArtifactError, ArtifactNotFound
 
     current_stage = "job metadata"
@@ -531,6 +586,209 @@ def _export_job_into_dir(
     return None
 
 
+def _export_shared_job_into_dir(
+    client: APIClient,
+    job_id: str,
+    dest: Path,
+    *,
+    stage_callback: Optional[StageCallback] = None,
+    timeout: float = _DOWNLOAD_TIMEOUT,
+    result_callback: Optional[ResultCallback] = None,
+    include_logs: bool = False,
+    include_events: bool = False,
+    extract_artifacts: bool = True,
+    skip_no_artifact: bool = False,
+) -> Optional[str]:
+    """Use the share route's signed archive URL; the SDK uses authenticated routes."""
+    stage = "job metadata"
+
+    def set_stage(value: str) -> None:
+        nonlocal stage
+        stage = value
+        if stage_callback is not None:
+            stage_callback(value)
+
+    try:
+        job = client.get_job(job_id)
+        set_stage("artifact metadata")
+        artifacts = client.get_job_artifacts([job_id])
+        artifact = artifacts[0] if artifacts else {"job_id": job_id, "url": None}
+        url = artifact.get("url")
+        if not url and skip_no_artifact:
+            set_stage("skipped")
+            if result_callback is not None:
+                result_callback(job_id, "skipped", None)
+            return job.get("job_name") or job_id
+
+        parent = dest.resolve()
+        while not parent.exists():
+            parent = parent.parent
+        with tempfile.TemporaryDirectory(prefix=".artifact-share-", dir=parent) as temporary:
+            staging = Path(temporary)
+            if url:
+                set_stage("downloading artifact")
+                try:
+                    _download_shared_archive(url, staging / "result.tgz", timeout)
+                except FileNotFoundError:
+                    if skip_no_artifact:
+                        _remove_path(dest)
+                        set_stage("skipped")
+                        if result_callback is not None:
+                            result_callback(job_id, "skipped", None)
+                        return job.get("job_name") or job_id
+                    (dest / "result.tgz").unlink(missing_ok=True)
+                    _warn_missing_artifact(job_id)
+                    url = None
+                if url and extract_artifacts:
+                    set_stage("extracting artifact")
+                    _extract_shared_archive(staging / "result.tgz", staging / "artifacts")
+
+            dest.mkdir(parents=True, exist_ok=True)
+            set_stage("metrics")
+            _write_json(dest / "job.json", job)
+            _write_json(dest / "metrics.json", client.get_job_metrics(job_id))
+            _write_json(dest / "artifacts.json", artifact)
+            if include_events:
+                set_stage("events")
+                _write_text(dest / "events.txt", _format_events(client.get_job_events(job_id)))
+            if include_logs:
+                set_stage("logs")
+                _write_logs(dest / "logs", client, job_id, job)
+
+            if url:
+                set_stage("publishing artifact")
+                if extract_artifacts:
+                    _commit_staged_artifacts(
+                        staging / "artifacts", dest / "artifacts", archive=staging / "result.tgz"
+                    )
+                else:
+                    (staging / "result.tgz").replace(dest / "result.tgz")
+                if result_callback is not None:
+                    result_callback(job_id, "downloaded", None)
+            elif result_callback is not None:
+                result_callback(job_id, "skipped", None)
+    except Exception as exc:
+        if result_callback is not None:
+            result_callback(job_id, "failed", None)
+        raise RuntimeError(f"Failed to export job {job_id} at stage '{stage}': {exc}") from exc
+    return None
+
+
+def _download_shared_archive(url: str, dest: Path, timeout: float) -> None:
+    """Stream a signed URL without including it in user-visible errors."""
+    try:
+        with requests.get(url, stream=True, timeout=(10, timeout)) as response:
+            if response.status_code == 404:
+                raise FileNotFoundError("shared artifact was not found")
+            if response.status_code >= 400:
+                raise RuntimeError(f"shared artifact download returned HTTP {response.status_code}")
+            with dest.open("wb") as output:
+                for chunk in response.iter_content(chunk_size=4 * 1024 * 1024):
+                    if chunk:
+                        output.write(chunk)
+    except requests.RequestException:
+        raise RuntimeError("shared artifact download failed") from None
+
+
+def _extract_shared_archive(archive: Path, artifacts: Path) -> None:
+    """Extract an archive inside a fresh staging directory with bounded links."""
+    raw = artifacts.parent / "unpacked"
+    raw.mkdir()
+    try:
+        directory_modes: dict[Path, int] = {}
+        with tarfile.open(archive, "r:gz") as tar:
+            for member in tar:
+                name = member.name
+                while name.startswith("./"):
+                    name = name[2:]
+                if name in ("", ".") and member.isdir():
+                    continue
+                parts = PurePosixPath(name).parts
+                if (
+                    not name
+                    or name.startswith("/")
+                    or "\\" in name
+                    or "\x00" in name
+                    or any(part in {".", ".."} for part in parts)
+                    or not (member.isfile() or member.isdir() or member.issym() or member.islnk())
+                ):
+                    raise ValueError("unsafe shared artifact archive member")
+                target = raw / name
+                if not target.resolve().is_relative_to(raw.resolve()):
+                    raise ValueError("shared artifact archive path escapes destination")
+                target.parent.mkdir(parents=True, exist_ok=True)
+                if member.isdir():
+                    target.mkdir(exist_ok=True)
+                    directory_modes[target] = member.mode & 0o777
+                elif member.isfile():
+                    with tar.extractfile(member) as source, target.open("wb") as output:
+                        shutil.copyfileobj(source, output)
+                    target.chmod(member.mode & 0o777)
+                else:
+                    link = member.linkname
+                    if (
+                        not link
+                        or link.startswith("/")
+                        or "\\" in link
+                        or "\x00" in link
+                        or re.match(r"^[A-Za-z]:", link)
+                    ):
+                        raise ValueError("unsafe shared artifact archive link")
+                    link_target = (target.parent if member.issym() else raw) / link
+                    if not link_target.resolve().is_relative_to(raw.resolve()):
+                        raise ValueError("shared artifact archive link escapes destination")
+                    if target.exists() or target.is_symlink():
+                        target.unlink()
+                    if member.issym():
+                        target.symlink_to(link)
+                    else:
+                        if not link_target.is_file():
+                            raise ValueError("shared artifact hard link target is not a file")
+                        os.link(link_target.resolve(), target)
+
+        entries = list(raw.iterdir())
+        root = (
+            entries[0]
+            if len(entries) == 1 and entries[0].is_dir() and not entries[0].is_symlink()
+            else raw
+        )
+        output_dir = artifacts / "output"
+        output_dir.mkdir(parents=True)
+        root_path = root.resolve()
+        rewritten_links: dict[Path, str] = {}
+        for entry in raw.rglob("*"):
+            if not entry.is_symlink():
+                continue
+            target = entry.resolve()
+            if not target.is_relative_to(root_path):
+                raise ValueError("shared artifact archive link escapes output")
+            final_link = output_dir / entry.relative_to(root)
+            final_target = output_dir / target.relative_to(root_path)
+            rewritten_links[final_link] = os.path.relpath(final_target, final_link.parent)
+        for entry in root.iterdir():
+            entry.replace(output_dir / entry.name)
+        for link_path, link_target in rewritten_links.items():
+            link_path.unlink()
+            link_path.symlink_to(link_target)
+            if not link_path.resolve().is_relative_to(output_dir.resolve()):
+                raise ValueError("shared artifact archive link escapes output")
+        # Apply explicit directory modes after all writes and link rewrites so
+        # private parents do not prevent extraction of their children.
+        for source_dir, mode in sorted(
+            directory_modes.items(), key=lambda item: len(item[0].parts), reverse=True
+        ):
+            final_dir = output_dir / source_dir.relative_to(root)
+            if (
+                final_dir.is_symlink()
+                or not final_dir.is_dir()
+                or not final_dir.resolve().is_relative_to(output_dir.resolve())
+            ):
+                raise ValueError("shared artifact archive directory changed type")
+            final_dir.chmod(mode)
+    finally:
+        shutil.rmtree(raw, ignore_errors=True)
+
+
 def _normalize_file_selectors(values: Optional[list[str]]) -> Optional[list[str]]:
     selectors: list[str] = []
     for raw in values or []:

{ap_client-0.6.0.dev0 → ap_client-0.6.0.dev2}/ap_client/irepo_sdk.py

@@ -451,7 +451,6 @@ def _cached_oss_probe(
 
         _probe_cache_log(verbose, status, cache_endpoint)
         reachable = run_probe()
-        now = _now()
         with _oss_probe_cache_lock(path, verbose=verbose) as write_locked:
             if not write_locked:
                 _probe_cache_log(verbose, "write skipped (cache busy)", cache_endpoint)
@@ -460,6 +459,7 @@ def _cached_oss_probe(
                 latest_entries = _read_oss_probe_cache(path)
             except Exception:
                 latest_entries = []
+            now = _now()
             fresh_entries = [
                 entry
                 for entry in latest_entries

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

@@ -138,20 +138,31 @@ def _safe_identifier(value: Any) -> str | None:
 
 
 class ManagedAKProtocolError(RuntimeError):
-    """A response cannot confirm that the requested AK reference was honored."""
+    """An unconfirmed AK reference, with only safe receipt identities retained."""
 
     def __init__(self, ak_id: str, response: Any):
         self.ak_id = ak_id
-        self.response = response
+        self.response: dict[str, Any] = {}
         self.job_ids: list[str] = []
         self.group_id = None
         if isinstance(response, dict):
             self.group_id = _safe_identifier(response.get("group_id"))
-            candidates = [response.get("job_id")]
+            if self.group_id:
+                self.response["group_id"] = self.group_id
+            job_id = _safe_identifier(response.get("job_id"))
+            if job_id:
+                self.response["job_id"] = job_id
+                self.job_ids.append(job_id)
             jobs = response.get("jobs")
             if isinstance(jobs, list):
-                candidates.extend(job.get("job_id") for job in jobs if isinstance(job, dict))
-            self.job_ids = [value for value in map(_safe_identifier, candidates) if value]
+                job_ids = [
+                    value
+                    for job in jobs
+                    if isinstance(job, dict)
+                    if (value := _safe_identifier(job.get("job_id")))
+                ]
+                self.job_ids.extend(job_ids)
+                self.response["jobs"] = [{"job_id": value} for value in job_ids]
         super().__init__(
             f"Managed AK protocol mismatch: server did not acknowledge ak_id={ak_id}. "
             f"Returned Job IDs: {self.job_ids}. Verify these jobs before resubmitting; "

ap_client-0.6.0.dev2/ap_client/share_api.py

@@ -0,0 +1,229 @@
+"""Read-only API adapter for Job and Group share tokens."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import Any
+from urllib.parse import quote, quote_plus
+
+import requests
+
+from .api import APIClient, APIError, PaginationProtocolError, TimeoutType
+
+
+class ShareAPIClient(APIClient):
+    """Use existing export/CLI readers against the token-scoped share routes."""
+
+    is_share = True
+
+    def __init__(self, config, token: str, *, group_id: str | None = None):
+        if not token or not token.strip():
+            raise ValueError("--share-token must not be empty")
+        # The share token is the only credential for these public routes.
+        headers = {
+            key: value
+            for key, value in config.headers.items()
+            if key.lower()
+            not in {
+                "authorization",
+                "x-api-key",
+                "cookie",
+                "proxy-authorization",
+                "x-access-token",
+                "x-apiserver-token",
+            }
+        }
+        safe_config = replace(config, headers=headers, token_key=None, verbose_redaction=True)
+        super().__init__(safe_config)
+        self.share_token = token.strip()
+        self.share_group_id = group_id
+
+    @classmethod
+    def from_client(cls, client: APIClient, token: str, *, group_id: str | None = None):
+        return cls(client.config, token, group_id=group_id)
+
+    def _group_path(self, group_id: str, suffix: str = "") -> str:
+        if self.share_group_id != group_id:
+            raise ValueError("Group share token requires its matching group ID")
+        return f"/share/view/groups/{quote(group_id, safe='')}{suffix}"
+
+    def _job_path(self, job_id: str, suffix: str = "") -> str:
+        encoded_job = quote(job_id, safe="")
+        return f"/share/view/jobs/{encoded_job}{suffix}"
+
+    def _share_get(self, path: str, *, timeout: TimeoutType = None, **params: Any) -> Any:
+        kwargs = {"timeout": timeout} if timeout is not None else {}
+        return self._get(path, params={"token": self.share_token, **params}, **kwargs)
+
+    def _token_spellings(self) -> set[str]:
+        return {
+            self.share_token,
+            quote(self.share_token, safe=""),
+            quote_plus(self.share_token),
+        }
+
+    def _redact_token(self, value: Any) -> str:
+        result = str(value)
+        for secret in self._token_spellings():
+            if secret:
+                result = result.replace(secret, "<redacted>")
+        return result
+
+    def _redacted_response(self, response: requests.Response | None) -> requests.Response | None:
+        if response is None:
+            return None
+        safe = requests.Response()
+        safe.status_code = response.status_code
+        safe.headers.update(
+            {key: self._redact_token(value) for key, value in response.headers.items()}
+        )
+        safe.url = self._redact_token(response.url or "")
+        safe.reason = self._redact_token(response.reason or "")
+        content = response.content
+        for secret in self._token_spellings():
+            if secret:
+                content = content.replace(secret.encode("utf-8"), b"<redacted>")
+        safe._content = content
+        return safe
+
+    def _request(self, *args, **kwargs):
+        try:
+            return super()._request(*args, **kwargs)
+        except APIError as exc:
+            # requests errors and server error bodies can echo the query string.
+            raise APIError(
+                exc.status_code,
+                self._redact_token(exc.detail),
+                exc.request_id,
+                self._redacted_response(exc.response),
+            ) from None
+
+    def _log_request(self, method, url, request_id, headers, params, body, **kwargs) -> None:
+        # The generic verbose redactor does not classify a plain `token` key.
+        safe_params = dict(params or {})
+        if params and "token" in params:
+            safe_params["token"] = "<redacted>"
+        super()._log_request(method, url, request_id, headers, safe_params, body, **kwargs)
+
+    def _log_exception(self, method, url, request_id, duration_ms, exc) -> None:
+        super()._log_exception(
+            method,
+            url,
+            request_id,
+            duration_ms,
+            exc,
+            error_detail=self._redact_token(exc),
+        )
+
+    def _log_retry(
+        self, method, url, request_id, attempt, max_attempts, delay, *, status=None, error=None
+    ) -> None:
+        super()._log_retry(
+            method,
+            url,
+            request_id,
+            attempt,
+            max_attempts,
+            delay,
+            status=status,
+            error=self._redact_token(error) if error is not None else None,
+        )
+
+    def _summarize_response(self, resp, raw) -> str:
+        return self._redact_token(super()._summarize_response(resp, raw))
+
+    def get_group(self, group_id: str, timeout: TimeoutType = None) -> dict:
+        return self._share_get(self._group_path(group_id), timeout=timeout)
+
+    def get_group_stats(self, group_id: str, timeout: TimeoutType = None) -> dict:
+        return self.get_group(group_id, timeout=timeout)
+
+    def list_jobs(
+        self, *, group_id: str | None = None, skip: int = 0, limit: int = 100, **kwargs
+    ) -> dict:
+        if group_id is None:
+            raise ValueError("Group share token requires --group-id to list jobs")
+        return self._share_get(self._group_path(group_id, "/jobs"), skip=skip, limit=limit)
+
+    def get_group_eval_summary(self, group_id: str) -> dict:
+        return self._share_get(self._group_path(group_id, "/eval_summary"))
+
+    def get_group_eval(self, group_id: str) -> dict:
+        result = self.get_group_eval_summary(group_id)
+        tasks: list[dict] = []
+        while True:
+            page = self._share_get(
+                self._group_path(group_id, "/eval_tasks"), skip=len(tasks), limit=500
+            )
+            batch = page.get("tasks")
+            total = page.get("total")
+            if not isinstance(batch, list) or not isinstance(total, int) or total < 0:
+                raise PaginationProtocolError("invalid share eval task page")
+            tasks.extend(batch)
+            if len(tasks) >= total:
+                break
+            if not batch:
+                raise PaginationProtocolError("share eval tasks ended before total")
+        return {**result, "per_task": tasks}
+
+    def get_job(
+        self,
+        job_id: str,
+        *,
+        include_params: bool = False,
+        include_spec: bool = False,
+        spec_format: str = "json",
+        timeout: TimeoutType = None,
+    ) -> dict:
+        result = self._share_get(self._job_path(job_id), timeout=timeout)
+        # Share responses include these payloads unconditionally; preserve the
+        # existing CLI opt-in presentation contract.
+        result = dict(result)
+        if not include_params:
+            result.pop("params", None)
+        if not include_spec:
+            result.pop("job_spec_data", None)
+        elif spec_format == "yaml" and isinstance(result.get("job_spec_data"), dict):
+            import yaml
+
+            spec_data = dict(result["job_spec_data"])
+            if "spec" in spec_data:
+                spec_data["spec_yaml"] = yaml.safe_dump(
+                    spec_data["spec"], allow_unicode=True, sort_keys=False
+                )
+            result["job_spec_data"] = spec_data
+        return result
+
+    def get_job_metrics(self, job_id: str) -> dict:
+        return self._share_get(self._job_path(job_id, "/metrics"))
+
+    def get_job_events(self, job_id: str, container: str | None = None) -> dict:
+        params = {"container": container} if container else {}
+        return self._share_get(self._job_path(job_id, "/events"), **params)
+
+    def get_job_containers(self, job_id: str) -> dict:
+        return self._share_get(self._job_path(job_id, "/containers"))
+
+    def get_job_logs(
+        self,
+        job_id: str,
+        container: str | None = None,
+        offset: int | None = 0,
+        limit: int | None = 500,
+    ) -> dict:
+        params: dict[str, Any] = {}
+        if container:
+            params["container"] = container
+        if offset is not None:
+            params["offset"] = offset
+        if limit is not None:
+            params["limit"] = limit
+        return self._share_get(self._job_path(job_id, "/logs"), **params)
+
+    def get_job_artifacts(self, job_ids: list[str], *, download_mode=None) -> list:
+        if download_mode is not None:
+            raise ValueError("share artifact endpoint does not accept download_mode")
+        items: list = []
+        for job_id in job_ids:
+            items.extend(self._share_get(self._job_path(job_id, "/artifacts")))
+        return items

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.6.0.dev0"
+version = "0.6.0.dev2"
 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"