runbios-sdk 0.2.1-dev.62

package/dist/resources/training.js

@@ -0,0 +1,419 @@
+import { normalizeGPUPlacement } from './gpu-priorities.js';
+const TRAINING_IDEMPOTENCY_KEY = /^[A-Za-z0-9._:-]{8,128}$/;
+function trainingIdempotencyKey(explicit) {
+    const key = explicit?.trim() || globalThis.crypto.randomUUID();
+    if (!TRAINING_IDEMPOTENCY_KEY.test(key)) {
+        throw new Error("RunBiOS: idempotencyKey must be 8-128 characters using letters, numbers, '.', '_', ':', or '-'");
+    }
+    return key;
+}
+function buildTrainingRequest(params) {
+    let trainingMethod = params.method;
+    if (trainingMethod === 'vlm')
+        trainingMethod = 'sft';
+    const datasetIds = (params.datasetIds || []).filter((id) => id.trim() !== '');
+    if (datasetIds.length === 0 && params.datasetId?.trim())
+        datasetIds.push(params.datasetId);
+    if (datasetIds.length === 0) {
+        throw new Error('RunBiOS: datasetId or datasetIds must contain at least one dataset');
+    }
+    const body = {
+        model_id: params.model,
+        dataset_ids: datasetIds,
+        training_method: trainingMethod,
+        train_type: params.adapter,
+    };
+    if (params.modelRevision !== undefined)
+        body.model_revision = params.modelRevision;
+    if (params.rlhfAlgorithm !== undefined)
+        body.rlhf_type = params.rlhfAlgorithm;
+    const queueEnabled = params.queueIfUnavailable ?? false;
+    const placement = normalizeGPUPlacement(params.gpuPriorities, queueEnabled, params.gpuType, params.gpuCount, 'queueIfUnavailable');
+    body.queue_if_unavailable = queueEnabled;
+    if (params.queueDeadline !== undefined) {
+        const deadline = params.queueDeadline instanceof Date
+            ? params.queueDeadline
+            : new Date(params.queueDeadline);
+        if (Number.isNaN(deadline.getTime())) {
+            throw new Error('RunBiOS: queueDeadline must be a valid RFC 3339 timestamp');
+        }
+        body.queue_deadline = deadline.toISOString();
+    }
+    if (params.maxPriceHourCents !== undefined) {
+        if (!Number.isInteger(params.maxPriceHourCents) || params.maxPriceHourCents < 0) {
+            throw new Error('RunBiOS: maxPriceHourCents must be a non-negative integer');
+        }
+        body.max_price_hour_cents = params.maxPriceHourCents;
+    }
+    if (placement.gpuType !== undefined)
+        body.gpu_type = placement.gpuType;
+    if (placement.gpuCount !== undefined)
+        body.gpu_count = placement.gpuCount;
+    if (placement.priorities !== undefined)
+        body.gpu_priorities = placement.priorities;
+    if (params.name !== undefined)
+        body.name = params.name;
+    if (params.workspaceId !== undefined)
+        body.workspace_id = params.workspaceId;
+    if (params.storageGb !== undefined)
+        body.storage_gb = params.storageGb;
+    if (params.numCheckpoints !== undefined)
+        body.num_checkpoints = params.numCheckpoints;
+    if (params.modelParamsB !== undefined)
+        body.model_params_b = params.modelParamsB;
+    if (params.modelActiveParamsB !== undefined)
+        body.model_active_params_b = params.modelActiveParamsB;
+    if (params.integrationId !== undefined)
+        body.integration_id = params.integrationId;
+    if (params.networkVolumeId !== undefined)
+        body.network_volume_id = params.networkVolumeId;
+    if (params.cacheDataset !== undefined)
+        body.cache_dataset = params.cacheDataset;
+    if (params.datasetSampleLimits !== undefined)
+        body.dataset_sample_limits = params.datasetSampleLimits;
+    if (params.datasetMixing !== undefined)
+        body.dataset_mixing = params.datasetMixing;
+    if (params.mixing !== undefined)
+        body.mixing = params.mixing;
+    const config = {};
+    if (params.epochs !== undefined)
+        config.num_train_epochs = params.epochs;
+    if (params.batchSize !== undefined)
+        config.per_device_train_batch_size = params.batchSize;
+    if (params.gradientAccumulation !== undefined)
+        config.gradient_accumulation_steps = params.gradientAccumulation;
+    if (params.learningRate !== undefined)
+        config.learning_rate = params.learningRate;
+    if (params.lrScheduler !== undefined)
+        config.lr_scheduler_type = params.lrScheduler;
+    if (params.warmupRatio !== undefined)
+        config.warmup_ratio = params.warmupRatio;
+    if (params.warmupSteps !== undefined)
+        config.warmup_steps = params.warmupSteps;
+    if (params.weightDecay !== undefined)
+        config.weight_decay = params.weightDecay;
+    if (params.maxGradNorm !== undefined)
+        config.max_grad_norm = params.maxGradNorm;
+    if (params.maxSeqLength !== undefined)
+        config.max_length = params.maxSeqLength;
+    if (params.gradientCheckpointing !== undefined)
+        config.gradient_checkpointing = params.gradientCheckpointing;
+    if (params.mixedPrecision !== undefined) {
+        config.torch_dtype = params.mixedPrecision === 'bf16'
+            ? 'bfloat16'
+            : params.mixedPrecision === 'fp16' ? 'float16' : 'float32';
+    }
+    if (params.seed !== undefined)
+        config.seed = params.seed;
+    if (params.loraRank !== undefined)
+        config.lora_rank = params.loraRank;
+    if (params.loraAlpha !== undefined)
+        config.lora_alpha = params.loraAlpha;
+    if (params.loraDropout !== undefined)
+        config.lora_dropout = params.loraDropout;
+    if (params.loraTargetModules !== undefined)
+        config.target_modules = params.loraTargetModules;
+    if (params.quantizationBit !== undefined)
+        config.quant_bits = params.quantizationBit;
+    if (params.deepspeed !== undefined)
+        config.deepspeed = params.deepspeed;
+    if (params.saveSteps !== undefined)
+        config.save_steps = params.saveSteps;
+    if (params.saveEpochs !== undefined) {
+        if (params.saveEpochs !== 1) {
+            throw new Error('RunBiOS: saveEpochs only supports 1; use extraConfig.save_strategy for explicit checkpoint policy');
+        }
+        config.save_strategy = 'epoch';
+    }
+    if (params.maxCheckpoints !== undefined)
+        config.save_total_limit = params.maxCheckpoints;
+    if (params.evalSteps !== undefined)
+        config.eval_steps = params.evalSteps;
+    if (params.evalSplit !== undefined) {
+        const ratio = typeof params.evalSplit === 'string' ? Number(params.evalSplit) : params.evalSplit;
+        if (!Number.isFinite(ratio))
+            throw new Error('RunBiOS: evalSplit must be a numeric ratio');
+        config.split_dataset_ratio = ratio;
+    }
+    if (params.extraConfig)
+        Object.assign(config, params.extraConfig);
+    if (Object.keys(config).length > 0)
+        body.config = config;
+    return { body, datasetIds, trainingMethod };
+}
+function normalizeJob(raw, fallback = {}) {
+    const job = { ...fallback, ...raw };
+    const id = String(job.id || job.job_id || '');
+    if (!id)
+        throw new Error('RunBiOS: training response did not include id or job_id');
+    job.id = id;
+    if (!job.job_id && raw.job_id)
+        job.job_id = String(raw.job_id);
+    if (!job.model_id && job.model)
+        job.model_id = job.model;
+    if (!job.training_method && job.method)
+        job.training_method = job.method;
+    if (!job.train_type && job.adapter)
+        job.train_type = job.adapter;
+    if (!job.rlhf_type && job.rlhf_algorithm)
+        job.rlhf_type = job.rlhf_algorithm;
+    if (!job.dataset_ids && job.dataset_id)
+        job.dataset_ids = [job.dataset_id];
+    // Compatibility aliases let existing automations migrate without losing the
+    // canonical REST field names returned by the current API.
+    if (!job.model && job.model_id)
+        job.model = job.model_id;
+    if (!job.method && job.training_method)
+        job.method = job.training_method;
+    if (!job.adapter && job.train_type)
+        job.adapter = job.train_type;
+    if (!job.rlhf_algorithm && job.rlhf_type)
+        job.rlhf_algorithm = job.rlhf_type;
+    if (!job.dataset_id && job.dataset_ids?.length)
+        job.dataset_id = job.dataset_ids[0];
+    if (!job.error && job.error_message)
+        job.error = job.error_message;
+    if (!job.status)
+        job.status = 'pending';
+    return job;
+}
+/**
+ * Create, monitor, and manage fine-tuning training jobs.
+ */
+export class Training {
+    _http;
+    /** @internal */
+    constructor(_http) {
+        this._http = _http;
+    }
+    /** Return the authoritative method, adapter, and hyperparameter contract Run BiOS trains against. */
+    async capabilities() {
+        return this._http.fetchGet('/api/training/capabilities');
+    }
+    /**
+     * Create a new training job (book-before-reveal).
+     *
+     * The call blocks while the ranked GPU ladder is booked (~40s typical). A
+     * training id and the "training started" email exist only once a real machine is
+     * secured, so the returned `status` is one of:
+     *
+     * - `"booked"` — a GPU was secured (booked == secured); the job then
+     *   progresses through provisioning, downloading, and running on its own.
+     * - `"securing"` — still booking at the deadline; the async tail continues.
+     *   Poll {@link get} until it reaches `booked`/`running` (or terminal).
+     *   Nothing is charged until a machine is real.
+     * - `"queued"` — returned only with explicit queue consent
+     *   (`queueIfUnavailable: true`); waits for stock at zero charge and books
+     *   via the same path.
+     *
+     * If the ladder is exhausted at booking time without queue consent, this
+     * rejects with a `CAPACITY_UNAVAILABLE` (HTTP 409) carrying neutral
+     * alternatives — no phantom job remains and nothing is billed. The SDK never
+     * auto-substitutes a GPU; a transient 503 is a retry, never a capacity
+     * verdict.
+     *
+     * @example
+     * ```ts
+     * const job = await client.training.create({
+     *   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',
+     *   gpuCount: 1,
+     * });
+     * console.log(`Job ${job.id} created -- status: ${job.status}`);
+     * ```
+    */
+    async create(params) {
+        const { body, datasetIds, trainingMethod } = buildTrainingRequest(params);
+        const result = await this._http.fetchPost('/api/training/jobs', body, {
+            'Idempotency-Key': trainingIdempotencyKey(params.idempotencyKey),
+        });
+        return normalizeJob(result, {
+            model_id: params.model,
+            model_revision: params.modelRevision,
+            training_method: trainingMethod,
+            train_type: params.adapter,
+            rlhf_type: params.rlhfAlgorithm,
+            dataset_ids: datasetIds,
+            gpu_type: params.gpuType,
+            gpu_count: params.gpuCount,
+            status: 'pending',
+        });
+    }
+    /** Validate and canonicalize a training request without creating or billing a job. */
+    async preflight(params) {
+        const { body } = buildTrainingRequest(params);
+        return this._http.fetchPost('/api/training/preflight', body);
+    }
+    /** Return one server-driven page with pagination metadata. */
+    async listPage(params = {}) {
+        const q = new URLSearchParams();
+        if (params.workspaceId)
+            q.set('workspace_id', params.workspaceId);
+        if (params.status)
+            q.set('status', params.status);
+        if (params.limit !== undefined)
+            q.set('limit', String(params.limit));
+        if (params.offset !== undefined)
+            q.set('offset', String(params.offset));
+        const qs = q.toString();
+        const raw = await this._http.fetchGet(`/api/training/jobs${qs ? `?${qs}` : ''}`);
+        const envelope = Array.isArray(raw)
+            ? { jobs: raw.map((job) => normalizeJob(job)), total: raw.length, limit: raw.length, offset: 0 }
+            : {
+                jobs: (raw.jobs || []).map((job) => normalizeJob(job)),
+                total: Number(raw.total || 0),
+                limit: Number(raw.limit || params.limit || 50),
+                offset: Number(raw.offset || 0),
+            };
+        return envelope;
+    }
+    /**
+     * List training jobs, optionally filtered by workspace or status.
+     *
+     * @example
+     * ```ts
+     * const jobs = await client.training.list({ status: 'running' });
+     * for (const job of jobs) {
+     *   console.log(`${job.id} -- ${job.model} -- ${job.status}`);
+     * }
+     * ```
+     */
+    async list(params = {}) {
+        return (await this.listPage(params)).jobs;
+    }
+    /**
+     * Get detailed information about a training job.
+     *
+     * @param id - Training job ID.
+     *
+     * @example
+     * ```ts
+     * const job = await client.training.get('job_abc123');
+     * console.log(`Status: ${job.status}, Progress: ${job.progress}%`);
+     * ```
+     */
+    async get(id) {
+        const result = await this._http.fetchGet(`/api/training/jobs/${encodeURIComponent(id)}`);
+        return normalizeJob(result);
+    }
+    /**
+     * Get training metrics (loss curves, learning rate, throughput) for a job.
+     *
+     * @param id - Training job ID.
+     *
+     * @example
+     * ```ts
+     * const metrics = await client.training.getMetrics('job_abc123');
+     * console.log(`Current loss: ${metrics.metrics.at(-1)?.loss}`);
+     * console.log(`${metrics.metrics.length} metric points`);
+     * ```
+     */
+    async getMetrics(id) {
+        const result = await this._http.fetchGet(`/api/training/jobs/${encodeURIComponent(id)}/metrics`);
+        const metrics = Array.isArray(result.metrics)
+            ? result.metrics
+            : Array.isArray(result.steps) ? result.steps : [];
+        return { ...result, metrics, graph_configs: result.graph_configs || [], steps: metrics };
+    }
+    /**
+     * List checkpoints saved during training.
+     *
+     * @param id - Training job ID.
+     *
+     * @example
+     * ```ts
+     * const checkpoints = await client.training.getCheckpoints('job_abc123');
+     * for (const cp of checkpoints) {
+     *   console.log(`${cp.name}: ${cp.size_bytes} bytes`);
+     * }
+     * ```
+     */
+    async getCheckpoints(id) {
+        const result = await this._http.fetchGet(`/api/training/jobs/${encodeURIComponent(id)}/checkpoints`);
+        return Array.isArray(result) ? result : result.checkpoints || [];
+    }
+    /**
+     * Get training logs for a job.
+     *
+     * @param id - Training job ID.
+     * @param tail - Maximum newest entries to return (server clamps to 1-1000).
+     *
+     * @example
+     * ```ts
+     * const logs = await client.training.getLogs('job_abc123');
+     * for (const entry of logs.logs) {
+     *   console.log(entry.level, entry.message);
+     * }
+     * ```
+     */
+    async getLogs(id, tail = 200) {
+        const result = await this._http.fetchGet(`/api/training/jobs/${encodeURIComponent(id)}/logs?tail=${encodeURIComponent(String(tail))}`);
+        const logs = (result.logs || []).map((entry) => typeof entry === 'string'
+            ? { level: 'INFO', message: entry, timestamp: '' }
+            : entry);
+        return { logs, lines: logs.map((entry) => entry.message) };
+    }
+    /**
+     * Stop a running training job.
+     *
+     * By default, intermediate data (checkpoints, logs) is preserved.
+     * Pass `keepData: false` to clean up all job artifacts.
+     *
+     * @param id - Training job ID.
+     * @param keepData - Whether to keep checkpoints and logs. Defaults to true.
+     *
+     * @example
+     * ```ts
+     * await client.training.stop('job_abc123');
+     * ```
+     */
+    async stop(id, keepData = true) {
+        return this._http.fetchPost(`/api/training/jobs/${encodeURIComponent(id)}/stop`, { keep_data: keepData });
+    }
+    /**
+     * Resume a stopped or `interrupted` training job from its last checkpoint.
+     *
+     * Use this on a `stopped` job, or one resting at `interrupted` — the
+     * self-heal state a started job enters when its machine is lost and billing has
+     * already been stopped (distinct from `failed`). Resume re-books on secured
+     * capacity before reporting resumed, so book-before-reveal still applies.
+     *
+     * @param id - Training job ID.
+     *
+     * @example
+     * ```ts
+     * await client.training.resume('job_abc123');
+     * ```
+     */
+    async resume(id, idempotencyKey) {
+        const result = await this._http.fetchPost(`/api/training/jobs/${encodeURIComponent(id)}/resume`, undefined, { 'Idempotency-Key': trainingIdempotencyKey(idempotencyKey) });
+        const resumedId = result.id || result.job_id;
+        if (!resumedId)
+            throw new Error('RunBiOS: resume response did not include job_id');
+        return { ...result, id: resumedId };
+    }
+    /**
+     * Delete a specific checkpoint from a training job.
+     *
+     * @param jobId - Training job ID.
+     * @param checkpointId - Checkpoint ID to delete.
+     *
+     * @example
+     * ```ts
+     * await client.training.deleteCheckpoint('job_abc123', 'cp_xyz789');
+     * ```
+     */
+    async getEvals(id) {
+        return this._http.fetchGet(`/api/training/jobs/${encodeURIComponent(id)}/evals`);
+    }
+    async deleteCheckpoint(jobId, checkpointId) {
+        await this._http.fetchDelete(`/api/training/jobs/${encodeURIComponent(jobId)}/checkpoints/${encodeURIComponent(checkpointId)}`);
+    }
+}

