usfbios 1.0.0__py3-none-any.whl

usfbios/__init__.py

@@ -0,0 +1,97 @@
+"""
+usfbios -- Official Python SDK for the USF BIOS fine-tuning platform.
+
+Usage::
+
+    from usfbios import USFBios
+
+    client = USFBios(api_key="sk_live_...")
+
+    # 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",
+    )
+"""
+
+from typing import Any, Dict, Optional
+
+from ._client import ApiError, HttpClient, VERSION
+from ._types import ApiKeyIntrospection
+from .models import Models
+from .datasets import Datasets
+from .training import Training
+from .wallet import Wallet
+from .gpu import GPU
+
+
+__version__ = VERSION
+__all__ = [
+    "USFBios",
+    "ApiError",
+    "VERSION",
+    "Models",
+    "Datasets",
+    "Training",
+    "Wallet",
+    "GPU",
+]
+
+
+class USFBios:
+    """Main client for the USF 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.
+
+    Example with API key::
+
+        client = USFBios(api_key="sk_live_...")
+
+    Example with JWT::
+
+        client = USFBios(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,
+    ) -> 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.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)
+        """View GPU pricing and get hardware recommendations."""
+
+    def introspect(self) -> ApiKeyIntrospection:
+        """Introspect the current API key to discover its permissions."""
+        return self._http.get("/api/api-keys/introspect")

usfbios/_client.py

@@ -0,0 +1,165 @@
+"""HTTP client for the USF BIOS API."""
+
+import os
+from typing import Any, Dict, Optional, Tuple
+
+import requests
+
+VERSION = "1.0.0"
+
+
+class ApiError(Exception):
+    """Typed error raised when the API returns a non-2xx status."""
+
+    def __init__(self, status: int, body: Dict[str, Any]) -> None:
+        msg = (
+            body.get("detail")
+            or body.get("error")
+            or body.get("message")
+            or "API error {}".format(status)
+        )
+        super().__init__(msg)
+        self.status: int = status
+        self.code: Optional[str] = body.get("code")
+        self.request_id: Optional[str] = body.get("request_id")
+        self.message: str = msg
+
+
+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:
+        self._base_url = (base_url or "https://api-bios.us.inc").rstrip("/")
+        self._api_key = api_key
+        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("USFBios: either api_key or access_token is required")
+
+        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": "usfbios-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 ApiError(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)