API Summary — v0.12.x (latest)

function cancel(params: CancelClientInput): Promise<void>;

// Cancel by requestId (primary path)
const run = completion({ ... });
await cancel({ requestId: run.requestId });

// Broad-cancel every inference running on a model
await cancel({ modelId: "model-123", kind: "completion" });

function classify(params: ClassifyClientParams): Promise<ClassificationResult[]>;

const modelId = await loadModel({ modelType: "ggml-classification" });
const jpeg = fs.readFileSync("photo.jpg");
const results = await classify({ modelId, image: jpeg });
// [ { label: "food", confidence: 0.93 }, { label: "other", confidence: 0.05 }, ... ]
await unloadModel({ modelId });

function completion(params: CompletionParams): CompletionRun;

import { z } from "zod";

const run = completion({
  modelId: "llama-2",
  history: [
    { role: "user", content: "What's the weather in Tokyo?" }
  ],
  stream: true,
  captureThinking: true,
  tools: [{
    name: "get_weather",
    description: "Get current weather",
    parameters: z.object({
      city: z.string().describe("City name"),
    }),
    handler: async (args) => {
      return { temperature: 22, condition: "sunny" };
    }
  }]
});

for await (const event of run.events) {
  if (event.type === "contentDelta") process.stdout.write(event.text);
  if (event.type === "toolCall") console.log(event.call.name, event.call.arguments);
}

const result = await run.final;
for (const toolCall of await result.toolCalls) {
  if (toolCall.invoke) {
    const toolResult = await toolCall.invoke();
    console.log(toolResult);
  }
}

function deleteCache(params: { all: true } | { kvCacheKey: string; modelId?: string }): Promise<{ success: boolean }>;

// Delete all caches
await deleteCache({ all: true });

// Delete entire cache key (all models)
await deleteCache({ kvCacheKey: "my-session" });

// Delete only specific model within cache key
await deleteCache({ kvCacheKey: "my-session", modelId: "model-abc123" });

function diffusion(params: DiffusionClientParams): DiffusionResult;

// txt2img
const { outputs, stats } = diffusion({ modelId, prompt: "a cat" });
const buffers = await outputs;
fs.writeFileSync("output.png", buffers[0]);

// img2img (SD/SDXL — SDEdit)
const initImage = fs.readFileSync("input.png");
const { outputs } = diffusion({ modelId, prompt: "oil painting style", init_image: initImage, strength: 0.7 });

// img2img (FLUX.2 — in-context conditioning)
// IMPORTANT: FLUX img2img requires `prediction: "flux2_flow"` to be set on the
// model config at loadModel time (e.g. `loadModel(src, { modelType: "diffusion",
// modelConfig: { prediction: "flux2_flow" } })`).
const { outputs } = diffusion({ modelId, prompt: "turn into watercolor", init_image: initImage });

// FLUX.2 multi-reference fusion
// IMPORTANT: requires the model loaded with `modelConfig: { prediction: "flux2_flow" }`
// and a Qwen3 text encoder via `llmModelSrc` (same loadModel requirements as the
// FLUX.2 img2img example above). `init_image` and `init_images` are mutually
// exclusive — pass one or the other, not both.
const refA = fs.readFileSync("scientist-a.jpg");
const refB = fs.readFileSync("scientist-b.jpg");
const { outputs } = diffusion({
  modelId,
  prompt: "a portrait using most visual traits from @image1 and the eyes from @image2",
  init_images: [refA, refB],
  width: 768,
  height: 768,
});

// LoRA adapter for this generation (absolute path required).
// Persistence across subsequent diffusion() calls is controlled at
// loadModel time via `modelConfig.lora_apply_mode`.
const { outputs } = diffusion({
  modelId,
  prompt: "a watercolor cat",
  lora: "/home/user/loras/watercolor.safetensors",
});

// ESRGAN upscale; requires the model to be loaded with `modelConfig.upscaler.model_src` set.
const { outputs: singleOutputs } = diffusion({
  modelId,
  prompt: "a fox portrait",
  width: 128,
  height: 128,
  upscale: true, // one native-scale pass
});
const single = await singleOutputs;
fs.writeFileSync("upscaled.png", single[0]);

// Repeat upscale passes when needed.
const { outputs: hiresOutputs } = diffusion({
  modelId,
  prompt: "a fox portrait",
  width: 128,
  height: 128,
  upscale: { repeats: 2 },
});
const hires = await hiresOutputs;
fs.writeFileSync("hires.png", hires[0]);

