bios-sdk 0.1.0-dev.1

package/dist/resources/datasets.d.ts

@@ -0,0 +1,180 @@
+import type { HttpClient } from '../client.js';
+import type { Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatSpecs, DatasetStorageUsage } from '../types.js';
+/**
+ * Manage training datasets -- upload files, import from HuggingFace,
+ * preview contents, and manage storage.
+ */
+export declare class Datasets {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: HttpClient);
+    /**
+     * List datasets in the current organization/workspace.
+     *
+     * @example
+     * ```ts
+     * const datasets = await client.datasets.list();
+     * console.log(`${datasets.length} datasets`);
+     * ```
+     */
+    list(params?: DatasetListParams): Promise<Dataset[]>;
+    /** Return one server-driven dataset page with counts and pagination metadata. */
+    listPage(params?: DatasetListParams): Promise<DatasetListResponse>;
+    /**
+     * Get a single dataset by ID.
+     *
+     * @param id - Dataset ID.
+     *
+     * @example
+     * ```ts
+     * const ds = await client.datasets.get('ds_abc123');
+     * console.log(`${ds.name} -- ${ds.row_count} rows`);
+     * ```
+     */
+    get(id: string): Promise<Dataset>;
+    /**
+     * Upload a dataset file from disk.
+     *
+     * Reads the file using `node:fs` and uploads it via multipart/form-data.
+     * Supported formats: JSONL, CSV, Parquet, JSON.
+     *
+     * @example
+     * ```ts
+     * const uploaded = await client.datasets.upload({
+     *   filePath: './training_data.jsonl',
+     *   name: 'My SFT Dataset',
+     * });
+     * console.log(`Uploaded: ${uploaded.id}`);
+     * ```
+     */
+    upload(params: DatasetUploadParams): Promise<Dataset>;
+    /**
+     * Preview rows from a dataset.
+     *
+     * @param id - Dataset ID.
+     * @param params - Pagination options.
+     *
+     * @example
+     * ```ts
+     * const preview = await client.datasets.preview('ds_abc123', { page: 1, pageSize: 5 });
+     * console.log(preview.samples[0]);
+     * console.log(`${preview.total} total preview rows`);
+     * ```
+     */
+    preview(id: string, params?: DatasetPreviewParams): Promise<DatasetPreview>;
+    /**
+     * Delete a dataset.
+     *
+     * @param id - Dataset ID.
+     *
+     * @example
+     * ```ts
+     * await client.datasets.delete('ds_abc123');
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Import a dataset from HuggingFace Hub via a connected integration.
+     *
+     * Requires a HuggingFace integration to be set up. Use
+     * `client.integrations.list()` to find available integrations.
+     *
+     * @example
+     * ```ts
+     * const imported = await client.datasets.importFromHuggingFace({
+     *   repoId: 'databricks/dolly-15k',
+     *   integrationId: 'int_abc123',
+     *   name: 'Dolly 15k',
+     * });
+     * console.log(`Imported: ${imported.id}`);
+     * ```
+     */
+    importFromHuggingFace(params: DatasetImportHFParams): Promise<Dataset>;
+    /**
+     * Register a HuggingFace dataset directly (without an integration).
+     *
+     * @example
+     * ```ts
+     * const ds = await client.datasets.registerHuggingFace({
+     *   repo_id: 'databricks/dolly-15k',
+     *   name: 'Dolly 15k',
+     *   split: 'train',
+     * });
+     * ```
+     */
+    registerHuggingFace(params: DatasetRegisterHFParams | Record<string, unknown>): Promise<Dataset>;
+    /**
+     * Get the processing status of a dataset.
+     *
+     * @param id - Dataset ID.
+     *
+     * @example
+     * ```ts
+     * const status = await client.datasets.getStatus('ds_abc123');
+     * console.log(status);
+     * ```
+     */
+    getStatus(id: string): Promise<Record<string, unknown>>;
+    /**
+     * Validate a dataset file before uploading.
+     *
+     * @param filePath - Path to the file to validate.
+     *
+     * @example
+     * ```ts
+     * const result = await client.datasets.validate('./data.jsonl');
+     * if (result.format_valid) {
+     *   console.log(`Valid ${result.detected_format} with ${result.num_samples} rows`);
+     * } else {
+     *   console.error('Errors:', result.validation_errors);
+     * }
+     * ```
+     */
+    validate(filePath: string): Promise<DatasetValidation>;
+    /**
+     * Get supported dataset format specifications.
+     *
+     * @example
+     * ```ts
+     * const specs = await client.datasets.getFormatSpecs();
+     * for (const spec of specs) {
+     *   console.log(`${spec.format}: ${spec.extensions.join(', ')}`);
+     * }
+     * ```
+     */
+    getFormatSpecs(): Promise<DatasetFormatSpecs>;
+    /**
+     * Search public datasets on HuggingFace Hub.
+     *
+     * @example
+     * ```ts
+     * const results = await client.datasets.searchHub({ query: 'code instruct' });
+     * ```
+     */
+    searchHub(params?: DatasetHubSearchParams): Promise<Record<string, unknown>>;
+    /**
+     * Preview rows from a HuggingFace Hub dataset before importing.
+     *
+     * @example
+     * ```ts
+     * const preview = await client.datasets.previewHub({
+     *   datasetId: 'databricks/dolly-15k',
+     *   split: 'train',
+     *   limit: 5,
+     * });
+     * ```
+     */
+    previewHub(params: DatasetHubPreviewParams): Promise<Record<string, unknown>>;
+    /**
+     * Get storage usage for datasets.
+     *
+     * @param workspaceId - Optional workspace ID filter.
+     *
+     * @example
+     * ```ts
+     * const usage = await client.datasets.getStorageUsage();
+     * console.log(`${usage.total_bytes} bytes across ${usage.dataset_count} datasets`);
+     * ```
+     */
+    getStorageUsage(workspaceId?: string): Promise<DatasetStorageUsage>;
+}

