@qvac/sdk 0.9.2 → 0.10.0

package/dist/examples/tts/utils.d.ts

@@ -11,7 +11,17 @@ export declare function int16ArrayToBuffer(samples: number[]): Buffer;
  */
 export declare function createWav(audioBuffer: number[], sampleRate: number, filename: string): void;
 /**
- * Play audio using system audio players
+ * Play a WAV buffer by streaming it into ffplay over stdin.
+ *
+ * ffplay ships with ffmpeg and is cross-platform (macOS/Linux/Windows), so
+ * we avoid the old "write to /tmp then shell out to afplay/aplay/powershell"
+ * dance — no temp files, no platform switch, no hardcoded /tmp path (which
+ * doesn't exist on Windows). Requires ffplay on PATH.
  */
+/**
+ * Play one mono s16le PCM chunk (as a minimal WAV) and wait for the player to finish.
+ * Chunks are played sequentially when awaited in order — suitable for streaming TTS output.
+ */
+export declare function playPcmInt16Chunk(samples: number[], sampleRate: number): Promise<void>;
 export declare function playAudio(audioBuffer: Buffer): void;
 //# sourceMappingURL=utils.d.ts.map

package/dist/examples/tts/utils.js

@@ -1,6 +1,7 @@
 import { writeFileSync, unlinkSync } from "fs";
-import { spawnSync } from "child_process";
-import { platform } from "os";
+import { spawn, spawnSync } from "child_process";
+import { platform, tmpdir } from "os";
+import { join } from "path";
 /**
  * Create WAV header for 16-bit PCM audio
  */
@@ -46,13 +47,30 @@ export function createWav(audioBuffer, sampleRate, filename) {
     console.log(`WAV file saved as: ${filename}`);
 }
 /**
- * Play audio using system audio players
+ * Play a WAV buffer by streaming it into ffplay over stdin.
+ *
+ * ffplay ships with ffmpeg and is cross-platform (macOS/Linux/Windows), so
+ * we avoid the old "write to /tmp then shell out to afplay/aplay/powershell"
+ * dance — no temp files, no platform switch, no hardcoded /tmp path (which
+ * doesn't exist on Windows). Requires ffplay on PATH.
  */
