spore-host 0.1.0__py3-none-any.whl

spore/__init__.py

@@ -0,0 +1,35 @@
+"""
+spore-host — ephemeral EC2 compute for researchers.
+
+Quick start:
+    import spore
+    results = spore.truffle.find("nvidia h100", region="us-east-1")
+    instance = spore.spawn.launch("c8a.2xlarge", ttl="8h")
+"""
+
+from .client import Client
+from . import truffle, spawn
+
+# Module-level convenience: a default client using ambient AWS credentials
+_default: Client | None = None
+
+
+def _get_default() -> Client:
+    global _default
+    if _default is None:
+        _default = Client()
+    return _default
+
+
+def __getattr__(name: str):
+    # Allow `spore.truffle.find(...)` and `spore.spawn.launch(...)` at module level
+    default = _get_default()
+    if name == "truffle":
+        return default.truffle
+    if name == "spawn":
+        return default.spawn
+    raise AttributeError(f"module 'spore' has no attribute {name!r}")
+
+
+__version__ = "0.1.0"
+__all__ = ["Client", "truffle", "spawn"]

spore/client.py

@@ -0,0 +1,89 @@
+"""Top-level Client — holds credentials and spawns sub-clients."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import boto3
+import requests
+
+
+class Client:
+    """
+    spore.host client. Uses standard AWS credential chain by default.
+
+    Args:
+        api_key:    spore.host API key (sk_...). If omitted, reads SPORE_API_KEY
+                    env var, then falls back to calling the REST API with
+                    SigV4-signed requests using ambient AWS credentials.
+        api_url:    Override the REST API base URL (useful for self-hosted).
+        profile:    AWS profile name (e.g. "my-research-account").
+        region:     Default AWS region.
+    """
+
+    DEFAULT_API_URL = "https://v7ochiyks4uknie3u4s7tiix7a0ejduj.lambda-url.us-east-1.on.aws"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        api_url: Optional[str] = None,
+        profile: Optional[str] = None,
+        region: Optional[str] = None,
+    ):
+        self._api_key = api_key or os.environ.get("SPORE_API_KEY")
+        self._api_url = (api_url or os.environ.get("SPORE_API_URL") or self.DEFAULT_API_URL).rstrip("/")
+        self._profile = profile or os.environ.get("AWS_PROFILE")
+        self._region = region or os.environ.get("AWS_DEFAULT_REGION", "us-east-1")
+
+        # Lazy boto3 session — created on first use
+        self._session: Optional[boto3.Session] = None
+
+        # Sub-clients
+        from .truffle import TruffleClient
+        from .spawn import SpawnClient
+        self.truffle = TruffleClient(self)
+        self.spawn = SpawnClient(self)
+
+    # ── HTTP helpers ──────────────────────────────────────────────────────────
+
+    def _headers(self) -> dict:
+        h = {"Content-Type": "application/json"}
+        if self._api_key:
+            h["X-API-Key"] = self._api_key
+        return h
+
+    def get(self, path: str, params: dict = None) -> dict:
+        resp = requests.get(
+            f"{self._api_url}{path}",
+            headers=self._headers(),
+            params=params or {},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def post(self, path: str, body: dict = None) -> dict:
+        resp = requests.post(
+            f"{self._api_url}{path}",
+            headers=self._headers(),
+            json=body or {},
+            timeout=30,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # ── AWS session (for direct SDK calls when needed) ────────────────────────
+
+    @property
+    def boto_session(self) -> boto3.Session:
+        if self._session is None:
+            kwargs = {"region_name": self._region}
+            if self._profile:
+                kwargs["profile_name"] = self._profile
+            self._session = boto3.Session(**kwargs)
+        return self._session
+
+    def __repr__(self) -> str:
+        key_hint = f"api_key={self._api_key[:8]}..." if self._api_key else "no api_key"
+        return f"<spore.Client {key_hint} region={self._region}>"

spore/spawn.py

@@ -0,0 +1,279 @@
+"""spawn — EC2 instance lifecycle: launch, status, stop, extend, terminate."""
+
+from __future__ import annotations
+
+import time
+import threading
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Callable, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+@dataclass
+class Instance:
+    """A spawn-managed EC2 instance."""
+
+    instance_id: str
+    name: str
+    instance_type: str
+    state: str
+    region: str
+    public_ip: str = ""
+    dns: str = ""
+    launch_time: Optional[datetime] = None
+    ttl: str = ""
+    idle_timeout: str = ""
+    _client: Optional["SpawnClient"] = field(default=None, repr=False)
+
+    # ── Actions ───────────────────────────────────────────────────────────────
+
+    def stop(self, hibernate: bool = False) -> "Instance":
+        """Stop the instance (preserves it; use start() to resume)."""
+        action = "hibernate" if hibernate else "stop"
+        self._client._action(self.instance_id, action, self.region)
+        self.state = "stopping"
+        return self
+
+    def start(self) -> "Instance":
+        """Start a stopped instance."""
+        self._client._action(self.instance_id, "start", self.region)
+        self.state = "pending"
+        return self
+
+    def terminate(self) -> "Instance":
+        """Permanently terminate the instance."""
+        self._client._action(self.instance_id, "terminate", self.region)
+        self.state = "shutting-down"
+        return self
+
+    def extend(self, duration: str) -> "Instance":
+        """
+        Extend the TTL deadline.
+
+        Args:
+            duration: Duration to add, e.g. "2h", "30m", "1d".
+
+        Example:
+            >>> instance.extend("4h")
+        """
+        self._client._action(self.instance_id, "extend", self.region, {"duration": duration})
+        self.ttl = duration
+        return self
+
+    def refresh(self) -> "Instance":
+        """Fetch current state from the API."""
+        updated = self._client.status(self.instance_id)
+        self.state = updated.state
+        self.public_ip = updated.public_ip
+        self.ttl = updated.ttl
+        return self
+
+    # ── Waiting ───────────────────────────────────────────────────────────────
+
+    def wait(
+        self,
+        state: str = "terminated",
+        poll_interval: int = 30,
+        timeout: int = 43200,
+        on_status: Optional[Callable[["Instance"], None]] = None,
+    ) -> "Instance":
+        """
+        Block until the instance reaches a target state.
+
+        Args:
+            state:         Target state: "running", "stopped", "terminated".
+            poll_interval: Seconds between polls (default 30).
+            timeout:       Max seconds to wait (default 12h).
+            on_status:     Optional callback called on each poll with the Instance.
+
+        Example:
+            >>> instance.wait("terminated", on_status=lambda i: print(i.state))
+        """
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            self.refresh()
+            if on_status:
+                on_status(self)
+            if self.state == state:
+                return self
+            if self.state in ("terminated", "shutting-down") and state != "terminated":
+                raise RuntimeError(f"Instance terminated before reaching {state!r}")
+            time.sleep(poll_interval)
+        raise TimeoutError(f"Instance did not reach {state!r} within {timeout}s")
+
+    def wait_running(self, **kwargs) -> "Instance":
+        """Block until running."""
+        return self.wait("running", **kwargs)
+
+    def wait_done(self, **kwargs) -> "Instance":
+        """Block until terminated (job complete or TTL fired)."""
+        return self.wait("terminated", **kwargs)
+
+    # ── Notebook display ──────────────────────────────────────────────────────
+
+    def _repr_html_(self) -> str:
+        state_colour = {
+            "running": "#059669", "stopped": "#d97706",
+            "terminated": "#6b7280", "pending": "#4059E5",
+        }.get(self.state, "#6b7280")
+        return (
+            f'<div style="font-family:monospace;font-size:0.9rem;padding:8px;'
+            f'border:1px solid #e5e7eb;border-radius:6px;background:#f8f9fa">'
+            f'<b>{self.name}</b> <code style="font-size:0.8em">{self.instance_id}</code><br>'
+            f'Type: {self.instance_type} &nbsp;|&nbsp; '
+            f'State: <span style="color:{state_colour};font-weight:600">{self.state}</span><br>'
+            f'Region: {self.region} &nbsp;|&nbsp; IP: {self.public_ip or "—"}<br>'
+            f'TTL: {self.ttl or "—"} &nbsp;|&nbsp; Idle timeout: {self.idle_timeout or "—"}'
+            f'</div>'
+        )
+
+    def __repr__(self) -> str:
+        return f"<Instance {self.name} ({self.instance_id}) {self.state} {self.region}>"
+
+
+class SpawnClient:
+    def __init__(self, client: "Client"):
+        self._c = client
+
+    def launch(
+        self,
+        instance_type: str,
+        *,
+        name: Optional[str] = None,
+        region: Optional[str] = None,
+        ttl: str = "4h",
+        idle_timeout: Optional[str] = None,
+        spot: bool = False,
+        on_complete: str = "terminate",
+        slack_workspace: Optional[str] = None,
+        active_processes: Optional[List[str]] = None,
+        phone: Optional[str] = None,
+        wait: bool = False,
+    ) -> Instance:
+        """
+        Launch an EC2 instance.
+
+        Args:
+            instance_type:    EC2 instance type, e.g. "c8a.2xlarge".
+            name:             Instance name (auto-generated if omitted).
+            region:           AWS region (default: client region).
+            ttl:              Time-to-live, e.g. "8h", "2d". Hard termination deadline.
+            idle_timeout:     Stop if idle for this duration, e.g. "30m".
+            spot:             Use Spot pricing.
+            on_complete:      Action on SPAWN_COMPLETE: "terminate", "stop", "hibernate".
+            slack_workspace:  Slack workspace ID for lifecycle notifications.
+            active_processes: Process names that indicate active work (e.g. ["rsession"]).
+            phone:            Phone number for SMS notifications (+1XXXXXXXXXX).
+            wait:             If True, block until instance is running.
+
+        Returns:
+            Instance object.
+
+        Example:
+            >>> inst = spore.spawn.launch(
+            ...     "c8a.2xlarge",
+            ...     name="my-analysis",
+            ...     ttl="12h",
+            ...     idle_timeout="30m",
+            ... )
+        """
+        raise NotImplementedError(
+            "spawn.launch() requires the spore.host CLI or spored on an EC2 instance. "
+            "Use the CLI: spawn launch --instance-type c8a.2xlarge --ttl 12h\n"
+            "This SDK method will be implemented when the REST API launch endpoint is complete."
+        )
+
+    def list(
+        self,
+        state: str = "running",
+        region: Optional[str] = None,
+    ) -> List[Instance]:
+        """
+        List spawn-managed instances.
+
+        Args:
+            state:  Filter by state: "running", "stopped", "all".
+            region: AWS region (all regions if omitted).
+
+        Example:
+            >>> running = spore.spawn.list()
+            >>> for inst in running:
+            ...     print(inst.name, inst.state)
+        """
+        params: dict = {"state": state}
+        if region:
+            params["region"] = region
+        data = self._c.get("/v1/instances", params=params)
+        return [self._parse(i) for i in data.get("instances", [])]
+
+    def status(self, instance_id_or_name: str) -> Instance:
+        """
+        Get detailed status for a single instance.
+
+        Example:
+            >>> inst = spore.spawn.status("sim-run-42")
+            >>> print(inst.state, inst.ttl)
+        """
+        data = self._c.get(f"/v1/instances/{instance_id_or_name}")
+        return self._parse(data)
+
+    def stop(self, instance_id_or_name: str, hibernate: bool = False) -> Instance:
+        """Stop a running instance."""
+        action = "hibernate" if hibernate else "stop"
+        data = self._action(instance_id_or_name, action)
+        return self.status(instance_id_or_name)
+
+    def start(self, instance_id_or_name: str) -> Instance:
+        """Start a stopped instance."""
+        self._action(instance_id_or_name, "start")
+        return self.status(instance_id_or_name)
+
+    def terminate(self, instance_id_or_name: str) -> dict:
+        """Permanently terminate an instance."""
+        return self._action(instance_id_or_name, "terminate")
+
+    def extend(self, instance_id_or_name: str, duration: str) -> dict:
+        """
+        Extend an instance's TTL deadline.
+
+        Example:
+            >>> spore.spawn.extend("sim-run-42", "4h")
+        """
+        return self._action(instance_id_or_name, "extend", body={"duration": duration})
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    def _action(
+        self,
+        instance_id_or_name: str,
+        action: str,
+        region: Optional[str] = None,
+        body: Optional[dict] = None,
+    ) -> dict:
+        path = f"/v1/instances/{instance_id_or_name}/{action}"
+        return self._c.post(path, body or {})
+
+    def _parse(self, d: dict) -> Instance:
+        launch_time = None
+        if d.get("launch_time"):
+            try:
+                launch_time = datetime.fromisoformat(d["launch_time"].replace("Z", "+00:00"))
+            except Exception:
+                pass
+        inst = Instance(
+            instance_id=d.get("instance_id", ""),
+            name=d.get("name", ""),
+            instance_type=d.get("instance_type", ""),
+            state=d.get("state", ""),
+            region=d.get("region", ""),
+            public_ip=d.get("public_ip", ""),
+            dns=d.get("dns", ""),
+            launch_time=launch_time,
+            ttl=d.get("ttl", ""),
+            idle_timeout=d.get("idle_timeout", ""),
+        )
+        inst._client = self
+        return inst

spore/truffle.py

@@ -0,0 +1,166 @@
+"""truffle — EC2 instance discovery: search, spot prices, quota checks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+@dataclass
+class InstanceType:
+    instance_type: str
+    region: str
+    vcpus: int
+    memory_gib: float
+    architecture: str
+    on_demand_price: float = 0.0
+    gpus: int = 0
+    gpu_model: str = ""
+    gpu_memory_gib: float = 0.0
+    available_azs: List[str] = field(default_factory=list)
+
+    @property
+    def memory_gb(self) -> float:
+        return self.memory_gib
+
+    def __repr__(self) -> str:
+        gpu = f"  {self.gpus}×{self.gpu_model}" if self.gpus else ""
+        price = f"  ${self.on_demand_price:.4f}/hr" if self.on_demand_price else ""
+        return f"<InstanceType {self.instance_type} {self.vcpus}vCPU {self.memory_gib:.0f}GiB{gpu}{price}>"
+
+
+@dataclass
+class SpotPrice:
+    instance_type: str
+    region: str
+    availability_zone: str
+    spot_price: float
+    on_demand_price: float
+    savings_pct: float
+
+
+@dataclass
+class QuotaInfo:
+    instance_type: str
+    region: str
+    vcpus: int
+    can_launch: bool
+    message: str
+    spot: bool = False
+
+
+class TruffleClient:
+    def __init__(self, client: "Client"):
+        self._c = client
+
+    def find(
+        self,
+        query: str,
+        region: Optional[str] = None,
+        regions: Optional[List[str]] = None,
+    ) -> List[InstanceType]:
+        """
+        Find EC2 instance types matching a natural language query.
+
+        Args:
+            query:   Natural language description, e.g. "nvidia h100 8gpu",
+                     "amd epyc genoa", "arm64 64gb memory".
+            region:  Single region to search (e.g. "us-east-1").
+            regions: Multiple regions (overrides region).
+
+        Returns:
+            List of InstanceType objects sorted by price.
+
+        Example:
+            >>> results = spore.truffle.find("amd epyc genoa", region="us-east-1")
+            >>> for r in results:
+            ...     print(r.instance_type, f"${r.on_demand_price:.4f}/hr")
+        """
+        params: dict = {"q": query}
+        if regions:
+            params["region"] = ",".join(regions)
+        elif region:
+            params["region"] = region
+
+        data = self._c.get("/v1/search", params=params)
+        return [self._parse(r) for r in data.get("results", [])]
+
+    def spot(
+        self,
+        instance_type: str,
+        region: Optional[str] = None,
+        regions: Optional[List[str]] = None,
+    ) -> List[SpotPrice]:
+        """
+        Get current Spot prices for an instance type across regions/AZs.
+
+        Example:
+            >>> prices = spore.truffle.spot("c8a.2xlarge", region="us-east-1")
+            >>> cheapest = min(prices, key=lambda p: p.spot_price)
+        """
+        params: dict = {"type": instance_type}
+        if regions:
+            params["region"] = ",".join(regions)
+        elif region:
+            params["region"] = region
+
+        data = self._c.get("/v1/spot", params=params)
+        return [
+            SpotPrice(
+                instance_type=p["instance_type"],
+                region=p["region"],
+                availability_zone=p["availability_zone"],
+                spot_price=float(p["spot_price"]),
+                on_demand_price=float(p.get("on_demand_price", 0)),
+                savings_pct=float(p.get("savings_percent", 0)),
+            )
+            for p in data.get("prices", [])
+        ]
+
+    def quota(
+        self,
+        instance_type: str,
+        region: str,
+        spot: bool = False,
+    ) -> QuotaInfo:
+        """
+        Check whether your AWS account has enough quota to launch an instance type.
+
+        Example:
+            >>> q = spore.truffle.quota("p4d.24xlarge", region="us-east-1")
+            >>> if not q.can_launch:
+            ...     print(q.message)
+        """
+        params = {"type": instance_type, "region": region, "spot": str(spot).lower()}
+        data = self._c.get("/v1/quota", params=params)
+        return QuotaInfo(
+            instance_type=instance_type,
+            region=region,
+            vcpus=int(data.get("vcpus", 0)),
+            can_launch=bool(data.get("can_launch", False)),
+            message=data.get("message", ""),
+            spot=spot,
+        )
+
+    def _parse(self, r: dict) -> InstanceType:
+        return InstanceType(
+            instance_type=r.get("instance_type", ""),
+            region=r.get("region", ""),
+            vcpus=int(r.get("v_cp_us", r.get("vcpus", 0))),
+            memory_gib=float(r.get("memory_mi_b", r.get("memory_gib", 0))) / 1024
+                if r.get("memory_mi_b") else float(r.get("memory_gib", 0)),
+            architecture=r.get("architecture", ""),
+            on_demand_price=float(r.get("on_demand_price", 0)),
+            gpus=int(r.get("gp_us", r.get("gpus", 0))),
+            gpu_model=r.get("gpu_model", ""),
+            gpu_memory_gib=float(r.get("gpu_memory_mi_b", 0)) / 1024,
+            available_azs=r.get("available_a_zs", r.get("available_azs", [])),
+        )
+
+    # ── Notebook display ──────────────────────────────────────────────────────
+
+    def _repr_html_(self) -> str:
+        return "<em>spore.truffle — use .find(), .spot(), .quota()</em>"