// With progress tracking
const { progressStream, outputs } = diffusion({ modelId, prompt: "a cat" });
for await (const { step, totalSteps } of progressStream) {
  console.log(`${step}/${totalSteps}`);
}
const buffers = await outputs;

function downloadAsset(options: DownloadAssetOptions, rpcOptions?: RPCOptions): Promise<string> & { requestId: string };

// Download model without loading
const assetId = await downloadAsset({
  assetSrc: "/path/to/model.gguf",
  seed: true
});

// Download with progress tracking
const assetId = await downloadAsset({
  assetSrc: "pear://key123/model.gguf",
  onProgress: (progress) => {
    console.log(`Downloaded: ${progress.percentage}%`);
  }
});

// Targeted cancel by requestId — grab the id synchronously, then
// cancel before the download resolves.
const op = downloadAsset({ assetSrc: "https://example.com/large.gguf" });
setTimeout(() => cancel({ requestId: op.requestId }), 1000);
await op; // rejects with `InferenceCancelledError`

function embed(params: { modelId: string; text: string }, options?: RPCOptions): Promise<{ embedding: number[]; stats?: { backendDevice?: "gpu" | "cpu"; tokensPerSecond?: number; totalTime?: number; totalTokens?: number } }> & { requestId: string };

function embed(params: { modelId: string; text: string[] }, options?: RPCOptions): Promise<{ embedding: number[][]; stats?: { backendDevice?: "gpu" | "cpu"; tokensPerSecond?: number; totalTime?: number; totalTokens?: number } }> & { requestId: string };

function finetune(params: FinetuneRunParams, rpcOptions?: RPCOptions): FinetuneHandle;

function finetune(params: FinetuneReplyParams, rpcOptions?: RPCOptions): Promise<FinetuneResult>;

function getLoadedModelInfo(params: GetLoadedModelInfoParams, rpcOptions?: RPCOptions): Promise<LoadedModelInfo>;

const info = await getLoadedModelInfo({ modelId });
if (info.isDelegated || info.handlers.includes("completionStream")) {
  // safe to call completion(); delegated path defers to provider
}

function getModelInfo(params: GetModelInfoParams): Promise<{ actualSize?: number; addon: "llm" | "whisper" | "embeddings" | "nmt" | "vad" | "tts" | "ocr" | "parakeet" | "diffusion" | "vla" | "classification" | "other"; blobBlockLength?: number; blobBlockOffset?: number; blobByteOffset?: number; blobCoreKey?: string; cachedAt?: Date; cacheFiles: { actualSize?: number; cachedAt?: Date; expectedSize: number; filename: string; isCached: boolean; path: string; sha256Checksum: string }[]; engine?: string; expectedSize: number; isCached: boolean; isLoaded: boolean; loadedInstances?: { config?: unknown; loadedAt: Date; registryId: string }[]; modelId: string; name: string; params?: string; quantization?: string; registryPath?: string; registrySource?: string; sha256Checksum: string }>;

function heartbeat(params?: { delegate?: { healthCheckTimeout?: number; providerPublicKey: string; timeout?: number } }): Promise<HeartbeatResponse>;

// Check if a delegated provider is online
try {
  await heartbeat({
    delegate: { providerPublicKey: "peerHex", timeout: 3000 },
  });
  console.log("Provider is online");
} catch {
  console.log("Provider is offline");
}

// Check if the local SDK worker is responsive
await heartbeat();

function invokePlugin(options: InvokePluginOptions<TParams>, rpcOptions?: RPCOptions): Promise<TResponse>;

function invokePluginStream(options: InvokePluginOptions<TParams>, rpcOptions?: RPCOptions): AsyncGenerator<TResponse>;

function loadModel(options: LoadModelDescriptorParam<S>, rpcOptions?: RPCOptions): Promise<string> & { requestId: string };

await loadModel({ modelSrc: LLAMA_3_2_1B_INST_Q4_0, modelConfig: { ctx_size: 2048 } });
await loadModel({ modelSrc: WHISPER_TINY });

function loadModel(options: LoadModelOptions, rpcOptions?: RPCOptions): Promise<string> & { requestId: string };

// Local file path - absolute path
const localModelId = await loadModel({
  modelSrc: "/home/user/models/llama-7b.gguf",
  modelType: "llm",
  modelConfig: { ctx_size: 2048 }
});

// Local file path - relative path
const relativeModelId = await loadModel({
  modelSrc: "./models/whisper-base.gguf",
  modelType: "whisper"
});

