mimiry 0.1.0__tar.gz

mimiry-0.1.0/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/PKG-INFO

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

@@ -0,0 +1,93 @@
+# 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/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-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-0.1.0/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-0.1.0/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()