API Summary — v0.9.1 (latest)

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

// Cancel inference
await cancel({ operation: "inference", modelId: "model-123" });

// Pause download (preserves partial file for automatic resume)
await cancel({ operation: "downloadAsset", downloadKey: "download-key" });

// Cancel download completely (deletes partial file)
await cancel({ operation: "downloadAsset", downloadKey: "download-key", clearCache: true });

// Cancel delegated remote download
await cancel({
  operation: "downloadAsset",
  downloadKey: "download-key",
  delegate: { topic: "topicHex", providerPublicKey: "peerHex" },
});

// Cancel RAG operation on default workspace
await cancel({ operation: "rag" });

// Cancel RAG operation on specific workspace
await cancel({ operation: "rag", workspace: "my-workspace" });

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 });

// 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>;

// 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}%`);
  }
});

function embed(params: { modelId: string; text: string }, options?: RPCOptions): Promise<{ embedding: number[]; stats?: EmbedStats }>;

function embed(params: { modelId: string; text: string[] }, options?: RPCOptions): Promise<{ embedding: number[][]; stats?: EmbedStats }>;

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

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

function getModelInfo(params: GetModelInfoParams): Promise<{ actualSize?: number; addon: "llm" | "whisper" | "embeddings" | "nmt" | "vad" | "tts" | "ocr" | "parakeet" | "diffusion" | "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; topic: string } }): Promise<HeartbeatResponse>;

// Check if a delegated provider is online
try {
  await heartbeat({
    delegate: { topic: "topicHex", 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: LoadModelOptions, rpcOptions?: RPCOptions): Promise<string>;

// Local file path - absolute path
const localModelId = await loadModel({
  modelSrc: "/home/user/models/llama-7b.gguf",
  modelType: "llm",
  modelConfig: { contextSize: 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: { contextSize: 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: ReloadConfigOptions, rpcOptions?: RPCOptions): Promise<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<{ processed: RagSaveEmbeddingsResult[]; droppedIndices: number[] }>;

// 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<RagReindexResult>;

// 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<RagSaveEmbeddingsResult[]>;

// 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(params: StopProvideParams): Promise<{ error?: string; success: boolean; type: "stopProvide" }>;

function suspend(): Promise<void>;

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

function textToSpeech(params: TtsClientParams, options?: RPCOptions): { buffer: Promise<number[]>; bufferStream: AsyncGenerator<number>; done: Promise<boolean> };

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

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

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>;

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();