@qvac/sdk 0.18.2 → 0.19.0

package/dist/server/bare/runtime/with-request-context.d.ts

@@ -1,22 +0,0 @@
-import type { Logger } from '../../../logging/types.js';
-export interface RequestLogContext {
-    requestId: string;
-    kind: string;
-    modelId: string | undefined;
-}
-/**
- * Wraps `logger` so every emit is prefixed with
- * `[request-lifecycle <kind> requestId=<id> modelId=<modelId>] `
- * (the `modelId=...` segment is dropped when absent). The wrapper is a
- * thin shim: `setLevel` / `getLevel` / `addTransport` / `setConsoleOutput`
- * pass through to the underlying logger, and transport callbacks receive
- * the prefixed message.
- *
- * @example
- *   await using ctx = await registry.begin({ requestId, kind: "completion", modelId });
- *   const log = withRequestContext(getServerLogger(), ctx);
- *   log.info("decoding token 7");
- *   // → "[request-lifecycle completion requestId=<id> modelId=<id>] decoding token 7"
- */
-export declare function withRequestContext(logger: Logger, ctx: RequestLogContext): Logger;
-//# sourceMappingURL=with-request-context.d.ts.map

package/dist/server/bare/runtime/with-request-context.js

@@ -1,53 +0,0 @@
-/**
- * Wraps `logger` so every emit is prefixed with
- * `[request-lifecycle <kind> requestId=<id> modelId=<modelId>] `
- * (the `modelId=...` segment is dropped when absent). The wrapper is a
- * thin shim: `setLevel` / `getLevel` / `addTransport` / `setConsoleOutput`
- * pass through to the underlying logger, and transport callbacks receive
- * the prefixed message.
- *
- * @example
- *   await using ctx = await registry.begin({ requestId, kind: "completion", modelId });
- *   const log = withRequestContext(getServerLogger(), ctx);
- *   log.info("decoding token 7");
- *   // → "[request-lifecycle completion requestId=<id> modelId=<id>] decoding token 7"
- */
-export function withRequestContext(logger, ctx) {
-    const prefix = ctx.modelId !== undefined
-        ? `[request-lifecycle ${ctx.kind} requestId=${ctx.requestId} modelId=${ctx.modelId}] `
-        : `[request-lifecycle ${ctx.kind} requestId=${ctx.requestId}] `;
-    function pick(method) {
-        switch (method) {
-            case 'error':
-                return logger.error;
-            case 'warn':
-                return logger.warn;
-            case 'info':
-                return logger.info;
-            case 'debug':
-                return logger.debug;
-            case 'trace':
-                return logger.trace;
-        }
-    }
-    function emit(method, args) {
-        const sink = pick(method);
-        if (args.length === 0) {
-            sink(prefix);
-            return;
-        }
-        const [first, ...rest] = args;
-        sink(prefix + String(first), ...rest);
-    }
-    return {
-        error: (...args) => emit('error', args),
-        warn: (...args) => emit('warn', args),
-        info: (...args) => emit('info', args),
-        debug: (...args) => emit('debug', args),
-        trace: (...args) => emit('trace', args),
-        setLevel: (level) => logger.setLevel(level),
-        getLevel: () => logger.getLevel(),
-        addTransport: (transport) => logger.addTransport(transport),
-        setConsoleOutput: (enabled) => logger.setConsoleOutput(enabled)
-    };
-}

package/dist/server/bare/runtime-lifecycle.d.ts

