mimiry 0.1.0__py3-none-any.whl

mimiry/__init__.py

@@ -0,0 +1,54 @@
+"""
+Mimiry Python SDK
+=================
+
+Simple, high-level client for the Mimiry compute platform.
+
+Quick start::
+
+    from mimiry import MimiryClient
+
+    client = MimiryClient()
+
+    # Run a command and get the output
+    result = client.run("nvidia-smi")
+    result.print_logs()
+
+    # Run a Python script
+    result = client.run_script("train.py", verbose=True)
+
+    # Create a session for SSH access
+    session = client.create_session(auto_terminate=False)
+    session.wait_until_running()
+    print(session.ssh_command())
+
+Authentication:
+    Run `mimiry auth login` once before using this SDK.
+    Tokens are refreshed automatically.
+"""
+
+from .client import (
+    CUDA_BASE,
+    PYTORCH_IMAGE,
+    PYTORCH_NGC,
+    MimiryClient,
+    RunResult,
+)
+from ._exceptions import AuthError, LogsError, MimiryError, QuotaError, SessionError
+from ._session import Session
+
+__all__ = [
+    "MimiryClient",
+    "RunResult",
+    "Session",
+    "CUDA_BASE",
+    "PYTORCH_IMAGE",
+    "PYTORCH_NGC",
+    "MimiryError",
+    "AuthError",
+    "QuotaError",
+    "SessionError",
+    "LogsError",
+]
+
+__version__ = "0.1.0"

mimiry/_auth.py

