runbios-sdk 0.2.1-dev.62

package/dist/resources/models.d.ts

@@ -0,0 +1,113 @@
+import type { HttpClient } from '../client.js';
+import type { ModelDetailResponse, ModelSearchParams, ModelSearchResponse, ModelConfig, AdapterCompatibilityParams, AdapterCompatibilityResponse, ArchitectureScope, SupportedArchitecturesResponse } from '../types.js';
+/**
+ * Access the Run BiOS model catalog -- search models, fetch
+ * training-relevant configuration, and check adapter compatibility.
+ */
+export declare class Models {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: HttpClient);
+    /**
+     * Search the Run BiOS model catalog -- the platform's own hosted, verified
+     * models. Every result is mirrored in Run BiOS storage and can be trained and
+     * deployed; this is never a live Hugging Face search. A model that is not
+     * listed here is not hosted on Run BiOS yet.
+     *
+     * Reads the registry endpoint `GET /api/models` DIRECTLY. Each result is the
+     * registry's own snake_case row plus `maxContext` (the native context window
+     * that caps a deployment's `contextLength`) and `weightBytes`. Note that `id`
+     * is the registry UUID -- the model HANDLE you pass to training and
+     * deployment is `repo_id`.
+     *
+     * `query` becomes the registry's `q` filter, the only search parameter it
+     * reads. The deprecated `author` / `visibility` / `kind` / `integrationId`
+     * filters are ignored by the registry and are no longer sent.
+     *
+     * @example
+     * ```ts
+     * const res = await client.models.search({ query: 'llama', type: 'llm', limit: 10 });
+     * for (const m of res.models) {
+     *   console.log(`${m.repo_id} -- ${m.params_total_b}B params, ${m.maxContext} ctx`);
+     * }
+     * ```
+     */
+    search(params?: ModelSearchParams): Promise<ModelSearchResponse>;
+    /**
+     * Fetch one catalog model by its `author/name` handle.
+     *
+     * The model block carries `maxContext` (the native context window that caps
+     * `contextLength` on a deployment) and `weightBytes` (on-disk weight size),
+     * both absent for partner/private models.
+     */
+    get(modelId: string): Promise<ModelDetailResponse>;
+    /**
+     * Native max context window in tokens, or undefined when not recorded.
+     *
+     * This is the ceiling a deployment's `contextLength` can never exceed.
+     * `undefined` means UNKNOWN (unreachable registry, unlisted model, or a
+     * partner model with the fact stripped) -- never treat it as zero.
+     */
+    nativeMaxContext(modelId: string): Promise<number | undefined>;
+    /**
+     * Fetch the training configuration for a specific model from the catalog.
+     *
+     * Returns parameter counts, architecture type, and whether the model
+     * uses Mixture-of-Experts -- information needed to choose the right
+     * GPU and adapter configuration.
+     *
+     * @param modelId - Full model id (e.g. "meta-llama/Llama-3.1-8B").
+     *
+     * @example
+     * ```ts
+     * const config = await client.models.getConfig('meta-llama/Llama-3.1-8B');
+     * console.log(`${config.totalParams}B params, MoE: ${config.isMoE}`);
+     * ```
+     */
+    getConfig(modelId: string): Promise<ModelConfig>;
+    /**
+     * Check which adapters are compatible with a given architecture,
+     * training method, and (optionally) RLHF algorithm.
+     *
+     * @example
+     * ```ts
+     * 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`);
+     * ```
+     */
+    getAdapterCompatibility(params?: AdapterCompatibilityParams): Promise<AdapterCompatibilityResponse>;
+    /**
+     * List the architectures the platform supports for a given scope. This is
+     * the authoritative registry the platform gates on:
+     *  - `inference` — architecture classes that can be served (deployed).
+     *  - `training` — architecture keys the fine-tuning wizard/gate accepts.
+     *
+     * A `count` of 0 means the registry is empty and nothing is explicitly
+     * restricted (every architecture the engine supports is allowed).
+     *
+     * ```ts
+     * const { architectures } = await client.models.getSupportedArchitectures({ scope: 'inference' });
+     * const servable = architectures.filter(a => a.enabled).map(a => a.architecture);
+     * ```
+     */
+    getSupportedArchitectures(params?: {
+        scope?: ArchitectureScope;
+    }): Promise<SupportedArchitecturesResponse>;
+}
+/** Registry detail path for an `author/name` catalog id, else undefined. @internal */
+export declare function modelDetailPath(modelId: string): string | undefined;
+/**
+ * Native max context window (tokens) for a catalog model, or undefined.
+ *
+ * Reads the registry directly (`GET /api/models/{author}/{name}` ->
+ * `model.maxContext`). Returns undefined for anything that is not an ANSWER: an
+ * id that is not `author/name`, an unreachable registry, a model the registry
+ * does not carry, or a model whose native window is not recorded. Callers MUST
+ * treat undefined as UNKNOWN and never as a rejection. @internal
+ */
+export declare function readNativeMaxContext(http: HttpClient, modelId: string): Promise<number | undefined>;

