levers9 0.1.265__py3-none-any.whl

levers9/__init__.py

@@ -0,0 +1,77 @@
+from importlib import import_module
+
+
+_EXPORTS = {
+    "Map": (".abstractions.map", "Map"),
+    "Image": (".abstractions.image", "Image"),
+    "Queue": (".abstractions.queue", "SimpleQueue"),
+    "Volume": (".abstractions.volume", "Volume"),
+    "CloudBucket": (".abstractions.volume", "CloudBucket"),
+    "CloudBucketConfig": (".abstractions.volume", "CloudBucketConfig"),
+    "task_queue": (".abstractions.taskqueue", "TaskQueue"),
+    "function": (".abstractions.function", "Function"),
+    "endpoint": (".abstractions.endpoint", "Endpoint"),
+    "asgi": (".abstractions.endpoint", "ASGI"),
+    "realtime": (".abstractions.endpoint", "RealtimeASGI"),
+    "Container": (".abstractions.base.container", "Container"),
+    "env": (".env", None),
+    "GpuType": (".type", "GpuType"),
+    "DatabaseServingConfig": (".type", "DatabaseServingConfig"),
+    "DurableDisk": (".type", "DurableDisk"),
+    "LLMConfig": (".type", "LLMConfig"),
+    "LLMTokenPressureAutoscaler": (".type", "LLMTokenPressureAutoscaler"),
+    "Pool": (".type", "Pool"),
+    "PythonVersion": (".type", "PythonVersion"),
+    "Output": (".abstractions.output", "Output"),
+    "QueueDepthAutoscaler": (".type", "QueueDepthAutoscaler"),
+    "ServingConfig": (".type", "ServingConfig"),
+    "experimental": (".abstractions.experimental", None),
+    "integrations": (".abstractions.integrations", None),
+    "schedule": (".abstractions.function", "Schedule"),
+    "TaskPolicy": (".type", "TaskPolicy"),
+    "Bot": (".abstractions.experimental.bot.bot", "Bot"),
+    "BotLocation": (".abstractions.experimental.bot.bot", "BotLocation"),
+    "BotEventType": (".abstractions.experimental.bot.bot", "BotEventType"),
+    "BotContext": (".abstractions.experimental.bot.types", "BotContext"),
+    "Pod": (".abstractions.pod", "Pod"),
+    "Service": (".abstractions.service", "Service"),
+    "PricingPolicy": (".type", "PricingPolicy"),
+    "PricingPolicyCostModel": (".type", "PricingPolicyCostModel"),
+    "Client": (".client.client", "Client"),
+    "Task": (".client.task", "Task"),
+    "Deployment": (".client.deployment", "Deployment"),
+    "schema": (".schema", None),
+    "Sandbox": (".abstractions.sandbox", "Sandbox"),
+    "SandboxInstance": (".abstractions.sandbox", "SandboxInstance"),
+    "SandboxProcess": (".abstractions.sandbox", "SandboxProcess"),
+    "SandboxProcessStream": (".abstractions.sandbox", "SandboxProcessStream"),
+    "SandboxProcessManager": (".abstractions.sandbox", "SandboxProcessManager"),
+    "SandboxProcessResponse": (".abstractions.sandbox", "SandboxProcessResponse"),
+    "SandboxConnectionError": (".abstractions.sandbox", "SandboxConnectionError"),
+    "SandboxProcessError": (".abstractions.sandbox", "SandboxProcessError"),
+    "SandboxFileSystemError": (".abstractions.sandbox", "SandboxFileSystemError"),
+    "SandboxFilePosition": (".abstractions.sandbox", "SandboxFilePosition"),
+    "SandboxFileSearchRange": (".abstractions.sandbox", "SandboxFileSearchRange"),
+    "SandboxFileSearchMatch": (".abstractions.sandbox", "SandboxFileSearchMatch"),
+    "SandboxFileInfo": (".abstractions.sandbox", "SandboxFileInfo"),
+    "SandboxFileSystem": (".abstractions.sandbox", "SandboxFileSystem"),
+    "SandboxFileSearchResult": (".abstractions.sandbox", "SandboxFileSearchResult"),
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name):
+    try:
+        module_name, attribute = _EXPORTS[name]
+    except KeyError as error:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from error
+
+    module = import_module(module_name, __name__)
+    value = module if attribute is None else getattr(module, attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted((*globals(), *__all__))

levers9/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main.start()

levers9/abstractions/base/__init__.py

@@ -0,0 +1,77 @@
+import os
+
+os.environ["GRPC_VERBOSITY"] = os.getenv("GRPC_VERBOSITY") or "NONE"
+
+import sys
+from abc import ABC
+from typing import Optional
+
+from ...channel import Channel
+from ...channel import get_channel as _get_channel
+from ...config import ConfigContext, get_config_context, set_settings
+
+# Global channel
+_channel: Optional[Channel] = None
+
+
+def set_channel(
+    channel: Optional[Channel] = None,
+    context: Optional[ConfigContext] = None,
+) -> None:
+    """
+    Sets the channel globally for the SDK.
+
+    Use this before importing any abstraction to control which
+    gateway to connect to. When you provide a channel, it should already be
+    authenticated. When you provide a context, this will authenticate for you.
+    If neither is provided, this uses the default context and will create a
+    channel. If there is no default context (or config file), then we will
+    prompt the user for it.
+
+    Args:
+        channel: gRPC channel. Defaults to None.
+        context: Config context that defines the channel credentials. Defaults to None.
+    """
+    global _channel
+
+    if channel:
+        _channel = channel
+        return
+
+    if context:
+        _channel = _get_channel(context)
+        return
+
+    context = get_config_context()
+    _channel = _get_channel(context)
+
+
+def unset_channel():
+    global _channel
+    _channel = None
+
+
+def get_channel() -> Channel:
+    global _channel
+
+    if not _channel:
+        set_channel()
+
+    return _channel  # type: ignore
+
+
+class BaseAbstraction(ABC):
+    @property
+    def channel(self) -> Channel:
+        return get_channel()
+
+    def __init_subclass__(cls, /, **kwargs):
+        """
+        Dynamically load settings depending on if this library is being used
+        by levers9 or beam.
+        """
+        if "beam" in sys.modules:
+            # Settings will be configured in SDKSettings.__post_init__
+            set_settings()
+
+        super().__init_subclass__(**kwargs)

levers9/abstractions/base/capacity.py

@@ -0,0 +1,503 @@
+"""
+Interactive capacity flow.
+
+When stub creation reports that no serverless pool supports the requested GPU
+(a guaranteed scheduling blackhole), this module lets the user launch
+on-demand hardware from the compute marketplace and routes the workload onto
+it — or fails fast with an actionable error in headless environments.
+"""
+
+import time
+from typing import TYPE_CHECKING, List, Optional
+
+from ... import terminal
+from ...clients.gateway import (
+    GetOrCreateStubRequest,
+    GetOrCreateStubResponse,
+    ListPoolOffersRequest,
+    ListPrivatePoolsRequest,
+    PoolConfig,
+    PoolOffer,
+)
+
+if TYPE_CHECKING:
+    from .runner import RunnerAbstraction
+
+CAPACITY_STATUS_AVAILABLE = "available"
+CAPACITY_STATUS_LOW = "low"
+CAPACITY_STATUS_NONE = "none"
+
+DEFAULT_ONDEMAND_TTL = "1h"
+DEFAULT_ONDEMAND_NODES = 1
+# "Indefinite" reservations: the control plane requires a TTL and spend cap
+# on every reservation, so manual-spindown mode reserves a 30-day window the
+# user releases early with 'levers9 machine release' (or extends with
+# 'levers9 pool extend').
+INDEFINITE_TTL = "720h"
+MAX_OFFER_CHOICES = 10
+PROVISION_TIMEOUT_S = 15 * 60
+PROVISION_POLL_INTERVAL_S = 5
+
+
+def requested_gpus(stub_request: GetOrCreateStubRequest) -> List[str]:
+    return [g for g in (stub_request.gpu or "").split(",") if g and g != "NO_GPU"]
+
+
+def cli_name() -> str:
+    """The installed CLI executable name ("levers9" or "beam"), for command hints."""
+    from ...config import get_settings
+
+    return (get_settings().name or "levers9").lower()
+
+
+def no_capacity_hint(gpus: List[str]) -> str:
+    gpu = gpus[0] if gpus else "<gpu>"
+    return (
+        f"run '{cli_name()} machine reserve --gpu {gpu}' to get hardware, or pick a different GPU"
+    )
+
+
+def no_offers_hint() -> str:
+    cli = cli_name()
+    return (
+        f"browse available GPUs with '{cli} machine list', "
+        f"or attach your own machine with '{cli} pool join'"
+    )
+
+
+def credits_url() -> Optional[str]:
+    """
+    The dashboard credits page, derived from the SDK's API host so the link
+    follows the environment (app.beam.cloud -> platform.beam.cloud,
+    app.stage.beam.cloud -> platform.stage.beam.cloud). Self-hosted installs
+    have no credits page, so hosts without the app. prefix return None.
+    """
+    from ...config import get_settings
+
+    host = (get_settings().api_host or "").split(":")[0]
+    if host.startswith("app."):
+        return f"https://platform.{host[len('app.') :]}/settings/credits"
+    return None
+
+
+def credit_error_hint(message: str) -> Optional[str]:
+    """A purchase link for credit-related failures; None for everything else."""
+    url = credits_url()
+    if url and "credit" in (message or "").lower():
+        return f"purchase credits at {url}"
+    return None
+
+
+def launch_failure_hint(
+    err_msg: str,
+    error_code: str = "",
+    required_cents: int = 0,
+    available_cents: int = 0,
+) -> Optional[str]:
+    """Actionable hint for a failed capacity launch; currently credit-focused."""
+    if "credit" not in (error_code or "") and not credit_error_hint(err_msg):
+        return None
+
+    parts = []
+    if required_cents:
+        parts.append(
+            f"requires ${required_cents / 100:.2f} in credit, you have ${available_cents / 100:.2f}"
+        )
+    if url := credits_url():
+        parts.append(f"purchase credits at {url}")
+    return " — ".join(parts) or None
+
+
+def offer_hardware_label(offer: PoolOffer, nodes: int = 1) -> str:
+    """Human label for an offer's hardware, e.g. '2 nodes of 4x A6000'."""
+    gpu_count = offer.gpu_count or 1
+    hardware = (
+        f"{gpu_count}x {offer.gpu}"
+        if offer.gpu
+        else (offer.display_name or offer.instance_type or "CPU node")
+    )
+    if nodes > 1:
+        hardware = f"{nodes} nodes of {hardware}"
+    return hardware
+
+
+def no_offers_error(gpu_label: str) -> None:
+    terminal.error(
+        f"No on-demand offers currently available for {gpu_label}.",
+        exit=False,
+        hint=no_offers_hint(),
+    )
+
+
+def _runner_interactive(runner: "RunnerAbstraction") -> bool:
+    return terminal.is_interactive() and not getattr(runner, "headless", False)
+
+
+def handle_capacity_verdict(
+    runner: "RunnerAbstraction",
+    stub_request: GetOrCreateStubRequest,
+    stub_response: GetOrCreateStubResponse,
+    stub_type: str,
+) -> Optional[GetOrCreateStubResponse]:
+    """
+    Reacts to the capacity verdict on a stub creation response. Returns the
+    response to continue with, or None when the workload should not proceed.
+    """
+    if not stub_response.ok:
+        return stub_response
+
+    # An explicit pool config is the user's placement choice; don't second-guess it.
+    if runner.pool_config is not None:
+        return stub_response
+
+    if stub_response.matched_private_pool:
+        return _attach_to_private_pool(runner, stub_request, stub_response)
+
+    if stub_response.capacity_status != CAPACITY_STATUS_NONE:
+        return stub_response
+
+    gpus = requested_gpus(stub_request)
+    gpu_label = ", ".join(gpus) if gpus else "the requested GPU"
+
+    if stub_type.endswith("/deployment"):
+        return _handle_deployment_capacity(runner, stub_request, stub_response, gpus, gpu_label)
+
+    if _runner_interactive(runner):
+        return _run_interactive_capacity_flow(
+            runner,
+            stub_request,
+            gpus,
+            gpu_label,
+            wait_for_ready=stub_type != "pod/run",
+        )
+
+    terminal.error(
+        f"No compute capacity supports {gpu_label}, so this workload can never be scheduled.",
+        exit=False,
+        hint=no_capacity_hint(gpus),
+    )
+    return None
+
+
+def _handle_deployment_capacity(
+    runner: "RunnerAbstraction",
+    stub_request: GetOrCreateStubRequest,
+    stub_response: GetOrCreateStubResponse,
+    gpus: List[str],
+    gpu_label: str,
+) -> Optional[GetOrCreateStubResponse]:
+    """
+    Deployments are long-lived and capacity is dynamic. Interactively the
+    best path is to reserve on-demand hardware and pin the deployment to
+    that pool; alternatively the user can deploy anyway (requests fail fast
+    with a clear reason until capacity is attached, then start succeeding
+    with no redeploy). Headless deploys warn and proceed — CI never blocks.
+    """
+    terminal.warn(f"No compute capacity currently supports {gpu_label}.")
+
+    if not _runner_interactive(runner):
+        terminal.detail(f"  hint: {no_capacity_hint(gpus)}")
+        return stub_response
+
+    try:
+        choice = terminal.select(
+            "How do you want to proceed?",
+            [
+                terminal.SelectOption(
+                    label="Reserve on-demand hardware",
+                    value="reserve",
+                    description="pins this deployment to the reserved machine",
+                ),
+                terminal.SelectOption(
+                    label="Deploy anyway",
+                    value="deploy",
+                    description="requests fail until capacity is attached",
+                ),
+                terminal.SelectOption(label="Cancel", value="cancel"),
+            ],
+        )
+    except KeyboardInterrupt:
+        choice = "cancel"
+
+    if choice == "reserve":
+        return _run_interactive_capacity_flow(runner, stub_request, gpus, gpu_label, announce=False)
+    if choice == "cancel":
+        # Cancelling is not a failure.
+        terminal.detail("Deployment cancelled.")
+        raise SystemExit(0)
+    return stub_response
+
+
+def _attach_to_private_pool(
+    runner: "RunnerAbstraction",
+    stub_request: GetOrCreateStubRequest,
+    stub_response: GetOrCreateStubResponse,
+) -> GetOrCreateStubResponse:
+    pool_name = stub_response.matched_private_pool
+    pool = PoolConfig(name=pool_name, selector=pool_name)
+
+    terminal.print(
+        f"[bold {terminal.BRAND_COLOR}]=>[/bold {terminal.BRAND_COLOR}] "
+        f"No serverless capacity for this GPU — using your pool [bold]{pool_name}[/bold]"
+    )
+
+    stub_request.pool = pool
+    response = runner.gateway_stub.get_or_create_stub(stub_request)
+    if response.ok:
+        runner.pool_config = pool
+    return response
+
+
+def _run_interactive_capacity_flow(
+    runner: "RunnerAbstraction",
+    stub_request: GetOrCreateStubRequest,
+    gpus: List[str],
+    gpu_label: str,
+    announce: bool = True,
+    wait_for_ready: bool = True,
+) -> Optional[GetOrCreateStubResponse]:
+    if announce:
+        terminal.warn(f"No serverless capacity for {gpu_label}.")
+
+    offers = fetch_offers(runner.gateway_stub, gpus)
+    if offers is None:
+        return None
+    if not offers:
+        no_offers_error(gpu_label)
+        return None
+
+    try:
+        offer = terminal.select(
+            "Launch on-demand hardware to run this workload?",
+            offer_options(offers),
+        )
+        if offer is None:
+            return None
+
+        hourly = offer.hourly_cost_micros / 1_000_000
+        ttl = select_ttl(hourly)
+        if not terminal.confirm(
+            f"Launch {offer_hardware_label(offer)} for ~${hourly:.2f}/hr ({ttl_label(ttl)})?",
+            default=True,
+        ):
+            return None
+    except KeyboardInterrupt:
+        terminal.detail("Cancelled.")
+        return None
+
+    pool = pool_config_for_offer(offer, ttl=ttl)
+    stub_request.pool = pool
+
+    response = runner.gateway_stub.get_or_create_stub(stub_request)
+    if not response.ok:
+        return response
+    runner.pool_config = pool
+
+    if wait_for_ready and not wait_for_pool_ready(runner.gateway_stub, pool.name):
+        return None
+    return response
+
+
+def fetch_offers(
+    gateway_stub, gpus: List[str], limit: int = MAX_OFFER_CHOICES
+) -> Optional[List[PoolOffer]]:
+    """Fetch on-demand offers sorted by price; None indicates a fetch error."""
+    with terminal.progress("Finding available hardware..."):
+        res = gateway_stub.list_pool_offers(ListPoolOffersRequest(pool=PoolConfig(gpu=gpus)))
+    if not res.ok:
+        terminal.error(f"Failed to list hardware offers: {res.err_msg}", exit=False)
+        return None
+
+    offers = list(res.offers)
+    offers.sort(key=lambda o: o.hourly_cost_micros)
+    if limit > 0:
+        offers = offers[:limit]
+    return offers
+
+
+def _offer_columns(offer: PoolOffer) -> tuple:
+    hourly = offer.hourly_cost_micros / 1_000_000
+    region = offer.region_display_name or offer.region or "any region"
+    hardware = offer_hardware_label(offer)
+    details = []
+    if offer.cpu_millicores:
+        details.append(f"{offer.cpu_millicores // 1000} vCPU")
+    if offer.memory_mb:
+        details.append(f"{offer.memory_mb // 1024}GB RAM")
+    if offer.reliability:
+        details.append(f"{offer.reliability * 100:.0f}% reliability")
+    return hardware, region, f"${hourly:.2f}/hr", ", ".join(details)
+
+
+def offer_options(offers: List[PoolOffer]) -> List[terminal.SelectOption]:
+    """
+    Build select options with the hardware/region/price columns padded to
+    equal widths across all offers, so the picker reads like a table.
+    """
+    rows = [_offer_columns(o) for o in offers]
+    widths = [max(len(row[i]) for row in rows) for i in range(3)] if rows else [0, 0, 0]
+    return [
+        terminal.SelectOption(
+            label=f"{hardware:<{widths[0]}}  {region:<{widths[1]}}  {price:>{widths[2]}}",
+            value=offer,
+            description=details,
+        )
+        for offer, (hardware, region, price, details) in zip(offers, rows)
+    ]
+
+
+def pool_config_for_offer(
+    offer: PoolOffer,
+    name: str = "",
+    nodes: int = DEFAULT_ONDEMAND_NODES,
+    ttl: str = DEFAULT_ONDEMAND_TTL,
+    max_spend: float = 0.0,
+) -> PoolConfig:
+    hourly = offer.hourly_cost_micros / 1_000_000
+    if max_spend <= 0:
+        # Cover the TTL with headroom so billing reconciliation never kills
+        # the node mid-session; the TTL is what actually bounds the spend.
+        # Long/indefinite reservations get a slimmer buffer so the cap stays
+        # a sane guardrail rather than a blank check.
+        hours = max(1.0, ttl_hours(ttl))
+        buffer = 2.0 if hours <= 24 else 1.25
+        max_spend = max(1.0, round(hourly * nodes * hours * buffer, 2))
+    pool_name = _sanitize_pool_name(name or f"ondemand-{offer.gpu or 'cpu'}")
+    return PoolConfig(
+        name=pool_name,
+        selector=pool_name,
+        gpu=[offer.gpu] if offer.gpu else [],
+        nodes=nodes,
+        ttl=ttl,
+        max_spend=max_spend,
+        providers=[offer.provider] if offer.provider else [],
+        offer_id=offer.id,
+    )
+
+
+def ttl_hours(ttl: str) -> float:
+    value = (ttl or "").strip().lower()
+    try:
+        if value.endswith("h"):
+            return float(value[:-1])
+        if value.endswith("m"):
+            return float(value[:-1]) / 60
+        if value.endswith("d"):
+            return float(value[:-1]) * 24
+        return float(value)
+    except ValueError:
+        return 1.0
+
+
+def ttl_label(ttl: str) -> str:
+    if ttl == INDEFINITE_TTL:
+        return "runs until you release it (30d cap)"
+    return f"expires in {ttl}"
+
+
+def valid_ttl(ttl: str) -> bool:
+    value = (ttl or "").strip().lower()
+    if len(value) < 2 or value[-1] not in "mhd":
+        return False
+    try:
+        return float(value[:-1]) > 0
+    except ValueError:
+        return False
+
+
+TTL_CHOICES = ["1h", "2h", "4h", "8h", "24h"]
+
+
+def select_ttl(hourly: float, nodes: int = 1, default: str = DEFAULT_ONDEMAND_TTL) -> str:
+    """
+    Interactive duration picker with the projected cost per choice. Falls
+    back to the default duration when the terminal isn't interactive.
+    """
+    if not terminal.is_interactive():
+        return default
+
+    options = [
+        terminal.SelectOption(
+            label="until I stop it",
+            value=INDEFINITE_TTL,
+            description=f"~${hourly * nodes:.2f}/hr until '{cli_name()} machine release' (30d cap)",
+        )
+    ]
+    for ttl in TTL_CHOICES:
+        cost = hourly * nodes * ttl_hours(ttl)
+        options.append(terminal.SelectOption(label=f"{ttl:<12}  ~${cost:.2f}", value=ttl))
+    options.append(terminal.SelectOption(label="other", value="", description="custom duration"))
+
+    choice = terminal.select("How long do you need it?", options)
+    if choice:
+        return choice
+
+    while True:
+        raw = str(terminal.prompt(text="Duration (e.g. 45m, 6h, 2d)", default=default))
+        if valid_ttl(raw):
+            return raw
+        terminal.warn("Use a number with a unit: 45m, 6h, or 2d.")
+
+
+def _sanitize_pool_name(value: str) -> str:
+    out = "".join(c if (c.isalnum() or c in "-._") else "-" for c in value.lower())
+    return out.strip("-._") or "ondemand"
+
+
+def wait_for_pool_ready(
+    gateway_stub,
+    pool_name: str,
+    timeout_s: int = PROVISION_TIMEOUT_S,
+) -> bool:
+    """
+    Block with live progress until the pool has at least one ready machine.
+    Milestones (reservation → booting → ready) print with elapsed times as
+    they are observed.
+    """
+    start = time.monotonic()
+    milestones_seen = set()
+
+    def milestone(name: str, label: str):
+        if name in milestones_seen:
+            return
+        milestones_seen.add(name)
+        terminal.print(
+            f"[bold green]✓[/bold green] {label} [dim]({time.monotonic() - start:.0f}s)[/dim]"
+        )
+
+    try:
+        with terminal.progress("Provisioning node...") as status:
+            while time.monotonic() - start < timeout_s:
+                pool = _find_pool(gateway_stub, pool_name)
+                if pool is not None:
+                    if pool.reservations or pool.reserved_nodes > 0:
+                        milestone("reserved", "Node reserved")
+                        status.update("Waiting for instance to boot...")
+                    if pool.machine_count > 0:
+                        milestone("joined", "Machine online, agent joined")
+                        status.update("Waiting for machine to become ready...")
+                    if pool.ready_machine_count > 0:
+                        milestone("ready", "Machine ready")
+                        return True
+                time.sleep(PROVISION_POLL_INTERVAL_S)
+    except KeyboardInterrupt:
+        terminal.warn(f"Interrupted; pool '{pool_name}' keeps provisioning in the background.")
+        terminal.detail(f"  hint: check progress with '{cli_name()} pool machines {pool_name}'")
+        return False
+
+    terminal.error(
+        f"Timed out waiting for pool '{pool_name}' to become ready; it may still be provisioning.",
+        exit=False,
+        hint=f"check progress with '{cli_name()} pool machines {pool_name}' and re-run once a machine is ready",
+    )
+    return False
+
+
+def _find_pool(gateway_stub, pool_name: str):
+    res = gateway_stub.list_private_pools(ListPrivatePoolsRequest())
+    if not res.ok:
+        return None
+    for pool in res.pools:
+        if pool.name == pool_name or pool.selector == pool_name:
+            return pool
+    return None