@qvac/sdk 0.9.2 → 0.10.1

package/dist/schemas/completion-stream.js

@@ -1,7 +1,22 @@
 import { z } from "zod";
-import { toolSchema, toolCallSchema, toolCallEventSchema } from "./tools.js";
+import { toolSchema } from "./tools.js";
+import { completionEventSchema } from "./completion-event.js";
+export { completionStatsSchema } from "./completion-event.js";
+/**
+ * Tool-call output dialect. Auto-detected from the model name; pass via
+ * `completion({ toolDialect })` to override.
+ *
+ * Expected raw model output per dialect:
+ * - `"hermes"`:   `<tool_call>{"name":"get_weather","arguments":{"city":"Tokyo"}}</tool_call>`
+ * - `"pythonic"`: `[get_weather(city="Tokyo")]` (optionally `<|tool_call_start|>...<|tool_call_end|>`-wrapped)
+ * - `"json"`:     `{"name":"get_weather","arguments":{"city":"Tokyo"}}` or `{"tool_calls":[{"name":"...","arguments":{...}}]}`
+ * - `"harmony"`:  `<|channel|>commentary to=functions.get_weather <|constrain|>json<|message|>{"city":"Tokyo"}<|call|>`
+ */
+export const toolDialectSchema = z.enum(["hermes", "pythonic", "json", "harmony"]);
 export const attachmentSchema = z.object({
-    path: z.string(),
+    path: z
+        .string()
+        .describe("Absolute or SDK-resolvable path to the attachment file (e.g., image for multimodal models)."),
 });
 const kvCacheSchema = z.union([
     z.boolean(),
@@ -9,46 +24,133 @@ const kvCacheSchema = z.union([
 ]);
 export const generationParamsSchema = z
     .object({
-    temp: z.number().optional(),
-    top_p: z.number().optional(),
-    top_k: z.number().optional(),
-    predict: z.number().optional(),
-    seed: z.number().optional(),
-    frequency_penalty: z.number().optional(),
-    presence_penalty: z.number().optional(),
-    repeat_penalty: z.number().optional(),
+    temp: z
+        .number()
+        .optional()
+        .describe("Sampling temperature (typically 0–2)."),
+    top_p: z
+        .number()
+        .optional()
+        .describe("Top-p (nucleus) sampling cutoff (0–1)."),
+    top_k: z
+        .number()
+        .optional()
+        .describe("Top-k sampling — keep only the top K tokens."),
+    predict: z
+        .number()
+        .optional()
+        .describe("Max tokens to predict. `-1` = until stop token, `-2` = until context filled."),
+    seed: z
+        .number()
+        .optional()
+        .describe("Random seed for reproducibility."),
+    frequency_penalty: z
+        .number()
+        .optional()
+        .describe("Penalty applied to tokens based on frequency so far."),
+    presence_penalty: z
+        .number()
+        .optional()
+        .describe("Penalty applied to tokens that have already appeared."),
+    repeat_penalty: z
+        .number()
+        .optional()
+        .describe("Penalty applied to repeated tokens."),
 })
     .strict();
+const jsonSchemaObjectSchema = z.record(z.string(), z.unknown());
+export const responseFormatSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("text") }).strict(),
+    z.object({ type: z.literal("json_object") }).strict(),
+    z
+        .object({
+        type: z.literal("json_schema"),
+        json_schema: z
+            .object({
+            name: z.string().min(1).describe("Schema identifier; OpenAI-compatibility only — not used by the addon."),
+            description: z
+                .string()
+                .optional()
+                .describe("Free-form schema description. Accepted for OpenAI compatibility only — not forwarded to the addon and does not affect generation."),
+            schema: jsonSchemaObjectSchema.describe("JSON Schema the model output must validate against. Forwarded to the addon as-is and converted to GBNF natively by llama.cpp's `json_schema_to_grammar()`."),
+            strict: z
+                .boolean()
+                .optional()
+                .describe("Accepted for OpenAI compatibility but does NOT trigger OpenAI's auto-tightening semantics (implicit `additionalProperties: false`, all properties required). The schema is forwarded to the addon verbatim, so callers wanting strict validation must encode it explicitly in `schema`."),
+        })
+            .strict(),
+    })
+        .strict(),
+]);
 export const completionParamsSchema = z.object({
-    history: z.array(z.object({
-        role: z.string(),
-        content: z.string(),
-        attachments: z.array(attachmentSchema).optional(),
-    })),
-    modelId: z.string(),
-    kvCache: kvCacheSchema.optional(),
+    history: z
+        .array(z.object({
+        role: z
+            .string()
+            .describe('Message role (e.g., `"user"`, `"assistant"`, `"system"`).'),
+        content: z.string().describe("Message content."),
+        attachments: z
+            .array(attachmentSchema)
+            .optional()
+            .describe("Optional file attachments for multimodal models."),
+    }))
+        .describe("Array of conversation messages sent to the model."),
+    modelId: z
+        .string()
+        .describe("The identifier of the model to use for completion."),
+    kvCache: kvCacheSchema
+        .optional()
+        .describe("KV cache configuration — `true` to auto-generate a cache key from history, a string to use a custom key, or `false`/`undefined` to disable."),
 });