@@ -1,38 +0,0 @@
-import type { LifecycleState, Request } from '../../schemas/index.js';
-export interface SuspendableSwarm {
-    readonly suspended: boolean;
-    suspend(): Promise<void>;
-    resume(): Promise<void>;
-}
-export interface SuspendableStore {
-    suspend(): Promise<void>;
-    resume(): Promise<void>;
-}
-interface ResourceMeta {
-    label: string;
-    createdAt: number;
-}
-type ResumeListener = () => void;
-/**
- * Register a callback fired after the runtime returns to "active". Lets in-flight
- * work (e.g. an HTTP download whose socket died while backgrounded) recover the
- * instant `resume()` runs instead of waiting for a timeout. Returns an
- * unregister function — callers MUST call it when their work finishes so the
- * listener doesn't leak into the next operation.
- */
-export declare function onResume(listener: ResumeListener): () => void;
-export declare function registerSwarm(swarm: SuspendableSwarm, meta: ResourceMeta): void;
-export declare function unregisterSwarm(swarm: SuspendableSwarm): void;
-export declare function registerCorestore(store: SuspendableStore, meta: ResourceMeta): void;
-export declare function unregisterCorestore(store: SuspendableStore): void;
-export declare function getLifecycleState(): LifecycleState;
-export declare function assertLifecycleAllowed(request: Request): void;
-export declare function getRegisteredResourceCounts(): {
-    swarms: number;
-    stores: number;
-};
-export declare function resetLifecycleState(): void;
-export declare function suspendRuntime(): Promise<void>;
-export declare function resumeRuntime(): Promise<void>;
-export {};
-//# sourceMappingURL=runtime-lifecycle.d.ts.map

package/dist/server/bare/runtime-lifecycle.js

