@octomil/browser 1.0.0 → 1.1.0

package/dist/octomil.js

@@ -1,55 +1,106 @@
 /**
  * @octomil/browser — Main SDK entry point
  *
- * The `Octomil` class is the primary public interface.  It orchestrates
+ * The `OctomilClient` class is the primary public interface.  It orchestrates
  * model loading, caching, inference, and optional telemetry.
  *
  * @example
  * ```ts
- * import { Octomil } from '@octomil/browser';
+ * import { OctomilClient } from '@octomil/browser';
  *
- * const ml = new Octomil({
- *   model: 'https://models.octomil.io/sentiment-v1.onnx',
+ * const ml = new OctomilClient({
+ *   model: 'https://models.octomil.com/sentiment-v1.onnx',
  *   backend: 'webgpu',
  * });
  *
  * await ml.load();
  * const result = await ml.predict({ raw: inputData, dims: [1, 3, 224, 224] });
  * console.log(result.label, result.score);
- * ml.dispose();
+ * ml.close();
  * ```
  */
+import { OctomilAudio } from "./audio/octomil-audio.js";
+import { CapabilitiesClient } from "./capabilities.js";
 import { createModelCache } from "./cache.js";
-import { InferenceEngine } from "./inference.js";
-import { ModelLoader } from "./model-loader.js";
+import { ChatClient } from "./chat.js";
+import { getDeviceContext } from "./configure.js";
+import { ControlClient } from "./control.js";
+import { embed as embedFn } from "./embeddings.js";
+import { InferenceEngine } from "./runtime/engines/onnx-web/engine.js";
+import { ModelManager } from "./model-manager.js";
+import { ModelsClient } from "./models.js";
+import { ResponsesClient } from "./responses.js";
+import { RoutingClient, detectDeviceCapabilities } from "./routing.js";
 import { TelemetryReporter } from "./telemetry.js";
-import { StreamingInferenceEngine } from "./streaming.js";
+import { OctomilText } from "./text/octomil-text.js";
 import { OctomilError } from "./types.js";
 // ---------------------------------------------------------------------------
-// Octomil
+// OctomilClient
 // ---------------------------------------------------------------------------
