deploypod 0.1.0__py3-none-any.whl

deploypod/__init__.py

@@ -0,0 +1,31 @@
+__version__ = "0.1.0"
+
+from deploypod.auth import AppCredentials
+from deploypod.client import DeployPodClient, DeploypodClient
+from deploypod.env import get_client_from_env
+from deploypod.exceptions import (
+    DeploypodError,
+    DeployPodError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    ConflictError,
+    LicenseError,
+    ServerError,
+)
+
+__all__ = [
+    "__version__",
+    "AppCredentials",
+    "DeploypodClient",
+    "DeployPodClient",
+    "get_client_from_env",
+    "DeploypodError",
+    "DeployPodError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "LicenseError",
+    "ServerError",
+]

deploypod/_http.py

@@ -0,0 +1,73 @@
+"""Shared HTTP utilities — imported by both client.py and resource modules."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from deploypod.exceptions import (
+    AuthenticationError,
+    ConflictError,
+    DeploypodError,
+    LicenseError,
+    NotFoundError,
+    ServerError,
+    ValidationError,
+)
+
+
+_STATUS_MAP: dict[int, type[DeploypodError]] = {
+    401: AuthenticationError,
+    403: AuthenticationError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: ValidationError,
+}
+
+
+def raise_for_status(resp: httpx.Response) -> None:
+    """Raise a typed DeploypodError for non-2xx responses."""
+    if resp.is_success:
+        return
+
+    try:
+        body = resp.json()
+    except Exception:
+        body = {"detail": resp.text}
+
+    detail = body.get("detail") or body.get("message") or resp.text
+
+    # License-specific 403
+    if resp.status_code == 403 and "license" in str(detail).lower():
+        raise LicenseError(resp.status_code, detail, body)
+
+    exc_cls = _STATUS_MAP.get(resp.status_code)
+    if exc_cls:
+        raise exc_cls(resp.status_code, detail, body)
+
+    if resp.status_code >= 500:
+        raise ServerError(resp.status_code, detail, body)
+
+    raise DeploypodError(resp.status_code, detail, body)
+
+
+def json_body(resp: httpx.Response) -> Any:
+    """The response's JSON, or {} when it carries none.
+
+    Several endpoints answer a successful delete or assign with 204 and no
+    body; parsing that as JSON raised JSONDecodeError after the server had
+    already done the work.
+    """
+    if resp.status_code == 204 or not resp.content:
+        return {}
+    return resp.json()
+
+
+def message_result(resp: httpx.Response) -> "MessageResult":
+    """A {message: ...} response as MessageResult; empty for a 204."""
+    from deploypod.types import MessageResult
+
+    body = json_body(resp)
+    message = body.get("message", "") if isinstance(body, dict) else ""
+    return MessageResult(message=message)

deploypod/auth.py

@@ -0,0 +1,90 @@
+"""Signing in with an application's own credentials (machine to machine).
+
+An administrator gives an application an ``app_id`` and an ``app_secret``.
+The application trades them for an access token at Deploypod's identity
+provider; the token lasts an hour. ``AppCredentials`` does the trade, keeps
+the token, and fetches a new one shortly before it expires or when the API
+answers 401.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Generator, Optional
+
+import httpx
+
+from deploypod.exceptions import AuthenticationError
+
+TOKEN_URL = "https://auth.deploypod.ai/oidc/token"
+API_RESOURCE = "https://api.deploypod.io"
+
+# A token is replaced this many seconds before it expires, so a request
+# never leaves with one that runs out on the way.
+_EARLY_REFRESH_S = 60
+
+
+class AppCredentials(httpx.Auth):
+    """httpx auth that sends a bearer token obtained with client credentials."""
+
+    # The request may be sent twice (see auth_flow), so httpx must keep its
+    # body, file uploads included, instead of streaming it once.
+    requires_request_body = True
+
+    def __init__(
+        self,
+        app_id: str,
+        app_secret: str,
+        *,
+        token_url: str = TOKEN_URL,
+        resource: str = API_RESOURCE,
+        transport: Optional[httpx.BaseTransport] = None,
+        headers: Optional[dict[str, str]] = None,
+    ):
+        self._app_id = app_id
+        self._app_secret = app_secret
+        self._token_url = token_url
+        self._resource = resource
+        self._transport = transport
+        self._headers = headers or {}
+        self._token: Optional[str] = None
+        self._expires_at = 0.0
+        self._lock = threading.Lock()
+
+    def _fetch(self) -> None:
+        with httpx.Client(transport=self._transport, headers=self._headers, timeout=30.0) as c:
+            resp = c.post(
+                self._token_url,
+                auth=(self._app_id, self._app_secret),
+                data={
+                    "grant_type": "client_credentials",
+                    "resource": self._resource,
+                    "scope": "all",
+                },
+            )
+        if not resp.is_success:
+            raise AuthenticationError(
+                resp.status_code,
+                f"could not get an access token with app_id {self._app_id!r}: {resp.text}",
+                None,
+            )
+        body = resp.json()
+        self._token = body["access_token"]
+        self._expires_at = time.monotonic() + float(body.get("expires_in", 3600))
+
+    def token(self, *, renew: bool = False) -> str:
+        """The current access token, fetched or renewed when needed."""
+        with self._lock:
+            if renew or self._token is None or time.monotonic() >= self._expires_at - _EARLY_REFRESH_S:
+                self._fetch()
+            assert self._token is not None
+            return self._token
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self.token()}"
+        response = yield request
+        if response.status_code == 401:
+            # Revoked or rotated early: one fresh token, one retry.
+            request.headers["Authorization"] = f"Bearer {self.token(renew=True)}"
+            yield request