@@ -1,163 +0,0 @@
-import { getServerLogger } from '../../logging/index.js';
-import { LifecycleOperationBlockedError } from '../../utils/errors-server.js';
-const logger = getServerLogger();
-const LIFECYCLE_ALLOWED_TYPES = new Set(['suspend', 'resume', 'state']);
-const swarms = new Map();
-const stores = new Map();
-const resumeListeners = new Set();
-let state = 'active';
-let transitionPromise = null;
-/**
- * Register a callback fired after the runtime returns to "active". Lets in-flight
- * work (e.g. an HTTP download whose socket died while backgrounded) recover the
- * instant `resume()` runs instead of waiting for a timeout. Returns an
- * unregister function — callers MUST call it when their work finishes so the
- * listener doesn't leak into the next operation.
- */
-export function onResume(listener) {
-    resumeListeners.add(listener);
-    return () => resumeListeners.delete(listener);
-}
-function notifyResume() {
-    for (const listener of Array.from(resumeListeners)) {
-        try {
-            listener();
-        }
-        catch (error) {
-            logger.error('Lifecycle: onResume listener threw:', error);
-        }
-    }
-}
-export function registerSwarm(swarm, meta) {
-    swarms.set(swarm, meta);
-    logger.debug(`Lifecycle: registered swarm [${meta.label}]`);
-}
-export function unregisterSwarm(swarm) {
-    const meta = swarms.get(swarm);
-    swarms.delete(swarm);
-    if (meta) {
-        logger.debug(`Lifecycle: unregistered swarm [${meta.label}]`);
-    }
-}
-export function registerCorestore(store, meta) {
-    stores.set(store, meta);
-    logger.debug(`Lifecycle: registered corestore [${meta.label}]`);
-}
-export function unregisterCorestore(store) {
-    const meta = stores.get(store);
-    stores.delete(store);
-    if (meta) {
-        logger.debug(`Lifecycle: unregistered corestore [${meta.label}]`);
-    }
-}
-export function getLifecycleState() {
-    return state;
-}
-export function assertLifecycleAllowed(request) {
-    if (state === 'active' || LIFECYCLE_ALLOWED_TYPES.has(request.type))
-        return;
-    throw new LifecycleOperationBlockedError(request.type, state);
-}
-export function getRegisteredResourceCounts() {
-    return { swarms: swarms.size, stores: stores.size };
-}
-export function resetLifecycleState() {
-    swarms.clear();
-    stores.clear();
-    resumeListeners.clear();
-    state = 'active';
-    transitionPromise = null;
-}
-async function runPhase(snapshot, liveSet, fn, phaseLabel) {
-    const errors = [];
-    for (const [resource, meta] of snapshot) {
-        try {
-            await fn(resource);
-            logger.debug(`Lifecycle: ${phaseLabel} [${meta.label}] OK`);
-        }
-        catch (error) {
-            if (!liveSet.has(resource))
-                continue;
-            logger.error(`Lifecycle: ${phaseLabel} [${meta.label}] failed:`, error);
-            errors.push(new Error(`${meta.label}: ${String(error)}`));
-        }
-    }
-    if (errors.length > 0) {
-        throw new AggregateError(errors, `Lifecycle ${phaseLabel} phase failed`);
-    }
-}
-export async function suspendRuntime() {
-    if (state === 'suspended')
-        return;
-    if (state === 'suspending' && transitionPromise)
-        return transitionPromise;
-    // Opposite transition in flight: wait for it, then re-evaluate
-    if (state === 'resuming' && transitionPromise) {
-        await transitionPromise;
-        return suspendRuntime();
-    }
-    state = 'suspending';
-    logger.info(`⏸️ Suspending runtime (${stores.size} stores, ${swarms.size} swarms)`);
-    transitionPromise = (async () => {
-        const swarmSnapshot = Array.from(swarms.entries());
-        const storeSnapshot = Array.from(stores.entries());
-        await runPhase(storeSnapshot, stores, async (store) => {
-            await store.suspend();
-        }, 'suspend-store');
-        await runPhase(swarmSnapshot, swarms, async (swarm) => {
-            if (!swarm.suspended)
-                await swarm.suspend();
-        }, 'suspend-swarm');
-    })()
-        .then(() => {
-        state = 'suspended';
-        logger.info('⏸️ Runtime suspended');
-    })
-        .catch((error) => {
-        // Partial failure: commit to target so recovery resume() can repair
-        // instead of leaving state as "suspending" which blocks all future calls.
-        state = 'suspended';
-        logger.error('⏸️ Runtime suspend partially failed, state committed for recovery');
-        throw error;
-    })
-        .finally(() => {
-        transitionPromise = null;
-    });
-    return transitionPromise;
-}
-export async function resumeRuntime() {
-    if (state === 'active')
-        return;
-    if (state === 'resuming' && transitionPromise)
-        return transitionPromise;
-    if (state === 'suspending' && transitionPromise) {
-        await transitionPromise;
-        return resumeRuntime();
-    }
-    state = 'resuming';
-    logger.info(`▶️ Resuming runtime (${swarms.size} swarms, ${stores.size} stores)`);
-    transitionPromise = (async () => {
-        const swarmSnapshot = Array.from(swarms.entries());
-        const storeSnapshot = Array.from(stores.entries());
-        await runPhase(swarmSnapshot, swarms, async (swarm) => {
-            await swarm.resume();
-        }, 'resume-swarm');
-        await runPhase(storeSnapshot, stores, async (store) => {
-            await store.resume();
-        }, 'resume-store');
-    })()
-        .then(() => {
-        state = 'active';
-        logger.info('▶️ Runtime resumed');
-        notifyResume();
-    })
-        .catch((error) => {
-        state = 'suspended';
-        logger.error('▶️ Runtime resume partially failed, staying suspended for retry');
-        throw error;
-    })
-        .finally(() => {
-        transitionPromise = null;
-    });
-    return transitionPromise;
-}

package/dist/server/bare/types/addon-responses.d.ts

