modal-devin 0.1.0__py3-none-any.whl

modal_devin/__init__.py

@@ -0,0 +1,33 @@
+"""Run Devin Outposts workers on Modal."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from modal_devin._config import WorkerSettings
+from modal_devin._exceptions import (
+    ConfigurationError,
+    ModalCompatibilityError,
+    ModalDevinError,
+    OutpostsAPIError,
+    OutpostsProtocolError,
+    SessionStatusUnknownError,
+    WorkerExitedError,
+)
+from modal_devin.worker import Worker
+
+try:
+    __version__ = version("modal-devin")
+except PackageNotFoundError:  # pragma: no cover - source trees without installed metadata
+    __version__ = "0+unknown"
+
+__all__ = [
+    "ConfigurationError",
+    "ModalCompatibilityError",
+    "ModalDevinError",
+    "OutpostsAPIError",
+    "OutpostsProtocolError",
+    "SessionStatusUnknownError",
+    "Worker",
+    "WorkerExitedError",
+    "WorkerSettings",
+    "__version__",
+]

modal_devin/__main__.py

@@ -0,0 +1,5 @@
+"""Support ``python -m modal_devin``."""
+
+from modal_devin.cli import run
+
+run()

modal_devin/_client.py

@@ -0,0 +1,224 @@
+"""Typed boundary around the Devin Outposts HTTP API."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from enum import StrEnum
+from types import TracebackType
+from typing import Protocol, TypeAlias, cast
+
+from modal_devin._exceptions import OutpostsAPIError, OutpostsProtocolError
+
+JsonValue: TypeAlias = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
+JsonObject: TypeAlias = dict[str, JsonValue]
+_MAX_RESPONSE_BYTES = 1024 * 1024
+
+
+class HTTPResponse(Protocol):
+    def __enter__(self) -> HTTPResponse: ...
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None: ...
+
+    def read(self, size: int = -1) -> bytes: ...
+
+
+class UrlOpen(Protocol):
+    def __call__(self, request: urllib.request.Request, *, timeout: float) -> HTTPResponse: ...
+
+
+_DEFAULT_URLOPEN = cast(UrlOpen, urllib.request.urlopen)
+
+
+class ClaimConflict(OutpostsAPIError):
+    """The session was claimed by another worker first."""
+
+
+class _HTTPError(OutpostsAPIError):
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        super().__init__(message)
+
+
+@dataclass(frozen=True, slots=True)
+class Claim:
+    deadline: str | None
+
+
+class SessionStatus(StrEnum):
+    """Session states understood by the Outposts worker protocol."""
+
+    NEW = "new"
+    PENDING = "pending"
+    CLAIMED = "claimed"
+    RUNNING = "running"
+    RESUMING = "resuming"
+    SUSPENDED = "suspended"
+    EXIT = "exit"
+    ERROR = "error"
+    TERMINATED = "terminated"
+
+
+def _json_object(body: bytes, *, url: str) -> JsonObject:
+    if not body:
+        return {}
+    try:
+        parsed = json.loads(body)
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise OutpostsProtocolError(f"invalid JSON response from {url}") from error
+    if not isinstance(parsed, dict):
+        raise OutpostsProtocolError(
+            f"expected a JSON object from {url}, got {type(parsed).__name__}"
+        )
+    return cast(JsonObject, parsed)
+
+
+def _items(response: Mapping[str, JsonValue]) -> Iterable[Mapping[str, JsonValue]]:
+    items = response.get("items")
+    if not isinstance(items, list):
+        raise OutpostsProtocolError("Outposts response is missing an items array")
+    for index, item in enumerate(items):
+        if not isinstance(item, dict):
+            raise OutpostsProtocolError(
+                f"expected items[{index}] to be an object, got {type(item).__name__}"
+            )
+        yield item
+
+
+def _nested_string(mapping: Mapping[str, JsonValue], outer_key: str, inner_key: str) -> str | None:
+    outer = mapping.get(outer_key)
+    if not isinstance(outer, dict):
+        return None
+    value = outer.get(inner_key)
+    return value if isinstance(value, str) else None
+
+
+def _required_nested_string(
+    mapping: Mapping[str, JsonValue],
+    outer_key: str,
+    inner_key: str,
+    *,
+    context: str,
+) -> str:
+    value = _nested_string(mapping, outer_key, inner_key)
+    if value is None:
+        raise OutpostsProtocolError(f"{context} is missing {outer_key}.{inner_key}")
+    return value
+
+
+def _session_status(value: str) -> SessionStatus:
+    try:
+        return SessionStatus(value)
+    except ValueError as error:
+        raise OutpostsProtocolError(f"unknown Outposts session status: {value!r}") from error
+
+
+class OutpostsClient:
+    """Small synchronous client used by the worker runtime."""
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        timeout: float,
+        urlopen: UrlOpen = _DEFAULT_URLOPEN,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._urlopen = urlopen
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Mapping[str, JsonValue] | None = None,
+    ) -> JsonObject:
+        data = json.dumps(body).encode() if body is not None else None
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        request = urllib.request.Request(url, data=data, method=method)
+        request.add_header("Accept", "application/json")
+        request.add_header("Authorization", f"Bearer {self.token}")
+        request.add_header("User-Agent", "modal-devin")
+        if data is not None:
+            request.add_header("Content-Type", "application/json")
+        try:
+            with self._urlopen(request, timeout=self.timeout) as response:
+                response_body = response.read(_MAX_RESPONSE_BYTES + 1)
+                if len(response_body) > _MAX_RESPONSE_BYTES:
+                    raise OutpostsProtocolError(f"response from {url} exceeded 1 MiB")
+                return _json_object(response_body, url=url)
+        except urllib.error.HTTPError as error:
+            raise _HTTPError(error.code, f"request to {url} failed: {error}") from error
+        except (urllib.error.URLError, TimeoutError) as error:
+            raise OutpostsAPIError(f"request to {url} failed: {error}") from error
+
+    @staticmethod
+    def _session_path(session_id: str, action: str) -> str:
+        encoded = urllib.parse.quote(session_id, safe="")
+        return f"/opbeta/outposts/devins/{encoded}/{action}"
+
+    def pending_session_ids(self, pool_id: str) -> tuple[str, ...]:
+        query = urllib.parse.urlencode({"pool": pool_id, "phase": "pending"})
+        response = self._request("GET", f"/opbeta/outposts/devins?{query}")
+        session_ids: list[str] = []
+        for index, item in enumerate(_items(response)):
+            session_ids.append(
+                _required_nested_string(
+                    item,
+                    "metadata",
+                    "session_id",
+                    context=f"pending item {index}",
+                )
+            )
+        return tuple(session_ids)
+
+    def claim(self, session_id: str, acceptor_id: str) -> Claim:
+        try:
+            response = self._request(
+                "POST",
+                self._session_path(session_id, "claim"),
+                {"acceptor_id": acceptor_id},
+            )
+        except _HTTPError as error:
+            if error.status_code == 409:
+                raise ClaimConflict(session_id) from error
+            raise OutpostsAPIError(f"claim request for {session_id!r} failed: {error}") from error
+        return Claim(deadline=_nested_string(response, "status", "claim_deadline"))
+
+    def release(self, session_id: str, acceptor_id: str) -> None:
+        self._request(
+            "POST",
+            self._session_path(session_id, "release"),
+            {"acceptor_id": acceptor_id},
+        )
+
+    def session_status(self, session_id: str, acceptor_id: str) -> SessionStatus | None:
+        query = urllib.parse.urlencode({"phase": "claimed", "acceptor_id": acceptor_id})
+        response = self._request("GET", f"/opbeta/outposts/devins?{query}")
+        for index, item in enumerate(_items(response)):
+            item_session_id = _required_nested_string(
+                item,
+                "metadata",
+                "session_id",
+                context=f"claimed item {index}",
+            )
+            if item_session_id == session_id:
+                value = _required_nested_string(
+                    item,
+                    "status",
+                    "session_status",
+                    context=f"claimed session {session_id!r}",
+                )
+                return _session_status(value)
+        return None

