agenttier 0.1.1__tar.gz

agenttier-0.1.1/.gitignore

@@ -0,0 +1,78 @@
+# Go
+bin/
+_output/
+vendor/
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+coverage.out
+coverage.html
+
+# Compiled binaries
+/controller
+/router
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Kiro (internal development tooling)
+.kiro/
+
+# Local working todo (not shipped)
+/todo.md
+
+# Node.js (web-ui)
+web-ui/node_modules/
+web-ui/dist/
+web-ui/.env.local
+web-ui/.env.*.local
+
+# Python (SDK)
+python-sdk/**/__pycache__/
+python-sdk/*.egg-info/
+python-sdk/dist/
+python-sdk/build/
+python-sdk/.venv/
+python-sdk/.env
+python-sdk/.pytest_cache/
+python-sdk/.mypy_cache/
+python-sdk/.ruff_cache/
+
+# Environment
+.env
+.env.local
+*.log
+
+# Kubernetes
+kubeconfig
+*.kubeconfig
+
+# Terraform
+terraform/**/.terraform/
+terraform/**/*.tfstate
+terraform/**/*.tfstate.backup
+terraform/**/*.tfvars
+!terraform/**/*.tfvars.example
+terraform/**/tfplan
+
+# Helm
+helm/agenttier/charts/
+
+# Build artifacts
+dist/
+tmp/
+
+# Test
+testbin/
+
+# OS files
+Thumbs.db

agenttier-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,102 @@
+# 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/examples/basic_usage.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+# Copyright 2024 AgentTier Authors.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Basic usage example for the AgentTier Python SDK.
+
+Before running: set ``AGENTTIER_API_KEY`` or ``AGENTTIER_TOKEN`` (or run the
+Router in dev mode locally) and update ``API_URL`` below.
+"""
+
+from __future__ import annotations
+
+from agenttier import AgentTierClient
+
+API_URL = "http://localhost:8080"  # or https://agenttier.company.com in production
+
+
+def main() -> None:
+    with AgentTierClient(api_url=API_URL) as client:
+        print("Authenticated as:", client.current_user())
+
+        print("Available templates:")
+        for template in client.list_templates():
+            print(f"  - {template.name}: {template.description or '(no description)'}")
+
+        sandbox = client.create_sandbox(template="general-coding", name="sdk-demo")
+        print(f"Created sandbox {sandbox.id}; waiting for Running…")
+        sandbox.wait_until_running()
+
+        result = sandbox.exec("echo 'Hello from AgentTier!'")
+        print(f"stdout: {result.stdout.strip()}")
+        print(f"exit:   {result.exit_code}")
+
+        sandbox.terminate()
+        print("Terminated.")
+
+
+if __name__ == "__main__":
+    main()

agenttier-0.1.1/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agenttier"
+# Source of truth is src/agenttier/_version.py — keep both in sync on release.
+version = "0.1.1"
+description = "Python SDK for AgentTier — manage isolated AI agent sandboxes on Kubernetes"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+    { name = "AgentTier Authors" },
+]
+keywords = ["kubernetes", "sandbox", "ai-agents", "developer-tools", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Clustering",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27.0,<1.0",
+    "pydantic>=2.0.0,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.30",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/agenttier/agenttier"
+Documentation = "https://agenttier.github.io/agenttier/sdk/"
+Repository = "https://github.com/agenttier/agenttier"
+Issues = "https://github.com/agenttier/agenttier/issues"
+Changelog = "https://github.com/agenttier/agenttier/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agenttier"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/agenttier/py.typed" = "agenttier/py.typed"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

agenttier-0.1.1/src/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-0.1.1/src/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-0.1.1/src/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"