@qvac/sdk 0.18.2 → 0.19.0

package/dist/schemas/completion-stream.js

@@ -1,236 +0,0 @@
-import { z } from 'zod';
-import { toolSchema } from './tools.js';
-import { completionEventSchema } from './completion-event.js';
-import { REASONING_BUDGET_MAX } from './llamacpp-config.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|>`
- * - `"qwen35"`:   `<tool_call><function=NAME><parameter=KEY>VALUE</parameter></function></tool_call>`
- * - `"gemma4"`:   `<|tool_call>call:NAME{key:<|"|>val<|"|>,...}<tool_call|>`
- * - `"dsml"`:     `<｜DSML｜tool_calls><｜DSML｜invoke name="NAME"><｜DSML｜parameter name="KEY" string="true">VALUE</｜DSML｜parameter></｜DSML｜invoke></｜DSML｜tool_calls>`
- *                 (DeepSeek Markup Language, emitted by DeepSeek V3.2 / V4)
- */
-export const toolDialectSchema = z.enum([
-    'hermes',
-    'pythonic',
-    'json',
-    'harmony',
-    'qwen35',
-    'gemma4',
-    'dsml'
-]);
-export const attachmentSchema = z.object({
-    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(),
-    z.string().min(1, 'KV cache key cannot be empty string')
-]);
-export const generationParamsSchema = z
-    .object({
-    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.'),
-    reasoning_budget: z
-        .number()
-        .int()
-        .min(-1)
-        .max(REASONING_BUDGET_MAX)
-        .optional()
-        .describe("Per-request reasoning channel budget. `-1` keeps the model's reasoning channel on; `0` disables it for this request; any positive integer caps the reasoning channel at that many tokens. Equivalent to the load-time `reasoning_budget` config but scoped to a single `run()` call; the prior value is restored afterwards."),
-    remove_thinking_from_context: z
-        .boolean()
-        .optional()
-        .describe('When the model emits a reasoning block during generation (e.g. `<think>...</think>` for the Qwen3 family, `<|channel>thought ... <channel|>` for Gemma 4), drop those tokens from the KV cache at end-of-generation so subsequent turns do not accumulate reasoning history. Defaults to `false`, except the Qwen3 reasoning family (Qwen3, Qwen3.5, Qwen3.6, including MoE variants), which defaults to `true`. No-op for models without a recognised reasoning channel. Supported on recurrent / hybrid-SSM models (e.g. Qwen3.5) via a state snapshot and replay when the reasoning close marker is a single token; on such a model with a multi-token close marker, enabling this fails with an error.')
-})
-    .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().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.')
-});
-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()
-        .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`.'),
-    requestId: z
-        .string()
-        .min(1)
-        .optional()
-        .describe('Stable identifier for this in-flight request, generated by the client at call time (opaque token, UUIDv4 when available). Surfaced on the `CompletionRun` result so callers can target it with `cancel({ requestId })`. Optional on the wire so legacy clients keep working — the server falls back to a server-generated id when the field is missing. Note: cancel-by-requestId only takes effect once the server has begun the request, so a cancel issued in the same tick as `completion()` may arrive before the request is registered.')
-});
-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')
-})
-    .superRefine(refineNoToolsWithStructuredOutput);
-export const completionStreamResponseSchema = z
-    .object({
-    type: z.literal('completionStream'),
-    done: z.boolean().optional(),
-    events: z.array(completionEventSchema)
-})
-    .strict();
-// ============================================
-// Worker-orchestrated completion (duplex)
-// ============================================
-export const completionOrchestrateRequestSchema = completionClientParamsBaseSchema
-    .extend({
-    type: z.literal('completionOrchestrate'),
-    maxToolTurns: z
-        .number()
-        .int()
-        .min(1)
-        .max(32)
-        .optional()
-        .describe('Upper bound on generation turns the worker will run before ending the ' +
-        'loop with `stopReason: "maxToolTurns"`. Each turn is one completion ' +
-        'pass; a turn that requests tool calls consumes callbacks and starts ' +
-        'the next turn. Defaults to 8.')
-})
-    .superRefine(refineNoToolsWithStructuredOutput);
-/**
- * Downstream frame of the orchestrated completion duplex stream. Exactly one
- * payload field is set per frame:
- *
- * - `events` — pass-through of the inner completion turn's events (with
- *   `turn` identifying which generation pass they belong to).
- * - `toolCallback` — the worker is asking the CLIENT to run a tool. The
- *   client executes its registered handler and writes a JSON line
- *   (`toolCallbackResultSchema`) up the request stream. The worker blocks
- *   this run (not the socket) until the matching `callId` arrives.
- * - `done` — terminal frame; the loop ended (final answer produced, error,
- *   cancellation, or the `maxToolTurns` cap).
- *
- * Only a LOCAL worker may emit `toolCallback`: tool handlers execute code on
- * the client machine, so a remote delegate streaming through this shape must
- * never trigger them.
- */
-export const completionOrchestrateResponseSchema = z
-    .object({
-    type: z.literal('completionOrchestrate'),
-    turn: z.number().int().nonnegative().optional(),
-    events: z.array(completionEventSchema).optional(),
-    toolCallback: z
-        .object({
-        callId: z.string().describe('Correlates the upstream result line to this request.'),
-        name: z.string(),
-        arguments: z.record(z.string(), z.unknown())
-    })
-        .optional(),
-    done: z.boolean().optional(),
-    stopReason: z
-        .literal('maxToolTurns')
-        .optional()
-        .describe('Set on the terminal `done` frame only when the loop stopped because it ' +
-        'hit `maxToolTurns` (the model still wanted a tool). Absent on a natural ' +
-        'finish, so the caller can tell a truncated run from a completed one.')
-})
-    .strict();
-/**
- * Upstream JSON line the client writes after running a tool callback.
- * Newline-delimited on the duplex request stream, after the initial request
- * payload. `error` reports a handler failure; the worker forwards it to the
- * model as the tool result so the loop can recover or finish.
- */
-export const toolCallbackResultSchema = z.object({
-    callId: z.string(),
-    result: z.unknown().optional(),
-    error: z.string().optional()
-});

package/dist/schemas/constants-registry.d.ts

@@ -1,83 +0,0 @@
-import { z } from 'zod';
-/**
- * Every public constant `enum` from index.ts that downstream (non-JS)
- * client generators should get as a real, named type instead of a
- * hardcoded string/number. `build-contract.ts` merges each of these
- * directly into `schema.json`'s `$defs` (same `z.toJSONSchema` call, same
- * generator run as every request/response type), tagged with an
- * `x-enum-varnames` hint so datamodel-code-generator preserves the
- * original key names instead of slugging them from the bare value — plain
- * JSON Schema `enum:` only carries values, not names, so without that hint
- * `PluginId`/`Verbosity` (whose keys aren't derivable from their values)
- * would lose their names entirely.
- *
- * A constant only reaches other languages if it's registered here. See
- * `.cursor/rules/sdk/public-constants-contract.mdc`: any new public
- * constant meant for downstream SDKs must be a `z.enum(...)` added here,
- * not just a bare `export const` in its own schema file — otherwise it
- * silently never leaves JS.
- *
- * Scoped to name→value maps (`z.enum`) only. A standalone scalar constant
- * (e.g. `VLA_DEFAULT_IMAGE_SIZE`) has no natural JSON Schema representation
- * as a plain value — a `const`-only schema generates an awkward
- * `RootModel[Literal[...]]` wrapper class in Python, not a usable
- * constant — so scalars aren't covered by this registry.
- */
-export declare const constantsRegistry: {
-    readonly ModelType: z.ZodEnum<{
-        readonly llamacppCompletion: "llamacpp-completion";
-        readonly whispercppTranscription: "whispercpp-transcription";
-        readonly bciWhispercppTranscription: "bci-whispercpp-transcription";
-        readonly llamacppEmbedding: "llamacpp-embedding";
-        readonly nmtcppTranslation: "nmtcpp-translation";
-        readonly onnxTts: "onnx-tts";
-        readonly ttsGgml: "tts-ggml";
-        readonly parakeetTranscription: "parakeet-transcription";
-        readonly ggmlOcr: "ggml-ocr";
-        readonly sdcppGeneration: "sdcpp-generation";
-        readonly audiogenGgml: "audiogen-ggml";
-        readonly ggmlVla: "ggml-vla";
-        readonly ggmlClassification: "ggml-classification";
-    }>;
-    readonly Verbosity: z.ZodEnum<{
-        readonly ERROR: 0;
-        readonly WARN: 1;
-        readonly INFO: 2;
-        readonly DEBUG: 3;
-    }>;
-    readonly PluginId: z.ZodEnum<{
-        readonly LLM: "@qvac/sdk/llamacpp-completion/plugin";
-        readonly EMBEDDING: "@qvac/sdk/llamacpp-embedding/plugin";
-        readonly WHISPER: "@qvac/sdk/whispercpp-transcription/plugin";
-        readonly BCI: "@qvac/sdk/bci-whispercpp-transcription/plugin";
-        readonly NMT: "@qvac/sdk/nmtcpp-translation/plugin";
-        readonly TTS: "@qvac/sdk/tts-ggml/plugin";
-        readonly OCR: "@qvac/sdk/ggml-ocr/plugin";
-        readonly DIFFUSION: "@qvac/sdk/sdcpp-generation/plugin";
-        readonly AUDIOGEN: "@qvac/sdk/audiogen-ggml/plugin";
-        readonly VLA: "@qvac/sdk/ggml-vla/plugin";
-        readonly CLASSIFICATION: "@qvac/sdk/ggml-classification/plugin";
-    }>;
-    readonly SupportedAudioFormat: z.ZodEnum<{
-        [k: string]: string;
-    }>;
-    readonly TtsPace: z.ZodEnum<{
-        [k: string]: string;
-    }>;
-    readonly TtsCosyvoice3Emotion: z.ZodEnum<{
-        [k: string]: string;
-    }>;
-    readonly TtsCosyvoice3InstructDialect: z.ZodEnum<{
-        [k: string]: string;
-    }>;
-    readonly TtsCosyvoice3InstructVolume: z.ZodEnum<{
-        [k: string]: string;
-    }>;
-    readonly TtsCosyvoice3InstructStyle: z.ZodEnum<{
-        [k: string]: string;
-    }>;
-    readonly AudioGenTaskType: z.ZodEnum<{
-        [k: string]: string;
-    }>;
-};
-//# sourceMappingURL=constants-registry.d.ts.map

package/dist/schemas/constants-registry.js

@@ -1,65 +0,0 @@
-import { z } from 'zod';
-import { ModelType } from './model-types.js';
-import { VERBOSITY } from './llamacpp-config.js';
-import { PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_AUDIOGEN, PLUGIN_VLA, PLUGIN_CLASSIFICATION } from './plugin.js';
-import { SUPPORTED_AUDIO_FORMATS } from '../constants/audio.js';
-import { AUDIOGEN_TASK_TYPES } from './audio-gen.js';
-import { TTS_PACES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES } from './text-to-speech.js';
-// Uppercases each vocabulary value into an identifier-safe varname (e.g.
-// 'slow' -> 'SLOW', 'cover-nofsq' -> 'COVER_NOFSQ'), mirroring the
-// SupportedAudioFormat derivation so names can't drift from the single
-// source-of-truth array.
-function enumFromVocabulary(values) {
-    return z.enum(Object.fromEntries(values.map((value) => [value.toUpperCase().replace(/-/g, '_'), value])));
-}
-/**
- * Every public constant `enum` from index.ts that downstream (non-JS)
- * client generators should get as a real, named type instead of a
- * hardcoded string/number. `build-contract.ts` merges each of these
- * directly into `schema.json`'s `$defs` (same `z.toJSONSchema` call, same
- * generator run as every request/response type), tagged with an
- * `x-enum-varnames` hint so datamodel-code-generator preserves the
- * original key names instead of slugging them from the bare value — plain
- * JSON Schema `enum:` only carries values, not names, so without that hint
- * `PluginId`/`Verbosity` (whose keys aren't derivable from their values)
- * would lose their names entirely.
- *
- * A constant only reaches other languages if it's registered here. See
- * `.cursor/rules/sdk/public-constants-contract.mdc`: any new public
- * constant meant for downstream SDKs must be a `z.enum(...)` added here,
- * not just a bare `export const` in its own schema file — otherwise it
- * silently never leaves JS.
- *
- * Scoped to name→value maps (`z.enum`) only. A standalone scalar constant
- * (e.g. `VLA_DEFAULT_IMAGE_SIZE`) has no natural JSON Schema representation
- * as a plain value — a `const`-only schema generates an awkward
- * `RootModel[Literal[...]]` wrapper class in Python, not a usable
- * constant — so scalars aren't covered by this registry.
- */
-export const constantsRegistry = {
-    ModelType: z.enum(ModelType),
-    Verbosity: z.enum(VERBOSITY),
-    PluginId: z.enum({
-        LLM: PLUGIN_LLM,
-        EMBEDDING: PLUGIN_EMBEDDING,
-        WHISPER: PLUGIN_WHISPER,
-        BCI: PLUGIN_BCI,
-        NMT: PLUGIN_NMT,
-        TTS: PLUGIN_TTS,
-        OCR: PLUGIN_OCR,
-        DIFFUSION: PLUGIN_DIFFUSION,
-        AUDIOGEN: PLUGIN_AUDIOGEN,
-        VLA: PLUGIN_VLA,
-        CLASSIFICATION: PLUGIN_CLASSIFICATION
-    }),
-    // Derived from SUPPORTED_AUDIO_FORMATS itself (e.g. '.mp3' -> 'MP3') rather
-    // than a hand-written record, so the varnames can't drift from the one
-    // source of truth every other consumer of SUPPORTED_AUDIO_FORMATS shares.
-    SupportedAudioFormat: z.enum(Object.fromEntries(SUPPORTED_AUDIO_FORMATS.map((ext) => [ext.slice(1).toUpperCase(), ext]))),
-    TtsPace: enumFromVocabulary(TTS_PACES),
-    TtsCosyvoice3Emotion: enumFromVocabulary(TTS_COSYVOICE3_EMOTIONS),
-    TtsCosyvoice3InstructDialect: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_DIALECTS),
-    TtsCosyvoice3InstructVolume: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_VOLUMES),
-    TtsCosyvoice3InstructStyle: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_STYLES),
-    AudioGenTaskType: enumFromVocabulary(AUDIOGEN_TASK_TYPES)
-};

package/dist/schemas/delegate.d.ts

@@ -1,16 +0,0 @@
-import { z } from 'zod';
-export declare const delegateBaseSchema: z.ZodObject<{
-    providerPublicKey: z.ZodString;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    healthCheckTimeout: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export declare const delegateSchema: z.ZodOptional<z.ZodObject<{
-    providerPublicKey: z.ZodString;
-    timeout: z.ZodOptional<z.ZodNumber>;
-    healthCheckTimeout: z.ZodOptional<z.ZodNumber>;
-    fallbackToLocal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    forceNewConnection: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>>;
-export type DelegateBase = z.infer<typeof delegateBaseSchema>;
-export type Delegate = z.infer<typeof delegateSchema>;
-//# sourceMappingURL=delegate.d.ts.map

package/dist/schemas/delegate.js

@@ -1,32 +0,0 @@
-import { z } from 'zod';
-const HYPERSWARM_PUBLIC_KEY_HEX = /^[0-9a-fA-F]{64}$/;
-export const delegateBaseSchema = z.object({
-    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)
-        .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/delete-cache.d.ts

@@ -1,17 +0,0 @@
-import { z } from 'zod';
-export declare const deleteCacheRequestSchema: z.ZodUnion<readonly [z.ZodObject<{
-    type: z.ZodLiteral<"deleteCache">;
-    all: z.ZodLiteral<true>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"deleteCache">;
-    kvCacheKey: z.ZodString;
-    modelId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>]>;
-export declare const deleteCacheResponseSchema: z.ZodObject<{
-    type: z.ZodLiteral<"deleteCache">;
-    success: z.ZodBoolean;
-    error: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type DeleteCacheRequest = z.infer<typeof deleteCacheRequestSchema>;
-export type DeleteCacheResponse = z.infer<typeof deleteCacheResponseSchema>;
-//# sourceMappingURL=delete-cache.d.ts.map

package/dist/schemas/delete-cache.js

@@ -1,21 +0,0 @@
-import { z } from 'zod';
-export const deleteCacheRequestSchema = z.union([
-    z
-        .object({
-        type: z.literal('deleteCache'),
-        all: z.literal(true)
-    })
-        .meta({ title: 'DeleteCacheAllRequest' }),
-    z
-        .object({
-        type: z.literal('deleteCache'),
-        kvCacheKey: z.string(),
-        modelId: z.string().optional()
-    })
-        .meta({ title: 'DeleteCacheKvEntryRequest' })
-]);
-export const deleteCacheResponseSchema = z.object({
-    type: z.literal('deleteCache'),
-    success: z.boolean(),
-    error: z.string().optional()
-});