package/dist/resources/datasets.js

@@ -0,0 +1,358 @@
+function normalizeDataset(raw) {
+    const dataset = { ...raw };
+    if (dataset.file_size === undefined && dataset.file_size_bytes !== undefined) {
+        dataset.file_size = dataset.file_size_bytes;
+    }
+    if (dataset.row_count === undefined && dataset.num_samples != null) {
+        dataset.row_count = dataset.num_samples;
+    }
+    if (dataset.column_count === undefined && dataset.num_columns != null) {
+        dataset.column_count = dataset.num_columns;
+    }
+    if (dataset.format === undefined) {
+        dataset.format = dataset.file_format || dataset.detected_format || undefined;
+    }
+    return dataset;
+}
+/**
+ * Manage training datasets -- upload files, import from HuggingFace,
+ * preview contents, and manage storage.
+ */
+export class Datasets {
+    _http;
+    /** @internal */
+    constructor(_http) {
+        this._http = _http;
+    }
+    /**
+     * List datasets in the current organization/workspace.
+     *
+     * @example
+     * ```ts
+     * const datasets = await client.datasets.list();
+     * console.log(`${datasets.length} datasets`);
+     * ```
+     */
+    async list(params = {}) {
+        return (await this.listPage(params)).datasets;
+    }
+    /** Return one server-driven dataset page with counts and pagination metadata. */
+    async listPage(params = {}) {
+        const q = new URLSearchParams();
+        if (params.workspaceId)
+            q.set('workspace_id', params.workspaceId);
+        if (params.datasetType)
+            q.set('dataset_type', params.datasetType);
+        if (params.status)
+            q.set('status', params.status);
+        if (params.query)
+            q.set('q', params.query);
+        if (params.sort)
+            q.set('sort', params.sort);
+        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/datasets${qs ? `?${qs}` : ''}`);
+        if (Array.isArray(raw)) {
+            return {
+                datasets: raw.map(normalizeDataset),
+                total: raw.length,
+                counts: { all: raw.length, ready: 0, processing: 0, failed: 0 },
+                total_samples: 0,
+                limit: raw.length,
+                offset: 0,
+            };
+        }
+        return { ...raw, datasets: (raw.datasets || []).map(normalizeDataset) };
+    }
+    /**
+     * Get a single dataset by ID.
+     *
+     * @param id - Dataset ID.
+     *
+     * @example
+     * ```ts
+     * const ds = await client.datasets.get('ds_abc123');
+     * console.log(`${ds.name} -- ${ds.row_count} rows`);
+     * ```
+     */
+    async get(id) {
+        return normalizeDataset(await this._http.fetchGet(`/api/datasets/${encodeURIComponent(id)}`));
+    }
+    /**
+     * Upload a dataset file from disk.
+     *
+     * Reads the file using `node:fs` and uploads it via multipart/form-data.
+     * Supported formats: JSONL, CSV, Parquet, JSON.
+     *
+     * @example
+     * ```ts
+     * const uploaded = await client.datasets.upload({
+     *   filePath: './training_data.jsonl',
+     *   name: 'My SFT Dataset',
+     * });
+     * console.log(`Uploaded: ${uploaded.id}`);
+     * ```
+     */
+    async upload(params) {
+        let fileData;
+        let fileName;
+        try {
+            const fs = await import('node:fs');
+            const path = await import('node:path');
+            const buf = fs.readFileSync(params.filePath);
+            // Copy into a standalone ArrayBuffer to avoid SharedArrayBuffer type mismatch
+            fileData = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+            fileName = path.basename(params.filePath);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to read file at "${params.filePath}": ${message}`);
+        }
+        const blob = new Blob([fileData]);
+        const formData = new FormData();
+        formData.append('file', blob, fileName);
+        formData.append('name', params.name);
+        if (params.description)
+            formData.append('description', params.description);
+        const workspaceId = params.workspaceId || this._http.workspaceId;
+        if (!workspaceId) {
+            throw new Error('BiOS: workspaceId is required for dataset uploads');
+        }
+        formData.append('workspace_id', workspaceId);
+        if (params.format)
+            formData.append('format', params.format);
+        if (params.maxSamples !== undefined)
+            formData.append('max_samples', String(params.maxSamples));
+        if (params.columnMapping !== undefined) {
+            formData.append('column_mapping', JSON.stringify(params.columnMapping));
+        }
+        return normalizeDataset(await this._http.fetchUpload('/api/datasets/upload', formData));
+    }
+    /**
+     * Preview rows from a dataset.
+     *
+     * @param id - Dataset ID.
+     * @param params - Pagination options.
+     *
+     * @example
+     * ```ts
+     * const preview = await client.datasets.preview('ds_abc123', { page: 1, pageSize: 5 });
+     * console.log(preview.samples[0]);
+     * console.log(`${preview.total} total preview rows`);
+     * ```
+     */
+    async preview(id, params = {}) {
+        const page = params.page ?? 1;
+        const pageSize = params.pageSize ?? 10;
+        const result = await this._http.fetchGet(`/api/datasets/${encodeURIComponent(id)}/preview?page=${page}&page_size=${pageSize}`);
+        return {
+            ...result,
+            samples: result.samples || result.rows || [],
+            total: result.total ?? result.total_rows ?? 0,
+            total_pages: result.total_pages ?? 0,
+            rows: result.samples || result.rows || [],
+            total_rows: result.total ?? result.total_rows ?? 0,
+        };
+    }
+    /**
+     * Delete a dataset.
+     *
+     * @param id - Dataset ID.
+     *
+     * @example
+     * ```ts
+     * await client.datasets.delete('ds_abc123');
+     * ```
+     */
+    async delete(id) {
+        await this._http.fetchDelete(`/api/datasets/${encodeURIComponent(id)}`);
+    }
+    /**
+     * Import a dataset from HuggingFace Hub via a connected integration.
+     *
+     * Requires a HuggingFace integration to be set up. Use
+     * `client.integrations.list()` to find available integrations.
+     *
+     * @example
+     * ```ts
+     * const imported = await client.datasets.importFromHuggingFace({
+     *   repoId: 'databricks/dolly-15k',
+     *   integrationId: 'int_abc123',
+     *   name: 'Dolly 15k',
+     * });
+     * console.log(`Imported: ${imported.id}`);
+     * ```
+     */
+    async importFromHuggingFace(params) {
+        if (!params.integrationId) {
+            throw new Error('integrationId is required for importing from HuggingFace');
+        }
+        return normalizeDataset(await this._http.fetchPost(`/api/datasets/integrations/${encodeURIComponent(params.integrationId)}/import`, {
+            dataset_id: params.repoId,
+            name: params.name || params.repoId.split('/').pop() || params.repoId,
+            subset: params.subset,
+            split: params.split,
+            max_samples: params.maxSamples,
+            sample_strategy: params.sampleStrategy,
+            column_mapping: params.columnMapping,
+            import_mode: params.importMode,
+        }));
+    }
+    /**
+     * Register a HuggingFace dataset directly (without an integration).
+     *
+     * @example
+     * ```ts
+     * const ds = await client.datasets.registerHuggingFace({
+     *   repo_id: 'databricks/dolly-15k',
+     *   name: 'Dolly 15k',
+     *   split: 'train',
+     * });
+     * ```
+     */
+    async registerHuggingFace(params) {
+        const raw = params;
+        const repoId = String(raw.repoId || raw.hf_dataset_id || raw.repo_id || '');
+        if (!repoId)
+            throw new Error('BiOS: repoId is required');
+        const workspaceId = String(raw.workspaceId || raw.workspace_id || '') || this._http.workspaceId;
+        if (!workspaceId) {
+            throw new Error('BiOS: workspaceId is required to register a HuggingFace dataset');
+        }
+        const result = await this._http.fetchPost('/api/datasets/register-hf', {
+            hf_dataset_id: repoId,
+            name: raw.name || repoId.split('/').pop() || repoId,
+            workspace_id: workspaceId,
+            description: raw.description,
+            hf_subset: raw.subset ?? raw.hf_subset,
+            hf_split: raw.split ?? raw.hf_split,
+            max_samples: raw.maxSamples ?? raw.max_samples,
+            sample_strategy: raw.sampleStrategy ?? raw.sample_strategy,
+            column_mapping: raw.columnMapping ?? raw.column_mapping,
+            import_mode: raw.importMode ?? raw.import_mode,
+        });
+        return normalizeDataset(result);
+    }
+    /**
+     * Get the processing status of a dataset.
+     *
+     * @param id - Dataset ID.
+     *
+     * @example
+     * ```ts
+     * const status = await client.datasets.getStatus('ds_abc123');
+     * console.log(status);
+     * ```
+     */
+    async getStatus(id) {
+        return this._http.fetchGet(`/api/datasets/${encodeURIComponent(id)}/status`);
+    }
+    /**
+     * Validate a dataset file before uploading.
+     *
+     * @param filePath - Path to the file to validate.
+     *
+     * @example
+     * ```ts
+     * const result = await client.datasets.validate('./data.jsonl');
+     * if (result.format_valid) {
+     *   console.log(`Valid ${result.detected_format} with ${result.num_samples} rows`);
+     * } else {
+     *   console.error('Errors:', result.validation_errors);
+     * }
+     * ```
+     */
+    async validate(filePath) {
+        let fileData;
+        let fileName;
+        try {
+            const fs = await import('node:fs');
+            const path = await import('node:path');
+            const buf = fs.readFileSync(filePath);
+            fileData = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+            fileName = path.basename(filePath);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to read file at "${filePath}": ${message}`);
+        }
+        const blob = new Blob([fileData]);
+        const formData = new FormData();
+        formData.append('file', blob, fileName);
+        return this._http.fetchUpload('/api/datasets/validate', formData);
+    }
+    /**
+     * Get supported dataset format specifications.
+     *
+     * @example
+     * ```ts
+     * const specs = await client.datasets.getFormatSpecs();
+     * for (const spec of specs) {
+     *   console.log(`${spec.format}: ${spec.extensions.join(', ')}`);
+     * }
+     * ```
+     */
+    async getFormatSpecs() {
+        const result = await this._http.fetchGet('/api/datasets/format-specs');
+        const wrapped = result;
+        return wrapped.formats || result;
+    }
+    /**
+     * Search public datasets on HuggingFace Hub.
+     *
+     * @example
+     * ```ts
+     * const results = await client.datasets.searchHub({ query: 'code instruct' });
+     * ```
+     */
+    async searchHub(params = {}) {
+        const q = new URLSearchParams();
+        if (params.query)
+            q.set('q', params.query);
+        if (params.page !== undefined)
+            q.set('page', String(params.page));
+        if (params.sort)
+            q.set('sort', params.sort);
+        return this._http.fetchGet(`/api/datasets/hub-search?${q}`);
+    }
+    /**
+     * Preview rows from a HuggingFace Hub dataset before importing.
+     *
+     * @example
+     * ```ts
+     * const preview = await client.datasets.previewHub({
+     *   datasetId: 'databricks/dolly-15k',
+     *   split: 'train',
+     *   limit: 5,
+     * });
+     * ```
+     */
+    async previewHub(params) {
+        const q = new URLSearchParams({ dataset_id: params.datasetId });
+        if (params.split)
+            q.set('split', params.split);
+        if (params.subset)
+            q.set('subset', params.subset);
+        if (params.limit !== undefined)
+            q.set('limit', String(params.limit));
+        return this._http.fetchGet(`/api/datasets/hub-preview?${q}`);
+    }
+    /**
+     * Get storage usage for datasets.
+     *
+     * @param workspaceId - Optional workspace ID filter.
+     *
+     * @example
+     * ```ts
+     * const usage = await client.datasets.getStorageUsage();
+     * console.log(`${usage.total_bytes} bytes across ${usage.dataset_count} datasets`);
+     * ```
+     */
+    async getStorageUsage(workspaceId) {
+        const params = workspaceId ? `?workspace_id=${encodeURIComponent(workspaceId)}` : '';
+        return this._http.fetchGet(`/api/datasets/storage-usage${params}`);
+    }
+}

package/dist/resources/gpu-priorities.d.ts

@@ -0,0 +1,14 @@
+import type { GPUChoice } from '../types.js';
+export interface NormalizedGPUPlacement {
+    priorities: Array<{
+        gpu_type: string;
+        gpu_count: number;
+        provider?: string;
+        region?: string;
+        tier: 'secure';
+    }> | undefined;
+    gpuType: string | undefined;
+    gpuCount: number | undefined;
+}
+/** Validate the ranked placement contract shared by training and deployments. */
+export declare function normalizeGPUPlacement(choices: GPUChoice[] | undefined, queueEnabled: boolean, gpuType: string | undefined, gpuCount: number | undefined, queueField: 'queueIfUnavailable' | 'allowCapacityQueue'): NormalizedGPUPlacement;

package/dist/resources/gpu-priorities.js

@@ -0,0 +1,54 @@
+/** Validate the ranked placement contract shared by training and deployments. */
+export function normalizeGPUPlacement(choices, queueEnabled, gpuType, gpuCount, queueField) {
+    if (choices === undefined) {
+        if (queueEnabled) {
+            throw new Error(`BiOS: ${queueField}=true requires 3 to 5 gpuPriorities`);
+        }
+        return { priorities: undefined, gpuType, gpuCount };
+    }
+    if (!Array.isArray(choices) || choices.length === 0) {
+        throw new Error('BiOS: gpuPriorities must contain at least one choice');
+    }
+    if (choices.length > 5) {
+        throw new Error('BiOS: gpuPriorities accepts at most 5 choices');
+    }
+    if (queueEnabled && choices.length < 3) {
+        throw new Error(`BiOS: ${queueField}=true requires 3 to 5 gpuPriorities`);
+    }
+    if (!queueEnabled && choices.length !== 1) {
+        throw new Error(`BiOS: gpuPriorities must contain exactly one choice when ${queueField} is false`);
+    }
+    const seen = new Set();
+    const priorities = choices.map((choice, index) => {
+        const choiceType = choice.gpuType?.trim();
+        if (!choiceType)
+            throw new Error(`BiOS: gpuPriorities[${index}].gpuType is required`);
+        if (!Number.isInteger(choice.gpuCount) || choice.gpuCount < 1 || choice.gpuCount > 8) {
+            throw new Error(`BiOS: gpuPriorities[${index}].gpuCount must be an integer between 1 and 8`);
+        }
+        const provider = choice.provider?.trim().toLocaleLowerCase('en-US');
+        const region = choice.region?.trim().toLocaleLowerCase('en-US');
+        const tier = choice.tier?.trim().toLocaleLowerCase('en-US');
+        if (tier && tier !== 'secure')
+            throw new Error(`BiOS: gpuPriorities[${index}].tier must be secure`);
+        // Dedup key only — provider is emitted below solely when the caller set
+        // it. Neutral platform alias default (never a vendor name).
+        const key = `${provider || 'bios-cloud'}|${region || 'global'}|${tier || 'secure'}|${choiceType.toLocaleLowerCase('en-US')}`;
+        if (seen.has(key))
+            throw new Error('BiOS: gpuPriorities provider/region/tier/GPU placements must be distinct');
+        seen.add(key);
+        return {
+            gpu_type: choiceType,
+            gpu_count: choice.gpuCount,
+            ...(provider ? { provider } : {}),
+            ...(region ? { region } : {}),
+            tier: 'secure',
+        };
+    });
+    const first = priorities[0];
+    if ((gpuType !== undefined && gpuType.trim() !== first.gpu_type)
+        || (gpuCount !== undefined && gpuCount !== first.gpu_count)) {
+        throw new Error('BiOS: gpuType/gpuCount must match the first gpuPriorities choice');
+    }
+    return { priorities, gpuType: first.gpu_type, gpuCount: first.gpu_count };
+}

package/dist/resources/gpu.d.ts

@@ -0,0 +1,60 @@
+import type { HttpClient } from '../client.js';
+import type { GPUPricingResponse, GPUInfo, GPUOptionsParams, GPUOptionsResponse } from '../types.js';
+/**
+ * View GPU pricing, availability, and get recommendations for your model.
+ */
+export declare class GPU {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: HttpClient);
+    /**
+     * Get pricing and availability for all GPU types.
+     *
+     * Returns the full catalog of GPUs with per-hour pricing, VRAM,
+     * and which training methods each supports.
+     *
+     * @example
+     * ```ts
+     * 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`);
+     * }
+     * ```
+     */
+    getPricing(): Promise<GPUPricingResponse>;
+    /**
+     * Get authoritative, model-aware training GPU options with live stock,
+     * required counts, total prices, and alternatives when nothing is bookable.
+     */
+    getOptions(params: GPUOptionsParams): Promise<GPUOptionsResponse>;
+    /**
+     * Get the recommended GPU configuration for a specific model.
+     *
+     * Uses the model's parameter count and architecture to suggest
+     * the best GPU type and count for training.
+     *
+     * @param modelId - Full HuggingFace model ID (e.g. "meta-llama/Llama-3.1-8B-Instruct").
+     *
+     * @example
+     * ```ts
+     * 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}`);
+     * }
+     * ```
+    */
+    getRecommended(modelId: string): Promise<GPURecommendation | null>;
+}
+/** GPU recommendation with sizing rationale. */
+export interface GPURecommendation extends GPUInfo {
+    /** Recommended number of GPUs. */
+    recommended_count: number;
+    /** Total VRAM across all recommended GPUs. */
+    total_vram_gb: number;
+    /** Estimated hourly cost in cents for the recommended configuration. */
+    estimated_cost_per_hour_cents: number;
+    /** Model parameter count in billions. */
+    model_params_b: number;
+    /** Human-readable recommendation reason. */
+    reason: string;
+}