API Summary — v0.8.0

Auto-generated from .d.ts declarations and TSDoc comments.

For per-parameter and per-field details, hover symbols in your IDE or open node_modules/@qvac/sdk/dist. This page is intentionally a high-level index.

Fields shown: description, signature, throws, examples, deprecation. Fields intentionally omitted: parameter descriptions, return field descriptions (covered by IDE hover and .d.ts declarations).

Scope: 31 functions in packages/sdk/client/api/ plus the profiler object.

Functions

cancel

Cancels an ongoing operation.

Signature:

function cancel(params): Promise<void>;

Throws:

• INVALID_RESPONSE_TYPE — Response type does not match expected "cancel"
• CANCEL_FAILED — The server reports cancellation failure

completion

Generates completion from a language model based on conversation history.

Signature:

function completion(params): {
  tokenStream: AsyncGenerator<string>;
  toolCallStream: AsyncGenerator<ToolCallEvent>;
  text: Promise<string>;
  toolCalls: Promise<ToolCallWithCall[]>;
  stats: Promise<CompletionStats | undefined>;
};

Throws:

• INVALID_TOOLS_ARRAY — Invalid tools array provided
• INVALID_TOOL_SCHEMA — A tool has an invalid schema

deleteCache

Deletes KV cache files.

Signature:

function deleteCache(params): Promise<{ success: boolean }>;

Throws:

• INVALID_DELETE_CACHE_PARAMS — Neither all nor kvCacheKey was provided
• DELETE_CACHE_FAILED — The server reports cache deletion failure

downloadAsset

Downloads an asset (model file) without loading it into memory.

Signature:

function downloadAsset(options, rpcOptions?): Promise<string>;

Throws:

• DOWNLOAD_ASSET_FAILED — The download operation fails
• STREAM_ENDED_WITHOUT_RESPONSE — Streaming ends without a final response (when using onProgress)
• INVALID_RESPONSE_TYPE — Response type does not match expected "downloadAsset"

embed

Generates embeddings for a single text using a specified model.

Signature:

function embed(params: { modelId: string; text: string }): Promise<number[]>;
function embed(params: { modelId: string; text: string[] }): Promise<number[][]>;

Throws:

• INVALID_RESPONSE_TYPE — Response type does not match expected "embed"

getModelInfo

Retrieves detailed information about a model, including cache status and loaded instances.

Signature:

function getModelInfo(params): Promise<ModelInfo>;

Throws:

• INVALID_RESPONSE_TYPE — Response type does not match expected "getModelInfo"

invokePlugin

Invoke a non-streaming plugin handler.

Signature:

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

Throws:

• INVALID_RESPONSE_TYPE — Response type does not match expected "pluginInvoke"

invokePluginStream

Invoke a streaming plugin handler.

Signature:

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

Throws:

• INVALID_RESPONSE_TYPE — A chunk's type does not match expected "pluginInvokeStream"

loadModel

Loads a machine learning model from a local path, remote URL, or Hyperdrive key.

Signature:

// Load new model
function loadModel(options: LoadModelOptions, rpcOptions?: RPCOptions): Promise<string>;

// Hot-reload config on an already-loaded model
function loadModel(options: ReloadConfigOptions, rpcOptions?: RPCOptions): Promise<string>;

Throws:

• MODEL_LOAD_FAILED — Model loading fails
• STREAM_ENDED_WITHOUT_RESPONSE — Streaming ends without a final response (when using onProgress)
• INVALID_RESPONSE_TYPE — Response type does not match expected "loadModel"

loggingStream

Opens a logging stream to receive real-time logs.

Signature:

function loggingStream(params): AsyncGenerator<LoggingStreamResponse>;

Throws:

• INVALID_RESPONSE_TYPE — A chunk's type does not match expected "loggingStream"

modelRegistryGetModel

Retrieves a single model entry from the QVAC model registry by path and source.

Signature:

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

Throws:

• QVAC_MODEL_REGISTRY_QUERY_FAILED — The registry query fails or model is not found

modelRegistryList

Returns all available models from the QVAC distributed model registry.

Signature:

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

Throws:

• QVAC_MODEL_REGISTRY_QUERY_FAILED — The registry query fails

modelRegistrySearch

Searches the QVAC model registry with optional filters.

Signature:

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

Throws:

• QVAC_MODEL_REGISTRY_QUERY_FAILED — The registry query fails

ocr

Performs Optical Character Recognition (OCR) on an image to extract text.

Signature:

function ocr(params): {
  blockStream: AsyncGenerator<OCRTextBlock[]>;
  blocks: Promise<OCRTextBlock[]>;
  stats: Promise<OCRStats | undefined>;
};

ping

Sends a ping request to the server and returns the pong response.

Signature:

function ping(): Promise<{ type: "pong"; number: number }>;

ragChunk

Chunks documents into smaller pieces for embedding.

Signature:

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

Throws:

