cloudsway-agent 1.0.0__py3-none-any.whl

agent_api/__init__.py

@@ -0,0 +1,68 @@
+"""Production Python SDK for the Managed Agent API."""
+
+from agent_api._version import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_STREAM_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    USER_AGENT,
+    __version__,
+)
+from agent_api.async_client import AsyncAgentAPI
+from agent_api.client import AgentAPI
+from agent_api.errors import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    is_retryable_status,
+    parse_response_error,
+)
+from agent_api.local_functions import (
+    function_call_output_input,
+    pending_function_calls,
+    run_local_function_handlers,
+)
+from agent_api.pagination import AsyncPage, Page, PageResult
+from agent_api.types import *
+
+__all__ = [
+    "AgentAPI",
+    "AsyncAgentAPI",
+    "APIError",
+    "APIConnectionError",
+    "APIStatusError",
+    "AuthenticationError",
+    "BadRequestError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "Page",
+    "AsyncPage",
+    "PageResult",
+    "AgentCapabilityPreference",
+    "AgentResponse",
+    "Model",
+    "ModelCapabilities",
+    "Preset",
+    "PublicTool",
+    "ResponseCreateParams",
+    "ResponseStreamEvent",
+    "ResponseStatus",
+    "ToolInvocationResult",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_STREAM_TIMEOUT",
+    "DEFAULT_TIMEOUT",
+    "USER_AGENT",
+    "is_retryable_status",
+    "parse_response_error",
+    "function_call_output_input",
+    "pending_function_calls",
+    "run_local_function_handlers",
+    "__version__",
+]

agent_api/_http.py

