@independo/inderun-web 0.3.0-dev.12 → 0.3.0-dev.14

package/src/index.ts

@@ -0,0 +1,147 @@
+/**
+ * Unified entry point for the IndeRun Web SDK (`@independo/inderun-web`).
+ *
+ * Everything a browser app needs to run and stream tasks is exported from here:
+ * the engine, the routing and provider seams, host services, error and telemetry
+ * types, and the contract types the SDK's own signatures use. Provider adapters
+ * are the deliberate exception — each ships from its own subpath
+ * (`/openai`, `/onnx`, `/system-model`) so this surface stays provider-agnostic.
+ */
+
+/**
+ * Host services: the platform capabilities the engine reads and calls through,
+ * and the seams an embedder overrides to supply its own (custom transport,
+ * credential storage, clock).
+ */
+export {
+  type AbortSignalLike,
+  type ConnectivityService,
+  type DeviceConstraintsService,
+  type SecureStorageService,
+  type ClockService,
+  type HttpClientService,
+  type HttpRequest,
+  type HttpResponse,
+  type HttpStreamResponse,
+  type HttpStreamingClientService,
+  type HostServices,
+  type ThermalState
+} from "./core/host.js";
+
+/**
+ * The provider contract. Implement `ProviderAdapter` for a Mode 1 backend and add
+ * a `stream` for Mode 2; the descriptor and dynamic capability check are what the
+ * router plans against.
+ */
+export {
+  type ProviderDescriptor,
+  type ProviderDynamicCapabilities,
+  type ProviderCapabilitySnapshot,
+  type RunContext,
+  type ProviderAdapter,
+  type ProviderStreamContext,
+  type ProviderStreamEvent,
+  type StreamRun
+} from "./core/provider.js";
+
+/**
+ * Per-run gatekeeper for a Mode 2 stream: assigns the sequence numbers callers
+ * order by, and enforces that exactly one terminal outcome is produced with
+ * nothing admitted after it. Exported for embedders driving a stream themselves.
+ */
+export { EventGate } from "./core/event-gate.js";
+
+/** Holds the provider adapters a given engine instance can route to. */
+export { ProviderRegistry } from "./core/registry.js";
+
+/**
+ * Route selection. `Router` turns a request plus a host capability snapshot into
+ * a provider chain; `WasmRoutePlanner` is the shared Rust planner behind it, and
+ * the only planner the Web SDK has — there is no JavaScript fallback.
+ */
+export { type RouteSelection, Router } from "./core/router.js";
+export {
+  type RoutePlanner,
+  type PlannerOutcome,
+  type WasmUnavailableReason,
+  type SharedPlannerInput,
+  type SharedPlannerRoutePlan,
+  WasmRoutePlanner
+} from "./core/route-planner.js";
+
+/**
+ * The normalized error taxonomy. Every failure the SDK surfaces is an
+ * `IndeRunException` in one of these classes, whatever the provider raised.
+ */
+export {
+  type IndeRunExceptionParams,
+  IndeRunException,
+  createCapabilityMismatch,
+  createOffline,
+  createAuthError,
+  createRateLimited,
+  createTimeout,
+  createUnavailable,
+  createInternal,
+  toIndeRunException
+} from "./core/errors.js";
+
+/** The engine itself, and the app-facing API surface it implements. */
+export { IndeRun, type StreamHandleResult } from "./core/engine.js";
+export type { IndeRunApi } from "./core/generated/inderun-api.js";
+
+/**
+ * The contract types this SDK's own signatures take and return.
+ *
+ * Re-exported so a typed app needs only the one dependency the README tells it to
+ * install. `@independo/inderun-contracts` is ours transitively, and under pnpm's
+ * isolated `node_modules` an undeclared import of it does not resolve at all.
+ * This is the npm counterpart of Gradle `api(...)` on Android and `@_exported
+ * import` on Swift — see
+ * {@link https://github.com/independo-gmbh/inderun/issues/189 | #189}. The
+ * host-service and telemetry blocks in this file re-export their halves of the
+ * same contract surface for the same reason.
+ *
+ * Depend on `@independo/inderun-contracts` directly only for what is not
+ * re-exported here: the JSON Schemas and the `get*ValidationIssues` validators.
+ */
+export type {
+  IndeRunError,
+  IndeRunErrorClass,
+  StreamEvent,
+  StreamRunHandle,
+  StreamTerminalOutcome,
+  TaskRequest,
+  TaskResult
+} from "@independo/inderun-contracts";
+
+/**
+ * Telemetry. Pass a `TelemetryService` to observe routing decisions and attempt
+ * outcomes; the engine defaults to `NoOpTelemetryService`.
+ */
+export {
+  type TelemetryEventType,
+  type TelemetryEvent,
+  type TelemetryService,
+  NoOpTelemetryService
+} from "./core/telemetry.js";
+
+/**
+ * The browser implementations of the host services above, and the factory that
+ * assembles them. Use these directly only when constructing `IndeRun` by hand.
+ */
+export {
+  BrowserConnectivityService,
+  FetchHttpClient,
+  FetchStreamingHttpClient,
+  SystemClockService,
+  createBrowserHostServices,
+  type CreateBrowserHostServicesOptions,
+  type FetchHttpClientOptions
+} from "./core/browser-host.js";
+
+/**
+ * The recommended way in: builds host services, registers the providers named in
+ * the options, and returns a ready engine.
+ */
+export { createIndeRunWeb, type CreateIndeRunWebOptions } from "./web-sdk.js";

