loopix-sdk 2.30.0__py3-none-any.whl

loopix/__init__.py

@@ -0,0 +1,260 @@
+"""
+Secure sandboxed cloud environments made for AI agents and AI apps.
+
+Check docs [here](https://vm.betmandu.net/docs).
+
+Loopix Sandbox is a secure cloud sandbox environment made for AI agents and AI
+apps.
+Sandboxes allow AI agents and apps to have long running cloud secure environments.
+In these environments, large language models can use the same tools as humans do.
+
+Loopix Python SDK supports both sync and async API:
+
+```py
+from loopix import Sandbox
+
+# Create sandbox
+sandbox = Sandbox.create()
+```
+
+```py
+from loopix import AsyncSandbox
+
+# Create sandbox
+sandbox = await AsyncSandbox.create()
+```
+"""
+
+from .api import (
+    ApiClient,
+    client,
+)
+from .connection_config import (
+    ApiParams,
+    ConnectionConfig,
+    ProxyTypes,
+    Username,
+)
+from .volume.connection_config import VolumeApiParams, VolumeConnectionConfig
+from .exceptions import (
+    AuthenticationException,
+    FileNotFoundException,
+    GitAuthException,
+    GitUpstreamException,
+    BuildException,
+    FileUploadException,
+    InvalidArgumentException,
+    NotEnoughSpaceException,
+    NotFoundException,
+    RateLimitException,
+    SandboxException,
+    SandboxNotFoundException,
+    TemplateException,
+    TimeoutException,
+    VolumeException,
+)
+from .sandbox.commands.command_handle import (
+    CommandExitException,
+    CommandResult,
+    PtyOutput,
+    PtySize,
+    Stderr,
+    Stdout,
+)
+from .sandbox.commands.main import ProcessInfo
+from .sandbox.filesystem.filesystem import EntryInfo, FileType, WriteInfo
+from .sandbox.filesystem.watch_handle import (
+    FilesystemEvent,
+    FilesystemEventType,
+)
+from .sandbox._git import GitBranches, GitFileStatus, GitResetMode, GitStatus
+from .sandbox_sync.git import Git
+from .sandbox.network import ALL_TRAFFIC
+from .sandbox.signature import get_signature
+from .sandbox.sandbox_api import (
+    GitHubMcpServer,
+    GitHubMcpServerConfig,
+    McpServer,
+    SandboxInfo,
+    SandboxInfoLifecycle,
+    SandboxMetrics,
+    SandboxLifecycle,
+    SandboxOnTimeout,
+    SandboxNetworkInfo,
+    SandboxNetworkOpts,
+    SandboxNetworkRule,
+    SandboxNetworkRuleInfo,
+    SandboxNetworkRules,
+    SandboxNetworkSelector,
+    SandboxNetworkSelectorContext,
+    SandboxNetworkTransform,
+    SandboxNetworkUpdate,
+    SandboxQuery,
+    SandboxState,
+    SnapshotInfo,
+)
+from .sandbox_async.commands.command_handle import AsyncCommandHandle
+from .sandbox_async.filesystem.watch_handle import AsyncWatchHandle
+from .sandbox_async.main import AsyncSandbox
+from .sandbox_async.paginator import AsyncSandboxPaginator, AsyncSnapshotPaginator
+from .sandbox_async.utils import OutputHandler
+from .sandbox_sync.commands.command_handle import CommandHandle
+from .sandbox_sync.filesystem.watch_handle import WatchHandle
+from .sandbox_sync.main import Sandbox
+from .sandbox_sync.paginator import SandboxPaginator, SnapshotPaginator
+from .template.logger import (
+    LogEntry,
+    LogEntryEnd,
+    LogEntryLevel,
+    LogEntryStart,
+    default_build_logger,
+)
+from .template.main import TemplateBase, TemplateClass
+from .template.readycmd import (
+    ReadyCmd,
+    wait_for_file,
+    wait_for_port,
+    wait_for_process,
+    wait_for_timeout,
+    wait_for_url,
+)
+from .template.types import (
+    BuildInfo,
+    BuildStatusReason,
+    CopyItem,
+    TemplateBuildStatus,
+    TemplateBuildStatusResponse,
+    TemplateTag,
+    TemplateTagInfo,
+)
+from .template_async.main import AsyncTemplate
+from .template_sync.main import Template
+
+from .volume.volume_sync import Volume
+from .volume.volume_async import AsyncVolume
+from .volume.types import (
+    VolumeInfo,
+    VolumeAndToken,
+    VolumeEntryStat,
+    VolumeFileType,
+)
+
+__all__ = [
+    # API
+    "ApiClient",
+    "client",
+    # Connection config
+    "ConnectionConfig",
+    "VolumeConnectionConfig",
+    "ProxyTypes",
+    "ApiParams",
+    "VolumeApiParams",
+    "Username",
+    # Exceptions
+    "SandboxException",
+    "TimeoutException",
+    "NotFoundException",
+    "FileNotFoundException",
+    "SandboxNotFoundException",
+    "AuthenticationException",
+    "GitAuthException",
+    "GitUpstreamException",
+    "InvalidArgumentException",
+    "NotEnoughSpaceException",
+    "TemplateException",
+    "BuildException",
+    "FileUploadException",
+    "RateLimitException",
+    "VolumeException",
+    # Sandbox API
+    "SandboxInfo",
+    "SandboxInfoLifecycle",
+    "SandboxMetrics",
+    "ProcessInfo",
+    "SandboxQuery",
+    "SandboxState",
+    "SandboxMetrics",
+    "GitStatus",
+    "GitBranches",
+    "GitFileStatus",
+    "GitResetMode",
+    # Command handle
+    "CommandResult",
+    "Stderr",
+    "Stdout",
+    "CommandExitException",
+    "PtyOutput",
+    "PtySize",
+    # Filesystem
+    "FilesystemEvent",
+    "FilesystemEventType",
+    "EntryInfo",
+    "WriteInfo",
+    "FileType",
+    # Network
+    "SandboxNetworkOpts",
+    "SandboxNetworkInfo",
+    "SandboxNetworkSelector",
+    "SandboxNetworkSelectorContext",
+    "SandboxNetworkRule",
+    "SandboxNetworkRuleInfo",
+    "SandboxNetworkRules",
+    "SandboxNetworkTransform",
+    "SandboxNetworkUpdate",
+    "SandboxLifecycle",
+    "SandboxOnTimeout",
+    "ALL_TRAFFIC",
+    # Snapshot
+    "SnapshotInfo",
+    "SnapshotPaginator",
+    "AsyncSnapshotPaginator",
+    # Signature
+    "get_signature",
+    # Sync sandbox
+    "Sandbox",
+    "SandboxPaginator",
+    "WatchHandle",
+    "CommandHandle",
+    # Async sandbox
+    "OutputHandler",
+    "AsyncSandboxPaginator",
+    "AsyncSandbox",
+    "AsyncWatchHandle",
+    "AsyncCommandHandle",
+    # Template
+    "Template",
+    "AsyncTemplate",
+    "TemplateBase",
+    "TemplateClass",
+    "CopyItem",
+    "BuildInfo",
+    "BuildStatusReason",
+    "TemplateBuildStatus",
+    "TemplateBuildStatusResponse",
+    "TemplateTag",
+    "TemplateTagInfo",
+    "ReadyCmd",
+    "wait_for_file",
+    "wait_for_url",
+    "wait_for_port",
+    "wait_for_process",
+    "wait_for_timeout",
+    "LogEntry",
+    "LogEntryStart",
+    "LogEntryEnd",
+    "LogEntryLevel",
+    "default_build_logger",
+    # MCP
+    "McpServer",
+    "GitHubMcpServer",
+    "GitHubMcpServerConfig",
+    # Git
+    "Git",
+    # Volume
+    "Volume",
+    "AsyncVolume",
+    "VolumeInfo",
+    "VolumeAndToken",
+    "VolumeEntryStat",
+    "VolumeFileType",
+]

