podstack 1.4.0__tar.gz → 1.7.0__tar.gz

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

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

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

@@ -54,7 +54,7 @@ Decorators:
         ...
 """
 
-__version__ = "1.4.0"
+__version__ = "1.7.0"
 
 from .client import Client
 from .notebook import Notebook, NotebookStatus
@@ -87,8 +87,13 @@ from .gpu_runner import (
     run as run_on_gpu,
     list_runners,
     get_runner_info,
+    describe_runner,
     pip_install,
 )
+# Typed runner catalog model (new in 1.7.x). Runner is a dict subclass so
+# existing dict-style access continues to work; `.describe()` / `.packages`
+# / `.filter()` on RunnerList are the new affordances.
+from .runners import Runner
 
 # Pipeline module import
 from . import pipelines
@@ -137,6 +142,50 @@ from .gpu_runner import (
     delete_deployment,
 )
 
+# Reactive cell data-transfer (Modal / Ray Jobs-style) with type dispatch.
+# Lets users write @podstack.cell(...) and have outputs auto-serialized,
+# uploaded to object storage, and auto-downloaded + deserialized in
+# downstream cells running on different GPUs.
+from . import session as _cell_session
+from .session import (
+    init_session,
+    current_session,
+    reset_session,
+    SessionConfig,
+)
+from . import serialization as cell_serialization
+from .serialization import (
+    register_serializer,
+    PayloadMeta,
+)
+from . import cell as _cell_module
+from .cell import (
+    cell,
+    CellResult,
+    CellOutputRef,
+    prune_session,
+)
+
+# Image-as-code builder (Modal-style). Users describe images in Python;
+# the backend deduplicates builds by structural hash so identical build
+# plans across users share one cached image.
+from . import image as _image_module
+from .image import Image
+
+# Agent Cloud module import
+from . import agent
+
+# Sandbox module import
+from . import sandbox
+from .sandbox import (
+    Sandbox,
+    SandboxClient,
+    SandboxError,
+    create as create_sandbox,
+    list_sandboxes,
+    get_sandbox,
+)
+
 
 def init(
     api_key: str = None,
@@ -182,6 +231,13 @@ def init(
         api_url=registry_url
     )
 
+    # Initialize sandbox
+    sandbox.init(
+        api_key=api_key,
+        project_id=project_id,
+        api_url=api_url,
+    )
+
 
 def auto_init():
     """
