runbios-sdk 0.2.1-dev.116 → 0.2.1-dev.120

package/dist/index.d.ts

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export declare const VERSION = "0.2.1-dev.116";
+export declare const VERSION = "0.2.1-dev.120";
 export declare class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     readonly models: Models;
@@ -75,4 +75,4 @@ export { Training } from './resources/training.js';
 export { Wallet } from './resources/wallet.js';
 export { GPU, type GPURecommendation } from './resources/gpu.js';
 export { Inference, validateChatRequest, parseSSE, buildInferenceRequest, contextSizingBasis, type ContextSizingBasis, CONTEXT_DEFAULT_CEILING, CONTEXT_EDITABLE_FLOOR, type ChatMessage, type FunctionTool, type ChatCompletionParams, type ChatCompletionResponse, type ChatCompletionChunk, } from './resources/inference.js';
-export type { BiOSConfig, PaginatedResponse, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement, InferenceBookingAccepted, Model, ModelSearchParams, ModelSearchResponse, ModelDetailResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, TrainingResourceMetrics, TrainingDeviceMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListResponse, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceDeploymentSummary, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, PromptTokensDetails, ChatCompletionUsage, } from './types.js';
+export type { BiOSConfig, PaginatedResponse, ApiErrorBody, AvailableGpuAlternative, CapacityMinimumRequirement, InferenceBookingAccepted, Model, ModelSearchParams, ModelSearchResponse, ModelDetailResponse, ModelConfig, Dataset, DatasetListParams, DatasetListResponse, DatasetUploadParams, DatasetPreview, DatasetPreviewParams, DatasetImportHFParams, DatasetRegisterHFParams, DatasetHubSearchParams, DatasetHubPreviewParams, DatasetValidation, DatasetFormatVariant, DatasetFormatSpec, DatasetFormatSpecs, DatasetStorageUsage, TrainingMethod, RLHFAlgorithm, AdapterType, TrainingJobStatus, TrainingStatusFilter, TrainingCreateParams, TrainingListParams, TrainingListResponse, TrainingJob, TrainingMetrics, TrainingResourceMetrics, TrainingDeviceMetrics, MetricPoint, MetricGraphConfig, TrainingCheckpoint, TrainingLogs, TrainingLogEntry, TrainingStopResponse, TrainingResumeResponse, CanonicalTrainingRequest, TrainingPreflightDataset, TrainingPreflightWarning, TrainingPreflightResponse, TrainingCapabilityChoice, TrainingConfigFieldCapability, TrainingCapabilities, GPUChoice, WalletBalance, Transaction, TransactionListResponse, TransactionListParams, GPUInfo, GPUPricingResponse, GPUOptionsParams, TrainingRecommendParams, TrainingAdvisorVerdict, TrainingAdvisorRecommendation, TrainingAdvisorUserShape, TrainingAdvisorJustification, TrainingAdvisorBasis, GPUOption, GPUOptionSuggestion, GPUOptionsResponse, InferenceStatus, InferenceCreateParams, InferenceUpdateParams, InferenceDeployment, InferenceDeploymentSummary, InferenceCreateResponse, InferenceListResponse, InferenceUpdateResponse, InferenceLifecycleResponse, InferenceDeleteResponse, InferenceGPUOptionMarket, InferenceGPUOption, InferenceGPUAlternative, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceCanonicalRequest, InferencePreflightWarning, InferencePreflightResponse, AdapterCompatibility, AdapterCompatibilityResponse, AdapterCompatibilityParams, SupportedArchitecture, ArchitectureScope, SupportedArchitecturesResponse, ApiKey, ApiKeyScope, ApiKeyIntrospection, Organization, OrgMember, OrgInvite, Workspace, Integration, IntegrationCreateParams, StorageUsage, StorageObject, PromptTokensDetails, ChatCompletionUsage, } from './types.js';

package/dist/index.js

