vswarm 0.1.0__py3-none-any.whl

vswarm/__init__.py

@@ -0,0 +1,136 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from vswarm.client import VSwarmClient
+from vswarm.resources import (
+    ArtifactClient,
+    BrowserClient,
+    BrowserSessionHandle,
+    BrowserSessionManager,
+    EventClient,
+    FileClient,
+    RunClient,
+    SandboxHandle,
+    SandboxManager,
+    TemplateClient,
+    TraceClient,
+    TraceHandle,
+    TraceSession,
+    TraceStep,
+)
+from vswarm.models import (
+    Admission,
+    BrowserAction,
+    BrowserActionResult,
+    BrowserAgentObservation,
+    BrowserCapacity,
+    BrowserClick,
+    BrowserDiagnostics,
+    BrowserElement,
+    BrowserEvidenceCapture,
+    BrowserFill,
+    BrowserNavigate,
+    BrowserObservation,
+    BrowserObserveInclude,
+    BrowserPolicy,
+    BrowserSiteChallenge,
+    BrowserTargetResolution,
+    BrowserTiming,
+    CapacityError,
+    CleanupResult,
+    Metadata,
+    NetworkPolicy,
+    PolicyError,
+    RequestOptions,
+    ResourceLimits,
+    RetryPolicy,
+    RunResult,
+    Timeout,
+    TraceArtifact,
+    TraceEvent,
+    TraceExportArtifact,
+    TraceExportBundle,
+    TraceRun,
+    Viewport,
+)
+from vswarm.errors import (
+    VSwarmAPIError,
+    VSwarmAuthenticationError,
+    VSwarmAuthorizationError,
+    VSwarmCapacityError,
+    VSwarmConflictError,
+    VSwarmNotFoundError,
+    VSwarmPolicyError,
+    VSwarmQuotaError,
+    VSwarmTimeoutError,
+    VSwarmValidationError,
+    VSwarmVersionError,
+)
+
+try:
+    __version__ = version("vswarm")
+except PackageNotFoundError:
+    # Support source-tree imports used by local conformance scripts.
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "__version__",
+    "Admission",
+    "ArtifactClient",
+    "BrowserAction",
+    "BrowserActionResult",
+    "BrowserAgentObservation",
+    "BrowserCapacity",
+    "BrowserClick",
+    "BrowserClient",
+    "BrowserDiagnostics",
+    "BrowserElement",
+    "BrowserEvidenceCapture",
+    "BrowserFill",
+    "BrowserNavigate",
+    "BrowserObservation",
+    "BrowserObserveInclude",
+    "BrowserPolicy",
+    "BrowserSessionHandle",
+    "BrowserSessionManager",
+    "BrowserSiteChallenge",
+    "BrowserTargetResolution",
+    "BrowserTiming",
+    "CapacityError",
+    "CleanupResult",
+    "EventClient",
+    "FileClient",
+    "Metadata",
+    "NetworkPolicy",
+    "PolicyError",
+    "RequestOptions",
+    "ResourceLimits",
+    "RetryPolicy",
+    "RunClient",
+    "RunResult",
+    "SandboxHandle",
+    "SandboxManager",
+    "TemplateClient",
+    "Timeout",
+    "TraceArtifact",
+    "TraceClient",
+    "TraceEvent",
+    "TraceExportArtifact",
+    "TraceExportBundle",
+    "TraceHandle",
+    "TraceRun",
+    "TraceSession",
+    "TraceStep",
+    "VSwarmAPIError",
+    "VSwarmAuthenticationError",
+    "VSwarmAuthorizationError",
+    "VSwarmCapacityError",
+    "VSwarmConflictError",
+    "VSwarmClient",
+    "VSwarmNotFoundError",
+    "VSwarmPolicyError",
+    "VSwarmQuotaError",
+    "VSwarmTimeoutError",
+    "VSwarmValidationError",
+    "VSwarmVersionError",
+    "Viewport",
+]