spore_host-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: spore-host
+Version: 0.1.0
+Summary: Python SDK for spore.host — ephemeral EC2 compute for researchers
+Project-URL: Homepage, https://spore.host
+Project-URL: Documentation, https://docs.spore.host
+Project-URL: Repository, https://github.com/scttfrdmn/spore-host
+Project-URL: Issues, https://github.com/scttfrdmn/spore-host/issues
+Author-email: Scott Friedman <scttfrdmn@gmail.com>
+License-Expression: Apache-2.0
+Keywords: aws,compute,ec2,hpc,research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Requires-Dist: boto3>=1.34
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: jupyter
+Requires-Dist: ipython>=8.0; extra == 'jupyter'
+Requires-Dist: ipywidgets>=8.0; extra == 'jupyter'
+Description-Content-Type: text/markdown
+
+# spore-host
+
+Python SDK for [spore.host](https://spore.host) — ephemeral EC2 compute for researchers.
+
+```sh
+pip install spore-host
+```
+
+## Quick start
+
+```python
+import spore
+
+# Find instances
+results = spore.truffle.find("amd epyc genoa", region="us-east-1")
+for r in results:
+    print(r.instance_type, f"${r.on_demand_price:.4f}/hr")
+
+# Check Spot prices
+prices = spore.truffle.spot("c8a.2xlarge", region="us-east-1")
+cheapest = min(prices, key=lambda p: p.spot_price)
+
+# Manage running instances
+instances = spore.spawn.list()
+inst = spore.spawn.status("sim-run-42")
+inst.extend("2h")     # push the TTL deadline forward
+inst.wait("terminated", on_status=lambda i: print(i.state))
+```
+
+Works in Jupyter notebooks, [marimo](https://marimo.io), and plain Python scripts.
+
+## Documentation
+
+Full documentation at **[docs.spore.host/guides/python-sdk](https://docs.spore.host/guides/python-sdk)**
+
+- [Jupyter example notebook](examples/jupyter_example.ipynb)
+- [marimo example](examples/marimo_example.py)
+- [Script example](examples/script_example.py)
+
+## Requirements
+
+- Python 3.9+
+- AWS credentials configured (`~/.aws/credentials` or environment variables)
+- `boto3`, `requests`
+
+Optional notebook extras: `pip install "spore-host[jupyter]"`
+
+## License
+
+Apache 2.0 — see [LICENSE](../../LICENSE)

spore_host-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+spore/__init__.py,sha256=pzYwu6OvGe7yGfnNRN1kCN78SM4GY_fEnt-uEuOwLBQ,897
+spore/client.py,sha256=cbCormV1I6znoYVXZ3luqlOvPVGp3qYuhmrlm_cFTB4,3181
+spore/spawn.py,sha256=4bfGFFgY8qjlIHgjw2CKGxirBlks00OHAjps8uXlE-s,10472
+spore/truffle.py,sha256=LjOnmcDX8W-fsXwhLNp-QdqqUpjvidGgENe3mnZy0cg,5409
+spore_host-0.1.0.dist-info/METADATA,sha256=N2qrpPzb9VTKAijUOgOLcNy1ZHa5q-l65u4q1GJkRsI,2663
+spore_host-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+spore_host-0.1.0.dist-info/RECORD,,

spore_host-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any