@@ -0,0 +1,392 @@
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import Any
+
+import httpx
+
+from agent_api._utils import build_query
+from agent_api._version import DEFAULT_MAX_RETRIES, DEFAULT_STREAM_TIMEOUT, DEFAULT_TIMEOUT, USER_AGENT
+from agent_api.errors import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    RateLimitError,
+    is_retryable_status,
+    parse_response_error,
+)
+from agent_api.streaming import aiter_sse, iter_sse
+
+
+class SyncHTTPClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None,
+        timeout: float,
+        stream_timeout: float,
+        max_retries: int,
+        default_headers: Mapping[str, str],
+        http_client: httpx.Client,
+    ) -> None:
+        self.base_url = base_url
+        self.api_key = api_key
+        self.timeout = timeout
+        self.stream_timeout = stream_timeout
+        self.max_retries = max_retries
+        self.default_headers = dict(default_headers)
+        self._client = http_client
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        response = self._request_response(
+            method,
+            path,
+            body,
+            stream=False,
+            timeout=timeout,
+            max_retries=max_retries,
+            extra_headers=extra_headers,
+        )
+        return response.json()
+
+    def stream(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any],
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> Iterator[Any]:
+        effective_timeout = timeout if timeout is not None else self.stream_timeout
+        headers = self._headers(stream=True, extra=extra_headers)
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                with self._client.stream(
+                    method,
+                    self.base_url + path,
+                    json=body,
+                    headers=headers,
+                    timeout=effective_timeout,
+                ) as response:
+                    if not response.is_success:
+                        try:
+                            payload: Any = response.json()
+                        except ValueError:
+                            payload = response.text
+                        raise parse_response_error(response, payload)
+                    yield from iter_sse(response.iter_lines())
+                return
+            except APIError as exc:
+                if attempt >= retries:
+                    raise
+                retryable = isinstance(exc, APIConnectionError) or (
+                    isinstance(exc, APIStatusError) and exc.status_code is not None and is_retryable_status(exc.status_code)
+                )
+                if not retryable:
+                    raise
+                attempt += 1
+                time.sleep(_retry_delay_seconds(exc, attempt))
+            except httpx.TimeoutException as exc:
+                raise APIConnectionError(f"Request timed out after {effective_timeout}s") from exc
+            except httpx.HTTPError as exc:
+                raise APIConnectionError(str(exc)) from exc
+
+    def _request_response(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+        *,
+        stream: bool,
+        timeout: float | None,
+        max_retries: int | None,
+        extra_headers: Mapping[str, str] | None,
+    ) -> httpx.Response:
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                return self._request_once(
+                    method,
+                    path,
+                    body,
+                    stream=stream,
+                    timeout=timeout,
+                    extra_headers=extra_headers,
+                )
+            except APIError as exc:
+                if attempt >= retries:
+                    raise
+                retryable = isinstance(exc, APIConnectionError) or (
+                    isinstance(exc, APIStatusError) and exc.status_code is not None and is_retryable_status(exc.status_code)
+                )
+                if not retryable:
+                    raise
+                attempt += 1
+                time.sleep(_retry_delay_seconds(exc, attempt))
+
+    def _request_once(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+        *,
+        stream: bool,
+        timeout: float | None,
+        extra_headers: Mapping[str, str] | None,
+    ) -> httpx.Response:
+        effective_timeout = timeout if timeout is not None else (self.stream_timeout if stream else self.timeout)
+        headers = self._headers(stream=stream, extra=extra_headers)
+        try:
+            if stream:
+                request = self._client.build_request(
+                    method,
+                    self.base_url + path,
+                    json=body,
+                    headers=headers,
+                    timeout=effective_timeout,
+                )
+                response = self._client.send(request, stream=True)
+            else:
+                response = self._client.request(
+                    method,
+                    self.base_url + path,
+                    json=body,
+                    headers=headers,
+                    timeout=effective_timeout,
+                )
+        except httpx.TimeoutException as exc:
+            raise APIConnectionError(f"Request timed out after {effective_timeout}s") from exc
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(str(exc)) from exc
+
+        if response.is_success:
+            return response
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            payload = response.text
+        raise parse_response_error(response, payload)
+
+    def _headers(self, *, stream: bool, extra: Mapping[str, str] | None) -> dict[str, str]:
+        headers = {
+            "Accept": "text/event-stream" if stream else "application/json",
+            "User-Agent": USER_AGENT,
+            **self.default_headers,
+            **dict(extra or {}),
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+
+class AsyncHTTPClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str | None,
+        timeout: float,
+        stream_timeout: float,
+        max_retries: int,
+        default_headers: Mapping[str, str],
+        http_client: httpx.AsyncClient,
+    ) -> None:
+        self.base_url = base_url
+        self.api_key = api_key
+        self.timeout = timeout
+        self.stream_timeout = stream_timeout
+        self.max_retries = max_retries
+        self.default_headers = dict(default_headers)
+        self._client = http_client
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> Any:
+        response = await self._request_response(
+            method,
+            path,
+            body,
+            stream=False,
+            timeout=timeout,
+            max_retries=max_retries,
+            extra_headers=extra_headers,
+        )
+        return response.json()
+
+    async def stream(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any],
+        *,
+        timeout: float | None = None,
+        max_retries: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> AsyncIterator[Any]:
+        effective_timeout = timeout if timeout is not None else self.stream_timeout
+        headers = self._headers(stream=True, extra=extra_headers)
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                async with self._client.stream(
+                    method,
+                    self.base_url + path,
+                    json=body,
+                    headers=headers,
+                    timeout=effective_timeout,
+                ) as response:
+                    if not response.is_success:
+                        try:
+                            payload: Any = response.json()
+                        except ValueError:
+                            payload = response.text
+                        raise parse_response_error(response, payload)
+                    async for event in aiter_sse(response.aiter_lines()):
+                        yield event
+                return
+            except APIError as exc:
+                if attempt >= retries:
+                    raise
+                retryable = isinstance(exc, APIConnectionError) or (
+                    isinstance(exc, APIStatusError) and exc.status_code is not None and is_retryable_status(exc.status_code)
+                )
+                if not retryable:
+                    raise
+                attempt += 1
+                await _async_sleep(_retry_delay_seconds(exc, attempt))
+            except httpx.TimeoutException as exc:
+                raise APIConnectionError(f"Request timed out after {effective_timeout}s") from exc
+            except httpx.HTTPError as exc:
+                raise APIConnectionError(str(exc)) from exc
+
+    async def _request_response(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+        *,
+        stream: bool,
+        timeout: float | None,
+        max_retries: int | None,
+        extra_headers: Mapping[str, str] | None,
+    ) -> httpx.Response:
+        retries = self.max_retries if max_retries is None else max_retries
+        attempt = 0
+        while True:
+            try:
+                return await self._request_once(
+                    method,
+                    path,
+                    body,
+                    stream=stream,
+                    timeout=timeout,
+                    extra_headers=extra_headers,
+                )
+            except APIError as exc:
+                if attempt >= retries:
+                    raise
+                retryable = isinstance(exc, APIConnectionError) or (
+                    isinstance(exc, APIStatusError) and exc.status_code is not None and is_retryable_status(exc.status_code)
+                )
+                if not retryable:
+                    raise
+                attempt += 1
+                await _async_sleep(_retry_delay_seconds(exc, attempt))
+
+    async def _request_once(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None,
+        *,
+        stream: bool,
+        timeout: float | None,
+        extra_headers: Mapping[str, str] | None,
+    ) -> httpx.Response:
+        effective_timeout = timeout if timeout is not None else (self.stream_timeout if stream else self.timeout)
+        headers = self._headers(stream=stream, extra=extra_headers)
+        try:
+            if stream:
+                request = self._client.build_request(
+                    method,
+                    self.base_url + path,
+                    json=body,
+                    headers=headers,
+                    timeout=effective_timeout,
+                )
+                response = await self._client.send(request, stream=True)
+            else:
+                response = await self._client.request(
+                    method,
+                    self.base_url + path,
+                    json=body,
+                    headers=headers,
+                    timeout=effective_timeout,
+                )
+        except httpx.TimeoutException as exc:
+            raise APIConnectionError(f"Request timed out after {effective_timeout}s") from exc
+        except httpx.HTTPError as exc:
+            raise APIConnectionError(str(exc)) from exc
+
+        if response.is_success:
+            return response
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            payload = response.text
+        raise parse_response_error(response, payload)
+
+    def _headers(self, *, stream: bool, extra: Mapping[str, str] | None) -> dict[str, str]:
+        headers = {
+            "Accept": "text/event-stream" if stream else "application/json",
+            "User-Agent": USER_AGENT,
+            **self.default_headers,
+            **dict(extra or {}),
+        }
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+
+def _retry_delay_seconds(error: APIError, attempt: int) -> float:
+    if isinstance(error, RateLimitError) and error.retry_after_seconds is not None:
+        return error.retry_after_seconds
+    base = 0.25
+    cap = 8.0
+    exponential = min(cap, base * (2 ** (attempt - 1)))
+    jitter = random.uniform(0, 0.1)
+    return exponential + jitter
+
+
+async def _async_sleep(seconds: float) -> None:
+    import asyncio
+
+    await asyncio.sleep(seconds)
+
+
+__all__ = ["SyncHTTPClient", "AsyncHTTPClient"]

