runbios-sdk 0.2.1-dev.62

package/README.md

@@ -0,0 +1,460 @@
+# runbios-sdk
+
+Official TypeScript/Node.js SDK for the [Run BiOS](https://runbios.ai) fine-tuning platform API.
+
+## Installation
+
+```bash
+npm install runbios-sdk
+```
+
+## Quick Start
+
+```typescript
+import { RunBiOS } from 'runbios-sdk';
+
+const client = new RunBiOS({
+  apiKey: 'bios-...',
+});
+
+// Search the hosted catalog. Rows come straight from the model registry, so
+// they are snake_case, and the HANDLE you pass everywhere else is repo_id
+// (`id` is the registry UUID).
+const models = await client.models.search({ query: 'llama', type: 'llm' });
+console.log(`Found ${models.total} models`);
+for (const m of models.models) {
+  console.log(`${m.repo_id} -- ${m.params_total_b}B params, ${m.maxContext} ctx`);
+}
+
+// Create a training job
+const job = await client.training.create({
+  idempotencyKey: 'training-create-20260711-0001',
+  model: 'meta-llama/Llama-3.1-8B-Instruct',
+  datasetId: 'ds_abc123',
+  method: 'sft',
+  adapter: 'lora',
+  epochs: 3,
+  learningRate: 2e-4,
+  loraRank: 16,
+  gpuType: 'A100_80GB',
+});
+console.log(`Job ${job.id} created`);
+```
+
+> **Note:** `BiOS` remains exported as a deprecated alias of `RunBiOS`, so
+> existing code keeps working unchanged.
+
+## Authentication
+
+### API Key (recommended)
+
+API keys start with `bios-` (legacy `usf-` keys stay valid).
+
+```typescript
+const client = new RunBiOS({
+  apiKey: 'bios-...',
+});
+```
+
+### Environment Variables
+
+When `apiKey`, `baseUrl`, or `inferenceKey` is omitted from the config, the SDK
+reads them from the environment:
+
+```bash
+export RUNBIOS_API_KEY=bios-...
+export RUNBIOS_BASE_URL=https://api.runbios.ai   # optional; this is the default
+export RUNBIOS_INFERENCE_KEY=sk-bios-...        # optional; defaults to RUNBIOS_API_KEY
+```
+
+The legacy `BIOS_API_KEY` / `BIOS_BASE_URL` / `BIOS_INFERENCE_KEY` names keep
+working as fallbacks when the `RUNBIOS_*` variable is not set.
+
+```typescript
+const client = new RunBiOS({}); // uses RUNBIOS_API_KEY / RUNBIOS_BASE_URL / RUNBIOS_INFERENCE_KEY
+```
+
+### JWT Access Token
+
+```typescript
+const client = new RunBiOS({
+  accessToken: 'eyJhbG...',
+  orgId: 'org_abc123',
+});
+```
+
+## Resources
+
+### Inference
+
+Pass a per-deployment `sk-bios-...` key for a dedicated deployment. For
+serverless catalog models you need nothing extra: `inferenceKey` falls back to
+`RUNBIOS_INFERENCE_KEY` (legacy `BIOS_INFERENCE_KEY`) and then to the
+control-plane `apiKey`, so a platform key
+carrying the serverless scope calls `/v1` directly without being supplied twice.
+The async iterator parses SSE across arbitrary chunk boundaries and aborts the
+upstream request when iteration is stopped. Inference POSTs are not retried implicitly;
+reuse an explicit `idempotencyKey` only when retrying the same request. The SDK
+propagates the header but does not promise server-side replay/deduplication
+without an explicit replay acknowledgement from the endpoint.
+
+**Parameter naming on `/v1` calls.** Only the parameters this SDK names are
+camelCase: `model`, `messages`, `tools`, `toolChoice`, `reasoningEffort`,
+`inferenceKey`, `idempotencyKey`, `requestId`, `signal`. Every other key is
+forwarded to the OpenAI-compatible endpoint **verbatim**, so it must use
+OpenAI's own snake_case spelling — `max_tokens`, `top_p`, `stop`,
+`frequency_penalty`, `presence_penalty`. The endpoint rejects an unknown key
+rather than ignoring it, so `maxTokens` is a `400 Unknown parameter:
+'maxTokens'`, not a silently dropped limit.
+
+```typescript
+const client = new RunBiOS({
+  apiKey: 'bios-control-plane-key',
+  inferenceKey: 'sk-bios-deployment-key', // omit to reuse apiKey
+  // inferenceBaseUrl: 'https://api-dev.runbios.ai', // explicit in dev
+});
+
+const controller = new AbortController();
+for await (const chunk of client.inference.streamChatCompletions({
+  messages: [{ role: 'user', content: 'Look up record 42' }],
+  tools: [{
+    type: 'function',
+    function: {
+      name: 'lookup',
+      parameters: { type: 'object', properties: { id: { type: 'integer' } } },
+    },
+  }],
+  idempotencyKey: 'chat-42-attempt-1',
+  signal: controller.signal,
+})) {
+  console.log(chunk);
+}
+// controller.abort() cancels an unfinished generation.
+```
+
+#### Serverless catalog models
+
+Call any catalog model by id on the unified `/v1` endpoint with a workspace
+platform key that carries the serverless scope — no per-deployment key. The
+gateway routes by `model`; dedicated deployments and serverless models share the
+same endpoint. `reasoningEffort` is forwarded to the endpoint, and streaming
+surfaces `content` and `reasoning_content` deltas incrementally.
+
+A platform key with the serverless scope is enough — `inferenceKey` falls back
+to `RUNBIOS_INFERENCE_KEY` (legacy `BIOS_INFERENCE_KEY`) and then to the
+control-plane `apiKey`, so the same key
+never has to be supplied twice.
+
+```typescript
+const client = new RunBiOS({
+  apiKey: 'bios-platform-key-with-serverless-scope',
+});
+
+for await (const chunk of client.inference.streamChatCompletions({
+  model: 'meta-llama/Llama-3.1-8B-Instruct', // serverless catalog id
+  messages: [{ role: 'user', content: 'Explain tensor parallelism briefly.' }],
+  reasoningEffort: 'low',
+})) {
+  const delta = (chunk.choices as any)?.[0]?.delta ?? {};
+  if (delta.reasoning_content) process.stdout.write(delta.reasoning_content);
+  if (delta.content) process.stdout.write(delta.content);
+}
+
+// Non-streaming; the final chunk carries `usage` when the model reports it.
+const completion = await client.inference.chatCompletions({
+  model: 'meta-llama/Llama-3.1-8B-Instruct',
+  messages: [{ role: 'user', content: 'One sentence on GPUs.' }],
+});
+// The response is an open OpenAI-shaped record; narrow it to read the answer.
+const choice = (completion.choices as Array<Record<string, any>>)?.[0];
+const answer = choice?.message?.content as string | null | undefined;
+if (answer) {
+  console.log(answer);
+} else {
+  // A 200 is NOT proof the model answered. Reasoning models can spend the whole
+  // budget inside reasoning_content and return content: null with
+  // finish_reason "length" — an empty answer that looks like success. Always
+  // read choices[0].message.content, and raise max_tokens (or lower
+  // reasoningEffort) when finish_reason is "length". max_tokens is an OpenAI
+  // passthrough parameter, so it keeps OpenAI's snake_case spelling -- the
+  // camelCase form is rejected with a 400, not silently ignored.
+  console.log('no answer:', choice?.finish_reason,
+    'reasoning tokens only:', Boolean(choice?.message?.reasoning_content));
+}
+```
+
+Streaming billing is charged server-side on completed usage; the SDK only needs
+to request `usage` where the endpoint exposes it (no client change).
+
+### Models
+
+The catalog lists only models hosted on Run BiOS (the platform's own verified
+registry, mirrored in Run BiOS storage) — every result can be trained and
+deployed; it is never a live Hugging Face search.
+
+Search results are the registry's own rows: snake_case fields, `repo_id` as the
+model handle (`id` is the registry UUID), plus `maxContext` — the native context
+window that caps a deployment's `contextLength` — and `weightBytes`, the on-disk
+weight size. `query` becomes the registry's `q` filter, the only search
+parameter it reads.
+
+```typescript
+// Search models
+const results = await client.models.search({ query: 'llama', limit: 10 });
+for (const m of results.models) {
+  console.log(m.repo_id, m.params_total_b, m.surface_type, m.maxContext, m.weightBytes);
+}
+
+// One model, by its author/name handle
+const detail = await client.models.get('meta-llama/Llama-3.1-8B-Instruct');
+console.log(detail.model.architecture, detail.model.maxContext);
+
+// The context ceiling on its own — undefined when the registry does not record it
+console.log(await client.models.nativeMaxContext('meta-llama/Llama-3.1-8B-Instruct'));
+
+// Get model config
+const config = await client.models.getConfig('meta-llama/Llama-3.1-8B-Instruct');
+
+// Check adapter compatibility
+const compat = await client.models.getAdapterCompatibility({
+  modelType: 'llama',
+  trainingMethod: 'sft',
+});
+```
+
+### Datasets
+
+```typescript
+// List datasets
+const datasets = await client.datasets.list();
+
+// Upload a dataset
+const uploaded = await client.datasets.upload({
+  filePath: './data.jsonl',
+  name: 'My Dataset',
+});
+
+// Preview rows
+const preview = await client.datasets.preview('ds_abc123', { pageSize: 5 });
+
+// Import from HuggingFace
+const imported = await client.datasets.importFromHuggingFace({
+  repoId: 'databricks/dolly-15k',
+  integrationId: 'int_abc123',
+  name: 'Dolly 15k',
+});
+
+// Validate before upload
+const validation = await client.datasets.validate('./data.jsonl');
+```
+
+### Training
+
+```typescript
+const request = {
+  idempotencyKey: 'training-create-20260711-0001',
+  model: 'meta-llama/Llama-3.1-8B-Instruct',
+  datasetIds: ['ds_abc123', 'ds_def456'],
+  method: 'sft' as const,
+  adapter: 'lora' as const,
+  queueIfUnavailable: true,
+  queueDeadline: '2026-07-18T00:00:00Z',
+  maxPriceHourCents: 500,
+  gpuPriorities: [
+    { gpuType: 'H100_80GB', gpuCount: 1 },
+    { gpuType: 'A100_80GB', gpuCount: 1 },
+    { gpuType: 'L40S_48GB', gpuCount: 1 },
+  ],
+};
+
+// Side-effect-free validation, canonical sizing, live stock and alternatives
+const check = await client.training.preflight(request);
+console.log(check.request_hash, check.recommended, check.queue_eligible);
+
+// Create the paid job only after reviewing preflight
+const job = await client.training.create(request);
+
+// List jobs
+const jobs = await client.training.list({ status: 'running' });
+const page = await client.training.listPage({ limit: 50, offset: 0 });
+
+// Get metrics
+const metrics = await client.training.getMetrics('job_abc123');
+for (const point of metrics.metrics) console.log(point.step, point.loss);
+
+// Get checkpoints
+const checkpoints = await client.training.getCheckpoints('job_abc123');
+
+// Structured logs
+const logs = await client.training.getLogs('job_abc123');
+for (const entry of logs.logs) console.log(entry.level, entry.message);
+
+// Stop / Resume
+await client.training.stop('job_abc123');
+await client.training.resume('job_abc123', 'training-resume-20260711-0001');
+```
+
+### Wallet
+
+`balance_cents` is the deposited balance; `available_balance_cents` is what can
+actually be spent right now (balance minus `active_holds_cents` and
+`accruing_cents`). Spend decisions read the second one. Auto top-up is flat
+(`auto_topup_enabled` / `auto_topup_threshold` / `auto_topup_amount`), and the
+transaction list is a wrapped page.
+
+```typescript
+// Get balance
+const balance = await client.wallet.getBalance();
+console.log(`Balance:   $${(balance.balance_cents / 100).toFixed(2)}`);
+console.log(`Spendable: $${(balance.available_balance_cents / 100).toFixed(2)}`);
+
+// Transaction history -- the rows are WRAPPED, so read .transactions
+const page = await client.wallet.getTransactions({ limit: 20 });
+console.log(`${page.total} transactions`);
+for (const t of page.transactions) {
+  console.log(`${t.type}/${t.category}: $${(t.amount_cents / 100).toFixed(2)} -- ${t.description}`);
+}
+```
+
+### Inference deployments
+
+`allowCapacityQueue: true` is explicit consent to wait for stock, so it requires
+3 to 5 ranked `gpuPriorities` — the SDK rejects the combination locally before
+any request. Leave the queue off to book exactly one placement.
+
+`servingMode`, `modelTask`, and `supportsImages` are all **server-derived and
+immutable**: the platform reads them off the resolved model and rejects a
+conflicting assertion, so omit them and read the result back from the
+deployment. Which `modelTask` values are accepted depends on the model, so the
+SDK does not judge one locally — it forwards whatever you pass and the server
+rules on it. `preflight()` echoes the derived task at
+`canonical_request.model_task` if you want to see it before creating.
+
+`contextLength` is optional and follows one policy: omit it and the server
+pre-fills `min(nativeMax, 262144)`; the window is adjustable only when the
+model's native max exceeds the 32,768 floor, and it can never exceed the model's
+own native max. It is also a **sizing input** — a bigger window means a bigger
+KV cache, which can raise the minimum GPU count. Read the ceiling with
+`client.models.nativeMaxContext(modelId)` first, and read it back from
+`native_max_context` on the deployment detail. Pass a whole number: the local
+capacity pre-check only runs on a window it can prove fits, so anything else (a
+numeric string out of a JSON config included) is forwarded for the server to
+answer.
+
+```typescript
+const nativeMax = await client.models.nativeMaxContext('meta-llama/Llama-3.1-8B-Instruct');
+const request = {
+  name: 'llama-api',
+  sourceType: 'hf_model' as const,
+  hfModelId: 'meta-llama/Llama-3.1-8B-Instruct',
+  gpuType: 'H100_80GB',
+  gpuCount: 1,
+  // Queueing needs 3-5 ranked placements; the first is the one booked now.
+  allowCapacityQueue: true,
+  gpuPriorities: [
+    { gpuType: 'H100_80GB', gpuCount: 1 },
+    { gpuType: 'A100_80GB', gpuCount: 1 },
+    { gpuType: 'L40S_48GB', gpuCount: 2 },
+  ],
+  // Never ask for more context than the model has.
+  ...(nativeMax ? { contextLength: Math.min(65536, nativeMax) } : {}),
+  maxPriceHourCents: 500,
+};
+
+// No wallet mutation and no GPU allocation.
+const check = await client.inference.preflight(request);
+console.log(check.selected_gpu, check.alternatives, check.billing);
+
+// Creates only after your automation accepts the live price/queue terms.
+const deployment = await client.inference.create(request, 'deploy-create-20260711-0001');
+console.log(deployment.inference_key); // returned once; store securely
+
+const status = await client.inference.status(deployment.id);
+console.log(status.status, status.status_reason, status.queue_expires_at, status.wallet_authorization_status);
+// The detail resolves the per-deployment serving settings a list row omits.
+console.log(status.context_length, status.native_max_context, status.model_task);
+// status remains "failed" for existing filters when status_reason is "queue_expired".
+const notificationHistory = await client.inference.notifications(deployment.id);
+console.log(notificationHistory.map(({ event_type, state, attempt_count }) => ({ event_type, state, attempt_count })));
+
+// Bounded newest-first listing. Reuse next_cursor with unchanged filters.
+// LIST rows are a lean grid projection: the model handle is `model_ref` (there
+// is no `model` key) and the serving settings above are absent -- call
+// client.inference.get(id) for those.
+const page = await client.inference.listPage({ limit: 100, status: 'running', search: 'llama' });
+if (page.has_more && page.next_cursor) {
+  const older = await client.inference.listPage({ limit: 100, status: 'running', search: 'llama', cursor: page.next_cursor });
+  console.log(older.deployments);
+}
+// Or traverse lazily without one unbounded response.
+for await (const item of client.inference.iterate({ status: 'running' })) {
+  console.log(item.name, item.model_ref, item.requests_total);
+}
+
+await client.inference.stop(deployment.id);
+await client.inference.delete(deployment.id);
+```
+
+### GPU
+
+```typescript
+// Get pricing
+const pricing = await client.gpu.getPricing();
+
+// Authoritative model-aware choices, live stock, total pricing, and alternatives
+const options = await client.gpu.getOptions({
+  modelId: 'meta-llama/Llama-3.1-8B',
+  trainType: 'qlora',
+  method: 'sft',
+});
+
+// Get recommendation for a model
+const rec = await client.gpu.getRecommended('meta-llama/Llama-3.1-8B');
+```
+
+### Key Introspection
+
+```typescript
+const info = await client.introspect();
+console.log(`Org: ${info.org.name}`);
+console.log(`Scopes: ${info.scopes.join(', ')}`);
+```
+
+## Error Handling
+
+```typescript
+import { RunBiOS, ApiError } from 'runbios-sdk';
+
+try {
+  await client.training.get('bad_id');
+} catch (err) {
+  if (err instanceof ApiError) {
+    console.log(`Status: ${err.status}`);
+    console.log(`Message: ${err.message}`);
+    console.log(`Code: ${err.code}`);
+  }
+}
+```
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `apiKey` | `RUNBIOS_API_KEY` env var (legacy `BIOS_API_KEY`) | 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` | `RUNBIOS_BASE_URL` env var (legacy `BIOS_BASE_URL`), then `https://api.runbios.ai` | Canonical production hostname (release-gated; this documentation does not assert current availability). During prelaunch/dev, pass `https://api-dev.runbios.ai` explicitly. |
+| `timeout` | `30000` | Request timeout in ms |
+| `inferenceKey` | `RUNBIOS_INFERENCE_KEY` env var (legacy `BIOS_INFERENCE_KEY`), then `apiKey` | Key used by `client.inference` for `/v1` calls. A per-deployment `sk-bios-...` key, or the platform `apiKey` itself when it carries the serverless scope — you never pass the same key twice |
+| `inferenceBaseUrl` | `baseUrl` | Explicit dev or production inference hostname |
+| `inferenceTimeout` | `900000` | End-to-end inference/stream timeout in ms |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- ESM modules
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,202 @@
+import type { BiOSConfig, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement } from './types.js';
+/**
+ * Typed error thrown by every SDK method when the API returns a non-2xx status.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.training.get('bad_id');
+ * } catch (err) {
+ *   if (err instanceof ApiError && err.status === 404) {
+ *     console.log('Job not found');
+ *   }
+ * }
+ * ```
+ *
+ * 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). */
+    readonly status: number;
+    /** Machine-readable error code from the API, if provided. */
+    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);
+}
+/**
+ * The one transient GPU-rejection code: the GPU is not in stock right now, so
+ * waiting or joining the capacity queue can still succeed.
+ */
+export declare const CAPACITY_UNAVAILABLE_CODE = "CAPACITY_UNAVAILABLE";
+/**
+ * The permanent GPU-rejection codes (HTTP 400). Each is a fixed fact about the
+ * request: the model does not fit on that GPU type, the count is below the
+ * model's minimum, the count cannot split the model, or the serving engine
+ * cannot run that card at all. Stock is irrelevant to all four, so the capacity
+ * queue is never offered for them and retrying the same request never helps.
+ */
+export declare const PERMANENT_GPU_CODES: readonly ["GPU_TYPE_TOO_SMALL", "GPU_COUNT_BELOW_MINIMUM", "GPU_COUNT_INVALID", "GPU_TYPE_UNSUPPORTED"];
+/**
+ * Typed error for the standard GPU-rejection body, shared by training and
+ * inference. Covers BOTH the 409 stock miss and the 400 permanent rejections,
+ * so one `catch` reaches every case that carries recovery data. Carries the
+ * rejection class (`reason`), the explicit server-computed `minimumRequirement`
+ * (min_gpus / valid_counts, never pick below them), and the canonical bookable
+ * alternatives via {@link ApiError.availableGpus}. Instanceof-compatible with
+ * ApiError so existing handlers keep working.
+ *
+ * Branch on {@link GpuRejectionError.queueOffered} (or `.permanent`), never on
+ * the status or the code, to decide whether offering "wait for capacity" makes
+ * sense. `CapacityUnavailableError` is a kept alias of this class.
+ */
+export declare class GpuRejectionError extends ApiError {
+    /**
+     * insufficient_stock | below_model_minimum | invalid_gpu_count |
+     * model_too_large | gpu_unsupported.
+     */
+    readonly reason: string | undefined;
+    /** The explicit minimum block for the model (selected type + per-type table). */
+    readonly minimumRequirement: CapacityMinimumRequirement | undefined;
+    /** The selection the rejection was about. */
+    readonly selected: ApiErrorBody['selected'];
+    /**
+     * True only when waiting for capacity is a real option. False for every
+     * permanent rejection: do not offer the queue, and do not retry unchanged.
+     */
+    readonly queueOffered: boolean;
+    /** Whether the capacity queue may be joined instead. */
+    readonly queueEligible: boolean;
+    /**
+     * 1-based rank of the gpu_priorities entry the rejection is about, when it
+     * came from a submitted ladder.
+     */
+    readonly gpuPrioritiesEntry: number | undefined;
+    constructor(status: number, body: ApiErrorBody);
+    /**
+     * True when the request can never succeed as submitted, whatever happens to
+     * stock. Only a different GPU type or count helps.
+     */
+    get permanent(): boolean;
+}
+/**
+ * Historical name for {@link GpuRejectionError}. It is the SAME class, so
+ * `err instanceof CapacityUnavailableError` still catches every rejection,
+ * including the permanent ones that now answer 400 with their own codes.
+ */
+export declare const CapacityUnavailableError: typeof GpuRejectionError;
+export type CapacityUnavailableError = GpuRejectionError;
+/**
+ * Machine codes the services answer with while a surface is pre-launch
+ * (HTTP 403): TRAINING_COMING_SOON from POST /api/training/jobs,
+ * DATASETS_COMING_SOON from the dataset creation endpoints (upload,
+ * uploads/initiate, register-hf, integration import).
+ */
+export declare const COMING_SOON_CODES: readonly ["TRAINING_COMING_SOON", "DATASETS_COMING_SOON"];
+/**
+ * Raised when a pre-launch surface rejects a creation call: fine-tuning and
+ * datasets launch soon, so training.create and dataset upload/import/register
+ * answer 403 with one of {@link COMING_SOON_CODES}. Read and lifecycle methods
+ * (list, get, status, stop, resume, delete, preview) are unaffected.
+ *
+ * The service is the authority: the SDK never blocks client-side, so when the
+ * gate lifts at launch every SDK version works again without an upgrade. This
+ * verdict is a deliberate product state, not an outage — retrying in a loop
+ * cannot succeed while the gate is on.
+ */
+export declare class ComingSoonError extends ApiError {
+    constructor(status: number, body: ApiErrorBody);
+}
+/** Whether a machine code is one of the permanent GPU rejections. */
+export declare function isPermanentGpuCode(code: string | undefined): boolean;
+/**
+ * The machine code that goes with a rejection `reason`, mirroring the service's
+ * mapping so a client-synthesized rejection is indistinguishable from the
+ * server's. An unknown reason falls back to the stock-miss code.
+ */
+export declare function gpuRejectionCodeForReason(reason: string | undefined): string;
+/**
+ * Map a non-2xx body to the most specific typed error. The service is the
+ * authority: any GPU-rejection code becomes {@link GpuRejectionError} so
+ * callers read `.availableGpus`/`.minimumRequirement`/`.queueOffered` without
+ * string matching. @internal
+ */
+export declare function buildApiError(status: number, body: ApiErrorBody): ApiError;
+/**
+ * Default API key when the config omits one. Falls back to the
+ * `RUNBIOS_API_KEY` environment variable (legacy: `BIOS_API_KEY`). @internal
+ */
+export declare function envApiKey(): string | undefined;
+/**
+ * Inference key when the config omits one. Falls back to the
+ * `RUNBIOS_INFERENCE_KEY` environment variable (legacy: `BIOS_INFERENCE_KEY`),
+ * then to the API key at the call site: a platform key carrying the serverless
+ * scope calls `/v1` directly. @internal
+ */
+export declare function envInferenceKey(): string | undefined;
+/**
+ * Default base URL when the config omits one. Falls back to the
+ * `RUNBIOS_BASE_URL` environment variable (legacy: `BIOS_BASE_URL`). @internal
+ */
+export declare function envBaseUrl(): string | undefined;
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly accessToken;
+    private readonly orgId;
+    private readonly workspaceIdValue;
+    private readonly timeout;
+    constructor(config: BiOSConfig);
+    /** Workspace configured on the client, used by multipart/control-plane helpers. */
+    get workspaceId(): string | undefined;
+    private buildHeaders;
+    /**
+     * Send a JSON request and parse the response.
+     * Throws {@link ApiError} on non-2xx responses.
+     */
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /** Send a GET request. */
+    fetchGet<T>(path: string, extraHeaders?: Record<string, string>): Promise<T>;
+    /** Send a POST request with a JSON body. */
+    fetchPost<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /** Send a PATCH request with a JSON body. */
+    fetchPatch<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /** Send a PUT request with a JSON body. */
+    fetchPut<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /** Send a DELETE request. */
+    fetchDelete<T>(path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    /**
+     * Upload a file via multipart/form-data.
+     * The caller is responsible for constructing the FormData.
+     * Throws {@link ApiError} on non-2xx responses.
+     */
+    fetchUpload<T>(path: string, formData: FormData): Promise<T>;
+}