ap-client 0.4.0__tar.gz → 0.5.0.dev0__tar.gz

{ap_client-0.4.0 → ap_client-0.5.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.4.0
+Version: 0.5.0.dev0
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
@@ -9,9 +9,9 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: websockets>=13.0
 Provides-Extra: all
-Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.2; extra == 'all'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.4; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.2; extra == 'dataset'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.4; 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.5.0.dev0/ap_client/akpool_commands.py

@@ -0,0 +1,181 @@
+"""``ap akpool`` 命令族 —— Account Pool(托管 AK)观测操作。
+
+* ``akpool rpm get`` → apiserver ``GET /apis/v1/model-api-keys/rpm-usage``
+  (中心侧,走 ``APIClient._get_central``),按 AK + 模型查询当前 RPM 用量与上限。
+
+AK 的两种指定方式互斥且必填其一:``--ak-id``(uak-xxx,仅平台托管 AK)或
+``--masked-ak``(掩码后 6 位,未托管 AK 走这条路)。服务端同口径(都缺或都给 →
+400),CLI 侧先拦一道,不发请求。``--time-range`` 是 Go duration 风格
+(``30s``/``5m``/``1h``);显式 ``--from``/``--to``(RFC3339)时覆盖
+``--time-range``。
+
+响应是嵌套结构(无信封):``usage.current_rpm``/``usage.sampled_at``、
+``rpm.limit``/``rpm.limit_state``/``rpm.synced_at``、``usage_status``、
+``time_range``、``ak_id``/``masked_api_key``/``model_id``。json/yaml 原样透传;
+plain/table 摊平成单行 key=value 展示。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+import typer
+from ap_client import get_client
+
+__all__ = ["akpool_app", "register"]
+
+akpool_app = typer.Typer(help="Account Pool operations (managed API keys)")
+rpm_app = typer.Typer(help="Account Pool RPM usage operations")
+
+akpool_app.add_typer(rpm_app, name="rpm")
+
+
+def register(app: typer.Typer) -> None:
+    """把 ``akpool`` 挂到 ``ap`` 根命令上。"""
+    app.add_typer(akpool_app, name="akpool")
+
+
+_FORMAT_HELP = "Output format: plain/table/json/yaml (default: AP_FORMAT or command default)"
+_TIME_RANGE_HELP = "Lookback window for the RPM reading (Go duration, e.g. 30s/5m/1h)"
+_ISO_TIME_HELP = "RFC3339 timestamp, e.g. 2026-09-21T12:00:00+08:00"
+
+_TIME_RANGE_RE = re.compile(r"^\d+[smh]$")
+
+#: plain/table 输出的字段顺序,取值自嵌套响应(见 _flatten_rpm)。
+_RPM_KEYS = (
+    "current_rpm",
+    "rpm_limit",
+    "model",
+    "sampled_at",
+    "time_range",
+    "ak_id",
+    "usage_status",
+)
+
+
+def _fmt(output_format: Optional[str]) -> str:
+    from .cli import _normalize_output_format
+
+    return _normalize_output_format(output_format, keep_table=True)
+
+
+def _check_time_range(value: str) -> str:
+    normalized = str(value or "").strip().lower()
+    if not _TIME_RANGE_RE.fullmatch(normalized):
+        raise typer.BadParameter(
+            f"--time-range must be a duration like 30s/5m/1h, got {value!r}"
+        )
+    return normalized
+
+
+def _flatten_rpm(payload: dict) -> dict:
+    """把嵌套的 rpm-usage 响应摊平成 plain/table 展示用的扁平 dict。
+
+    null 值渲染为 ``-``(如未托管 AK 的 ``ak_id``、未知限额的 ``rpm.limit``)。
+    """
+    rpm = payload.get("rpm")
+    usage = payload.get("usage")
+    flat = {
+        "current_rpm": usage.get("current_rpm") if isinstance(usage, dict) else None,
+        "rpm_limit": rpm.get("limit") if isinstance(rpm, dict) else None,
+        "model": payload.get("model_id"),
+        "sampled_at": usage.get("sampled_at") if isinstance(usage, dict) else None,
+        "time_range": payload.get("time_range"),
+        "ak_id": payload.get("ak_id"),
+        "usage_status": payload.get("usage_status"),
+    }
+    return {key: (value if value is not None else "-") for key, value in flat.items()}
+
+
+def _emit_rpm(payload: Any, output_format: str) -> None:
+    from .cli import _print_formatted, _print_rich_table
+
+    if not isinstance(payload, dict):
+        payload = {"value": payload}
+    if output_format in ("json", "yaml"):
+        _print_formatted(payload, output_format)
+        return
+    flat = _flatten_rpm(payload)
+    keys = [key for key in _RPM_KEYS if key in flat]
+    keys += [key for key in flat if key not in keys]
+    if output_format == "table":
+        _print_rich_table([flat], [(key, key) for key in keys])
+        return
+    _print_rpm_plain(payload)
+
+
+def _print_rpm_plain(payload: dict) -> None:
+    """plain 输出：标题行(usage_status) + 对齐 key/value，与 _print_job_get_plain 同风格。
+
+    current_rpm 在限额已知时附利用率百分比；rpm_limit 未知/不限时展示 limit_state。
+    ak_id / masked_api_key 为 null(未托管 AK)时整行省略。
+    """
+    from .cli import _print_key_values
+
+    rpm = payload.get("rpm")
+    usage = payload.get("usage")
+    rpm = rpm if isinstance(rpm, dict) else {}
+    usage = usage if isinstance(usage, dict) else {}
+
+    current = usage.get("current_rpm")
+    limit = rpm.get("limit")
+    limit_state = rpm.get("limit_state") or "unknown"
+
+    if isinstance(current, (int, float)) and isinstance(limit, (int, float)) and limit > 0:
+        current_text = f"{current} ({current / limit * 100:.1f}% of limit)"
+    else:
+        current_text = current
+    limit_text = f"{limit} ({limit_state})" if limit is not None else limit_state
+
+    typer.echo(f"AK RPM Usage ({payload.get('usage_status') or 'unknown'})")
+    _print_key_values(
+        [
+            ("current_rpm", current_text),
+            ("rpm_limit", limit_text),
+            ("model", payload.get("model_id")),
+            ("ak_id", payload.get("ak_id")),
+            ("masked_api_key", payload.get("masked_api_key")),
+            ("sampled_at", usage.get("sampled_at")),
+            ("time_range", payload.get("time_range")),
+        ]
+    )
+
+
+@rpm_app.command("get")
+def rpm_get(
+    ak_id: Optional[str] = typer.Option(
+        None, "--ak-id", help="Managed AK ID (uak-xxx); mutually exclusive with --masked-ak"
+    ),
+    masked_ak: Optional[str] = typer.Option(
+        None, "--masked-ak", help="Last 6 characters of the AK; mutually exclusive with --ak-id"
+    ),
+    model: str = typer.Option(..., "--model", help="Model the RPM reading applies to"),
+    time_range: str = typer.Option("5m", "--time-range", help=_TIME_RANGE_HELP),
+    from_time: Optional[str] = typer.Option(
+        None, "--from", help=f"Window start ({_ISO_TIME_HELP}); overrides --time-range"
+    ),
+    to_time: Optional[str] = typer.Option(
+        None, "--to", help=f"Window end ({_ISO_TIME_HELP}); overrides --time-range"
+    ),
+    output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
+):
+    """Show the current RPM usage and limit of a managed AK for one model."""
+    resolved_ak_id = (ak_id or "").strip()
+    resolved_masked_ak = (masked_ak or "").strip()
+    if bool(resolved_ak_id) == bool(resolved_masked_ak):
+        raise typer.BadParameter("exactly one of --ak-id or --masked-ak is required")
+    if not model.strip():
+        raise typer.BadParameter("--model must not be empty")
+    normalized_range = _check_time_range(time_range)
+    output_format = _fmt(output_format)
+
+    result = get_client().get_akpool_rpm(
+        model=model.strip(),
+        ak_id=resolved_ak_id or None,
+        masked_ak=resolved_masked_ak or None,
+        time_range=normalized_range,
+        from_time=from_time,
+        to_time=to_time,
+    )
+    _emit_rpm(result, output_format)

{ap_client-0.4.0 → ap_client-0.5.0.dev0}/ap_client/api.py

@@ -9,10 +9,11 @@ import sys
 import time
 import uuid
 from email.utils import parsedate_to_datetime
-from typing import Any, Optional, Union
+from typing import Any, Literal, Optional, Union
 from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
 
 import requests
+from urllib3.util import Timeout as HTTPTimeout
 
 from .config import Config, ConfigurationError, get_config, has_cluster_header
 from .managed_ak import require_managed_ak_ack, validate_ak_id, validate_ak_selection
@@ -126,7 +127,6 @@ EXTRA_AGG_OPS = ("avg", "sum")
 _OTHERS_MODEL = {
     "name": "Others",
     "series_name": "",
-    "is_default": False,
     "source_id": "",
     "series_id": "",
 }
@@ -171,7 +171,9 @@ def _merge_meta_tags(
     conflicts = [k for k, v in provided.items() if v and str(v).strip() and k in existing_keys]
     if conflicts:
         raise ValueError(
-            "tags 中已包含 " + ", ".join(conflicts) + "，与 meta 参数冲突，请只保留一种方式"
+            "tags already contains "
+            + ", ".join(conflicts)
+            + "; it conflicts with the meta parameter, keep only one"
         )
     extra = [
         f"{key}:{str(value).strip()}"
@@ -343,6 +345,11 @@ def _split_paged(payload: Any) -> tuple[list[dict], dict]:
     )
 
 
+# apiserver meta-tags 端点单页上限（handler.metaTagPaging 截断到 200；
+# 缺省仅 20，目录查询必须显式带上并翻页）。
+_META_TAG_PAGE_SIZE = 200
+
+
 class APIClient:
     """Agent Platform API client."""
 
@@ -401,6 +408,8 @@ class APIClient:
         params: Optional[dict] = None,
         json_body: Any = None,
         timeout: TimeoutType = None,
+        deadline: Optional[float] = None,
+        _return_response: bool = False,
     ) -> Any:
         """Send an HTTP request with X-Request-ID and optional verbose logging."""
         self._require_cluster_config()
@@ -412,6 +421,7 @@ class APIClient:
         verbose = self.config.verbose
         max_attempts = self._max_attempts_for(method)
         for attempt in range(1, max_attempts + 1):
+            attempt_timeout = _deadline_timeout(timeout, deadline)
             request_id = str(uuid.uuid4())
             headers = {"X-Request-ID": request_id}
             if verbose:
@@ -435,9 +445,11 @@ class APIClient:
                     params=params,
                     json=json_body,
                     headers=headers,
-                    timeout=timeout,
+                    timeout=attempt_timeout,
                 )
             except requests.RequestException as exc:
+                if deadline is not None:
+                    _manifest_budget_remaining(deadline)
                 duration_ms = (time.perf_counter() - start) * 1000
                 if verbose:
                     self._log_exception(method, url, request_id, duration_ms, exc)
@@ -453,10 +465,12 @@ class APIClient:
                             delay,
                             error=f"{type(exc).__name__}: {exc}",
                         )
-                    time.sleep(delay)
+                    _deadline_sleep(delay, deadline)
                     continue
                 raise APIError(None, str(exc), request_id, None) from exc
             duration_ms = (time.perf_counter() - start) * 1000
+            if deadline is not None:
+                _manifest_budget_remaining(deadline)
             if verbose:
                 self._log_response(method, url, request_id, resp, duration_ms)
             if not resp.ok:
@@ -472,10 +486,12 @@ class APIClient:
                             delay,
                             status=resp.status_code,
                         )
-                    time.sleep(delay)
+                    _deadline_sleep(delay, deadline)
                     continue
                 detail = _response_error_detail(resp)
                 raise APIError(resp.status_code, detail, request_id, resp)
+            if _return_response:
+                return resp, request_id
             if not resp.content:
                 return None
             try:
@@ -977,24 +993,142 @@ class APIClient:
                 return item
         raise APIError(404, f"meta model {name!r} not found", "client-filter", None)
 
+    def _get_meta_tag_catalog(
+        self, path: str, params: Optional[dict] = None
+    ) -> tuple[list[dict], dict]:
+        """按 benchmarks 同口径自动翻页取全量目录记录，返回 ``(records, pagination)``。
+
+        apiserver ``meta-tags`` 端点分页参数为 ``page`` / ``page_size``（缺省
+        20、上限 200，见 handler.metaTagPaging）；单页取用会把值目录静默截断
+        （``meta-job-type`` 漏掉 ``Eval-Eval`` 时 ``default`` 会被算成空串），
+        故显式传上限并翻页。
+        """
+        records: list[dict] = []
+        pagination: dict = {}
+        page = 1
+        # 与 list_benchmarks 同口径的 100 页上限，防分页异常导致死循环
+        max_pages = 100
+        while page <= max_pages:
+            query = dict(params or {})
+            query["page"] = page
+            query["page_size"] = _META_TAG_PAGE_SIZE
+            page_records, pagination = _split_paged(self._get_central(path, params=query))
+            records.extend(page_records)
+            if not page_records or not pagination:
+                break
+            try:
+                total = int(pagination.get("total"))
+            except (TypeError, ValueError):
+                total = None
+            if total is not None:
+                if len(records) >= total:
+                    break
+            elif len(page_records) < _META_TAG_PAGE_SIZE:
+                break
+            page += 1
+        return records, pagination
+
+    def list_meta_tags(self) -> dict:
+        """meta 标签键目录（apiserver GET /apis/v1/meta-tags/keys，返回 {items:[...]}）。
+
+        apiserver 用 PagedSuccess envelope（{code,data,pagination}）返回，
+        按基准 benchmarks 客户端同口径经 _split_paged 拆包并自动翻页；
+        裸列表等旧形态兜底为空分页。
+        """
+        records, pagination = self._get_meta_tag_catalog("/meta-tags/keys")
+        result = {"items": records}
+        if pagination:
+            result["pagination"] = pagination
+        return result
+
+    def get_meta_tags(self, key: str) -> dict:
+        """单个 meta 键的值目录（GET /apis/v1/meta-tags?key=，返回 {items:[...]}）。
+
+        与 ``list_meta_tags`` 同样自动翻页，避免值目录被单页默认大小截断。
+        """
+        records, pagination = self._get_meta_tag_catalog("/meta-tags", {"key": key})
+        result = {"items": records}
+        if pagination:
+            result["pagination"] = pagination
+        return result
+
     def list_meta_job_types(self) -> dict:
-        """任务类型词表（本地常量，不走接口）。
+        """任务类型词表（目录驱动：GET /apis/v1/meta-tags?key=meta-job-type）。
 
-        job-type 词表固定为 Eval-Eval（默认）+ Others（兜底手动输入），
-        不依赖服务端可用性。default 固定 ``Eval-Eval``（job-type 词表
-        不再走集群配置，``AP_META_DEFAULT_JOB_TYPE`` env 已删）。
+        仅取目录中 ``is_enabled`` 的值（缺失按启用解析）+ 末尾 ``Others``
+        兜底行；``default`` 为 ``Eval-Eval``（在目录中时，否则空串）。
+        目录请求失败或为空 → 回退本地常量（Eval-Eval + Others，fail-open），
+        并在 stderr 打一行告警，词表降级可见但不阻塞命令。
         """
-        default = "Eval-Eval"
+        error: Exception | None = None
+        try:
+            items = self.get_meta_tags("meta-job-type").get("items") or []
+        except Exception as exc:  # fail-open：目录不可用不阻塞词表命令
+            error = exc
+            items = []
+        if items:
+            options = []
+            for item in items:
+                value = str(item.get("value") or "").strip()
+                if value and item.get("is_enabled", True):
+                    options.append({"value": value})
+            if options:
+                default = "Eval-Eval" if any(o["value"] == "Eval-Eval" for o in options) else ""
+                return {
+                    "meta_job_type": {
+                        "default": default,
+                        "options": [*options, {"value": "Others"}],
+                    }
+                }
+        _write_stderr(
+            [
+                "warning: meta-job-type catalog unavailable or empty, "
+                f"falling back to local constants (reason={error or 'empty catalog'})"
+            ]
+        )
         return {
             "meta_job_type": {
-                "default": default,
-                "options": [
-                    {"value": default, "is_default": True},
-                    {"value": "Others", "is_default": False},
-                ],
+                "default": "Eval-Eval",
+                "options": [{"value": "Eval-Eval"}, {"value": "Others"}],
             }
         }
 
+    # ==================== Account Pool operations ====================
+
+    def get_akpool_rpm(
+        self,
+        *,
+        model: str,
+        ak_id: Optional[str] = None,
+        masked_ak: Optional[str] = None,
+        time_range: Optional[str] = None,
+        from_time: Optional[str] = None,
+        to_time: Optional[str] = None,
+        timeout: TimeoutType = None,
+    ) -> dict:
+        """查询托管 AK 在指定模型上的当前 RPM 用量与上限（GET /apis/v1/model-api-keys/rpm-usage）。
+
+        ``ak_id``(uak-xxx) 与 ``masked_ak``(掩码后 6 位) 二选一，都缺或都给
+        服务端返回 400；``from_time``/``to_time``(RFC3339) 显式指定时覆盖
+        ``time_range``(Go duration，如 5m/1h，服务端默认 5m)。
+        响应为嵌套结构：``usage.current_rpm``/``usage.sampled_at``、
+        ``rpm.limit``/``rpm.limit_state``/``rpm.synced_at``、``usage_status``；
+        查未托管 AK 时 ``ak_id`` 为 null。
+        """
+        validate_ak_id(ak_id)
+        params: dict = {"model": model}
+        if ak_id is not None:
+            params["ak_id"] = ak_id
+        if masked_ak is not None:
+            params["masked_ak"] = masked_ak
+        if time_range is not None:
+            params["time_range"] = time_range
+        if from_time is not None:
+            params["from"] = from_time
+        if to_time is not None:
+            params["to"] = to_time
+        return self._get_central("/model-api-keys/rpm-usage", params=params, timeout=timeout)
+
     # ==================== Job operations ====================
 
     def create_group(
@@ -1150,6 +1284,7 @@ class APIClient:
         experiment: Optional[str] = None,
         ak_id: Optional[str] = None,
         instance_range: Optional[str] = None,
+        profile: Optional[str] = None,
     ) -> dict:
         """Create a job."""
         body = self.build_create_job_body(
@@ -1180,6 +1315,7 @@ class APIClient:
             credential_type=credential_type,
             account_pool=account_pool,
             eval_config=eval_config,
+            profile=profile,
             profile_id=profile_id,
             profile_version=profile_version,
             instances=instances,
@@ -1260,16 +1396,19 @@ class APIClient:
         experiment: Optional[str] = None,
         ak_id: Optional[str] = None,
         instance_range: Optional[str] = None,
+        profile: Optional[str] = None,
     ) -> dict:
         """Build the /jobs request body for job creation."""
+        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(
             account_pool=account_pool,
             credential_type=credential_type,
             params=params,
             params_list=params_list,
         )
-        if not template and not profile_id:
-            raise ValueError("Either template or profile_id is required")
+        if not template and not profile_id and profile is None:
+            raise ValueError("Either template, profile or profile_id is required")
         validate_ak_selection(ak_id, params, params_list, overrides)
         body: dict = {}
         if template is not None:
@@ -1347,6 +1486,8 @@ class APIClient:
             body["eval_config"] = eval_config
 
         # Profile mode fields
+        if profile is not None:
+            body["profile"] = profile
         if profile_id is not None:
             body["profile_id"] = profile_id
         if profile_version is not None:
@@ -2024,9 +2165,14 @@ class APIClient:
         return self._delete(f"/concurrency-policies/{quote(policy_id)}")
 
     # ==================== Logs and artifacts ====================
-    def cancel_group(self, group_id: str) -> dict:
+    def preview_group_cancel(self, group_id: str) -> dict:
+        """Preview the current Group cancel scope and obtain confirmation if required."""
+        return self._post(f"/groups/{quote(group_id)}/cancel-preview", {})
+
+    def cancel_group(self, group_id: str, confirmation_token: Optional[str] = None) -> dict:
         """Cancel all unfinished jobs in a group."""
-        return self._post(f"/groups/{quote(group_id)}/cancel", {})
+        body = {"confirmation_token": confirmation_token} if confirmation_token else {}
+        return self._post(f"/groups/{quote(group_id)}/cancel", body)
 
     def get_job_logs(
         self,
@@ -2212,8 +2358,14 @@ class APIClient:
         next_token: Optional[str] = None,
         pagination: Optional[str] = None,
         include_total: bool = True,
+        download_mode: Optional[Literal["oss", "proxy", "both"]] = None,
     ) -> dict:
-        """Get one page of artifact download links for a group."""
+        """Get one page of archive links.
+
+        Omit download_mode for the server default and legacy response. Explicit
+        oss/proxy/both modes add a downloads mapping to each artifact; both can
+        return only one successful provider. This method does not download files.
+        """
         params: dict[str, object] = {"skip": skip, "limit": limit}
         if include_post_process:
             params["include_post_process"] = True
@@ -2223,19 +2375,28 @@ class APIClient:
             params["pagination"] = pagination
         if not include_total:
             params["include_total"] = False
+        if download_mode is not None:
+            params["download_mode"] = download_mode
         endpoint = f"/groups/{quote(group_id)}/artifacts"
         response = self._get(endpoint, params=params)
         _ensure_next_token_honored(response, next_token=next_token, endpoint=endpoint)
         return response
 
-    def get_group_artifacts(self, group_id: str, include_post_process: bool = False) -> dict:
-        """Get artifact download links for a group."""
+    def get_group_artifacts(
+        self,
+        group_id: str,
+        include_post_process: bool = False,
+        *,
+        download_mode: Optional[Literal["oss", "proxy", "both"]] = None,
+    ) -> dict:
+        """Collect all archive-link pages, preserving download_mode on every page."""
         next_token: str | None = None
         skip = 0
         mode: str | None = None
         artifacts: list[dict] = []
         last_page: dict | None = None
 
+        download_options = {"download_mode": download_mode} if download_mode is not None else {}
         while True:
             page = self.get_group_artifacts_page(
                 group_id,
@@ -2245,6 +2406,7 @@ class APIClient:
                 next_token=next_token,
                 pagination="cursor" if mode in {None, "cursor"} else None,
                 include_total=False,
+                **download_options,
             )
             last_page = page
             page_artifacts = page.get("artifacts") or []
@@ -2278,9 +2440,17 @@ class APIClient:
         )
         return result
 
