agentkernel-sdk 0.7.1__tar.gz

agentkernel_sdk-0.7.1/.gitignore

@@ -0,0 +1,4 @@
+.pytest_cache/
+.venv/
+__pycache__/
+dist/

agentkernel_sdk-0.7.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: agentkernel-sdk
+Version: 0.7.1
+Summary: Python SDK for agentkernel — run AI coding agents in secure, isolated microVMs
+Project-URL: Homepage, https://github.com/thrashr888/agentkernel
+Project-URL: Repository, https://github.com/thrashr888/agentkernel/tree/main/sdk/python
+Author-email: Paul Thrasher <thrashr888@gmail.com>
+License-Expression: MIT
+Keywords: agent,agentkernel,ai,firecracker,microvm,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agentkernel
+
+Python SDK for [agentkernel](https://github.com/thrashr888/agentkernel) — run AI coding agents in secure, isolated microVMs.
+
+## Install
+
+```bash
+pip install agentkernel-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from agentkernel import AgentKernel
+
+with AgentKernel() as client:
+    result = client.run(["echo", "hello"])
+    print(result.output)  # "hello\n"
+```
+
+## Async
+
+```python
+from agentkernel import AsyncAgentKernel
+
+async with AsyncAgentKernel() as client:
+    result = await client.run(["echo", "hello"])
+    print(result.output)
+```
+
+## Sandbox Sessions
+
+```python
+with AgentKernel() as client:
+    with client.sandbox("test", image="python:3.12-alpine") as sb:
+        sb.run(["pip", "install", "numpy"])
+        result = sb.run(["python3", "-c", "import numpy; print(numpy.__version__)"])
+        print(result.output)
+    # sandbox auto-removed
+```
+
+## Streaming
+
+```python
+for event in client.run_stream(["python3", "script.py"]):
+    if event.type == "output":
+        print(event.data["data"], end="")
+```
+
+## Configuration
+
+```python
+client = AgentKernel(
+    base_url="http://localhost:18888",  # default
+    api_key="sk-...",                  # optional
+    timeout=30.0,                      # default
+)
+```
+
+Or use environment variables:
+
+```bash
+export AGENTKERNEL_BASE_URL=http://localhost:18888
+export AGENTKERNEL_API_KEY=sk-...
+```
+
+## License
+
+MIT

agentkernel_sdk-0.7.1/README.md

@@ -0,0 +1,71 @@
+# agentkernel
+
+Python SDK for [agentkernel](https://github.com/thrashr888/agentkernel) — run AI coding agents in secure, isolated microVMs.
+
+## Install
+
+```bash
+pip install agentkernel-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from agentkernel import AgentKernel
+
+with AgentKernel() as client:
+    result = client.run(["echo", "hello"])
+    print(result.output)  # "hello\n"
+```
+
+## Async
+
+```python
+from agentkernel import AsyncAgentKernel
+
+async with AsyncAgentKernel() as client:
+    result = await client.run(["echo", "hello"])
+    print(result.output)
+```
+
+## Sandbox Sessions
+
+```python
+with AgentKernel() as client:
+    with client.sandbox("test", image="python:3.12-alpine") as sb:
+        sb.run(["pip", "install", "numpy"])
+        result = sb.run(["python3", "-c", "import numpy; print(numpy.__version__)"])
+        print(result.output)
+    # sandbox auto-removed
+```
+
+## Streaming
+
+```python
+for event in client.run_stream(["python3", "script.py"]):
+    if event.type == "output":
+        print(event.data["data"], end="")
+```
+
+## Configuration
+
+```python
+client = AgentKernel(
+    base_url="http://localhost:18888",  # default
+    api_key="sk-...",                  # optional
+    timeout=30.0,                      # default
+)
+```
+
+Or use environment variables:
+
+```bash
+export AGENTKERNEL_BASE_URL=http://localhost:18888
+export AGENTKERNEL_API_KEY=sk-...
+```
+
+## License
+
+MIT

agentkernel_sdk-0.7.1/examples/async_example.py

@@ -0,0 +1,31 @@
+"""Async example for agentkernel Python SDK."""
+
+import asyncio
+import sys
+
+from agentkernel import AsyncAgentKernel
+
+
+async def main() -> None:
+    async with AsyncAgentKernel() as client:
+        # Health check
+        print("Health:", await client.health())
+
+        # Run a command
+        result = await client.run(["echo", "Hello from async agentkernel!"])
+        print("Output:", result.output)
+
+        # Sandbox session with async context manager
+        async with client.sandbox("async-demo", image="python:3.12-alpine") as sb:
+            await sb.run(["pip", "install", "requests"])
+            result = await sb.run(["python3", "-c", "import requests; print(requests.__version__)"])
+            print(result.output)
+        # sandbox auto-removed
+
+        # Async streaming
+        async for event in client.run_stream(["echo", "streaming async"]):
+            if event.event_type == "output":
+                sys.stdout.write(event.data.get("data", ""))
+
+
+asyncio.run(main())

agentkernel_sdk-0.7.1/examples/quickstart.py

@@ -0,0 +1,16 @@
+"""Quick start example for agentkernel Python SDK."""
+
+from agentkernel import AgentKernel
+
+client = AgentKernel()
+
+# Health check
+print("Health:", client.health())
+
+# Run a command
+result = client.run(["echo", "Hello from agentkernel!"])
+print("Output:", result.output)
+
+# List sandboxes
+sandboxes = client.list_sandboxes()
+print("Sandboxes:", sandboxes)

agentkernel_sdk-0.7.1/examples/sandbox_session.py

@@ -0,0 +1,16 @@
+"""Sandbox session example for agentkernel Python SDK."""
+
+from agentkernel import AgentKernel
+
+client = AgentKernel()
+
+# Create a sandbox session — auto-removed when context manager exits
+with client.sandbox("demo", image="python:3.12-alpine") as sb:
+    # Install a package
+    sb.run(["pip", "install", "numpy"])
+
+    # Run code
+    result = sb.run(["python3", "-c", "import numpy; print(f'numpy {numpy.__version__}')"])
+    print(result.output)
+
+# Sandbox is automatically removed here

agentkernel_sdk-0.7.1/examples/streaming.py

@@ -0,0 +1,19 @@
+"""Streaming example for agentkernel Python SDK."""
+
+import sys
+
+from agentkernel import AgentKernel
+
+client = AgentKernel()
+
+# Stream output from a command
+for event in client.run_stream(["python3", "-c", "print('Hello from streaming!')"]):
+    match event.event_type:
+        case "started":
+            print("[started]", event.data)
+        case "output":
+            sys.stdout.write(event.data.get("data", ""))
+        case "done":
+            print(f"\n[done] exit_code: {event.data.get('exit_code')}")
+        case "error":
+            print(f"[error] {event.data.get('message')}", file=sys.stderr)

agentkernel_sdk-0.7.1/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentkernel-sdk"
+version = "0.7.1"
+description = "Python SDK for agentkernel — run AI coding agents in secure, isolated microVMs"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Paul Thrasher", email = "thrashr888@gmail.com" }]
+keywords = ["agentkernel", "sandbox", "microvm", "ai", "agent", "firecracker"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27", "httpx-sse>=0.4", "pydantic>=2.0"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-httpx>=0.34",
+    "mypy>=1.13",
+    "ruff>=0.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/thrashr888/agentkernel"
+Repository = "https://github.com/thrashr888/agentkernel/tree/main/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentkernel"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["integration: requires running agentkernel server"]

agentkernel_sdk-0.7.1/src/agentkernel/__init__.py

@@ -0,0 +1,51 @@
+"""agentkernel SDK — run AI coding agents in secure, isolated microVMs."""
+
+from .async_client import AsyncAgentKernel, AsyncSandboxSession
+from .client import AgentKernel, SandboxSession
+from .errors import (
+    AgentKernelError,
+    AuthError,
+    NetworkError,
+    NotFoundError,
+    ServerError,
+    StreamError,
+    ValidationError,
+)
+from .types import (
+    BatchCommand,
+    BatchResult,
+    BatchRunResponse,
+    CreateSandboxOptions,
+    FileReadResponse,
+    RunOptions,
+    RunOutput,
+    SandboxInfo,
+    SecurityProfile,
+    StreamEvent,
+    StreamEventType,
+)
+
+__all__ = [
+    "AgentKernel",
+    "AsyncAgentKernel",
+    "SandboxSession",
+    "AsyncSandboxSession",
+    "AgentKernelError",
+    "AuthError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+    "NetworkError",
+    "StreamError",
+    "BatchCommand",
+    "BatchResult",
+    "BatchRunResponse",
+    "CreateSandboxOptions",
+    "FileReadResponse",
+    "RunOptions",
+    "RunOutput",
+    "SandboxInfo",
+    "SecurityProfile",
+    "StreamEvent",
+    "StreamEventType",
+]

agentkernel_sdk-0.7.1/src/agentkernel/_config.py

@@ -0,0 +1,29 @@
+"""Configuration resolution for the agentkernel SDK."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "http://localhost:18888"
+DEFAULT_TIMEOUT = 30.0
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: str
+    api_key: str | None
+    timeout: float
+
+
+def resolve_config(
+    base_url: str | None = None,
+    api_key: str | None = None,
+    timeout: float | None = None,
+) -> Config:
+    """Resolve config from constructor args > env vars > defaults."""
+    return Config(
+        base_url=(base_url or os.environ.get("AGENTKERNEL_BASE_URL") or DEFAULT_BASE_URL).rstrip("/"),
+        api_key=api_key or os.environ.get("AGENTKERNEL_API_KEY"),
+        timeout=timeout if timeout is not None else DEFAULT_TIMEOUT,
+    )

agentkernel_sdk-0.7.1/src/agentkernel/async_client.py

@@ -0,0 +1,255 @@
+"""Asynchronous client for the agentkernel HTTP API."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._config import resolve_config
+from .errors import AgentKernelError, NetworkError, error_from_status
+from .types import (
+    BatchRunResponse,
+    CreateSandboxOptions,
+    FileReadResponse,
+    RunOptions,
+    RunOutput,
+    SandboxInfo,
+    SecurityProfile,
+    StreamEvent,
+)
+
+SDK_VERSION = "0.4.0"
+
+
+class AsyncSandboxSession:
+    """An async sandbox session with auto-cleanup on context manager exit."""
+
+    def __init__(self, name: str, client: AsyncAgentKernel) -> None:
+        self.name = name
+        self._client = client
+        self._removed = False
+
+    async def run(self, command: list[str]) -> RunOutput:
+        """Run a command in this sandbox."""
+        return await self._client.exec_in_sandbox(self.name, command)
+
+    async def info(self) -> SandboxInfo:
+        """Get sandbox info."""
+        return await self._client.get_sandbox(self.name)
+
+    async def remove(self) -> None:
+        """Remove the sandbox. Idempotent."""
+        if self._removed:
+            return
+        self._removed = True
+        await self._client.remove_sandbox(self.name)
+
+    async def __aenter__(self) -> AsyncSandboxSession:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.remove()
+
+
+class AsyncAgentKernel:
+    """Asynchronous client for the agentkernel HTTP API.
+
+    Example::
+
+        async with AsyncAgentKernel() as client:
+            result = await client.run(["echo", "hello"])
+            print(result.output)
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        config = resolve_config(base_url, api_key, timeout)
+        headers: dict[str, str] = {"User-Agent": f"agentkernel-python-sdk/{SDK_VERSION}"}
+        if config.api_key:
+            headers["Authorization"] = f"Bearer {config.api_key}"
+        self._http = httpx.AsyncClient(
+            base_url=config.base_url,
+            headers=headers,
+            timeout=config.timeout,
+        )
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncAgentKernel:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    # -- API methods --
+
+    async def health(self) -> str:
+        """Health check. Returns 'ok'."""
+        return await self._request("GET", "/health")
+
+    async def run(
+        self,
+        command: list[str],
+        *,
+        image: str | None = None,
+        profile: SecurityProfile | None = None,
+        fast: bool = True,
+    ) -> RunOutput:
+        """Run a command in a temporary sandbox."""
+        data = await self._request(
+            "POST",
+            "/run",
+            json={"command": command, "image": image, "profile": profile, "fast": fast},
+        )
+        return RunOutput(**data)
+
+    async def run_stream(
+        self,
+        command: list[str],
+        *,
+        image: str | None = None,
+        profile: SecurityProfile | None = None,
+        fast: bool = True,
+    ) -> AsyncIterator[StreamEvent]:
+        """Run a command with SSE streaming output."""
+        from .sse import iter_sse_async
+
+        response = await self._http.send(
+            self._http.build_request(
+                "POST",
+                "/run/stream",
+                json={"command": command, "image": image, "profile": profile, "fast": fast},
+            ),
+            stream=True,
+        )
+        if response.status_code >= 400:
+            await response.aread()
+            raise error_from_status(response.status_code, response.text)
+        return iter_sse_async(response)
+
+    async def list_sandboxes(self) -> list[SandboxInfo]:
+        """List all sandboxes."""
+        data = await self._request("GET", "/sandboxes")
+        return [SandboxInfo(**s) for s in data]
+
+    async def create_sandbox(
+        self,
+        name: str,
+        *,
+        image: str | None = None,
+        vcpus: int | None = None,
+        memory_mb: int | None = None,
+        profile: SecurityProfile | None = None,
+    ) -> SandboxInfo:
+        """Create a new sandbox."""
+        data = await self._request(
+            "POST",
+            "/sandboxes",
+            json={"name": name, "image": image, "vcpus": vcpus, "memory_mb": memory_mb, "profile": profile},
+        )
+        return SandboxInfo(**data)
+
+    async def get_sandbox(self, name: str) -> SandboxInfo:
+        """Get info about a sandbox."""
+        data = await self._request("GET", f"/sandboxes/{name}")
+        return SandboxInfo(**data)
+
+    async def remove_sandbox(self, name: str) -> None:
+        """Remove a sandbox."""
+        await self._request("DELETE", f"/sandboxes/{name}")
+
+    async def exec_in_sandbox(self, name: str, command: list[str]) -> RunOutput:
+        """Run a command in an existing sandbox."""
+        data = await self._request("POST", f"/sandboxes/{name}/exec", json={"command": command})
+        return RunOutput(**data)
+
+    async def read_file(self, name: str, path: str) -> FileReadResponse:
+        """Read a file from a sandbox."""
+        data = await self._request("GET", f"/sandboxes/{name}/files/{path}")
+        return FileReadResponse(**data)
+
+    async def write_file(
+        self,
+        name: str,
+        path: str,
+        content: str,
+        *,
+        encoding: str = "utf8",
+    ) -> str:
+        """Write a file to a sandbox."""
+        return await self._request(
+            "PUT",
+            f"/sandboxes/{name}/files/{path}",
+            json={"content": content, "encoding": encoding},
+        )
+
+    async def delete_file(self, name: str, path: str) -> str:
+        """Delete a file from a sandbox."""
+        return await self._request("DELETE", f"/sandboxes/{name}/files/{path}")
+
+    async def get_sandbox_logs(self, name: str) -> list[dict]:
+        """Get audit log entries for a sandbox."""
+        return await self._request("GET", f"/sandboxes/{name}/logs")
+
+    async def batch_run(self, commands: list[list[str]]) -> BatchRunResponse:
+        """Run multiple commands in parallel."""
+        batch_commands = [{"command": cmd} for cmd in commands]
+        data = await self._request("POST", "/batch/run", json={"commands": batch_commands})
+        return BatchRunResponse(**data)
+
+    async def sandbox(
+        self,
+        name: str,
+        *,
+        image: str | None = None,
+        vcpus: int | None = None,
+        memory_mb: int | None = None,
+        profile: SecurityProfile | None = None,
+    ) -> AsyncSandboxSession:
+        """Create a sandbox session with automatic cleanup.
+
+        Example::
+
+            async with await client.sandbox("test") as sb:
+                await sb.run(["echo", "hello"])
+            # sandbox auto-removed
+        """
+        await self.create_sandbox(name, image=image, vcpus=vcpus, memory_mb=memory_mb, profile=profile)
+        return AsyncSandboxSession(name, self)
+
+    # -- Internal --
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = await self._http.request(method, path, **kwargs)
+        except httpx.ConnectError as e:
+            raise NetworkError(f"Failed to connect: {e}") from e
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}") from e
+
+        if response.status_code >= 400:
+            raise error_from_status(response.status_code, response.text)
+
+        data = response.json()
+        if not data.get("success"):
+            raise AgentKernelError(data.get("error", "Unknown error"))
+        return data.get("data")

agentkernel_sdk-0.7.1/src/agentkernel/client.py

@@ -0,0 +1,241 @@
+"""Synchronous client for the agentkernel HTTP API."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from ._config import resolve_config
+from .errors import AgentKernelError, NetworkError, error_from_status
+from .types import (
+    BatchRunResponse,
+    CreateSandboxOptions,
+    FileReadResponse,
+    RunOptions,
+    RunOutput,
+    SandboxInfo,
+    SecurityProfile,
+    StreamEvent,
+)
+
+SDK_VERSION = "0.4.0"
+
+
+class SandboxSession:
+    """A sandbox session with auto-cleanup on context manager exit."""
+
+    def __init__(self, name: str, client: AgentKernel) -> None:
+        self.name = name
+        self._client = client
+        self._removed = False
+
+    def run(self, command: list[str]) -> RunOutput:
+        """Run a command in this sandbox."""
+        return self._client.exec_in_sandbox(self.name, command)
+
+    def info(self) -> SandboxInfo:
+        """Get sandbox info."""
+        return self._client.get_sandbox(self.name)
+
+    def remove(self) -> None:
+        """Remove the sandbox. Idempotent."""
+        if self._removed:
+            return
+        self._removed = True
+        self._client.remove_sandbox(self.name)
+
+    def __enter__(self) -> SandboxSession:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.remove()
+
+
+class AgentKernel:
+    """Synchronous client for the agentkernel HTTP API.
+
+    Example::
+
+        with AgentKernel() as client:
+            result = client.run(["echo", "hello"])
+            print(result.output)
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        config = resolve_config(base_url, api_key, timeout)
+        headers: dict[str, str] = {"User-Agent": f"agentkernel-python-sdk/{SDK_VERSION}"}
+        if config.api_key:
+            headers["Authorization"] = f"Bearer {config.api_key}"
+        self._http = httpx.Client(
+            base_url=config.base_url,
+            headers=headers,
+            timeout=config.timeout,
+        )
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> AgentKernel:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # -- API methods --
+
+    def health(self) -> str:
+        """Health check. Returns 'ok'."""
+        return self._request("GET", "/health")
+
+    def run(
+        self,
+        command: list[str],
+        *,
+        image: str | None = None,
+        profile: SecurityProfile | None = None,
+        fast: bool = True,
+    ) -> RunOutput:
+        """Run a command in a temporary sandbox."""
+        data = self._request(
+            "POST",
+            "/run",
+            json={"command": command, "image": image, "profile": profile, "fast": fast},
+        )
+        return RunOutput(**data)
+
+    def run_stream(
+        self,
+        command: list[str],
+        *,
+        image: str | None = None,
+        profile: SecurityProfile | None = None,
+        fast: bool = True,
+    ) -> Iterator[StreamEvent]:
+        """Run a command with SSE streaming output."""
+        from .sse import iter_sse_sync
+
+        with self._http.stream(
+            "POST",
+            "/run/stream",
+            json={"command": command, "image": image, "profile": profile, "fast": fast},
+        ) as response:
+            if response.status_code >= 400:
+                response.read()
+                raise error_from_status(response.status_code, response.text)
+            yield from iter_sse_sync(response)
+
+    def list_sandboxes(self) -> list[SandboxInfo]:
+        """List all sandboxes."""
+        data = self._request("GET", "/sandboxes")
+        return [SandboxInfo(**s) for s in data]
+
+    def create_sandbox(
+        self,
+        name: str,
+        *,
+        image: str | None = None,
+        vcpus: int | None = None,
+        memory_mb: int | None = None,
+        profile: SecurityProfile | None = None,
+    ) -> SandboxInfo:
+        """Create a new sandbox."""
+        data = self._request(
+            "POST",
+            "/sandboxes",
+            json={"name": name, "image": image, "vcpus": vcpus, "memory_mb": memory_mb, "profile": profile},
+        )
+        return SandboxInfo(**data)
+
+    def get_sandbox(self, name: str) -> SandboxInfo:
+        """Get info about a sandbox."""
+        data = self._request("GET", f"/sandboxes/{name}")
+        return SandboxInfo(**data)
+
+    def remove_sandbox(self, name: str) -> None:
+        """Remove a sandbox."""
+        self._request("DELETE", f"/sandboxes/{name}")
+
+    def exec_in_sandbox(self, name: str, command: list[str]) -> RunOutput:
+        """Run a command in an existing sandbox."""
+        data = self._request("POST", f"/sandboxes/{name}/exec", json={"command": command})
+        return RunOutput(**data)
+
+    def read_file(self, name: str, path: str) -> FileReadResponse:
+        """Read a file from a sandbox."""
+        data = self._request("GET", f"/sandboxes/{name}/files/{path}")
+        return FileReadResponse(**data)
+
+    def write_file(
+        self,
+        name: str,
+        path: str,
+        content: str,
+        *,
+        encoding: str = "utf8",
+    ) -> str:
+        """Write a file to a sandbox."""
+        return self._request(
+            "PUT",
+            f"/sandboxes/{name}/files/{path}",
+            json={"content": content, "encoding": encoding},
+        )
+
+    def delete_file(self, name: str, path: str) -> str:
+        """Delete a file from a sandbox."""
+        return self._request("DELETE", f"/sandboxes/{name}/files/{path}")
+
+    def get_sandbox_logs(self, name: str) -> list[dict]:
+        """Get audit log entries for a sandbox."""
+        return self._request("GET", f"/sandboxes/{name}/logs")
+
+    def batch_run(self, commands: list[list[str]]) -> BatchRunResponse:
+        """Run multiple commands in parallel."""
+        batch_commands = [{"command": cmd} for cmd in commands]
+        data = self._request("POST", "/batch/run", json={"commands": batch_commands})
+        return BatchRunResponse(**data)
+
+    def sandbox(
+        self,
+        name: str,
+        *,
+        image: str | None = None,
+        vcpus: int | None = None,
+        memory_mb: int | None = None,
+        profile: SecurityProfile | None = None,
+    ) -> SandboxSession:
+        """Create a sandbox session with automatic cleanup.
+
+        Example::
+
+            with client.sandbox("test", image="python:3.12-alpine") as sb:
+                sb.run(["pip", "install", "numpy"])
+            # sandbox auto-removed
+        """
+        self.create_sandbox(name, image=image, vcpus=vcpus, memory_mb=memory_mb, profile=profile)
+        return SandboxSession(name, self)
+
+    # -- Internal --
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            response = self._http.request(method, path, **kwargs)
+        except httpx.ConnectError as e:
+            raise NetworkError(f"Failed to connect: {e}") from e
+        except httpx.TimeoutException as e:
+            raise NetworkError(f"Request timed out: {e}") from e
+
+        if response.status_code >= 400:
+            raise error_from_status(response.status_code, response.text)
+
+        data = response.json()
+        if not data.get("success"):
+            raise AgentKernelError(data.get("error", "Unknown error"))
+        return data.get("data")

agentkernel_sdk-0.7.1/src/agentkernel/errors.py

@@ -0,0 +1,54 @@
+"""Exception hierarchy for the agentkernel SDK."""
+
+from __future__ import annotations
+
+
+class AgentKernelError(Exception):
+    """Base error for all agentkernel SDK errors."""
+
+
+class AuthError(AgentKernelError):
+    """401 Unauthorized."""
+
+    status = 401
+
+
+class NotFoundError(AgentKernelError):
+    """404 Not Found."""
+
+    status = 404
+
+
+class ValidationError(AgentKernelError):
+    """400 Bad Request."""
+
+    status = 400
+
+
+class ServerError(AgentKernelError):
+    """500 Internal Server Error."""
+
+    status = 500
+
+
+class NetworkError(AgentKernelError):
+    """Network / connection error."""
+
+
+class StreamError(AgentKernelError):
+    """SSE streaming error."""
+
+
+def error_from_status(status: int, body: str) -> AgentKernelError:
+    """Map an HTTP status code + body to the appropriate error."""
+    import json
+
+    try:
+        parsed = json.loads(body)
+        message = parsed.get("error", body)
+    except (json.JSONDecodeError, TypeError):
+        message = body
+
+    errors = {400: ValidationError, 401: AuthError, 404: NotFoundError}
+    cls = errors.get(status, ServerError)
+    return cls(message)

agentkernel_sdk-0.7.1/src/agentkernel/sse.py

@@ -0,0 +1,49 @@
+"""SSE stream parsing for the agentkernel SDK."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator
+from typing import TYPE_CHECKING
+
+import httpx
+import httpx_sse
+
+from .types import StreamEvent
+
+if TYPE_CHECKING:
+    pass
+
+KNOWN_EVENTS = frozenset({"started", "progress", "output", "done", "error"})
+
+
+def iter_sse_sync(response: httpx.Response) -> Iterator[StreamEvent]:
+    """Parse SSE events from a sync httpx response."""
+    with httpx_sse.connect_sse(response.stream) as event_source:  # type: ignore[arg-type]
+        for sse in event_source.iter_sse():
+            if sse.event not in KNOWN_EVENTS:
+                continue
+            try:
+                data = json.loads(sse.data)
+            except (json.JSONDecodeError, TypeError):
+                data = {"raw": sse.data}
+            event = StreamEvent(type=sse.event, data=data)  # type: ignore[arg-type]
+            yield event
+            if event.type in ("done", "error"):
+                return
+
+
+async def iter_sse_async(response: httpx.Response) -> AsyncIterator[StreamEvent]:
+    """Parse SSE events from an async httpx response."""
+    async with httpx_sse.aconnect_sse(response.stream) as event_source:  # type: ignore[arg-type]
+        async for sse in event_source.aiter_sse():
+            if sse.event not in KNOWN_EVENTS:
+                continue
+            try:
+                data = json.loads(sse.data)
+            except (json.JSONDecodeError, TypeError):
+                data = {"raw": sse.data}
+            event = StreamEvent(type=sse.event, data=data)  # type: ignore[arg-type]
+            yield event
+            if event.type in ("done", "error"):
+                return

agentkernel_sdk-0.7.1/src/agentkernel/types.py

@@ -0,0 +1,81 @@
+"""Type definitions for the agentkernel SDK."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+SecurityProfile = Literal["permissive", "moderate", "restrictive"]
+SandboxStatus = Literal["running", "stopped"]
+StreamEventType = Literal["started", "progress", "output", "done", "error"]
+
+
+class RunOutput(BaseModel):
+    """Output from a command execution."""
+
+    output: str
+
+
+class SandboxInfo(BaseModel):
+    """Information about a sandbox."""
+
+    name: str
+    status: SandboxStatus
+    backend: str
+    image: str | None = None
+    vcpus: int | None = None
+    memory_mb: int | None = None
+    created_at: str | None = None
+
+
+class RunOptions(BaseModel):
+    """Options for the run command."""
+
+    image: str | None = None
+    profile: SecurityProfile | None = None
+    fast: bool = True
+
+
+class CreateSandboxOptions(BaseModel):
+    """Options for creating a sandbox."""
+
+    image: str | None = None
+    vcpus: int | None = None
+    memory_mb: int | None = None
+    profile: SecurityProfile | None = None
+
+
+class StreamEvent(BaseModel):
+    """SSE stream event."""
+
+    type: StreamEventType
+    data: dict
+
+
+class FileReadResponse(BaseModel):
+    """Response from reading a file."""
+
+    content: str
+    encoding: str
+    size: int
+
+
+class BatchCommand(BaseModel):
+    """A command for batch execution."""
+
+    command: list[str]
+
+
+class BatchResult(BaseModel):
+    """Result of a single batch command."""
+
+    output: str | None = None
+    error: str | None = None
+
+
+class BatchRunResponse(BaseModel):
+    """Response from batch execution."""
+
+    results: list[BatchResult]

agentkernel_sdk-0.7.1/tests/test_async_client.py

@@ -0,0 +1,64 @@
+"""Tests for the asynchronous AsyncAgentKernel client."""
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from agentkernel import AsyncAgentKernel, NotFoundError, RunOutput, SandboxInfo
+
+BASE_URL = "http://localhost:9999"
+
+
+def make_client(**kwargs) -> AsyncAgentKernel:
+    return AsyncAgentKernel(base_url=BASE_URL, **kwargs)
+
+
+class TestAsyncHealth:
+    async def test_returns_ok(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": "ok"})
+        async with make_client() as client:
+            assert await client.health() == "ok"
+
+
+class TestAsyncRun:
+    async def test_returns_output(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": {"output": "hello\n"}})
+        async with make_client() as client:
+            result = await client.run(["echo", "hello"])
+            assert isinstance(result, RunOutput)
+            assert result.output == "hello\n"
+
+
+class TestAsyncListSandboxes:
+    async def test_returns_list(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(
+            json={
+                "success": True,
+                "data": [{"name": "sb-1", "status": "running", "backend": "docker"}],
+            }
+        )
+        async with make_client() as client:
+            result = await client.list_sandboxes()
+            assert len(result) == 1
+            assert isinstance(result[0], SandboxInfo)
+
+
+class TestAsyncGetSandbox:
+    async def test_not_found(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(status_code=404, json={"success": False, "error": "Not found"})
+        async with make_client() as client:
+            with pytest.raises(NotFoundError):
+                await client.get_sandbox("missing")
+
+
+class TestAsyncSandboxSession:
+    async def test_auto_removes(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(
+            json={"success": True, "data": {"name": "sess", "status": "running", "backend": "docker"}}
+        )
+        httpx_mock.add_response(json={"success": True, "data": "Sandbox removed"})
+
+        async with make_client() as client:
+            async with await client.sandbox("sess") as sb:
+                assert sb.name == "sess"
+        requests = httpx_mock.get_requests()
+        assert requests[-1].method == "DELETE"

agentkernel_sdk-0.7.1/tests/test_client.py

@@ -0,0 +1,171 @@
+"""Tests for the synchronous AgentKernel client."""
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from agentkernel import (
+    AgentKernel,
+    AuthError,
+    NotFoundError,
+    RunOutput,
+    SandboxInfo,
+    ServerError,
+    ValidationError,
+)
+
+BASE_URL = "http://localhost:9999"
+
+
+def make_client(**kwargs) -> AgentKernel:
+    return AgentKernel(base_url=BASE_URL, **kwargs)
+
+
+class TestHealth:
+    def test_returns_ok(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": "ok"})
+        assert make_client().health() == "ok"
+
+
+class TestRun:
+    def test_returns_output(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": {"output": "hello\n"}})
+        result = make_client().run(["echo", "hello"])
+        assert isinstance(result, RunOutput)
+        assert result.output == "hello\n"
+
+    def test_passes_options(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": {"output": "ok\n"}})
+        make_client().run(
+            ["python3", "-c", "print('ok')"],
+            image="python:3.12-alpine",
+            profile="restrictive",
+            fast=False,
+        )
+        request = httpx_mock.get_request()
+        assert request is not None
+        import json
+
+        body = json.loads(request.content)
+        assert body["image"] == "python:3.12-alpine"
+        assert body["profile"] == "restrictive"
+        assert body["fast"] is False
+
+
+class TestListSandboxes:
+    def test_returns_list(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(
+            json={
+                "success": True,
+                "data": [
+                    {"name": "sb-1", "status": "running", "backend": "docker"},
+                    {"name": "sb-2", "status": "stopped", "backend": "docker"},
+                ],
+            }
+        )
+        result = make_client().list_sandboxes()
+        assert len(result) == 2
+        assert all(isinstance(s, SandboxInfo) for s in result)
+        assert result[0].name == "sb-1"
+
+
+class TestCreateSandbox:
+    def test_creates(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(
+            status_code=201,
+            json={"success": True, "data": {"name": "new", "status": "running", "backend": "docker"}},
+        )
+        result = make_client().create_sandbox("new")
+        assert result.name == "new"
+        assert result.status == "running"
+
+
+class TestGetSandbox:
+    def test_returns_info(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(
+            json={"success": True, "data": {"name": "test", "status": "running", "backend": "docker"}}
+        )
+        result = make_client().get_sandbox("test")
+        assert result.name == "test"
+
+    def test_not_found(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(status_code=404, json={"success": False, "error": "Not found"})
+        with pytest.raises(NotFoundError):
+            make_client().get_sandbox("missing")
+
+
+class TestRemoveSandbox:
+    def test_removes(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": "Sandbox removed"})
+        make_client().remove_sandbox("test")  # no exception
+
+
+class TestExecInSandbox:
+    def test_returns_output(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": {"output": "result\n"}})
+        result = make_client().exec_in_sandbox("test", ["echo", "result"])
+        assert result.output == "result\n"
+
+
+class TestSandboxSession:
+    def test_auto_removes(self, httpx_mock: HTTPXMock) -> None:
+        # create
+        httpx_mock.add_response(
+            json={"success": True, "data": {"name": "sess", "status": "running", "backend": "docker"}}
+        )
+        # remove
+        httpx_mock.add_response(json={"success": True, "data": "Sandbox removed"})
+
+        client = make_client()
+        with client.sandbox("sess") as sb:
+            assert sb.name == "sess"
+        # remove was called
+        requests = httpx_mock.get_requests()
+        assert requests[-1].method == "DELETE"
+
+    def test_remove_is_idempotent(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(
+            json={"success": True, "data": {"name": "idem", "status": "running", "backend": "docker"}}
+        )
+        httpx_mock.add_response(json={"success": True, "data": "Sandbox removed"})
+
+        client = make_client()
+        sb = client.sandbox("idem")
+        sb.remove()
+        sb.remove()  # second call is a no-op
+        delete_requests = [r for r in httpx_mock.get_requests() if r.method == "DELETE"]
+        assert len(delete_requests) == 1
+
+
+class TestAuth:
+    def test_sends_bearer_token(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": "ok"})
+        make_client(api_key="sk-test").health()
+        request = httpx_mock.get_request()
+        assert request is not None
+        assert request.headers["authorization"] == "Bearer sk-test"
+
+
+class TestErrors:
+    def test_401(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(status_code=401, json={"success": False, "error": "Unauthorized"})
+        with pytest.raises(AuthError):
+            make_client().health()
+
+    def test_400(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(status_code=400, json={"success": False, "error": "Bad request"})
+        with pytest.raises(ValidationError):
+            make_client().run([])
+
+    def test_500(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(status_code=500, json={"success": False, "error": "Internal error"})
+        with pytest.raises(ServerError):
+            make_client().health()
+
+
+class TestUserAgent:
+    def test_sends_user_agent(self, httpx_mock: HTTPXMock) -> None:
+        httpx_mock.add_response(json={"success": True, "data": "ok"})
+        make_client().health()
+        request = httpx_mock.get_request()
+        assert request is not None
+        assert request.headers["user-agent"].startswith("agentkernel-python-sdk/")