spore-host 0.1.0__tar.gz

spore_host-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Binaries
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+/bin/
+truffle/bin/
+spawn/bin/
+
+# Lambda binaries
+bootstrap
+function.zip
+**/lambda/*/bootstrap
+**/lambda/*-orchestrator
+**/lambda/*-handler
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool
+*.out
+
+# Go workspace file
+go.work
+
+# Dependency directories
+vendor/
+
+# Build artifacts
+dist/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.log
+/tmp/
+
+# Release artifacts
+*.tar.gz
+*.zip
+checksums.txt
+
+# Configuration (credentials)
+/config/
+
+# Local archive (not pushed to GitHub)
+.local-archive/
+spawn/lambda/rest-api/rest-api

spore_host-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,50 @@
+# 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/examples/jupyter_example.ipynb

@@ -0,0 +1,197 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# spore.host — Jupyter Notebook Example\n",
+    "\n",
+    "This notebook shows how to use the `spore-host` Python SDK to find, launch, and manage EC2 instances directly from a notebook.\n",
+    "\n",
+    "**Prerequisites:**\n",
+    "```sh\n",
+    "pip install spore-host\n",
+    "export SPORE_API_KEY=sk_...    # or AWS credentials already configured\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import spore\n",
+    "print(f\"spore-host {spore.__version__}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Find the right instance\n",
+    "\n",
+    "`spore.truffle.find()` searches EC2 instance types using natural language."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results = spore.truffle.find(\"amd epyc genoa\", region=\"us-east-1\")\n",
+    "\n",
+    "# Rich display in Jupyter\n",
+    "import pandas as pd\n",
+    "pd.DataFrame([\n",
+    "    {\n",
+    "        \"Instance\": r.instance_type,\n",
+    "        \"vCPUs\": r.vcpus,\n",
+    "        \"Memory (GiB)\": r.memory_gib,\n",
+    "        \"$/hr\": f\"${r.on_demand_price:.4f}\",\n",
+    "        \"AZs\": \", \".join(r.available_azs),\n",
+    "    }\n",
+    "    for r in results\n",
+    "])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Check Spot prices"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "prices = spore.truffle.spot(\"c8a.2xlarge\", region=\"us-east-1\")\n",
+    "cheapest = min(prices, key=lambda p: p.spot_price)\n",
+    "print(f\"Cheapest Spot: {cheapest.availability_zone} @ ${cheapest.spot_price:.4f}/hr ({cheapest.savings_pct:.0f}% savings)\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Check your account's quota"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "quota = spore.truffle.quota(\"c8a.2xlarge\", region=\"us-east-1\")\n",
+    "status = \"✅ Can launch\" if quota.can_launch else \"❌ Quota insufficient\"\n",
+    "print(f\"{status}: {quota.message}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Check running instances"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "instances = spore.spawn.list()\n",
+    "if not instances:\n",
+    "    print(\"No running instances\")\n",
+    "else:\n",
+    "    for inst in instances:\n",
+    "        display(inst)   # uses _repr_html_"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Manage an existing instance\n",
+    "\n",
+    "Replace `\"sim-run-42\"` with your instance name."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "inst = spore.spawn.status(\"sim-run-42\")\n",
+    "display(inst)\n",
+    "\n",
+    "# Extend TTL if needed\n",
+    "# inst.extend(\"2h\")\n",
+    "\n",
+    "# Wake a stopped instance\n",
+    "# inst.start()\n",
+    "\n",
+    "# Wait for job to finish (non-blocking poll with callback)\n",
+    "# inst.wait(\"terminated\", poll_interval=60, on_status=lambda i: print(f\"{i.state}\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Launch and wait (full workflow)\n",
+    "\n",
+    "> **Note:** `spawn.launch()` is coming in the next SDK release. Use the CLI for now:\n",
+    "> ```sh\n",
+    "> spawn launch --name my-job --instance-type c8a.2xlarge --ttl 8h --idle-timeout 30m\n",
+    "> ```\n",
+    "\n",
+    "Once launch is available, the full pattern will be:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Full workflow (launch available in next release)\n",
+    "#\n",
+    "# inst = spore.spawn.launch(\n",
+    "#     \"c8a.2xlarge\",\n",
+    "#     name=\"notebook-job\",\n",
+    "#     ttl=\"8h\",\n",
+    "#     idle_timeout=\"30m\",\n",
+    "#     on_complete=\"terminate\",\n",
+    "# )\n",
+    "#\n",
+    "# # Poll with progress bar\n",
+    "# from tqdm.notebook import tqdm\n",
+    "# with tqdm(desc=\"Waiting for job\", unit=\"poll\") as pbar:\n",
+    "#     inst.wait(\"terminated\", on_status=lambda i: pbar.set_postfix(state=i.state))\n",
+    "#\n",
+    "# print(f\"Done. Instance {inst.name} terminated.\")\n",
+    "print(\"launch() coming soon — use spawn CLI to launch instances\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.11.0"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

spore_host-0.1.0/examples/marimo_example.py

@@ -0,0 +1,149 @@
+"""
+spore.host — marimo notebook example
+
+Run with:
+    pip install marimo spore-host
+    marimo edit marimo_example.py
+"""
+
+import marimo as mo
+
+app = mo.App(width="medium")
+
+
+@app.cell
+def _():
+    import spore
+    mo.md(f"**spore-host** {spore.__version__} — ephemeral EC2 compute")
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Find instances
+
+    Search for EC2 instance types using natural language.
+    """)
+
+
+@app.cell
+def _(mo):
+    query = mo.ui.text(
+        value="amd epyc genoa",
+        label="Search query",
+        placeholder="e.g. nvidia h100, arm64 32gb, amd genoa",
+    )
+    region = mo.ui.dropdown(
+        options=["us-east-1", "us-west-2", "eu-west-1", "ap-northeast-1"],
+        value="us-east-1",
+        label="Region",
+    )
+    mo.hstack([query, region])
+
+
+@app.cell
+def _(mo, query, region):
+    import spore
+
+    results = spore.truffle.find(query.value, region=region.value)
+
+    if not results:
+        mo.callout(mo.md("No results. Try a different query."), kind="warn")
+    else:
+        mo.table([
+            {
+                "Instance": r.instance_type,
+                "vCPUs": r.vcpus,
+                "Memory (GiB)": f"{r.memory_gib:.0f}",
+                "$/hr": f"${r.on_demand_price:.4f}" if r.on_demand_price else "—",
+                "AZs": len(r.available_azs),
+            }
+            for r in results
+        ])
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Running instances
+
+    Current spawn-managed instances in your account.
+    """)
+
+
+@app.cell
+def _(mo):
+    refresh_btn = mo.ui.button(label="Refresh", kind="neutral")
+    refresh_btn
+
+
+@app.cell
+def _(mo, refresh_btn):
+    import spore
+    _ = refresh_btn.value  # re-run when button clicked
+
+    instances = spore.spawn.list(state="all")
+
+    if not instances:
+        mo.callout(mo.md("No instances found."), kind="info")
+    else:
+        rows = []
+        for inst in instances:
+            rows.append({
+                "Name": inst.name,
+                "Type": inst.instance_type,
+                "State": inst.state,
+                "Region": inst.region,
+                "IP": inst.public_ip or "—",
+                "TTL": inst.ttl or "—",
+            })
+        mo.table(rows)
+
+
+@app.cell
+def _(mo):
+    mo.md("""
+    ## Manage an instance
+
+    Enter an instance name or ID to manage it.
+    """)
+
+
+@app.cell
+def _(mo):
+    inst_input = mo.ui.text(label="Instance name or ID", placeholder="sim-run-42")
+    inst_input
+
+
+@app.cell
+def _(inst_input, mo):
+    import spore
+
+    if not inst_input.value:
+        mo.stop(True, mo.md("Enter an instance name above."))
+
+    try:
+        inst = spore.spawn.status(inst_input.value)
+        state_color = {
+            "running": "green", "stopped": "orange",
+            "terminated": "gray", "pending": "blue",
+        }.get(inst.state, "gray")
+
+        mo.md(f"""
+        **{inst.name}** `{inst.instance_id}`
+
+        | Field | Value |
+        |-------|-------|
+        | Type | {inst.instance_type} |
+        | State | **{inst.state}** |
+        | Region | {inst.region} |
+        | IP | {inst.public_ip or "—"} |
+        | TTL | {inst.ttl or "—"} |
+        | Idle timeout | {inst.idle_timeout or "—"} |
+        """)
+    except Exception as e:
+        mo.callout(mo.md(f"Error: {e}"), kind="danger")
+
+
+if __name__ == "__main__":
+    app.run()

spore_host-0.1.0/examples/script_example.py

@@ -0,0 +1,73 @@
+"""
+spore.host — plain Python script example
+
+Shows how to use spore-host in a data pipeline or batch script
+without a notebook environment.
+
+Usage:
+    pip install spore-host
+    export SPORE_API_KEY=sk_...
+    python script_example.py
+"""
+
+import spore
+
+
+def find_best_instance(query: str, region: str = "us-east-1"):
+    """Find the best instance type for a workload."""
+    print(f"Searching for: {query!r} in {region}")
+    results = spore.truffle.find(query, region=region)
+
+    if not results:
+        print("No results found.")
+        return None
+
+    # Sort by price
+    results.sort(key=lambda r: r.on_demand_price)
+
+    print(f"\nFound {len(results)} instance type(s):\n")
+    for r in results[:5]:
+        gpu_info = f"  {r.gpus}× {r.gpu_model}" if r.gpus else ""
+        print(f"  {r.instance_type:<16} {r.vcpus:>3} vCPU  {r.memory_gib:>6.0f} GiB{gpu_info}  ${r.on_demand_price:.4f}/hr")
+
+    return results[0]
+
+
+def check_running_instances():
+    """Print all currently running instances and their costs."""
+    instances = spore.spawn.list(state="running")
+
+    if not instances:
+        print("No running instances.")
+        return
+
+    print(f"\n{len(instances)} running instance(s):\n")
+    for inst in instances:
+        print(f"  {inst.name:<20} {inst.instance_type:<14} {inst.region}  TTL: {inst.ttl or '—'}")
+
+
+def extend_if_needed(name: str, min_ttl_hours: float = 1.0):
+    """Extend an instance's TTL if less than min_ttl_hours remain."""
+    inst = spore.spawn.status(name)
+    print(f"{inst.name}: {inst.state}  TTL: {inst.ttl or 'none'}")
+
+    # In a real script you'd parse the TTL and check remaining time
+    # For demo: just show how to extend
+    if inst.state == "running":
+        inst.extend("2h")
+        print(f"  → Extended TTL by 2h")
+
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("spore.host Python SDK — script example")
+    print("=" * 60)
+
+    # 1. Find instances
+    best = find_best_instance("amd epyc genoa", region="us-east-1")
+
+    # 2. Check what's running
+    print("\n" + "=" * 60)
+    check_running_instances()
+
+    print("\nDone. Use `spawn launch` CLI to launch instances.")

spore_host-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spore-host"
+version = "0.1.0"
+description = "Python SDK for spore.host — ephemeral EC2 compute for researchers"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [
+    { name = "Scott Friedman", email = "scttfrdmn@gmail.com" },
+]
+keywords = ["aws", "ec2", "compute", "research", "hpc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+
+dependencies = [
+    "boto3>=1.34",
+    "requests>=2.31",
+]
+
+[project.optional-dependencies]
+jupyter = ["ipywidgets>=8.0", "IPython>=8.0"]
+dev     = ["pytest>=7", "pytest-asyncio", "black", "ruff"]
+
+[project.urls]
+Homepage      = "https://spore.host"
+Documentation = "https://docs.spore.host"
+Repository    = "https://github.com/scttfrdmn/spore-host"
+Issues        = "https://github.com/scttfrdmn/spore-host/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["spore"]

spore_host-0.1.0/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_host-0.1.0/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_host-0.1.0/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_host-0.1.0/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>"