@@ -1,51 +0,0 @@
-import type ASRGgml from '@qvac/asr-ggml';
-import type TranslationNmtcpp from '@qvac/translation-nmtcpp';
-export interface LlmStats {
-    TTFT?: number;
-    TPS?: number;
-    CacheTokens?: number;
-    promptTokens?: number;
-    generatedTokens?: number;
-    avgConcurrentSeq?: number;
-    backendDevice?: 'cpu' | 'gpu';
-    stopReason?: 'none' | 'eos' | 'antiprompt' | 'predictionLimit' | 'sequenceLimit' | 'contextOverflow';
-}
-export interface LlmResponse {
-    stats?: LlmStats;
-    iterate(): AsyncIterable<string>;
-}
-export type NmtStats = TranslationNmtcpp.RuntimeStats;
-export type NmtResponse = TranslationNmtcpp.TranslationResponse;
-export interface TtsStats {
-    audioDurationMs?: number;
-    totalSamples?: number;
-    enhancerBackendDevice?: number;
-    enhancerBackendId?: number;
-}
-export interface TtsResponse {
-    stats?: TtsStats;
-    iterate(): AsyncIterable<{
-        outputArray: ArrayLike<number>;
-    }>;
-}
-export interface EmbedStats {
-    total_time_ms?: number;
-    tokens_per_second?: number;
-    total_tokens?: number;
-    backendDevice?: 'cpu' | 'gpu';
-    context_size?: number;
-}
-export interface EmbedResponse {
-    stats?: EmbedStats;
-    await(): Promise<Float32Array[][]>;
-}
-export type TranscribeStats = Partial<ASRGgml.WhisperRuntimeStats & ASRGgml.ParakeetRuntimeStats>;
-export type TranscribeAddonSegment = ASRGgml.TranscriptionSegment;
-export type TranscribeAddonVadEvent = ASRGgml.VadEvent;
-export type TranscribeAddonEndOfTurnEvent = ASRGgml.EndOfTurnEvent;
-export type TranscribeAddonOutput = ASRGgml.ASRStreamOutput;
-export interface TranscribeResponse {
-    stats?: TranscribeStats;
-    iterate(): AsyncIterable<TranscribeAddonOutput>;
-}
-//# sourceMappingURL=addon-responses.d.ts.map

package/dist/server/bare/types/addon-responses.js

@@ -1 +0,0 @@
-export {};

package/dist/server/bare/utils/asr-events.d.ts

@@ -1,15 +0,0 @@
-import type ASRGgml from '@qvac/asr-ggml';
-export declare function isVadEvent(event: ASRGgml.ASRStreamOutput): event is ASRGgml.VadEvent;
-export declare function isEndOfTurnEvent(event: ASRGgml.ASRStreamOutput): event is ASRGgml.EndOfTurnEvent;
-export declare function toVadStateEvent(event: ASRGgml.VadEvent): {
-    speaking: boolean;
-    probability: number;
-};
-export declare function toEndOfTurnEvent(event: ASRGgml.EndOfTurnEvent): {
-    source: "parakeet";
-    silenceDurationMs?: never;
-} | {
-    source: "whisper";
-    silenceDurationMs: number;
-} | null;
-//# sourceMappingURL=asr-events.d.ts.map

package/dist/server/bare/utils/asr-events.js

@@ -1,30 +0,0 @@
-export function isVadEvent(event) {
-    return (!Array.isArray(event) &&
-        event.type === 'vad' &&
-        typeof event.speaking === 'boolean' &&
-        typeof event.score === 'number' &&
-        (event.source === 'silero' || event.source === 'energy'));
-}
-export function isEndOfTurnEvent(event) {
-    return (!Array.isArray(event) &&
-        event.type === 'endOfTurn' &&
-        (event.source === 'vad-silence' || event.source === 'model-eou'));
-}
-export function toVadStateEvent(event) {
-    return {
-        speaking: event.speaking,
-        probability: event.score
-    };
-}
-export function toEndOfTurnEvent(event) {
-    if (event.source === 'model-eou') {
-        return { source: 'parakeet' };
-    }
-    if (event.silenceDurationMs === undefined) {
-        return null;
-    }
-    return {
-        source: 'whisper',
-        silenceDurationMs: event.silenceDurationMs
-    };
-}

package/dist/server/bare/utils/audio-input.d.ts

@@ -1,10 +0,0 @@
-import { Readable } from 'bare-stream';
-import type { AudioInput, AudioFormat } from '../../../schemas/index.js';
-/**
- * Converts an AudioInput (base64 or filePath) into a Readable stream,
- * decoding the audio when necessary.
- *
- * Shared by all transcription plugins (Whisper, Parakeet, etc.).
- */
-export declare function createAudioStream(audioChunk: AudioInput, audioFormat: AudioFormat): Promise<Readable>;
-//# sourceMappingURL=audio-input.d.ts.map

package/dist/server/bare/utils/audio-input.js

