Config Types

CreateClientOptions

The options object passed to createClient().

interface CreateClientOptions {
  local?: LocalConfig;
  cloud?: CloudConfig;
  onProgress?: ProgressCallback;
  onRoute?: RouteCallback;
  onError?: (error: Error) => void;
}

LocalConfig

Configures the local inference backend.

type LocalConfig =
  | 'auto'                              // Auto-detect device, pick model
  | false | null                        // Disable local inference
  | string                              // Fixed model ID
  | LocalObjectConfig                   // Full configuration object
  | ((stats: DeviceStats) => string | null)  // Dynamic model selector
  | ResolvedLocalBackend;               // Explicit provider (mlc())

LocalObjectConfig

interface LocalObjectConfig {
  tiers?: TiersConfig;
  model?: string;
  useCache?: boolean;      // Default: true
  useWebWorker?: boolean;  // Default: true
}

CloudConfig

Configures the cloud inference backend.

type CloudConfig =
  | string                  // URL shorthand → { baseURL: string }
  | CloudObjectConfig       // Full configuration object
  | CloudFn                 // Custom function
  | ResolvedCloudBackend;   // Explicit provider (fetchSSE())

CloudObjectConfig

interface CloudObjectConfig {
  baseURL: string;
  apiKey?: string;
  model?: string;
  headers?: Record<string, string>;
  timeout?: number;   // ms
  retries?: number;
}

CloudFn

A function that handles inference directly.

type CloudFn = (
  messages: Message[],
  context: RouteContext,
) => Promise<ChatCompletion> | AsyncIterable<ChatCompletionChunk>;

TiersConfig

Maps device grade categories to model IDs.

interface TiersConfig {
  high?: string | 'auto' | null;    // Grade S/A devices
  medium?: string | 'auto' | null;  // Grade B devices
  low?: string | 'auto' | null;     // Grade C devices
}

'auto' — SDK picks a default model for that tier
null — Disable local inference for that tier
string — Specific model ID

LoadProgress

Progress information emitted during model loading.

interface LoadProgress {
  stage: 'download' | 'compile' | 'warmup';
  progress: number;        // 0 to 1
  model: string;           // Model ID being loaded
  bytesLoaded?: number;
  bytesTotal?: number;
}

ProgressCallback

type ProgressCallback = (progress: LoadProgress) => void;

DeviceStats

Hardware information collected during capability detection.

interface DeviceStats {
  gpu: GpuInfo | null;
  grade: DeviceGrade;          // 'S' | 'A' | 'B' | 'C'
  battery: BatteryInfo | null;
  memory: number;              // navigator.deviceMemory (GB)
}

CapabilityReport

Returned by checkCapability().

interface CapabilityReport {
  webgpu: boolean;
  gpu: GpuInfo | null;
  grade: DeviceGrade;
  battery: BatteryInfo | null;
  memory: number;
}

Supporting Types

type DeviceGrade = 'S' | 'A' | 'B' | 'C';

interface GpuInfo {
  vendor: string;
  name: string;
  vram: number;    // Estimated VRAM in MB
}

interface BatteryInfo {
  level: number;
  charging: boolean;
}

ModelLoadState

Internal state tracked by the load manager.

interface ModelLoadState {
  modelId: string;
  status: 'idle' | 'downloading' | 'compiling' | 'ready' | 'error';
  progress: number;
  error?: Error;
}

CacheInfo

interface CacheInfo {
  modelId: string;
  cached: boolean;
}

ClientStatus

Runtime status returned by client.status().

interface ClientStatus {
  localModel: string | null;
  localReady: boolean;
  localEnabled: boolean;
  cloudEnabled: boolean;
}

localModel — Resolved local model ID, or null if no model is selected
localReady — true if the local model is loaded and ready for inference
localEnabled — true if local inference is configured
cloudEnabled — true if cloud inference is configured

RouteCallback

Callback type for observing routing decisions.

type RouteCallback = (info: { decision: 'local' | 'cloud'; reason: string }) => void;

decision — Which backend was selected
reason — Human-readable explanation for the routing decision