anycloud-sdk 5.17.2__tar.gz

anycloud_sdk-5.17.2/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/

anycloud_sdk-5.17.2/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: anycloud-sdk
+Version: 5.17.2
+Summary: Python SDK for anycloud — submit jobs, build DAGs, run workloads on any cloud
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# anycloud Python SDK
+
+Submit jobs, build DAGs, run workloads on any cloud.
+
+## Install
+
+```bash
+pip install anycloud
+```
+
+## Define jobs as functions
+
+```python
+import anycloud
+
+ac = anycloud.Client()
+IMG = anycloud.image("my-training:latest")
+
+@ac.job(image=IMG, gpu="h100:8")
+def train(lr: float = 0.001, batch_size: int = 32):
+    ...
+
+# Submit — function params become env vars (LR=0.01, BATCH_SIZE=32)
+job = train.submit(lr=0.01)
+job.wait()
+print(job.logs())
+```
+
+## DAGs via `after`
+
+```python
+@ac.job(image=anycloud.image("prep:latest"))
+def preprocess():
+    ...
+
+@ac.job(image=IMG, gpu="h100:8")
+def train(lr: float = 0.001):
+    ...
+
+@ac.job(image=anycloud.image("eval:latest"))
+def evaluate():
+    ...
+
+prep = preprocess()
+t = train.submit(lr=0.01, after=[prep])
+e = evaluate.submit(after=[t])
+e.wait()  # preprocess → train → evaluate
+```
+
+## Fan-out / fan-in
+
+```python
+split = preprocess()
+shards = [train.submit(lr=lr, after=[split]) for lr in [0.1, 0.01, 0.001]]
+best = evaluate.submit(after=shards)
+best.wait()  # preprocess → 3× train (parallel) → evaluate
+```
+
+## Low-level API
+
+```python
+# submit() works without the decorator too
+job = ac.submit("my-image:latest", cloud="aws", gpu="h100:8", env={"LR": "0.01"})
+job.wait()
+```

anycloud_sdk-5.17.2/README.md

@@ -0,0 +1,65 @@
+# anycloud Python SDK
+
+Submit jobs, build DAGs, run workloads on any cloud.
+
+## Install
+
+```bash
+pip install anycloud
+```
+
+## Define jobs as functions
+
+```python
+import anycloud
+
+ac = anycloud.Client()
+IMG = anycloud.image("my-training:latest")
+
+@ac.job(image=IMG, gpu="h100:8")
+def train(lr: float = 0.001, batch_size: int = 32):
+    ...
+
+# Submit — function params become env vars (LR=0.01, BATCH_SIZE=32)
+job = train.submit(lr=0.01)
+job.wait()
+print(job.logs())
+```
+
+## DAGs via `after`
+
+```python
+@ac.job(image=anycloud.image("prep:latest"))
+def preprocess():
+    ...
+
+@ac.job(image=IMG, gpu="h100:8")
+def train(lr: float = 0.001):
+    ...
+
+@ac.job(image=anycloud.image("eval:latest"))
+def evaluate():
+    ...
+
+prep = preprocess()
+t = train.submit(lr=0.01, after=[prep])
+e = evaluate.submit(after=[t])
+e.wait()  # preprocess → train → evaluate
+```
+
+## Fan-out / fan-in
+
+```python
+split = preprocess()
+shards = [train.submit(lr=lr, after=[split]) for lr in [0.1, 0.01, 0.001]]
+best = evaluate.submit(after=shards)
+best.wait()  # preprocess → 3× train (parallel) → evaluate
+```
+
+## Low-level API
+
+```python
+# submit() works without the decorator too
+job = ac.submit("my-image:latest", cloud="aws", gpu="h100:8", env={"LR": "0.01"})
+job.wait()
+```

anycloud_sdk-5.17.2/anycloud/__init__.py

@@ -0,0 +1,50 @@
+"""anycloud Python SDK — submit jobs, build DAGs, run workloads on any cloud."""
+
+from anycloud.client import Client
+from anycloud.errors import (
+    AnyCloudError,
+    APIError,
+    ConflictError,
+    JobFailedError,
+    NotFoundError,
+    TimeoutError,
+)
+from anycloud.image import Image, image
+from anycloud.job import Job
+from anycloud.remote import RemoteFunction
+from anycloud.types import (
+    AWSCredentials,
+    AzureCredentials,
+    CloudConfig,
+    CloudType,
+    Deployment,
+    DeploymentState,
+    DockerOptions,
+    GCPCredentials,
+    LambdaCredentials,
+)
+
+__all__ = [
+    "Client",
+    "Image",
+    "image",
+    "Job",
+    "RemoteFunction",
+    # Types
+    "CloudConfig",
+    "CloudType",
+    "Deployment",
+    "DeploymentState",
+    "DockerOptions",
+    "AWSCredentials",
+    "GCPCredentials",
+    "AzureCredentials",
+    "LambdaCredentials",
+    # Errors
+    "AnyCloudError",
+    "APIError",
+    "ConflictError",
+    "JobFailedError",
+    "NotFoundError",
+    "TimeoutError",
+]

