podstack 1.3.21__tar.gz → 1.4.0__tar.gz

{podstack-1.3.21 → podstack-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: podstack
-Version: 1.3.21
+Version: 1.4.0
 Summary: Official Python SDK for Podstack GPU Notebook Platform
 Author-email: Podstack <support@podstack.ai>
 License-Expression: MIT

{podstack-1.3.21 → podstack-1.4.0}/podstack/__init__.py

@@ -54,7 +54,7 @@ Decorators:
         ...
 """
 
-__version__ = "1.3.2"
+__version__ = "1.4.0"
 
 from .client import Client
 from .notebook import Notebook, NotebookStatus
@@ -86,6 +86,31 @@ from .gpu_runner import (
     RunnerList,
     run as run_on_gpu,
     list_runners,
+    get_runner_info,
+    pip_install,
+)
+
+# Pipeline module import
+from . import pipelines
+from .pipelines import (
+    step,
+    pipeline,
+    StepConfig,
+    PipelineDef,
+    list_pipelines,
+    get_pipeline,
+    get_pipeline_run,
+    trigger_pipeline,
+    cancel_pipeline_run,
+    archive_pipeline,
+)
+
+# Storage module import
+from . import storage
+from .storage import (
+    StorageClient, BucketList, VolumeList,
+    create_bucket, get_bucket, list_buckets, delete_bucket,
+    create_volume, get_volume, list_volumes, delete_volume,
 )
 
 # Annotations module import
@@ -103,6 +128,13 @@ from .annotations import (
     get_environment,
     get_auto_shutdown_minutes,
     enable_remote_execution,
+    deploy,
+    DeployConfig,
+)
+from .gpu_runner import (
+    get_deployment,
+    stop_deployment,
+    delete_deployment,
 )
 
 
@@ -206,6 +238,31 @@ __all__ = [
     "WalletBalance",
     # Registry
     "registry",
+    # Pipelines
+    "pipelines",
+    "step",
+    "pipeline",
+    "StepConfig",
+    "PipelineDef",
+    "list_pipelines",
+    "get_pipeline",
+    "get_pipeline_run",
+    "trigger_pipeline",
+    "cancel_pipeline_run",
+    "archive_pipeline",
+    # Storage
+    "storage",
+    "StorageClient",
+    "BucketList",
+    "VolumeList",
+    "create_bucket",
+    "get_bucket",
+    "list_buckets",
+    "delete_bucket",
+    "create_volume",
+    "get_volume",
+    "list_volumes",
+    "delete_volume",
     # GPU Runner
     "gpu_runner",
     "GPURunner",
@@ -213,6 +270,8 @@ __all__ = [
     "RunnerList",
     "run_on_gpu",
     "list_runners",
+    "get_runner_info",
+    "pip_install",
     # Annotations
     "annotations",
     "gpu",
@@ -227,4 +286,10 @@ __all__ = [
     "get_environment",
     "get_auto_shutdown_minutes",
     "enable_remote_execution",
+    # Deploy
+    "deploy",
+    "DeployConfig",
+    "get_deployment",
+    "stop_deployment",
+    "delete_deployment",
 ]

{podstack-1.3.21 → podstack-1.4.0}/podstack/annotations.py

@@ -37,6 +37,7 @@ from typing import Optional, Dict, Any, Callable, Union
 from contextlib import contextmanager
 
 from . import registry
+from .pipelines import step, pipeline, StepConfig, PipelineDef
 from .gpu_runner import (
     GPURunner,
     GPUExecutionResult,
@@ -802,6 +803,154 @@ class ModelRegistry:
 model = ModelRegistry()
 
 
+class DeployConfig:
+    """
+    Deploy configuration decorator.
+
+    Deploys the decorated function as a persistent REST API endpoint.
+
+    Usage:
+        @podstack.deploy(name="sentiment-api", gpu="A10", fraction=50)
+        def predict(data):
+            return {"sentiment": "positive", "text": data["text"]}
+
+        result = predict()  # Deploys and returns endpoint info
+    """
+
+    def __init__(
+        self,
+        name: str,
+        gpu: str = "A10",
+        count: int = 1,
+        fraction: int = 100,
+        pip: Union[str, list] = None,
+        uv: Union[str, list] = None,
+        function: str = None,
+        image: str = None,
+    ):
+        self.name = name
+        self.gpu = gpu
+        self.count = count
+        self.fraction = fraction
+        self.pip = pip
+        self.uv = uv
+        self.function = function
+        self.image = image
+
+    def __call__(self, func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            runner = get_runner()
+
+            # Get function source
+            source = inspect.getsource(func)
+            source = textwrap.dedent(source)
+
+            # Remove decorator lines
+            lines = source.split('\n')
+            clean_lines = []
+            skip_decorator = False
+            paren_depth = 0
+            for line in lines:
+                stripped = line.strip()
+                if stripped.startswith('@podstack.deploy') or stripped.startswith('@deploy'):
+                    skip_decorator = True
+                    paren_depth += line.count('(') - line.count(')')
+                    if paren_depth <= 0:
+                        skip_decorator = False
+                    continue
+                if skip_decorator:
+                    paren_depth += line.count('(') - line.count(')')
+                    if paren_depth <= 0:
+                        skip_decorator = False
+                    continue
+                if stripped.startswith('@'):
+                    continue
+                clean_lines.append(line)
+            source = '\n'.join(clean_lines)
+
+            function_name = self.function or func.__name__
+            pip_packages = self.pip
+            if isinstance(pip_packages, list):
+                pip_packages = " ".join(pip_packages)
+
+            # POST to deployment API
+            import httpx
+            headers = runner._get_headers()
+            url = f"{runner.api_url}/api/v1/deployments/from-source"
+            with httpx.Client(timeout=30.0) as client:
+                response = client.post(url, headers=headers, json={
+                    "name": self.name,
+                    "source": source,
+                    "function_name": function_name,
+                    "gpu_type": self.gpu,
+                    "gpu_fraction": self.fraction,
+                    "gpu_count": self.count,
+                    "pip_packages": pip_packages or "",
+                    "image": self.image or "",
+                })
+                if response.status_code >= 400:
+                    raise PodstackError(f"Deployment failed: {response.text}")
+                data = response.json()
+
+            deployment_id = data.get("deployment_id")
+            print(f"[Podstack] Deploying '{self.name}' as REST API...")
+            print(f"[Podstack] Deployment ID: {deployment_id}")
+            print(f"[Podstack] Status: {data.get('status')}")
+
+            # Poll for active status (up to 120s)
+            status_url = f"{runner.api_url}/api/v1/deployments/{deployment_id}"
+            for _ in range(24):
+                time.sleep(5)
+                with httpx.Client(timeout=30.0) as client:
+                    status_resp = client.get(status_url, headers=headers)
+                    if status_resp.status_code >= 400:
+                        continue
+                    status_data = status_resp.json()
+                status = status_data.get("status")
+                if status == "active":
+                    endpoint = status_data.get("service_url", "")
+                    print(f"[Podstack] Endpoint live: POST {endpoint}/predict")
+                    return {"deployment_id": deployment_id, "status": "active", "endpoint": f"{endpoint}/predict"}
+                elif status == "failed":
+                    error = status_data.get("error_message", "Unknown error")
+                    print(f"[Podstack] Deployment failed: {error}")
+                    raise PodstackError(f"Deployment failed: {error}")
+                print(f"[Podstack] Status: {status}...")
+
+            print(f"[Podstack] Deployment still starting. Check status with:")
+            print(f"  podstack.get_deployment('{deployment_id}')")
+            return {"deployment_id": deployment_id, "status": "starting"}
+
+        return wrapper
+
+
+def deploy(
+    name: str,
+    gpu: str = "A10",
+    count: int = 1,
+    fraction: int = 100,
+    pip: Union[str, list] = None,
+    uv: Union[str, list] = None,
+    function: str = None,
+    image: str = None,
+) -> DeployConfig:
+    """Deploy a function as a persistent REST API endpoint.
+
+    Examples:
+        @podstack.deploy(name="sentiment-api", gpu="A10", fraction=25)
+        def predict(data):
+            return {"sentiment": "positive"}
+
+        result = predict()  # Deploys and returns endpoint info
+        print(result["endpoint"])
+    """
+    return DeployConfig(
+        name=name, gpu=gpu, count=count, fraction=fraction,
+        pip=pip, uv=uv, function=function, image=image,
+    )
+
+
 def get_gpu_config() -> Dict[str, Any]:
     """Get current GPU configuration."""
     return _current_gpu_config.copy()
@@ -832,6 +981,13 @@ __all__ = [
     "enable_remote_execution",
     "is_remote_execution_enabled",
     "GPUConfig",
+    "deploy",
+    "DeployConfig",
+    # Pipeline
+    "step",
+    "pipeline",
+    "StepConfig",
+    "PipelineDef",
     # Exceptions
     "PodstackError",
     "PodstackTimeoutError",

{podstack-1.3.21 → podstack-1.4.0}/podstack/gpu_runner.py

@@ -128,6 +128,42 @@ def is_jupyter() -> bool:
     return False
 
 
+def _format_libraries(libs) -> str:
+    """Format a libraries field into a compact comma-separated string."""
+    if not libs:
+        return ""
+    # If it's a JSON string, parse it
+    if isinstance(libs, str):
+        try:
+            libs = __import__("json").loads(libs)
+        except (ValueError, TypeError):
+            return libs
+    # Dict like {"torch": "2.3.0", "numpy": "1.26"} → "torch, numpy"
+    if isinstance(libs, dict):
+        return ", ".join(libs.keys())
+    # List like ["torch", "numpy"]
+    if isinstance(libs, list):
+        return ", ".join(str(item) for item in libs)
+    return str(libs)
+
+
+def _normalize_mounts(mounts: list, default_prefix: str) -> str:
+    """Normalize mount specs to 'name:/path,name2:/path2' format.
+
+    Accepts: ["name:/path", "name"] -> "name:/path,name:/mnt/nfs/name"
+    """
+    parts = []
+    for entry in mounts:
+        entry = entry.strip()
+        if not entry:
+            continue
+        if ":" in entry:
+            parts.append(entry)
+        else:
+            parts.append(f"{entry}:{default_prefix}/{entry}")
+    return ",".join(parts)
+
+
 class RunnerList(list):
     """A list of runners with a .show() method for tabular display."""
 
@@ -141,18 +177,22 @@ class RunnerList(list):
         no_w = 5
         name_w = 45
         type_w = 6
-        desc_w = 50
+        libs_w = 40
+        desc_w = 40
 
-        header = f"{'S.NO':<{no_w}} {'Name':<{name_w}} {'Type':<{type_w}} {'Description'}"
+        header = f"{'S.NO':<{no_w}} {'Name':<{name_w}} {'Type':<{type_w}} {'Libraries':<{libs_w}} {'Description'}"
         print(header)
-        print("-" * (no_w + name_w + type_w + desc_w + 3))
+        print("-" * (no_w + name_w + type_w + libs_w + desc_w + 4))
         for i, r in enumerate(self, 1):
             name = r.get("name", "")
             rtype = r.get("type", "")
             desc = r.get("description", "")
+            libs = _format_libraries(r.get("libraries", ""))
             if len(desc) > desc_w:
                 desc = desc[:desc_w - 3] + "..."
-            print(f"{i:<{no_w}} {name:<{name_w}} {rtype:<{type_w}} {desc}")
+            if len(libs) > libs_w:
+                libs = libs[:libs_w - 3] + "..."
+            print(f"{i:<{no_w}} {name:<{name_w}} {rtype:<{type_w}} {libs:<{libs_w}} {desc}")
 
 
 class OutputStreamer:
@@ -396,7 +436,9 @@ class GPURunner:
         conda: Union[str, list] = None,
         requirements: str = None,
         use_uv: bool = False,
-        runner: str = None
+        runner: str = None,
+        nfs: List[str] = None,
+        buckets: List[str] = None
     ) -> str:
         """Build the @podstack annotation string."""
         parts = [f"#@podstack gpu={gpu}"]
@@ -439,6 +481,12 @@ class GPURunner:
         if runner:
             parts.append(f"runner={runner}")
 
+        # NFS volume and bucket mounts
+        if nfs:
+            parts.append(f"nfs={_normalize_mounts(nfs, '/mnt/nfs')}")
+        if buckets:
+            parts.append(f"buckets={_normalize_mounts(buckets, '/mnt/buckets')}")
+
         return " ".join(parts)
 
     def submit(
@@ -456,7 +504,9 @@ class GPURunner:
         use_uv: bool = False,
         env_vars: Dict[str, str] = None,
         add_annotation: bool = True,
-        runner: str = None
+        runner: str = None,
+        nfs: List[str] = None,
+        buckets: List[str] = None
     ) -> Dict[str, Any]:
         """
         Submit code for GPU execution (non-blocking).
@@ -486,7 +536,7 @@ class GPURunner:
 
         # Add annotation if not present
         if add_annotation and not code.strip().startswith("#@podstack"):
-            annotation = self._build_annotation(gpu, count, fraction, timeout, env, pip, uv, conda, requirements, use_uv, runner)
+            annotation = self._build_annotation(gpu, count, fraction, timeout, env, pip, uv, conda, requirements, use_uv, runner, nfs=nfs, buckets=buckets)
             code = f"{annotation}\n\n{code}"
 
         # Inject environment variables
@@ -780,7 +830,9 @@ _stream_install(
         provisioning_timeout: int = 300,
         cancel_on_timeout: bool = True,
         stream: bool = None,
-        runner: str = None
+        runner: str = None,
+        nfs: List[str] = None,
+        buckets: List[str] = None
     ) -> GPUExecutionResult:
         """
         Execute code on GPU and optionally wait for completion.
@@ -815,7 +867,7 @@ _stream_install(
             ValueError: If parameters are invalid
         """
         # Submit the code
-        submission = self.submit(code, gpu, count, fraction, timeout, env, pip, uv, conda, requirements, use_uv, env_vars=env_vars, runner=runner)
+        submission = self.submit(code, gpu, count, fraction, timeout, env, pip, uv, conda, requirements, use_uv, env_vars=env_vars, runner=runner, nfs=nfs, buckets=buckets)
         execution_id = submission.get("execution_id")
 
         if not execution_id:
@@ -1158,6 +1210,162 @@ _stream_install(
             except Exception:
                 raise RuntimeError(f"Invalid JSON response: {response.text[:200]}")
 
+    def get_runner_info(self, name: str) -> dict:
+        """
+        Get details for a specific runner by name.
+
+        Args:
+            name: Runner name (e.g. "pytorch-2.3.0-cuda-12.1-py3.11")
+
+        Returns:
+            Dict with runner details (name, type, description, image, libraries, scenarios)
+        """
+        platform_url = self._get_platform_url()
+        url = f"{platform_url}/api/v1/runners/{name}"
+
+        with httpx.Client(timeout=self.timeout) as client:
+            try:
+                response = client.get(url, headers=self._get_headers())
+            except httpx.ConnectError as e:
+                raise ConnectionError(f"Failed to connect to {url}: {e}")
+            except httpx.TimeoutException:
+                raise TimeoutError(f"Request to {url} timed out")
+
+            if response.status_code >= 400:
+                try:
+                    error_msg = response.json().get("error", response.text)
+                except Exception:
+                    error_msg = response.text[:500] if response.text else f"HTTP {response.status_code}"
+                raise RuntimeError(f"Failed to get runner info: {error_msg}")
+
+            try:
+                return response.json()
+            except Exception:
+                raise RuntimeError(f"Invalid JSON response: {response.text[:200]}")
+
+    def pip_install(
+        self,
+        packages: Union[str, list],
+        gpu: str = "L40S",
+        fraction: int = 100,
+        runner: str = None,
+        use_uv: bool = False,
+        wait: bool = True,
+        stream: bool = None,
+    ) -> GPUExecutionResult:
+        """
+        Install pip packages on a GPU runner.
+
+        Args:
+            packages: Package(s) to install — string or list of strings
+            gpu: GPU type (default: L40S)
+            fraction: GPU fraction percentage (default: 100)
+            runner: Runner name to use
+            use_uv: Use uv instead of pip (faster)
+            wait: Wait for completion (default: True)
+            stream: Stream output in real-time
+
+        Returns:
+            GPUExecutionResult object
+
+        Examples:
+            podstack.pip_install("transformers")
+            podstack.pip_install(["torch", "datasets"], gpu="A100-80G")
+            podstack.pip_install("scikit-learn", use_uv=True)
+        """
+        if isinstance(packages, str):
+            packages = [packages]
+        return self.run(
+            code="print('[Podstack] Package installation complete')",
+            gpu=gpu,
+            fraction=fraction,
+            runner=runner,
+            pip=packages,
+            use_uv=use_uv,
+            wait=wait,
+            stream=stream,
+        )
+
+    # === Deployment Management ===
+
+    def deploy_source(
+        self,
+        name: str,
+        source: str,
+        function_name: str = "predict",
+        gpu: str = "A10",
+        fraction: int = 100,
+        count: int = 1,
+        pip_packages: str = "",
+        image: str = "",
+    ) -> Dict[str, Any]:
+        """Deploy raw Python source as a REST API endpoint.
+
+        Args:
+            name: Deployment name
+            source: Python source code containing the serve function
+            function_name: Function to expose (default: predict)
+            gpu: GPU type
+            fraction: GPU fraction percentage
+            count: GPU count
+            pip_packages: Space-separated pip packages
+            image: Docker image override
+
+        Returns:
+            Deployment info dict with deployment_id and status
+        """
+        url = f"{self.api_url}/api/v1/deployments/from-source"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.post(url, headers=self._get_headers(), json={
+                "name": name,
+                "source": source,
+                "function_name": function_name,
+                "gpu_type": gpu,
+                "gpu_fraction": fraction,
+                "gpu_count": count,
+                "pip_packages": pip_packages,
+                "image": image,
+            })
+            if response.status_code >= 400:
+                raise RuntimeError(f"Failed to create deployment: {response.text}")
+            return response.json()
+
+    def get_deployment(self, deployment_id: str) -> Dict[str, Any]:
+        """Get deployment status and info."""
+        url = f"{self.api_url}/api/v1/deployments/{deployment_id}"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.get(url, headers=self._get_headers())
+            if response.status_code >= 400:
+                raise RuntimeError(f"Failed to get deployment: {response.text}")
+            return response.json()
+
+    def list_deployments(self, notebook_id: str = None) -> List[Dict[str, Any]]:
+        """List deployments for a notebook."""
+        if not notebook_id:
+            raise ValueError("notebook_id is required")
+        url = f"{self.api_url}/api/v1/notebooks/{notebook_id}/deployments"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.get(url, headers=self._get_headers())
+            if response.status_code >= 400:
+                raise RuntimeError(f"Failed to list deployments: {response.text}")
+            return response.json().get("deployments", [])
+
+    def stop_deployment(self, deployment_id: str) -> None:
+        """Stop a running deployment."""
+        url = f"{self.api_url}/api/v1/deployments/{deployment_id}/stop"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.post(url, headers=self._get_headers())
+            if response.status_code >= 400:
+                raise RuntimeError(f"Failed to stop deployment: {response.text}")
+
+    def delete_deployment(self, deployment_id: str) -> None:
+        """Delete a deployment."""
+        url = f"{self.api_url}/api/v1/deployments/{deployment_id}"
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.delete(url, headers=self._get_headers())
+            if response.status_code >= 400:
+                raise RuntimeError(f"Failed to delete deployment: {response.text}")
+
     def run_function(
         self,
         func: Callable,
@@ -1266,7 +1474,9 @@ def run(
     requirements: str = None,
     use_uv: bool = False,
     wait: bool = True,
-    stream: bool = None
+    stream: bool = None,
+    nfs: List[str] = None,
+    buckets: List[str] = None
 ) -> GPUExecutionResult:
     """
     Execute code on remote GPU.
@@ -1285,6 +1495,8 @@ def run(
         use_uv: Use uv instead of pip for all installations (faster)
         wait: Whether to wait for completion
         stream: Stream output in real-time (default: True in Jupyter, False otherwise)
+        nfs: NFS volumes to mount — ["name:/path"] or ["name"] (auto-mounts at /mnt/nfs/name)
+        buckets: Buckets to mount — ["name:/path"] or ["name"] (auto-mounts at /mnt/buckets/name)
 
     Returns:
         GPUExecutionResult object
@@ -1313,6 +1525,9 @@ def run(
 
         # Force streaming in non-Jupyter environment
         podstack.run(code, stream=True)
+
+        # Mount NFS volumes and buckets
+        podstack.run_on_gpu(code, nfs=["model-weights:/weights"], buckets=["data"])
     """
     return get_runner().run(
         code=code,
@@ -1327,7 +1542,9 @@ def run(
         requirements=requirements,
         use_uv=use_uv,
         wait=wait,
-        stream=stream
+        stream=stream,
+        nfs=nfs,
+        buckets=buckets
     )
 
 
@@ -1345,6 +1562,58 @@ def list_runners() -> RunnerList:
     return get_runner().list_runners()
 
 
+def get_runner_info(name: str) -> dict:
+    """
+    Get details for a specific runner by name.
+
+    Args:
+        name: Runner name (e.g. "pytorch-2.3.0-cuda-12.1-py3.11")
+
+    Returns:
+        Dict with runner details (name, type, description, image, libraries, scenarios)
+
+    Example:
+        info = podstack.get_runner_info("pytorch-2.3.0-cuda-12.1-py3.11")
+        print(info["libraries"])
+    """
+    return get_runner().get_runner_info(name)
+
+
+def pip_install(
+    packages: Union[str, list],
+    gpu: str = "L40S",
+    fraction: int = 100,
+    runner: str = None,
+    use_uv: bool = False,
+    wait: bool = True,
+    stream: bool = None,
+) -> GPUExecutionResult:
+    """
+    Install pip packages on a GPU runner.
+
+    Args:
+        packages: Package(s) to install — string or list of strings
+        gpu: GPU type (default: L40S)
+        fraction: GPU fraction percentage (default: 100)
+        runner: Runner name to use
+        use_uv: Use uv instead of pip (faster)
+        wait: Wait for completion (default: True)
+        stream: Stream output in real-time
+
+    Returns:
+        GPUExecutionResult object
+
+    Examples:
+        podstack.pip_install("transformers")
+        podstack.pip_install(["torch", "datasets"], gpu="A100-80G")
+        podstack.pip_install("scikit-learn", use_uv=True)
+    """
+    return get_runner().pip_install(
+        packages, gpu=gpu, fraction=fraction, runner=runner,
+        use_uv=use_uv, wait=wait, stream=stream,
+    )
+
+
 def stream_output(execution_id: str, show_output: bool = True) -> Iterator[Dict[str, Any]]:
     """
     Stream real-time output from a running execution.
@@ -1365,3 +1634,18 @@ def stream_output(execution_id: str, show_output: bool = True) -> Iterator[Dict[
                 print(f"Done!")
     """
     return get_runner().stream_output(execution_id, show_output=show_output)
+
+
+def get_deployment(deployment_id: str) -> Dict[str, Any]:
+    """Get deployment status and info."""
+    return get_runner().get_deployment(deployment_id)
+
+
+def stop_deployment(deployment_id: str) -> None:
+    """Stop a running deployment."""
+    get_runner().stop_deployment(deployment_id)
+
+
+def delete_deployment(deployment_id: str) -> None:
+    """Delete a deployment."""
+    get_runner().delete_deployment(deployment_id)