package/dist/resources/models.js

@@ -0,0 +1,171 @@
+/**
+ * Access the Run BiOS model catalog -- search models, fetch
+ * training-relevant configuration, and check adapter compatibility.
+ */
+export class Models {
+    _http;
+    /** @internal */
+    constructor(_http) {
+        this._http = _http;
+    }
+    /**
+     * Search the Run BiOS model catalog -- the platform's own hosted, verified
+     * models. Every result is mirrored in Run BiOS storage and can be trained and
+     * deployed; this is never a live Hugging Face search. A model that is not
+     * listed here is not hosted on Run BiOS yet.
+     *
+     * Reads the registry endpoint `GET /api/models` DIRECTLY. Each result is the
+     * registry's own snake_case row plus `maxContext` (the native context window
+     * that caps a deployment's `contextLength`) and `weightBytes`. Note that `id`
+     * is the registry UUID -- the model HANDLE you pass to training and
+     * deployment is `repo_id`.
+     *
+     * `query` becomes the registry's `q` filter, the only search parameter it
+     * reads. The deprecated `author` / `visibility` / `kind` / `integrationId`
+     * filters are ignored by the registry and are no longer sent.
+     *
+     * @example
+     * ```ts
+     * const res = await client.models.search({ query: 'llama', type: 'llm', limit: 10 });
+     * for (const m of res.models) {
+     *   console.log(`${m.repo_id} -- ${m.params_total_b}B params, ${m.maxContext} ctx`);
+     * }
+     * ```
+     */
+    async search(params = {}) {
+        const q = new URLSearchParams();
+        if (params.query)
+            q.set('q', params.query);
+        if (params.type)
+            q.set('type', params.type);
+        if (params.offset !== undefined)
+            q.set('offset', String(params.offset));
+        if (params.limit !== undefined)
+            q.set('limit', String(params.limit));
+        if (params.minParams !== undefined)
+            q.set('min_params', String(params.minParams));
+        if (params.maxParams !== undefined)
+            q.set('max_params', String(params.maxParams));
+        if (params.sort)
+            q.set('sort', params.sort);
+        return this._http.fetchGet(`/api/models?${q}`);
+    }
+    /**
+     * Fetch one catalog model by its `author/name` handle.
+     *
+     * The model block carries `maxContext` (the native context window that caps
+     * `contextLength` on a deployment) and `weightBytes` (on-disk weight size),
+     * both absent for partner/private models.
+     */
+    async get(modelId) {
+        const path = modelDetailPath(modelId);
+        if (!path)
+            throw new Error('RunBiOS: modelId must be a catalog handle of the form author/name');
+        return this._http.fetchGet(path);
+    }
+    /**
+     * Native max context window in tokens, or undefined when not recorded.
+     *
+     * This is the ceiling a deployment's `contextLength` can never exceed.
+     * `undefined` means UNKNOWN (unreachable registry, unlisted model, or a
+     * partner model with the fact stripped) -- never treat it as zero.
+     */
+    async nativeMaxContext(modelId) {
+        return readNativeMaxContext(this._http, modelId);
+    }
+    /**
+     * Fetch the training configuration for a specific model from the catalog.
+     *
+     * Returns parameter counts, architecture type, and whether the model
+     * uses Mixture-of-Experts -- information needed to choose the right
+     * GPU and adapter configuration.
+     *
+     * @param modelId - Full model id (e.g. "meta-llama/Llama-3.1-8B").
+     *
+     * @example
+     * ```ts
+     * const config = await client.models.getConfig('meta-llama/Llama-3.1-8B');
+     * console.log(`${config.totalParams}B params, MoE: ${config.isMoE}`);
+     * ```
+     */
+    async getConfig(modelId) {
+        return this._http.fetchGet(`/api/public/model-config?id=${encodeURIComponent(modelId)}`);
+    }
+    /**
+     * Check which adapters are compatible with a given architecture,
+     * training method, and (optionally) RLHF algorithm.
+     *
+     * @example
+     * ```ts
+     * 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`);
+     * ```
+     */
+    async getAdapterCompatibility(params = {}) {
+        const q = new URLSearchParams();
+        if (params.architecture)
+            q.set('architecture', params.architecture);
+        if (params.modelType)
+            q.set('model_type', params.modelType);
+        if (params.trainingMethod)
+            q.set('training_method', params.trainingMethod);
+        if (params.rlhfAlgorithm)
+            q.set('rlhf_algorithm', params.rlhfAlgorithm);
+        return this._http.fetchGet(`/api/public/adapter-compatibility?${q}`);
+    }
+    /**
+     * List the architectures the platform supports for a given scope. This is
+     * the authoritative registry the platform gates on:
+     *  - `inference` — architecture classes that can be served (deployed).
+     *  - `training` — architecture keys the fine-tuning wizard/gate accepts.
+     *
+     * A `count` of 0 means the registry is empty and nothing is explicitly
+     * restricted (every architecture the engine supports is allowed).
+     *
+     * ```ts
+     * const { architectures } = await client.models.getSupportedArchitectures({ scope: 'inference' });
+     * const servable = architectures.filter(a => a.enabled).map(a => a.architecture);
+     * ```
+     */
+    async getSupportedArchitectures(params = {}) {
+        const q = new URLSearchParams();
+        q.set('scope', params.scope ?? 'inference');
+        return this._http.fetchGet(`/api/public/serving-architectures?${q}`);
+    }
+}
+/** Registry detail path for an `author/name` catalog id, else undefined. @internal */
+export function modelDetailPath(modelId) {
+    const repo = (modelId || '').trim().replace(/^\/+|\/+$/g, '');
+    const parts = repo.split('/');
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return undefined;
+    return `/api/models/${encodeURIComponent(parts[0])}/${encodeURIComponent(parts[1])}`;
+}
+/**
+ * Native max context window (tokens) for a catalog model, or undefined.
+ *
+ * Reads the registry directly (`GET /api/models/{author}/{name}` ->
+ * `model.maxContext`). Returns undefined for anything that is not an ANSWER: an
+ * id that is not `author/name`, an unreachable registry, a model the registry
+ * does not carry, or a model whose native window is not recorded. Callers MUST
+ * treat undefined as UNKNOWN and never as a rejection. @internal
+ */
+export async function readNativeMaxContext(http, modelId) {
+    const path = modelDetailPath(modelId);
+    if (!path)
+        return undefined;
+    let response;
+    try {
+        response = await http.fetchGet(path);
+    }
+    catch {
+        return undefined;
+    }
+    const native = response?.model?.maxContext;
+    return typeof native === 'number' && Number.isFinite(native) && native > 0 ? native : undefined;
+}

