ap-client 0.2.0.dev0__tar.gz → 0.2.1__tar.gz

{ap_client-0.2.0.dev0 → ap_client-0.2.1}/PKG-INFO

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

{ap_client-0.2.0.dev0 → ap_client-0.2.1}/ap_client/api.py

@@ -268,6 +268,20 @@ class APIError(Exception):
         return f"API Error {self.status_code}: {self.detail} (request_id={self.request_id})"
 
 
+class PaginationProtocolError(RuntimeError):
+    """The server stopped honoring a pagination protocol already in use."""
+
+
+def _ensure_next_token_honored(response: dict, *, next_token: Optional[str], endpoint: str) -> None:
+    # An old server ignores the unknown next_token param and answers with its
+    # default first page, so a `response.get("next_token")` loop would silently
+    # repeat that page and drop the rest of the collection.
+    if next_token and "next_token" not in response:
+        raise PaginationProtocolError(
+            f"server stopped returning next_token while paginating {endpoint}; upgrade the server"
+        )
+
+
 def _secret_ws_params(workspace_id: Optional[str]) -> Optional[dict]:
     """Build the ``?workspace_id=`` query for name-addressed secret endpoints.
 
@@ -1267,6 +1281,9 @@ class APIClient:
         meta_job_type: Optional[str] = None,
         upstream_platform: Optional[str] = None,
         upstream_job_id: Optional[str] = None,
+        next_token: Optional[str] = None,
+        pagination: Optional[str] = None,
+        include_total: bool = True,
     ) -> dict:
         """List jobs."""
         params = {"skip": skip, "limit": limit}
@@ -1324,7 +1341,15 @@ class APIClient:
             params["created_at_sort"] = created_at_sort
         if finished_at_sort is not None:
             params["finished_at_sort"] = finished_at_sort
-        return self._get("/jobs", params=params)
+        if next_token:
+            params["next_token"] = next_token
+        if pagination:
+            params["pagination"] = pagination
+        if not include_total:
+            params["include_total"] = False
+        response = self._get("/jobs", params=params)
+        _ensure_next_token_honored(response, next_token=next_token, endpoint="/jobs")
+        return response
 
     # ==================== Group operations ====================
 
@@ -1515,6 +1540,9 @@ class APIClient:
         meta_job_type: Optional[str] = None,
         upstream_platform: Optional[str] = None,
         upstream_job_id: Optional[str] = None,
+        next_token: Optional[str] = None,
+        pagination: Optional[str] = None,
+        include_total: bool = True,
     ) -> dict:
         """List jobs in a group."""
         params: dict = {"skip": skip, "limit": limit}
@@ -1538,7 +1566,16 @@ class APIClient:
             params["upstream_job_id"] = upstream_job_id
         if include_post_process:
             params["include_post_process"] = True
-        return self._get(f"/groups/{quote(group_id)}/jobs", params=params)
+        if next_token:
+            params["next_token"] = next_token
+        if pagination:
+            params["pagination"] = pagination
+        if not include_total:
+            params["include_total"] = False
+        endpoint = f"/groups/{quote(group_id)}/jobs"
+        response = self._get(endpoint, params=params)
+        _ensure_next_token_honored(response, next_token=next_token, endpoint=endpoint)
+        return response
 
     def get_group_post_process_job_id(
         self, group_id: str, timeout: TimeoutType = None
@@ -2016,19 +2053,30 @@ class APIClient:
         skip: int = 0,
         limit: int = _GROUP_ARTIFACTS_PAGE_SIZE,
         include_post_process: bool = False,
+        next_token: Optional[str] = None,
+        pagination: Optional[str] = None,
+        include_total: bool = True,
     ) -> dict:
         """Get one page of artifact download links for a group."""
         params: dict[str, object] = {"skip": skip, "limit": limit}
         if include_post_process:
             params["include_post_process"] = True
-        return self._get(
-            f"/groups/{quote(group_id)}/artifacts",
-            params=params,
-        )
+        if next_token:
+            params["next_token"] = next_token
+        if pagination:
+            params["pagination"] = pagination
+        if not include_total:
+            params["include_total"] = False
+        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."""
+        next_token: str | None = None
         skip = 0
+        mode: str | None = None
         artifacts: list[dict] = []
         last_page: dict | None = None
 
@@ -2038,25 +2086,41 @@ class APIClient:
                 skip=skip,
                 limit=_GROUP_ARTIFACTS_PAGE_SIZE,
                 include_post_process=include_post_process,
+                next_token=next_token,
+                pagination="cursor" if mode in {None, "cursor"} else None,
+                include_total=False,
             )
             last_page = page
             page_artifacts = page.get("artifacts") or []
             artifacts.extend(page_artifacts)
+            has_token_field = "next_token" in page
 
-            total = page.get("total")
-            if total is not None and len(artifacts) >= total:
-                break
-            if len(page_artifacts) < _GROUP_ARTIFACTS_PAGE_SIZE:
-                break
-
-            skip += len(page_artifacts)
+            if mode is None:
+                mode = "cursor" if has_token_field else "offset"
 