loopix/api/__init__.py

@@ -0,0 +1,287 @@
+import asyncio
+import json
+import logging
+import os
+import re
+import threading
+import weakref
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Callable, Optional, Protocol, Union
+
+import httpx
+from httpx import AsyncBaseTransport, BaseTransport, Limits, Timeout
+
+from loopix.api.client.client import AuthenticatedClient
+from loopix.api.client.types import Response
+from loopix.api.metadata import default_headers
+from loopix.connection_config import ConnectionConfig
+from loopix.exceptions import (
+    AuthenticationException,
+    RateLimitException,
+    SandboxException,
+)
+
+
+def make_logging_event_hooks(log: Optional[logging.Logger]) -> dict:
+    """Build synchronous httpx ``event_hooks`` that log requests and responses
+    to the given ``logging.Logger``. Requests log at ``INFO``, successful
+    responses at ``INFO`` and responses with status >= 400 at ``ERROR``.
+
+    Returns no hooks when ``log`` is ``None`` so that nothing is logged unless a
+    logger was explicitly supplied."""
+    if log is None:
+        return {}
+
+    def on_request(request) -> None:
+        log.info(f"Request {request.method} {request.url}")
+
+    def on_response(response: Response) -> None:
+        if response.status_code >= 400:
+            log.error(f"Response {response.status_code}")
+        else:
+            log.info(f"Response {response.status_code}")
+
+    return {"request": [on_request], "response": [on_response]}
+
+
+def make_async_logging_event_hooks(log: Optional[logging.Logger]) -> dict:
+    """Asynchronous counterpart of :func:`make_logging_event_hooks`."""
+    if log is None:
+        return {}
+
+    async def on_request(request) -> None:
+        log.info(f"Request {request.method} {request.url}")
+
+    async def on_response(response: Response) -> None:
+        if response.status_code >= 400:
+            log.error(f"Response {response.status_code}")
+        else:
+            log.info(f"Response {response.status_code}")
+
+    return {"request": [on_request], "response": [on_response]}
+
+
+limits = Limits(
+    max_keepalive_connections=int(os.getenv("LOOPIX_MAX_KEEPALIVE_CONNECTIONS", "20")),
+    max_connections=int(os.getenv("LOOPIX_MAX_CONNECTIONS", "2000")),
+    keepalive_expiry=int(os.getenv("LOOPIX_KEEPALIVE_EXPIRY", "300")),
+)
+
+connection_retries = int(os.getenv("LOOPIX_CONNECTION_RETRIES", "3"))
+
+
+@dataclass
+class SandboxCreateResponse:
+    sandbox_id: str
+    sandbox_domain: Optional[str]
+    envd_version: str
+    envd_access_token: Optional[str]
+    traffic_access_token: Optional[str]
+
+
+def handle_api_exception(
+    e: "SupportsApiErrorResponse",
+    default_exception_class: type[Exception] = SandboxException,
+    stack_trace: Optional[TracebackType] = None,
+):
+    try:
+        body = json.loads(e.content) if e.content else {}
+    except json.JSONDecodeError:
+        body = {}
+
+    if e.status_code == 401:
+        message = f"{e.status_code}: Unauthorized, please check your credentials."
+        if body.get("message"):
+            message += f" - {body['message']}"
+        return AuthenticationException(message)
+
+    if e.status_code == 429:
+        message = f"{e.status_code}: Rate limit exceeded, please try again later."
+        if body.get("message"):
+            message += f" - {body['message']}"
+        return RateLimitException(message)
+
+    if "message" in body:
+        return default_exception_class(
+            f"{e.status_code}: {body['message']}"
+        ).with_traceback(stack_trace)
+    return default_exception_class(f"{e.status_code}: {e.content}").with_traceback(
+        stack_trace
+    )
+
+
+class SupportsApiErrorResponse(Protocol):
+    @property
+    def status_code(self) -> int: ...
+
+    @property
+    def content(self) -> Union[str, bytes]: ...
+
+
+_API_KEY_PATTERN = re.compile(r"\Alpx_[0-9a-f]+\Z")
+_API_KEY_EXAMPLE = "lpx_" + "0" * 40
+
+
+def validate_api_key(api_key: str) -> None:
+    """Validate that an Loopix API key has the expected ``lpx_`` prefix
+    followed by hex characters. Raises ``AuthenticationException`` otherwise.
+    """
+    if not _API_KEY_PATTERN.match(api_key):
+        raise AuthenticationException(
+            'Invalid API key format: expected "lpx_" followed by hex '
+            f'characters (e.g. "{_API_KEY_EXAMPLE}"). '
+            "Visit the API Keys tab at https://vm.betmandu.net/dashboard?tab=keys to get your API key."
+        )
+
+
+class ApiClient(AuthenticatedClient):
+    """
+    The client for interacting with the Loopix API.
+    """
+
+    def __init__(
+        self,
+        config: ConnectionConfig,
+        transport: Optional[Union[BaseTransport, AsyncBaseTransport]] = None,
+        transport_factory: Optional[Callable[[], BaseTransport]] = None,
+        async_transport_factory: Optional[Callable[[], AsyncBaseTransport]] = None,
+        *args,
+        **kwargs,
+    ):
+        if transport is not None and (
+            transport_factory is not None or async_transport_factory is not None
+        ):
+            raise ValueError("Use either transport or transport_factory, not both")
+
+        self._transport_factory = transport_factory
+        self._async_transport_factory = async_transport_factory
+        self._thread_local = threading.local()
+        # Keyed weakly by the event loop object itself, not id(loop) —
+        # CPython reuses object ids, so a new loop could otherwise inherit
+        # a client bound to a previous, closed loop.
+        self._async_clients: weakref.WeakKeyDictionary[
+            asyncio.AbstractEventLoop, httpx.AsyncClient
+        ] = weakref.WeakKeyDictionary()
+        self._proxy = config.proxy
+
+        if config.api_key is None:
+            raise AuthenticationException(
+                "API key is required, please visit the API Keys tab at https://vm.betmandu.net/dashboard?tab=keys to get your API key. "
+                "You can either set the environment variable `LOOPIX_API_KEY` "
+                'or you can pass it directly to the method like api_key="lpx_..."',
+            )
+
+        if config.api_key is not None and config.validate_api_key:
+            validate_api_key(config.api_key)
+
+        token = config.api_key
+        auth_header_name = "X-API-KEY"
+        prefix = ""
+
+        self._logger = config.logger
+
+        headers = {
+            **default_headers,
+            # Deprecated: send the access token alongside the API key when one
+            # is available, mirroring the JS SDK. Prefer `api_headers` instead.
+            # Spread before `config.headers` so a custom `Authorization` in
+            # `api_headers` wins over the deprecated access token, matching JS.
+            **(
+                {"Authorization": f"Bearer {config.access_token}"}
+                if config.access_token is not None
+                else {}
+            ),
+            **(config.headers or {}),
+        }
+
+        # Prevent passing these parameters twice
+        more_headers: Optional[dict] = kwargs.pop("headers", None)
+        if more_headers:
+            headers.update(more_headers)
+        kwargs.pop("token", None)
+        kwargs.pop("auth_header_name", None)
+        kwargs.pop("prefix", None)
+
+        httpx_args = {
+            "event_hooks": self._logging_event_hooks(),
+        }
+        if transport is not None:
+            httpx_args["transport"] = transport
+        if (
+            transport is None
+            and transport_factory is None
+            and async_transport_factory is None
+        ):
+            httpx_args["proxy"] = config.proxy
+
+        # config.request_timeout is None when the timeout is explicitly
+        # disabled (request_timeout=0), which httpx.Timeout(None) preserves.
+        kwargs.setdefault("timeout", Timeout(config.request_timeout))
+
+        super().__init__(
+            base_url=config.api_url,
+            httpx_args=httpx_args,
+            headers=headers,
+            token=token or "",
+            auth_header_name=auth_header_name,
+            prefix=prefix,
+            *args,
+            **kwargs,
+        )
+
+    def _logging_event_hooks(self) -> dict:
+        return make_logging_event_hooks(self._logger)
+
+    def _headers_with_auth(self) -> dict:
+        return {
+            **self._headers,
+            self.auth_header_name: (
+                f"{self.prefix} {self.token}" if self.prefix else self.token
+            ),
+        }
+
+    def get_httpx_client(self) -> httpx.Client:
+        if self._client is not None or self._transport_factory is None:
+            return super().get_httpx_client()
+
+        client = getattr(self._thread_local, "client", None)
+        if client is None:
+            client = httpx.Client(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers_with_auth(),
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                event_hooks=self._httpx_args.get("event_hooks"),
+                transport=self._transport_factory(),
+            )
+            self._thread_local.client = client
+        return client
+
+    def get_async_httpx_client(self) -> httpx.AsyncClient:
+        if self._async_client is not None or self._async_transport_factory is None:
+            return super().get_async_httpx_client()
+
+        loop = asyncio.get_running_loop()
+        client = self._async_clients.get(loop)
+        if client is None:
+            client = httpx.AsyncClient(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers_with_auth(),
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                event_hooks=self._httpx_args.get("event_hooks"),
+                transport=self._async_transport_factory(),
+            )
+            self._async_clients[loop] = client
+        return client
+
+
+# We need to override the logging hooks for the async usage
+class AsyncApiClient(ApiClient):
+    def _logging_event_hooks(self) -> dict:
+        return make_async_logging_event_hooks(self._logger)

loopix/api/client/__init__.py

@@ -0,0 +1,8 @@
+"""A client library for accessing Loopix API"""
+
+from .client import AuthenticatedClient, Client
+
+__all__ = (
+    "AuthenticatedClient",
+    "Client",
+)

loopix/api/client/api/__init__.py

@@ -0,0 +1 @@
+"""Contains methods for accessing the API"""

loopix/api/client/api/sandboxes/__init__.py

@@ -0,0 +1 @@
+"""Contains endpoint functions for accessing the API"""