@@ -0,0 +1,70 @@
+"""
+Token management for the Mimiry SDK.
+
+Platform note: JWTs issued by `mimiry auth token --refresh` expire in
+approximately 5-8 minutes. Any API call after expiry returns 401, and
+cleanup DELETE calls silently fail, leaving sessions running and billing
+the account. This manager refreshes proactively every 4 minutes.
+"""
+
+import json
+import subprocess
+import time
+
+from ._exceptions import AuthError
+
+# Refresh well before the ~5-8 min expiry window
+_REFRESH_INTERVAL = 240  # 4 minutes
+
+
+class TokenManager:
+    """
+    Retrieves and caches a Mimiry JWT, auto-refreshing before expiry.
+
+    Calls `mimiry auth token --refresh --json` under the hood.
+    Run `mimiry auth login` once before using the SDK.
+    """
+
+    def __init__(self):
+        self._token: str | None = None
+        self._fetched_at: float = 0.0
+
+    def get(self, force: bool = False) -> str:
+        """Return a valid token, refreshing from the CLI if needed."""
+        age = time.time() - self._fetched_at
+        if force or not self._token or age >= _REFRESH_INTERVAL:
+            self._token = self._fetch()
+            self._fetched_at = time.time()
+        return self._token
+
+    def _fetch(self) -> str:
+        result = subprocess.run(
+            ["mimiry", "auth", "token", "--refresh", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode != 0:
+            raise AuthError(
+                "Failed to get auth token. Run: mimiry auth login\n"
+                f"stderr: {result.stderr.strip()}"
+            )
+
+        # Try JSON response first (CLI >= 1.1)
+        try:
+            data = json.loads(result.stdout)
+            token = data.get("access_token") or data.get("token")
+            if token:
+                return token
+        except json.JSONDecodeError:
+            pass
+
+        # Fallback: older CLI versions print a bare JWT line
+        for line in result.stdout.splitlines():
+            line = line.strip()
+            if line.startswith("eyJ"):
+                return line
+
+        raise AuthError(
+            f"Could not parse token from CLI output: {result.stdout[:300]!r}"
+        )

mimiry/_exceptions.py

@@ -0,0 +1,48 @@
+"""
+Mimiry SDK exception hierarchy.
+"""
+
+
+class MimiryError(Exception):
+    """Base exception for all Mimiry SDK errors."""
+
+
+class AuthError(MimiryError):
+    """
+    Authentication failed or token could not be retrieved.
+    Fix: run `mimiry auth login` then retry.
+    """
+
+
+class QuotaError(MimiryError):
+    """
+    Account quota exceeded or insufficient credits.
+    Check balance with client.balance() and active sessions with client.sessions().
+    """
+
+
+class SessionError(MimiryError):
+    """
+    Session creation, provisioning, or execution failed.
+    The session ID is available on the exception when applicable.
+    """
+
+    def __init__(self, message, session_id=None):
+        super().__init__(message)
+        self.session_id = session_id
+
+
+class LogsError(MimiryError):
+    """
+    Failed to retrieve session logs after all retries.
+    This typically means the VM setup took longer than expected.
+    """
+
+
+class _HttpError(Exception):
+    """Internal: raised for non-2xx HTTP responses."""
+
+    def __init__(self, status, body):
+        self.status = status
+        self.body = body
+        super().__init__(f"HTTP {status}: {body}")

mimiry/_session.py

@@ -0,0 +1,262 @@
+"""
+Session resource — wraps a single Mimiry compute session.
+
+Platform quirks handled here (transparent to callers):
+  - status='running' means VM SSH is up, NOT Docker/GPU ready (Bug 2)
+  - /logs returns 503 'vm_setup_in_progress' for ~60-90s after 'running'
+  - Token is auto-refreshed before every network call
+"""
+
+import time
+
+from ._exceptions import LogsError, SessionError, _HttpError
+
+
+class Session:
+    """
+    A Mimiry compute session.
+
+    Returned by MimiryClient.create_session() and MimiryClient.run().
+    Do not construct directly.
+
+    Attributes:
+        id       : Session UUID.
+        status   : Last-known status string (call refresh() to update).
+        host     : SSH hostname (None until provisioning completes).
+        port     : SSH port (default 22).
+        username : SSH username (default 'ubuntu').
+    """
+
+    def __init__(self, session_id: str, client):
+        self.id = session_id
+        self._client = client
+        self.status = "pending"
+        self.host: str | None = None
+        self.port: int = 22
+        self.username: str = "ubuntu"
+
+    # ── State ──────────────────────────────────────────────────────────────────
+
+    def refresh(self) -> "Session":
+        """Fetch the latest session state from the API."""
+        data = self._client._get(f"/sessions/{self.id}")
+        self.status = data.get("status", "unknown")
+        ssh = data.get("ssh") or {}
+        if ssh.get("host"):
+            self.host = ssh["host"]
+        self.port = ssh.get("port", 22)
+        self.username = ssh.get("username", "ubuntu")
+        return self
+
+    def wait_until_running(self, timeout: int = 300, poll_interval: int = 5) -> "Session":
+        """
+        Block until status == 'running' (VM SSH daemon is up).
+
+        Typical time: 23-55 seconds. After this returns, wait another
+        60-90 seconds before calling logs() — Docker and the GPU driver
+        are still loading.
+
+        Raises:
+            SessionError: if the session fails or the timeout is exceeded.
+        """
+        start = time.time()
+        last_status = ""
+
+        while True:
+            elapsed = time.time() - start
+            if elapsed >= timeout:
+                raise SessionError(
+                    f"Timed out after {timeout}s waiting for 'running' "
+                    f"(last status: {self.status})",
+                    session_id=self.id,
+                )
+
+            self.refresh()
+
+            if self.status != last_status:
+                last_status = self.status
+
+            if self.status == "running":
+                return self
+
+            if self.status in ("completed", "done", "succeeded"):
+                # Fast session that completed before we polled
+                return self
+
+            if self.status in ("failed", "terminated", "cancelled"):
+                raise SessionError(
+                    f"Session {self.id} reached '{self.status}' during provisioning",
+                    session_id=self.id,
+                )
+
+            time.sleep(poll_interval)
+
+    # ── Logs ───────────────────────────────────────────────────────────────────
+
+    def logs(self, tail: int = 500, max_retries: int = 12, initial_delay: int = 15) -> str:
+        """
+        Fetch container logs, retrying automatically on 503.
+
+        The /logs endpoint returns 503 'vm_setup_in_progress' for ~60-90s
+        after status=running while Docker and the GPU driver finish loading.
+        This is handled transparently with exponential backoff.
+
+        Returns:
+            Log text as a string. Empty string if the container produced
+            no output (normal for sessions without a command field set).
+
+        Raises:
+            LogsError: if all retry attempts are exhausted.
+        """
+        delay = initial_delay
+
+        for attempt in range(1, max_retries + 1):
+            self._client._tokens.get()  # proactive token refresh
+
+            try:
+                data = self._client._get(
+                    f"/sessions/{self.id}/logs?tail={tail}&timestamps=false"
+                )
+                return data.get("logs") or ""
+
+            except _HttpError as exc:
+                if exc.status == 503:
+                    retry_after = (exc.body or {}).get("retry_after_seconds", delay)
+                    time.sleep(retry_after)
+                    delay = min(delay * 2, 60)
+                    continue
+                if exc.status == 409:
+                    # Session not in a loggable state — may have already exited cleanly
+                    return ""
+                raise LogsError(
+                    f"Unexpected HTTP {exc.status} fetching logs "
+                    f"for session {self.id}: {exc.body}"
+                ) from exc
+
+        raise LogsError(
+            f"Could not fetch logs for session {self.id} "
+            f"after {max_retries} attempts (VM setup still in progress)"
+        )
+
+    def poll_logs(
+        self,
+        tail: int = 1000,
+        poll_interval: int = 30,
+        timeout: int = 2400,
+        stop_pattern: str | None = None,
+        on_output=None,
+    ) -> str:
+        """
+        Poll logs repeatedly until the session ends or a stop_pattern matches.
+
+        Designed for long-running jobs (e.g. ML training) where you want to
+        see progress as it happens. Token is refreshed automatically.
+
+        Args:
+            tail:          Number of log lines to fetch per poll.
+            poll_interval: Seconds between polls once logs are flowing.
+            timeout:       Hard stop in seconds.
+            stop_pattern:  Stop when this string appears in the logs.
+            on_output:     Optional callable(new_text) — called with each
+                           new chunk of log content.
+
+        Returns:
+            The final complete log string (all lines since session start).
+        """
+        start = time.time()
+        last_log = ""
+
+        while True:
+            elapsed = time.time() - start
+            if elapsed >= timeout:
+                break
+
+            self._client._tokens.get()
+
+            try:
+                text = self.logs(tail=tail)
+            except LogsError:
+                break
+
+            if text and text != last_log:
+                new_content = text[len(last_log):]
+                last_log = text
+                if on_output and new_content.strip():
+                    on_output(new_content)
+
+            if stop_pattern and last_log and stop_pattern in last_log:
+                break
+
+            self.refresh()
+            if self.status in ("terminated", "completed", "done", "failed"):
+                # One final log fetch to capture anything written right before exit
+                try:
+                    final = self.logs(tail=tail)
+                    if final and final != last_log:
+                        new_content = final[len(last_log):]
+                        last_log = final
+                        if on_output and new_content.strip():
+                            on_output(new_content)
+                except LogsError:
+                    pass
+                break
+
+            time.sleep(poll_interval)
+
+        return last_log
+
+    # ── SSH ────────────────────────────────────────────────────────────────────
+
+    def ssh_command(self, key_path: str = "~/.ssh/mimiry_api") -> str:
+        """
+        Return the SSH command string to connect to this session.
+
+        Note: 'running' status means SSH is up, but the GPU driver takes
+        another ~60-90s to load. Connecting too early will show
+        'NVIDIA-SMI has failed' — this is normal, just wait and retry.
+
+        Raises:
+            SessionError: if the session has no SSH host assigned.
+        """
+        if not self.host:
+            self.refresh()
+        if not self.host:
+            raise SessionError(
+                f"Session {self.id} has no SSH host "
+                f"(status: {self.status}). "
+                "Did you set ssh_enabled=True when creating the session?",
+                session_id=self.id,
+            )
+        return (
+            f"ssh -i {key_path} "
+            f"-o StrictHostKeyChecking=no "
+            f"-p {self.port} "
+            f"{self.username}@{self.host}"
+        )
+
+    # ── Lifecycle ──────────────────────────────────────────────────────────────
+
+    def terminate(self) -> None:
+        """
+        Terminate this session (DELETE /sessions/{id}).
+
+        Always call this when done — auto_terminate may not fire reliably
+        when background processes keep the host alive. Silently ignores
+        errors (e.g. session already terminated).
+        """
+        try:
+            self._client._delete(f"/sessions/{self.id}")
+        except Exception:
+            pass
+        self.status = "terminated"
+
+    def __repr__(self) -> str:
+        return (
+            f"Session(id={self.id!r}, status={self.status!r}, host={self.host!r})"
+        )
+
+    def __enter__(self) -> "Session":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.terminate()

mimiry/client.py

@@ -0,0 +1,591 @@
+"""
+MimiryClient — the main entry point for the Mimiry Python SDK.
+
+Confirmed-working patterns (validated on Mimiry soft-launch, Feb 2026):
+
+  Payload:
+    - image.uri   : use nvcr.io/nvidia/cuda:12.1.0-base-ubuntu22.04 for quick jobs
+                    use pytorch/pytorch:2.3.1-cuda12.1-cudnn8-runtime for ML jobs
+    - command     : runs inside user-container (DO NOT use startup_script — ignored)
+    - ssh_enabled : required for /logs endpoint to work
+    - auto_terminate: True recommended to avoid zombie sessions + billing
+
+  Timing:
+    - status='running' in 23-55s, but Docker/GPU take another 60-90s
+    - /logs returns 503 for ~60-90s after 'running' — handled automatically
+    - JWT tokens expire in ~5-8 min — refreshed automatically every 4 min
+"""
+
+import base64
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+from ._auth import TokenManager
+from ._exceptions import AuthError, MimiryError, QuotaError, SessionError, _HttpError
+from ._session import Session
+
+# ── Default images ─────────────────────────────────────────────────────────────
+# Confirmed working, fastest startup. Contains CUDA 12.1 + drivers only.
+CUDA_BASE = "nvcr.io/nvidia/cuda:12.1.0-base-ubuntu22.04"
+
+# Best balance of size vs. capability for ML jobs.
+# ~3.8 GB compressed, ~2-4 min pull. Contains torch + CUDA 12.1 + cuDNN 8.
+PYTORCH_IMAGE = "pytorch/pytorch:2.3.1-cuda12.1-cudnn8-runtime"
+
+# Full NGC PyTorch stack (~14 GB, 10-15 min pull). Only use if you need
+# Jupyter, Apex, Triton, or other NGC extras. Increases job startup time
+# from ~5 min to ~20 min.
+PYTORCH_NGC = "nvcr.io/nvidia/pytorch:24.01-py3"
+
+# Default API base
+_API_BASE = "https://softlaunch.mimiry.com/api/compute/v1"
+
+
+@dataclass
+class RunResult:
+    """
+    Result returned by MimiryClient.run() and MimiryClient.run_script().
+
+    Attributes:
+        logs:       Full container output (stdout + stderr).
+        session_id: The session UUID.
+        success:    True if the session completed without error status.
+        elapsed:    Wall-clock seconds from session creation to log retrieval.
+        image:      The container image that was used.
+    """
+
+    logs: str
+    session_id: str
+    success: bool
+    elapsed: float
+    image: str
+
+    def print_logs(self) -> None:
+        """Print logs to stdout."""
+        print(self.logs)
+
+    def __repr__(self) -> str:
+        lines = len(self.logs.splitlines()) if self.logs else 0
+        return (
+            f"RunResult(session_id={self.session_id!r}, "
+            f"success={self.success}, elapsed={self.elapsed:.1f}s, "
+            f"log_lines={lines})"
+        )
+
+
+class MimiryClient:
+    """
+    Client for the Mimiry compute platform.
+
+    Authenticates automatically via the `mimiry` CLI. Run `mimiry auth login`
+    once before using this client.
+
+    Args:
+        api_base:     Override the API base URL (default: softlaunch endpoint).
+        ssh_key_path: Path to the SSH private key used for session access.
+                      Default: ~/.ssh/mimiry_api
+
+    Example::
+
+        from mimiry import MimiryClient
+
+        client = MimiryClient()
+        result = client.run("nvidia-smi")
+        result.print_logs()
+    """
+
+    def __init__(
+        self,
+        api_base: str = _API_BASE,
+        ssh_key_path: str = "~/.ssh/mimiry_api",
+    ):
+        self._api_base = api_base.rstrip("/")
+        self._ssh_key_path = ssh_key_path
+        self._tokens = TokenManager()
+
+    # ── High-level API ─────────────────────────────────────────────────────────
+
+    def run(
+        self,
+        command: str,
+        *,
+        image: str = CUDA_BASE,
+        gpu: str = "T4",
+        gpu_count: int = 1,
+        name: str | None = None,
+        ssh_key_path: str | None = None,
+        provision_timeout: int = 300,
+        job_timeout: int = 600,
+        logs_tail: int = 500,
+        logs_retries: int = 12,
+        poll_interval: int = 30,
+        stop_pattern: str | None = None,
+        verbose: bool = False,
+    ) -> RunResult:
+        """
+        Submit a command, wait for it to complete, and return the logs.
+
+        This is the main method for running one-shot GPU workloads. It handles
+        the full lifecycle: auth, session creation, provisioning poll, log
+        retrieval with 503 retry, token refresh, and cleanup.
+
+        Args:
+            command:           Shell command to run inside the container.
+                               For multi-step commands use bash -c syntax:
+                               'bash -c "pip install numpy && python3 job.py"'
+            image:             Container image URI. Default is the small CUDA
+                               base (fast start, no PyTorch). For ML jobs use
+                               PYTORCH_IMAGE or pass your own.
+            gpu:               GPU type. 'T4' is the only type on soft-launch.
+            gpu_count:         Number of GPUs (default 1).
+            name:              Session name shown in the dashboard. Auto-generated
+                               from timestamp if not provided.
+            ssh_key_path:      Path to SSH public key to embed in the session.
+                               Defaults to client-level ssh_key_path + '.pub'.
+            provision_timeout: Seconds to wait for status='running' (default 300).
+            job_timeout:       Seconds to wait for the job to complete (default 600).
+                               For large image pulls (NGC PyTorch ~14 GB) use 2400+.
+            logs_tail:         Lines of log output to retrieve per poll (default 500).
+            logs_retries:      503 retry attempts while VM setup is in progress.
+                               Each retry waits ~15-60s, so 12 ≈ 3-12 min total.
+            poll_interval:     Seconds between log polls for long-running jobs.
+            stop_pattern:      Stop polling when this string appears in the logs.
+                               Useful for jobs that don't auto-terminate.
+            verbose:           Print progress and logs to stdout as they arrive.
+
+        Returns:
+            RunResult with .logs, .session_id, .success, .elapsed, .image
+
+        Raises:
+            AuthError:    Not logged in.
+            QuotaError:   Account quota exceeded.
+            SessionError: Session failed during provisioning.
+
+        Example — GPU check::
+
+            result = client.run("nvidia-smi")
+            result.print_logs()
+
+        Example — Install + run::
+
+            result = client.run(
+                'bash -c "pip install -q numpy && python3 -c \\"import numpy; print(numpy.__version__)\\""',
+                image=CUDA_BASE,
+            )
+        """
+        t0 = time.time()
+        session_name = name or f"sdk-run-{int(t0)}"
+
+        # Resolve SSH public key
+        key_pub = self._resolve_pub_key(ssh_key_path)
+
+        if verbose:
+            print(f"[mimiry] Creating session '{session_name}' on {gpu}...")
+            print(f"[mimiry] Image: {image}")
+
+        session = self.create_session(
+            image=image,
+            gpu=gpu,
+            gpu_count=gpu_count,
+            name=session_name,
+            command=command,
+            ssh_key_pub=key_pub,
+            auto_terminate=True,
+        )
+
+        if verbose:
+            print(f"[mimiry] Session: {session.id}")
+            print("[mimiry] Waiting for VM to reach 'running'...")
+
+        try:
+            session.wait_until_running(timeout=provision_timeout)
+
+            if verbose:
+                elapsed = time.time() - t0
+                print(f"[mimiry] Running ({elapsed:.0f}s). Fetching logs...")
+
+            # Initial log fetch handles the 503 'vm_setup_in_progress' phase
+            logs = session.logs(tail=logs_tail, max_retries=logs_retries)
+
+            if verbose and logs:
+                print(logs, flush=True)
+
+            # For jobs that haven't terminated yet, keep polling
+            session.refresh()
+            if session.status not in ("terminated", "completed", "done", "failed"):
+                def _on_output(text):
+                    if verbose:
+                        print(text, end="", flush=True)
+
+                logs = session.poll_logs(
+                    tail=logs_tail,
+                    poll_interval=poll_interval,
+                    timeout=job_timeout,
+                    stop_pattern=stop_pattern,
+                    on_output=_on_output,
+                )
+
+            success = session.status not in ("failed",)
+            elapsed = time.time() - t0
+
+            if verbose:
+                print(f"\n[mimiry] Done in {elapsed:.1f}s — session {session.id}")
+
+            return RunResult(
+                logs=logs,
+                session_id=session.id,
+                success=success,
+                elapsed=elapsed,
+                image=image,
+            )
+
+        finally:
+            session.terminate()
+
+    def run_script(
+        self,
+        script: str,
+        *,
+        image: str = PYTORCH_IMAGE,
+        gpu: str = "T4",
+        name: str | None = None,
+        job_timeout: int = 2400,
+        provision_timeout: int = 300,
+        stop_pattern: str | None = None,
+        verbose: bool = False,
+        **kwargs,
+    ) -> RunResult:
+        """
+        Run a Python script on a GPU session and return its output.
+
+        The script is base64-encoded and decoded inside the container, avoiding
+        all shell-quoting issues. This is the recommended pattern for any
+        non-trivial Python workload.
+
+        Confirmed working pattern (from run_ml_benchmark.sh, Feb 2026):
+          command = "bash -c 'echo <base64> | base64 -d | python3 -u'"
+
+        Args:
+            script:  Path to a .py file (str or Path), or a Python source string.
+            image:   Container image. Default is pytorch/pytorch:2.3.1 (~3.8 GB,
+                     2-4 min pull). Use PYTORCH_NGC for the full NGC stack.
+            gpu:     GPU type ('T4' on soft-launch).
+            name:    Session name (auto-generated if not provided).
+            job_timeout:       Max seconds to wait for job completion.
+                               NGC PyTorch (~14 GB) needs 2400+ for image pull.
+            provision_timeout: Max seconds to wait for VM to reach 'running'.
+            stop_pattern:      Stop polling when this string appears in logs.
+            verbose:           Print progress and logs as they arrive.
+            **kwargs:          Passed through to run() (e.g. logs_tail, poll_interval).
+
+        Returns:
+            RunResult with .logs, .session_id, .success, .elapsed, .image
+
+        Example — inline script::
+
+            result = client.run_script(
+                '''
+                import torch
+                print(f"CUDA: {torch.cuda.is_available()}")
+                print(f"GPU:  {torch.cuda.get_device_name(0)}")
+                '''
+            )
+            result.print_logs()
+
+        Example — script file::
+
+            result = client.run_script("ml_benchmark.py", verbose=True)
+        """
+        # Resolve script content
+        path = Path(script) if "\n" not in script and len(script) < 500 else None
+        if path and path.exists():
+            source = path.read_text()
+            script_label = path.name
+        else:
+            source = script.strip()
+            script_label = "inline_script.py"
+
+        b64 = base64.b64encode(source.encode()).decode()
+        command = f"bash -c 'echo {b64} | base64 -d | python3 -u'"
+
+        session_name = name or f"sdk-script-{int(time.time())}"
+
+        if verbose:
+            print(f"[mimiry] Script: {script_label} ({len(source)} bytes)")
+            print(f"[mimiry] Image:  {image}")
+            if image == PYTORCH_IMAGE:
+                print("[mimiry] Note: ~3.8 GB image pull, expect 2-4 min before logs appear")
+            elif image == PYTORCH_NGC:
+                print("[mimiry] Note: ~14 GB NGC image pull, expect 10-15 min before logs appear")
+
+        return self.run(
+            command,
+            image=image,
+            gpu=gpu,
+            name=session_name,
+            job_timeout=job_timeout,
+            provision_timeout=provision_timeout,
+            stop_pattern=stop_pattern,
+            verbose=verbose,
+            **kwargs,
+        )
+
+    # ── Session management ─────────────────────────────────────────────────────
+
+    def create_session(
+        self,
+        *,
+        image: str = CUDA_BASE,
+        gpu: str = "T4",
+        gpu_count: int = 1,
+        name: str | None = None,
+        command: str | None = None,
+        ssh_key_pub: str | None = None,
+        ssh_key_path: str | None = None,
+        auto_terminate: bool = True,
+    ) -> Session:
+        """
+        Create a session and return a Session object for manual control.
+
+        Use this when you want to SSH in interactively, run multiple commands,
+        or manage the session lifecycle yourself.
+
+        Args:
+            image:         Container image URI.
+            gpu:           GPU type ('T4' on soft-launch).
+            gpu_count:     Number of GPUs (default 1).
+            name:          Session name.
+            command:       Optional command to run on start. If None, the
+                           container starts but runs nothing (useful for SSH).
+            ssh_key_pub:   SSH public key contents (overrides ssh_key_path).
+            ssh_key_path:  Path to SSH private key; .pub will be read automatically.
+                           Defaults to client-level ssh_key_path.
+            auto_terminate: Terminate when command exits (default True).
+                            Set to False for interactive/SSH sessions.
+
+        Returns:
+            Session object (NOT yet running — call wait_until_running()).
+
+        Example — SSH session::
+
+            with client.create_session(
+                auto_terminate=False,
+                command=None,
+            ) as session:
+                session.wait_until_running()
+                print(session.ssh_command())
+                input("Press Enter when done...")
+                # session.terminate() called automatically by context manager
+        """
+        session_name = name or f"sdk-session-{int(time.time())}"
+
+        # Resolve public key
+        pub_key = ssh_key_pub or self._resolve_pub_key(ssh_key_path)
+
+        payload: dict = {
+            "name": session_name,
+            "image": {"uri": image},
+            "gpu": {"types": [gpu], "count": gpu_count},
+            "ssh_enabled": True,
+            "auto_terminate": auto_terminate,
+        }
+
+        if pub_key:
+            payload["ssh_public_key"] = pub_key
+
+        if command:
+            payload["command"] = command
+
+        resp = self._post("/sessions", payload)
+        session_id = resp.get("id") or resp.get("session_id")
+
+        if not session_id:
+            raise SessionError(f"No session ID in API response: {resp}")
+
+        return Session(session_id, self)
+
+    def sessions(self, include_terminal: bool = False) -> list[Session]:
+        """
+        List sessions on this account.
+
+        Args:
+            include_terminal: Include terminated/failed/completed sessions.
+                              Default False (active sessions only).
+
+        Returns:
+            List of Session objects (status is populated, but host may be None
+            for sessions that have terminated).
+        """
+        data = self._get("/sessions")
+        raw = data.get("sessions") or []
+
+        terminal = {"terminated", "failed", "completed", "done", "cancelled"}
+        result = []
+
+        for s in raw:
+            status = s.get("status", "")
+            if not include_terminal and status in terminal:
+                continue
+
+            session = Session(s["id"], self)
+            session.status = status
+            ssh = s.get("ssh") or {}
+            session.host = ssh.get("host")
+            session.port = ssh.get("port", 22)
+            session.username = ssh.get("username", "ubuntu")
+            result.append(session)
+
+        return result
+
+    def kill_all(self, confirm: bool = True) -> int:
+        """
+        Terminate all active sessions.
+
+        Args:
+            confirm: If True (default), print a list and ask for confirmation.
+                     Set to False for non-interactive scripts.
+
+        Returns:
+            Number of sessions terminated.
+        """
+        active = self.sessions()
+
+        if not active:
+            print("No active sessions.")
+            return 0
+
+        print(f"Active sessions ({len(active)}):")
+        for s in active:
+            print(f"  {s.id}  [{s.status}]  host={s.host or 'none'}")
+
+        if confirm:
+            answer = input(f"\nTerminate all {len(active)} session(s)? [y/N] ").strip()
+            if answer.lower() not in ("y", "yes"):
+                print("Aborted.")
+                return 0
+
+        count = 0
+        for s in active:
+            s.terminate()
+            count += 1
+            print(f"  Terminated: {s.id}")
+
+        return count
+
+    # ── Account info ───────────────────────────────────────────────────────────
+
+    def balance(self) -> dict:
+        """
+        Return account balance information.
+
+        Returns:
+            Dict with at least 'balance' (float, EUR).
+
+        Example::
+
+            info = client.balance()
+            print(f"Balance: €{info['balance']:.2f}")
+        """
+        return self._get("/balance")
+
+    def quota(self) -> dict:
+        """
+        Return current quota usage.
+
+        Returns:
+            Dict with 'current_jobs' and 'max_concurrent_jobs'.
+
+        Note: The 'active_sessions' field is always 0 due to a known platform
+        bug — use client.sessions() for accurate counts.
+
+        Example::
+
+            q = client.quota()
+            print(f"Jobs: {q['current_jobs']}/{q['max_concurrent_jobs']}")
+        """
+        return self._get("/quota")
+
+    # ── HTTP helpers ───────────────────────────────────────────────────────────
+
+    def _get(self, path: str) -> dict:
+        return self._request("GET", path)
+
+    def _post(self, path: str, body: dict) -> dict:
+        return self._request("POST", path, json_body=body)
+
+    def _delete(self, path: str) -> dict:
+        return self._request("DELETE", path)
+
+    def _request(self, method: str, path: str, json_body: dict | None = None) -> dict:
+        """Execute an authenticated API request, raising _HttpError on non-2xx."""
+        url = self._api_base + path
+        token = self._tokens.get()
+
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        }
+
+        data: bytes | None = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode()
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                body = resp.read()
+                return json.loads(body) if body else {}
+
+        except urllib.error.HTTPError as exc:
+            body_bytes = exc.read()
+            try:
+                body = json.loads(body_bytes)
+            except Exception:
+                body = {"raw": body_bytes.decode(errors="replace")}
+
+            if exc.code == 401:
+                # Token may have just expired — force refresh and retry once
+                self._tokens.get(force=True)
+                token = self._tokens._token
+                req.add_header("Authorization", f"Bearer {token}")
+                try:
+                    with urllib.request.urlopen(req, timeout=30) as resp2:
+                        body2 = resp2.read()
+                        return json.loads(body2) if body2 else {}
+                except urllib.error.HTTPError as exc2:
+                    body2 = exc2.read()
+                    raise _HttpError(exc2.code, json.loads(body2) if body2 else {})
+
+            if exc.code == 402:
+                raise QuotaError(
+                    "Insufficient credits (HTTP 402). Top up your account balance."
+                )
+            if exc.code == 429:
+                raise QuotaError(
+                    f"Rate limited or quota exceeded (HTTP 429): {body}"
+                )
+
+            raise _HttpError(exc.code, body)
+
+        except urllib.error.URLError as exc:
+            raise MimiryError(f"Network error reaching {url}: {exc.reason}") from exc
+
+    # ── Internal helpers ───────────────────────────────────────────────────────
+
+    def _resolve_pub_key(self, ssh_key_path: str | None = None) -> str:
+        """Read the SSH public key file. Returns empty string if not found."""
+        path_str = ssh_key_path or self._ssh_key_path
+        path = Path(path_str).expanduser()
+        pub = path.with_suffix(".pub") if path.suffix != ".pub" else path
+        if pub.exists():
+            return pub.read_text().strip()
+        return ""
+
+
+# Re-export for convenience
+from ._exceptions import AuthError, MimiryError, QuotaError, SessionError  # noqa: F401

mimiry-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: mimiry
+Version: 0.1.0
+Summary: Python SDK for the Mimiry GPU compute platform
+Author-email: Mimiry <team@mimiry.com>
+License: MIT
+Keywords: gpu,cloud,compute,machine-learning,cuda,mimiry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Mimiry Python SDK
+
+Run GPU jobs on [Mimiry](https://mimiry.com) from Python — no shell scripts, no manual API calls.
+
+```bash
+pip install mimiry
+```
+
+## Requirements
+
+- Python 3.10 or newer
+- [Mimiry CLI](https://mimiry.com) installed and authenticated (`mimiry auth login`)
+
+## Quick start
+
+**Run a command on a GPU and get the output:**
+
+```python
+from mimiry import MimiryClient
+
+client = MimiryClient()
+result = client.run("nvidia-smi", verbose=True)
+result.print_logs()
+```
+
+**Run a Python script on a GPU:**
+
+```python
+from mimiry import MimiryClient, PYTORCH_IMAGE
+
+client = MimiryClient()
+result = client.run_script("train.py", image=PYTORCH_IMAGE, verbose=True)
+result.print_logs()
+```
+
+**Or pass an inline script directly:**
+
+```python
+result = client.run_script(
+    """
+    import torch
+    print(torch.cuda.get_device_name(0))
+    """,
+    image=PYTORCH_IMAGE,
+)
+```
+
+**Check your balance and quota:**
+
+```python
+print(client.balance())
+print(client.quota())
+```
+
+**Clean up all running sessions:**
+
+```python
+client.kill_all()
+```
+
+## How it works
+
+Each `client.run()` call:
+
+1. Creates a session via the Mimiry Sessions API
+2. Polls until the VM reaches `running` status (~30–55 s)
+3. Waits for Docker and the GPU driver to finish loading (~60–90 s)
+4. Fetches the command output from the platform log endpoint
+5. Terminates the session automatically
+
+Sessions are always terminated after the job finishes. If a script crashes before cleanup, run `client.kill_all()`.
+
+## Images
+
+| Constant | Image | Size | Use when |
+|---|---|---|---|
+| `CUDA_BASE` | `nvcr.io/nvidia/cuda:12.1.0-base-ubuntu22.04` | ~0.2 GB | Quick checks, no PyTorch |
+| `PYTORCH_IMAGE` | `pytorch/pytorch:2.3.1-cuda12.1-cudnn8-runtime` | ~3.8 GB | Most ML jobs |
+| `PYTORCH_NGC` | `nvcr.io/nvidia/pytorch:24.01-py3` | ~14 GB | Full NGC stack |
+
+## Authentication
+
+The SDK reads credentials from the Mimiry CLI automatically. Run once before using the SDK:
+
+```bash
+mimiry auth login
+```
+
+Tokens expire in ~5–8 minutes but are refreshed automatically by the SDK.
+
+## License
+
+MIT

mimiry-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mimiry/__init__.py,sha256=u2f3LVwyc2ib644X93vlQV3skfu-wjlG9PU-vhJRO-A,1109
+mimiry/_auth.py,sha256=rdj00JDfsTmkWws7XmooetYW_BOjj9kk0wvX-QNYlmA,2173
+mimiry/_exceptions.py,sha256=m3lIsy5HpRN0ZtEWEkiLTipQVwiYoogC7LuhjBaVRwI,1155
+mimiry/_session.py,sha256=3PrvA5wEF_rxfIxPxFDuGpcCQcBs3qZU8loFhLTTm-g,9554
+mimiry/client.py,sha256=na0SYOrqAbXxgF44TsTSXiv6cAzIsgUNWQJ-l0mRcDA,21713
+mimiry-0.1.0.dist-info/licenses/LICENSE,sha256=CPRMv5J9OLMZRk7wVbXsWsRRUI9cxI5_ZLHIlvztF3E,1063
+mimiry-0.1.0.dist-info/METADATA,sha256=IUXeVWpTvWqIkTkNQAihBawLcFrxF2VEZ_7dT2qssRc,3006
+mimiry-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+mimiry-0.1.0.dist-info/top_level.txt,sha256=aUypA93QzhCqQ7eLjpQbmeHCzCnbYPIYVPAWZb8YEJk,7
+mimiry-0.1.0.dist-info/RECORD,,

mimiry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mimiry-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mimiry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mimiry-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mimiry