bios-sdk

bios-sdk

Official TypeScript/Node.js SDK for the BIOS fine-tuning platform API.

Installation

npm install bios-sdk

Quick Start

import { BiOS } from 'bios-sdk';

const client = new BiOS({
  apiKey: 'bios-...',
});

// Search for models
const models = await client.models.search({ query: 'llama', type: 'llm' });
console.log(`Found ${models.total} models`);

// 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`);

Authentication

API Key (recommended)

API keys start with bios- (legacy usf- keys stay valid).

const client = new BiOS({
  apiKey: 'bios-...',
});

Environment Variables

When apiKey or baseUrl is omitted from the config, the SDK reads them from the environment:

export BIOS_API_KEY=bios-...
export BIOS_BASE_URL=https://api.usbios.ai   # optional; this is the default

const client = new BiOS({}); // uses BIOS_API_KEY / BIOS_BASE_URL

JWT Access Token

const client = new BiOS({
  accessToken: 'eyJhbG...',
  orgId: 'org_abc123',
});

Resources

Inference

Use a deployment inference key, never the control-plane API key. 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.

const client = new BiOS({
  apiKey: 'bios-control-plane-key',
  inferenceKey: 'sk-bios-deployment-key',
  // inferenceBaseUrl: 'https://api-dev.usbios.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.

Models

// Search models
const results = await client.models.search({ query: 'llama', limit: 10 });

// Get model config
const config = await client.models.getConfig('meta-llama/Llama-3.1-8B');

// Check adapter compatibility
const compat = await client.models.getAdapterCompatibility({
  modelType: 'llama',
  trainingMethod: 'sft',
});

Datasets

// 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

const request = {
  idempotencyKey: 'training-create-20260711-0001',
  model: 'meta-llama/Llama-3.1-8B-Instruct',
  datasetIds: ['ds_abc123', 'ds_def456'],
  method: 'sft',
  adapter: 'lora',
  queueIfUnavailable: true,
  queueDeadline: '2026-07-18T00:00:00Z',
  maxPriceHourCents: 500,
  gpuPriorities: [
    { gpuType: 'H100_80GB', gpuCount: 1 },
    { gpuType: 'A100_80GB', gpuCount: 1 },
    { gpuType: 'L40S', gpuCount: 1 },
  ],
} as const;

// 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

// Get balance
const balance = await client.wallet.getBalance();
console.log(`$${(balance.balance_cents / 100).toFixed(2)}`);

// Transaction history
const txns = await client.wallet.getTransactions({ limit: 20 });

Inference deployments

const request = {
  name: 'llama-api',
  sourceType: 'hf_model',
  hfModelId: 'meta-llama/Llama-3.1-8B-Instruct',
  gpuType: 'H100_80GB',
  gpuCount: 1,
  allowCapacityQueue: true,
  maxPriceHourCents: 500,
} as const;

// 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);
// 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.
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);

await client.inference.stop(deployment.id);
await client.inference.delete(deployment.id);

GPU

// 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

const info = await client.introspect();
console.log(`Org: ${info.org.name}`);
console.log(`Scopes: ${info.scopes.join(', ')}`);

Error Handling

import { BiOS, ApiError } from 'bios-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	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	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

• Node.js >= 18.0.0
• ESM modules

License

MIT