@@ -268,9 +324,11 @@ __all__ = [
     "GPURunner",
     "GPUExecutionResult",
     "RunnerList",
+    "Runner",
     "run_on_gpu",
     "list_runners",
     "get_runner_info",
+    "describe_runner",
     "pip_install",
     # Annotations
     "annotations",
@@ -292,4 +350,26 @@ __all__ = [
     "get_deployment",
     "stop_deployment",
     "delete_deployment",
+    # Sandbox
+    "sandbox",
+    "Sandbox",
+    "SandboxClient",
+    "SandboxError",
+    "create_sandbox",
+    "list_sandboxes",
+    "get_sandbox",
+    # Cell data transfer (reactive, cross-GPU)
+    "cell",
+    "CellResult",
+    "CellOutputRef",
+    "prune_session",
+    "init_session",
+    "current_session",
+    "reset_session",
+    "SessionConfig",
+    "cell_serialization",
+    "register_serializer",
+    "PayloadMeta",
+    # Image-as-code (Modal-style)
+    "Image",
 ]

podstack-1.7.0/podstack/agent/__init__.py

@@ -0,0 +1,105 @@
+"""
+Podstack Agent Cloud SDK
+
+Prompt-to-model generation: describe a model in natural language,
+generate training code via LLM, execute on GPU, auto-iterate, and deploy.
+
+Usage:
+    from podstack.agent import AgentClient
+
+    client = AgentClient(api_key="...", project_id="...")
+    spec = client.create_spec_from_prompt("Build a CIFAR-10 classifier with 90% accuracy")
+    gen = client.generate_code(spec.id)
+    run = client.execute_generation(gen.id)
+    endpoint = client.deploy_run(run.id)
+
+Or use module-level convenience functions:
+
+    from podstack import agent
+
+    agent.init(api_key="...", project_id="...")
+    spec = agent.create_spec_from_prompt("Build a CIFAR-10 classifier")
+"""
+
+from typing import Optional
+
+from .client import AgentClient
+from .models import (
+    AgentAction,
+    CodeGeneration,
+    IterationLog,
+    ModelGenArtifact,
+    ModelGenEndpoint,
+    ModelGenRun,
+    ModelSpec,
+)
+from .spec import ModelSpecBuilder
+from .exceptions import (
+    AgentError,
+    ExecutionError,
+    GateFailedError,
+    GenerationError,
+    IterationLimitError,
+    SpecValidationError,
+)
+
+__all__ = [
+    # Client
+    "AgentClient",
+    "ModelSpecBuilder",
+    # Models
+    "ModelSpec",
+    "CodeGeneration",
+    "ModelGenRun",
+    "ModelGenArtifact",
+    "ModelGenEndpoint",
+    "AgentAction",
+    "IterationLog",
+    # Exceptions
+    "AgentError",
+    "SpecValidationError",
+    "GateFailedError",
+    "IterationLimitError",
+    "GenerationError",
+    "ExecutionError",
+    # Module-level functions
+    "init",
+    "create_spec",
+    "create_spec_from_prompt",
+]
+
+_client: Optional[AgentClient] = None
+
+
+def _get_client() -> AgentClient:
+    global _client
+    if _client is None:
+        _client = AgentClient()
+    return _client
+
+
+def init(
+    api_url: str = None,
+    api_key: str = None,
+    project_id: str = None,
+    timeout: int = 60,
+) -> AgentClient:
+    """Initialize the module-level AgentClient singleton."""
+    global _client
+    _client = AgentClient(
+        api_url=api_url,
+        api_key=api_key,
+        project_id=project_id,
+        timeout=timeout,
+    )
+    return _client
+
+
+def create_spec(name: str, task_type: str, **kwargs) -> ModelSpec:
+    """Create a ModelSpec from structured parameters."""
+    return _get_client().create_spec(name=name, task_type=task_type, **kwargs)
+
+
+def create_spec_from_prompt(prompt: str) -> ModelSpec:
+    """Create a ModelSpec from natural language."""
+    return _get_client().create_spec_from_prompt(prompt)

podstack-1.7.0/podstack/agent/client.py

@@ -0,0 +1,308 @@
+"""
+Agent Cloud Client
+
+Client for interacting with the Podstack Agent Cloud API.
+"""
+
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .exceptions import AgentError
+from .models import (
+    AgentAction,
+    CodeGeneration,
+    IterationLog,
+    ModelGenArtifact,
+    ModelGenEndpoint,
+    ModelGenRun,
+    ModelSpec,
+)
+from ..exceptions import AuthenticationError
+
+
+class AgentClient:
+    """
+    Podstack Agent Cloud Client for prompt-to-model generation.
+
+    Usage:
+        client = AgentClient(
+            api_url="https://cloud.podstack.ai/agent-cloud",
+            api_key="your-api-key",
+            project_id="your-project-id"
+        )
+
+        # Create spec from natural language
+        spec = client.create_spec_from_prompt("Build a CIFAR-10 image classifier with 90% accuracy")
+
+        # Generate code
+        gen = client.generate_code(spec.id)
+
+        # Execute on GPU
+        run = client.execute_generation(gen.id)
+
+        # Deploy
+        endpoint = client.deploy_run(run.id)
+    """
+
+    DEFAULT_API_URL = "https://cloud.podstack.ai/agent-cloud"
+
+    def __init__(
+        self,
+        api_url: str = None,
+        api_key: str = None,
+        project_id: str = None,
+        timeout: int = 60,
+    ):
+        self.api_url = api_url or os.getenv("PODSTACK_AGENT_URL", self.DEFAULT_API_URL)
+        self.api_key = api_key or os.getenv("PODSTACK_API_KEY")
+        self.project_id = project_id or os.getenv("PODSTACK_PROJECT_ID")
+        self.timeout = timeout
+
+    def _get_headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.project_id:
+            headers["X-Project-ID"] = self.project_id
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        json: Dict[str, Any] = None,
+        params: Dict[str, Any] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.api_url}/api/v1{endpoint}"
+        headers = self._get_headers()
+
+        try:
+            response = requests.request(
+                method=method,
+                url=url,
+                headers=headers,
+                json=json,
+                params=params,
+                timeout=self.timeout,
+            )
+
+            if response.status_code == 401:
+                raise AuthenticationError("Invalid or expired API key")
+            elif response.status_code == 404:
+                error_msg = response.json().get("error", "Not found")
+                raise AgentError(error_msg, code="not_found")
+            elif response.status_code >= 400:
+                error_data = response.json() if response.content else {}
+                error_msg = error_data.get("error", f"Request failed: {response.status_code}")
+                raise AgentError(error_msg)
+
+            if response.status_code == 204 or not response.content:
+                return {}
+            return response.json()
+
+        except requests.exceptions.Timeout:
+            raise AgentError("Request timed out", code="timeout")
+        except requests.exceptions.ConnectionError:
+            raise AgentError("Connection failed — is agent-cloud service running?", code="connection")
+
+    # ── Spec methods ──────────────────────────────────────────────────────
+
+    def create_spec(
+        self,
+        name: str,
+        task_type: str,
+        data_kind: str = "",
+        task_description: str = "",
+        domain: str = "",
+        data_source: str = "",
+        data_format: str = "",
+        primary_metric: str = "",
+        minimum_thresholds: Dict[str, float] = None,
+        deploy_target: str = "api",
+        max_training_time_sec: int = 3600,
+        seed: int = 42,
+        validate_bias: bool = False,
+        validate_fairness: bool = False,
+    ) -> ModelSpec:
+        """Create a ModelSpec from structured parameters."""
+        body = {
+            "name": name,
+            "task_type": task_type,
+            "data_kind": data_kind,
+            "task_description": task_description,
+            "domain": domain,
+            "data_source": data_source,
+            "data_format": data_format,
+            "primary_metric": primary_metric,
+            "deploy_target": deploy_target,
+            "max_training_time_sec": max_training_time_sec,
+            "seed": seed,
+            "validate_bias": validate_bias,
+            "validate_fairness": validate_fairness,
+        }
+        if minimum_thresholds:
+            body["minimum_thresholds"] = minimum_thresholds
+
+        data = self._request("POST", "/specs", json=body)
+        return ModelSpec.from_dict(data.get("spec", data))
+
+    def create_spec_from_prompt(self, prompt: str) -> ModelSpec:
+        """Create a ModelSpec from a natural language prompt via LLM."""
+        data = self._request("POST", "/specs/from-prompt", json={"prompt": prompt})
+        return ModelSpec.from_dict(data.get("spec", data))
+
+    def get_spec(self, spec_id: str) -> ModelSpec:
+        """Get a spec by ID."""
+        data = self._request("GET", f"/specs/{spec_id}")
+        return ModelSpec.from_dict(data.get("spec", data))
+
+    def list_specs(self, limit: int = 20, offset: int = 0) -> List[ModelSpec]:
+        """List specs in the project."""
+        data = self._request("GET", "/specs", params={"limit": limit, "offset": offset})
+        return [ModelSpec.from_dict(s) for s in data.get("specs", [])]
+
+    def delete_spec(self, spec_id: str) -> None:
+        """Delete a spec."""
+        self._request("DELETE", f"/specs/{spec_id}")
+
+    # ── Generation methods ────────────────────────────────────────────────
+
+    def generate_code(self, spec_id: str) -> CodeGeneration:
+        """Generate training code for a spec via LLM."""
+        data = self._request("POST", f"/specs/{spec_id}/generate")
+        return CodeGeneration.from_dict(data.get("generation", data))
+
+    def get_generation(self, generation_id: str) -> CodeGeneration:
+        """Get a code generation by ID."""
+        data = self._request("GET", f"/generations/{generation_id}")
+        return CodeGeneration.from_dict(data.get("generation", data))
+
+    def execute_generation(
+        self, generation_id: str, gpu_type: str = "A100", gpu_count: int = 1
+    ) -> ModelGenRun:
+        """Execute generated code on GPU."""
+        data = self._request(
+            "POST",
+            f"/generations/{generation_id}/execute",
+            json={"gpu_type": gpu_type, "gpu_count": gpu_count},
+        )
+        return ModelGenRun.from_dict(data.get("run", data))
+
+    # ── Run methods ───────────────────────────────────────────────────────
+
+    def get_run(self, run_id: str) -> ModelGenRun:
+        """Get a run by ID."""
+        data = self._request("GET", f"/runs/{run_id}")
+        return ModelGenRun.from_dict(data.get("run", data))
+
+    def list_runs(
+        self, spec_id: str = None, status: str = None, limit: int = 20, offset: int = 0
+    ) -> List[ModelGenRun]:
+        """List runs with optional filters."""
+        params = {"limit": limit, "offset": offset}
+        if spec_id:
+            params["spec_id"] = spec_id
+        if status:
+            params["status"] = status
+        data = self._request("GET", "/runs", params=params)
+        return [ModelGenRun.from_dict(r) for r in data.get("runs", [])]
+
+    def cancel_run(self, run_id: str) -> None:
+        """Cancel a running execution."""
+        self._request("POST", f"/runs/{run_id}/cancel")
+
+    def get_run_logs(self, run_id: str) -> str:
+        """Get execution logs for a run."""
+        data = self._request("GET", f"/runs/{run_id}/logs")
+        return data.get("logs", "")
+
+    def list_artifacts(self, run_id: str) -> List[ModelGenArtifact]:
+        """List artifacts for a run."""
+        data = self._request("GET", f"/runs/{run_id}/artifacts")
+        return [ModelGenArtifact.from_dict(a) for a in data.get("artifacts", [])]
+
+    # ── Iteration methods ─────────────────────────────────────────────────
+
+    def iterate(self, run_id: str) -> IterationLog:
+        """Trigger one iteration cycle (plan -> patch -> critique -> validate -> execute)."""
+        data = self._request("POST", f"/runs/{run_id}/iterate")
+        return IterationLog.from_dict(data.get("iteration", data))
+
+    def iterate_until_success(self, run_id: str, max_iterations: int = 5) -> ModelGenRun:
+        """Auto-iterate until primary metric threshold is met or max iterations reached."""
+        from .exceptions import IterationLimitError
+
+        current_run_id = run_id
+        for i in range(max_iterations):
+            iter_log = self.iterate(current_run_id)
+            if iter_log.new_run_id:
+                new_run = self.get_run(iter_log.new_run_id)
+                if new_run.final_metric_value is not None and new_run.metric_gate_passed:
+                    return new_run
+                current_run_id = new_run.id
+
+        # Return the last run
+        last_run = self.get_run(current_run_id)
+        raise IterationLimitError(max_iterations, last_run.final_metric_value)
+
+    def list_iterations(self, run_id: str) -> List[IterationLog]:
+        """List iteration logs for a run."""
+        data = self._request("GET", f"/runs/{run_id}/iterations")
+        return [IterationLog.from_dict(i) for i in data.get("iterations", [])]
+
+    # ── Deployment methods ────────────────────────────────────────────────
+
+    def run_gates(self, run_id: str) -> Dict[str, bool]:
+        """Run all 5 deployment gates and return pass/fail per gate."""
+        data = self._request("POST", f"/runs/{run_id}/gates")
+        gates = data.get("gates", [])
+        return {g["gate"]: g["passed"] for g in gates}
+
+    def deploy_run(
+        self, run_id: str, name: str = None, replicas: int = 1
+    ) -> ModelGenEndpoint:
+        """Deploy a run as an API endpoint (runs gates first)."""
+        body = {"replicas": replicas}
+        if name:
+            body["name"] = name
+        data = self._request("POST", f"/runs/{run_id}/deploy", json=body)
+        return ModelGenEndpoint.from_dict(data.get("endpoint", data))
+
+    def predict(self, endpoint_id: str, input_data: Any) -> Any:
+        """Make a prediction via a deployed endpoint."""
+        data = self._request("POST", f"/endpoints/{endpoint_id}/predict", json=input_data)
+        return data.get("prediction", data)
+
+    def get_endpoint(self, endpoint_id: str) -> ModelGenEndpoint:
+        """Get endpoint details."""
+        data = self._request("GET", f"/endpoints/{endpoint_id}")
+        return ModelGenEndpoint.from_dict(data.get("endpoint", data))
+
+    def list_endpoints(self, limit: int = 20, offset: int = 0) -> List[ModelGenEndpoint]:
+        """List all endpoints."""
+        data = self._request("GET", "/endpoints", params={"limit": limit, "offset": offset})
+        return [ModelGenEndpoint.from_dict(e) for e in data.get("endpoints", [])]
+
+    def stop_endpoint(self, endpoint_id: str) -> None:
+        """Stop an active endpoint."""
+        self._request("POST", f"/endpoints/{endpoint_id}/stop")
+
+    def delete_endpoint(self, endpoint_id: str) -> None:
+        """Delete an endpoint."""
+        self._request("DELETE", f"/endpoints/{endpoint_id}")
+
+    # ── Observability ─────────────────────────────────────────────────────
+
+    def list_actions(
+        self, spec_id: str = None, run_id: str = None, limit: int = 50, offset: int = 0
+    ) -> List[AgentAction]:
+        """Query the agent audit trail."""
+        params = {"limit": limit, "offset": offset}
+        if spec_id:
+            params["spec_id"] = spec_id
+        if run_id:
+            params["run_id"] = run_id
+        data = self._request("GET", "/actions", params=params)
+        return [AgentAction.from_dict(a) for a in data.get("actions", [])]