vswarm/client.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import Any, Mapping
+
+from packaging.version import InvalidVersion, Version
+
+from vswarm.errors import VSwarmVersionError
+from vswarm.models import RequestOptions, to_api
+from vswarm.resources import (
+    ArtifactClient,
+    BrowserClient,
+    EventClient,
+    PreviewAttachmentClient,
+    RunClient,
+    SandboxManager,
+    TemplateClient,
+    TraceClient,
+    WorkspaceManager,
+)
+from vswarm.transport import AsyncTransport, HTTPXTransport, decode_response
+
+
+class VSwarmClient:
+    def __init__(
+        self,
+        *,
+        base_url: str = "http://127.0.0.1:8080",
+        token: str | None = None,
+        project: str | None = None,
+        user: str | None = None,
+        transport: AsyncTransport | None = None,
+        timeout: float = 60.0,
+        connect_timeout: float | None = None,
+        min_api_version: str | None = None,
+        compatibility: str = "off",
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.project = project
+        self.user = user
+        self.timeout = timeout
+        self.connect_timeout = connect_timeout
+        self.min_api_version = min_api_version
+        self.compatibility = compatibility
+        self.transport = transport or HTTPXTransport(timeout=timeout, connect_timeout=connect_timeout)
+        self._trace_context: ContextVar[Any | None] = ContextVar("vswarm_trace_context", default=None)
+        self.templates = TemplateClient(self)
+        self.sandboxes = SandboxManager(self)
+        self.workspaces = WorkspaceManager(self)
+        self.artifacts = ArtifactClient(self)
+        self.browser = BrowserClient(self)
+        self.runs = RunClient(self)
+        self.events = EventClient(self)
+        self.preview_attachments = PreviewAttachmentClient(self)
+        self.traces = TraceClient(self)
+
+    async def close(self) -> None:
+        await self.transport.aclose()
+
+    async def __aenter__(self) -> "VSwarmClient":
+        if self.compatibility == "strict":
+            await self.check_compatibility()
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def health(self) -> dict[str, Any]:
+        return await self._request("GET", "/v1/health")
+
+    async def server_info(self) -> dict[str, Any]:
+        return await self.health()
+
+    async def features(self) -> dict[str, Any]:
+        info = await self.server_info()
+        return dict(info.get("features", {}) if isinstance(info.get("features"), Mapping) else {})
+
+    async def check_compatibility(self) -> dict[str, Any]:
+        info = await self.server_info()
+        if self.min_api_version and info.get("api_version"):
+            current_version = _parse_api_version(str(info["api_version"]), "server")
+            minimum_version = _parse_api_version(self.min_api_version, "minimum")
+            if current_version < minimum_version:
+                raise VSwarmVersionError(
+                    f"VSwarm API version {info['api_version']} is older than required {self.min_api_version}",
+                    payload=info,
+                )
+        return info
+
+    async def browser_capacity(self) -> dict[str, Any]:
+        return await self._request("GET", "/v1/browser/capacity")
+
+    async def capacity(self) -> dict[str, Any]:
+        return await self._request("GET", "/v1/capacity")
+
+    async def reconcile_browser(self) -> dict[str, Any]:
+        return await self._request("POST", "/v1/browser/reconcile", json={})
+
+    def trace(self, **request: Any):
+        return self.traces.session(**request)
+
+    def browser_session(
+        self,
+        *,
+        template: str = "browser-chromium",
+        sandbox: Mapping[str, Any] | None = None,
+        **session: Any,
+    ):
+        return self.browser.session(template=template, sandbox=sandbox, **session)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+        options: RequestOptions | Mapping[str, Any] | None = None,
+    ) -> Any:
+        return await self._request(method, path, json=json, content=content, headers=headers, options=options)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any | None = None,
+        content: bytes | str | None = None,
+        headers: Mapping[str, str] | None = None,
+        trace: Any | None = None,
+        options: RequestOptions | Mapping[str, Any] | None = None,
+    ) -> Any:
+        request_headers = self._headers(headers=headers, options=options, trace=trace)
+        response = await self.transport.request(
+            method,
+            self.base_url + path,
+            headers=request_headers,
+            json=to_api(json),
+            content=content,
+        )
+        return await decode_response(response)
+
+    def _headers(
+        self,
+        *,
+        headers: Mapping[str, str] | None = None,
+        options: RequestOptions | Mapping[str, Any] | None = None,
+        trace: Any | None = None,
+    ) -> dict[str, str]:
+        request_headers: dict[str, str] = {}
+        opts = _request_options(options)
+        if opts.headers:
+            request_headers.update(dict(opts.headers))
+        if headers:
+            request_headers.update(dict(headers))
+        if opts.request_id:
+            request_headers["X-VSwarm-Request-ID"] = opts.request_id
+        if self.token:
+            request_headers["Authorization"] = f"Bearer {self.token}"
+        if self.project:
+            request_headers["X-VSwarm-Project"] = self.project
+        if self.user:
+            request_headers["X-VSwarm-User"] = self.user
+        trace_context = trace or self._trace_context.get()
+        if trace_context is not None and hasattr(trace_context, "headers"):
+            request_headers.update(trace_context.headers())
+        return request_headers
+
+    def _push_trace(self, trace: Any) -> Token:
+        return self._trace_context.set(trace)
+
+    def _pop_trace(self, token: Token) -> None:
+        self._trace_context.reset(token)
+
+
+def _request_options(options: RequestOptions | Mapping[str, Any] | None) -> RequestOptions:
+    if options is None:
+        return RequestOptions()
+    if isinstance(options, RequestOptions):
+        return options
+    return RequestOptions(
+        request_id=options.get("request_id"),
+        headers=options.get("headers"),
+    )
+
+
+def _parse_api_version(value: str, source: str) -> Version:
+    try:
+        return Version(value)
+    except InvalidVersion as exc:
+        raise VSwarmVersionError(f"Invalid {source} VSwarm API version: {value}") from exc