anycloud_sdk-5.17.2/anycloud/client.py

@@ -0,0 +1,342 @@
+"""anycloud Client — submit jobs, manage deployments."""
+
+from __future__ import annotations
+
+import json
+import os
+from importlib.metadata import version as _pkg_version, PackageNotFoundError
+from pathlib import Path
+from typing import Any, Callable
+
+import httpx
+
+from anycloud.errors import APIError, ConflictError, NotFoundError
+from anycloud.image import Image
+from anycloud.job import Job
+from anycloud.remote import RemoteFunction
+from anycloud.types import (
+    CloudConfig,
+    Deployment,
+    StatusResponse,
+)
+
+
+def _read_version() -> str:
+    """Resolve SDK version: installed package metadata first, then monorepo package.json."""
+    try:
+        return _pkg_version("anycloud-sdk")
+    except PackageNotFoundError:
+        pass
+    # Development fallback: read from monorepo root package.json
+    pkg = Path(__file__).resolve().parent.parent.parent.parent / "package.json"
+    try:
+        with open(pkg) as f:
+            return json.load(f)["version"]
+    except (FileNotFoundError, KeyError):
+        raise RuntimeError(
+            "Could not determine anycloud-sdk version. "
+            "Install the package (pip install anycloud-sdk) or run from the monorepo."
+        )
+
+
+_SDK_VERSION = _read_version()
+
+
+class Client:
+    """anycloud Python client.
+
+    Usage::
+
+        from anycloud import Client
+        from anycloud.types import CloudConfig, AWSCredentials
+
+        cc = CloudConfig(
+            cloudProvider="AWS",
+            credentials=AWSCredentials(
+                accessKeyId="...", secretAccessKey="...",
+            ),
+            region="us-west-2",
+            spot=True,
+        )
+
+        ac = Client(access_token="ghp_...", cloud_config=cc)
+
+        # Submit a job — returns a Job (promise/future)
+        job = ac.submit("train:latest", gpu="h100:8")
+        job.wait()
+
+        # Chain jobs into a DAG
+        prep  = ac.submit("prep:latest")
+        train = ac.submit("train:latest", gpu="h100:8", after=[prep])
+        eval  = ac.submit("eval:latest", after=[train])
+        eval.wait()  # waits for the entire chain
+
+    Args:
+        access_token: GitHub token for authentication.
+            Falls back to ``ANYCLOUD_ACCESS_TOKEN`` env var.
+        conductor_url: Base URL of the conductor API.
+            Falls back to ``ANYCLOUD_CONDUCTOR_URL``, then ``http://localhost:8080``.
+        cloud_config: Default ``CloudConfig`` applied to every ``submit()`` call.
+            Can be overridden per-submit via ``submit(cloud_config=...)``.
+    """
+
+    def __init__(
+        self,
+        *,
+        access_token: str | None = None,
+        conductor_url: str | None = None,
+        cloud_config: CloudConfig | None = None,
+    ):
+        self._access_token = access_token or os.environ.get("ANYCLOUD_ACCESS_TOKEN", "")
+        self._base_url = (
+            conductor_url
+            or os.environ.get("ANYCLOUD_CONDUCTOR_URL", "http://localhost:8080")
+        ).rstrip("/")
+        self._default_cloud_config = cloud_config
+        self._http = httpx.Client(base_url=self._base_url, timeout=30.0)
+
+    # ------------------------------------------------------------------
+    # Decorator: @client.job()
+    # ------------------------------------------------------------------
+
+    def job(
+        self,
+        *,
+        image: Image | str,
+        cloud_config: CloudConfig | None = None,
+        gpu: str | None = None,
+        docker_options: dict[str, Any] | None = None,
+        command: list[str] | None = None,
+    ) -> Callable:
+        """Decorator that turns a function into a submittable anycloud job.
+
+        The function's parameters (with defaults) become environment variables
+        when submitted. The function body is not executed — the Docker image
+        is what runs on the cloud.
+
+        Usage::
+
+            IMG = anycloud.image("train:latest")
+
+            @ac.job(image=IMG, cloud_config=my_config, gpu="h100:8")
+            def train(lr: float = 0.001, batch_size: int = 32):
+                ...
+
+            job = train.submit(lr=0.01)
+            job = train(lr=0.01)          # shorthand
+            job = train.submit(after=[prep_job])  # DAG
+        """
+        def decorator(fn: Callable) -> RemoteFunction:
+            return RemoteFunction(
+                self,
+                fn,
+                image=image,
+                cloud_config=cloud_config,
+                gpu=gpu,
+                docker_options=docker_options,
+                command=command,
+            )
+        return decorator
+
+    # ------------------------------------------------------------------
+    # Core: submit
+    # ------------------------------------------------------------------
+
+    def submit(
+        self,
+        image: str,
+        *,
+        cloud_config: CloudConfig | None = None,
+        gpu: str | None = None,
+        env: dict[str, str] | None = None,
+        docker_options: dict[str, Any] | None = None,
+        command: list[str] | None = None,
+        persist: bool = False,
+        deployment_id: str | None = None,
+        image_digest: str | None = None,
+        after: list[Job] | None = None,
+    ) -> Job:
+        """Submit a job and return a ``Job`` promise.
+
+        If ``after`` is provided, the job is **deferred**: it won't be
+        submitted to the conductor until all upstream jobs complete.
+        Calling ``wait()`` on a deferred job blocks on the full chain.
+
+        This lets you build arbitrary DAGs::
+
+            prep  = client.submit("prep:latest", cloud_config=cc)
+            train = client.submit("train:latest", cloud_config=cc, gpu="h100:8", after=[prep])
+            eval  = client.submit("eval:latest", cloud_config=cc, after=[train])
+            eval.wait()  # prep → train → eval
+
+        Fan-out / fan-in::
+
+            split  = client.submit("split:latest", cloud_config=cc)
+            shards = [client.submit("worker:latest", cloud_config=cc, after=[split]) for _ in range(4)]
+            merge  = client.submit("merge:latest", cloud_config=cc, after=shards)
+            merge.wait()  # split → 4× worker → merge
+
+        Args:
+            image: Docker image reference (e.g. ``"train:latest"``).
+            cloud_config: ``CloudConfig`` specifying provider, credentials, region, etc.
+                Falls back to the default set on ``Client(cloud_config=...)``.
+            gpu: GPU type shorthand (e.g. ``"h100:8"``).
+            env: Environment variables passed to the container.
+            docker_options: Docker runtime options (shmSize, gpus, etc.).
+            command: Override container CMD.
+            persist: Keep VM alive after job completion.
+            deployment_id: Custom deployment ID (auto-generated if omitted).
+            image_digest: Docker image digest (e.g. ``"sha256:abc..."``).
+            after: List of upstream ``Job`` objects that must complete first.
+
+        Returns:
+            A ``Job`` handle you can poll, wait on, or pass as a dependency.
+        """
+        body = self._build_request_body(
+            image=image,
+            gpu=gpu,
+            env=env,
+            docker_options=docker_options,
+            command=command,
+            persist=persist,
+            deployment_id=deployment_id,
+            cloud_config=cloud_config,
+            image_digest=image_digest,
+        )
+
+        if after:
+            # Deferred: don't submit yet, wait for deps on .wait()
+            job = Job(self, deployment_id or "(deferred)", after=after)
+            job._submit_kwargs = body
+            return job
+
+        # Immediate: submit now
+        data = self._submit_raw(body)
+        return Job(self, data["id"])
+
+    # ------------------------------------------------------------------
+    # Deployment management
+    # ------------------------------------------------------------------
+
+    def list(self, *, limit: int = 20) -> list[Deployment]:
+        """List recent deployments."""
+        data = self._post("/v1/list", {
+            "accessToken": self._access_token,
+            "version": _SDK_VERSION,
+            "limit": limit,
+        })
+        return [Deployment.model_validate(d) for d in data]
+
+    def get(self, deployment_id: str) -> Job:
+        """Get a ``Job`` handle for an existing deployment."""
+        return Job(self, deployment_id)
+
+    # ------------------------------------------------------------------
+    # Internal API calls (used by Job)
+    # ------------------------------------------------------------------
+
+    def _submit_raw(self, body: dict[str, Any]) -> dict[str, Any]:
+        """POST /v1/new and return the response dict."""
+        return self._post("/v1/new", body)
+
+    def _status(self, deployment_id: str, *, verbose: bool = False) -> StatusResponse:
+        body: dict[str, Any] = {
+            "id": deployment_id,
+            "accessToken": self._access_token,
+            "version": _SDK_VERSION,
+        }
+        if verbose:
+            body["verbose"] = True
+        data = self._post("/v1/status", body)
+        return StatusResponse.model_validate(data)
+
+    def _terminate(self, deployment_id: str) -> None:
+        self._post("/v1/terminate", {
+            "id": deployment_id,
+            "accessToken": self._access_token,
+            "version": _SDK_VERSION,
+        })
+
+    def _resubmit(self, deployment_id: str) -> None:
+        self._post("/v1/resubmit", {
+            "id": deployment_id,
+            "accessToken": self._access_token,
+            "version": _SDK_VERSION,
+        })
+
+    # ------------------------------------------------------------------
+    # HTTP
+    # ------------------------------------------------------------------
+
+    def _post(self, path: str, body: dict[str, Any]) -> Any:
+        resp = self._http.post(path, json=body)
+        if resp.status_code == 409:
+            raise ConflictError(resp.text)
+        if resp.status_code == 404:
+            raise NotFoundError(resp.text)
+        if resp.status_code >= 400:
+            # /v1/status returns 400 (not 404) for missing deployments
+            if "not found" in resp.text.lower():
+                raise NotFoundError(resp.text)
+            raise APIError(resp.status_code, resp.text)
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _build_request_body(
+        self,
+        *,
+        image: str,
+        gpu: str | None,
+        env: dict[str, str] | None,
+        docker_options: dict[str, Any] | None,
+        command: list[str] | None,
+        persist: bool,
+        deployment_id: str | None,
+        cloud_config: CloudConfig | None,
+        image_digest: str | None = None,
+    ) -> dict[str, Any]:
+        cc = cloud_config or self._default_cloud_config
+        if cc is None:
+            raise ValueError(
+                "A cloud config is required. Pass cloud_config=CloudConfig(...) "
+                "or set a default via Client(cloud_config=...)."
+            )
+
+        body: dict[str, Any] = {
+            "image": image,
+            "deploymentType": "job",
+            "version": _SDK_VERSION,
+            "accessToken": self._access_token,
+            "cloudConfig": cc.model_dump(by_alias=True, exclude_none=True),
+        }
+
+        if deployment_id is not None:
+            body["id"] = deployment_id
+        if env is not None:
+            body["env"] = env
+        if persist:
+            body["persist"] = True
+        if docker_options is not None:
+            body["dockerOptions"] = docker_options
+        if command is not None:
+            body["command"] = command
+        if gpu is not None:
+            body["gpuType"] = gpu
+        if image_digest is not None:
+            body["imageDigest"] = image_digest
+
+        return body
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+