package/dist/resources/wallet.d.ts

@@ -0,0 +1,53 @@
+import type { HttpClient } from '../client.js';
+import type { WalletBalance, TransactionListParams, TransactionListResponse } from '../types.js';
+/**
+ * View wallet balance, transaction history, and billing information.
+ */
+export declare class Wallet {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: HttpClient);
+    /**
+     * Get the wallet balance, spendable balance, holds, and accruing usage.
+     *
+     * `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 latter.
+     *
+     * @example
+     * ```ts
+     * 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)}`);
+     * console.log(`On hold:   $${((balance.active_holds_cents ?? 0) / 100).toFixed(2)}`);
+     * console.log(`Accruing:  $${((balance.accruing_cents ?? 0) / 100).toFixed(2)}`);
+     * ```
+     */
+    getBalance(): Promise<WalletBalance>;
+    /**
+     * List billing transactions (credits, charges, refunds).
+     *
+     * Returns the WRAPPED page `{ transactions, total, limit, offset }` -- read
+     * `.transactions`, never the response itself.
+     *
+     * @example
+     * ```ts
+     * 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}`);
+     * }
+     * ```
+     */
+    getTransactions(params?: TransactionListParams): Promise<TransactionListResponse>;
+    /**
+     * Get pricing information for compute and storage.
+     *
+     * @example
+     * ```ts
+     * const pricing = await client.wallet.getPricing();
+     * console.log(pricing);
+     * ```
+     */
+    getPricing(): Promise<Record<string, unknown>>;
+}