package/dist/resources/training.d.ts

@@ -0,0 +1,166 @@
+import type { HttpClient } from '../client.js';
+import type { TrainingCreateParams, TrainingListParams, TrainingJob, TrainingListResponse, TrainingMetrics, TrainingCheckpoint, TrainingLogs, TrainingStopResponse, TrainingResumeResponse, TrainingPreflightResponse, TrainingCapabilities } from '../types.js';
+/**
+ * Create, monitor, and manage fine-tuning training jobs.
+ */
+export declare class Training {
+    private readonly _http;
+    /** @internal */
+    constructor(_http: HttpClient);
+    /** Return the authoritative method, adapter, and hyperparameter contract Run BiOS trains against. */
+    capabilities(): Promise<TrainingCapabilities>;
+    /**
+     * 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}`);
+     * ```
+    */
+    create(params: TrainingCreateParams): Promise<TrainingJob>;
+    /** Validate and canonicalize a training request without creating or billing a job. */
+    preflight(params: TrainingCreateParams): Promise<TrainingPreflightResponse>;
+    /** Return one server-driven page with pagination metadata. */
+    listPage(params?: TrainingListParams): Promise<TrainingListResponse>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    list(params?: TrainingListParams): Promise<TrainingJob[]>;
+    /**
+     * 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}%`);
+     * ```
+     */
+    get(id: string): Promise<TrainingJob>;
+    /**
+     * 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`);
+     * ```
+     */
+    getMetrics(id: string): Promise<TrainingMetrics>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    getCheckpoints(id: string): Promise<TrainingCheckpoint[]>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    getLogs(id: string, tail?: number): Promise<TrainingLogs>;
+    /**
+     * 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');
+     * ```
+     */
+    stop(id: string, keepData?: boolean): Promise<TrainingStopResponse>;
+    /**
+     * 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');
+     * ```
+     */
+    resume(id: string, idempotencyKey?: string): Promise<TrainingResumeResponse>;
+    /**
+     * 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');
+     * ```
+     */
+    getEvals(id: string): Promise<Record<string, unknown>>;
+    deleteCheckpoint(jobId: string, checkpointId: string): Promise<void>;
+}