-        return {
-            **last_page,
-            "skip": 0,
-            "limit": len(artifacts),
-            "artifacts": artifacts,
-        }
+            if mode == "cursor":
+                next_token = page.get("next_token")
+                if not next_token:
+                    break
+            else:
+                skip += len(page_artifacts)
+                total = page.get("total")
+                if not page_artifacts or len(page_artifacts) < _GROUP_ARTIFACTS_PAGE_SIZE:
+                    break
+                if total is not None and skip >= total:
+                    break
+
+        result = dict(last_page or {})
+        result.pop("next_token", None)
+        result.update(
+            {
+                "total": len(artifacts),
+                "skip": 0,
+                "limit": len(artifacts),
+                "artifacts": artifacts,
+            }
+        )
+        return result
 
     def get_job_artifacts(self, job_ids: list) -> list:
         """Get artifact download links for one or more jobs."""

{ap_client-0.2.0.dev0 → ap_client-0.2.1}/ap_client/cli.py

@@ -16,6 +16,7 @@ from ap_client import __version__, get_client, get_config, tbb
 from ap_client.api import (
     _OTHERS_MODEL,
     APIError,
+    PaginationProtocolError,
     _merge_meta_tags,
     set_cluster_override,
     set_verbose_override,
@@ -2633,6 +2634,21 @@ def job_list(
     desc: bool = typer.Option(False, "--desc", help="Sort descending; requires --sort"),
     skip: int = typer.Option(0, "--skip", help="Skip the first N entries"),
     limit: int = typer.Option(100, "--limit", help="Maximum number of entries to return"),
+    next_token: Optional[str] = typer.Option(
+        None,
+        "--next-token",
+        help="Opaque token returned by the previous exact-group job list page; requires --group-id",
+    ),
+    cursor: bool = typer.Option(
+        False,
+        "--cursor",
+        help="Opt this page into next-token pagination; requires --group-id",
+    ),
+    no_total: bool = typer.Option(
+        False,
+        "--no-total",
+        help="Skip the server-side count; total becomes null in json/yaml output",
+    ),
     columns: Optional[str] = typer.Option(
         None,
         "--columns",
@@ -2658,7 +2674,16 @@ def job_list(
         raise typer.BadParameter("--tag-pattern cannot be used with --tag")
     if normalized_tag_logic != "and" and not tag:
         raise typer.BadParameter("--tag-logic requires --tag")
+    if next_token and not group_id:
+        raise typer.BadParameter("--next-token requires --group-id")
+    if cursor and not group_id:
+        raise typer.BadParameter("--cursor requires --group-id")
+    if next_token and skip > 0:
+        raise typer.BadParameter("--next-token cannot be used with --skip greater than 0")
+    if cursor and skip > 0:
+        raise typer.BadParameter("--cursor cannot be used with --skip greater than 0")
     sort_kwargs = _job_list_sort_kwargs(sort, asc=asc, desc=desc)
+    cursor_request = bool(next_token) or cursor
     client = get_client()
     result = client.list_jobs(
         template=template,
@@ -2682,6 +2707,9 @@ def job_list(
         **({"meta_model": meta_model} if meta_model is not None else {}),
         **({"meta_job_type": meta_job_type} if meta_job_type is not None else {}),
         **sort_kwargs,
+        **({"next_token": next_token} if next_token else {}),
+        **({"pagination": "cursor"} if cursor_request else {}),
+        include_total=not no_total,
         skip=skip,
         limit=limit,
     )
@@ -2691,6 +2719,9 @@ def job_list(
         _print_job_list_plain(result, columns=selected_columns)
     else:
         _print_formatted(result, output_format)
+    next_token = result.get("next_token")
+    if output_format in {"table", "plain"} and next_token:
+        typer.echo(f"Next token: {next_token}", err=True)
 
 
 @job_app.command("create")
@@ -5743,6 +5774,21 @@ def group_jobs(
     ),
     skip: int = typer.Option(0, "--skip", help="Skip the first N entries"),
     limit: int = typer.Option(100, "--limit", help="Maximum number of entries to return"),
+    next_token: Optional[str] = typer.Option(
+        None,
+        "--next-token",
+        help="Opaque token returned by the previous Group jobs page",
+    ),
+    cursor: bool = typer.Option(
+        False,
+        "--cursor",
+        help="Opt this page into next-token pagination",
+    ),
+    no_total: bool = typer.Option(
+        False,
+        "--no-total",
+        help="Skip the server-side count; total becomes null in json/yaml output",
+    ),
     output_format: str = typer.Option(
         None,
         "--format",
@@ -5751,6 +5797,11 @@ def group_jobs(
 ):
     """List jobs in a Group."""
     output_format = _normalize_output_format(output_format, keep_table=True)
+    if next_token and skip > 0:
+        raise typer.BadParameter("--next-token cannot be used with --skip greater than 0")
+    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,
@@ -5758,6 +5809,9 @@ def group_jobs(
         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)
@@ -5765,6 +5819,9 @@ def group_jobs(
         _print_job_list_plain(result)
     else:
         _print_formatted(result, output_format)
+    following_token = result.get("next_token")
+    if output_format in {"table", "plain"} and following_token:
+        typer.echo(f"Next token: {following_token}", err=True)
 
 
 @group_app.command("stats")
@@ -6035,7 +6092,7 @@ def main() -> None:
     except APIError as exc:
         typer.echo(_format_api_error(exc), err=True)
         raise SystemExit(1) from None
-    except ConfigurationError as exc:
+    except (ConfigurationError, PaginationProtocolError) as exc:
         typer.echo(f"error: {exc}", err=True)
         raise SystemExit(1) from None
 

{ap_client-0.2.0.dev0 → ap_client-0.2.1}/pyproject.toml

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