// Hyperdrive URL with key and path
const hyperdriveId = await loadModel({
  modelSrc: "pear://<hyperdrive-key>/llama-7b.gguf",
  modelType: "llm",
  modelConfig: { ctx_size: 2048 }
});

// Remote HTTP/HTTPS URL with progress tracking
const remoteId = await loadModel({
  modelSrc: "https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/main/llama-2-7b-chat.Q4_K_M.gguf",
  modelType: "llm",
  onProgress: (progress) => {
    console.log(`Downloaded: ${progress.percentage}%`);
  }
});

// Multimodal model with projection
const multimodalId = await loadModel({
  modelSrc: "https://huggingface.co/.../main-model.gguf",
  modelType: "llm",
  modelConfig: {
    ctx_size: 512,
    projectionModelSrc: "https://huggingface.co/.../projection-model.gguf"
  },
  onProgress: (progress) => {
    console.log(`Loading: ${progress.percentage}%`);
  }
});

// Whisper with VAD model
const whisperId = await loadModel({
  modelSrc: "https://huggingface.co/.../whisper-model.gguf",
  modelType: "whisper",
  modelConfig: {
    mode: "caption",
    output_format: "plaintext",
    min_seconds: 2,
    max_seconds: 6,
    vadModelSrc: "https://huggingface.co/.../vad-model.bin"
  }
});

// Load with automatic logging - logs from the model will be forwarded to your logger
import { getLogger } from "@/logging";
const logger = getLogger("my-app");

const modelId = await loadModel({
  modelSrc: "/path/to/model.gguf",
  modelType: "llm",
  logger // Pass logger in options
});

function loadModel(options: LoadCustomPluginModelOptions<T>, rpcOptions?: RPCOptions): Promise<string> & { requestId: string };

function loadModel(options: ReloadConfigOptions, rpcOptions?: RPCOptions): Promise<string> & { requestId: string };

// Load new model
const modelId = await loadModel({
  modelSrc: "pear://<hyperdrive-key>/whisper-tiny.gguf",
  modelType: "whisper",
  modelConfig: { language: "en" },
});

// Later, update the config without reloading the model
await loadModel({
  modelId,
  modelType: "whisper",
  modelConfig: { language: "es" },
});

function loggingStream(params: LoggingParams): AsyncGenerator<LoggingStreamResponse>;

// Open a logging stream for a model
const logStream = loggingStream({ id: 'my-model-id' });

// Or stream SDK server logs
const sdkLogs = loggingStream({ id: SDK_LOG_ID });

for await (const logMessage of logStream) {
  console.log(`[${logMessage.level}] ${logMessage.namespace}: ${logMessage.message}`);
}

function modelRegistryGetModel(registryPath: string, registrySource: string): Promise<ModelRegistryEntry>;

function modelRegistryList(): Promise<ModelRegistryEntry[]>;

function modelRegistrySearch(params: ModelRegistrySearchParams): Promise<ModelRegistryEntry[]>;

function ocr(params: OCRClientParams): { blocks: Promise<{ bbox?: [number, number, number, number]; confidence?: number; text: string }[]>; blockStream: AsyncGenerator<{ bbox?: [number, number, number, number]; confidence?: number; text: string }[]>; stats: Promise<{ detectionTime?: number; recognitionTime?: number; totalTime?: number } | undefined> };

// Non-streaming mode (default) - get all blocks at once
const { blocks } = ocr({ modelId, image: "/path/to/image.png" });
for (const block of await blocks) {
  console.log(block.text, block.bbox, block.confidence);
}

// Streaming mode - process blocks as they arrive
const { blockStream } = ocr({ modelId, image: imageBuffer, stream: true });
for await (const blocks of blockStream) {
  console.log("Detected:", blocks);
}

function ragChunk(params: RagChunkParams, options?: RPCOptions): Promise<RagDoc[]>;

const chunks = await ragChunk({
  documents: ["Long document text here..."],
  chunkOpts: {
    chunkSize: 256,
    chunkOverlap: 50,
    chunkStrategy: "paragraph",
  },
});

function ragCloseWorkspace(params?: RagCloseWorkspaceParams, options?: RPCOptions): Promise<void>;

// Close a specific workspace
await ragCloseWorkspace({ workspace: "my-docs" });

// Close and delete in one call
await ragCloseWorkspace({ workspace: "my-docs", deleteOnClose: true });

function ragDeleteEmbeddings(params: RagDeleteEmbeddingsParams, options?: RPCOptions): Promise<void>;

await ragDeleteEmbeddings({
  ids: ["doc-1", "doc-2"],
  workspace: "my-docs",
});