@@ -36,7 +36,7 @@ import { Loop } from './resources/loop.js';
  * SDK version. Sent as part of the User-Agent header.
  * Must match package.json "version" -- enforced by a contract test.
  */
-export const VERSION = '0.2.1-dev.116';
+export const VERSION = '0.2.1-dev.120';
 export class RunBiOS {
     /** Search models, fetch configs, check adapter compatibility. */
     models;

package/dist/resources/gpu.js

@@ -46,6 +46,13 @@ export class GPU {
         if (params.modelActiveParamsB !== undefined) {
             q.set('model_active_params_b', String(params.modelActiveParamsB));
         }
+        if (params.maxLength !== undefined)
+            q.set('max_length', String(params.maxLength));
+        if (params.effectiveBatch !== undefined)
+            q.set('effective_batch', String(params.effectiveBatch));
+        else if (params.perDeviceTrainBatchSize !== undefined) {
+            q.set('per_device_train_batch_size', String(params.perDeviceTrainBatchSize));
+        }
         return this._http.fetchGet(`/api/training/gpu-options?${q}`);
     }
     /**

package/dist/resources/training.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { TrainingCreateParams, TrainingListParams, TrainingJob, TrainingListResponse, TrainingMetrics, TrainingCheckpoint, TrainingLogs, TrainingStopResponse, TrainingResumeResponse, TrainingPreflightResponse, TrainingCapabilities } from '../types.js';
+import type { TrainingCreateParams, TrainingListParams, TrainingJob, TrainingListResponse, TrainingMetrics, TrainingCheckpoint, TrainingLogs, TrainingStopResponse, TrainingResumeResponse, TrainingPreflightResponse, TrainingRecommendParams, TrainingAdvisorVerdict, TrainingCapabilities } from '../types.js';
 /**
  * Create, monitor, and manage fine-tuning training jobs.
  */
@@ -55,6 +55,14 @@ export declare class Training {
     create(params: TrainingCreateParams): Promise<TrainingJob>;
     /** Validate and canonicalize a training request without creating or billing a job. */
     preflight(params: TrainingCreateParams): Promise<TrainingPreflightResponse>;
+    /**
+     * Ask the trainer's own sizing model what to run: per-device batch,
+     * accumulation, learning rate, warmup, predicted peak memory, minimum GPU
+     * count and a wall-clock estimate for this model on this GPU type, with the
+     * basis of every number. Side-effect free. When `available` is false no
+     * advisor is deployed and the other fields are absent -- nothing is guessed.
+     */
+    recommend(params: TrainingRecommendParams): Promise<TrainingAdvisorVerdict>;
     /** Return one server-driven page with pagination metadata. */
     listPage(params?: TrainingListParams): Promise<TrainingListResponse>;
     /**

package/dist/resources/training.js

@@ -244,6 +244,41 @@ export class Training {
         const { body } = buildTrainingRequest(params);
         return this._http.fetchPost('/api/training/preflight', body);
     }
+    /**
+     * Ask the trainer's own sizing model what to run: per-device batch,
+     * accumulation, learning rate, warmup, predicted peak memory, minimum GPU
+     * count and a wall-clock estimate for this model on this GPU type, with the
+     * basis of every number. Side-effect free. When `available` is false no
+     * advisor is deployed and the other fields are absent -- nothing is guessed.
+     */
+    async recommend(params) {
+        const q = new URLSearchParams({ model_id: params.model, gpu_type: params.gpuType });
+        if (params.modelRevision)
+            q.set('model_revision', params.modelRevision);
+        if (params.integrationId)
+            q.set('integration_id', params.integrationId);
+        if (params.gpuCount !== undefined)
+            q.set('gpu_count', String(params.gpuCount));
+        if (params.adapter)
+            q.set('train_type', params.adapter);
+        if (params.method)
+            q.set('method', params.method === 'cpt' ? 'pt' : params.method);
+        if (params.maxLength !== undefined)
+            q.set('max_length', String(params.maxLength));
+        if (params.epochs !== undefined)
+            q.set('num_train_epochs', String(params.epochs));
+        if (params.maxSteps !== undefined)
+            q.set('max_steps', String(params.maxSteps));
+        if (params.perDeviceTrainBatchSize !== undefined)
+            q.set('per_device_train_batch_size', String(params.perDeviceTrainBatchSize));
+        if (params.gradientAccumulationSteps !== undefined)
+            q.set('gradient_accumulation_steps', String(params.gradientAccumulationSteps));
+        if (params.datasetIds?.length)
+            q.set('dataset_ids', params.datasetIds.join(','));
+        if (params.workspaceId)
+            q.set('workspace_id', params.workspaceId);
+        return this._http.fetchGet(`/api/training/recommend?${q}`);
+    }
     /** Return one server-driven page with pagination metadata. */
     async listPage(params = {}) {
         const q = new URLSearchParams();

package/dist/types.d.ts

@@ -907,6 +907,8 @@ export interface TrainingPreflightDataset {
 export interface TrainingPreflightWarning {
     code: string;
     message: string;
+    /** Request field the warning is about (e.g. `per_device_train_batch_size`), when there is one. */
+    field?: string;
 }
 /** Side-effect-free validation/sizing result; this endpoint never creates or bills a job. */
 export interface TrainingPreflightResponse {
@@ -927,6 +929,131 @@ export interface TrainingPreflightResponse {
     queue_eligible: boolean;
     warnings: TrainingPreflightWarning[];
     checked_at: string;
+    /**
+     * The trainer image's own sizing verdict for the requested GPU shape:
+     * recommended microbatch/accumulation/learning rate, predicted peak memory,
+     * minimum GPU count, wall-clock estimate, and whether the per-device batch
+     * you asked for is predicted to fit. Absent when no advisor is deployed.
+     */
+    advisor?: TrainingAdvisorVerdict;
+}
+/** Parameters for `training.recommend()` (GET /api/training/recommend). */
+export interface TrainingRecommendParams {
+    model: string;
+    modelRevision?: string;
+    integrationId?: string;
+    gpuType: string;
+    gpuCount?: number;
+    adapter?: 'full' | 'lora' | 'qlora';
+    method?: 'sft' | 'cpt' | 'pt';
+    maxLength?: number;
+    epochs?: number;
+    maxSteps?: number;
+    /** Your own microbatch, to be judged against the model. */
+    perDeviceTrainBatchSize?: number;
+    gradientAccumulationSteps?: number;
+    /** Datasets the job will train on; their measured token statistics feed the sizing. */
+    datasetIds?: string[];
+    workspaceId?: string;
+}
+/** Basis of one recommended value: measured on hardware, derived through a stated model, or an argued default. */
+export type TrainingAdvisorBasis = 'measured' | 'derived' | 'judgement';
+export interface TrainingAdvisorJustification {
+    field: string;
+    value: string;
+    reason: string;
+    basis: TrainingAdvisorBasis;
+}
+export interface TrainingAdvisorRecommendation {
+    per_device_train_batch_size: number;
+    gradient_accumulation_steps: number;
+    global_batch_size: number;
+    activation_checkpoint: string;
+    compile: boolean;
+    learning_rate: number;
+    warmup_steps: number;
+    parallelism: {
+        dp_replicate: number;
+        dp_shard: number;
+        tp: number;
+        pp: number;
+        cp: number;
+        ep: number;
+    };
+    /** Predicted peak reserved GPU memory per device, GiB. */
+    predicted_peak_gb: number;
+    /** (median, worst) percent the prediction ran over measurement on the calibration rows. */
+    memory_band_percent: [number, number];
+    memory_class: string;
+    predicted_mfu: number;
+    supervised_tokens_per_step: number;
+    predicted_roughness: number;
+    tokens_per_second: number;
+    throughput_basis: 'measured' | 'derived';
+    wall_clock: {
+        steps_per_epoch: number;
+        total_steps: number;
+        training_hours: number;
+        startup_minutes_estimate: number;
+        basis: TrainingAdvisorBasis;
+    } | null;
+}
+export interface TrainingAdvisorUserShape {
+    per_device_train_batch_size: number;
+    fits: boolean;
+    largest_fitting_batch?: number;
+    predicted_peak_gb?: number;
+    reason?: string;
+    /** Same global batch, a microbatch that fits. Present only when `fits` is false. */
+    suggested?: {
+        per_device_train_batch_size: number;
+        gradient_accumulation_steps: number;
+        reason: string;
+    };
+}
+/**
+ * Verdict of the training advisor. `available: false` means no advisor is
+ * deployed or it did not answer; nothing else is populated then.
+ */
+export interface TrainingAdvisorVerdict {
+    available: boolean;
+    reason?: string;
+    fits?: boolean;
+    /** Smallest GPU count of this type the job fits on; null when none up to the per-job cap. */
+    min_gpu_count?: number | null;
+    gpu?: {
+        platform_type: string;
+        sized_as: string;
+        capacity_gb: number;
+        capacity_measured: boolean;
+    };
+    model?: {
+        params_total_b: number;
+        params_active_b: number;
+        is_moe: boolean;
+        is_vlm: boolean;
+        has_linear_attention: boolean;
+    };
+    dataset_measured?: boolean;
+    seq_len?: number;
+    gpu_count?: number;
+    recommended?: TrainingAdvisorRecommendation;
+    user_shape?: TrainingAdvisorUserShape;
+    justifications?: TrainingAdvisorJustification[];
+    warnings?: string[];
+    dataset_stats_used?: {
+        num_rows: number;
+        avg_tokens_per_sample?: number;
+        avg_supervised_tokens_per_sample?: number;
+        has_images: boolean;
+        estimated: boolean;
+    };
+    measured_history?: {
+        tokens_per_second: number;
+        memory_anchors: number;
+    };
+    model_id?: string;
+    model_revision?: string;
 }
 /** One method, algorithm, or adapter reported by the pinned training engine. */
 export interface TrainingCapabilityChoice {
@@ -1099,6 +1226,17 @@ export interface GPUOptionsParams {
     rlhfType?: RLHFAlgorithm | string;
     modelParamsB?: number;
     modelActiveParamsB?: number;
+    /** Training sequence length the sizing should assume (tokens). */
+    maxLength?: number;
+    /**
+     * Effective batch (samples per optimizer step) -- the quality decision made
+     * before a GPU is chosen. Each option then answers with the per-device split
+     * that runs it there (`recommended_micro_batch` x `recommended_grad_accum`
+     * x `required_count`), and the minimum GPU count is sized at micro-batch 1.
+     */
+    effectiveBatch?: number;
+    /** Per-device batch to size as typed instead (ignored when effectiveBatch is set). */
+    perDeviceTrainBatchSize?: number;
 }
 /** One model-aware GPU option with live stock and total-price context. */
 export interface GPUOption {
@@ -1119,6 +1257,10 @@ export interface GPUOption {
     bookable: boolean;
     reason?: string;
     checked_at?: string;
+    /** Present when the request stated an effective batch: its split on this card at required_count. */
+    effective_batch?: number;
+    recommended_micro_batch?: number;
+    recommended_grad_accum?: number;
 }
 /** Actionable alternative returned when no GPU option is currently bookable. */
 export interface GPUOptionSuggestion {
@@ -1148,6 +1290,10 @@ export interface GPUOptionsResponse {
         storage_gb: number;
         price_per_hour_cents: number;
         total_price_per_hour_cents: number;
+        /** Present when the request stated an effective batch. */
+        effective_batch?: number;
+        per_device_train_batch_size?: number;
+        gradient_accumulation_steps?: number;
     };
     suggestions?: GPUOptionSuggestion[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runbios-sdk",
-  "version": "0.2.1-dev.116",
+  "version": "0.2.1-dev.120",
   "description": "Official TypeScript SDK for the Run BiOS training and deployment platform API",
   "type": "module",
   "main": "./dist/index.js",