-    def get_job_artifacts(self, job_ids: list) -> list:
-        """Get artifact download links for one or more jobs."""
-        return self._post("/jobs/artifacts", {"job_ids": job_ids})
+    def get_job_artifacts(
+        self,
+        job_ids: list,
+        *,
+        download_mode: Optional[Literal["oss", "proxy", "both"]] = None,
+    ) -> list:
+        """Get archive links; explicit modes also return typed ``downloads`` entries."""
+        body = {"job_ids": job_ids}
+        if download_mode is not None:
+            body["download_mode"] = download_mode
+        return self._post("/jobs/artifacts", body)
 
     def get_job_artifacts_manifest(
         self,
@@ -2295,6 +2465,52 @@ class APIClient:
             params=params,
         )
 
+    def wait_for_job_artifacts_manifest(self, job_id: str) -> dict:
+        """Poll the new API within one per-Job budget; HTTP failures keep normal retries."""
+        budget = self.config.artifact_manifest_wait_timeout
+        if not math.isfinite(budget) or budget <= 0:
+            raise ConfigurationError(
+                "AP_ARTIFACT_MANIFEST_WAIT_TIMEOUT must be a finite positive number"
+            )
+        deadline = time.monotonic() + budget
+        while True:
+            response, request_id = self._request(
+                "GET",
+                f"/jobs/{quote(job_id, safe='')}/artifacts/manifest",
+                deadline=deadline,
+                _return_response=True,
+            )
+            try:
+                payload = response.json()
+            except ValueError as exc:
+                raise APIError(
+                    response.status_code, "Invalid artifact manifest response", request_id, response
+                ) from exc
+            if not isinstance(payload, dict) or payload.get("job_id") != job_id:
+                raise APIError(
+                    response.status_code, "Invalid artifact manifest response", request_id, response
+                )
+            if response.status_code == 200:
+                if "manifest" not in payload or (
+                    payload["manifest"] is not None and not isinstance(payload["manifest"], list)
+                ):
+                    raise APIError(200, "Invalid artifact manifest response", request_id, response)
+                return payload
+            if response.status_code != 202 or payload.get("status") != "preparing":
+                raise APIError(
+                    response.status_code,
+                    "Invalid artifact preparation response",
+                    request_id,
+                    response,
+                )
+            try:
+                delay = float(response.headers.get("Retry-After", "2"))
+            except ValueError:
+                delay = 2.0
+            if not math.isfinite(delay) or delay <= 0:
+                delay = 2.0
+            _deadline_sleep(delay, deadline)
+
     def get_artifact_file_download_urls(self, job_id: str, paths: list[str]) -> dict:
         """Get download URLs for multiple artifact files."""
         endpoint = f"/jobs/{quote(job_id, safe='')}/artifacts/files/download"
@@ -3208,3 +3424,34 @@ def _summarize_json_value(data: Any, limit: int) -> str:
         summary = {"_count": len(data), "_sample": sample}
         return _truncate_text(_safe_json(summary), limit)
     return _truncate_text(_safe_json(data), limit)
+
+
+def _manifest_budget_remaining(deadline: float) -> float:
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise APIError(None, "Artifact manifest wait timed out", None, None)
+    return remaining
+
+
+def _deadline_timeout(
+    timeout: TimeoutType, deadline: Optional[float]
+) -> Union[TimeoutType, HTTPTimeout]:
+    if deadline is None:
+        return timeout
+    remaining = _manifest_budget_remaining(deadline)
+
+    def bounded(value):
+        return min(value, remaining) if value is not None else remaining
+
+    if isinstance(timeout, tuple):
+        connect, read = (bounded(value) for value in timeout)
+    else:
+        connect = read = bounded(timeout)
+    # The connect phase must consume the same remaining budget as the read.
+    return HTTPTimeout(total=remaining, connect=connect, read=read)
+
+
+def _deadline_sleep(delay: float, deadline: Optional[float]) -> None:
+    if deadline is not None:
+        delay = min(delay, _manifest_budget_remaining(deadline))
+    time.sleep(delay)