agenttier 0.1.1__py3-none-any.whl

agenttier/__init__.py

@@ -0,0 +1,83 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""AgentTier Python SDK.
+
+Manage isolated AI agent sandboxes on Kubernetes from Python.
+
+Typical usage::
+
+    from agenttier import AgentTierClient
+
+    with AgentTierClient(api_url="https://agenttier.company.com") as client:
+        sandbox = client.create_sandbox(template="general-coding", name="demo")
+        sandbox.wait_until_running()
+        print(sandbox.exec("uname -a").stdout)
+        sandbox.terminate()
+
+See :mod:`agenttier.async_client` for the ``async/await`` variant.
+"""
+
+from agenttier._version import __version__
+from agenttier.async_client import AsyncAgentTierClient
+from agenttier.async_sandbox import AsyncSandbox
+from agenttier.auth import APIKeyAuth, AuthProvider, BearerTokenAuth, KubeconfigAuth
+from agenttier.client import AgentTierClient
+from agenttier.exceptions import (
+    AgentTierError,
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    NotFoundError,
+    PolicyViolationError,
+    SandboxErrorState,
+    SandboxTimeoutError,
+)
+from agenttier.models import (
+    AuditEvent,
+    CommandResult,
+    CreatedBy,
+    CurrentUser,
+    ForwardedPort,
+    SandboxPhase,
+    SandboxSummary,
+    Template,
+    UsageAnalytics,
+)
+from agenttier.sandbox import Sandbox
+
+__all__ = [
+    "__version__",
+    # Clients
+    "AgentTierClient",
+    "AsyncAgentTierClient",
+    # Handles
+    "Sandbox",
+    "AsyncSandbox",
+    # Auth
+    "AuthProvider",
+    "APIKeyAuth",
+    "BearerTokenAuth",
+    "KubeconfigAuth",
+    # Models
+    "AuditEvent",
+    "CommandResult",
+    "CreatedBy",
+    "CurrentUser",
+    "ForwardedPort",
+    "SandboxPhase",
+    "SandboxSummary",
+    "Template",
+    "UsageAnalytics",
+    # Exceptions
+    "AgentTierError",
+    "APIError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ConflictError",
+    "NotFoundError",
+    "PolicyViolationError",
+    "SandboxErrorState",
+    "SandboxTimeoutError",
+]

agenttier/_http.py

@@ -0,0 +1,74 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Internal HTTP utilities.
+
+Kept private (underscore prefix) so we can change the shape freely without a
+compat guarantee. The public clients are the only consumers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from agenttier.exceptions import (
+    APIError,
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    NotFoundError,
+    PolicyViolationError,
+)
+
+
+def _decode_body(response: httpx.Response) -> Any:
+    """Return a JSON body, a text body, or None, whichever succeeds."""
+    if not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return response.text or None
+
+
+def raise_for_status(response: httpx.Response) -> None:
+    """Translate non-2xx responses into typed SDK exceptions.
+
+    The Router returns structured JSON error bodies (``{"error": ..., ...}``)
+    so we can offer crisp exception types without parsing error strings.
+    """
+    if response.is_success:
+        return
+
+    body = _decode_body(response)
+    status = response.status_code
+    message = _extract_message(body, response.reason_phrase)
+
+    if status == 401:
+        raise AuthenticationError(message)
+    if status == 403:
+        if isinstance(body, dict) and body.get("error") == "policy_violation":
+            raise PolicyViolationError(message, list(body.get("violations", [])))
+        raise AuthorizationError(message)
+    if status == 404:
+        raise NotFoundError(message)
+    if status == 409:
+        raise ConflictError(message)
+    raise APIError(status, message, body)
+
+
+def _extract_message(body: Any, fallback: str) -> str:
+    if isinstance(body, dict):
+        for key in ("error", "message"):
+            v = body.get(key)
+            if isinstance(v, str) and v:
+                return v
+    if isinstance(body, str) and body:
+        return body
+    return fallback or "request failed"
+
+
+def default_user_agent(version: str) -> str:
+    return f"agenttier-python-sdk/{version}"

agenttier/_version.py

@@ -0,0 +1,11 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Single source of truth for the SDK version string.
+
+Kept in a separate module so ``pyproject.toml`` and :mod:`agenttier` can both
+import it without circular dependencies. Release tooling reads this file when
+bumping versions; keep the identifier named ``__version__``.
+"""
+
+__version__ = "0.1.1"

agenttier/async_client.py

