runbios-sdk 0.2.2__py3-none-any.whl

bios/__init__.py

@@ -0,0 +1,172 @@
+"""
+bios -- Official Python SDK for the Run BiOS fine-tuning platform.
+
+Usage::
+
+    from bios import RunBiOS
+
+    client = RunBiOS(api_key="bios-...")
+
+    # Search for models
+    models = client.models.search(query="llama")
+
+    # Create a training job
+    job = client.training.create(
+        model="meta-llama/Llama-3.1-8B-Instruct",
+        dataset_id="ds_abc123",
+        method="sft",
+        adapter="lora",
+    )
+"""
+
+import os
+from typing import Optional
+
+from ._client import ApiError, HttpClient, VERSION
+from ._types import ApiKeyIntrospection
+from .errors import (
+    CAPACITY_UNAVAILABLE_CODE,
+    COMING_SOON_CODES,
+    GPU_REJECTION_CODE_BY_REASON,
+    GPU_REJECTION_CODES,
+    PERMANENT_GPU_CODES,
+    PERMANENT_GPU_REASONS,
+    CapacityUnavailableError,
+    ComingSoonError,
+    MinGpuCountError,
+    gpu_rejection_code_for_reason,
+    is_permanent_gpu_code,
+    is_permanent_gpu_reason,
+)
+from .models import Models
+from .datasets import Datasets
+from .integrations import Integrations
+from .training import Training
+from .wallet import Wallet
+from .gpu import GPU
+from .loop import Loop
+from .inference import Inference
+
+
+__version__ = VERSION
+__all__ = [
+    "RunBiOS",
+    "BiOS",
+    "ApiError",
+    "CapacityUnavailableError",
+    "ComingSoonError",
+    "MinGpuCountError",
+    "CAPACITY_UNAVAILABLE_CODE",
+    "COMING_SOON_CODES",
+    "PERMANENT_GPU_CODES",
+    "PERMANENT_GPU_REASONS",
+    "GPU_REJECTION_CODES",
+    "GPU_REJECTION_CODE_BY_REASON",
+    "is_permanent_gpu_code",
+    "is_permanent_gpu_reason",
+    "gpu_rejection_code_for_reason",
+    "VERSION",
+    "Models",
+    "Datasets",
+    "Integrations",
+    "Training",
+    "Wallet",
+    "GPU",
+    "Loop",
+    "Inference",
+]
+
+
+class RunBiOS:
+    """Main client for the Run BiOS API.
+
+    Create an instance with either an API key or a JWT access token,
+    then use the resource properties to interact with the API. When
+    ``api_key``, ``base_url``, or ``inference_key`` is omitted, the
+    ``RUNBIOS_API_KEY``, ``RUNBIOS_BASE_URL``, and ``RUNBIOS_INFERENCE_KEY``
+    environment variables are used as defaults (the legacy ``BIOS_API_KEY``,
+    ``BIOS_BASE_URL``, and ``BIOS_INFERENCE_KEY`` names are still accepted).
+    ``inference_key`` falls back to ``api_key`` last, so a platform key with
+    the serverless scope calls ``/v1`` without being passed twice.
+
+    Example with API key::
+
+        client = RunBiOS(api_key="bios-...")
+
+    Example with JWT::
+
+        client = RunBiOS(access_token="eyJhbG...", org_id="org_abc123")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        access_token: Optional[str] = None,
+        org_id: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        inference_key: Optional[str] = None,
+        inference_base_url: Optional[str] = None,
+        inference_timeout: Optional[float] = None,
+    ) -> None:
+        http = HttpClient(
+            api_key=api_key,
+            access_token=access_token,
+            org_id=org_id,
+            workspace_id=workspace_id,
+            base_url=base_url,
+            timeout=timeout,
+        )
+        self._http = http
+
+        self.models: Models = Models(http)
+        """Search models, fetch configs, check adapter compatibility."""
+
+        self.datasets: Datasets = Datasets(http)
+        """Upload, import, preview, and manage training datasets."""
+
+        self.integrations: Integrations = Integrations(http)
+
+        self.training: Training = Training(http)
+        """Create, monitor, stop, and resume fine-tuning jobs."""
+
+        self.wallet: Wallet = Wallet(http)
+        """View wallet balance and transaction history."""
+
+        self.gpu: GPU = GPU(http)
+        #: The Conscious Loop. Capture what your model was asked and answered,
+        #: record whether it was right, and turn those judgements into training
+        #: data. Nothing is captured until you turn it on for a source.
+        self.loop: Loop = Loop(http)
+        """View GPU pricing and get hardware recommendations."""
+
+        # Inference-key resolution, most specific first:
+        #   1. an explicit inference_key (a per-deployment sk-bios-... key)
+        #   2. RUNBIOS_INFERENCE_KEY (legacy BIOS_INFERENCE_KEY) from the environment
+        #   3. the control-plane api_key / RUNBIOS_API_KEY (legacy BIOS_API_KEY)
+        # (3) exists because a workspace platform key carrying the serverless
+        # scope calls /v1 directly, so RunBiOS(api_key=K).inference.chat_completions()
+        # must work without passing the same key twice.
+        self.inference: Inference = Inference(
+            inference_key=(
+                inference_key
+                or os.environ.get("RUNBIOS_INFERENCE_KEY")
+                or os.environ.get("BIOS_INFERENCE_KEY")
+                or api_key
+                or os.environ.get("RUNBIOS_API_KEY")
+                or os.environ.get("BIOS_API_KEY")
+            ),
+            base_url=inference_base_url or base_url,
+            timeout=inference_timeout,
+            http=http,
+        )
+        """Validate, create, monitor, stop, and delete model deployments, and
+        call OpenAI-compatible endpoints without automatic retries."""
+
+    def introspect(self) -> ApiKeyIntrospection:
+        """Introspect the current API key to discover its permissions."""
+        return self._http.get("/api/api-keys/introspect")
+
+
+BiOS = RunBiOS  # deprecated alias

bios/_client.py

@@ -0,0 +1,238 @@
+"""HTTP client for the Run BiOS API."""
+
+import os
+from typing import Any, Dict, Optional, Tuple
+
+import requests
+
+VERSION = "0.2.2"
+
+
+class ApiError(Exception):
+    """Typed error raised when the API returns a non-2xx status."""
+
+    def __init__(self, status: int, body: Dict[str, Any]) -> None:
+        err = body.get("error")
+        nested = err if isinstance(err, dict) else None
+        msg = (
+            body.get("detail")
+            or (
+                str(nested.get("message") or nested.get("detail") or "")
+                if nested
+                else ""
+            )
+            or (err if isinstance(err, str) else "")
+            or body.get("message")
+            or "API error {}".format(status)
+        )
+        super().__init__(msg)
+        self.status: int = status
+        self.code: Optional[str] = (
+            str(nested["code"]) if nested and nested.get("code") else body.get("code")
+        ) or None
+        self.request_id: Optional[str] = body.get("request_id")
+        self.message: str = msg
+        # The full parsed error body: structured fields (available_gpus,
+        # minimum_requirement, checked_at, ...) must survive for typed
+        # subclasses and for callers that need more than code/message.
+        self.body: Dict[str, Any] = body
+
+
+def _error_code(body: Dict[str, Any]) -> Optional[str]:
+    err = body.get("error")
+    nested = err if isinstance(err, dict) else None
+    return (
+        (str(nested["code"]) if nested and nested.get("code") else body.get("code"))
+        or None
+    )
+
+
+def _build_api_error(status: int, body: Dict[str, Any]) -> ApiError:
+    """Map a non-2xx body to the most specific typed exception available.
+
+    The service is the authority: every GPU-rejection code becomes the typed
+    :class:`~bios.errors.CapacityUnavailableError` so callers can read its
+    ``.alternatives`` / ``.minimum_requirement`` without string-matching. That
+    is the transient ``CAPACITY_UNAVAILABLE`` 409 AND the four permanent 400s
+    (``GPU_TYPE_TOO_SMALL``, ``GPU_COUNT_BELOW_MINIMUM``, ``GPU_COUNT_INVALID``,
+    ``GPU_TYPE_UNSUPPORTED``), which carry the same body and the same recovery
+    data, so one ``except`` still catches all of them. Read ``.permanent`` to
+    tell "wait for stock" apart from "pick a different GPU type or count".
+    Everything else stays ``ApiError``.
+    """
+    code = _error_code(body)
+    if code is not None:
+        # Lazy import avoids a circular dependency at module load time.
+        from .errors import (
+            COMING_SOON_CODES,
+            GPU_REJECTION_CODES,
+            CapacityUnavailableError,
+            ComingSoonError,
+        )
+
+        if code in GPU_REJECTION_CODES:
+            return CapacityUnavailableError(status, body)
+        if code in COMING_SOON_CODES:
+            return ComingSoonError(status, body)
+    return ApiError(status, body)
+
+
+class HttpClient:
+    """Shared HTTP transport used by resource modules via composition."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        access_token: Optional[str] = None,
+        org_id: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        # Config wins; otherwise the RUNBIOS_* environment variables supply
+        # defaults (the legacy BIOS_* names are still accepted), then the
+        # canonical production hostname.
+        self._base_url = (
+            base_url
+            or os.environ.get("RUNBIOS_BASE_URL")
+            or os.environ.get("BIOS_BASE_URL")
+            # api.runbios.ai DNS does not exist yet; planned cutover target.
+            or "https://api.runbios.ai"
+        ).rstrip("/")
+        self._api_key = (
+            api_key
+            or os.environ.get("RUNBIOS_API_KEY")
+            or os.environ.get("BIOS_API_KEY")
+            or None
+        )
+        self._access_token = access_token
+        self._org_id = org_id
+        self._workspace_id = workspace_id
+        self._timeout = timeout if timeout is not None else 30.0
+
+        if not self._api_key and not self._access_token:
+            raise ValueError(
+                "Run BiOS: either api_key or access_token is required "
+                "(or set the RUNBIOS_API_KEY environment variable; "
+                "the legacy BIOS_API_KEY name is still accepted)"
+            )
+
+        self._session = requests.Session()
+        self._session.headers.update(self._build_base_headers())
+
+    def _build_base_headers(self) -> Dict[str, str]:
+        headers: Dict[str, str] = {
+            "User-Agent": "bios-python/{}".format(VERSION),
+            "Accept": "application/json",
+        }
+
+        if self._api_key:
+            headers["X-API-Key"] = self._api_key
+        elif self._access_token:
+            headers["Authorization"] = "Bearer {}".format(self._access_token)
+
+        if self._org_id:
+            headers["X-Org-ID"] = self._org_id
+        if self._workspace_id:
+            headers["X-Workspace-ID"] = self._workspace_id
+
+        return headers
+
+    def _handle_response(self, response: requests.Response) -> Any:
+        if not response.ok:
+            try:
+                body = response.json()
+            except (ValueError, RuntimeError):
+                body = {
+                    "error": response.text
+                    or "API error {}".format(response.status_code)
+                }
+            raise _build_api_error(response.status_code, body)
+
+        if response.status_code == 204 or not response.content:
+            return None
+
+        try:
+            return response.json()
+        except (ValueError, RuntimeError):
+            return None
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Any] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Send a JSON request and parse the response."""
+        url = "{}{}".format(self._base_url, path)
+        headers = {"Content-Type": "application/json"}
+        if extra_headers:
+            headers.update(extra_headers)
+
+        response = self._session.request(
+            method=method,
+            url=url,
+            json=body,
+            headers=headers,
+            timeout=self._timeout,
+        )
+        return self._handle_response(response)
+
+    def get(self, path: str, extra_headers: Optional[Dict[str, str]] = None) -> Any:
+        """Send a GET request."""
+        url = "{}{}".format(self._base_url, path)
+        response = self._session.get(url, headers=extra_headers, timeout=self._timeout)
+        return self._handle_response(response)
+
+    def post(
+        self,
+        path: str,
+        body: Optional[Any] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Send a POST request with a JSON body."""
+        return self.request("POST", path, body, extra_headers)
+
+    def patch(
+        self,
+        path: str,
+        body: Optional[Any] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Send a PATCH request with a JSON body."""
+        return self.request("PATCH", path, body, extra_headers)
+
+    def put(
+        self,
+        path: str,
+        body: Optional[Any] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Send a PUT request with a JSON body."""
+        return self.request("PUT", path, body, extra_headers)
+
+    def delete(
+        self,
+        path: str,
+        body: Optional[Any] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Send a DELETE request."""
+        return self.request("DELETE", path, body, extra_headers)
+
+    def upload(
+        self,
+        path: str,
+        files: Dict[str, Tuple[str, Any, str]],
+        data: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Upload files via multipart/form-data."""
+        url = "{}{}".format(self._base_url, path)
+        response = self._session.post(
+            url,
+            files=files,
+            data=data,
+            timeout=self._timeout,
+        )
+        return self._handle_response(response)

bios/_gpu_priorities.py

@@ -0,0 +1,114 @@
+"""Canonical ranked GPU placement validation shared by training/deployments."""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def normalize_gpu_priorities(
+    raw: Optional[List[Dict[str, Any]]],
+    *,
+    queue_enabled: bool,
+    gpu_type: Optional[str],
+    gpu_count: Optional[int],
+    queue_field: str,
+    ranked_immediate: bool = False,
+) -> Tuple[Optional[List[Dict[str, Any]]], Optional[str], Optional[int]]:
+    """Validate ordering/cardinality and return canonical snake-case choices.
+
+    ``ranked_immediate=True`` (training) lets a launch without the queue carry
+    1 to 5 choices ranked best first; the extras are used as backups when the
+    first choice is not free at launch. With ``ranked_immediate=False``
+    (deployments) a launch without the queue still needs exactly one choice.
+    Queueing always needs 3 to 5 choices.
+    """
+    if raw is None:
+        if queue_enabled:
+            raise ValueError(
+                "Run BiOS: {}=true requires 3 to 5 gpu_priorities".format(
+                    queue_field
+                )
+            )
+        return None, gpu_type, gpu_count
+
+    if not isinstance(raw, list) or not raw:
+        raise ValueError("Run BiOS: gpu_priorities must contain at least one choice")
+    if len(raw) > 5:
+        raise ValueError("Run BiOS: gpu_priorities accepts at most 5 choices")
+    if queue_enabled and len(raw) < 3:
+        raise ValueError(
+            "Run BiOS: {}=true requires 3 to 5 gpu_priorities".format(queue_field)
+        )
+    if not queue_enabled and not ranked_immediate and len(raw) != 1:
+        raise ValueError(
+            "Run BiOS: gpu_priorities must contain exactly one choice when {} is false".format(
+                queue_field
+            )
+        )
+
+    normalized: List[Dict[str, Any]] = []
+    seen = set()
+    for index, choice in enumerate(raw):
+        if not isinstance(choice, dict):
+            raise ValueError("Run BiOS: gpu_priorities entries must be objects")
+        choice_type = str(
+            choice.get("gpu_type") or choice.get("gpuType") or ""
+        ).strip()
+        choice_count = choice.get("gpu_count")
+        if choice_count is None:
+            choice_count = choice.get("gpuCount")
+        if not choice_type:
+            raise ValueError(
+                "Run BiOS: gpu_priorities[{}].gpu_type is required".format(index)
+            )
+        if (
+            not isinstance(choice_count, int)
+            or isinstance(choice_count, bool)
+            or not 1 <= choice_count <= 8
+        ):
+            raise ValueError(
+                "Run BiOS: gpu_priorities[{}].gpu_count must be an integer between 1 and 8".format(
+                    index
+                )
+            )
+        provider = str(choice.get("provider") or "").strip().casefold()
+        region = str(choice.get("region") or "").strip().casefold()
+        tier = str(choice.get("tier") or "").strip().casefold()
+        if tier and tier != "secure":
+            raise ValueError(
+                "Run BiOS: gpu_priorities[{}].tier must be secure".format(index)
+            )
+        # Dedup key only (the provider is NEVER emitted below unless the caller
+        # set it). Default to the neutral platform alias so two omitted-provider
+        # choices collapse under "bios-cloud", matching the console/server key
+        # convention.
+        canonical_key = "{}|{}|{}|{}".format(
+            provider or "bios-cloud",
+            region or "global",
+            tier or "secure",
+            choice_type.casefold(),
+        )
+        if canonical_key in seen:
+            raise ValueError(
+                "Run BiOS: gpu_priorities provider/region/tier/GPU placements must be distinct"
+            )
+        seen.add(canonical_key)
+        entry = {"gpu_type": choice_type, "gpu_count": choice_count}
+        if provider:
+            entry["provider"] = provider
+        if region:
+            entry["region"] = region
+        entry["tier"] = "secure"
+        normalized.append(entry)
+
+    first = normalized[0]
+    if gpu_type is not None and str(gpu_type).strip() != first["gpu_type"]:
+        raise ValueError(
+            "Run BiOS: gpu_type/gpu_count must match the first gpu_priorities choice"
+        )
+    if gpu_count is not None and gpu_count != first["gpu_count"]:
+        raise ValueError(
+            "Run BiOS: gpu_type/gpu_count must match the first gpu_priorities choice"
+        )
+    return normalized, first["gpu_type"], first["gpu_count"]
+
+
+__all__ = ["normalize_gpu_priorities"]