ap-client 0.1.4.dev0__py3-none-any.whl

ap_client/__init__.py

@@ -0,0 +1,13 @@
+"""Agent Platform API Client"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .api import APIClient, get_client
+from .config import Config, get_config
+
+try:
+    __version__ = version("ap-client")
+except PackageNotFoundError:
+    __version__ = "0.1.4"
+
+__all__ = ["APIClient", "Config", "__version__", "get_client", "get_config"]

ap_client/api.py

@@ -0,0 +1,516 @@
+"""API client."""
+
+import json as _json
+import platform
+import sys
+import time
+import uuid
+from typing import Any, Optional
+from urllib.parse import quote
+
+import requests
+
+from .config import Config, get_config
+
+_GROUP_ARTIFACTS_PAGE_SIZE = 500
+_VERBOSE_SAMPLE_KEYS = 5
+_VERBOSE_SAMPLE_ITEMS = 3
+_VERBOSE_VALUE_PREVIEW = 120
+
+
+class APIClient:
+    """Agent Platform API client."""
+
+    def __init__(self, config: Config):
+        self.config = config
+        self.session = requests.Session()
+        headers = dict(config.headers)
+        user_agent = _build_user_agent(headers.get("User-Agent"))
+        headers["User-Agent"] = user_agent
+        self.session.headers.update(
+            {
+                "Content-Type": "application/json",
+                **headers,
+            }
+        )
+
+    def _url(self, path: str) -> str:
+        """Build the full URL."""
+        if (
+            path.startswith("/")
+            and "/api" not in self.config.base_url
+            and "nlb-" not in self.config.base_url
+            and "localhost" not in self.config.base_url
+        ):
+            return f"{self.config.base_url}/api{path}"
+        return f"{self.config.base_url}{path}"
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[dict] = None,
+        json_body: Any = None,
+        timeout: float = 30,
+    ) -> Any:
+        """Send an HTTP request with X-Request-ID and optional verbose logging."""
+        url = self._url(path)
+        request_id = str(uuid.uuid4())
+        headers = {"X-Request-ID": request_id}
+        verbose = self.config.verbose
+        if verbose:
+            self._log_request(method, url, request_id, params, json_body)
+        start = time.perf_counter()
+        try:
+            resp = self.session.request(
+                method,
+                url,
+                params=params,
+                json=json_body,
+                headers=headers,
+                timeout=timeout,
+            )
+        except Exception as exc:
+            if verbose:
+                duration_ms = (time.perf_counter() - start) * 1000
+                self._log_exception(method, url, request_id, duration_ms, exc)
+            raise
+        duration_ms = (time.perf_counter() - start) * 1000
+        if verbose:
+            self._log_response(method, url, request_id, resp, duration_ms)
+        if not resp.ok:
+            try:
+                err_data = resp.json()
+                detail = err_data.get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise Exception(
+                f"API Error {resp.status_code}: {detail} (request_id={request_id})"
+            )
+        if not resp.content:
+            return None
+        return resp.json()
+
+    def _get(self, path: str, params: Optional[dict] = None) -> Any:
+        """Send a GET request."""
+        return self._request("GET", path, params=params)
+
+    def _post(self, path: str, data: Any, timeout: float = 30) -> Any:
+        """Send a POST request."""
+        return self._request("POST", path, json_body=data, timeout=timeout)
+
+    def _delete(self, path: str) -> Any:
+        """Send a DELETE request."""
+        return self._request("DELETE", path)
+
+    # ==================== Verbose logging ====================
+
+    def _log_request(
+        self,
+        method: str,
+        url: str,
+        request_id: str,
+        params: Optional[dict],
+        body: Any,
+    ) -> None:
+        lines = [f">> {method} {url}", f"   request_id={request_id}"]
+        if params:
+            lines.append(f"   params={_safe_json(params)}")
+        if body is not None:
+            encoded = _safe_json(body).encode("utf-8", errors="replace")
+            lines.append(f"   body_size={len(encoded)}")
+            preview = self._summarize_body(body, encoded)
+            if preview:
+                lines.append(f"   body={preview}")
+        _write_stderr(lines)
+
+    def _log_response(
+        self,
+        method: str,
+        url: str,
+        request_id: str,
+        resp: requests.Response,
+        duration_ms: float,
+    ) -> None:
+        raw = resp.content or b""
+        lines = [
+            f"<< {method} {url}",
+            f"   request_id={request_id}",
+            f"   status={resp.status_code}",
+            f"   duration_ms={duration_ms:.1f}",
+            f"   body_size={len(raw)}",
+        ]
+        preview = self._summarize_response(resp, raw)
+        if preview:
+            lines.append(f"   body={preview}")
+        _write_stderr(lines)
+
+    def _log_exception(
+        self,
+        method: str,
+        url: str,
+        request_id: str,
+        duration_ms: float,
+        exc: Exception,
+    ) -> None:
+        _write_stderr(
+            [
+                f"!! {method} {url}",
+                f"   request_id={request_id}",
+                f"   duration_ms={duration_ms:.1f}",
+                f"   error={type(exc).__name__}: {exc}",
+            ]
+        )
+
+    def _summarize_body(self, body: Any, encoded: bytes) -> str:
+        if self.config.verbose_full_body:
+            return encoded.decode("utf-8", errors="replace")
+        limit = self.config.verbose_body_limit
+        if len(encoded) <= limit:
+            return encoded.decode("utf-8", errors="replace")
+        return _summarize_json_value(body, limit)
+
+    def _summarize_response(self, resp: requests.Response, raw: bytes) -> str:
+        if not raw:
+            return ""
+        if self.config.verbose_full_body:
+            return _safe_decode(raw)
+        limit = self.config.verbose_body_limit
+        content_type = (resp.headers.get("Content-Type") or "").lower()
+        if "json" in content_type:
+            try:
+                data = resp.json()
+            except Exception:
+                return _truncate_text(_safe_decode(raw), limit)
+            encoded = _safe_json(data)
+            if len(encoded.encode("utf-8", errors="replace")) <= limit:
+                return encoded
+            return _summarize_json_value(data, limit)
+        return _truncate_text(_safe_decode(raw), limit)
+
+    # ==================== Template operations ====================
+
+    def list_templates(self) -> list:
+        """List all templates."""
+        params = {}
+        if self.config.agenthub_ref:
+            params["agenthub_revision"] = self.config.agenthub_ref
+        return self._get("/templates", params=params)
+
+    def get_template(self, name: str) -> dict:
+        """Get template details."""
+        params = {}
+        if self.config.agenthub_ref:
+            params["agenthub_revision"] = self.config.agenthub_ref
+        return self._get(f"/templates/{quote(name)}", params=params)
+
+    # ==================== Dataset operations ====================
+
+    def list_datasets(self, search: Optional[str] = None) -> dict:
+        """List all datasets."""
+        params = {"limit": 500}
+        if search:
+            params["search"] = search
+        return self._get("/datasets", params=params)
+
+    def list_dataset_versions(self, dataset: str) -> list:
+        """List dataset versions."""
+        return self._get(f"/datasets/{quote(dataset)}/versions")
+
+    def list_dataset_instances(self, dataset_version: str, limit: int = 10000) -> dict:
+        """List dataset instances."""
+        return self._get(f"/datasets/{quote(dataset_version)}/instances", params={"limit": limit})
+
+    # ==================== Job operations ====================
+
+    def create_group(
+        self,
+        name: Optional[str] = None,
+        max_concurrency: Optional[int] = None,
+        eval_config: Optional[dict] = None,
+    ) -> dict:
+        """Create a group."""
+        body: dict = {}
+        if name:
+            body["name"] = name
+        if max_concurrency is not None:
+            body["max_concurrency"] = max_concurrency
+        if eval_config is not None:
+            body["eval_config"] = eval_config
+        return self._post("/groups", body)
+
+    def create_job(
+        self,
+        template: str,
+        params: Optional[dict] = None,
+        params_list: Optional[list] = None,
+        suite_name: Optional[str] = None,
+        tags: Optional[list] = None,
+        overrides: Optional[dict] = None,
+        max_concurrency: Optional[int] = None,
+        group_id: Optional[str] = None,
+        enable_otel_tracing: Optional[bool] = None,
+        timeout: float = 30,
+    ) -> dict:
+        """Create a job."""
+        body: dict = {"template": template}
+
+        if params is not None:
+            body["params"] = params
+        if params_list is not None:
+            body["params_list"] = params_list
+        if suite_name:
+            body["suite_name"] = suite_name
+        if self.config.agenthub_ref:
+            body["agenthub_revision"] = self.config.agenthub_ref
+        if tags:
+            body["tags"] = tags
+        if overrides:
+            body["overrides"] = overrides
+        if max_concurrency is not None:
+            body["max_concurrency"] = max_concurrency
+        if group_id is not None:
+            body["group_id"] = group_id
+        if enable_otel_tracing is not None:
+            body["enable_otel_tracing"] = enable_otel_tracing
+
+        return self._post("/jobs", body, timeout=timeout)
+
+    def get_job(self, job_id: str) -> dict:
+        """Get job status."""
+        return self._get(f"/jobs/{quote(job_id)}")
+
+    def list_jobs(
+        self,
+        template: Optional[str] = None,
+        group_id: Optional[str] = None,
+        status: Optional[str] = None,
+        job_id: Optional[str] = None,
+        instance_id: Optional[str] = None,
+        finished_after: Optional[str] = None,
+        finished_before: Optional[str] = None,
+        created_after: Optional[str] = None,
+        created_before: Optional[str] = None,
+        skip: int = 0,
+        limit: int = 100,
+    ) -> dict:
+        """List jobs."""
+        params = {"skip": skip, "limit": limit}
+        if template:
+            params["template"] = template
+        if group_id:
+            params["group_id"] = group_id
+        if status:
+            params["status"] = status
+        if job_id:
+            params["job_id"] = job_id
+        if instance_id:
+            params["instance_id"] = instance_id
+        if finished_after:
+            params["finished_after"] = finished_after
+        if finished_before:
+            params["finished_before"] = finished_before
+        if created_after:
+            params["created_after"] = created_after
+        if created_before:
+            params["created_before"] = created_before
+        return self._get("/jobs", params=params)
+
+    # ==================== Group operations ====================
+
+    def get_group(self, group_id: str) -> dict:
+        """Get group details."""
+        return self._get(f"/groups/{quote(group_id)}")
+
+    def list_groups(self, skip: int = 0, limit: int = 100) -> dict:
+        """List groups."""
+        return self._get("/groups", params={"skip": skip, "limit": limit})
+
+    def list_group_jobs(
+        self,
+        group_id: str,
+        tag: Optional[list[str]] = None,
+        skip: int = 0,
+        limit: int = 100,
+    ) -> dict:
+        """List jobs in a group."""
+        params: dict = {"skip": skip, "limit": limit}
+        if tag:
+            params["tag"] = tag
+        return self._get(f"/groups/{quote(group_id)}/jobs", params=params)
+
+    def get_group_stats(self, group_id: str) -> dict:
+        """Get group progress."""
+        return self._get(f"/groups/{quote(group_id)}/stats")
+
+    def get_group_eval(self, group_id: str) -> dict:
+        """Get aggregated evaluation results for a group."""
+        return self._get(f"/groups/{quote(group_id)}/eval")
+
+    # ==================== Logs and artifacts ====================
+    def cancel_group(self, group_id: str) -> dict:
+        """Cancel all unfinished jobs in a group."""
+        return self._post(f"/groups/{quote(group_id)}/cancel", {})
+
+    def get_job_logs(
+        self, job_id: str, container: Optional[str] = None, tail: Optional[int] = None
+    ) -> dict:
+        """Get job logs."""
+        params = {}
+        if container:
+            params["container"] = container
+        if tail:
+            params["tail"] = tail
+        return self._get(f"/jobs/{quote(job_id)}/logs", params=params or None)
+
+    def get_job_events(self, job_id: str, container: Optional[str] = None) -> dict:
+        """Get job events."""
+        params = {}
+        if container:
+            params["container"] = container
+        return self._get(f"/jobs/{quote(job_id)}/events", params=params or None)
+
+    def get_job_metrics(self, job_id: str) -> dict:
+        """Get job metrics."""
+        return self._get(f"/metrics/{quote(job_id)}")
+
+    def cancel_job(self, job_id: str) -> dict:
+        """Cancel a job."""
+        return self._delete(f"/jobs/{quote(job_id)}")
+
+    def get_group_artifacts_page(
+        self,
+        group_id: str,
+        *,
+        skip: int = 0,
+        limit: int = _GROUP_ARTIFACTS_PAGE_SIZE,
+    ) -> dict:
+        """Get one page of artifact download links for a group."""
+        return self._get(
+            f"/groups/{quote(group_id)}/artifacts",
+            params={"skip": skip, "limit": limit},
+        )
+
+    def get_group_artifacts(self, group_id: str) -> dict:
+        """Get artifact download links for a group."""
+        skip = 0
+        artifacts: list[dict] = []
+        last_page: dict | None = None
+
+        while True:
+            page = self.get_group_artifacts_page(
+                group_id,
+                skip=skip,
+                limit=_GROUP_ARTIFACTS_PAGE_SIZE,
+            )
+            last_page = page
+            page_artifacts = page.get("artifacts") or []
+            artifacts.extend(page_artifacts)
+
+            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)
+
+        return {
+            **last_page,
+            "skip": 0,
+            "limit": len(artifacts),
+            "artifacts": artifacts,
+        }
+
+    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 render_template(self, name: str, params: dict) -> dict:
+        """Preview the rendered template output."""
+        return self._post(f"/templates/{quote(name)}/render", {"params": params})
+
+
+_verbose_override: Optional[bool] = None
+
+
+def set_verbose_override(value: Optional[bool]) -> None:
+    """Set a process-wide verbose override consulted by get_client()."""
+    global _verbose_override
+    _verbose_override = value
+
+
+def get_client() -> APIClient:
+    """Get an API client."""
+    return APIClient(get_config(verbose=_verbose_override))
+
+
+def _build_user_agent(existing: Optional[str] = None) -> str:
+    """Build client User-Agent string."""
+    client_ua = (
+        f"ap-client/{_client_version()} "
+        f"python/{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro} "
+        f"{platform.system().lower()}/{platform.machine().lower()}"
+    )
+    if existing:
+        return f"{existing} {client_ua}"
+    return client_ua
+
+
+def _client_version() -> str:
+    from . import __version__
+
+    return __version__
+
+
+def _write_stderr(lines: list[str]) -> None:
+    sys.stderr.write("\n".join(lines) + "\n")
+    sys.stderr.flush()
+
+
+def _safe_json(value: Any) -> str:
+    try:
+        return _json.dumps(value, ensure_ascii=False, default=str)
+    except Exception:
+        return str(value)
+
+
+def _safe_decode(raw: bytes) -> str:
+    try:
+        return raw.decode("utf-8", errors="replace")
+    except Exception:
+        return f"<{len(raw)} bytes binary>"
+
+
+def _truncate_text(text: str, limit: int) -> str:
+    if len(text) <= limit:
+        return text
+    return text[:limit] + f"...<truncated {len(text) - limit} chars>"
+
+
+def _shorten_value(value: Any) -> Any:
+    if isinstance(value, str):
+        if len(value) > _VERBOSE_VALUE_PREVIEW:
+            return value[:_VERBOSE_VALUE_PREVIEW] + "..."
+        return value
+    if isinstance(value, dict):
+        return f"<dict {len(value)} keys>"
+    if isinstance(value, list):
+        return f"<list {len(value)} items>"
+    return value
+
+
+def _summarize_json_value(data: Any, limit: int) -> str:
+    if isinstance(data, dict):
+        keys = list(data.keys())
+        sample = {k: _shorten_value(data[k]) for k in keys[:_VERBOSE_SAMPLE_KEYS]}
+        summary = {"_keys": keys, "_sample": sample}
+        if len(keys) > _VERBOSE_SAMPLE_KEYS:
+            summary["_truncated_keys"] = len(keys) - _VERBOSE_SAMPLE_KEYS
+        return _truncate_text(_safe_json(summary), limit)
+    if isinstance(data, list):
+        sample = [_shorten_value(item) for item in data[:_VERBOSE_SAMPLE_ITEMS]]
+        summary = {"_count": len(data), "_sample": sample}
+        return _truncate_text(_safe_json(summary), limit)
+    return _truncate_text(_safe_json(data), limit)