podstack-1.7.0/podstack/agent/exceptions.py

@@ -0,0 +1,56 @@
+"""
+Agent Cloud Exception Classes
+
+Custom exceptions for the Podstack Agent Cloud SDK.
+"""
+
+from ..exceptions import PodstackError
+
+
+class AgentError(PodstackError):
+    """Base exception for agent cloud errors."""
+
+    def __init__(self, message: str, code: str = "agent_error"):
+        super().__init__(message, code=code)
+
+
+class SpecValidationError(AgentError):
+    """Raised when a model spec fails validation."""
+
+    def __init__(self, message: str):
+        super().__init__(message, code="spec_validation_error")
+
+
+class GateFailedError(AgentError):
+    """Raised when a deployment gate check fails."""
+
+    def __init__(self, gate: str, message: str):
+        super().__init__(f"Gate '{gate}' failed: {message}", code="gate_failed")
+        self.gate = gate
+
+
+class IterationLimitError(AgentError):
+    """Raised when the maximum iteration count is reached without meeting thresholds."""
+
+    def __init__(self, max_iterations: int, best_metric: float = None):
+        msg = f"Maximum iterations ({max_iterations}) reached"
+        if best_metric is not None:
+            msg += f" — best metric value: {best_metric:.4f}"
+        super().__init__(msg, code="iteration_limit")
+        self.max_iterations = max_iterations
+        self.best_metric = best_metric
+
+
+class GenerationError(AgentError):
+    """Raised when code generation fails."""
+
+    def __init__(self, message: str):
+        super().__init__(message, code="generation_error")
+
+
+class ExecutionError(AgentError):
+    """Raised when GPU execution fails."""
+
+    def __init__(self, message: str, run_id: str = None):
+        super().__init__(message, code="execution_error")
+        self.run_id = run_id