deploypod/client.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from deploypod import __version__
+from deploypod.auth import AppCredentials
+from deploypod.resources.agents import AgentsResource
+from deploypod.resources.knowledge_bases import KnowledgeBasesResource
+from deploypod.resources.knowledge_sources import KnowledgeSourcesResource
+from deploypod.resources.skills import SkillsResource
+from deploypod.resources.custom_tools import CustomToolsResource
+from deploypod.resources.mcp_servers import MCPServersResource
+from deploypod.resources.providers import ProvidersResource
+from deploypod.resources.connections import ConnectionsResource
+from deploypod.resources.conversations import ConversationsResource
+from deploypod.resources.users import UsersResource
+from deploypod.resources.groups import GroupsResource
+from deploypod.resources.organization import OrganizationResource
+from deploypod.resources.async_tasks import AsyncTasksResource
+from deploypod.resources.jobs import JobsResource
+
+
+DEFAULT_BASE_URL = "https://deploypod.ai/api"
+
+
+class DeploypodClient:
+    """Synchronous Python client for the Deploypod API.
+
+    Sign in with your application's credentials (an administrator creates
+    them; the client gets and renews the access token itself)::
+
+        from deploypod import DeploypodClient
+
+        client = DeploypodClient(org_id="42", app_id="...", app_secret="...")
+        for agent in client.agents.list():
+            print(agent.uuid, agent.name)
+
+    or with an access token you already have::
+
+        client = DeploypodClient(org_id="42", token="<access token>")
+
+    ``base_url`` defaults to Deploypod's cloud; pass your own for an
+    on-premises installation.
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        org_id: str | None = None,
+        token: str | None = None,
+        *,
+        app_id: str | None = None,
+        app_secret: str | None = None,
+        token_url: str | None = None,
+        timeout: float = 30.0,
+        extra_headers: dict[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        if org_id is None or str(org_id) == "":
+            raise ValueError("org_id is required: your organization's number in Deploypod")
+        if token and (app_id or app_secret):
+            raise ValueError("pass either token, or app_id and app_secret, not both")
+        if not token and not (app_id and app_secret):
+            raise ValueError("pass token, or app_id and app_secret")
+
+        # Cloudflare in front of deploypod.ai refuses requests that carry
+        # no User-Agent; name the SDK so they always have one.
+        headers: dict[str, str] = {
+            "org_id": str(org_id),
+            "User-Agent": f"deploypod-python/{__version__}",
+        }
+        auth: httpx.Auth | None = None
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        else:
+            kw = {"token_url": token_url} if token_url else {}
+            auth = AppCredentials(
+                app_id, app_secret, transport=transport,
+                headers={"User-Agent": headers["User-Agent"]}, **kw,
+            )
+        if extra_headers:
+            headers.update(extra_headers)
+
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers=headers,
+            auth=auth,
+            timeout=timeout,
+            transport=transport,
+        )
+
+        # Resource namespaces
+        self.agents = AgentsResource(self._http)
+        self.knowledge_bases = KnowledgeBasesResource(self._http)
+        self.knowledge_sources = KnowledgeSourcesResource(self._http)
+        self.skills = SkillsResource(self._http)
+        self.custom_tools = CustomToolsResource(self._http)
+        self.mcp_servers = MCPServersResource(self._http)
+        self.providers = ProvidersResource(self._http)
+        self.connections = ConnectionsResource(self._http)
+        self.conversations = ConversationsResource(self._http)
+        self.users = UsersResource(self._http)
+        self.groups = GroupsResource(self._http)
+        self.organization = OrganizationResource(self._http)
+        self.async_tasks = AsyncTasksResource(self._http)
+        self.jobs = JobsResource(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> DeploypodClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+# The name before the package went public. Kept so existing code runs
+# unchanged; new code uses DeploypodClient.
+DeployPodClient = DeploypodClient

deploypod/env.py

@@ -0,0 +1,49 @@
+"""A client built from environment variables, for scripts."""
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from deploypod.client import DEFAULT_BASE_URL, DeploypodClient
+
+
+def get_client_from_env(
+    deploypod_repo: Optional[Path] = None,
+) -> DeploypodClient:
+    """Build a DeploypodClient from environment variables.
+
+      DEPLOYPOD_ORG_ID     — your organization's number. Required.
+      DEPLOYPOD_APP_ID,
+      DEPLOYPOD_APP_SECRET — your application's credentials; the client gets
+                             and renews the access token itself.
+      DEPLOYPOD_TOKEN      — or an access token you already have. If neither
+                             is set and ``deploypod_repo`` is given, the token
+                             comes from ``<deploypod_repo>/scripts/get_token.sh``
+                             (Deploypod's own development scripts).
+      DEPLOYPOD_BASE_URL   — API address, default https://deploypod.ai/api.
+
+    Raises RuntimeError if the organization or the credentials are missing.
+    """
+    org_id = os.environ.get("DEPLOYPOD_ORG_ID")
+    if not org_id:
+        raise RuntimeError("DEPLOYPOD_ORG_ID is not set: export your organization's number.")
+    base_url = os.environ.get("DEPLOYPOD_BASE_URL", DEFAULT_BASE_URL)
+
+    app_id = os.environ.get("DEPLOYPOD_APP_ID")
+    app_secret = os.environ.get("DEPLOYPOD_APP_SECRET")
+    if app_id and app_secret:
+        return DeploypodClient(base_url, org_id, app_id=app_id, app_secret=app_secret)
+
+    token = os.environ.get("DEPLOYPOD_TOKEN")
+    if not token and deploypod_repo is not None:
+        script = Path(deploypod_repo) / "scripts" / "get_token.sh"
+        if script.exists():
+            token = subprocess.check_output([str(script)], text=True).strip()
+    if not token:
+        raise RuntimeError(
+            "No credentials: export DEPLOYPOD_APP_ID and DEPLOYPOD_APP_SECRET, "
+            "or DEPLOYPOD_TOKEN."
+        )
+    return DeploypodClient(base_url, org_id, token)

deploypod/exceptions.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+
+class DeploypodError(Exception):
+    """Base exception for all Deploypod SDK errors."""
+
+    def __init__(self, status_code: int, detail: str, response_body: dict | None = None):
+        self.status_code = status_code
+        self.detail = detail
+        self.response_body = response_body
+        super().__init__(f"[{status_code}] {detail}")
+
+
+# The name before the package went public, kept for existing code.
+DeployPodError = DeploypodError
+
+
+class AuthenticationError(DeploypodError):
+    """401/403 — invalid or missing credentials."""
+
+
+class NotFoundError(DeploypodError):
+    """404 — resource does not exist."""
+
+
+class ValidationError(DeploypodError):
+    """422 — request body failed validation."""
+
+
+class ConflictError(DeploypodError):
+    """409 — resource conflict (e.g. duplicate slug)."""
+
+
+class LicenseError(DeploypodError):
+    """403 — license limit exceeded or feature not available."""
+
+
+class ServerError(DeploypodError):
+    """5xx — unexpected server error."""