modal_devin/_config.py

@@ -0,0 +1,192 @@
+"""Validated configuration and Modal resource naming."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import os
+import re
+import urllib.parse
+from dataclasses import dataclass, fields
+from typing import Any, Self, cast
+
+from modal_devin._exceptions import ConfigurationError
+
+DEFAULT_API_URL = "https://api.beta.devinenterprise.com"
+DEFAULT_SCHEDULER_INTERVAL_SECONDS = 30
+DEFAULT_SESSION_TIMEOUT_SECONDS = 1800
+DEFAULT_API_TIMEOUT_SECONDS = 30.0
+DEFAULT_SNAPSHOT_TTL_SECONDS = 30 * 24 * 60 * 60
+DEFAULT_STATUS_ATTEMPTS = 3
+DEFAULT_STATUS_RETRY_DELAY_SECONDS = 1.0
+DEFAULT_SANDBOX_READY_TIMEOUT_SECONDS = 120
+DEFAULT_SIDECAR_READY_TIMEOUT_SECONDS = 60
+DEFAULT_SNAPSHOT_TIMEOUT_SECONDS = 120
+
+_TERMINATION_MARGIN_SECONDS = 30
+
+_RESOURCE_COMPONENT_RE = re.compile(r"[^a-z0-9._-]+")
+_ENV_PREFIX = "MODAL_DEVIN_"
+
+
+def _resource_slug(value: str, *, max_length: int = 32) -> str:
+    """Return a readable, bounded Modal resource-name component."""
+    lowercase = value.strip().lower()
+    normalized = _RESOURCE_COMPONENT_RE.sub("-", lowercase).strip("-._")
+    if not normalized:
+        normalized = "worker"
+    if normalized == lowercase and len(normalized) <= max_length:
+        return normalized
+    digest = hashlib.sha256(value.encode()).hexdigest()[:8]
+    prefix = normalized[: max_length - len(digest) - 1].rstrip("-._") or "worker"
+    return f"{prefix}-{digest}"
+
+
+def _validate_api_url(value: str) -> str:
+    parsed = urllib.parse.urlsplit(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ConfigurationError("api_url must be an absolute http:// or https:// URL")
+    if parsed.username or parsed.password:
+        raise ConfigurationError("api_url must not contain credentials")
+    if parsed.query or parsed.fragment:
+        raise ConfigurationError("api_url must not contain a query string or fragment")
+    return value.rstrip("/")
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerSettings:
+    """Operational settings for a :class:`modal_devin.Worker`.
+
+    Use :meth:`from_env` to read ``MODAL_DEVIN_*`` overrides. Keeping this separate
+    from the worker identity makes configuration explicit and straightforward to test.
+    """
+
+    scheduler_interval_seconds: int = DEFAULT_SCHEDULER_INTERVAL_SECONDS
+    session_timeout_seconds: int = DEFAULT_SESSION_TIMEOUT_SECONDS
+    api_timeout_seconds: float = DEFAULT_API_TIMEOUT_SECONDS
+    snapshot_ttl_seconds: int | None = DEFAULT_SNAPSHOT_TTL_SECONDS
+    status_attempts: int = DEFAULT_STATUS_ATTEMPTS
+    status_retry_delay_seconds: float = DEFAULT_STATUS_RETRY_DELAY_SECONDS
+    sandbox_ready_timeout_seconds: int = DEFAULT_SANDBOX_READY_TIMEOUT_SECONDS
+    sidecar_ready_timeout_seconds: int = DEFAULT_SIDECAR_READY_TIMEOUT_SECONDS
+    snapshot_timeout_seconds: int = DEFAULT_SNAPSHOT_TIMEOUT_SECONDS
+    log_level: str = "INFO"
+
+    def __post_init__(self) -> None:
+        positive = (
+            "scheduler_interval_seconds",
+            "session_timeout_seconds",
+            "api_timeout_seconds",
+            "status_attempts",
+            "sandbox_ready_timeout_seconds",
+            "sidecar_ready_timeout_seconds",
+            "snapshot_timeout_seconds",
+        )
+        for name in positive:
+            if getattr(self, name) <= 0:
+                raise ConfigurationError(f"{name} must be greater than zero")
+        if self.snapshot_ttl_seconds is not None and self.snapshot_ttl_seconds <= 0:
+            raise ConfigurationError("snapshot_ttl_seconds must be positive or None")
+        if self.status_retry_delay_seconds < 0:
+            raise ConfigurationError("status_retry_delay_seconds must not be negative")
+        valid_levels = {"CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"}
+        if self.log_level.upper() not in valid_levels:
+            raise ConfigurationError(
+                "log_level must be one of CRITICAL, ERROR, WARNING, INFO, or DEBUG"
+            )
+
+    @classmethod
+    def from_env(cls) -> Self:
+        """Build settings from ``MODAL_DEVIN_*`` environment variables.
+
+        Set ``MODAL_DEVIN_SNAPSHOT_TTL_SECONDS=none`` to retain snapshots indefinitely.
+        """
+        values: dict[str, object] = {}
+        integer_fields = {
+            "scheduler_interval_seconds",
+            "session_timeout_seconds",
+            "status_attempts",
+            "sandbox_ready_timeout_seconds",
+            "sidecar_ready_timeout_seconds",
+            "snapshot_timeout_seconds",
+        }
+        float_fields = {"api_timeout_seconds", "status_retry_delay_seconds"}
+        for field in fields(cls):
+            raw = os.environ.get(_ENV_PREFIX + field.name.upper())
+            if raw is None:
+                continue
+            try:
+                if field.name in integer_fields:
+                    values[field.name] = int(raw)
+                elif field.name in float_fields:
+                    values[field.name] = float(raw)
+                elif field.name == "snapshot_ttl_seconds":
+                    values[field.name] = None if raw.lower() in {"none", "null"} else int(raw)
+                else:
+                    values[field.name] = raw
+            except ValueError as error:
+                env_name = _ENV_PREFIX + field.name.upper()
+                raise ConfigurationError(f"invalid value for {env_name}: {raw!r}") from error
+        return cls(**cast(dict[str, Any], values))
+
+
+def _status_budget_seconds(settings: WorkerSettings) -> float:
+    request_budget = settings.status_attempts * settings.api_timeout_seconds
+    retry_delay_budget = settings.status_retry_delay_seconds * sum(
+        range(1, settings.status_attempts)
+    )
+    return request_budget + retry_delay_budget
+
+
+def _sandbox_lifetime_seconds(settings: WorkerSettings) -> int:
+    """Maximum Sandbox lifetime including work, startup, and recovery."""
+    return math.ceil(
+        settings.session_timeout_seconds
+        + settings.sandbox_ready_timeout_seconds
+        + settings.sidecar_ready_timeout_seconds
+        + _status_budget_seconds(settings)
+        + settings.snapshot_timeout_seconds
+        + _TERMINATION_MARGIN_SECONDS
+    )
+
+
+def _session_function_timeout_seconds(settings: WorkerSettings) -> int:
+    """Minimum outer Function timeout around one complete Sandbox lifecycle."""
+    claim_and_release_budget = 2 * settings.api_timeout_seconds
+    return math.ceil(_sandbox_lifetime_seconds(settings) + claim_and_release_budget)
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerConfig:
+    """Identity and validated runtime configuration for one worker deployment."""
+
+    name: str
+    pool_id: str
+    api_url: str = DEFAULT_API_URL
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ConfigurationError("name must not be empty")
+        if not self.pool_id.strip():
+            raise ConfigurationError("pool_id must not be empty")
+        object.__setattr__(self, "api_url", _validate_api_url(self.api_url))
+
+    @property
+    def resource_slug(self) -> str:
+        return _resource_slug(self.name)
+
+    @property
+    def acceptor_id(self) -> str:
+        return f"modal-{self.resource_slug}"
+
+    @property
+    def app_name(self) -> str:
+        return f"modal-devin-{self.resource_slug}"
+
+    @property
+    def snapshot_store_name(self) -> str:
+        return f"modal-devin-{self.resource_slug}-snapshots"
+
+    @property
+    def image_build_app_name(self) -> str:
+        return f"modal-devin-{self.resource_slug}-image-builds"

modal_devin/_exceptions.py

@@ -0,0 +1,36 @@
+"""Public exception hierarchy for :mod:`modal_devin`."""
+
+from __future__ import annotations
+
+
+class ModalDevinError(Exception):
+    """Base class for errors raised by modal-devin."""
+
+
+class ConfigurationError(ModalDevinError, ValueError):
+    """The worker configuration is invalid."""
+
+
+class ModalCompatibilityError(ModalDevinError):
+    """The installed Modal SDK does not provide a required capability."""
+
+
+class OutpostsAPIError(ModalDevinError):
+    """A Devin Outposts API request failed."""
+
+
+class OutpostsProtocolError(OutpostsAPIError):
+    """The Devin Outposts API returned an unexpected response."""
+
+
+class SessionStatusUnknownError(ModalDevinError):
+    """A session's final status could not be established safely."""
+
+
+class WorkerExitedError(ModalDevinError):
+    """The Devin worker process exited unsuccessfully."""
+
+    def __init__(self, session_id: str, returncode: int) -> None:
+        self.session_id = session_id
+        self.returncode = returncode
+        super().__init__(f"Devin worker for {session_id!r} exited with status {returncode}")