bios-sdk 0.1.0 → 0.1.1-dev.13

package/README.md

@@ -14,7 +14,7 @@ npm install bios-sdk
 import { BiOS } from 'bios-sdk';
 
 const client = new BiOS({
-  apiKey: 'usf-...',
+  apiKey: 'bios-...',
 });
 
 // Search for models
@@ -40,12 +40,28 @@ console.log(`Job ${job.id} created`);
 
 ### API Key (recommended)
 
+API keys start with `bios-` (legacy `usf-` keys stay valid).
+
 ```typescript
 const client = new BiOS({
-  apiKey: 'usf-...',
+  apiKey: 'bios-...',
 });
 ```
 
+### Environment Variables
+
+When `apiKey` or `baseUrl` is omitted from the config, the SDK reads them
+from the environment:
+
+```bash
+export BIOS_API_KEY=bios-...
+export BIOS_BASE_URL=https://api.usbios.ai   # optional; this is the default
+```
+
+```typescript
+const client = new BiOS({}); // uses BIOS_API_KEY / BIOS_BASE_URL
+```
+
 ### JWT Access Token
 
 ```typescript
@@ -68,8 +84,8 @@ without an explicit replay acknowledgement from the endpoint.
 
 ```typescript
 const client = new BiOS({
-  apiKey: 'usf-control-plane-key',
-  inferenceKey: 'sk-usf-deployment-key',
+  apiKey: 'bios-control-plane-key',
+  inferenceKey: 'sk-bios-deployment-key',
   // inferenceBaseUrl: 'https://api-dev.usbios.ai', // explicit in dev
 });
 