package/src/onnx.ts

@@ -0,0 +1,57 @@
+/**
+ * Provider-specific entry point for the Web member of the ONNX Runtime provider family.
+ *
+ * Kept out of the unified SDK index (`@independo/inderun-web`) so the top-level
+ * surface stays provider-agnostic. Import from `@independo/inderun-web/onnx`
+ * when registering the adapter manually or when implementing a custom
+ * `OnnxTextGenerationRuntime`; most browser apps should pass `onnx` to
+ * `createIndeRunWeb` from the main entry point instead.
+ *
+ * See {@link https://github.com/independo-gmbh/inderun/blob/main/docs/architecture/onnx-runtime-provider-family.md | the ONNX Runtime provider family doc}
+ * for the model IO contract, supported source types, and error mapping.
+ */
+
+/** The adapter itself, plus the source types and default id the router plans against. */
+export {
+  OnnxRuntimeWebProvider,
+  DEFAULT_ONNX_WEB_PROVIDER_ID,
+  SUPPORTED_WEB_MODEL_SOURCE_TYPES,
+  type OnnxProviderOptions
+} from "./providers/onnx/provider.js";
+
+/**
+ * The runtime seam. The provider does no inference itself: it delegates to an
+ * `OnnxTextGenerationRuntime`, so an app can swap in its own engine, or
+ * `createFixtureOnnxRuntime()` for demos and tests without shipping a model.
+ */
+export {
+  OnnxRuntimeError,
+  createFixtureOnnxRuntime,
+  type FixtureOnnxRuntimeOptions,
+  type OnnxGenerationInput,
+  type OnnxGenerationMessage,
+  type OnnxGenerationOutput,
+  type OnnxRuntimeAvailability,
+  type OnnxRuntimeErrorKind,
+  type OnnxTextGenerationRuntime
+} from "./providers/onnx/runtime.js";
+
+/**
+ * The model-description contract types this entry point's options take.
+ * Re-exported for the same reason as the contract types on the SDK index — see
+ * the note there.
+ */
+export type { ModelPackage, ModelSourceType } from "@independo/inderun-contracts";
+
+/**
+ * The default runtime, backed by `@huggingface/transformers`. That package is an
+ * optional peer dependency and is reached structurally through
+ * `TransformersModule`, so nothing here forces it on apps that supply their own
+ * runtime.
+ */
+export {
+  createTransformersJsRuntime,
+  type TransformersJsRuntimeOptions,
+  type TransformersModule,
+  type TransformersTextGenerator
+} from "./providers/onnx/transformers-runtime.js";