vswarm/errors.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class VSwarmAPIError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        payload: object | None = None,
+        request_id: str | None = None,
+        retry_after_seconds: float | None = None,
+        capacity: object | None = None,
+        resource_id: str | None = None,
+        operation_id: str | None = None,
+        trace_id: str | None = None,
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+        self.request_id = request_id
+        self.trace_id = trace_id
+        self.retry_after_seconds = retry_after_seconds
+        self.capacity = capacity
+        self.resource_id = resource_id
+        self.operation_id = operation_id
+
+
+class VSwarmValidationError(VSwarmAPIError):
+    pass
+
+
+class VSwarmAuthenticationError(VSwarmAPIError):
+    pass
+
+
+class VSwarmAuthorizationError(VSwarmAPIError):
+    pass
+
+
+class VSwarmNotFoundError(VSwarmAPIError):
+    pass
+
+
+class VSwarmCapacityError(VSwarmAPIError):
+    pass
+
+
+class VSwarmQuotaError(VSwarmAPIError):
+    pass
+
+
+class VSwarmPolicyError(VSwarmAPIError):
+    pass
+
+
+class VSwarmTimeoutError(VSwarmAPIError):
+    pass
+
+
+class VSwarmConflictError(VSwarmAPIError):
+    pass
+
+
+class VSwarmVersionError(VSwarmAPIError):
+    pass
+
+
+def payload_field(payload: object, *names: str) -> Any | None:
+    if not isinstance(payload, dict):
+        return None
+    for name in names:
+        value = payload.get(name)
+        if value is not None:
+            return value
+    return None

vswarm/models/__init__.py

@@ -0,0 +1,77 @@
+from vswarm.models.artifacts import ArtifactRef
+from vswarm.models.browser import (
+    BrowserAction,
+    BrowserActionResult,
+    BrowserAgentObservation,
+    BrowserCapacity,
+    BrowserClick,
+    BrowserDiagnostics,
+    BrowserElement,
+    BrowserEvidenceCapture,
+    BrowserFill,
+    BrowserNavigate,
+    BrowserObservation,
+    BrowserObserveInclude,
+    BrowserSiteChallenge,
+    BrowserTargetResolution,
+    BrowserTiming,
+    CapacityError,
+    PolicyError,
+    Viewport,
+)
+from vswarm.models.common import (
+    Admission,
+    CleanupResult,
+    Metadata,
+    NetworkPolicy,
+    RequestOptions,
+    ResourceLimits,
+    RetryPolicy,
+    Timeout,
+    clean_mapping,
+    encode_base64,
+    to_api,
+)
+from vswarm.models.policy import BrowserPolicy
+from vswarm.models.runs import RunResult
+from vswarm.models.traces import TraceArtifact, TraceEvent, TraceExportArtifact, TraceExportBundle, TraceRun
+
+__all__ = [
+    "Admission",
+    "ArtifactRef",
+    "BrowserAction",
+    "BrowserActionResult",
+    "BrowserAgentObservation",
+    "BrowserCapacity",
+    "BrowserClick",
+    "BrowserDiagnostics",
+    "BrowserElement",
+    "BrowserEvidenceCapture",
+    "BrowserFill",
+    "BrowserNavigate",
+    "BrowserObservation",
+    "BrowserObserveInclude",
+    "BrowserPolicy",
+    "BrowserSiteChallenge",
+    "BrowserTargetResolution",
+    "BrowserTiming",
+    "CapacityError",
+    "CleanupResult",
+    "Metadata",
+    "NetworkPolicy",
+    "PolicyError",
+    "RequestOptions",
+    "ResourceLimits",
+    "RetryPolicy",
+    "RunResult",
+    "Timeout",
+    "TraceArtifact",
+    "TraceEvent",
+    "TraceExportArtifact",
+    "TraceExportBundle",
+    "TraceRun",
+    "Viewport",
+    "clean_mapping",
+    "encode_base64",
+    "to_api",
+]

vswarm/models/artifacts.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class ArtifactRef:
+    id: str
+    kind: str | None = None
+    path: str | None = None
+    content_type: str | None = None
+    size_bytes: int | None = None
+    raw: Mapping[str, Any] | None = None
+
+    @classmethod
+    def from_api(cls, data: Mapping[str, Any]) -> "ArtifactRef":
+        return cls(
+            id=str(data.get("id", "")),
+            kind=data.get("kind"),
+            path=data.get("path"),
+            content_type=data.get("content_type"),
+            size_bytes=data.get("size_bytes"),
+            raw=data,
+        )