runbios-sdk 0.2.1-dev.62

package/dist/resources/inference.js

@@ -0,0 +1,794 @@
+import { ApiError, GpuRejectionError, gpuRejectionCodeForReason, envApiKey, envBaseUrl, envInferenceKey } from '../client.js';
+import { readNativeMaxContext } from './models.js';
+import { normalizeGPUPlacement } from './gpu-priorities.js';
+const FUNCTION_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const ROLES = new Set(['system', 'developer', 'user', 'assistant', 'tool', 'function']);
+const INFERENCE_IDEMPOTENCY_KEY = /^[A-Za-z0-9._:-]{8,128}$/;
+/**
+ * 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 const CONTEXT_DEFAULT_CEILING = 262_144;
+export const CONTEXT_EDITABLE_FLOOR = 32_768;
+export function contextSizingBasis(requested) {
+    if (requested === undefined || requested === null)
+        return ['server_default', 0];
+    if (typeof requested !== 'number' || !Number.isInteger(requested))
+        return ['unprovable', 0];
+    if (requested <= 0)
+        return ['server_default', 0];
+    return ['explicit', requested];
+}
+const INFERENCE_TOOL_CALL_PARSERS = new Set([
+    'deepseekv3', 'deepseekv31', 'deepseekv32',
+    'glm', 'glm45', 'glm47', 'gpt-oss', 'kimi_k2',
+    'lfm2', 'llama3', 'mimo', 'mistral',
+    'omega17', 'omega17_exp', 'omega17_vl_exp', 'pythonic',
+    'qwen', 'qwen25', 'qwen3_coder', 'step3', 'step3p5',
+    'minimax-m2', 'trinity', 'interns1', 'hermes', 'gigachat3',
+    'usf_omega', 'usf_milli', 'usf_mini',
+]);
+function inferenceIdempotencyKey(value) {
+    const key = value?.trim();
+    if (!INFERENCE_IDEMPOTENCY_KEY.test(key)) {
+        throw new Error("RunBiOS: idempotencyKey is required and must be 8-128 characters using letters, numbers, '.', '_', ':', or '-'");
+    }
+    return key;
+}
+function buildInferenceRequest(params) {
+    const queueEnabled = params.allowCapacityQueue ?? false;
+    const placement = normalizeGPUPlacement(params.gpuPriorities, queueEnabled, params.gpuType, params.gpuCount, 'allowCapacityQueue', 
+    // Backup rungs are decoupled from queue consent (book-first §4): a
+    // non-queued deployment may rank 1-5 placements. Only the selected rung
+    // is booked up front; the extras become the after-start replacement
+    // ladder if a GPU is ever lost.
+    true);
+    if (!params.name?.trim())
+        throw new Error('RunBiOS: deployment name is required');
+    if (!placement.gpuType)
+        throw new Error('RunBiOS: gpuType is required');
+    if (!Number.isInteger(placement.gpuCount) || placement.gpuCount < 1 || placement.gpuCount > 8) {
+        throw new Error('RunBiOS: gpuCount must be an integer between 1 and 8');
+    }
+    if (params.sourceType === 'checkpoint') {
+        if (!params.sourceJobId || !params.sourceCheckpointId) {
+            throw new Error('RunBiOS: checkpoint deployments require sourceJobId and sourceCheckpointId');
+        }
+    }
+    else if (params.sourceType === 'hf_model') {
+        if (!params.hfModelId)
+            throw new Error('RunBiOS: hf_model deployments require hfModelId');
+        if (params.servingMode !== undefined && params.servingMode !== 'full') {
+            throw new Error('RunBiOS: hf_model deployments use servingMode=full; checkpoint modes are derived from the verified artifact');
+        }
+    }
+    else {
+        throw new Error('RunBiOS: sourceType must be checkpoint or hf_model');
+    }
+    if (params.servingMode !== undefined && !['full', 'adapter', 'merged'].includes(params.servingMode)) {
+        throw new Error('RunBiOS: servingMode must be full, adapter, or merged');
+    }
+    // modelTask is NOT validated here. It is server-DERIVED from the resolved
+    // model (deriveModelTask), and whether a given value is accepted depends on
+    // that derivation — which only the server can do. Live dev proves both
+    // directions: 'completions'/'Completion' are ACCEPTED for a base model
+    // (openai-community/gpt2 preflights 200) while 'completion' is REJECTED for a
+    // chat model, so any client vocabulary is simultaneously too narrow and too
+    // wide. The value rides through untouched and the server answers; read the
+    // derived task back from preflight's canonical_request.model_task.
+    if (params.gpuTier !== undefined && params.gpuTier !== 'secure') {
+        throw new Error('RunBiOS: gpuTier must be secure; other deployment capacity tiers are not supported');
+    }
+    const requestedParser = params.servingConfig?.tool_call_parser;
+    if (requestedParser !== undefined && !INFERENCE_TOOL_CALL_PARSERS.has(requestedParser)) {
+        throw new Error('RunBiOS: servingConfig.tool_call_parser must name a parser the Run BiOS serving runtime supports');
+    }
+    const body = {
+        name: params.name.trim(),
+        source_type: params.sourceType,
+        gpu_type: placement.gpuType,
+        gpu_count: placement.gpuCount,
+        gpu_tier: params.gpuTier || 'secure',
+        allow_capacity_queue: queueEnabled,
+    };
+    if (placement.priorities !== undefined)
+        body.gpu_priorities = placement.priorities;
+    if (params.sourceJobId !== undefined)
+        body.source_job_id = params.sourceJobId;
+    if (params.sourceCheckpointId !== undefined)
+        body.source_checkpoint_id = params.sourceCheckpointId;
+    if (params.hfModelId !== undefined)
+        body.hf_model_id = params.hfModelId;
+    if (params.hfModelRevision !== undefined)
+        body.hf_model_revision = params.hfModelRevision;
+    if (params.hfIntegrationId !== undefined)
+        body.hf_integration_id = params.hfIntegrationId;
+    if (params.baseModelId !== undefined)
+        body.base_model_id = params.baseModelId;
+    if (params.baseModelRevision !== undefined)
+        body.base_model_revision = params.baseModelRevision;
+    if (params.servingMode !== undefined)
+        body.serving_mode = params.servingMode;
+    if (params.modelTask !== undefined)
+        body.model_task = params.modelTask;
+    // supportsImages is deliberately NOT forwarded: image-input support is
+    // derived server-side from the resolved model's own config and the wire field
+    // is IGNORED, so sending a client value would only advertise control the
+    // caller does not have. See InferenceCreateParams.
+    if (params.storageGb !== undefined)
+        body.storage_gb = params.storageGb;
+    if (params.contextLength !== undefined)
+        body.context_length = params.contextLength;
+    if (params.quant !== undefined)
+        body.quant = params.quant;
+    if (params.servingConfig !== undefined)
+        body.serving_config = params.servingConfig;
+    if (params.maxPriceHourCents !== undefined)
+        body.max_price_hour_cents = params.maxPriceHourCents;
+    return body;
+}
+export function validateChatRequest(body) {
+    const messages = body.messages;
+    if (!Array.isArray(messages) || messages.length === 0) {
+        throw new Error('messages must be a non-empty array');
+    }
+    const tools = body.tools ?? [];
+    if (!Array.isArray(tools))
+        throw new Error('tools must be an array');
+    const names = [];
+    for (const rawTool of tools) {
+        if (!rawTool || typeof rawTool !== 'object')
+            throw new Error('each tool must be an object');
+        const tool = rawTool;
+        if ((tool.type ?? 'function') !== 'function')
+            throw new Error('each tool must have type="function"');
+        const fn = tool.function;
+        if (!fn || typeof fn !== 'object')
+            throw new Error('each tool requires a function object');
+        const definition = fn;
+        if (typeof definition.name !== 'string' || !FUNCTION_NAME.test(definition.name)) {
+            throw new Error('tool function names must be 1-64 safe characters');
+        }
+        const parameters = definition.parameters;
+        if (parameters !== undefined && (!parameters || typeof parameters !== 'object' || Array.isArray(parameters)
+            || (parameters.type ?? 'object') !== 'object')) {
+            throw new Error('tool parameters must be a JSON Schema object');
+        }
+        names.push(definition.name);
+    }
+    if (new Set(names).size !== names.length)
+        throw new Error('tool function names must be unique');
+    const choice = body.tool_choice;
+    if (choice && typeof choice === 'object') {
+        const fn = choice.function;
+        const selected = fn && typeof fn === 'object' ? fn.name : undefined;
+        if (typeof selected !== 'string' || !names.includes(selected)) {
+            throw new Error('tool_choice references an undefined function');
+        }
+    }
+    else if ((choice === 'auto' || choice === 'required') && tools.length === 0) {
+        throw new Error('tool_choice requires at least one tool');
+    }
+    const pending = new Set();
+    for (const rawMessage of messages) {
+        if (!rawMessage || typeof rawMessage !== 'object')
+            throw new Error('every message must be an object');
+        const message = rawMessage;
+        const role = message.role;
+        if (typeof role !== 'string' || !ROLES.has(role))
+            throw new Error('every message requires a valid role');
+        const calls = message.tool_calls;
+        if (calls !== undefined && role !== 'assistant')
+            throw new Error('tool_calls are only valid on assistant messages');
+        if (role === 'assistant' && Array.isArray(calls) && calls.length > 0) {
+            if (pending.size > 0)
+                throw new Error('tool calls must be resolved before the next turn');
+            for (const rawCall of calls) {
+                if (!rawCall || typeof rawCall !== 'object')
+                    throw new Error('assistant tool calls must be objects');
+                const call = rawCall;
+                const id = call.id;
+                const fn = call.function;
+                if (typeof id !== 'string' || !id)
+                    throw new Error('assistant tool calls require a non-empty id');
+                if (pending.has(id))
+                    throw new Error('assistant tool call ids must be unique');
+                if (!fn || typeof fn !== 'object')
+                    throw new Error('assistant tool calls require a function');
+                const functionCall = fn;
+                if (tools.length > 0 && !names.includes(String(functionCall.name ?? ''))) {
+                    throw new Error('assistant tool call references an undefined function');
+                }
+                let args = functionCall.arguments;
+                if (typeof args === 'string') {
+                    try {
+                        args = JSON.parse(args);
+                    }
+                    catch {
+                        throw new Error('tool call arguments must be valid JSON');
+                    }
+                }
+                if (!args || typeof args !== 'object' || Array.isArray(args)) {
+                    throw new Error('tool call arguments must encode a JSON object');
+                }
+                pending.add(id);
+            }
+        }
+        else if (role === 'tool') {
+            const id = message.tool_call_id;
+            if (typeof id !== 'string' || !pending.delete(id)) {
+                throw new Error('tool message references an unknown tool_call_id');
+            }
+        }
+        else if (pending.size > 0) {
+            throw new Error('tool calls must be resolved before the next turn');
+        }
+    }
+    if (pending.size > 0)
+        throw new Error('assistant tool calls are missing tool response messages');
+}
+function extractFrames(buffer, final = false) {
+    const frames = [];
+    let rest = buffer;
+    while (true) {
+        const match = /\r\n\r\n|\n\n|\r\r/.exec(rest);
+        if (!match || match.index === undefined)
+            break;
+        frames.push(rest.slice(0, match.index));
+        rest = rest.slice(match.index + match[0].length);
+    }
+    if (final && rest) {
+        frames.push(rest);
+        rest = '';
+    }
+    return { frames, rest };
+}
+function dataFromFrame(frame) {
+    const data = [];
+    for (const line of frame.replaceAll('\r\n', '\n').replaceAll('\r', '\n').split('\n')) {
+        if (!line || line.startsWith(':'))
+            continue;
+        const colon = line.indexOf(':');
+        const field = colon < 0 ? line : line.slice(0, colon);
+        let value = colon < 0 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        if (field === 'data')
+            data.push(value);
+    }
+    return data.length > 0 ? data.join('\n') : undefined;
+}
+export async function* parseSSE(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const extracted = extractFrames(buffer);
+            buffer = extracted.rest;
+            for (const frame of extracted.frames) {
+                const data = dataFromFrame(frame);
+                if (data !== undefined)
+                    yield data;
+            }
+        }
+        buffer += decoder.decode();
+        const extracted = extractFrames(buffer, true);
+        for (const frame of extracted.frames) {
+            const data = dataFromFrame(frame);
+            if (data !== undefined)
+                yield data;
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+async function apiError(response) {
+    const text = await response.text().catch(() => '');
+    let body = { error: text || `Inference API error ${response.status}` };
+    try {
+        body = JSON.parse(text);
+    }
+    catch { /* use text envelope */ }
+    return new ApiError(response.status, body);
+}
+/**
+ * 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 class Inference {
+    key;
+    baseUrl;
+    timeout;
+    _http;
+    constructor(config = {}, http) {
+        // Explicit key, then RUNBIOS_INFERENCE_KEY (legacy BIOS_INFERENCE_KEY),
+        // then RUNBIOS_API_KEY (legacy BIOS_API_KEY): a platform key
+        // carrying the serverless scope calls /v1 directly, so the same key must
+        // never have to be supplied twice. The SDK client resolves its own apiKey
+        // ahead of this (see RunBiOS's constructor).
+        this.key = config.inferenceKey || envInferenceKey() || envApiKey();
+        // Same default host as HttpClient (api.runbios.ai); api.runbios.ai cutover
+        // is planned once its DNS exists — update both call sites together.
+        this.baseUrl = (config.baseUrl || envBaseUrl() || 'https://api-dev.runbios.ai').replace(/\/+$/, '');
+        this.timeout = config.timeout ?? 900_000;
+        this._http = http;
+    }
+    /** @internal Control-plane transport; present when constructed by the SDK client. */
+    get http() {
+        if (!this._http) {
+            throw new Error('RunBiOS: control-plane inference management requires an SDK client (apiKey or accessToken)');
+        }
+        return this._http;
+    }
+    // --------------------------------------------------------------------------
+    // Control-plane deployment management — `/api/inference*`
+    // --------------------------------------------------------------------------
+    /** Side-effect-free validation with authoritative stock, prices, alternatives, and hold terms. */
+    preflight(params) {
+        return this.http.fetchPost('/api/inference/preflight', buildInferenceRequest(params));
+    }
+    async create(params, idempotencyKey, options) {
+        const body = buildInferenceRequest(params);
+        // Validate the RESOLVED placement (gpu_type/gpu_count may come from the
+        // first ranked priority rather than the top-level fields).
+        await this.validateGpuSelectionBeforeSubmit(params, String(body.gpu_type ?? ''), Number(body.gpu_count ?? NaN));
+        const response = await this.http.fetchPost('/api/inference', body, { 'Idempotency-Key': inferenceIdempotencyKey(idempotencyKey) });
+        const handle = response?.booking?.handle;
+        if (handle && (options?.waitForBooking ?? true)) {
+            return this.waitForBooking(handle, options?.bookingTimeoutMs ?? 300_000);
+        }
+        return response;
+    }
+    /**
+     * 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) {
+        return this.http.fetchGet(`/api/inference/bookings/${encodeURIComponent(handle)}`);
+    }
+    /** Poll a booking handle to its terminal outcome (see {@link create}). */
+    async waitForBooking(handle, timeoutMs = 300_000, pollIntervalMs = 2_000) {
+        const deadline = Date.now() + Math.max(timeoutMs, pollIntervalMs);
+        for (;;) {
+            if (Date.now() > deadline) {
+                throw new ApiError(408, {
+                    error: {
+                        code: 'BOOKING_POLL_TIMEOUT',
+                        message: `RunBiOS: the GPU booking did not conclude within ${Math.round(timeoutMs / 1000)}s. `
+                            + `Nothing was charged and no deployment exists until a GPU is confirmed; `
+                            + `poll getBooking('${handle}') to continue waiting.`,
+                    },
+                });
+            }
+            await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
+            let outcome;
+            try {
+                outcome = await this.getBooking(handle);
+            }
+            catch (err) {
+                if (err instanceof ApiError && err.status === 503)
+                    continue; // transient — never fail-closed
+                throw err;
+            }
+            if (outcome?.booking?.status === 'booking')
+                continue;
+            return outcome;
+        }
+    }
+    /**
+     * 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
+     */
+    async contextSizingIsTrustworthy(params) {
+        const [basis, requested] = contextSizingBasis(params.contextLength);
+        if (basis === 'server_default')
+            return true;
+        if (basis === 'unprovable')
+            return false;
+        const model = params.hfModelId || params.baseModelId;
+        // No control-plane transport: leave the pre-existing failure point where it
+        // was (the POST) rather than throwing a step earlier from an advisory check.
+        if (!model || !this._http)
+            return false;
+        const native = await readNativeMaxContext(this._http, model);
+        if (native === undefined)
+            return false; // unknown basis — the server decides
+        return requested <= native;
+    }
+    /**
+     * 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
+     */
+    async validateGpuSelectionBeforeSubmit(params, gpuType, gpuCount) {
+        const model = params.hfModelId || params.baseModelId;
+        if (!model || !gpuType || !Number.isInteger(gpuCount))
+            return;
+        if (!(await this.contextSizingIsTrustworthy(params)))
+            return;
+        let options;
+        try {
+            options = await this.getGPUOptions({
+                model,
+                revision: params.hfModelRevision || params.baseModelRevision,
+                quant: params.quant,
+                contextLength: params.contextLength,
+                hfIntegrationId: params.hfIntegrationId,
+            });
+        }
+        catch {
+            return; // advisory only — the create gate is the enforcement floor
+        }
+        const chosen = options?.options?.find(option => option.gpu_type === gpuType);
+        if (!chosen)
+            return;
+        const minGpus = chosen.min_gpus || 0;
+        const validCounts = (chosen.valid_counts || []).filter(count => Number.isInteger(count));
+        let reason;
+        let message = '';
+        if (chosen.selectable === false) {
+            reason = chosen.reason_code === 'gpu_unsupported' ? 'gpu_unsupported' : 'model_too_large';
+            message = reason === 'gpu_unsupported'
+                ? `RunBiOS: ${gpuType} cannot run this model, whatever GPU count you pick. Choose one of the GPUs listed in available_gpus.`
+                : `RunBiOS: this model does not fit on ${gpuType}, at any GPU count. Pick one of the GPUs listed in available_gpus, which all have room for it.`;
+        }
+        else if (minGpus > 0 && gpuCount < minGpus) {
+            reason = 'below_model_minimum';
+            message = `RunBiOS: this model needs at least ${minGpus} ${gpuType}${minGpus === 1 ? '' : ' GPUs'} to run, and this request asked for ${gpuCount}. Raise the GPU count, or pick one of the GPUs listed in available_gpus.`;
+        }
+        else if (validCounts.length > 0 && !validCounts.includes(gpuCount)) {
+            reason = 'invalid_gpu_count';
+            message = `RunBiOS: this model cannot be split across ${gpuCount} ${gpuType}${gpuCount === 1 ? '' : ' GPUs'}. Use one of these GPU counts instead: ${validCounts.join(', ')}.`;
+        }
+        if (!reason)
+            return;
+        const selectableOptions = (options.options || []).filter((option) => !!option && option.selectable !== false);
+        const alternatives = selectableOptions
+            .filter(option => option.market?.availability_status === 'available')
+            .map(option => ({
+            gpu_type: option.gpu_type,
+            gpu_count: option.min_gpus,
+            min_gpus: option.min_gpus,
+            valid_counts: option.valid_counts,
+            tier: 'secure',
+            available_count: option.market?.available_count ?? undefined,
+            price_hour_cents: (option.market?.price_per_gpu_hour_cents || 0) * (option.min_gpus || 1),
+        }));
+        // Every reason this guard can raise is a PERMANENT property of the request,
+        // so it must speak the same 400 + own-code + no-queue contract the service
+        // does. Claiming CAPACITY_UNAVAILABLE here would tell the caller to wait for
+        // stock that would never make the request bookable.
+        throw new GpuRejectionError(400, {
+            error: {
+                code: gpuRejectionCodeForReason(reason),
+                message,
+            },
+            reason,
+            checked_at: options.availability_checked_at,
+            queue_offered: false,
+            queue_eligible: false,
+            selected: {
+                gpu_type: gpuType,
+                gpu_count: gpuCount,
+                tier: params.gpuTier || 'secure',
+                availability_status: 'unknown',
+            },
+            minimum_requirement: {
+                selected_gpu_min: minGpus,
+                selected_valid_counts: validCounts,
+                per_type: selectableOptions
+                    .filter(option => (option.min_gpus || 0) >= 1)
+                    .map(option => ({
+                    gpu_type: option.gpu_type,
+                    min_gpus: option.min_gpus,
+                    valid_counts: option.valid_counts || [],
+                })),
+            },
+            available_gpus: alternatives,
+            available_alternatives: alternatives,
+        });
+    }
+    /** Fetch one bounded newest-first page. Reuse next_cursor with unchanged filters. */
+    async listPage(params = {}) {
+        const query = new URLSearchParams();
+        if (params.limit !== undefined) {
+            if (!Number.isInteger(params.limit) || params.limit < 1) {
+                throw new Error('RunBiOS: deployment list limit must be a positive integer');
+            }
+            query.set('limit', String(Math.min(params.limit, 200)));
+        }
+        if (params.cursor)
+            query.set('cursor', params.cursor);
+        if (params.status && params.status !== 'all')
+            query.set('status', params.status);
+        if (params.search?.trim())
+            query.set('search', params.search.trim());
+        const suffix = query.toString();
+        const response = await this.http.fetchGet(`/api/inference${suffix ? `?${suffix}` : ''}`);
+        // Compatibility with pre-pagination servers during a rolling release.
+        if (Array.isArray(response)) {
+            return { deployments: response, has_more: false, next_cursor: null, limit: response.length };
+        }
+        return {
+            deployments: response.deployments || [],
+            has_more: response.has_more === true,
+            next_cursor: response.next_cursor ?? null,
+            limit: response.limit || params.limit || 50,
+        };
+    }
+    /**
+     * 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.
+     */
+    async list(params = {}) {
+        return (await this.listPage(params)).deployments;
+    }
+    /**
+     * Lazily traverse pages without materializing an unbounded tenant list.
+     * Yields LIST rows (see {@link list}), not details.
+     */
+    async *iterate(params = {}) {
+        let cursor;
+        do {
+            const page = await this.listPage({ ...params, cursor });
+            for (const deployment of page.deployments)
+                yield deployment;
+            cursor = page.has_more && page.next_cursor ? page.next_cursor : undefined;
+        } while (cursor);
+    }
+    /**
+     * 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) {
+        return this.http.fetchGet(`/api/inference/${encodeURIComponent(id)}`);
+    }
+    /** Alias for get(), useful in polling automations. */
+    status(id) {
+        return this.get(id);
+    }
+    /** Durable email delivery history, including bounded retries and dead letters. */
+    async notifications(id, limit = 50) {
+        const safeLimit = Math.max(1, Math.min(100, Math.trunc(limit)));
+        const response = await this.http.fetchGet(`/api/inference/${encodeURIComponent(id)}/notifications?limit=${safeLimit}`);
+        return response.notifications || [];
+    }
+    stop(id) {
+        return this.http.fetchPost(`/api/inference/${encodeURIComponent(id)}/stop`);
+    }
+    resume(id) {
+        return this.http.fetchPost(`/api/inference/${encodeURIComponent(id)}/resume`);
+    }
+    restart(id) {
+        return this.http.fetchPost(`/api/inference/${encodeURIComponent(id)}/restart`);
+    }
+    update(id, params) {
+        const body = {};
+        if (params.allowCapacityQueue !== undefined)
+            body.allow_capacity_queue = params.allowCapacityQueue;
+        if (params.maxPriceHourCents !== undefined)
+            body.max_price_hour_cents = params.maxPriceHourCents;
+        if (params.contextLength !== undefined)
+            body.context_length = params.contextLength;
+        if (params.quant !== undefined)
+            body.quant = params.quant;
+        if (params.servingConfig !== undefined)
+            body.serving_config = params.servingConfig;
+        return this.http.fetchPatch(`/api/inference/${encodeURIComponent(id)}`, body);
+    }
+    delete(id) {
+        return this.http.fetchDelete(`/api/inference/${encodeURIComponent(id)}`);
+    }
+    /**
+     * 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) {
+        if (params.gpuTier !== undefined && params.gpuTier !== 'secure') {
+            throw new Error('RunBiOS: gpuTier must be secure; other deployment capacity tiers are not supported');
+        }
+        if (params.model === undefined && params.inferenceId === undefined && params.paramsB === undefined) {
+            throw new Error('RunBiOS: pass model (or inferenceId) for server-resolved sizing, or the deprecated paramsB client facts');
+        }
+        const query = new URLSearchParams();
+        if (params.model !== undefined)
+            query.set('model', params.model);
+        if (params.revision !== undefined)
+            query.set('revision', params.revision);
+        if (params.inferenceId !== undefined)
+            query.set('inference_id', params.inferenceId);
+        if (params.hfIntegrationId !== undefined)
+            query.set('hf_integration_id', params.hfIntegrationId);
+        if (params.paramsB !== undefined)
+            query.set('params_b', String(params.paramsB));
+        if (params.activeParamsB !== undefined)
+            query.set('active_params_b', String(params.activeParamsB));
+        if (params.isMoe !== undefined)
+            query.set('is_moe', String(params.isMoe));
+        if (params.quant !== undefined)
+            query.set('quant', params.quant);
+        if (params.contextLength !== undefined)
+            query.set('context_length', String(params.contextLength));
+        if (params.kvHeads !== undefined)
+            query.set('kv_heads', String(params.kvHeads));
+        if (params.numLayers !== undefined)
+            query.set('num_layers', String(params.numLayers));
+        if (params.kvLayers !== undefined)
+            query.set('kv_layers', String(params.kvLayers));
+        if (params.headDim !== undefined)
+            query.set('head_dim', String(params.headDim));
+        if (params.attention !== undefined)
+            query.set('attn', params.attention);
+        if (params.numAttentionHeads !== undefined)
+            query.set('num_attention_heads', String(params.numAttentionHeads));
+        if (params.kvLoraRank !== undefined)
+            query.set('kv_lora_rank', String(params.kvLoraRank));
+        if (params.qkRopeHeadDim !== undefined)
+            query.set('qk_rope_head_dim', String(params.qkRopeHeadDim));
+        if (params.gpuTier !== undefined)
+            query.set('gpu_tier', params.gpuTier);
+        return this.http.fetchGet(`/api/inference/gpu-options?${query}`);
+    }
+    // --------------------------------------------------------------------------
+    // OpenAI-compatible key-scoped inference — `/v1/chat/completions`
+    // --------------------------------------------------------------------------
+    prepare(params, stream) {
+        const { messages, model, tools, toolChoice, reasoningEffort, inferenceKey, idempotencyKey, requestId, signal, ...extra } = params;
+        const key = inferenceKey || this.key;
+        if (!key)
+            throw new Error('an inferenceKey is required');
+        const body = { ...extra, messages, stream };
+        if (model)
+            body.model = model;
+        if (tools !== undefined)
+            body.tools = tools;
+        if (toolChoice !== undefined)
+            body.tool_choice = toolChoice;
+        if (reasoningEffort !== undefined)
+            body.reasoning_effort = reasoningEffort;
+        validateChatRequest(body);
+        const headers = {
+            Authorization: `Bearer ${key}`,
+            Accept: stream ? 'text/event-stream' : 'application/json',
+            'Content-Type': 'application/json',
+            'X-Request-ID': requestId || crypto.randomUUID(),
+        };
+        if (idempotencyKey)
+            headers['Idempotency-Key'] = idempotencyKey;
+        return { body, key, headers, signal };
+    }
+    abortContext(signal) {
+        const controller = new AbortController();
+        const relay = () => controller.abort(signal?.reason);
+        if (signal?.aborted)
+            relay();
+        else
+            signal?.addEventListener('abort', relay, { once: true });
+        const timeoutId = setTimeout(() => controller.abort(new Error(`Inference timed out after ${this.timeout}ms`)), this.timeout);
+        return {
+            controller,
+            timeoutId,
+            remove: () => signal?.removeEventListener('abort', relay),
+        };
+    }
+    async chatCompletions(params) {
+        const prepared = this.prepare(params, false);
+        const abort = this.abortContext(prepared.signal);
+        try {
+            const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+                method: 'POST', headers: prepared.headers, body: JSON.stringify(prepared.body), signal: abort.controller.signal,
+            });
+            if (!response.ok)
+                throw await apiError(response);
+            return await response.json();
+        }
+        catch (error) {
+            if (abort.controller.signal.aborted && !(error instanceof ApiError)) {
+                throw new ApiError(0, { error: String(abort.controller.signal.reason || 'Inference request aborted') });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(abort.timeoutId);
+            abort.remove();
+        }
+    }
+    async *streamChatCompletions(params) {
+        const prepared = this.prepare(params, true);
+        const abort = this.abortContext(prepared.signal);
+        try {
+            const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+                method: 'POST', headers: prepared.headers, body: JSON.stringify(prepared.body), signal: abort.controller.signal,
+            });
+            if (!response.ok)
+                throw await apiError(response);
+            const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+            if (!contentType.includes('text/event-stream')) {
+                throw new ApiError(response.status, { error: `Expected text/event-stream, received ${contentType || 'no content type'}` });
+            }
+            if (!response.body)
+                throw new ApiError(0, { error: 'Inference response has no body' });
+            for await (const data of parseSSE(response.body)) {
+                if (data === '[DONE]')
+                    return;
+                let event;
+                try {
+                    event = JSON.parse(data);
+                }
+                catch {
+                    throw new ApiError(0, { error: 'Invalid JSON SSE event' });
+                }
+                if (event && typeof event === 'object' && 'error' in event) {
+                    throw new ApiError(0, event);
+                }
+                yield event;
+            }
+        }
+        catch (error) {
+            if (abort.controller.signal.aborted && !(error instanceof ApiError)) {
+                throw new ApiError(0, { error: String(abort.controller.signal.reason || 'Inference request aborted') });
+            }
+            throw error;
+        }
+        finally {
+            abort.controller.abort('stream closed');
+            clearTimeout(abort.timeoutId);
+            abort.remove();
+        }
+    }
+}
+export { buildInferenceRequest };