-export class Octomil {
+export class OctomilClient {
     options;
     cache;
     loader;
     engine;
+    inferenceEngine;
+    routingClient = null;
+    deviceContext;
     telemetry = null;
+    deviceCaps = null;
+    _responses = null;
+    _chat = null;
+    _control = null;
+    _capabilities = null;
+    _models = null;
+    _audio = null;
+    _text = null;
     loaded = false;
-    disposed = false;
+    closed = false;
+    _warmedUp = false;
     constructor(options) {
+        // Extract serverUrl and apiKey from the auth config
+        const auth = options.auth;
+        const serverUrl = auth?.serverUrl;
+        const apiKey = auth?.type === "org_api_key"
+            ? auth.apiKey
+            : auth?.type === "device_token"
+                ? auth.bootstrapToken
+                : undefined;
+        const orgId = auth?.type === "org_api_key" ? auth.orgId : getDeviceContext()?.orgId ?? undefined;
+        this.deviceContext = getDeviceContext();
         this.options = {
             telemetry: false,
             cacheStrategy: "cache-api",
             ...options,
+            // Map auth fields into legacy locations for internal consumers
+            serverUrl,
+            apiKey,
         };
         this.cache = createModelCache(this.options.cacheStrategy);
-        this.loader = new ModelLoader(this.options, this.cache);
-        this.engine = new InferenceEngine();
+        this.loader = new ModelManager(this.options, this.cache);
+        const defaultEngine = options.runtime ? null : new InferenceEngine();
+        this.engine = options.runtime ?? defaultEngine;
+        this.inferenceEngine = defaultEngine;
+        // Routing is opt-in: only enabled when serverUrl + apiKey + routing are set.
+        if (serverUrl && apiKey && this.options.routing) {
+            this.routingClient = new RoutingClient({
+                serverUrl,
+                apiKey,
+                cacheTtlMs: this.options.routing.cacheTtlMs,
+                prefer: this.options.routing.prefer,
+            });
+        }
         if (this.options.telemetry) {
             this.telemetry = new TelemetryReporter({
                 url: this.options.telemetryUrl,
-                apiKey: this.options.apiKey,
+                apiKey,
+                authHeadersProvider: () => this.deviceContext?.authHeaders() ?? null,
+                orgId,
+                deviceId: this.deviceContext?.installationId,
             });
+            if (this.deviceContext) {
+                this.telemetry.updateResource(this.deviceContext.telemetryResource());
+            }
         }
     }
     // -----------------------------------------------------------------------
@@ -60,38 +111,56 @@ export class Octomil {
      * inference session.  Must be called before `predict()` or `chat()`.
      */
     async load() {
-        this.ensureNotDisposed();
+        this.ensureNotClosed();
         const start = performance.now();
-        const wasCached = await this.loader.isCached();
         const modelData = await this.loader.load();
         await this.engine.createSession(modelData, this.options.backend);
         this.loaded = true;
         const durationMs = performance.now() - start;
-        this.trackEvent({
-            type: "model_load",
-            model: this.options.model,
-            durationMs,
-            metadata: {
-                backend: this.engine.activeBackend,
-                cached: wasCached,
-                sizeBytes: modelData.byteLength,
-            },
-            timestamp: Date.now(),
-        });
-        if (wasCached) {
-            this.trackEvent({
-                type: "cache_hit",
-                model: this.options.model,
-                timestamp: Date.now(),
-            });
-        }
-        else {
-            this.trackEvent({
-                type: "cache_miss",
-                model: this.options.model,
-                timestamp: Date.now(),
-            });
+        this.telemetry?.reportDeployStarted(this.options.model, "latest");
+        this.telemetry?.reportDeployCompleted(this.options.model, "latest", durationMs);
+    }
+    /**
+     * Explicitly warm up the ONNX runtime by running a minimal dummy inference.
+     *
+     * This pre-allocates internal buffers, compiles GPU shaders, and triggers
+     * any lazy initialisation that would otherwise happen on the first real
+     * `predict()` call.  Useful for latency-sensitive applications that want
+     * predictable first-inference timing.
+     *
+     * Idempotent: calling `warmup()` after it has already completed is a no-op.
+     * Requires `load()` to have been called first.
+     */
+    async warmup() {
+        this.ensureReady();
+        if (this._warmedUp)
+            return;
+        // Build a minimal input tensor (1-element Float32) for the first input.
+        // The goal is to trigger ONNX runtime buffer allocation, not produce
+        // meaningful output.
+        const inputName = this.inferenceEngine
+            ? this.inferenceEngine.inputNames[0]
+            : undefined;
+        if (inputName) {
+            const dummyTensors = {
+                [inputName]: {
+                    data: new Float32Array([0]),
+                    dims: [1, 1],
+                },
+            };
+            try {
+                await this.engine.run(dummyTensors);
+            }
+            catch {
+                // Warmup failures are non-fatal. The runtime may reject the dummy
+                // shape, but the internal buffers will still have been allocated.
+            }
         }
+        this._warmedUp = true;
+    }
+    /** Whether `warmup()` has been called and completed successfully. */
+    get isWarmedUp() {
+        return this._warmedUp;
     }
     // -----------------------------------------------------------------------
     // Inference
@@ -104,14 +173,19 @@ export class Octomil {
      */
     async predict(input) {
         this.ensureReady();
+        // Attempt cloud routing if configured.
+        if (this.routingClient) {
+            const cloudResult = await this.tryCloudInference(input);
+            if (cloudResult)
+                return cloudResult;
+        }
+        // Local inference (default path).
         const tensors = this.prepareTensors(input);
+        this.telemetry?.reportInferenceStarted(this.options.model, { target: "device" });
         const result = await this.engine.run(tensors);
-        this.trackEvent({
-            type: "inference",
-            model: this.options.model,
-            durationMs: result.latencyMs,
-            metadata: { backend: this.engine.activeBackend },
-            timestamp: Date.now(),
+        this.telemetry?.reportInferenceCompleted(this.options.model, result.latencyMs, {
+            backend: this.inferenceEngine?.activeBackend ?? "unknown",
+            target: "device",
         });
         return result;
     }
@@ -130,95 +204,158 @@ export class Octomil {
             results.push(result);
         }
         const totalMs = performance.now() - start;
-        this.trackEvent({
-            type: "inference",
-            model: this.options.model,
-            durationMs: totalMs,
-            metadata: {
-                backend: this.engine.activeBackend,
-                batchSize: inputs.length,
-            },
-            timestamp: Date.now(),
+        this.telemetry?.reportInferenceCompleted(this.options.model, totalMs, {
+            backend: this.inferenceEngine?.activeBackend ?? "unknown",
+            batchSize: inputs.length,
         });
         return results;
     }
     /**
      * OpenAI-compatible chat completion.
-     * Requires a server with streaming endpoint. Uses StreamingInferenceEngine
-     * under the hood to collect the full response.
+     *
+     * @deprecated Use `client.chat.create()` instead. This method will be
+     * removed in the next major version.
      */
-    async chat(messages, options = {}) {
-        this.ensureReady();
-        if (!this.options.serverUrl) {
-            throw new OctomilError("INFERENCE_FAILED", "chat() requires serverUrl to be configured.");
+    async createChat(messages, options = {}) {
+        return this.chat.create(messages, options);
+    }
+    /**
+     * Streaming chat — yields chunks as they arrive.
+     *
+     * @deprecated Use `client.chat.stream()` instead. This method will be
+     * removed in the next major version.
+     */
+    async *createChatStream(messages, options = {}) {
+        yield* this.chat.stream(messages, options);
+    }
+    // -----------------------------------------------------------------------
+    // Cloud Streaming Inference (SSE)
+    // -----------------------------------------------------------------------
+    /**
+     * Stream tokens from the cloud inference endpoint via SSE.
+     *
+     * Consumes `POST /api/v1/inference/stream` and yields `StreamToken`
+     * objects as they arrive. Requires `serverUrl` and `apiKey` to be
+     * configured.
+     *
+     * @param modelId - Model identifier (e.g. `"phi-4-mini"`).
+     * @param input - Plain string prompt or chat-style messages.
+     * @param parameters - Generation parameters (temperature, max_tokens, etc.).
+     * @param signal - Optional AbortSignal for cancellation.
+     */
+    async *predictStream(modelId, input, parameters, signal) {
+        if (!this.options.serverUrl || !this.options.apiKey) {
+            throw new OctomilError("INFERENCE_FAILED", "predictStream() requires serverUrl and apiKey to be configured.");
         }
-        const streaming = new StreamingInferenceEngine({
-            serverUrl: this.options.serverUrl,
-            apiKey: this.options.apiKey,
-            onTelemetry: (e) => this.trackEvent(e),
-        });
-        const start = performance.now();
-        let content = "";
-        const generator = streaming.stream(this.options.model, {
-            messages,
-            temperature: options.temperature,
-            max_tokens: options.maxTokens,
-            top_p: options.topP,
-        }, { modality: "text", signal: options.signal });
-        for await (const chunk of generator) {
-            if (typeof chunk.data === "string") {
-                content += chunk.data;
-            }
+        const url = `${this.options.serverUrl.replace(/\/+$/, "")}/api/v1/inference/stream`;
+        const body = { model_id: modelId };
+        if (typeof input === "string") {
+            body.input_data = input;
         }
-        return {
-            message: { role: "assistant", content },
-            latencyMs: performance.now() - start,
+        else {
+            body.messages = input;
+        }
+        if (parameters) {
+            body.parameters = parameters;
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "text/event-stream",
+            Authorization: `Bearer ${this.options.apiKey}`,
         };
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal,
+            });
+        }
+        catch (err) {
+            throw new OctomilError("NETWORK_UNAVAILABLE", `predictStream request failed: ${String(err)}`, err);
+        }
+        if (!response.ok) {
+            throw new OctomilError("INFERENCE_FAILED", `predictStream failed: HTTP ${response.status}`);
+        }
+        if (!response.body) {
+            throw new OctomilError("INFERENCE_FAILED", "Server did not return a streaming body.");
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let chunkIndex = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (!line.startsWith("data:"))
+                        continue;
+                    const data = line.slice(5).trim();
+                    if (!data)
+                        continue;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(data);
+                    }
+                    catch {
+                        continue;
+                    }
+                    this.telemetry?.reportChunkProduced(modelId, chunkIndex);
+                    chunkIndex++;
+                    yield {
+                        token: parsed.token ?? "",
+                        done: parsed.done ?? false,
+                        provider: parsed.provider,
+                        latencyMs: parsed.latency_ms,
+                        sessionId: parsed.session_id,
+                    };
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
     }
+    // -----------------------------------------------------------------------
+    // Embeddings
+    // -----------------------------------------------------------------------
     /**
-     * Streaming chat — yields chunks as they arrive.
+     * Generate embeddings via the Octomil cloud endpoint.
+     *
+     * Requires `serverUrl` and `apiKey` to be configured.
+     *
+     * @param modelId - Embedding model identifier (e.g. `"nomic-embed-text"`).
+     * @param input - A single string or array of strings to embed.
+     * @param signal - Optional AbortSignal for cancellation.
      */
-    async *chatStream(messages, options = {}) {
-        this.ensureReady();
-        if (!this.options.serverUrl) {
-            throw new OctomilError("INFERENCE_FAILED", "chatStream() requires serverUrl to be configured.");
-        }
-        const streaming = new StreamingInferenceEngine({
-            serverUrl: this.options.serverUrl,
-            apiKey: this.options.apiKey,
-            onTelemetry: (e) => this.trackEvent(e),
-        });
-        const generator = streaming.stream(this.options.model, {
-            messages,
-            temperature: options.temperature,
-            max_tokens: options.maxTokens,
-            top_p: options.topP,
-        }, { modality: "text", signal: options.signal });
-        for await (const chunk of generator) {
-            yield {
-                index: chunk.index,
-                content: typeof chunk.data === "string" ? chunk.data : JSON.stringify(chunk.data),
-                done: chunk.done,
-                role: "assistant",
-            };
+    async embed(modelId, input, signal) {
+        if (!this.options.serverUrl || !this.options.apiKey) {
+            throw new OctomilError("NETWORK_UNAVAILABLE", "embed() requires serverUrl and apiKey to be configured.");
         }
+        return embedFn(this.options.serverUrl, this.options.apiKey, modelId, input, signal);
     }
     // -----------------------------------------------------------------------
     // Cache
     // -----------------------------------------------------------------------
     /** Check whether the model binary is currently cached locally. */
     async isCached() {
-        this.ensureNotDisposed();
+        this.ensureNotClosed();
         return this.loader.isCached();
     }
     /** Remove the cached model binary. */
     async clearCache() {
-        this.ensureNotDisposed();
+        this.ensureNotClosed();
         return this.loader.clearCache();
     }
     /** Get cache metadata for the model. */
     async cacheInfo() {
-        this.ensureNotDisposed();
+        this.ensureNotClosed();
         return this.loader.getCacheInfo();
     }
     // -----------------------------------------------------------------------
@@ -226,47 +363,206 @@ export class Octomil {
     // -----------------------------------------------------------------------
     /** The inference backend currently in use (after `load()`). */
     get activeBackend() {
-        return this.engine.activeBackend;
+        return this.inferenceEngine?.activeBackend ?? null;
     }
     /** Input tensor names defined by the loaded model. */
     get inputNames() {
         this.ensureReady();
-        return this.engine.inputNames;
+        if (!this.inferenceEngine) {
+            throw new OctomilError("INVALID_INPUT", "inputNames not available with custom runtime");
+        }
+        return this.inferenceEngine.inputNames;
     }
     /** Output tensor names defined by the loaded model. */
     get outputNames() {
         this.ensureReady();
-        return this.engine.outputNames;
+        if (!this.inferenceEngine) {
+            throw new OctomilError("INVALID_INPUT", "outputNames not available with custom runtime");
+        }
+        return this.inferenceEngine.outputNames;
     }
     /** Whether `load()` has been called successfully. */
     get isLoaded() {
         return this.loaded;
     }
     // -----------------------------------------------------------------------
+    // Chat namespace (OpenAI-compatible chat completions)
+    // -----------------------------------------------------------------------
+    /**
+     * Lazily-created `ChatClient` providing `chat.create()` and
+     * `chat.stream()` methods for OpenAI-compatible chat completions.
+     *
+     * Uses a local responses runtime when configured, otherwise falls back to
+     * the configured server-backed responses client.
+     *
+     * @example
+     * ```ts
+     * const response = await client.chat.create([
+     *   { role: 'user', content: 'Hello!' },
+     * ]);
+     * ```
+     */
+    get chat() {
+        if (!this._chat) {
+            this._chat = new ChatClient({
+                model: this.options.model,
+                serverUrl: this.options.serverUrl,
+                apiKey: this.options.apiKey,
+                getResponses: () => this.responses,
+                ensureReady: () => this.ensureReady(),
+            });
+        }
+        return this._chat;
+    }
+    // -----------------------------------------------------------------------
+    // Responses namespace (Layer 2 — structured response API)
+    // -----------------------------------------------------------------------
+    /**
+     * Lazily-created `ResponsesClient` providing `responses.create()` and
+     * `responses.stream()` methods for the structured response API.
+     *
+     * Uses a configured local responses runtime when available; otherwise uses
+     * the server-backed responses API. `apiKey` is optional but recommended for
+     * server-backed usage.
+     */
+    get responses() {
+        if (!this._responses) {
+            this._responses = new ResponsesClient({
+                serverUrl: this.options.serverUrl,
+                apiKey: this.options.apiKey,
+                telemetry: this.telemetry,
+                deviceContext: this.deviceContext,
+                localRuntime: this.options.responsesRuntime,
+            });
+        }
+        return this._responses;
+    }
+    // -----------------------------------------------------------------------
+    // Control namespace (device registration + heartbeat)
+    // -----------------------------------------------------------------------
+    /**
+     * Lazily-created `ControlClient` providing `control.register()`,
+     * `control.heartbeat()`, and `control.refresh()` methods.
+     *
+     * Uses the configured `serverUrl`, `apiKey`, and any `orgId`
+     * inferred from the options.
+     */
+    get control() {
+        if (!this._control) {
+            this._control = new ControlClient({
+                serverUrl: this.options.serverUrl,
+                apiKey: this.options.apiKey,
+                orgId: this.options.auth?.type === "org_api_key" ? this.options.auth.orgId : undefined,
+                deviceContext: this.deviceContext,
+                telemetry: this.telemetry,
+            });
+        }
+        return this._control;
+    }
+    // -----------------------------------------------------------------------
+    // Capabilities namespace (device capability profiling)
+    // -----------------------------------------------------------------------
+    /**
+     * Lazily-created `CapabilitiesClient` providing `capabilities.current()`
+     * to detect the full device capability profile.
+     */
+    get capabilities() {
+        if (!this._capabilities) {
+            this._capabilities = new CapabilitiesClient();
+        }
+        return this._capabilities;
+    }
+    // -----------------------------------------------------------------------
+    // Models namespace (status / load / unload / list / clearCache)
+    // -----------------------------------------------------------------------
+    /**
+     * Lazily-created `ModelsClient` providing `models.status()`,
+     * `models.load()`, `models.unload()`, `models.list()`, and
+     * `models.clearCache()`.
+     */
+    get models() {
+        if (!this._models) {
+            this._models = new ModelsClient(this.options.model, this.loader, () => {
+                // When ModelsClient.load() succeeds, mark the engine as loaded
+                // so that predict()/chat() work without a separate load() call.
+                // Note: the engine session is NOT created here — callers should
+                // still use OctomilClient.load() for full setup.  This callback
+                // ensures the downloading→ready state transition is tracked.
+            });
+        }
+        return this._models;
+    }
+    // -----------------------------------------------------------------------
+    // Audio namespace (transcriptions)
+    // -----------------------------------------------------------------------
+    /**
+     * Lazily-created `OctomilAudio` providing
+     * `audio.transcriptions.create()` for speech-to-text.
+     *
+     * Requires `serverUrl` and `apiKey` to be configured.
+     *
+     * @example
+     * ```ts
+     * const result = await client.audio.transcriptions.create({
+     *   file: audioBlob,
+     *   model: 'whisper-large-v3',
+     * });
+     * console.log(result.text);
+     * ```
+     */
+    get audio() {
+        if (!this._audio) {
+            if (!this.options.serverUrl || !this.options.apiKey) {
+                throw new OctomilError("INVALID_INPUT", "audio requires serverUrl and apiKey to be configured.");
+            }
+            this._audio = new OctomilAudio(this.options.serverUrl, this.options.apiKey);
+        }
+        return this._audio;
+    }
+    /**
+     * Lazily-created `OctomilText` providing `text.predictions.create()`
+     * for browser-local text inference via the loaded model.
+     */
+    get text() {
+        if (!this._text) {
+            this._text = new OctomilText((input) => this.predict(input));
+        }
+        return this._text;
+    }
+    // -----------------------------------------------------------------------
     // Cleanup
     // -----------------------------------------------------------------------
     /** Release all resources (WASM memory, WebGPU device, telemetry). */
-    dispose() {
-        if (this.disposed)
+    close() {
+        if (this.closed)
             return;
-        this.disposed = true;
+        this.closed = true;
         this.loaded = false;
         this.engine.dispose();
-        this.telemetry?.dispose();
+        this.telemetry?.close();
         this.telemetry = null;
+        this._responses = null;
+        this._chat = null;
+        this._control?.stopHeartbeat();
+        this._control = null;
+        this._capabilities = null;
+        this._models = null;
+        this._audio = null;
+        this._text = null;
+        this._warmedUp = false;
     }
     // -----------------------------------------------------------------------
     // Private helpers
     // -----------------------------------------------------------------------
-    ensureNotDisposed() {
-        if (this.disposed) {
-            throw new OctomilError("SESSION_DISPOSED", "This Octomil instance has been disposed. Create a new one.");
+    ensureNotClosed() {
+        if (this.closed) {
+            throw new OctomilError("CANCELLED", "This OctomilClient instance has been closed. Create a new one.");
         }
     }
     ensureReady() {
-        this.ensureNotDisposed();
+        this.ensureNotClosed();
         if (!this.loaded) {
-            throw new OctomilError("NOT_LOADED", "Model not loaded. Call load() before predict() or chat().");
+            throw new OctomilError("MODEL_LOAD_FAILED", "Model not loaded. Call load() before predict() or chat().");
         }
     }
     /**
@@ -280,7 +576,7 @@ export class Octomil {
         }
         // { raw, dims } — wrap in the first input name.
         if ("raw" in input && "dims" in input) {
-            const name = this.engine.inputNames[0];
+            const name = this.inferenceEngine.inputNames[0];
             if (!name) {
                 throw new OctomilError("INVALID_INPUT", "Model has no input tensors defined.");
             }
@@ -290,7 +586,7 @@ export class Octomil {
         // Real tokenization would require a tokenizer; this is a minimal
         // placeholder that works for models expecting raw code-point inputs.
         if ("text" in input) {
-            const name = this.engine.inputNames[0];
+            const name = this.inferenceEngine.inputNames[0];
             if (!name) {
                 throw new OctomilError("INVALID_INPUT", "Model has no input tensors defined.");
             }
@@ -350,7 +646,7 @@ export class Octomil {
             float[pixels + i] = rgba[i * 4 + 1] / 255; // G
             float[2 * pixels + i] = rgba[i * 4 + 2] / 255; // B
         }
-        const name = this.engine.inputNames[0];
+        const name = this.inferenceEngine?.inputNames[0];
         if (!name) {
             throw new OctomilError("INVALID_INPUT", "Model has no input tensors defined.");
         }
@@ -361,8 +657,43 @@ export class Octomil {
             },
         };
     }
-    trackEvent(event) {
-        this.telemetry?.track(event);
+    /**
+     * Attempt routing + cloud inference. Returns a PredictOutput if the
+     * routing decision is "cloud" and the cloud call succeeds, or `null`
+     * to fall back to local inference.
+     */
+    async tryCloudInference(input) {
+        try {
+            if (!this.deviceCaps) {
+                this.deviceCaps = await detectDeviceCapabilities();
+            }
+            const routing = this.options.routing;
+            const decision = await this.routingClient.route(this.options.model, routing.modelParams ?? 0, routing.modelSizeMb ?? 0, this.deviceCaps);
+            if (!decision || decision.target !== "cloud") {
+                return null;
+            }
+            const start = performance.now();
+            const cloudResponse = await this.routingClient.cloudInfer(this.options.model, input);
+            const latencyMs = performance.now() - start;
+            this.telemetry?.reportInferenceCompleted(this.options.model, latencyMs, {
+                target: "cloud",
+                provider: cloudResponse.provider,
+                routingId: decision.id,
+            });
+            // Wrap the cloud output in PredictOutput shape.
+            return {
+                tensors: {},
+                latencyMs,
+                ...(typeof cloudResponse.output === "object" &&
+                    cloudResponse.output !== null
+                    ? cloudResponse.output
+                    : { label: String(cloudResponse.output) }),
+            };
+        }
+        catch {
+            // Any failure in routing/cloud → fall back to local inference silently.
+            return null;
+        }
     }
 }
 //# sourceMappingURL=octomil.js.map