package/src/openai.ts

@@ -0,0 +1,21 @@
+/**
+ * Provider-specific entry point for the OpenAI Responses adapter.
+ *
+ * Kept out of the unified SDK index (`@independo/inderun-web`) so the top-level
+ * surface stays provider-agnostic. Import from `@independo/inderun-web/openai`
+ * when registering the adapter manually; most browser apps should use
+ * `createIndeRunWeb` from the main entry point instead.
+ *
+ * Browser apps must point `endpointUrl` at a same-origin proxy that holds the
+ * API key server-side. Provider credentials must never reach the browser.
+ */
+
+/**
+ * The adapter and its options. Runs Mode 1 and Mode 2 against any
+ * OpenAI-Responses-compatible endpoint, not just OpenAI's own.
+ */
+export {
+  OpenAIResponsesProvider,
+  type OpenAIProviderOptions,
+  DEFAULT_OPENAI_RESPONSES_ENDPOINT
+} from "./providers/openai/provider.js";

package/src/providers/onnx/provider.ts

@@ -0,0 +1,300 @@
+import {
+  getModelPackageValidationIssues,
+  type ModelPackage,
+  type ModelSourceType,
+  type TaskRequest,
+  type TaskResult
+} from "@independo/inderun-contracts";
+import {
+  createCapabilityMismatch,
+  createInternal,
+  createTimeout,
+  createUnavailable,
+  toIndeRunException,
+  type IndeRunException
+} from "../../core/errors.js";
+import type { HostServices } from "../../core/host.js";
+import {
+  OnnxRuntimeError,
+  type OnnxGenerationMessage,
+  type OnnxGenerationOutput,
+  type OnnxTextGenerationRuntime
+} from "./runtime.js";
+import { createTransformersJsRuntime } from "./transformers-runtime.js";
+import type {
+  ProviderAdapter,
+  ProviderDescriptor,
+  ProviderDynamicCapabilities,
+  RunContext
+} from "../../core/provider.js";
+
+/** Default provider id of the Web member of the ONNX Runtime provider family. */
+export const DEFAULT_ONNX_WEB_PROVIDER_ID = "local.onnx.genai.web";
+
+/** Task kind this provider implements in Milestone 2 (Mode 1 only). */
+const TEXT_TO_TEXT = "text_to_text";
+
+/**
+ * Model source types the Web member of the ONNX Runtime provider family can honor.
+ *
+ * `filesystem` is unsupported because browsers do not expose arbitrary local paths, and `remote`
+ * is deferred: hosts download model files themselves and then supply them as `bundled`,
+ * `app_managed`, or `programmatic`.
+ */
+export const SUPPORTED_WEB_MODEL_SOURCE_TYPES: readonly ModelSourceType[] = [
+  "registry",
+  "bundled",
+  "programmatic",
+  "app_managed"
+];
+
+/**
+ * Configuration for the Web ONNX Runtime provider.
+ */
+export interface OnnxProviderOptions {
+  /**
+   * Provider id exposed in telemetry and routing explanations.
+   */
+  id?: string;
+  /**
+   * Provider-neutral bootstrap metadata describing the developer-supplied model.
+   */
+  modelPackage: ModelPackage;
+  /**
+   * Runtime implementation used to execute generation. Defaults to the Transformers.js-backed
+   * runtime; applications can inject their own implementation of the seam.
+   */
+  runtime?: OnnxTextGenerationRuntime;
+  /**
+   * Optional generation timeout in milliseconds. A request-level `constraints.timeoutMs` wins.
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Local provider adapter that executes Mode-1 text-to-text requests with a developer-supplied ONNX
+ * model in the browser.
+ *
+ * The adapter owns the IndeRun-facing contract (descriptor, capability checks, error taxonomy) and
+ * delegates execution to an injectable {@link OnnxTextGenerationRuntime}. ONNX Runtime execution
+ * backends (WASM, WebGPU, WebNN) stay behind that seam and are never public routing concepts.
+ */
+export class OnnxRuntimeWebProvider implements ProviderAdapter {
+  private readonly id: string;
+  private readonly modelPackage: ModelPackage;
+  private readonly runtime: OnnxTextGenerationRuntime;
+
+  /**
+   * Creates a Web ONNX Runtime provider.
+   * @param options - Model package plus optional id, runtime, and timeout overrides.
+   */
+  constructor(private readonly options: OnnxProviderOptions) {
+    this.id = options.id ?? DEFAULT_ONNX_WEB_PROVIDER_ID;
+    this.modelPackage = options.modelPackage;
+    this.runtime = options.runtime ?? createTransformersJsRuntime();
+  }
+
+  /**
+   * Returns static metadata used by the router for deterministic provider selection.
+   */
+  describe(): ProviderDescriptor {
+    return {
+      id: this.id,
+      type: "local",
+      transport: "in_process",
+      supports: {
+        run: true,
+        streaming: false,
+        realtime: false,
+        tools: false,
+        reasoningEvents: false,
+        structuredOutput: false,
+        multimodal: false
+      },
+      cancel: "soft",
+      tasks: getDeclaredTasks(this.modelPackage),
+      privacy: {
+        dataLeavesDevice: false
+      }
+    };
+  }
+
+  /**
+   * Reports dynamic provider availability for the current host.
+   *
+   * Every failure below is provider-internal detail: the shared route planner flattens it into a
+   * single `capability_unavailable` rejection carrying the returned reason.
+   *
+   * @param _host - Host services available to the engine (unused; ONNX runs in-process).
+   */
+  async capabilities(_host: HostServices): Promise<ProviderDynamicCapabilities> {
+    const issues = getModelPackageValidationIssues(this.modelPackage);
+    if (issues.length > 0) {
+      const summary = issues.map((issue) => `${issue.path} ${issue.message}`).join("; ");
+      return { available: false, reason: `model package malformed: ${summary}` };
+    }
+
+    const sourceType = this.modelPackage.source?.sourceType;
+    if (sourceType !== undefined && !SUPPORTED_WEB_MODEL_SOURCE_TYPES.includes(sourceType)) {
+      return {
+        available: false,
+        reason:
+          sourceType === "filesystem"
+            ? "model source unavailable: 'filesystem' model sources are unsupported on Web because browsers cannot read arbitrary local paths."
+            : `model source unavailable: '${sourceType}' model sources are deferred on Web; supply model files as ${SUPPORTED_WEB_MODEL_SOURCE_TYPES.join(", ")}.`
+      };
+    }
+
+    const platforms = this.modelPackage.runtime?.platforms;
+    if (Array.isArray(platforms) && platforms.length > 0 && !platforms.includes("web")) {
+      return {
+        available: false,
+        reason: `platform unsupported: the model package targets ${platforms.join(", ")} and does not list 'web'.`
+      };
+    }
+
+    if (!getDeclaredTasks(this.modelPackage).includes(TEXT_TO_TEXT)) {
+      return {
+        available: false,
+        reason: `unsupported task: the model package declares ${getDeclaredTasks(this.modelPackage).join(", ")} and does not support '${TEXT_TO_TEXT}'.`
+      };
+    }
+
+    return this.runtime.prepare(this.modelPackage);
+  }
+
+  /**
+   * Executes a normalized text-to-text task on the developer-supplied local ONNX model.
+   * @param request - Canonical IndeRun task request.
+   * @param context - Engine execution context containing run id and host services.
+   * @returns Normalized IndeRun task result.
+   * @throws IndeRunException mapped to the standard error taxonomy.
+   */
+  async run(request: TaskRequest, context: RunContext): Promise<TaskResult> {
+    const availability = await this.capabilities(context.hostServices);
+    if (!availability.available) {
+      throw createCapabilityMismatch(
+        availability.reason ?? "ONNX Runtime Web provider is unavailable on this host.",
+        { providerId: this.id, runId: context.runId }
+      );
+    }
+
+    const messages = createMessages(request);
+    if (messages.length === 0) {
+      throw createInternal("ONNX Runtime Web provider requires a prompt or messages.", {
+        providerId: this.id,
+        runId: context.runId
+      });
+    }
+
+    const timeoutMs = request.constraints?.timeoutMs ?? this.options.timeoutMs;
+    const controller = new AbortController();
+    const timer =
+      timeoutMs !== undefined && timeoutMs > 0
+        ? setTimeout(() => controller.abort(), timeoutMs)
+        : undefined;
+
+    let output: OnnxGenerationOutput;
+    try {
+      output = await this.runtime.generate(
+        {
+          modelPackage: this.modelPackage,
+          messages,
+          ...(request.generation !== undefined ? { generation: request.generation } : {})
+        },
+        controller.signal
+      );
+    } catch (err) {
+      throw this.mapRuntimeError(err, context);
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+
+    if (typeof output.text !== "string" || output.text.length === 0) {
+      throw createInternal("ONNX Runtime Web provider returned no text output.", {
+        providerId: this.id,
+        runId: context.runId
+      });
+    }
+
+    const result: TaskResult = {
+      schemaVersion: "1.0",
+      runId: context.runId,
+      output: {
+        type: "text",
+        text: output.text
+      },
+      finishReason: output.finishReason ?? "stop",
+      telemetry: {
+        providerUsed: this.id,
+        totalMs: 0
+      }
+    };
+
+    if (output.usage) {
+      result.usage = output.usage;
+    }
+
+    return result;
+  }
+
+  private mapRuntimeError(error: unknown, context: RunContext): IndeRunException {
+    const extra = { providerId: this.id, runId: context.runId };
+
+    if (error instanceof OnnxRuntimeError) {
+      const details =
+        error.originalError !== undefined
+          ? { details: { originalError: getErrorSummary(error.originalError) } }
+          : {};
+
+      switch (error.kind) {
+        case "capability":
+          return createCapabilityMismatch(error.message, { ...extra, ...details });
+        case "unavailable":
+          return createUnavailable(error.message, { ...extra, ...details });
+        case "timeout":
+          return createTimeout(error.message, { ...extra, ...details });
+        default:
+          return createInternal(error.message, { ...extra, ...details });
+      }
+    }
+
+    if (isAbortError(error)) {
+      return createTimeout("ONNX Runtime Web generation timed out.", extra);
+    }
+
+    return toIndeRunException(error, extra);
+  }
+}
+
+function getDeclaredTasks(modelPackage: ModelPackage): string[] {
+  const tasks = modelPackage.tasks;
+  return Array.isArray(tasks) && tasks.length > 0 ? tasks : [TEXT_TO_TEXT];
+}
+
+function createMessages(request: TaskRequest): OnnxGenerationMessage[] {
+  if (request.messages && request.messages.length > 0) {
+    return request.messages.map((message) => ({
+      role: message.role,
+      content: message.content
+    }));
+  }
+
+  const prompt = request.prompt;
+  return prompt !== undefined && prompt.length > 0 ? [{ role: "user", content: prompt }] : [];
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { name?: unknown }).name === "AbortError"
+  );
+}
+
+function getErrorSummary(error: unknown): Record<string, unknown> {
+  if (error instanceof Error) {
+    return { name: error.name, message: error.message, stack: error.stack };
+  }
+  return { message: String(error) };
+}