TypeScript SDK
The official TypeScript SDK for the Run BiOS fine-tuning platform. Build, train, and manage models programmatically with full type safety.
Installation
npm install bios-sdkRequires Node.js 18+ or any runtime with native fetch support.
API Key Setup
Before using the SDK, create an API key from the BIOS console:
- Sign in at
https://platform.runbios.aiwith your account (e.g.you@example.com). - Navigate to Settings → API Keys in the dashboard sidebar.
- Click Create API Key and enter a name (e.g. “SDK Development”).
- Select the permission scopes your application needs:
| Scope | Grants access to |
|---|---|
| models:read | Search models, fetch configs, check adapter compatibility |
| datasets:read | List datasets, preview rows, check status |
| datasets:write | Upload, import, validate, and delete datasets |
| training:read | List jobs, view metrics, logs, and checkpoints |
| training:write | Create, stop, resume, and delete training jobs |
| deployments:read | Preflight, list, and monitor model-serving deployments |
| deployments:write | Create, update, stop, restart, and delete deployments |
| billing:read | View wallet balance and transaction history |
| analytics:read | View usage, audit, training, and inference analytics |
| integrations:read | List connected integrations |
| integrations:write | Connect and manage HuggingFace integrations |
| skills:read | Read platform skills and your organization’s own skills |
| skills:write | Create, clone, edit, and remove your organization’s skills |
| loop:read | Read your Conscious Loop samples and their feedback, pipelines, versions, attempts and benchmarks |
| loop:write | Send samples and feedback, import data, create and edit pipelines, train now, and approve, reject or roll back versions |
| serverless | Call the serverless inference API (chat completions and the model catalog) |
- Click Create and copy the key (starts with
sk-bios-). It is shown only once.
Configuration
Initialize the client with your API key:
import { USFBios } from 'bios-sdk';
const client = new USFBios({
apiKey: process.env.BIOS_API_KEY, // default bios-...; custom prefixes work
});All configuration options:
| Option | Type | Default | Description |
|---|---|---|---|
| apiKey | string | - | API key (recommended). Default prefix bios-; custom prefixes work too. |
| accessToken | string | - | JWT token (alternative to API key). |
| baseUrl | string | https://api.runbios.ai | API base URL. |
| orgId | string | - | Organization ID (required with JWT, auto-resolved with API key). |
| workspaceId | string | - | Workspace ID (required with JWT, auto-resolved with API key). |
| timeout | number | 30000 | Request timeout in milliseconds. |
You can also introspect your API key to check permissions:
const info = await client.introspect();
console.log(`Org: ${info.org.name}`);
console.log(`Workspace: ${info.workspace.name}`);
console.log(`Scopes: ${info.scopes.join(', ')}`);Resources & Methods
The SDK is organized into resource namespaces. Each method is fully typed with request parameters and response objects.
Models
Search the model catalog, fetch training configs, and check adapter compatibility.
// Search for models
const results = await client.models.search({
query: 'llama',
type: 'llm',
limit: 10,
});
for (const m of results.models) {
console.log(`${m.id} - ${m.totalParams}B params`);
}
// Get model config for GPU planning
const config = await client.models.getConfig('meta-llama/Llama-3.1-8B');
console.log(`${config.totalParams}B params, MoE: ${config.isMoE}`);
// Check adapter compatibility
const compat = await client.models.getAdapterCompatibility({
modelType: 'llama',
trainingMethod: 'rlhf',
rlhfAlgorithm: 'dpo',
});
const usable = compat.adapters.filter(a => a.compatible);
console.log(`${usable.length} compatible adapters`);| Method | Scope | Description |
|---|---|---|
| models.search(params?) | models:read | Search fine-tunable models |
| models.getConfig(modelId) | models:read | Get training config (params, architecture, MoE) |
| models.getAdapterCompatibility(params?) | models:read | Check adapter compatibility for architecture |
Datasets
Upload, import, preview, validate, and manage training datasets.
// Upload a local dataset file
const ds = await client.datasets.upload({
filePath: './training_data.jsonl',
name: 'Customer Support SFT',
});
console.log(`Uploaded: ${ds.id}`);
// List all datasets
const datasets = await client.datasets.list();
console.log(`${datasets.length} datasets`);
// Preview rows before training
const preview = await client.datasets.preview('ds_abc123', {
page: 1,
pageSize: 5,
});
console.log(preview.columns);
// Validate a file before uploading
const result = await client.datasets.validate('./data.jsonl');
if (result.valid) {
console.log(`Valid ${result.format} - ${result.row_count} rows`);
} else {
console.error('Errors:', result.errors);
}
// Import from HuggingFace
const imported = await client.datasets.importFromHuggingFace({
repoId: 'databricks/dolly-15k',
integrationId: 'int_abc123',
name: 'Dolly 15k',
});
// Search HuggingFace Hub
const hubResults = await client.datasets.searchHub({ query: 'code instruct' });
// Delete a dataset
await client.datasets.delete('ds_abc123');| Method | Scope | Description |
|---|---|---|
| datasets.list(params?) | datasets:read | List datasets in workspace |
| datasets.get(id) | datasets:read | Get dataset details |
| datasets.upload(params) | datasets:write | Upload a local file (JSONL, CSV, Parquet) |
| datasets.preview(id, params?) | datasets:read | Preview rows with pagination |
| datasets.getStatus(id) | datasets:read | Get processing status |
| datasets.validate(filePath) | datasets:write | Validate file format before upload |
| datasets.importFromHuggingFace(params) | datasets:write | Import from HuggingFace via integration |
| datasets.registerHuggingFace(data) | datasets:write | Register a public HF dataset directly |
| datasets.searchHub(params?) | datasets:read | Search public HuggingFace Hub datasets |
| datasets.previewHub(params) | datasets:read | Preview rows from a HF Hub dataset |
| datasets.getFormatSpecs() | datasets:read | Get supported format specifications |
| datasets.getStorageUsage(workspaceId?) | datasets:read | Get storage usage summary |
| datasets.delete(id) | datasets:write | Delete a dataset |
Training
Create, monitor, stop, and resume fine-tuning jobs.
// 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,
loraAlpha: 32,
gpuType: 'A100_80GB',
});
console.log(`Job ${job.id} created - status: ${job.status}`);
// Monitor training
const metrics = await client.training.getMetrics(job.id);
console.log(`Loss: ${metrics.current_loss}`);
// View logs
const logs = await client.training.getLogs(job.id);
for (const line of logs.logs) {
console.log(line);
}
// List checkpoints
const checkpoints = await client.training.getCheckpoints(job.id);
for (const cp of checkpoints) {
console.log(`Step ${cp.step}: loss ${cp.loss}`);
}
// Stop and resume
await client.training.stop(job.id);
await client.training.resume(job.id, 'training-resume-20260711-0001');| Method | Scope | Description |
|---|---|---|
| training.create(params) | training:write | Launch a new fine-tuning job |
| training.list(params?) | training:read | List jobs with optional filters |
| training.get(id) | training:read | Get job details |
| training.getMetrics(id) | training:read | Get loss curves, LR, throughput |
| training.getCheckpoints(id) | training:read | List saved checkpoints |
| training.getLogs(id) | training:read | Get training stdout/stderr logs |
| training.stop(id, keepData?) | training:write | Stop a running job |
| training.resume(id, idempotencyKey?) | training:write | Resume from last checkpoint |
| training.deleteCheckpoint(jobId, cpId) | training:write | Delete a specific checkpoint |
Billing & GPU
Check wallet balance, view transactions, get GPU pricing, and get hardware recommendations.
// Check wallet balance
const balance = await client.wallet.getBalance();
console.log(`Balance: $${(balance.balance_cents / 100).toFixed(2)}`);
console.log(`Available: $${(balance.available_cents / 100).toFixed(2)}`);
// View transaction history
const txns = await client.wallet.getTransactions({ limit: 20 });
for (const t of txns) {
console.log(`${t.type}: $${(t.amount_cents / 100).toFixed(2)} - ${t.description}`);
}
// Get GPU pricing
const pricing = await client.gpu.getPricing();
for (const gpu of pricing.gpus) {
console.log(`${gpu.display_name}: ${gpu.price_display} - ${gpu.vram_gb}GB VRAM`);
}
// Get recommended GPU for a model
const rec = await client.gpu.getRecommended('meta-llama/Llama-3.1-8B-Instruct');
if (rec) {
console.log(`Recommended: ${rec.display_name} x${rec.recommended_count}`);
console.log(`Estimated cost: $${(rec.estimated_cost_per_hour_cents / 100).toFixed(2)}/hr`);
}| Method | Scope | Description |
|---|---|---|
| wallet.getBalance() | billing:read | Current balance, available credits, pending charges |
| wallet.getTransactions(params?) | billing:read | Transaction history with pagination |
| wallet.getPricing() | billing:read | Compute and storage pricing |
| gpu.getPricing() | (public) | All GPU types with per-second pricing and VRAM |
| gpu.getRecommended(modelId) | (public) | Best GPU configuration for a model |
Integrations
The SDK accesses integrations through the datasets resource for HuggingFace import workflows:
// Import from a connected HuggingFace account
const imported = await client.datasets.importFromHuggingFace({
repoId: 'your-org/private-dataset',
integrationId: 'int_abc123', // from connected HF account
name: 'My Private Dataset',
split: 'train',
maxSamples: 10000,
});
console.log(`Imported: ${imported.id} - ${imported.row_count} rows`);Conscious Loop
A Conscious Loop pipeline keeps one model your app uses getting better from your app’s own conversations: your app adds the pipeline ID to its calls, you say which answers were good or wrong, and the pipeline trains and tests new versions by itself. The SDK’s client.loop covers all of it: create a pipeline, send feedback with upvote, downvote and correct, and read trainings and versions.
// npm install runbios-sdk
import { RunBiOS } from 'runbios-sdk';
const client = new RunBiOS({
apiKey: process.env.RUNBIOS_API_KEY,
baseUrl: 'https://api.runbios.ai',
});
const reply = await client.inference.chatCompletions({
model: 'your-current-model',
messages: [{ role: 'user', content: 'How long do refunds take?' }],
loop: { pipeline: 'support-replies' },
});
const { choices } = reply as {
choices: { message: { content: string } }[];
};
const answer = choices[0].message.content;
// The sample ID came back in the reply's headers.
// Keep it to send feedback (step 2).
// No ID means this call was not saved.
const sampleId = reply.loop_sample_id;How it works, in plain words: the Conscious Loop guide. Every call: Conscious Loop API.
Error Handling
All SDK methods throw ApiError on non-2xx responses with typed error details:
import { USFBios, ApiError } from 'bios-sdk';
const client = new USFBios({ apiKey: process.env.BIOS_API_KEY });
try {
const job = await client.training.get('job_nonexistent');
} catch (err) {
if (err instanceof ApiError) {
console.error(`HTTP ${err.status}: ${err.message}`);
console.error(`Code: ${err.code}`); // e.g. "NOT_FOUND"
console.error(`Request ID: ${err.requestId}`); // for support
}
}
// Common error status codes:
// 401 - Invalid or expired API key
// 403 - Key missing required scope
// 404 - Resource not found
// 422 - Validation error
// 429 - Rate limit exceededTypeScript Support
The SDK ships with full TypeScript definitions. All request parameters and response types are exported:
import type {
USFBiosConfig,
ModelSearchParams,
ModelSearchResponse,
ModelConfig,
Dataset,
DatasetUploadParams,
TrainingJob,
TrainingCreateParams,
TrainingMetrics,
TrainingCheckpoint,
WalletBalance,
Transaction,
GPUPricingResponse,
ApiKeyIntrospection,
} from 'bios-sdk';User-Agent header with every request for debugging and support.Run BiOS Documentation. Need help? Email contact@runbios.ai