-export function playAudio(audioBuffer) {
+/**
+ * Play one mono s16le PCM chunk (as a minimal WAV) and wait for the player to finish.
+ * Chunks are played sequentially when awaited in order — suitable for streaming TTS output.
+ */
+export function playPcmInt16Chunk(samples, sampleRate) {
+    if (samples.length === 0) {
+        return Promise.resolve();
+    }
+    const audioData = int16ArrayToBuffer(samples);
+    const wavHeader = createWavHeader(audioData.length, sampleRate);
+    const wavFile = Buffer.concat([wavHeader, audioData]);
+    // `os.tmpdir()` resolves to the OS-specific temp directory (e.g. `%TEMP%`
+    // on Windows), so the Windows branch below no longer tries to read a
+    // POSIX-only `/tmp/...` path.
+    const tempFile = join(tmpdir(), `qvac-tts-chunk-${Date.now()}-${Math.random().toString(16).slice(2)}.wav`);
+    writeFileSync(tempFile, wavFile);
     const currentPlatform = platform();
-    const tempFile = `/tmp/audio-${Date.now()}.wav`;
-    // Write audio buffer to temporary file
-    writeFileSync(tempFile, audioBuffer);
     let audioPlayer;
     let args;
     switch (currentPlatform) {
@@ -75,19 +93,54 @@ export function playAudio(audioBuffer) {
             audioPlayer = "aplay";
             args = [tempFile];
     }
-    const result = spawnSync(audioPlayer, args, {
-        stdio: ["inherit", "inherit", "inherit"],
+    return new Promise(function (resolve, reject) {
+        const proc = spawn(audioPlayer, args, { stdio: "ignore" });
+        proc.on("error", function (err) {
+            try {
+                unlinkSync(tempFile);
+            }
+            catch {
+                // ignore
+            }
+            reject(err);
+        });
+        proc.on("close", function (code) {
+            try {
+                unlinkSync(tempFile);
+            }
+            catch {
+                // ignore
+            }
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Audio player exited with code ${code}`));
+            }
+        });
+    });
+}
+export function playAudio(audioBuffer) {
+    const result = spawnSync("ffplay", [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-autoexit",
+        "-nodisp",
+        "-i",
+        "pipe:0",
+    ], {
+        input: audioBuffer,
+        stdio: ["pipe", "inherit", "inherit"],
     });
-    try {
-        unlinkSync(tempFile);
-    }
-    catch {
-        // Ignore cleanup errors
-    }
     if (result.error) {
-        throw new Error(`Audio player failed: ${result.error.message}`);
+        const code = result.error.code;
+        if (code === "ENOENT") {
+            throw new Error("ffplay not found on PATH. Install ffmpeg (ffplay ships with it) and retry.");
+        }
+        throw new Error(`ffplay failed: ${result.error.message}`);
     }
     if (result.status !== 0) {
-        throw new Error(`Audio player exited with code ${result.status}`);
+        throw new Error(`ffplay exited with code ${result.status}`);
     }
 }

package/dist/examples/voice-assistant/voice-assistant.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=voice-assistant.d.ts.map

package/dist/examples/voice-assistant/voice-assistant.js

@@ -0,0 +1,207 @@
+/**
+ * Real-time Voice Assistant: mic → Whisper (with Silero VAD) → Llama → Supertonic TTS.
+ *
+ * Usage: bun run examples/voice-assistant/voice-assistant.ts
+ *
+ * Speak a question; the VAD detects when you pause, the utterance is
+ * transcribed, sent to the LLM, and the response is spoken back. The loop
+ * continues until you press Ctrl+C. While the assistant is speaking, mic
+ * audio is dropped so it does not hear itself.
+ *
+ * Requirements: FFmpeg installed, microphone access, speakers.
+ */
+import { loadModel, unloadModel, transcribeStream, completion, textToSpeech, WHISPER_TINY, VAD_SILERO_5_1_2, LLAMA_3_2_1B_INST_Q4_0, TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_DURATION_PREDICTOR_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_VECTOR_ESTIMATOR_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_VOCODER_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_UNICODE_INDEXER_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_TTS_CONFIG_SUPERTONE, TTS_SUPERTONIC2_OFFICIAL_VOICE_STYLE_SUPERTONE, } from "@qvac/sdk";
+import { spawnSync } from "child_process";
+import { startMicrophone } from "../audio/mic-input";
+import { createWavHeader, int16ArrayToBuffer, playAudio } from "../tts/utils";
+const MIC_SAMPLE_RATE = 16000;
+const TTS_SAMPLE_RATE = 44100;
+const SYSTEM_PROMPT = "You are a concise, friendly voice assistant. Keep responses under two sentences. " +
+    "Never use markdown, lists, or code blocks — your output will be spoken aloud.";
+// VAD parameters tuned for conversational speech without the assistant looping
+// on its own echo. These defaults are deliberately conservative:
+//   - threshold 0.6: less sensitive than Silero's default; avoids triggering
+//     on TTS reverb bleeding into the mic or low-level background noise.
+//   - min_speech_duration_ms 300: drops short clicks/breaths and stray words.
+//   - min_silence_duration_ms 700: requires a longer quiet tail before
+//     committing a segment. Crucial for preventing self-hearing feedback loops
+//     where Whisper hallucinates content from near-silent audio.
+//   - max_speech_duration_s 15: caps runaway utterances.
+//   - speech_pad_ms 200: padding improves accuracy on utterance edges.
+// If the assistant cuts you off mid-sentence, raise min_silence_duration_ms.
+// If it keeps hallucinating / talking to itself, raise threshold to 0.7 and/or
+// min_silence_duration_ms to 900.
+const VAD_PARAMS = {
+    threshold: 0.6,
+    min_speech_duration_ms: 300,
+    min_silence_duration_ms: 700,
+    max_speech_duration_s: 15.0,
+    speech_pad_ms: 200,
+};
+// Short grace period after TTS playback before we start listening again.
+// Gives the speaker amp / room reverb a moment to fully settle so the first
+// post-playback mic frames don't get transcribed as the tail of our own voice.
+const POST_PLAYBACK_COOLDOWN_MS = 300;
+// Minimum characters for an utterance to be considered meaningful. Whisper
+// frequently hallucinates single words like "you", ".", or "Thanks." from
+// silence or faint noise; these short phantoms are the main driver of the
+// self-hearing feedback loop, so we drop them.
+const MIN_UTTERANCE_CHARS = 3;
+function isMeaningfulTranscript(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return false;
+    if (trimmed.includes("[No speech detected]"))
+        return false;
+    // Whisper sometimes emits non-linguistic cues on silence, e.g. "[BLANK_AUDIO]".
+    if (/^\[[^\]]+\]$/.test(trimmed))
+        return false;
+    // Strip punctuation/whitespace for the length check so ". . ." is rejected.
+    const letters = trimmed.replace(/[^\p{L}\p{N}]/gu, "");
+    if (letters.length < MIN_UTTERANCE_CHARS)
+        return false;
+    return true;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ── Main ──
+for (const tool of ["ffmpeg", "ffplay"]) {
+    const r = spawnSync(tool, ["-version"], { stdio: "ignore" });
+    if (r.error || r.status !== 0) {
+        console.error(`${tool} not found on PATH. Install ffmpeg (ffplay ships with it) and retry.`);
+        process.exit(1);
+    }
+}
+console.log("Loading whisper-tiny + Silero VAD...");
+const asrModelId = await loadModel({
+    modelSrc: WHISPER_TINY,
+    modelType: "whisper",
+    modelConfig: {
+        vadModelSrc: VAD_SILERO_5_1_2,
+        audio_format: "f32le",
+        strategy: "greedy",
+        n_threads: 4,
+        language: "en",
+        no_timestamps: true,
+        suppress_blank: true,
+        suppress_nst: true,
+        temperature: 0.0,
+        vad_params: VAD_PARAMS,
+    },
+});
+console.log("Loading Llama 3.2 1B...");
+const llmModelId = await loadModel({
+    modelSrc: LLAMA_3_2_1B_INST_Q4_0,
+    modelType: "llm",
+    modelConfig: {
+        ctx_size: 4096,
+    },
+});
+console.log("Loading Supertonic TTS...");
+const ttsModelId = await loadModel({
+    modelSrc: TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32.src,
+    modelType: "tts",
+    modelConfig: {
+        ttsEngine: "supertonic",
+        language: "en",
+        ttsSpeed: 1.05,
+        ttsNumInferenceSteps: 5,
+        ttsSupertonicMultilingual: false,
+        ttsTextEncoderSrc: TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32.src,
+        ttsDurationPredictorSrc: TTS_SUPERTONIC2_OFFICIAL_DURATION_PREDICTOR_SUPERTONE_FP32.src,
+        ttsVectorEstimatorSrc: TTS_SUPERTONIC2_OFFICIAL_VECTOR_ESTIMATOR_SUPERTONE_FP32.src,
+        ttsVocoderSrc: TTS_SUPERTONIC2_OFFICIAL_VOCODER_SUPERTONE_FP32.src,
+        ttsUnicodeIndexerSrc: TTS_SUPERTONIC2_OFFICIAL_UNICODE_INDEXER_SUPERTONE_FP32.src,
+        ttsTtsConfigSrc: TTS_SUPERTONIC2_OFFICIAL_TTS_CONFIG_SUPERTONE.src,
+        ttsVoiceStyleSrc: TTS_SUPERTONIC2_OFFICIAL_VOICE_STYLE_SUPERTONE.src,
+    },
+});
+console.log("All models loaded.\n");
+const ffmpeg = startMicrophone({
+    sampleRate: MIC_SAMPLE_RATE,
+    format: "f32le",
+});
+const session = await transcribeStream({ modelId: asrModelId });
+const history = [{ role: "system", content: SYSTEM_PROMPT }];
+// Dropped-chunk gate: while the assistant is speaking we stop feeding the mic
+// stream into the ASR session. Using a flag (rather than pausing the ffmpeg
+// pipe) keeps the pipe drained so we never accumulate stale audio, and the
+// VAD starts fresh on the next user turn.
+let isSpeaking = false;
+ffmpeg.stdout.on("data", (chunk) => {
+    if (isSpeaking)
+        return;
+    session.write(chunk);
+});
+let shuttingDown = false;
+async function cleanup() {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    console.log("\n\nStopping...");
+    ffmpeg.kill();
+    try {
+        session.end();
+    }
+    catch {
+        // session may already be closed
+    }
+    await unloadModel({ modelId: ttsModelId }).catch(() => { });
+    await unloadModel({ modelId: llmModelId }).catch(() => { });
+    await unloadModel({ modelId: asrModelId }).catch(() => { });
+    console.log("Done.");
+    process.exit(0);
+}
+process.on("SIGINT", () => void cleanup());
+process.on("SIGTERM", () => void cleanup());
+console.log("🎙️  Listening. Speak a question and pause. Ctrl+C to quit.\n");
+for await (const rawText of session) {
+    if (!isMeaningfulTranscript(rawText))
+        continue;
+    const userText = rawText.trim();
+    console.log(`🗣️  You: ${userText}`);
+    history.push({ role: "user", content: userText });
+    isSpeaking = true;
+    try {
+        process.stdout.write("🤖 Assistant: ");
+        const llmResult = completion({
+            modelId: llmModelId,
+            history,
+            stream: true,
+        });
+        let assistantText = "";
+        for await (const token of llmResult.tokenStream) {
+            process.stdout.write(token);
+            assistantText += token;
+        }
+        process.stdout.write("\n");
+        history.push({ role: "assistant", content: assistantText });
+        const spoken = assistantText.trim();
+        if (spoken.length > 0) {
+            const ttsResult = textToSpeech({
+                modelId: ttsModelId,
+                text: spoken,
+                inputType: "text",
+                stream: false,
+            });
+            const samples = await ttsResult.buffer;
+            const audioData = int16ArrayToBuffer(samples);
+            const wavBuffer = Buffer.concat([
+                createWavHeader(audioData.length, TTS_SAMPLE_RATE),
+                audioData,
+            ]);
+            playAudio(wavBuffer);
+            // Cooldown keeps the mic gated briefly so speaker tail / room reverb
+            // doesn't feed into the next VAD segment.
+            await sleep(POST_PLAYBACK_COOLDOWN_MS);
+        }
+    }
+    catch (turnError) {
+        console.error("\n⚠️  Turn failed:", turnError instanceof Error ? turnError.message : turnError);
+    }
+    finally {
+        isSpeaking = false;
+        console.log("\n🎙️  Listening...\n");
+    }
+}

package/dist/expo/plugins/withMobileBundle.js

@@ -74,7 +74,7 @@ function findConfigFile(projectRoot) {
  * falls back to npx for convenience when CLI is not installed.
  */
 function resolveCliCommand(projectRoot) {
-    const cliPath = path.join(projectRoot, "node_modules", "@qvac", "cli", "src", "index.js");
+    const cliPath = path.join(projectRoot, "node_modules", "@qvac", "cli", "dist", "index.js");
     if (fs.existsSync(cliPath)) {
         return `node "${cliPath}"`;
     }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import "#polyfill-bare-globals";
-export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, getModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, type DiffusionProgressTick, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, suspend, resume, type FinetuneHandle, } from "./client/api/index";
+export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, textToSpeechStream, getModelInfo, getLoadedModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, type DiffusionProgressTick, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, suspend, resume, state, type FinetuneHandle, } from "./client/api/index";
 export { close } from "./client/index";
-export { type ModelProgressUpdate, type LoadModelOptions, type DownloadAssetOptions, type Tool, type ToolCall, type ToolCallWithCall, type ToolCallError, type ToolCallEvent, type CompletionStats, type EmbedStats, VERBOSITY, type Attachment, type TranscribeStreamSession, type CompletionParams, type RagSearchResult, type RagSaveEmbeddingsResult, type RagReindexResult, type RagEmbeddedDoc, type RagDoc, type RagWorkspaceInfo, type RagCloseWorkspaceParams, type RagDeleteWorkspaceParams, type RagIngestStage, type RagReindexStage, type RagSaveStage, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, type QvacConfig, type ModelInfo, type GetModelInfoParams, type LoadedInstance, type CacheFileInfo, toolSchema, type McpClient, type McpClientInput, type OCRClientParams, type OCRTextBlock, type OCROptions, type DiffusionClientParams, type DiffusionStreamResponse, type DiffusionStats, definePlugin, defineHandler, defineDuplexHandler, type QvacPlugin, type CreateModelParams, type PluginModelResult, type ModelRegistryEntry, type ModelRegistryEntryAddon, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, SDK_DEFAULT_PLUGINS, type BuiltinPlugin, type ProfilerMode, type FinetuneValidation, type FinetuneRunParams, type FinetuneGetStateParams, type FinetuneStopParams, type FinetuneParams, type FinetuneStatus, type FinetuneProgress, type FinetuneStats, type FinetuneResult, } from "./schemas/index";
+export { type LifecycleState, type ModelProgressUpdate, type LoadModelOptions, type LoadCustomPluginModelOptions, type DownloadAssetOptions, type Tool, type ToolCall, type ToolCallWithCall, type ToolCallError, type ToolCallEvent, type CompletionEvent, type CompletionFinal, type CompletionRun, type CompletionStats, type EmbedStats, VERBOSITY, type Attachment, type TranscribeStreamSession, type TranscribeStreamMetadataSession, type TranscribeSegment, type TextToSpeechStreamSession, type TextToSpeechStreamResponse, type TextToSpeechStreamClientParams, type CompletionParams, type ToolDialect, type RagSearchResult, type RagSaveEmbeddingsResult, type RagReindexResult, type RagEmbeddedDoc, type RagDoc, type RagWorkspaceInfo, type RagCloseWorkspaceParams, type RagDeleteWorkspaceParams, type RagIngestStage, type RagReindexStage, type RagSaveStage, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, type QvacConfig, type ModelInfo, type GetModelInfoParams, type GetLoadedModelInfoParams, type LoadedModelInfo, type LoadedInstance, type CacheFileInfo, toolSchema, TOOLS_MODE, type ToolsMode, type McpClient, type McpClientInput, type OCRClientParams, type OCRTextBlock, type OCROptions, type DiffusionClientParams, type DiffusionStreamResponse, type DiffusionStats, definePlugin, defineHandler, defineDuplexHandler, type QvacPlugin, type CreateModelParams, type PluginModelResult, type ModelRegistryEntry, type ModelRegistryEntryAddon, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, SDK_DEFAULT_PLUGINS, type BuiltinPlugin, type ProfilerMode, type FinetuneValidation, type FinetuneRunParams, type FinetuneGetStateParams, type FinetuneStopParams, type FinetuneParams, type FinetuneStatus, type FinetuneProgress, type FinetuneStats, type FinetuneResult, } from "./schemas/index";
 export { type ToolInput, type ToolHandler } from "./utils/tool-helpers";
 export { MODEL_TYPES, ModelType } from "./schemas/index";
 export * from "./models/registry/index";

package/dist/index.js

@@ -1,8 +1,8 @@
 import "#polyfill-bare-globals";
 // Public API exports only
-export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, getModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, suspend, resume, } from "./client/api/index.js";
+export { completion, deleteCache, loadModel, downloadAsset, heartbeat, startQVACProvider, stopQVACProvider, unloadModel, transcribe, transcribeStream, embed, finetune, translate, cancel, ragChunk, ragIngest, ragSaveEmbeddings, ragSearch, ragDeleteEmbeddings, ragReindex, ragListWorkspaces, ragCloseWorkspace, ragDeleteWorkspace, textToSpeech, textToSpeechStream, getModelInfo, getLoadedModelInfo, loggingStream, ocr, invokePlugin, invokePluginStream, diffusion, modelRegistryList, modelRegistrySearch, modelRegistryGetModel, suspend, resume, state, } from "./client/api/index.js";
 export { close } from "./client/index.js";
-export { VERBOSITY, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, toolSchema, definePlugin, defineHandler, defineDuplexHandler, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, SDK_DEFAULT_PLUGINS, } from "./schemas/index.js";
+export { VERBOSITY, SDK_CLIENT_ERROR_CODES, SDK_SERVER_ERROR_CODES, toolSchema, TOOLS_MODE, definePlugin, defineHandler, defineDuplexHandler, PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, SDK_DEFAULT_PLUGINS, } from "./schemas/index.js";
 export {} from "./utils/tool-helpers.js";
 // Model types - canonical naming with backward-compatible aliases
 export { MODEL_TYPES, ModelType } from "./schemas/index.js";

package/dist/logging/logger.d.ts

@@ -1,3 +1,14 @@
 import type { Logger, LoggerOptions } from "./types";
+/**
+ * Creates or retrieves a namespaced logger instance.
+ *
+ * Loggers are cached per namespace when `options` is omitted, so repeated
+ * calls with the same namespace return the same instance. When `options` is
+ * supplied, a fresh logger is returned and the cache is bypassed.
+ *
+ * @param namespace - Namespace used to prefix log messages from this logger (e.g. `"my-app"`, `"@qvac/sdk:embed"`).
+ * @param options - Optional logger configuration (custom transports, log level, etc.). When provided, a new logger is always constructed.
+ * @returns A `Logger` instance scoped to `namespace`.
+ */
 export declare function getLogger(namespace: string, options?: LoggerOptions): Logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.js

@@ -17,6 +17,17 @@ function createLogger(namespace, options) {
         : undefined;
     return createBaseLogger(namespace, safeOptions);
 }
+/**
+ * Creates or retrieves a namespaced logger instance.
+ *
+ * Loggers are cached per namespace when `options` is omitted, so repeated
+ * calls with the same namespace return the same instance. When `options` is
+ * supplied, a fresh logger is returned and the cache is bypassed.
+ *
+ * @param namespace - Namespace used to prefix log messages from this logger (e.g. `"my-app"`, `"@qvac/sdk:embed"`).
+ * @param options - Optional logger configuration (custom transports, log level, etc.). When provided, a new logger is always constructed.
+ * @returns A `Logger` instance scoped to `namespace`.
+ */
 export function getLogger(namespace, options) {
     const cache = getLoggerCache();
     if (!options) {

package/dist/logging/types.d.ts

@@ -1,20 +1,38 @@
 import type { LogLevel } from "@qvac/logging";
+/**
+ * Log transport callback signature. Receives the log `level`, namespace
+ * scoping the message, and the formatted `message`. May return a promise to
+ * allow async backends (e.g., network sinks).
+ */
 export type LogTransport = (level: LogLevel, namespace: string, message: string) => void | Promise<void>;
 export interface LoggerOptions {
+    /** Minimum log level that will be emitted. */
     level?: LogLevel;
+    /** Namespace prefix applied to every message emitted by this logger. */
     namespace?: string;
+    /** Additional log transports to receive every emitted message. */
     transports?: LogTransport[];
+    /** When `false`, disables the default console transport. */
     enableConsole?: boolean;
 }
 export interface Logger {
+    /** Emits a message at the `error` level. */
     error: (...args: unknown[]) => void;
+    /** Emits a message at the `warn` level. */
     warn: (...args: unknown[]) => void;
+    /** Emits a message at the `info` level. */
     info: (...args: unknown[]) => void;
+    /** Emits a message at the `debug` level. */
     debug: (...args: unknown[]) => void;
+    /** Emits a message at the `trace` level. */
     trace: (...args: unknown[]) => void;
+    /** Sets the logger's minimum log level. */
     setLevel: (level: LogLevel) => void;
+    /** Returns the logger's current minimum log level. */
     getLevel: () => LogLevel;
+    /** Registers an additional log transport with this logger. */
     addTransport: (transport: LogTransport) => void;
+    /** Enables or disables this logger's default console transport. */
     setConsoleOutput: (enabled: boolean) => void;
 }
 //# sourceMappingURL=types.d.ts.map