runbios-sdk 0.2.1-dev.100

package/dist/resources/gpu.js

@@ -0,0 +1,101 @@
+/**
+ * View GPU pricing, availability, and get recommendations for your model.
+ */
+export class GPU {
+    _http;
+    /** @internal */
+    constructor(_http) {
+        this._http = _http;
+    }
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    async getPricing() {
+        return this._http.fetchGet('/api/public/gpu-pricing');
+    }
+    /**
+     * Get authoritative, model-aware training GPU options with live stock,
+     * required counts, total prices, and alternatives when nothing is bookable.
+     */
+    async getOptions(params) {
+        const q = new URLSearchParams({
+            model_id: params.modelId,
+            train_type: String(params.trainType || params.adapter || 'lora'),
+        });
+        if (params.modelRevision)
+            q.set('model_revision', params.modelRevision);
+        if (params.integrationId)
+            q.set('integration_id', params.integrationId);
+        if (params.method)
+            q.set('method', params.method);
+        if (params.rlhfType)
+            q.set('rlhf_type', params.rlhfType);
+        if (params.modelParamsB !== undefined)
+            q.set('model_params_b', String(params.modelParamsB));
+        if (params.modelActiveParamsB !== undefined) {
+            q.set('model_active_params_b', String(params.modelActiveParamsB));
+        }
+        return this._http.fetchGet(`/api/training/gpu-options?${q}`);
+    }
+    /**
+     * 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 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}`);
+     * }
+     * ```
+    */
+    async getRecommended(modelId) {
+        const options = await this.getOptions({ modelId, trainType: 'lora', method: 'sft' });
+        const recommended = options.recommended;
+        if (!recommended)
+            return null;
+        const option = options.options.find((item) => item.gpu_type === recommended.gpu_type);
+        if (!option?.bookable)
+            return null;
+        // Preserve the legacy recommendation shape while deriving sizing, stock,
+        // and total cost from the same authoritative endpoint as job creation.
+        const pricing = await this.getPricing();
+        const catalog = pricing.gpus.find((item) => item.gpu_type === recommended.gpu_type);
+        const pricePerGPU = recommended.price_per_hour_cents || option.price_per_hour_cents;
+        return {
+            gpu_type: recommended.gpu_type,
+            display_name: catalog?.display_name || option.display_name,
+            vram_gb: catalog?.vram_gb || option.vram_gb,
+            tier: catalog?.tier || '',
+            best_for: catalog?.best_for || '',
+            max_gpu_count: catalog?.max_gpu_count || option.max_gpu_count,
+            default_storage_gb: recommended.storage_gb,
+            param_range: catalog?.param_range || '',
+            methods: catalog?.methods || '',
+            available: option.available,
+            available_count: option.available_count,
+            price_per_hour_cents: pricePerGPU,
+            price_display: catalog?.price_display || `$${(pricePerGPU / 100).toFixed(2)}/hr`,
+            recommended_count: recommended.gpu_count,
+            total_vram_gb: option.vram_gb * recommended.gpu_count,
+            estimated_cost_per_hour_cents: recommended.total_price_per_hour_cents,
+            model_params_b: options.model_params_b,
+            reason: 'Cheapest currently bookable configuration that meets the model and adapter requirements',
+        };
+    }
+}

package/dist/resources/inference.d.ts