agent_api/_utils.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agent_api.types import AgentResponse
+
+
+def drop_none(values: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in values.items() if value is not None}
+
+
+def add_output_text(response: AgentResponse) -> AgentResponse:
+    if "output_text" in response:
+        return response
+    text = ""
+    for item in response.get("output", []):
+        if item.get("type") != "message":
+            continue
+        for part in item.get("content", []):
+            if part.get("type") == "output_text":
+                text += part.get("text", "")
+    response["output_text"] = text
+    return response
+
+
+def build_query(params: dict[str, Any]) -> str:
+    filtered = {key: value for key, value in params.items() if value is not None and value != ""}
+    if not filtered:
+        return ""
+    from urllib.parse import urlencode
+
+    return "?" + urlencode(filtered)

agent_api/_version.py

@@ -0,0 +1,8 @@
+"""Agent API Python SDK version."""
+
+__version__ = "1.0.0"
+USER_AGENT = f"cloudsway-agent/{__version__}"
+
+DEFAULT_TIMEOUT = 600.0
+DEFAULT_STREAM_TIMEOUT = 3600.0
+DEFAULT_MAX_RETRIES = 2

agent_api/async_client.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+import httpx
+
+from agent_api._http import AsyncHTTPClient
+from agent_api._version import DEFAULT_MAX_RETRIES, DEFAULT_STREAM_TIMEOUT, DEFAULT_TIMEOUT
+from agent_api.resources.catalog import AsyncModelsAPI, AsyncPresetsAPI, AsyncToolsAPI
+from agent_api.resources.responses import AsyncResponsesAPI
+
+
+class AsyncAgentAPI:
+    """Asynchronous production client for the Managed Agent API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        stream_timeout: float | None = None,
+        max_retries: int | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("AGENT_API_KEY")
+        self.base_url = (base_url or os.environ.get("AGENT_API_BASE_URL") or "https://api.agentsway.dev").rstrip("/")
+        self.timeout = float(timeout) if isinstance(timeout, (int, float)) else DEFAULT_TIMEOUT
+        self.stream_timeout = stream_timeout if stream_timeout is not None else DEFAULT_STREAM_TIMEOUT
+        self.max_retries = max_retries if max_retries is not None else DEFAULT_MAX_RETRIES
+        self.default_headers = dict(default_headers or {})
+        self._client = http_client or httpx.AsyncClient(timeout=timeout or DEFAULT_TIMEOUT)
+        self._http = AsyncHTTPClient(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+            stream_timeout=self.stream_timeout,
+            max_retries=self.max_retries,
+            default_headers=self.default_headers,
+            http_client=self._client,
+        )
+        self.responses = AsyncResponsesAPI(self._http, "/v1/responses")
+        self.agent = AsyncResponsesAPI(self._http, "/v1/agent")
+        self.models = AsyncModelsAPI(self._http)
+        self.presets = AsyncPresetsAPI(self._http)
+        self.tools = AsyncToolsAPI(self._http)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAgentAPI:
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.close()

agent_api/client.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+import httpx
+
+from agent_api._http import SyncHTTPClient
+from agent_api._version import DEFAULT_MAX_RETRIES, DEFAULT_STREAM_TIMEOUT, DEFAULT_TIMEOUT
+from agent_api.resources.catalog import ModelsAPI, PresetsAPI, ToolsAPI
+from agent_api.resources.responses import ResponsesAPI
+
+
+class AgentAPI:
+    """Synchronous production client for the Managed Agent API."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = None,
+        stream_timeout: float | None = None,
+        max_retries: int | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("AGENT_API_KEY")
+        self.base_url = (base_url or os.environ.get("AGENT_API_BASE_URL") or "https://api.agentsway.dev").rstrip("/")
+        self.timeout = float(timeout) if isinstance(timeout, (int, float)) else DEFAULT_TIMEOUT
+        self.stream_timeout = stream_timeout if stream_timeout is not None else DEFAULT_STREAM_TIMEOUT
+        self.max_retries = max_retries if max_retries is not None else DEFAULT_MAX_RETRIES
+        self.default_headers = dict(default_headers or {})
+        self._client = http_client or httpx.Client(timeout=timeout or DEFAULT_TIMEOUT)
+        self._http = SyncHTTPClient(
+            base_url=self.base_url,
+            api_key=self.api_key,
+            timeout=self.timeout,
+            stream_timeout=self.stream_timeout,
+            max_retries=self.max_retries,
+            default_headers=self.default_headers,
+            http_client=self._client,
+        )
+        self.responses = ResponsesAPI(self._http, "/v1/responses")
+        self.agent = ResponsesAPI(self._http, "/v1/agent")
+        self.models = ModelsAPI(self._http)
+        self.presets = PresetsAPI(self._http)
+        self.tools = ToolsAPI(self._http)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> AgentAPI:
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+