@@ -0,0 +1,141 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Async client for the AgentTier REST API."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Optional
+
+import httpx
+
+from agenttier._http import default_user_agent, raise_for_status
+from agenttier._version import __version__
+from agenttier.async_sandbox import AsyncSandbox
+from agenttier.auth import AuthProvider, auto_detect_auth
+from agenttier.models import CurrentUser, SandboxSummary, Template
+
+_API_PREFIX = "/api/v1"
+_DEFAULT_TIMEOUT = 30.0
+
+
+class AsyncAgentTierClient:
+    """Async counterpart to :class:`AgentTierClient`."""
+
+    def __init__(
+        self,
+        api_url: str,
+        auth: Optional[AuthProvider] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        *,
+        verify: bool | str = True,
+    ) -> None:
+        if not api_url:
+            raise ValueError("api_url must be a non-empty string")
+        self._api_url = api_url.rstrip("/")
+        self._auth = auth or auto_detect_auth()
+        self._http = httpx.AsyncClient(
+            base_url=f"{self._api_url}{_API_PREFIX}",
+            timeout=timeout,
+            verify=verify,
+            headers={"User-Agent": default_user_agent(__version__)},
+            event_hooks={"request": [self._apply_auth]},
+        )
+
+    async def __aenter__(self) -> "AsyncAgentTierClient":
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def create_sandbox(
+        self,
+        template: str,
+        name: str,
+        namespace: str = "default",
+        timeout: Optional[str] = None,
+        idle_timeout: Optional[str] = None,
+        storage_size: Optional[str] = None,
+    ) -> AsyncSandbox:
+        if not template:
+            raise ValueError("template must be a non-empty string")
+        if not name:
+            raise ValueError("name must be a non-empty string")
+
+        body: dict[str, object] = {
+            "name": name,
+            "namespace": namespace,
+            "templateRef": {"name": template, "kind": "ClusterSandboxTemplate"},
+        }
+        if timeout:
+            body["timeout"] = timeout
+        if idle_timeout:
+            body["idleTimeout"] = idle_timeout
+        if storage_size:
+            body["storage"] = {"size": storage_size}
+
+        resp = await self._http.post("/sandboxes", json=body)
+        raise_for_status(resp)
+        data = resp.json()
+        return AsyncSandbox(
+            self._http,
+            data["sandboxId"],
+            data.get("name", name),
+            data.get("namespace", namespace),
+        )
+
+    async def list_sandboxes(
+        self,
+        namespace: Optional[str] = None,
+        status: Optional[str] = None,
+    ) -> list[SandboxSummary]:
+        params: dict[str, str] = {}
+        if namespace:
+            params["namespace"] = namespace
+        if status:
+            params["status"] = status
+        resp = await self._http.get("/sandboxes", params=params)
+        raise_for_status(resp)
+        return [SandboxSummary.model_validate(s) for s in (resp.json().get("sandboxes") or [])]
+
+    async def get_sandbox(self, sandbox_id: str) -> AsyncSandbox:
+        if not sandbox_id:
+            raise ValueError("sandbox_id must be a non-empty string")
+        resp = await self._http.get(f"/sandboxes/{sandbox_id}")
+        raise_for_status(resp)
+        data = resp.json()
+        return AsyncSandbox(
+            self._http,
+            data["sandboxId"],
+            data.get("name", sandbox_id),
+            data.get("namespace", "default"),
+        )
+
+    async def list_templates(self) -> list[Template]:
+        resp = await self._http.get("/templates")
+        raise_for_status(resp)
+        return [Template.model_validate(t) for t in (resp.json().get("templates") or [])]
+
+    async def get_template(self, name: str) -> Template:
+        if not name:
+            raise ValueError("name must be a non-empty string")
+        resp = await self._http.get(f"/templates/{name}")
+        raise_for_status(resp)
+        return Template.model_validate(resp.json())
+
+    async def current_user(self) -> CurrentUser:
+        resp = await self._http.get("/user/me")
+        raise_for_status(resp)
+        return CurrentUser.model_validate(resp.json())
+
+    async def _apply_auth(self, request: httpx.Request) -> None:
+        self._auth.apply(request)

agenttier/async_sandbox.py