package/dist/resources/wallet.js

@@ -0,0 +1,61 @@
+/**
+ * View wallet balance, transaction history, and billing information.
+ */
+export class Wallet {
+    _http;
+    /** @internal */
+    constructor(_http) {
+        this._http = _http;
+    }
+    /**
+     * Get the wallet balance, spendable balance, holds, and accruing usage.
+     *
+     * `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 latter.
+     *
+     * @example
+     * ```ts
+     * 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)}`);
+     * console.log(`On hold:   $${((balance.active_holds_cents ?? 0) / 100).toFixed(2)}`);
+     * console.log(`Accruing:  $${((balance.accruing_cents ?? 0) / 100).toFixed(2)}`);
+     * ```
+     */
+    async getBalance() {
+        return this._http.fetchGet('/api/billing/wallet');
+    }
+    /**
+     * List billing transactions (credits, charges, refunds).
+     *
+     * Returns the WRAPPED page `{ transactions, total, limit, offset }` -- read
+     * `.transactions`, never the response itself.
+     *
+     * @example
+     * ```ts
+     * 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}`);
+     * }
+     * ```
+     */
+    async getTransactions(params = {}) {
+        const limit = params.limit ?? 50;
+        const offset = params.offset ?? 0;
+        return this._http.fetchGet(`/api/billing/transactions?limit=${limit}&offset=${offset}`);
+    }
+    /**
+     * Get pricing information for compute and storage.
+     *
+     * @example
+     * ```ts
+     * const pricing = await client.wallet.getPricing();
+     * console.log(pricing);
+     * ```
+     */
+    async getPricing() {
+        return this._http.fetchGet('/api/billing/pricing');
+    }
+}