@@ -1,33 +0,0 @@
-import { Readable } from 'bare-stream';
-import fs from 'bare-fs';
-import { needsDecoding, decodeAudioToStream } from '../../../server/utils/audio/decoder.js';
-import { AudioFileNotFoundError, InvalidAudioChunkError } from '../../../utils/errors-server.js';
-/**
- * Converts an AudioInput (base64 or filePath) into a Readable stream,
- * decoding the audio when necessary.
- *
- * Shared by all transcription plugins (Whisper, Parakeet, etc.).
- */
-export async function createAudioStream(audioChunk, audioFormat) {
-    switch (audioChunk.type) {
-        case 'base64': {
-            const audioBuffer = Buffer.from(audioChunk.value, 'base64');
-            return Readable.from([audioBuffer]);
-        }
-        case 'filePath': {
-            const filePath = audioChunk.value;
-            try {
-                fs.accessSync(filePath);
-            }
-            catch (error) {
-                throw new AudioFileNotFoundError(filePath, error);
-            }
-            if (needsDecoding(filePath)) {
-                return decodeAudioToStream(filePath, audioFormat);
-            }
-            return fs.createReadStream(filePath);
-        }
-        default:
-            throw new InvalidAudioChunkError();
-    }
-}

package/dist/server/bare/utils/transcribe-metadata.d.ts

@@ -1,21 +0,0 @@
-import { type TranscribeSegment } from '../../../schemas/index.js';
-export interface WhisperAddonSegment {
-    text: string;
-    start?: number;
-    end?: number;
-    toAppend?: boolean;
-    id?: number;
-}
-/**
- * Normalize a native whisper-addon segment to the SDK-level `TranscribeSegment`
- * shape exposed to callers: seconds → milliseconds, `toAppend` → `append`,
- * and defaults for optional fields.
- */
-export declare function toTranscribeSegment(chunk: WhisperAddonSegment): TranscribeSegment;
-/**
- * Guard used by transcription ops when the caller opts into `metadata: true`.
- * Only the whisper engine emits per-segment metadata; any other engine
- * requesting metadata is rejected with `TranscriptionFailedError`.
- */
-export declare function assertMetadataSupported(modelId: string, engineType: string, metadata: boolean | undefined): void;
-//# sourceMappingURL=transcribe-metadata.d.ts.map

package/dist/server/bare/utils/transcribe-metadata.js

@@ -1,28 +0,0 @@
-import { ModelType } from '../../../schemas/index.js';
-import { TranscriptionFailedError } from '../../../utils/errors-server.js';
-/**
- * Normalize a native whisper-addon segment to the SDK-level `TranscribeSegment`
- * shape exposed to callers: seconds → milliseconds, `toAppend` → `append`,
- * and defaults for optional fields.
- */
-export function toTranscribeSegment(chunk) {
-    return {
-        text: chunk.text,
-        startMs: (chunk.start ?? 0) * 1000,
-        endMs: (chunk.end ?? 0) * 1000,
-        append: chunk.toAppend ?? false,
-        id: chunk.id ?? 0
-    };
-}
-/**
- * Guard used by transcription ops when the caller opts into `metadata: true`.
- * Only the whisper engine emits per-segment metadata; any other engine
- * requesting metadata is rejected with `TranscriptionFailedError`.
- */
-export function assertMetadataSupported(modelId, engineType, metadata) {
-    if (!metadata)
-        return;
-    if (engineType !== ModelType.whispercppTranscription) {
-        throw new TranscriptionFailedError(`metadata mode is not supported on model ${modelId} (engine: ${engineType || 'unknown'}); only the whisper engine supports metadata`);
-    }
-}

package/dist/server/bare/utils/tts-stats.d.ts