@@ -0,0 +1,110 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Async sandbox handle mirroring :mod:`agenttier.sandbox`."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Optional
+
+from agenttier._http import raise_for_status
+from agenttier.exceptions import SandboxErrorState, SandboxTimeoutError
+from agenttier.models import CommandResult, ForwardedPort, SandboxPhase, SandboxSummary
+
+if TYPE_CHECKING:  # pragma: no cover
+    import httpx
+
+_DEFAULT_WAIT_TIMEOUT = 120.0
+_DEFAULT_POLL_INTERVAL = 2.0
+
+
+class AsyncSandbox:
+    """Async remote handle for a sandbox."""
+
+    def __init__(
+        self,
+        http: "httpx.AsyncClient",
+        sandbox_id: str,
+        name: str,
+        namespace: str,
+    ) -> None:
+        self._http = http
+        self.id = sandbox_id
+        self.name = name
+        self.namespace = namespace
+
+    async def status(self) -> SandboxSummary:
+        resp = await self._http.get(f"/sandboxes/{self.id}")
+        raise_for_status(resp)
+        return SandboxSummary.model_validate(resp.json())
+
+    async def wait_until_running(
+        self,
+        timeout: float = _DEFAULT_WAIT_TIMEOUT,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> SandboxSummary:
+        loop = asyncio.get_event_loop()
+        deadline = loop.time() + timeout
+        last: Optional[SandboxSummary] = None
+        while loop.time() < deadline:
+            last = await self.status()
+            if last.phase is SandboxPhase.RUNNING:
+                return last
+            if last.phase is SandboxPhase.ERROR:
+                raise SandboxErrorState(last.message or f"sandbox {self.id} entered Error state")
+            await asyncio.sleep(poll_interval)
+        raise SandboxTimeoutError(
+            f"sandbox {self.id} did not reach Running within {timeout:.0f}s "
+            f"(last phase: {last.phase.value if last else 'unknown'})"
+        )
+
+    async def stop(self) -> None:
+        resp = await self._http.post(f"/sandboxes/{self.id}/stop")
+        raise_for_status(resp)
+
+    async def resume(self) -> None:
+        resp = await self._http.post(f"/sandboxes/{self.id}/resume")
+        raise_for_status(resp)
+
+    async def terminate(self) -> None:
+        resp = await self._http.delete(f"/sandboxes/{self.id}")
+        raise_for_status(resp)
+
+    delete = terminate
+
+    async def exec(self, command: str, timeout: int = 30) -> CommandResult:
+        if not command:
+            raise ValueError("command must be a non-empty string")
+        if timeout <= 0:
+            raise ValueError("timeout must be > 0")
+        resp = await self._http.post(
+            f"/sandboxes/{self.id}/exec",
+            json={"command": command, "timeout": timeout},
+            timeout=timeout + 10,
+        )
+        raise_for_status(resp)
+        return CommandResult.model_validate(resp.json())
+
+    async def list_ports(self) -> list[ForwardedPort]:
+        resp = await self._http.get(f"/sandboxes/{self.id}/ports")
+        raise_for_status(resp)
+        ports = resp.json().get("ports") or []
+        return [ForwardedPort.model_validate(p) for p in ports]
+
+    async def forward_port(self, port: int, protocol: str = "http") -> ForwardedPort:
+        if not 1 <= port <= 65535:
+            raise ValueError("port must be between 1 and 65535")
+        resp = await self._http.post(
+            f"/sandboxes/{self.id}/ports",
+            json={"port": port, "protocol": protocol},
+        )
+        raise_for_status(resp)
+        return ForwardedPort.model_validate(resp.json())
+
+    async def remove_port(self, port: int) -> None:
+        resp = await self._http.delete(f"/sandboxes/{self.id}/ports/{port}")
+        raise_for_status(resp)
+
+    def __repr__(self) -> str:
+        return f"AsyncSandbox(id={self.id!r}, name={self.name!r}, namespace={self.namespace!r})"

agenttier/auth.py

@@ -0,0 +1,105 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Authentication providers for the AgentTier SDK.
+
+Three concrete providers are shipped:
+
+* :class:`APIKeyAuth` — sends ``X-API-Key``.
+* :class:`BearerTokenAuth` — sends ``Authorization: Bearer <token>`` (OIDC JWT).
+* :class:`KubeconfigAuth` — uses the in-cluster ServiceAccount token when
+  available; falls back to unauthenticated (the Router's dev mode accepts this).
+
+:func:`auto_detect_auth` picks the best available provider from environment
+variables and file system state.
+"""
+
+from __future__ import annotations
+
+import os
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+
+import httpx
+
+
+class AuthProvider(ABC):
+    """Attaches credentials to outgoing HTTP requests."""
+
+    @abstractmethod
+    def apply(self, request: httpx.Request) -> None:
+        """Mutate ``request`` in place to carry credentials."""
+
+
+class BearerTokenAuth(AuthProvider):
+    """Static bearer token (typically an OIDC JWT)."""
+
+    def __init__(self, token: str) -> None:
+        if not token:
+            raise ValueError("token must be a non-empty string")
+        self._token = token
+
+    def apply(self, request: httpx.Request) -> None:
+        request.headers["Authorization"] = f"Bearer {self._token}"
+
+
+class APIKeyAuth(AuthProvider):
+    """AgentTier API key."""
+
+    def __init__(self, api_key: str) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string")
+        self._api_key = api_key
+
+    def apply(self, request: httpx.Request) -> None:
+        request.headers["X-API-Key"] = self._api_key
+
+
+# Standard in-cluster ServiceAccount token path (Kubernetes Downward API).
+_IN_CLUSTER_TOKEN_PATH = Path("/var/run/secrets/kubernetes.io/serviceaccount/token")
+
+
+class KubeconfigAuth(AuthProvider):
+    """In-cluster ServiceAccount token, if one is mounted.
+
+    A proper kubeconfig parser is intentionally out of scope; if you need
+    kubeconfig-driven auth against a remote cluster, extract the token
+    yourself and pass it to :class:`BearerTokenAuth`.
+    """
+
+    def __init__(self, token_path: Optional[str | Path] = None) -> None:
+        path = Path(token_path) if token_path else _IN_CLUSTER_TOKEN_PATH
+        self._token: Optional[str] = None
+        if path.exists():
+            try:
+                self._token = path.read_text().strip() or None
+            except OSError:
+                # Permission problems etc. — fall back to unauthenticated.
+                self._token = None
+
+    def apply(self, request: httpx.Request) -> None:
+        if self._token:
+            request.headers["Authorization"] = f"Bearer {self._token}"
+
+
+def auto_detect_auth() -> AuthProvider:
+    """Return the best available auth provider for the current environment.
+
+    Priority order:
+
+    1. ``AGENTTIER_API_KEY``
+    2. ``AGENTTIER_TOKEN`` (bearer / OIDC JWT)
+    3. In-cluster ServiceAccount token at ``/var/run/secrets/...``
+    4. Unauthenticated — the Router accepts this only in dev mode (no OIDC
+       configured); production deployments will return 401.
+    """
+    api_key = os.environ.get("AGENTTIER_API_KEY")
+    if api_key:
+        return APIKeyAuth(api_key)
+
+    token = os.environ.get("AGENTTIER_TOKEN")
+    if token:
+        return BearerTokenAuth(token)
+
+    return KubeconfigAuth()

agenttier/client.py

@@ -0,0 +1,175 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Sync client for the AgentTier REST API."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Optional
+
+import httpx
+
+from agenttier._http import default_user_agent, raise_for_status
+from agenttier._version import __version__
+from agenttier.auth import AuthProvider, auto_detect_auth
+from agenttier.models import CurrentUser, SandboxSummary, Template
+from agenttier.sandbox import Sandbox
+
+_API_PREFIX = "/api/v1"
+_DEFAULT_TIMEOUT = 30.0
+
+
+class AgentTierClient:
+    """High-level sync client for the AgentTier REST API.
+
+    Example:
+
+    .. code-block:: python
+
+        with AgentTierClient(api_url="https://agenttier.company.com") as client:
+            sandbox = client.create_sandbox(template="general-coding", name="demo")
+            sandbox.wait_until_running()
+            print(sandbox.exec("uname -a").stdout)
+            sandbox.terminate()
+    """
+
+    def __init__(
+        self,
+        api_url: str,
+        auth: Optional[AuthProvider] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+        *,
+        verify: bool | str = True,
+    ) -> None:
+        if not api_url:
+            raise ValueError("api_url must be a non-empty string")
+        self._api_url = api_url.rstrip("/")
+        self._auth = auth or auto_detect_auth()
+        self._http = httpx.Client(
+            base_url=f"{self._api_url}{_API_PREFIX}",
+            timeout=timeout,
+            verify=verify,
+            headers={"User-Agent": default_user_agent(__version__)},
+            event_hooks={"request": [self._apply_auth]},
+        )
+
+    # ------- context manager --------------------------------------------
+
+    def __enter__(self) -> "AgentTierClient":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    # ------- sandboxes --------------------------------------------------
+
+    def create_sandbox(
+        self,
+        template: str,
+        name: str,
+        namespace: str = "default",
+        timeout: Optional[str] = None,
+        idle_timeout: Optional[str] = None,
+        storage_size: Optional[str] = None,
+    ) -> Sandbox:
+        """Create a sandbox from a ``ClusterSandboxTemplate``.
+
+        ``timeout`` and ``idle_timeout`` take Go-style duration strings
+        (``"8h"``, ``"30m"``).
+        """
+        if not template:
+            raise ValueError("template must be a non-empty string")
+        if not name:
+            raise ValueError("name must be a non-empty string")
+
+        body: dict[str, object] = {
+            "name": name,
+            "namespace": namespace,
+            "templateRef": {"name": template, "kind": "ClusterSandboxTemplate"},
+        }
+        if timeout:
+            body["timeout"] = timeout
+        if idle_timeout:
+            body["idleTimeout"] = idle_timeout
+        if storage_size:
+            body["storage"] = {"size": storage_size}
+
+        resp = self._http.post("/sandboxes", json=body)
+        raise_for_status(resp)
+        data = resp.json()
+        return Sandbox(
+            self._http,
+            data["sandboxId"],
+            data.get("name", name),
+            data.get("namespace", namespace),
+        )
+
+    def list_sandboxes(
+        self,
+        namespace: Optional[str] = None,
+        status: Optional[str] = None,
+    ) -> list[SandboxSummary]:
+        """List sandboxes visible to the caller."""
+        params: dict[str, str] = {}
+        if namespace:
+            params["namespace"] = namespace
+        if status:
+            params["status"] = status
+
+        resp = self._http.get("/sandboxes", params=params)
+        raise_for_status(resp)
+        return [SandboxSummary.model_validate(s) for s in (resp.json().get("sandboxes") or [])]
+
+    def get_sandbox(self, sandbox_id: str) -> Sandbox:
+        """Return a handle to an existing sandbox."""
+        if not sandbox_id:
+            raise ValueError("sandbox_id must be a non-empty string")
+        resp = self._http.get(f"/sandboxes/{sandbox_id}")
+        raise_for_status(resp)
+        data = resp.json()
+        return Sandbox(
+            self._http,
+            data["sandboxId"],
+            data.get("name", sandbox_id),
+            data.get("namespace", "default"),
+        )
+
+    # ------- templates --------------------------------------------------
+
+    def list_templates(self) -> list[Template]:
+        resp = self._http.get("/templates")
+        raise_for_status(resp)
+        return [Template.model_validate(t) for t in (resp.json().get("templates") or [])]
+
+    def get_template(self, name: str) -> Template:
+        if not name:
+            raise ValueError("name must be a non-empty string")
+        resp = self._http.get(f"/templates/{name}")
+        raise_for_status(resp)
+        return Template.model_validate(resp.json())
+
+    # ------- identity ---------------------------------------------------
+
+    def current_user(self) -> CurrentUser:
+        """Return the server's view of the caller's identity.
+
+        Uses the same logic as the Web UI — handy for verifying auth is wired
+        up correctly.
+        """
+        resp = self._http.get("/user/me")
+        raise_for_status(resp)
+        return CurrentUser.model_validate(resp.json())
+
+    # ------- internals --------------------------------------------------
+
+    def _apply_auth(self, request: httpx.Request) -> None:
+        self._auth.apply(request)

agenttier/exceptions.py

@@ -0,0 +1,61 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Exception hierarchy for the AgentTier SDK.
+
+All SDK errors inherit from ``AgentTierError`` so callers can catch everything
+with a single except-clause.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AgentTierError(Exception):
+    """Base class for all SDK errors."""
+
+
+class AuthenticationError(AgentTierError):
+    """Raised when authentication fails (401)."""
+
+
+class AuthorizationError(AgentTierError):
+    """Raised when the caller is not permitted to perform an action (403)."""
+
+
+class NotFoundError(AgentTierError):
+    """Raised when a requested resource does not exist (404)."""
+
+
+class ConflictError(AgentTierError):
+    """Raised when an operation conflicts with the resource's current state (409)."""
+
+
+class PolicyViolationError(AgentTierError):
+    """Raised when a governance policy rejects a sandbox create.
+
+    The server returns a structured body with per-rule violation codes; those
+    are preserved on the exception so callers can inspect them programmatically.
+    """
+
+    def __init__(self, message: str, violations: list[dict[str, Any]]) -> None:
+        super().__init__(message)
+        self.violations = violations
+
+
+class SandboxTimeoutError(AgentTierError, TimeoutError):
+    """Raised when ``wait_until_running`` times out."""
+
+
+class SandboxErrorState(AgentTierError):
+    """Raised when a sandbox transitions to the Error phase while being awaited."""
+
+
+class APIError(AgentTierError):
+    """Generic HTTP error wrapping the server's response body."""
+
+    def __init__(self, status_code: int, message: str, body: Any = None) -> None:
+        super().__init__(f"{status_code}: {message}")
+        self.status_code = status_code
+        self.body = body

agenttier/models.py

@@ -0,0 +1,136 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pydantic v2 models for AgentTier REST responses.
+
+The Router serializes fields in camelCase; we surface them to Python users as
+snake_case. Both names are accepted when parsing so downstream code can be
+written either way.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def _to_camel(s: str) -> str:
+    head, *tail = s.split("_")
+    return head + "".join(p.capitalize() for p in tail)
+
+
+class _Model(BaseModel):
+    """Internal base with camelCase serialization and permissive extras."""
+
+    model_config = ConfigDict(
+        alias_generator=_to_camel,
+        populate_by_name=True,
+        # Router responses may grow new fields; don't break old SDK versions.
+        extra="ignore",
+    )
+
+
+class SandboxPhase(str, Enum):
+    """Lifecycle phases for a sandbox."""
+
+    CREATING = "Creating"
+    RUNNING = "Running"
+    STOPPED = "Stopped"
+    ERROR = "Error"
+    DELETING = "Deleting"
+    UNKNOWN = "Unknown"
+
+
+class CreatedBy(_Model):
+    """Identity of the user that created a sandbox."""
+
+    email: Optional[str] = None
+    display_name: Optional[str] = None
+
+
+class SandboxSummary(_Model):
+    """Sandbox as returned by list/get endpoints."""
+
+    sandbox_id: str = Field(alias="sandboxId")
+    name: str
+    namespace: str
+    status: str
+    pod_name: Optional[str] = Field(default=None, alias="podName")
+    pvc_name: Optional[str] = Field(default=None, alias="pvcName")
+    template_ref: Optional[str] = Field(default=None, alias="templateRef")
+    created_at: Optional[str] = Field(default=None, alias="createdAt")
+    last_activity_at: Optional[str] = Field(default=None, alias="lastActivityAt")
+    created_by: Optional[CreatedBy] = Field(default=None, alias="createdBy")
+    message: Optional[str] = None
+
+    @property
+    def phase(self) -> SandboxPhase:
+        """Typed view of ``status``; returns ``UNKNOWN`` for unexpected values."""
+        try:
+            return SandboxPhase(self.status)
+        except ValueError:
+            return SandboxPhase.UNKNOWN
+
+
+class CommandResult(_Model):
+    """Output of a non-interactive command run inside a sandbox."""
+
+    stdout: str
+    stderr: str
+    exit_code: int = Field(alias="exitCode")
+
+
+class Template(_Model):
+    """Sandbox template as exposed by the Router templates endpoints."""
+
+    name: str
+    description: Optional[str] = None
+    image: Optional[str] = None
+    resource_version: Optional[str] = Field(default=None, alias="resourceVersion")
+    # ``spec`` is the full SandboxTemplateSpec — kept as a free-form dict so the
+    # SDK does not have to track every field as it evolves.
+    spec: Optional[dict[str, Any]] = None
+
+
+class ForwardedPort(_Model):
+    """A port exposed from the sandbox via the Router."""
+
+    port: int
+    protocol: str
+    preview_url: Optional[str] = Field(default=None, alias="previewUrl")
+    internal_url: Optional[str] = Field(default=None, alias="internalUrl")
+
+
+class CurrentUser(_Model):
+    """The authenticated identity as seen by the Router."""
+
+    sub: str
+    email: Optional[str] = None
+    name: Optional[str] = None
+    groups: list[str] = Field(default_factory=list)
+    is_admin: bool = Field(default=False, alias="isAdmin")
+
+
+class UsageAnalytics(_Model):
+    """Fleet-wide usage summary returned by /analytics/usage."""
+
+    total_sandboxes: int = Field(alias="total_sandboxes")
+    status_breakdown: dict[str, int] = Field(alias="status_breakdown")
+    template_breakdown: dict[str, int] = Field(alias="template_breakdown")
+    avg_startup_ms: int = Field(alias="avg_startup_ms")
+    startup_sample_count: int = Field(alias="startup_sample_count")
+
+
+class AuditEvent(_Model):
+    """One entry from the activity log."""
+
+    timestamp: Optional[datetime] = None
+    event_type: Optional[str] = Field(default=None, alias="eventType")
+    sandbox_id: Optional[str] = Field(default=None, alias="sandboxId")
+    sandbox_name: Optional[str] = Field(default=None, alias="sandboxName")
+    namespace: Optional[str] = None
+    user_email: Optional[str] = Field(default=None, alias="userEmail")
+    details: Optional[dict[str, Any]] = None

agenttier/sandbox.py

@@ -0,0 +1,150 @@
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Sync sandbox handle.
+
+Use :meth:`AgentTierClient.create_sandbox` / :meth:`AgentTierClient.get_sandbox`
+to obtain instances — don't construct :class:`Sandbox` directly.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Optional
+
+from agenttier._http import raise_for_status
+from agenttier.exceptions import SandboxErrorState, SandboxTimeoutError
+from agenttier.models import CommandResult, ForwardedPort, SandboxPhase, SandboxSummary
+
+if TYPE_CHECKING:  # pragma: no cover
+    import httpx
+
+_DEFAULT_WAIT_TIMEOUT = 120.0
+_DEFAULT_POLL_INTERVAL = 2.0
+
+
+class Sandbox:
+    """Remote handle for a sandbox running in an AgentTier cluster."""
+
+    def __init__(
+        self,
+        http: "httpx.Client",
+        sandbox_id: str,
+        name: str,
+        namespace: str,
+    ) -> None:
+        self._http = http
+        self.id = sandbox_id
+        self.name = name
+        self.namespace = namespace
+
+    # ------- state -------------------------------------------------------
+
+    def status(self) -> SandboxSummary:
+        """Fetch the latest status from the server."""
+        resp = self._http.get(f"/sandboxes/{self.id}")
+        raise_for_status(resp)
+        return SandboxSummary.model_validate(resp.json())
+
+    @property
+    def phase(self) -> SandboxPhase:
+        """Shortcut returning the typed phase of the current status."""
+        return self.status().phase
+
+    def wait_until_running(
+        self,
+        timeout: float = _DEFAULT_WAIT_TIMEOUT,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+    ) -> SandboxSummary:
+        """Block until the sandbox reaches ``Running``.
+
+        Returns the final :class:`SandboxSummary` on success.
+
+        Raises :class:`SandboxTimeoutError` on timeout and
+        :class:`SandboxErrorState` if the sandbox transitions to Error.
+        """
+        deadline = time.monotonic() + timeout
+        last: Optional[SandboxSummary] = None
+        while time.monotonic() < deadline:
+            last = self.status()
+            if last.phase is SandboxPhase.RUNNING:
+                return last
+            if last.phase is SandboxPhase.ERROR:
+                raise SandboxErrorState(last.message or f"sandbox {self.id} entered Error state")
+            time.sleep(poll_interval)
+        raise SandboxTimeoutError(
+            f"sandbox {self.id} did not reach Running within {timeout:.0f}s "
+            f"(last phase: {last.phase.value if last else 'unknown'})"
+        )
+
+    # ------- lifecycle ---------------------------------------------------
+
+    def stop(self) -> None:
+        """Delete the sandbox Pod while preserving the PVC."""
+        resp = self._http.post(f"/sandboxes/{self.id}/stop")
+        raise_for_status(resp)
+
+    def resume(self) -> None:
+        """Re-create the Pod for a stopped sandbox; re-uses the same PVC."""
+        resp = self._http.post(f"/sandboxes/{self.id}/resume")
+        raise_for_status(resp)
+
+    def terminate(self) -> None:
+        """Permanently delete the sandbox and its workspace."""
+        resp = self._http.delete(f"/sandboxes/{self.id}")
+        raise_for_status(resp)
+
+    # Alias kept for consistency with the REST name.
+    delete = terminate
+
+    # ------- execution ---------------------------------------------------
+
+    def exec(self, command: str, timeout: int = 30) -> CommandResult:
+        """Run a shell command inside the sandbox and wait for the result.
+
+        ``timeout`` is applied both server-side (to the exec) and on the HTTP
+        call (with a small buffer for overhead).
+        """
+        if not command:
+            raise ValueError("command must be a non-empty string")
+        if timeout <= 0:
+            raise ValueError("timeout must be > 0")
+        # Give the HTTP call a small buffer over the server-side exec timeout
+        # so the server error bubbles up instead of httpx cutting us off.
+        resp = self._http.post(
+            f"/sandboxes/{self.id}/exec",
+            json={"command": command, "timeout": timeout},
+            timeout=timeout + 10,
+        )
+        raise_for_status(resp)
+        return CommandResult.model_validate(resp.json())
+
+    # ------- port forwarding --------------------------------------------
+
+    def list_ports(self) -> list[ForwardedPort]:
+        """Return the ports currently forwarded from this sandbox."""
+        resp = self._http.get(f"/sandboxes/{self.id}/ports")
+        raise_for_status(resp)
+        ports = resp.json().get("ports") or []
+        return [ForwardedPort.model_validate(p) for p in ports]
+
+    def forward_port(self, port: int, protocol: str = "http") -> ForwardedPort:
+        """Expose a container port via a ClusterIP Service (and Ingress if configured)."""
+        if not 1 <= port <= 65535:
+            raise ValueError("port must be between 1 and 65535")
+        resp = self._http.post(
+            f"/sandboxes/{self.id}/ports",
+            json={"port": port, "protocol": protocol},
+        )
+        raise_for_status(resp)
+        return ForwardedPort.model_validate(resp.json())
+
+    def remove_port(self, port: int) -> None:
+        """Tear down a previously-forwarded port."""
+        resp = self._http.delete(f"/sandboxes/{self.id}/ports/{port}")
+        raise_for_status(resp)
+
+    # ------- misc --------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f"Sandbox(id={self.id!r}, name={self.name!r}, namespace={self.namespace!r})"

agenttier-0.1.1.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: agenttier
+Version: 0.1.1
+Summary: Python SDK for AgentTier — manage isolated AI agent sandboxes on Kubernetes
+Project-URL: Homepage, https://github.com/agenttier/agenttier
+Project-URL: Documentation, https://agenttier.github.io/agenttier/sdk/
+Project-URL: Repository, https://github.com/agenttier/agenttier
+Project-URL: Issues, https://github.com/agenttier/agenttier/issues
+Project-URL: Changelog, https://github.com/agenttier/agenttier/blob/main/CHANGELOG.md
+Author: AgentTier Authors
+License-Expression: Apache-2.0
+Keywords: agents,ai-agents,developer-tools,kubernetes,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Clustering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27.0
+Requires-Dist: pydantic<3.0,>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AgentTier Python SDK
+
+Programmatic client for [AgentTier](https://github.com/agenttier/agenttier) —
+manage isolated, persistent Kubernetes sandboxes for AI agents from Python.
+
+```
+pip install agenttier
+```
+
+## Synchronous quick start
+
+```python
+from agenttier import AgentTierClient
+
+with AgentTierClient(api_url="https://agenttier.company.com") as client:
+    sandbox = client.create_sandbox(template="general-coding", name="demo")
+    sandbox.wait_until_running()
+
+    result = sandbox.exec("echo 'hello from AgentTier'")
+    print(result.stdout, "exit", result.exit_code)
+
+    port = sandbox.forward_port(8080)
+    print("Forwarded:", port.preview_url or port.internal_url)
+
+    sandbox.terminate()
+```
+
+## Async
+
+```python
+import asyncio
+from agenttier import AsyncAgentTierClient
+
+async def main():
+    async with AsyncAgentTierClient(api_url="https://agenttier.company.com") as client:
+        sandbox = await client.create_sandbox(template="general-coding", name="demo")
+        await sandbox.wait_until_running()
+        result = await sandbox.exec("uname -a")
+        print(result.stdout)
+        await sandbox.terminate()
+
+asyncio.run(main())
+```
+
+## Authentication
+
+The SDK auto-detects credentials in this order:
+
+1. `AGENTTIER_API_KEY` — sent as `X-API-Key`.
+2. `AGENTTIER_TOKEN` — sent as `Authorization: Bearer <token>` (OIDC JWT).
+3. In-cluster ServiceAccount token at `/var/run/secrets/kubernetes.io/serviceaccount/token`.
+4. Unauthenticated (accepted only in the Router's dev mode).
+
+Or pass an explicit provider:
+
+```python
+from agenttier import AgentTierClient, APIKeyAuth, BearerTokenAuth
+
+client = AgentTierClient(
+    api_url="https://agenttier.company.com",
+    auth=APIKeyAuth("sk_live_..."),
+)
+```
+
+## Error handling
+
+Every error inherits from `AgentTierError` so you can catch them all at once.
+The common subclasses you'll want to handle individually:
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` | 401 — token / API key missing or invalid |
+| `AuthorizationError` | 403 — authenticated but not permitted |
+| `PolicyViolationError` | 403 with governance body; exposes `.violations` |
+| `NotFoundError` | 404 — resource doesn't exist |
+| `ConflictError` | 409 — operation invalid for current state |
+| `SandboxTimeoutError` | `wait_until_running` timed out |
+| `SandboxErrorState` | sandbox entered the `Error` phase while waiting |
+| `APIError` | anything else; carries `.status_code` and `.body` |
+
+## Supported API surface (v0.1.1)
+
+Only endpoints that the Router server implements in v0.1.0 are exposed:
+
+- **Sandboxes** — `create_sandbox`, `list_sandboxes`, `get_sandbox`, `stop`,
+  `resume`, `terminate`, `exec`, `wait_until_running`, `status`.
+- **Port forwarding** — `forward_port`, `list_ports`, `remove_port`.
+- **Templates** — `list_templates`, `get_template`.
+- **Identity** — `current_user`.
+
+Endpoints that are not yet implemented on the server (file transfer, sharing,
+cloning, WebSocket terminal from Python) are **not exposed** by the SDK and
+will be added in a future release once the server ships them.
+
+## Supported Python versions
+
+3.10, 3.11, 3.12, 3.13. Runtime dependencies: `httpx` and `pydantic`.
+
+## License
+
+Apache-2.0. Source at
+[github.com/agenttier/agenttier/tree/main/python-sdk](https://github.com/agenttier/agenttier/tree/main/python-sdk).

agenttier-0.1.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+agenttier/__init__.py,sha256=C7c0mu17A3NqYJ5_pzth4FG7XWdWr2b2uvisDTMtkn8,1966
+agenttier/_http.py,sha256=JUv82WECWrZidSIq-Xt7r-Mp9CurTLBE7mn3-6o5NOo,2079
+agenttier/_version.py,sha256=umoBVGIuorxMM9hvvs2JqoAPSiQd3WaFR9u-MKvTfZU,374
+agenttier/async_client.py,sha256=0C1L6lMzpBwWX46Ymb5eNWJdltuIuzoi5HYST5nVb5Y,4594
+agenttier/async_sandbox.py,sha256=TZIzYY4PC4PgNtn7oj-aEetRo2h_5_pi-0sFFGePpOs,3854
+agenttier/auth.py,sha256=9cPUq7ZVBQT49ybU-2dm536u7obKA_80g1seIkmQ_WQ,3364
+agenttier/client.py,sha256=2NfGTP6XgE0MhUE9wWeMSaGegkHkAS6z6kROhEWQo0s,5620
+agenttier/exceptions.py,sha256=NDCgXccXvwe37ONSIq-pxNJovmAclCAIIb5fCrhNmPY,1790
+agenttier/models.py,sha256=6nqPYZI3BJVnNHxACVj-0_SXjVtJeVGBSiia7F8C-fg,4279
+agenttier/sandbox.py,sha256=4qwWgoIyCkJlm04WoYZ10sEpdGnal8bRLBf62j-MSD0,5528
+agenttier/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agenttier-0.1.1.dist-info/METADATA,sha256=TokHeeXQgigqyH0sQG-po-O_eqztNDGy5MNTKpF4Pi0,4908
+agenttier-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agenttier-0.1.1.dist-info/RECORD,,

agenttier-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any