anycloud_sdk-5.17.2/anycloud/errors.py

@@ -0,0 +1,52 @@
+"""anycloud SDK exceptions."""
+
+
+class AnyCloudError(Exception):
+    """Base exception for anycloud SDK."""
+
+
+class APIError(AnyCloudError):
+    """HTTP error from the conductor API."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"[{status_code}] {message}")
+
+
+class ConflictError(APIError):
+    """Deployment ID already exists (409)."""
+
+    def __init__(self, message: str = "Deployment ID already exists"):
+        super().__init__(409, message)
+
+
+class NotFoundError(APIError):
+    """Deployment not found (404)."""
+
+    def __init__(self, message: str = "Deployment not found"):
+        super().__init__(404, message)
+
+
+class JobFailedError(AnyCloudError):
+    """Job reached a terminal failure state."""
+
+    def __init__(self, job_id: str, state: str, message: str | None = None):
+        self.job_id = job_id
+        self.state = state
+        detail = f": {message}" if message else ""
+        super().__init__(f"Job {job_id} {state}{detail}")
+
+
+class DAGError(AnyCloudError):
+    """Error in DAG construction or execution."""
+
+
+class CycleError(DAGError):
+    """DAG contains a cycle."""
+
+    def __init__(self):
+        super().__init__("DAG contains a cycle")
+
+
+class TimeoutError(AnyCloudError):
+    """Operation timed out."""

anycloud_sdk-5.17.2/anycloud/image.py

@@ -0,0 +1,31 @@
+"""Image reference for anycloud jobs."""
+
+from __future__ import annotations
+
+
+class Image:
+    """A reference to a Docker image.
+
+    Usage::
+
+        IMG = anycloud.image("pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime")
+
+        @ac.job(image=IMG, gpu="h100:8")
+        def train(lr: float = 0.001):
+            ...
+    """
+
+    def __init__(self, ref: str):
+        self.ref = ref
+
+    def __repr__(self) -> str:
+        return f"Image({self.ref!r})"
+
+
+def image(ref: str) -> Image:
+    """Create an image reference.
+
+    Args:
+        ref: Docker image reference (e.g. ``"pytorch/pytorch:2.1.0"``).
+    """
+    return Image(ref)