@@ -1,26 +0,0 @@
-import type { TtsStats } from '../../../schemas/index.js';
-/**
- * Shared types and utilities for TTS operations.
- * Used by both text-to-speech.ts and text-to-speech-stream.ts.
- */
-export type TtsStreamChunk = {
-    outputArray: ArrayLike<number>;
-    chunkIndex?: number;
-    sentenceChunk?: string;
-};
-export type TtsOpYield = {
-    buffer: number[];
-    chunkIndex?: number;
-    sentenceChunk?: string;
-};
-type AddonTtsStats = {
-    audioDurationMs?: number;
-    totalSamples?: number;
-    enhancerBackendDevice?: number;
-    enhancerBackendId?: number;
-};
-export declare function collectTtsStats(response: {
-    stats?: AddonTtsStats;
-}): TtsStats;
-export {};
-//# sourceMappingURL=tts-stats.d.ts.map

package/dist/server/bare/utils/tts-stats.js

@@ -1,16 +0,0 @@
-export function collectTtsStats(response) {
-    return {
-        ...(response.stats?.audioDurationMs !== undefined && {
-            audioDuration: response.stats.audioDurationMs
-        }),
-        ...(response.stats?.totalSamples !== undefined && {
-            totalSamples: response.stats.totalSamples
-        }),
-        ...(response.stats?.enhancerBackendDevice !== undefined && {
-            enhancerBackendDevice: response.stats.enhancerBackendDevice
-        }),
-        ...(response.stats?.enhancerBackendId !== undefined && {
-            enhancerBackendId: response.stats.enhancerBackendId
-        })
-    };
-}

package/dist/server/error-handlers.js

@@ -1,32 +0,0 @@
-import { createErrorResponse, responseSchema } from '../schemas/index.js';
-import { getServerLogger } from '../logging/index.js';
-import {} from './rpc/profiling/index.js';
-const logger = getServerLogger();
-function buildErrorResponseData(error, profiler) {
-    const errorResponse = createErrorResponse(error);
-    const validated = responseSchema.parse(errorResponse);
-    const json = JSON.stringify(validated);
-    return profiler ? profiler.serializeError(json) : json;
-}
-export function sendErrorResponse(req, error, profiler) {
-    try {
-        req.reply(buildErrorResponseData(error, profiler), 'utf-8');
-    }
-    catch (responseError) {
-        logger.error('Failed to create error response:', responseError);
-        const fallbackError = createErrorResponse(new Error('Internal server error'));
-        req.reply(JSON.stringify(fallbackError), 'utf-8');
-    }
-}
-export function sendStreamErrorResponse(stream, error, profiler) {
-    try {
-        stream.write(buildErrorResponseData(error, profiler) + '\n', 'utf-8');
-        stream.end();
-    }
-    catch (responseError) {
-        logger.error('Failed to create stream error response:', responseError);
-        const fallbackError = createErrorResponse(new Error('Internal server error'));
-        stream.write(JSON.stringify(fallbackError) + '\n', 'utf-8');
-        stream.end();
-    }
-}

package/dist/server/plugins/index.d.ts

@@ -1,2 +0,0 @@
-export { registerPlugin, registerPlugins, getPlugin, getPluginHandler, hasPlugin, getAllPlugins, clearPlugins, unregisterPlugin } from './registry.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/server/plugins/index.js

@@ -1 +0,0 @@
-export { registerPlugin, registerPlugins, getPlugin, getPluginHandler, hasPlugin, getAllPlugins, clearPlugins, unregisterPlugin } from './registry.js';

package/dist/server/plugins/registry.d.ts

@@ -1,10 +0,0 @@
-import { type QvacPlugin, type PluginHandlerDefinition } from '../../schemas/plugin.js';
-export declare function registerPlugin(plugin: QvacPlugin): void;
-export declare function registerPlugins(pluginList: readonly QvacPlugin[]): void;
-export declare function getPlugin(modelType: string): QvacPlugin | undefined;
-export declare function getPluginHandler(modelType: string, handlerName: string): PluginHandlerDefinition | undefined;
-export declare function hasPlugin(modelType: string): boolean;
-export declare function unregisterPlugin(modelType: string): boolean;
-export declare function getAllPlugins(): QvacPlugin[];
-export declare function clearPlugins(): void;
-//# sourceMappingURL=registry.d.ts.map