@qvac/sdk 0.18.0 → 0.18.2

package/NOTICE

@@ -666,7 +666,7 @@ JavaScript Dependencies
     https://github.com/tetherto/qvac
   @qvac/diagnostics@0.1.2
     https://github.com/tetherto/qvac
-  @qvac/diffusion-cpp@0.17.0
+  @qvac/diffusion-cpp@0.18.0
     https://github.com/tetherto/qvac
   @qvac/embed-llamacpp@0.34.0
     https://github.com/tetherto/qvac

package/dist/schemas/llamacpp-config.js

@@ -15,85 +15,129 @@ export const VERBOSITY = {
 const verbositySchema = z.enum(VERBOSITY);
 // Base schema - validates types, all fields optional (for client-side validation)
 export const llmConfigBaseSchema = z.object({
-    ctx_size: z.number().optional(),
-    temp: z.number().min(0).max(2).optional(),
-    top_p: z.number().min(0).max(1).optional(),
-    top_k: z.number().int().min(0).max(128).optional(),
-    seed: z.number().optional(),
-    gpu_layers: z.number().optional(),
-    lora: z.string().optional(),
-    device: z.string().optional(),
+    ctx_size: z
+        .number()
+        .optional()
+        .describe("Context window size in tokens; `0` uses the model's trained context length. Default 1024."),
+    temp: z.number().min(0).max(2).optional().describe('Sampling temperature (0–2). Default 0.8.'),
+    top_p: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe('Top-p (nucleus) sampling cutoff (0–1). Default 0.9.'),
+    top_k: z
+        .number()
+        .int()
+        .min(0)
+        .max(128)
+        .optional()
+        .describe('Top-k sampling — keep only the top K tokens (0–128). Default 40.'),
+    seed: z.number().optional().describe('Sampling RNG seed; `-1` (default) picks a random seed.'),
+    gpu_layers: z
+        .number()
+        .optional()
+        .describe('Number of model layers to offload to the GPU. Default 99 (offload all).'),
+    lora: z
+        .string()
+        .optional()
+        .describe('Path to a LoRA adapter file to apply on top of the base model.'),
+    device: z
+        .string()
+        .optional()
+        .describe("Device to run inference on: `'gpu'` or `'cpu'`. Default `'gpu'`."),
     predict: z
         .union([
         z.literal(-1), // special: until stop token
         z.literal(-2), // special: until context filled
         z.number().int().min(1) // positive integer: fixed token count
     ])
-        .optional(),
-    /** JS-side only: seeds conversation history. Never forwarded to the C++ addon. */
-    system_prompt: z.string().optional(),
-    no_mmap: z.boolean().optional(),
-    verbosity: verbositySchema.optional(),
-    presence_penalty: z.number().optional(),
-    frequency_penalty: z.number().optional(),
-    repeat_penalty: z.number().optional(),
-    stop_sequences: z.array(z.string()).optional(),
-    n_discarded: z.number().optional(),
-    /**
-     * Concurrent sequence slots for continuous batching. Defaults to 1
-     * (sequential, batching disabled); values >= 2 enable batched decoding in
-     * @qvac/llm-llamacpp.
-     */
-    parallel: z.number().int().min(1).optional(),
-    tools: z.boolean().optional(),
-    'cache-type-k': z.string().optional(),
-    'cache-type-v': z.string().optional(),
-    'main-gpu': z.union([z.number().int().min(0), z.enum(['integrated', 'dedicated'])]).optional(),
-    'split-mode': z.enum(['none', 'layer', 'row']).optional(),
-    'tensor-split': z.string().optional(),
-    /**
-     * Writable directory for OpenCL kernel binary cache. Required on Android
-     * for fast GPU startup.
-     */
-    openclCacheDir: z.string().optional(),
-    /**
-     * Reasoning channel token budget. `-1` = unrestricted, `0` = disabled, any
-     * positive integer caps the reasoning channel at that many tokens (the
-     * sampler force-emits the closing think tag once the budget is exhausted).
-     */
-    reasoning_budget: z.number().int().min(-1).max(REASONING_BUDGET_MAX).optional(),
-    projectionModelSrc: modelSrcInputSchema.optional(),
-    /**
-     * Qwen3.5-VL multi-tile image encoding mode (multimodal models only):
-     *   - `"sequential"` (default): encode image tiles one tile at a time.
-     *   - `"batched"`: encode all tiles in a single batched pass.
-     *   - `"disabled"`: no multi-tile encoding (single tile).
-     * Ignored by text-only models. Default is `"sequential"`.
-     */
-    image_tile_mode: z.enum(['disabled', 'batched', 'sequential']).optional(),
-    /**
-     * idefics3-style image preprocessing rule (multimodal models only):
-     *   - `"on"`: round the image's long side up to a whole number of slices and
-     *     cap it, so an image smaller than the cap keeps its own resolution and
-     *     becomes far fewer slices.
-     *   - `"off"`: always stretch the long side to the cap.
-     * When unset, the model's own GGUF value is used. Ignored with a warning by
-     * models that do not use idefics3-style preprocessing. Changes the number of
-     * image tokens, and therefore both accuracy and encode time, so a checkpoint
-     * whose GGUF omits the key needs this set to preprocess correctly.
-     */
-    image_no_upscale: z.enum(['on', 'off']).optional(),
-    /**
-     * Run the multimodal projector (mmproj / vision encoder) on the GPU
-     * (multimodal models only). `true` forces GPU, `false` forces CPU. When
-     * unset, the llm-llamacpp addon auto-selects the backend per device class:
-     * GPU on desktop/iOS and positively-detected Android Adreno 800+ GPUs; CPU on
-     * every other Android GPU — Mali, Adreno <800, and any tier that can't be
-     * detected (only Adreno 800+ is benchmarked to encode the projector faster on
-     * the GPU than the CPU). Only honoured when the model itself runs on a GPU
-     * backend — ignored with a warning on CPU.
-     */
-    'mmproj-use-gpu': z.boolean().optional()
+        .optional()
+        .describe('Max tokens to predict. `-1` = until stop token, `-2` = until context filled.'),
+    system_prompt: z
+        .string()
+        .optional()
+        .describe("Seeds conversation history on the JS side only; never forwarded to the addon. Default `'You are a helpful assistant.'`"),
+    no_mmap: z.boolean().optional().describe('Disable memory-mapped model loading. Default false.'),
+    verbosity: verbositySchema
+        .optional()
+        .describe('Native log verbosity: `0`=ERROR, `1`=WARN, `2`=INFO, `3`=DEBUG. Default 0.'),
+    presence_penalty: z
+        .number()
+        .optional()
+        .describe('Presence penalty applied to tokens that have already appeared. Default 0.'),
+    frequency_penalty: z
+        .number()
+        .optional()
+        .describe('Frequency penalty applied to tokens by their frequency so far. Default 0.'),
+    repeat_penalty: z
+        .number()
+        .optional()
+        .describe('Repetition penalty applied to repeated tokens. Default 1.1.'),
+    stop_sequences: z
+        .array(z.string())
+        .optional()
+        .describe('Strings that stop generation when produced (forwarded to the addon as `reverse_prompt`).'),
+    n_discarded: z
+        .number()
+        .optional()
+        .describe('Tokens to discard from the front of the context when it fills (sliding window); `0` (default) disables sliding. In batch mode clamped to the per-slot window (`ctx_size / parallel`).'),
+    parallel: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Concurrent sequence slots for continuous batching (1–256). Default 1 (sequential, batching off); `>= 2` enables batched decoding and splits the KV cache evenly across slots.'),
+    tools: z
+        .boolean()
+        .optional()
+        .describe("Enable tool calling via the model's jinja chat template. Default false."),
+    'cache-type-k': z
+        .string()
+        .optional()
+        .describe('KV-cache key quantization type (`f16`, `f32`, `bf16`, `q8_0`, `q4_0`, …). Unset selects a backend-safe default.'),
+    'cache-type-v': z
+        .string()
+        .optional()
+        .describe('KV-cache value quantization type; quantizing the value cache requires flash attention. Unset selects a backend-safe default.'),
+    'main-gpu': z
+        .union([z.number().int().min(0), z.enum(['integrated', 'dedicated'])])
+        .optional()
+        .describe("GPU to use on multi-GPU systems: a device index, or `'integrated'`/`'dedicated'` to restrict selection to that class."),
+    'split-mode': z
+        .enum(['none', 'layer', 'row'])
+        .optional()
+        .describe("How to split the model across GPUs: `'none'` (default, single GPU), `'layer'` (pipeline parallelism), or `'row'` (tensor parallelism)."),
+    'tensor-split': z
+        .string()
+        .optional()
+        .describe("Proportions for distributing layers/rows across GPUs, e.g. `'1,1'` (equal) or `'3,1'` (75/25)."),
+    openclCacheDir: z
+        .string()
+        .optional()
+        .describe('Writable directory for the OpenCL kernel binary cache; required on Android for fast GPU startup.'),
+    reasoning_budget: z
+        .number()
+        .int()
+        .min(-1)
+        .max(REASONING_BUDGET_MAX)
+        .optional()
+        .describe('Reasoning-channel token budget. `-1` (default) unrestricted, `0` disables it, any positive integer caps the reasoning channel at that many tokens (the closing think tag is force-emitted once the budget is spent).'),
+    projectionModelSrc: modelSrcInputSchema
+        .optional()
+        .describe('Multimodal projection (mmproj / vision encoder) model source; multimodal models only.'),
+    image_tile_mode: z
+        .enum(['disabled', 'batched', 'sequential'])
+        .optional()
+        .describe("Qwen3.5-VL multi-tile image encoding mode (multimodal models only): `'sequential'` (default) encodes image tiles one at a time, `'batched'` encodes all tiles in a single batched pass, `'disabled'` does no multi-tile encoding (single tile). Ignored by text-only models."),
+    image_no_upscale: z
+        .enum(['on', 'off'])
+        .optional()
+        .describe("idefics3-style image preprocessing rule (multimodal models only): `'on'` rounds the image's long side up to a whole number of slices and caps it, so an image smaller than the cap keeps its own resolution and becomes far fewer slices; `'off'` always stretches the long side to the cap. When unset, the model's own GGUF value is used; ignored with a warning by models that do not use idefics3-style preprocessing. Changes the number of image tokens (and therefore both accuracy and encode time), so a checkpoint whose GGUF omits the key needs this set to preprocess correctly."),
+    'mmproj-use-gpu': z
+        .boolean()
+        .optional()
+        .describe('Run the multimodal projector (mmproj / vision encoder) on the GPU (multimodal models only). `true` forces GPU, `false` forces CPU. When unset, the backend is auto-selected per device class: GPU on desktop/iOS and Android Adreno 800+; CPU on every other Android GPU (Arm Mali, Adreno <800, and undetectable Adreno tiers), with the LLM layers still on the GPU. Only honoured when the model itself runs on a GPU backend — ignored with a warning on CPU.')
 });
 // Default values - typed as partial of the config
 export const LLM_CONFIG_DEFAULTS = {
@@ -110,22 +154,57 @@ export const llmConfigSchema = llmConfigBaseSchema.transform((data) => ({
 }));
 // Base schema - validates types, all fields optional (for client-side validation)
 export const embedConfigBaseSchema = z.object({
-    gpuLayers: z.number().int().optional(),
-    device: z.enum(['gpu', 'cpu']).optional(),
-    batchSize: z.number().int().min(1).optional(),
-    pooling: z.enum(['none', 'mean', 'cls', 'last', 'rank']).optional(),
-    attention: z.enum(['causal', 'non-causal']).optional(),
-    embdNormalize: z.number().int().optional(),
-    flashAttention: z.enum(['on', 'off', 'auto']).optional(),
-    mainGpu: z.union([z.number().int().min(0), z.enum(['integrated', 'dedicated'])]).optional(),
-    splitMode: z.enum(['none', 'layer', 'row']).optional(),
-    tensorSplit: z.string().optional(),
-    verbosity: verbositySchema.optional(),
-    /**
-     * Writable directory for OpenCL kernel binary cache. Required on Android
-     * for fast GPU startup.
-     */
-    openclCacheDir: z.string().optional()
+    gpuLayers: z
+        .number()
+        .int()
+        .optional()
+        .describe('Number of model layers to offload to the GPU. Default 99 (offload all).'),
+    device: z
+        .enum(['gpu', 'cpu'])
+        .optional()
+        .describe("Device to run inference on: `'gpu'` or `'cpu'`. Default `'gpu'`."),
+    batchSize: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Tokens processed per batch (input throughput). Default 1024.'),
+    pooling: z
+        .enum(['none', 'mean', 'cls', 'last', 'rank'])
+        .optional()
+        .describe("Pooling strategy collapsing token embeddings into one sequence vector: `'none'`, `'mean'`, `'cls'`, `'last'`, or `'rank'`. Unset uses the model default."),
+    attention: z
+        .enum(['causal', 'non-causal'])
+        .optional()
+        .describe("Attention type: `'causal'` or `'non-causal'`. Unset uses the model default."),
+    embdNormalize: z
+        .number()
+        .int()
+        .optional()
+        .describe('Embedding normalization: `-1` none, `0` max-abs int16, `1` taxicab, `2` euclidean, `>2` p-norm. Default 2 (euclidean).'),
+    flashAttention: z
+        .enum(['on', 'off', 'auto'])
+        .optional()
+        .describe("Flash attention: `'on'`, `'off'`, or `'auto'`. Default `'auto'`."),
+    mainGpu: z
+        .union([z.number().int().min(0), z.enum(['integrated', 'dedicated'])])
+        .optional()
+        .describe("GPU to use on multi-GPU systems: a device index, or `'integrated'`/`'dedicated'` to restrict selection to that class."),
+    splitMode: z
+        .enum(['none', 'layer', 'row'])
+        .optional()
+        .describe("How to split the model across GPUs: `'none'` (default, single GPU), `'layer'` (pipeline parallelism), or `'row'` (tensor parallelism)."),
+    tensorSplit: z
+        .string()
+        .optional()
+        .describe("Proportions for distributing layers/rows across GPUs, e.g. `'1,1'` (equal) or `'3,1'` (75/25)."),
+    verbosity: verbositySchema
+        .optional()
+        .describe('Native log verbosity: `0`=ERROR, `1`=WARN, `2`=INFO, `3`=DEBUG. Default 0.'),
+    openclCacheDir: z
+        .string()
+        .optional()
+        .describe('Writable directory for the OpenCL kernel binary cache; required on Android for fast GPU startup.')
 });
 // Default values - typed as partial of the config
 export const EMBED_CONFIG_DEFAULTS = {

package/dist/schemas/public.d.ts

@@ -0,0 +1,3 @@
+export { llmConfigBaseSchema as llamacppCompletionConfigSchema, embedConfigBaseSchema as llamacppEmbeddingConfigSchema, type LlmConfigInput as LlamacppCompletionConfig, type EmbedConfigInput as LlamacppEmbeddingConfig } from './llamacpp-config.js';
+export { modelSrcInputSchema as modelSourceSchema, type ModelSrcInput as ModelSource } from './model-src-utils.js';
+//# sourceMappingURL=public.d.ts.map

package/dist/schemas/public.js

@@ -0,0 +1,6 @@
+// Public schema surface for `@qvac/sdk/schemas`. Stable, end-user-facing names
+// (aliased from the internal schemas) so consumers such as the CLI can import a
+// model's `modelConfig` schema and read its field descriptions without
+// depending on internal identifiers.
+export { llmConfigBaseSchema as llamacppCompletionConfigSchema, embedConfigBaseSchema as llamacppEmbeddingConfigSchema } from './llamacpp-config.js';
+export { modelSrcInputSchema as modelSourceSchema } from './model-src-utils.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/sdk",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -124,6 +124,11 @@
       "types": "./dist/schemas/plugin.d.ts",
       "import": "./dist/schemas/plugin.js"
     },
+    "./schemas": {
+      "types": "./dist/schemas/public.d.ts",
+      "import": "./dist/schemas/public.js",
+      "require": "./dist/schemas/public.js"
+    },
     "./expo-plugin": "./dist/expo/plugins/index.js",
     "./electron-forge": {
       "require": "./electron-forge/index.cjs",
@@ -211,7 +216,7 @@
     "@qvac/bci-whispercpp": "^0.7.1",
     "@qvac/classification-ggml": "^0.20.0",
     "@qvac/decoder-audio": "^0.5.0",
-    "@qvac/diffusion-cpp": "^0.17.0",
+    "@qvac/diffusion-cpp": "^0.18.0",
     "@qvac/embed-llamacpp": "^0.34.0",
     "@qvac/error": "^0.1.1",
     "@qvac/langdetect-text": "^0.1.2",