• RAG_CHUNK_FAILED — The chunking operation fails

ragCloseWorkspace

Closes a RAG workspace, releasing in-memory resources (Corestore, HyperDB adapter, RAG instance).

Signature:

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

Throws:

• RAG_WORKSPACE_CLOSE_FAILED — The close operation fails

ragDeleteEmbeddings

Deletes document embeddings from the RAG vector database.

Signature:

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

Throws:

• RAG_DELETE_FAILED — The delete operation fails or workspace doesn't exist

ragDeleteWorkspace

Deletes a RAG workspace and all its data.

Signature:

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

Throws:

• RAG_DELETE_FAILED — The workspace doesn't exist or is currently loaded

ragIngest

Ingests documents into the RAG vector database.

Signature:

function ragIngest(params, options?): Promise<{ processed: RagSaveEmbeddingsResult[]; droppedIndices: number[] }>;

Throws:

• RAG_SAVE_FAILED — The ingestion operation fails
• STREAM_ENDED_WITHOUT_RESPONSE — Streaming ends unexpectedly (when using onProgress)

ragListWorkspaces

Lists all RAG workspaces with their open status.

Signature:

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

Throws:

• RAG_LIST_WORKSPACES_FAILED — The operation fails

ragReindex

Reindexes the RAG database to optimize search performance.

Signature:

function ragReindex(params, options?): Promise<RagReindexResult>;

Throws:

• RAG_SAVE_FAILED — The reindex operation fails or workspace doesn't exist
• STREAM_ENDED_WITHOUT_RESPONSE — Streaming ends unexpectedly (when using onProgress)

ragSaveEmbeddings

Saves pre-embedded documents to the RAG vector database.

Signature:

function ragSaveEmbeddings(params, options?): Promise<RagSaveEmbeddingsResult[]>;

Throws:

• RAG_SAVE_FAILED — The save operation fails
• STREAM_ENDED_WITHOUT_RESPONSE — Streaming ends unexpectedly (when using onProgress)

ragSearch

Searches for similar documents in the RAG vector database.

Signature:

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

Throws:

• RAG_SEARCH_FAILED — The search operation fails

startQVACProvider

Starts a provider service that offers QVAC capabilities to remote peers.

Signature:

function startQVACProvider(params): Promise<object>;

Throws:

• INVALID_RESPONSE_TYPE — Response type does not match expected "provide"
• PROVIDER_START_FAILED — The server reports provider start failure

stopQVACProvider

Stops a running provider service and leaves the specified topic.

Signature:

function stopQVACProvider(params): Promise<object>;

Throws:

• INVALID_RESPONSE_TYPE — Response type does not match expected "stopProvide"
• PROVIDER_STOP_FAILED — The server reports provider stop failure

textToSpeech

Converts text to speech audio.

Signature:

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

transcribe

Provides a simple interface for transcribing audio by collecting all streaming results into a single string response.

Signature:

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

Throws:

• TRANSCRIPTION_FAILED — Transcription fails

Example:

const text = await transcribe({
  modelId: "whisper-model",
  audioChunk: "/path/to/audio.wav",
});
console.log(text);

transcribeStream

Streams audio transcription results in real-time, yielding text chunks as they become available from the model.

Signature:

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

Throws:

• TRANSCRIPTION_FAILED — Transcription fails

Example:

const stream = transcribeStream({
  modelId: "whisper-model",
  audioChunk: "/path/to/audio.wav",
});

for await (const textChunk of stream) {
  process.stdout.write(textChunk);
}

translate

Translates text from one language to another using a specified translation model.

Signature:

function translate(params): {
  tokenStream: AsyncGenerator<string>;
  text: Promise<string>;
  stats: Promise<TranslationStats | undefined>;
};

Throws:

• TRANSLATION_FAILED — Translation fails

unloadModel

Unloads a previously loaded model from the server.

Signature:

function unloadModel(params): Promise<void>;

Throws:

• INVALID_RESPONSE_TYPE — Response type does not match expected "unloadModel"
• MODEL_UNLOAD_FAILED — The server reports unload failure

Objects

profiler

Singleton object that collects and exports profiling data for SDK operations.

Shape:

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

Methods:

• enable() — Enables profiling and resets aggregated data
• disable() — Disables profiling
• isEnabled() — Returns whether profiling is currently enabled
• exportJSON() — Exports profiling data as a structured JSON object
• exportTable() — Exports aggregated stats as a formatted ASCII table
• exportSummary() — Exports a human-readable summary string
• onRecord() — Registers a listener for profiling events; returns an unsubscribe function
• getConfig() — Returns the current effective profiler configuration
• getAggregates() — Returns all aggregated stats keyed by operation name
• clear() — Clears all aggregated data and recent events

Errors

Public error codes thrown across the SDK. Catch via instanceof QvacErrorBase and read error.code / error.cause. Code ranges: 50,001–52,000 (client) and 52,001–54,000 (server).

Client errors

Server errors