function ragDeleteWorkspace(params: RagDeleteWorkspaceParams, options?: RPCOptions): Promise<void>;

await ragDeleteWorkspace({ workspace: "my-docs" });

function ragIngest(params: RagIngestParams, options?: RPCOptions): Promise<{ droppedIndices: number[]; processed: SaveEmbeddingsResult[] }> & { requestId: string };

// Simple ingest
const result = await ragIngest({
  modelId,
  documents: ["Document 1", "Document 2"],
});

// With progress tracking
const result = await ragIngest({
  modelId,
  documents: ["Document 1", "Document 2"],
  workspace: "my-docs",
  onProgress: (stage, current, total) => {
    console.log(`[${stage}] ${current}/${total}`);
  },
});

function ragListWorkspaces(options?: RPCOptions): Promise<RagWorkspaceInfo[]>;

const workspaces = await ragListWorkspaces();
// [{ name: "default", open: true }, { name: "my-docs", open: false }]

function ragReindex(params: RagReindexParams, options?: RPCOptions): Promise<ReindexResult> & { requestId: string };

// Simple reindex
const result = await ragReindex({
  workspace: "my-docs",
});

// Check result
if (!result.reindexed) {
  console.log("Reindex skipped:", result.details?.reason);
}

// With progress tracking
const result = await ragReindex({
  workspace: "my-docs",
  onProgress: (stage, current, total) => {
    console.log(`[${stage}] ${current}/${total}`);
  },
});

function ragSaveEmbeddings(params: RagSaveEmbeddingsParams, options?: RPCOptions): Promise<SaveEmbeddingsResult[]> & { requestId: string };

// Segregated flow
const chunks = await ragChunk({ documents: ["text1", "text2"] });
const { embedding: embeddings } = await embed({ modelId, text: chunks.map(c => c.content) });
const embeddedDocs = chunks.map((chunk, i) => ({
  ...chunk,
  embedding: embeddings[i],
  embeddingModelId: modelId,
}));
const result = await ragSaveEmbeddings({
  documents: embeddedDocs,
  workspace: "my-workspace",
});

function ragSearch(params: RagSearchParams, options?: RPCOptions): Promise<RagSearchResult[]>;

const results = await ragSearch({
  modelId,
  query: "AI and machine learning",
  topK: 5,
  workspace: "my-docs",
});

function resume(): Promise<void>;

// Foreground handler
await resume();
console.log(await state()); // "active"

function startQVACProvider(params: ProvideParams): Promise<{ error?: string; publicKey?: string; success: boolean; type: "provide" }>;

function state(): Promise<LifecycleState>;

// Branch on lifecycle state before issuing work
const current = await state();
if (current !== "active") {
  await resume();
}

function stopQVACProvider(): Promise<{ error?: string; success: boolean; type: "stopProvide" }>;

function suspend(): Promise<void>;

// Background handler
await suspend();
console.log(await state()); // "suspended"

function textToSpeech(params: TtsClientParamsInput, options?: RPCOptions): TextToSpeechStreamResult;

function textToSpeechStream(params: TextToSpeechStreamClientParams, options?: RPCOptions): Promise<TextToSpeechStreamSession>;

function transcribe(params: TranscribeClientParams & { metadata: true }, options?: RPCOptions): Promise<{ append: boolean; endMs: number; id: number; startMs: number; text: string }[]> & { requestId: string };

function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string> & { requestId: string };

function transcribeStream(params: TranscribeClientParams & { metadata: true }, options?: RPCOptions): AsyncGenerator<TranscribeSegment>;

function transcribeStream(params: TranscribeClientParams, options?: RPCOptions): AsyncGenerator<string>;