-export const completionClientParamsSchema = completionParamsSchema.extend({
-    tools: z.array(toolSchema).optional(),
-    stream: z.boolean(),
+const completionClientParamsBaseSchema = completionParamsSchema.extend({
+    tools: z
+        .array(toolSchema)
+        .optional()
+        .describe("Optional array of tools (full `Tool` objects or Zod-schema `ToolInput` definitions) the model can call."),
+    stream: z
+        .boolean()
+        .describe("Whether to stream tokens (`true`) or return the complete response once (`false`)."),
     kvCache: kvCacheSchema.optional(),
-    generationParams: generationParamsSchema.optional(),
+    generationParams: generationParamsSchema
+        .optional()
+        .describe("Optional sampling / generation parameters."),
+    captureThinking: z
+        .boolean()
+        .optional()
+        .describe("When `true`, capture and emit reasoning/thinking deltas separately from content deltas; requires a model that frames its thinking output."),
+    emitRawDeltas: z
+        .boolean()
+        .optional()
+        .describe("When `true`, also emit raw per-token deltas in the event stream in addition to normalized `contentDelta` events."),
+    toolDialect: toolDialectSchema
+        .optional()
+        .describe("Override auto-detected tool-call dialect. Use when the SDK's name-based detection picks the wrong parser chain for your model."),
+    responseFormat: responseFormatSchema
+        .optional()
+        .describe("Optional structured-output constraint: `text` (default, free-form), `json_object` (any valid JSON), or `json_schema` (output conforms to the provided JSON Schema). Mutually exclusive with `tools`."),
 });
-export const completionStreamRequestSchema = completionClientParamsSchema.extend({
+function refineNoToolsWithStructuredOutput(data, ctx) {
+    if (data.responseFormat &&
+        data.responseFormat.type !== "text" &&
+        data.tools &&
+        data.tools.length > 0) {
+        ctx.addIssue({
+            code: "custom",
+            message: "responseFormat (json_object/json_schema) cannot be combined with tools; tools already constrain output via their parameter schema.",
+            path: ["responseFormat"],
+        });
+    }
+}
+export const completionClientParamsSchema = completionClientParamsBaseSchema.superRefine(refineNoToolsWithStructuredOutput);
+export const completionStreamRequestSchema = completionClientParamsBaseSchema
+    .extend({
     type: z.literal("completionStream"),
-});
-export const completionStatsSchema = z.object({
-    timeToFirstToken: z.number().optional(),
-    tokensPerSecond: z.number().optional(),
-    cacheTokens: z.number().optional(),
-    backendDevice: z.enum(["cpu", "gpu"]).optional(),
-});
-export const completionStreamResponseSchema = z.object({
+})
+    .superRefine(refineNoToolsWithStructuredOutput);
+export const completionStreamResponseSchema = z
+    .object({
     type: z.literal("completionStream"),
-    token: z.string(),
     done: z.boolean().optional(),
-    stats: completionStatsSchema.optional(),
-    toolCallEvent: toolCallEventSchema.optional(),
-    toolCalls: z.array(toolCallSchema).optional(),
-    error: z.string().optional(),
-});
+    events: z.array(completionEventSchema),
+})
+    .strict();

package/dist/schemas/delegate.d.ts

@@ -1,12 +1,10 @@
 import { z } from "zod";
 export declare const delegateBaseSchema: z.ZodObject<{
-    topic: z.ZodString;
     providerPublicKey: z.ZodString;
     timeout: z.ZodOptional<z.ZodNumber>;
     healthCheckTimeout: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const delegateSchema: z.ZodOptional<z.ZodObject<{
-    topic: z.ZodString;
     providerPublicKey: z.ZodString;
     timeout: z.ZodOptional<z.ZodNumber>;
     healthCheckTimeout: z.ZodOptional<z.ZodNumber>;

package/dist/schemas/delegate.js

@@ -1,13 +1,32 @@
 import { z } from "zod";
+const HYPERSWARM_PUBLIC_KEY_HEX = /^[0-9a-fA-F]{64}$/;
 export const delegateBaseSchema = z.object({
-    topic: z.string(),
-    providerPublicKey: z.string(),
-    timeout: z.number().min(100).optional(),
-    healthCheckTimeout: z.number().min(100).optional(),
+    providerPublicKey: z
+        .string()
+        .regex(HYPERSWARM_PUBLIC_KEY_HEX, "providerPublicKey must be a 64-character hex string (32-byte ed25519 public key)")
+        .describe("Hex-encoded public key of the remote provider to delegate to."),
+    timeout: z
+        .number()
+        .min(100)
+        .optional()
+        .describe("Per-call timeout in milliseconds for the delegated request."),
+    healthCheckTimeout: z
+        .number()
+        .min(100)
+        .optional()
+        .describe("Timeout in milliseconds for the health-check probe before delegating."),
 });
 export const delegateSchema = delegateBaseSchema
     .extend({
-    fallbackToLocal: z.boolean().optional().default(false),
-    forceNewConnection: z.boolean().optional().default(false),
+    fallbackToLocal: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("When `true`, fall back to local execution if the delegated provider is unreachable."),
+    forceNewConnection: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("When `true`, skip any cached delegation connection and open a fresh one."),
 })
     .optional();

package/dist/schemas/download-asset.d.ts

@@ -13,6 +13,7 @@ export declare const downloadAssetOptionsSchema: z.ZodPipe<z.ZodObject<{
         expectedSize: z.ZodOptional<z.ZodNumber>;
         sha256Checksum: z.ZodOptional<z.ZodString>;
         addon: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            embeddings: "embeddings";
             "llamacpp-completion": "llamacpp-completion";
             "whispercpp-transcription": "whispercpp-transcription";
             "llamacpp-embedding": "llamacpp-embedding";
@@ -23,7 +24,6 @@ export declare const downloadAssetOptionsSchema: z.ZodPipe<z.ZodObject<{
             "sdcpp-generation": "sdcpp-generation";
             llm: "llm";
             whisper: "whisper";
-            embeddings: "embeddings";
             nmt: "nmt";
             parakeet: "parakeet";
             tts: "tts";
@@ -45,7 +45,7 @@ export declare const downloadAssetOptionsSchema: z.ZodPipe<z.ZodObject<{
         engine?: string | undefined;
         expectedSize?: number | undefined;
         sha256Checksum?: string | undefined;
-        addon?: "llamacpp-completion" | "whispercpp-transcription" | "llamacpp-embedding" | "nmtcpp-translation" | "onnx-tts" | "parakeet-transcription" | "onnx-ocr" | "sdcpp-generation" | "llm" | "whisper" | "embeddings" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | undefined;
+        addon?: "embeddings" | "llamacpp-completion" | "whispercpp-transcription" | "llamacpp-embedding" | "nmtcpp-translation" | "onnx-tts" | "parakeet-transcription" | "onnx-ocr" | "sdcpp-generation" | "llm" | "whisper" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | undefined;
     };
 }, {
     assetSrc: string | {
@@ -59,7 +59,7 @@ export declare const downloadAssetOptionsSchema: z.ZodPipe<z.ZodObject<{
         engine?: string | undefined;
         expectedSize?: number | undefined;
         sha256Checksum?: string | undefined;
-        addon?: "llamacpp-completion" | "whispercpp-transcription" | "llamacpp-embedding" | "nmtcpp-translation" | "onnx-tts" | "parakeet-transcription" | "onnx-ocr" | "sdcpp-generation" | "llm" | "whisper" | "embeddings" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | undefined;
+        addon?: "embeddings" | "llamacpp-completion" | "whispercpp-transcription" | "llamacpp-embedding" | "nmtcpp-translation" | "onnx-tts" | "parakeet-transcription" | "onnx-ocr" | "sdcpp-generation" | "llm" | "whisper" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | undefined;
     };
     seed?: boolean | undefined;
 }>>;
@@ -76,6 +76,7 @@ export declare const downloadAssetOptionsToRequestSchema: z.ZodPipe<z.ZodObject<
         expectedSize: z.ZodOptional<z.ZodNumber>;
         sha256Checksum: z.ZodOptional<z.ZodString>;
         addon: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            embeddings: "embeddings";
             "llamacpp-completion": "llamacpp-completion";
             "whispercpp-transcription": "whispercpp-transcription";
             "llamacpp-embedding": "llamacpp-embedding";
@@ -86,7 +87,6 @@ export declare const downloadAssetOptionsToRequestSchema: z.ZodPipe<z.ZodObject<
             "sdcpp-generation": "sdcpp-generation";
             llm: "llm";
             whisper: "whisper";
-            embeddings: "embeddings";
             nmt: "nmt";
             parakeet: "parakeet";
             tts: "tts";
@@ -114,7 +114,7 @@ export declare const downloadAssetOptionsToRequestSchema: z.ZodPipe<z.ZodObject<
         engine?: string | undefined;
         expectedSize?: number | undefined;
         sha256Checksum?: string | undefined;
-        addon?: "llamacpp-completion" | "whispercpp-transcription" | "llamacpp-embedding" | "nmtcpp-translation" | "onnx-tts" | "parakeet-transcription" | "onnx-ocr" | "sdcpp-generation" | "llm" | "whisper" | "embeddings" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | undefined;
+        addon?: "embeddings" | "llamacpp-completion" | "whispercpp-transcription" | "llamacpp-embedding" | "nmtcpp-translation" | "onnx-tts" | "parakeet-transcription" | "onnx-ocr" | "sdcpp-generation" | "llm" | "whisper" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | undefined;
     };
     seed?: boolean | undefined;
     onProgress?: unknown;

package/dist/schemas/embed.js

@@ -1,28 +1,40 @@
 import { z } from "zod";
 export const embedParamsSchema = z.object({
-    modelId: z.string(),
-    text: z.union([
+    modelId: z.string().describe("The identifier of the embedding model to use"),
+    text: z
+        .union([
         z.string().min(1, "Text cannot be empty"),
         z
             .array(z.string().min(1, "Text cannot be empty"))
             .min(1, "Text array cannot be empty"),
-    ]),
+    ])
+        .describe("The input text(s) to embed. A single string returns `number[]`; an array returns `number[][]`."),
 });
 export const embedRequestSchema = embedParamsSchema.extend({
     type: z.literal("embed"),
 });
 export const embedStatsSchema = z.object({
-    totalTime: z.number().optional(),
-    tokensPerSecond: z.number().optional(),
-    totalTokens: z.number().optional(),
-    backendDevice: z.enum(["cpu", "gpu"]).optional(),
+    totalTime: z
+        .number()
+        .optional()
+        .describe("Total embedding time in milliseconds"),
+    tokensPerSecond: z
+        .number()
+        .optional()
+        .describe("Tokens processed per second"),
+    totalTokens: z.number().optional().describe("Total tokens processed"),
+    backendDevice: z
+        .enum(["cpu", "gpu"])
+        .optional()
+        .describe("Compute backend used for inference"),
 });
 export const embedResponseSchema = z.object({
     type: z.literal("embed"),
     success: z.boolean(),
     embedding: z
         .union([z.array(z.number()), z.array(z.array(z.number()))])
-        .default([]),
-    stats: embedStatsSchema.optional(),
+        .default([])
+        .describe("The embedding vector(s). Single `number[]` when `text` is a string; `number[][]` when `text` is an array."),
+    stats: embedStatsSchema.optional().describe("Performance statistics"),
     error: z.string().optional(),
 });

package/dist/schemas/engine-addon-map.d.ts

@@ -1,5 +1,15 @@
 import { type ModelRegistryEngine, type ModelRegistryEntryAddon } from "./registry";
-export declare const ENGINE_TO_ADDON: Record<ModelRegistryEngine, ModelRegistryEntryAddon>;
+export declare const ENGINE_TO_ADDON: {
+    readonly "llamacpp-completion": "llm";
+    readonly "whispercpp-transcription": "whisper";
+    readonly "llamacpp-embedding": "embeddings";
+    readonly "nmtcpp-translation": "nmt";
+    readonly "onnx-tts": "tts";
+    readonly "onnx-ocr": "ocr";
+    readonly "parakeet-transcription": "parakeet";
+    readonly "sdcpp-generation": "diffusion";
+    readonly "onnx-vad": "vad";
+};
 export declare function resolveCanonicalEngine(engine: string): ModelRegistryEngine | null;
 export declare function getAddonFromEngine(engine: ModelRegistryEngine): ModelRegistryEntryAddon;
 //# sourceMappingURL=engine-addon-map.d.ts.map

package/dist/schemas/engine-addon-map.js

@@ -1,8 +1,8 @@
 import { ModelType } from "./model-types.js";
 import { ADDON_DIFFUSION, ADDON_EMBEDDING, ADDON_LLM, ADDON_NMT, ADDON_OCR, ADDON_PARAKEET, ADDON_TTS, ADDON_WHISPER, } from "./plugin.js";
 import { modelRegistryEngineSchema, } from "./registry.js";
-// Canonical engine → addon mapping (exhaustive).
-// TypeScript enforces that every ModelRegistryEngine has an entry.
+// Canonical engine → addon mapping (exhaustive). `as const` preserves
+// per-key literals so the addon can be derived from the engine at the type level.
 export const ENGINE_TO_ADDON = {
     [ModelType.llamacppCompletion]: "llm",
     [ModelType.whispercppTranscription]: "whisper",

package/dist/schemas/get-loaded-model-info.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+export declare const getLoadedModelInfoParamsSchema: z.ZodObject<{
+    modelId: z.ZodString;
+}, z.core.$strip>;
+export declare const getLoadedModelInfoRequestSchema: z.ZodObject<{
+    modelId: z.ZodString;
+    type: z.ZodLiteral<"getLoadedModelInfo">;
+}, z.core.$strip>;
+export declare const loadedModelInfoSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    modelId: z.ZodString;
+    isDelegated: z.ZodLiteral<false>;
+    modelType: z.ZodString;
+    handlers: z.ZodArray<z.ZodString>;
+    displayName: z.ZodOptional<z.ZodString>;
+    addonPackage: z.ZodOptional<z.ZodString>;
+    loadedAt: z.ZodCoercedDate<unknown>;
+    name: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    modelId: z.ZodString;
+    isDelegated: z.ZodLiteral<true>;
+    handlers: z.ZodArray<z.ZodString>;
+    providerInfo: z.ZodObject<{
+        providerPublicKey: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>], "isDelegated">;
+export declare const getLoadedModelInfoResponseSchema: z.ZodObject<{
+    type: z.ZodLiteral<"getLoadedModelInfo">;
+    info: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        modelId: z.ZodString;
+        isDelegated: z.ZodLiteral<false>;
+        modelType: z.ZodString;
+        handlers: z.ZodArray<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        addonPackage: z.ZodOptional<z.ZodString>;
+        loadedAt: z.ZodCoercedDate<unknown>;
+        name: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        modelId: z.ZodString;
+        isDelegated: z.ZodLiteral<true>;
+        handlers: z.ZodArray<z.ZodString>;
+        providerInfo: z.ZodObject<{
+            providerPublicKey: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>], "isDelegated">;
+}, z.core.$strip>;
+export type GetLoadedModelInfoParams = z.input<typeof getLoadedModelInfoParamsSchema>;
+export type GetLoadedModelInfoRequest = z.infer<typeof getLoadedModelInfoRequestSchema>;
+export type GetLoadedModelInfoResponse = z.infer<typeof getLoadedModelInfoResponseSchema>;
+export type LoadedModelInfo = z.infer<typeof loadedModelInfoSchema>;
+//# sourceMappingURL=get-loaded-model-info.d.ts.map

package/dist/schemas/get-loaded-model-info.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export const getLoadedModelInfoParamsSchema = z.object({
+    modelId: z.string(),
+});
+export const getLoadedModelInfoRequestSchema = getLoadedModelInfoParamsSchema.extend({
+    type: z.literal("getLoadedModelInfo"),
+});
+const delegatedProviderInfoSchema = z.object({
+    providerPublicKey: z.string(),
+});
+/**
+ * Loaded local model: routing plugin known on this node, so modelType +
+ * handler vocabulary are authoritative.
+ */
+const localLoadedModelInfoSchema = z.object({
+    modelId: z.string(),
+    isDelegated: z.literal(false),
+    modelType: z.string(),
+    handlers: z.array(z.string()),
+    displayName: z.string().optional(),
+    addonPackage: z.string().optional(),
+    loadedAt: z.coerce.date(),
+    name: z.string().optional(),
+    path: z.string().optional(),
+});
+/**
+ * Loaded delegated model: this node only stores routing info, so `modelType`,
+ * `displayName`, `addonPackage`, `loadedAt`, `name`, and `path` are absent,
+ * and `handlers` is always empty.
+ */
+const delegatedLoadedModelInfoSchema = z.object({
+    modelId: z.string(),
+    isDelegated: z.literal(true),
+    handlers: z.array(z.string()),
+    providerInfo: delegatedProviderInfoSchema,
+});
+export const loadedModelInfoSchema = z.discriminatedUnion("isDelegated", [
+    localLoadedModelInfoSchema,
+    delegatedLoadedModelInfoSchema,
+]);
+export const getLoadedModelInfoResponseSchema = z.object({
+    type: z.literal("getLoadedModelInfo"),
+    info: loadedModelInfoSchema,
+});

package/dist/schemas/get-model-info.d.ts

@@ -35,9 +35,9 @@ export declare const modelInfoSchema: z.ZodObject<{
     expectedSize: z.ZodNumber;
     sha256Checksum: z.ZodString;
     addon: z.ZodEnum<{
+        embeddings: "embeddings";
         llm: "llm";
         whisper: "whisper";
-        embeddings: "embeddings";
         nmt: "nmt";
         parakeet: "parakeet";
         tts: "tts";
@@ -82,9 +82,9 @@ export declare const getModelInfoResponseSchema: z.ZodObject<{
         expectedSize: z.ZodNumber;
         sha256Checksum: z.ZodString;
         addon: z.ZodEnum<{
+            embeddings: "embeddings";
             llm: "llm";
             whisper: "whisper";
-            embeddings: "embeddings";
             nmt: "nmt";
             parakeet: "parakeet";
             tts: "tts";