@@ -275,11 +291,11 @@ try {
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `apiKey` | — | API key (`usf-...`) |
+| `apiKey` | `BIOS_API_KEY` env var | API key (`bios-...`; legacy `usf-...` keys stay valid) |
 | `accessToken` | — | JWT access token |
 | `orgId` | — | Organization ID (auto-resolved with API keys) |
 | `workspaceId` | — | Workspace ID (auto-resolved with API keys) |
-| `baseUrl` | `https://api.usbios.ai` | Canonical production hostname (release-gated; this documentation does not assert current availability). During prelaunch/dev, pass `https://api-dev.usbios.ai` explicitly. |
+| `baseUrl` | `BIOS_BASE_URL` env var, then `https://api.usbios.ai` | Canonical production hostname (release-gated; this documentation does not assert current availability). During prelaunch/dev, pass `https://api-dev.usbios.ai` explicitly. |
 | `timeout` | `30000` | Request timeout in ms |
 
 ## Requirements

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BiOSConfig, ApiErrorBody } from './types.js';
+import type { BiOSConfig, ApiErrorBody, AvailableGpuAlternative } from './types.js';
 /**
  * Typed error thrown by every SDK method when the API returns a non-2xx status.
  *
@@ -12,6 +12,22 @@ import type { BiOSConfig, ApiErrorBody } from './types.js';
  *   }
  * }
  * ```
+ *
+ * Availability rejections are self-recoverable: when the selected GPU is no
+ * longer bookable at submit time the API answers 409 with a machine code and
+ * the currently bookable alternatives, and the SDK surfaces them typed:
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.training.create({ ...req, gpu_type: 'A100_80GB' });
+ * } catch (err) {
+ *   if (err instanceof ApiError && err.code === 'SELECTED_GPU_UNAVAILABLE') {
+ *     const next = err.availableGpus?.[0];
+ *     if (next) await client.training.create({ ...req, gpu_type: next.gpu_type });
+ *   }
+ * }
+ * ```
  */
 export declare class ApiError extends Error {
     /** HTTP status code (e.g. 401, 404, 500). */
@@ -20,8 +36,26 @@ export declare class ApiError extends Error {
     readonly code: string | undefined;
     /** Server-assigned request ID for support / debugging. */
     readonly requestId: string | undefined;
+    /**
+     * The full parsed error response body. Availability rejections carry
+     * structured recovery data here (`available_gpus`, `checked_at`).
+     */
+    readonly body: ApiErrorBody;
+    /**
+     * Bookable-now GPU alternatives on availability rejections
+     * (SELECTED_GPU_UNAVAILABLE / CAPACITY_UNAVAILABLE); undefined otherwise.
+     * Every entry fit the requested model when `checkedAt` was stamped —
+     * resubmit with one of these and nothing else changed.
+     */
+    readonly availableGpus: AvailableGpuAlternative[] | undefined;
+    /** Availability snapshot time behind an availability rejection. */
+    readonly checkedAt: string | undefined;
     constructor(status: number, body: ApiErrorBody);
 }
+/** Default API key from `BIOS_API_KEY` when the config omits one. @internal */
+export declare function envApiKey(): string | undefined;
+/** Default base URL from `BIOS_BASE_URL` when the config omits one. @internal */
+export declare function envBaseUrl(): string | undefined;
 export declare class HttpClient {
     private readonly baseUrl;
     private readonly apiKey;

package/dist/client.js

@@ -15,6 +15,22 @@ import { VERSION } from './index.js';
  *   }
  * }
  * ```
+ *
+ * Availability rejections are self-recoverable: when the selected GPU is no
+ * longer bookable at submit time the API answers 409 with a machine code and
+ * the currently bookable alternatives, and the SDK surfaces them typed:
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.training.create({ ...req, gpu_type: 'A100_80GB' });
+ * } catch (err) {
+ *   if (err instanceof ApiError && err.code === 'SELECTED_GPU_UNAVAILABLE') {
+ *     const next = err.availableGpus?.[0];
+ *     if (next) await client.training.create({ ...req, gpu_type: next.gpu_type });
+ *   }
+ * }
+ * ```
  */
 export class ApiError extends Error {
     /** HTTP status code (e.g. 401, 404, 500). */
@@ -23,6 +39,20 @@ export class ApiError extends Error {
     code;
     /** Server-assigned request ID for support / debugging. */
     requestId;
+    /**
+     * The full parsed error response body. Availability rejections carry
+     * structured recovery data here (`available_gpus`, `checked_at`).
+     */
+    body;
+    /**
+     * Bookable-now GPU alternatives on availability rejections
+     * (SELECTED_GPU_UNAVAILABLE / CAPACITY_UNAVAILABLE); undefined otherwise.
+     * Every entry fit the requested model when `checkedAt` was stamped —
+     * resubmit with one of these and nothing else changed.
+     */
+    availableGpus;
+    /** Availability snapshot time behind an availability rejection. */
+    checkedAt;
     constructor(status, body) {
         const err = body.error;
         const nested = typeof err === 'object' && err !== null ? err : null;
@@ -36,9 +66,34 @@ export class ApiError extends Error {
         this.status = status;
         this.code = (nested ? String(nested.code || '') : body.code) || undefined;
         this.requestId = body.request_id;
+        this.body = body;
+        const alts = body.available_gpus ?? body.available_alternatives;
+        this.availableGpus = Array.isArray(alts) && alts.length > 0 ? alts : undefined;
+        this.checkedAt = body.checked_at;
     }
 }
 // ============================================================================
+// Environment defaults
+// ============================================================================
+/**
+ * Read an environment variable, tolerating browser bundles where `process`
+ * does not exist. Returns undefined for missing or empty values.
+ */
+function envVar(name) {
+    if (typeof process === 'undefined' || !process.env)
+        return undefined;
+    const value = process.env[name];
+    return value && value.trim() !== '' ? value.trim() : undefined;
+}
+/** Default API key from `BIOS_API_KEY` when the config omits one. @internal */
+export function envApiKey() {
+    return envVar('BIOS_API_KEY');
+}
+/** Default base URL from `BIOS_BASE_URL` when the config omits one. @internal */
+export function envBaseUrl() {
+    return envVar('BIOS_BASE_URL');
+}
+// ============================================================================
 // HttpClient — shared HTTP transport used by resource modules via composition
 // ============================================================================
 export class HttpClient {
@@ -49,14 +104,14 @@ export class HttpClient {
     workspaceIdValue;
     timeout;
     constructor(config) {
-        this.baseUrl = (config.baseUrl || 'https://api.usbios.ai').replace(/\/+$/, '');
-        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl || envBaseUrl() || 'https://api-dev.usbios.ai').replace(/\/+$/, '');
+        this.apiKey = config.apiKey ?? envApiKey();
         this.accessToken = config.accessToken;
         this.orgId = config.orgId;
         this.workspaceIdValue = config.workspaceId;
         this.timeout = config.timeout ?? 30_000;
         if (!this.apiKey && !this.accessToken) {
-            throw new Error('BiOS: either apiKey or accessToken is required');
+            throw new Error('BiOS: either apiKey or accessToken is required (or set the BIOS_API_KEY environment variable)');
         }
     }
     /** Workspace configured on the client, used by multipart/control-plane helpers. */

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * import { BiOS } from 'bios-sdk';
  *
  * const client = new BiOS({
- *   apiKey: 'usf-...',
+ *   apiKey: 'bios-...',
  * });
  *
  * // Search for models
@@ -30,8 +30,11 @@ import { Training } from './resources/training.js';
 import { Wallet } from './resources/wallet.js';
 import { GPU } from './resources/gpu.js';
 import { Inference } from './resources/inference.js';
-/** SDK version. Sent as part of the User-Agent header. */
-export declare const VERSION = "1.0.2";
+/**
+ * SDK version. Sent as part of the User-Agent header.
+ * Must match package.json "version" -- enforced by a contract test.
+ */
+export declare const VERSION = "0.1.1";
 export declare class BiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;
@@ -60,4 +63,4 @@ export { Training } from './resources/training.js';
 export { Wallet } from './resources/wallet.js';
 export { GPU, type GPURecommendation } from './resources/gpu.js';
 export { Inference, validateChatRequest, parseSSE, type ChatMessage, type FunctionTool, type ChatCompletionParams, type ChatCompletionResponse, type ChatCompletionChunk, } from './resources/inference.js';
-export type { BiOSConfig, PaginatedResponse, ApiErrorBody, Model, ModelSearchParams, ModelSearchResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, } from './types.js';
+export type { BiOSConfig, PaginatedResponse, ApiErrorBody, AvailableGpuAlternative, Model, ModelSearchParams, ModelSearchResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, } from './types.js';

package/dist/index.js

@@ -6,7 +6,7 @@
  * import { BiOS } from 'bios-sdk';
  *
  * const client = new BiOS({
- *   apiKey: 'usf-...',
+ *   apiKey: 'bios-...',
  * });
  *
  * // Search for models
@@ -30,8 +30,11 @@ import { Training } from './resources/training.js';
 import { Wallet } from './resources/wallet.js';
 import { GPU } from './resources/gpu.js';
 import { Inference } from './resources/inference.js';
-/** SDK version. Sent as part of the User-Agent header. */
-export const VERSION = '1.0.2';
+/**
+ * SDK version. Sent as part of the User-Agent header.
+ * Must match package.json "version" -- enforced by a contract test.
+ */
+export const VERSION = '0.1.1';
 export class BiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;

package/dist/resources/inference.js

@@ -1,4 +1,4 @@
-import { ApiError } from '../client.js';
+import { ApiError, envBaseUrl } from '../client.js';
 import { normalizeGPUPlacement } from './gpu-priorities.js';
 const FUNCTION_NAME = /^[A-Za-z0-9_-]{1,64}$/;
 const ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool', 'function']);
@@ -280,7 +280,7 @@ export class Inference {
     _http;
     constructor(config = {}, http) {
         this.key = config.inferenceKey;
-        this.baseUrl = (config.baseUrl || 'https://api.usbios.ai').replace(/\/+$/, '');
+        this.baseUrl = (config.baseUrl || envBaseUrl() || 'https://api-dev.usbios.ai').replace(/\/+$/, '');
         this.timeout = config.timeout ?? 900_000;
         this._http = http;
     }

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /** Configuration for initializing the BIOS SDK client. */
 export interface BiOSConfig {
-    /** API key for authentication (prefix: usf-). Mutually exclusive with accessToken. */
+    /** API key for authentication (prefix: bios-; legacy usf- keys stay valid). Falls back to the BIOS_API_KEY environment variable. Mutually exclusive with accessToken. */
     apiKey?: string;
     /** JWT access token for authentication. Mutually exclusive with apiKey. */
     accessToken?: string;
@@ -8,13 +8,13 @@ export interface BiOSConfig {
     orgId?: string;
     /** Workspace ID. Optional when using API keys (resolved from the key). Can override for multi-workspace keys. */
     workspaceId?: string;
-    /** Base URL for the API. Defaults to the canonical https://api.usbios.ai hostname. */
+    /** Base URL for the API. Falls back to the BIOS_BASE_URL environment variable, then the canonical https://api-dev.usbios.ai hostname. */
     baseUrl?: string;
     /** Request timeout in milliseconds. Defaults to 30000. */
     timeout?: number;
     /** Default per-deployment inference key. Can be overridden per inference call. */
     inferenceKey?: string;
-    /** Inference base URL. Defaults to baseUrl, then https://api.usbios.ai. */
+    /** Inference base URL. Defaults to baseUrl, then https://api-dev.usbios.ai. */
     inferenceBaseUrl?: string;
     /** End-to-end inference timeout in milliseconds. Defaults to 15 minutes. */
     inferenceTimeout?: number;
@@ -38,6 +38,27 @@ export interface ApiErrorBody {
     message?: string;
     code?: string;
     request_id?: string;
+    /**
+     * Bookable-now GPU alternatives, present on availability rejections
+     * (SELECTED_GPU_UNAVAILABLE / CAPACITY_UNAVAILABLE): each entry fits the
+     * requested model's minimum requirements and was in stock at `checked_at`.
+     * Pick one and resubmit — nothing else about the request needs to change.
+     */
+    available_gpus?: AvailableGpuAlternative[];
+    /** Same contract as `available_gpus`; some surfaces use this field name. */
+    available_alternatives?: AvailableGpuAlternative[];
+    /** When the availability snapshot behind the rejection was taken. */
+    checked_at?: string;
+}
+/** One bookable-now GPU alternative carried on an availability rejection. */
+export interface AvailableGpuAlternative {
+    gpu_type: string;
+    gpu_count?: number;
+    available_count?: number;
+    price_per_hour_cents?: number;
+    provider?: string;
+    region?: string;
+    tier?: string;
 }
 /** A model returned from the HuggingFace-backed model search. */
 export interface Model {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bios-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1-dev.13",
   "description": "Official TypeScript SDK for the BIOS training and deployment platform API",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,15 +26,18 @@
   },
   "keywords": [
     "bios-sdk",
+    "bios",
     "fine-tuning",
     "deployment",
+    "fine-tuning",
     "inference",
     "llm",
     "machine-learning",
-    "sdk"
+    "sdk",
+    "usbios"
   ],
   "author": "BIOS <bios@us.inc>",
-  "homepage": "https://bios.us.com",
+  "homepage": "https://usbios.ai",
   "license": "MIT",
   "engines": {
     "node": ">=18.0.0"