@@ -0,0 +1,230 @@
+import type { HttpClient } from '../client.js';
+import type { InferenceDeployment, InferenceDeploymentSummary, InferenceBookingAccepted, InferenceCreateParams, InferenceCreateResponse, InferenceDeleteResponse, InferenceGPUOptionsParams, InferenceGPUOptionsResponse, InferenceLifecycleResponse, InferenceListParams, InferenceListResponse, InferenceNotificationListResponse, InferencePreflightResponse, InferenceUpdateResponse, InferenceUpdateParams } from '../types.js';
+/**
+ * Serving context-length policy, owned and enforced by the server. Mirrored
+ * here for documentation only -- never to pre-empt a server verdict.
+ *
+ *   default = min(nativeMax, CONTEXT_DEFAULT_CEILING)
+ *   the window is editable only when nativeMax exceeds CONTEXT_EDITABLE_FLOOR,
+ *   and a request can NEVER exceed the model's own nativeMax (that is a 400).
+ *
+ * CONTEXT_EDITABLE_FLOOR doubles as the default when the native window is
+ * unknown; a genuinely small-context model keeps its own native window rather
+ * than being raised to the floor.
+ */
+export declare const CONTEXT_DEFAULT_CEILING = 262144;
+export declare const CONTEXT_EDITABLE_FLOOR = 32768;
+/**
+ * The sizing BASIS the advisory capacity check is allowed to reason from —
+ * what window the SERVER will size the request at, as far as this client can
+ * prove it. Deliberately not "what type did the caller pass": the trust
+ * decision must be identical for the same over-native window whether it
+ * arrives as `999999` or `'999999'` (TypeScript types are erased, and a JSON
+ * config, a form field or a plain-JS caller all hand over strings).
+ *
+ * - `server_default` — no window asked for. The server sizes
+ *   `min(nativeMax, CONTEXT_DEFAULT_CEILING)`, which can never exceed native,
+ *   and treats `null` and any non-positive value the same way. Sound with no
+ *   extra request.
+ * - `explicit` — an integral window this client can compare against the
+ *   registry's native max.
+ * - `unprovable` — anything else. Coercing it and then trusting the result
+ *   would put the fabricated verdict straight back: a numeric string reaches
+ *   the sizing endpoint verbatim as a query param and inflates `min_gpus`
+ *   exactly like the number. @internal
+ */
+export type ContextSizingBasis = 'server_default' | 'explicit' | 'unprovable';
+export declare function contextSizingBasis(requested: unknown): [ContextSizingBasis, number];
+declare function buildInferenceRequest(params: InferenceCreateParams): Record<string, unknown>;
+export interface ChatMessage extends Record<string, unknown> {
+    role: 'system' | 'developer' | 'user' | 'assistant' | 'tool' | 'function';
+    content?: unknown;
+}
+export interface FunctionTool extends Record<string, unknown> {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+        strict?: boolean;
+    };
+}
+export interface ChatCompletionParams extends Record<string, unknown> {
+    messages: ChatMessage[];
+    model?: string;
+    tools?: FunctionTool[];
+    toolChoice?: 'none' | 'auto' | 'required' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+    /**
+     * Standardized reasoning effort. Forwarded to `/v1/chat/completions` as
+     * `reasoning_effort`. Use `'none'` to disable reasoning where the model
+     * allows it — with reasoning off, no thinking tokens are generated or billed.
+     *
+     * `'low'` and `'medium'` minimise or skip thinking. `'high'`, `'xhigh'` and
+     * `'max'` think, and thinking tokens are billed as output tokens AND count
+     * against `max_tokens` — so a small `max_tokens` at those levels can be spent
+     * entirely on thinking and return an empty `content` with
+     * `finish_reason: "length"`. Budget generously at `'xhigh'`/`'max'`.
+     */
+    reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+    inferenceKey?: string;
+    idempotencyKey?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+}
+export type ChatCompletionResponse = Record<string, unknown>;
+export type ChatCompletionChunk = Record<string, unknown>;
+export declare function validateChatRequest(body: Record<string, unknown>): void;
+export declare function parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+/**
+ * Inference surface. Combines control-plane management of model-serving
+ * deployments (`/api/inference*`) with OpenAI-compatible key-scoped inference
+ * (`/v1/chat/completions`). Requests are dispatched once; an idempotency header
+ * is forwarded but server-side replay is not assumed.
+ */
+export declare class Inference {
+    private readonly key;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly _http;
+    constructor(config?: {
+        inferenceKey?: string;
+        baseUrl?: string;
+        timeout?: number;
+    }, http?: HttpClient);
+    /** @internal Control-plane transport; present when constructed by the SDK client. */
+    private get http();
+    /** Side-effect-free validation with authoritative stock, prices, alternatives, and hold terms. */
+    preflight(params: InferenceCreateParams): Promise<InferencePreflightResponse>;
+    /**
+     * Create after preflight. Reuse idempotencyKey after a timeout to recover
+     * the same deployment and inference key.
+     *
+     * Pre-submit validation (book-first §2): the chosen gpuType/gpuCount are
+     * checked against the server's MODEL-ADDRESSED gpu-options (computed
+     * min_gpus/valid_counts) before any POST; a below-minimum or TP-invalid
+     * selection throws the typed {@link GpuRejectionError} with the standard
+     * body, `permanent: true` and no queue offer. The server stays the
+     * enforcement floor; an unreadable sizing endpoint never blocks the create.
+     *
+     * That advisory check is SKIPPED whenever its sizing basis cannot be
+     * trusted -- when an explicit `contextLength` cannot be proven to fit the
+     * model's native window, and equally when the value is not one this client
+     * can read as a window at all (a string from a JSON config, a fraction, a
+     * boolean). `contextLength` feeds KV sizing, so an over-native value inflates
+     * `min_gpus` and would make this client synthesize a "buy more GPUs" 409 for
+     * what is really one bad parameter. The server answers that case correctly
+     * (400 `context_length N exceeds the model's maximum of M`), so it is left to
+     * answer it.
+     *
+     * Book-before-reveal (book-first §1): a non-queued create answers 202 with
+     * a booking handle while a real GPU is secured (30-40s typical).
+     * By default this method POLLS the booking to its terminal outcome and
+     * returns the full create payload (the one-time inference_key exactly
+     * once); a definitive miss throws {@link GpuRejectionError} with
+     * FRESH alternatives + the minimum block, and NO deployment exists. Pass
+     * `{ waitForBooking: false }` to receive the raw 202 body and poll
+     * {@link getBooking} yourself. Transient 503s during the poll are retried —
+     * a market outage is never a capacity verdict.
+     */
+    create(params: InferenceCreateParams, idempotencyKey: string): Promise<InferenceCreateResponse>;
+    create(params: InferenceCreateParams, idempotencyKey: string, options: {
+        waitForBooking?: boolean;
+        bookingTimeoutMs?: number;
+    }): Promise<InferenceCreateResponse | InferenceBookingAccepted>;
+    /**
+     * Poll a pre-reveal booking handle once: `{ booking: {...} }` while pending,
+     * or the full create payload once the GPU is secured (the one-time
+     * inference_key is present exactly once). Throws
+     * {@link GpuRejectionError} on the definitive 409 stock miss and ApiError
+     * 503 on a transient market outage (retry — never a capacity verdict).
+     */
+    getBooking(handle: string): Promise<InferenceCreateResponse | InferenceBookingAccepted>;
+    /** Poll a booking handle to its terminal outcome (see {@link create}). */
+    waitForBooking(handle: string, timeoutMs?: number, pollIntervalMs?: number): Promise<InferenceCreateResponse>;
+    /**
+     * Whether the advisory capacity check may run on this context length.
+     *
+     * `contextLength` is an INPUT to KV-cache sizing. An over-native value
+     * inflates the KV estimate, raises the computed `min_gpus`, and would make
+     * {@link validateGpuSelectionBeforeSubmit} synthesize a 409 telling the
+     * caller to buy more GPUs — when the real problem is one parameter and the
+     * server's own verdict is a 400 (`context_length N exceeds the model's
+     * maximum of M`). A client must never fabricate a capacity verdict the server
+     * would not give.
+     *
+     * True only when the sizing basis is sound: no explicit `contextLength` (the
+     * server sizes from `min(nativeMax, 262144)`, which can never exceed native),
+     * or a window PROVEN to fit the registry's recorded native max. False when
+     * the registry says the context is over native, when the native max cannot be
+     * read at all, or when the value is not one this client can read as a window
+     * (see {@link contextSizingBasis}) — all of them hand the question to the
+     * server, which answers authoritatively before any wallet hold or GPU
+     * booking. The decision never depends on the runtime type the caller passed:
+     * `'999999'` from a JSON config skips the check exactly like `999999` does.
+     * @internal
+     */
+    private contextSizingIsTrustworthy;
+    /**
+     * Advisory model-addressed min/valid-count check before any POST. Throws the
+     * typed GpuRejectionError only when the selection can NEVER be booked for
+     * this model, so it always carries a permanent code and no queue offer; every
+     * failure to ANSWER (endpoint unreachable, unknown shape, an untrustworthy
+     * context length) is silent — the create gate re-validates authoritatively
+     * and unknown never fails closed. @internal
+     */
+    private validateGpuSelectionBeforeSubmit;
+    /** Fetch one bounded newest-first page. Reuse next_cursor with unchanged filters. */
+    listPage(params?: InferenceListParams): Promise<InferenceListResponse>;
+    /**
+     * Compatibility helper returning only one bounded page. Prefer listPage for
+     * pagination.
+     *
+     * These are LIST rows, not details: the model handle is `model_ref` (there is
+     * no `model` key) and the per-row serving settings are absent. Call
+     * {@link get} for the full deployment.
+     */
+    list(params?: InferenceListParams): Promise<InferenceDeploymentSummary[]>;
+    /**
+     * Lazily traverse pages without materializing an unbounded tenant list.
+     * Yields LIST rows (see {@link list}), not details.
+     */
+    iterate(params?: Omit<InferenceListParams, 'cursor'>): AsyncGenerator<InferenceDeploymentSummary, void, void>;
+    /**
+     * Current durable lifecycle, queue, price-cap, and wallet-authorization state.
+     *
+     * Unlike a {@link list} row this resolves the per-deployment serving settings
+     * — `context_length` and its `native_max_context` ceiling, `quantization`,
+     * `serving_config`, the applied-vs-requested snapshot, tool/reasoning
+     * capability, and `available_actions` — and it exposes the model handle as
+     * `hf_model_id` / `base_model_id` while `model` aliases the deployment name.
+     */
+    get(id: string): Promise<InferenceDeployment>;
+    /** Alias for get(), useful in polling automations. */
+    status(id: string): Promise<InferenceDeployment>;
+    /** Durable email delivery history, including bounded retries and dead letters. */
+    notifications(id: string, limit?: number): Promise<InferenceNotificationListResponse['notifications']>;
+    stop(id: string): Promise<InferenceLifecycleResponse>;
+    resume(id: string): Promise<InferenceLifecycleResponse>;
+    restart(id: string): Promise<InferenceLifecycleResponse>;
+    update(id: string, params: InferenceUpdateParams): Promise<InferenceUpdateResponse>;
+    delete(id: string): Promise<InferenceDeleteResponse>;
+    /**
+     * Model-fit GPU choices joined to the authoritative deployment market
+     * snapshot. MODEL-ADDRESSED (recommended, book-first §2): pass `model` (or
+     * `inferenceId`) and the SERVER resolves the facts and computes
+     * min_gpus/valid_counts/bookable_counts — the same single implementation the
+     * create gate enforces, so client facts can never understate a minimum. The
+     * client-fact params (`paramsB` & friends) are DEPRECATED, kept one release.
+     */
+    getGPUOptions(params: InferenceGPUOptionsParams): Promise<InferenceGPUOptionsResponse>;
+    private prepare;
+    private abortContext;
+    chatCompletions(params: ChatCompletionParams): Promise<ChatCompletionResponse>;
+    streamChatCompletions(params: ChatCompletionParams): AsyncGenerator<ChatCompletionChunk>;
+}
+export { buildInferenceRequest };