function transcribeStream(params: TranscribeStreamClientParams & { emitVadEvents: true }, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;

function transcribeStream(params: TranscribeStreamClientParams & { parakeetStreamingConfig: { chunkLeftContextMs?: number; chunkMs?: number; chunkRightContextMs?: number; emitEnergyVad?: boolean; emitPartials?: boolean; fifoLen?: number; historyMs?: number; leftContextMs?: number; rightLookaheadMs?: number; spkCacheEnable?: boolean; spkCacheLen?: number; spkCacheUpdatePeriod?: number } }, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;

function transcribeStream(params: TranscribeStreamClientParams & { metadata: true }, options?: RPCOptions): Promise<TranscribeStreamMetadataSession>;

function transcribeStream(params: TranscribeStreamClientParams, options?: RPCOptions): Promise<TranscribeStreamSession>;

function translate(params: TranslateClientParams, options?: RPCOptions): { stats: Promise<{ cacheTokens?: number; decodeTime?: number; encodeTime?: number; timeToFirstToken?: number; tokensPerSecond?: number; totalTime?: number; totalTokens?: number } | undefined>; text: Promise<string>; tokenStream: AsyncGenerator<string> };

// Streaming mode (default)
const result = translate({
  modelId: "modelId",
  text: "Hello world",
  from: "en",
  to: "es"
  modelType: "llm",
});

for await (const token of result.tokenStream) {
  console.log(token);
}

// Non-streaming mode
const response = translate({
  modelId: "modelId",
  text: "Hello world",
  from: "en",
  to: "es"
  modelType: "llm",
  stream: false,
});

console.log(await response.text);

function unloadModel(params: UnloadModelParams): Promise<void>;

function upscale(params: UpscaleClientParams): UpscaleResult;

const modelId = await loadModel(REALESRGAN_X4PLUS_ANIME_6B, {
  modelType: "diffusion",
  modelConfig: { mode: "upscale", upscaler: { tile_size: 128 } },
});
const pngBytes = fs.readFileSync("input.png");
const { outputs, stats } = upscale({ modelId, image: pngBytes, repeats: 2 });
const [upscaledPng] = await outputs;
fs.writeFileSync("upscaled.png", upscaledPng);
console.log(await stats);

function video(params: VideoClientParams): VideoResult;

// Basic txt2vid generation
const { outputs, stats } = video({
  modelId,
  mode: "txt2vid",
  prompt: "a cat surfing a wave at sunset",
  width: 480,
  height: 832,
  video_frames: 17, // must satisfy (4*k + 1)
  fps: 16,
});
const buffers = await outputs;
fs.writeFileSync("output.avi", buffers[0]);

// With progress tracking
const { progressStream, outputs } = video({
  modelId,
  mode: "txt2vid",
  prompt: "a sunset over the ocean",
});
for await (const { step, totalSteps } of progressStream) {
  console.log(`${step}/${totalSteps}`);
}
const buffers = await outputs;

// With control frames (e.g. for guided generation)
const frameA = fs.readFileSync("frame-a.png");
const frameB = fs.readFileSync("frame-b.png");
const { outputs } = video({
  modelId,
  mode: "txt2vid",
  prompt: "smooth transition between scenes",
  control_frames: [frameA, frameB],
});

// Cancellation via requestId
const { requestId, outputs } = video({ modelId, mode: "txt2vid", prompt: "..." });
// ...later
await cancel(requestId);

function vla(params: VlaClientRunParams): Promise<VlaClientRunResult>;

import { loadModel, vla, vlaPreprocessImage, vlaPadState, vlaHparams } from "@qvac/sdk";

const modelId = await loadModel({ modelSrc: "/path/to/smolvla.gguf", modelType: "vla" });
const { hparams } = await vlaHparams({ modelId });
const size = hparams.visionImageSize;
const front = vlaPreprocessImage(frontPixels, frontW, frontH, { size });
const wrist = vlaPreprocessImage(wristPixels, wristW, wristH, { size });
const state = vlaPadState(robotState, hparams.maxStateDim);
const tokens = new Int32Array(hparams.tokenizerMaxLength);
const mask = new Uint8Array(hparams.tokenizerMaxLength);
// ...tokenize the instruction into tokens/mask...
const { actions } = await vla({
  modelId, images: [front, wrist], imgWidth: size, imgHeight: size,
  state, tokens, mask,
});

function vlaHparams(params: { modelId: string }): Promise<{ hparams: VlaHparams; backendName: string | null }>;

function vlaPadState(state: ArrayLike<number>, targetDim: number): Float32Array;

function vlaPreprocessImage(pixels: PixelsInput, width: number, height: number, opts: VlaPreprocessImageOptions): Float32Array;

const profiler: {
  clear(): void;
  disable(): void;
  enable(options?: ProfilerRuntimeOptions): void;
  exportJSON(options?: { includeRecentEvents?: boolean }): ProfilerExport;
  exportSummary(): string;
  exportTable(): string;
  getAggregates(): Record<string, AggregatedStats>;
  getConfig(): ResolvedProfilerConfig;
  isEnabled(): boolean;
  onRecord(callback: (event: ProfilingEvent) => void): () => void;
};

import { profiler } from "@qvac/sdk";

profiler.enable({ mode: "summary" });
// ... run SDK operations ...
console.log(profiler.exportTable());
profiler.disable();