@gobing-ai/knowledge-kit 0.0.6 → 0.0.8

package/plugins/generations/voice-gen/src/voicebox-client.ts

@@ -0,0 +1,223 @@
+export interface VoiceboxGenerateBody {
+    profile_id: string;
+    text: string;
+    language: string;
+    engine?: string;
+    instruct?: string;
+    max_chunk_chars: number;
+    crossfade_ms: number;
+    personality: false;
+    normalize: true;
+}
+
+export interface VoiceboxProfile {
+    id: string;
+    name: string;
+    description?: string;
+    engine?: string;
+    language?: string;
+}
+
+export interface VoiceboxHistory {
+    id: string;
+    status: 'pending' | 'generating' | 'completed' | 'failed' | string;
+    duration?: number;
+    error?: string;
+}
+
+export interface VoiceboxClient {
+    readonly url: string;
+    health(): Promise<void>;
+    resolveProfile(nameOrId: string): Promise<VoiceboxProfile>;
+    generate(body: VoiceboxGenerateBody): Promise<{ id: string }>;
+    waitUntilDone(
+        id: string,
+        timeoutMs?: number,
+        pollMs?: number,
+    ): Promise<{ status: 'completed' | 'failed'; duration?: number; error?: string }>;
+    downloadAudio(id: string): Promise<Uint8Array>;
+}
+
+export interface VoiceboxClientOptions {
+    url?: string;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * Creates a client for the Voicebox local REST API.
+ */
+export function createVoiceboxClient(options: VoiceboxClientOptions = {}): VoiceboxClient {
+    const rawUrl = options.url || process.env.VOICEBOX_URL || 'http://127.0.0.1:17493';
+    const url = rawUrl.replace(/\/+$/, '');
+    const customFetch = options.fetch ?? globalThis.fetch;
+    const sleep = options.sleep ?? ((ms: number) => new Promise((resolve) => setTimeout(resolve, ms)));
+
+    return {
+        url,
+
+        async health(): Promise<void> {
+            try {
+                const res = await customFetch(`${url}/health`);
+                if (!res.ok) {
+                    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+                }
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox health check failed at ${url}: ${reason}`);
+            }
+        },
+
+        async resolveProfile(nameOrId: string): Promise<VoiceboxProfile> {
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/profiles`);
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /profiles request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                throw new Error(`Voicebox /profiles request failed at ${url}: HTTP ${res.status} ${res.statusText}`);
+            }
+
+            let profiles: VoiceboxProfile[];
+            try {
+                profiles = (await res.json()) as VoiceboxProfile[];
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /profiles returned invalid JSON at ${url}: ${reason}`);
+            }
+
+            if (!Array.isArray(profiles)) {
+                throw new Error(`Voicebox /profiles returned non-array at ${url}`);
+            }
+
+            const targetLower = nameOrId.toLowerCase();
+            const matched = profiles.find((p) => p.id === nameOrId || (p.name && p.name.toLowerCase() === targetLower));
+
+            if (!matched) {
+                throw new Error(`Voicebox profile "${nameOrId}" not found at ${url}`);
+            }
+
+            return matched;
+        },
+
+        async generate(body: VoiceboxGenerateBody): Promise<{ id: string }> {
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/generate`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify(body),
+                });
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /generate request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                let errorDetails = '';
+                try {
+                    errorDetails = await res.text();
+                } catch {
+                    // ignore
+                }
+                throw new Error(
+                    `Voicebox /generate failed at ${url}: HTTP ${res.status} ${res.statusText} ${errorDetails}`.trim(),
+                );
+            }
+
+            let data: { id: string };
+            try {
+                data = (await res.json()) as { id: string };
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /generate returned invalid JSON at ${url}: ${reason}`);
+            }
+
+            if (!data || typeof data.id !== 'string') {
+                throw new Error(`Voicebox /generate response missing id at ${url}`);
+            }
+
+            return { id: data.id };
+        },
+
+        async waitUntilDone(
+            id: string,
+            timeoutMs?: number,
+            pollMs?: number,
+        ): Promise<{ status: 'completed' | 'failed'; duration?: number; error?: string }> {
+            const timeout =
+                timeoutMs ?? (process.env.VOICEBOX_TIMEOUT_MS ? parseInt(process.env.VOICEBOX_TIMEOUT_MS, 10) : 600000);
+            const poll = pollMs ?? (process.env.VOICEBOX_POLL_MS ? parseInt(process.env.VOICEBOX_POLL_MS, 10) : 1000);
+
+            const startTime = Date.now();
+
+            while (true) {
+                let res: Response;
+                try {
+                    res = await customFetch(`${url}/history/${id}`);
+                } catch (err: unknown) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    throw new Error(`Voicebox /history/${id} request failed at ${url}: ${reason}`);
+                }
+
+                if (!res.ok) {
+                    throw new Error(
+                        `Voicebox /history/${id} request failed at ${url}: HTTP ${res.status} ${res.statusText}`,
+                    );
+                }
+
+                let history: VoiceboxHistory;
+                try {
+                    history = (await res.json()) as VoiceboxHistory;
+                } catch (err: unknown) {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    throw new Error(`Voicebox /history/${id} returned invalid JSON at ${url}: ${reason}`);
+                }
+
+                if (history.status === 'completed') {
+                    return { status: 'completed', duration: history.duration };
+                }
+                if (history.status === 'failed') {
+                    return {
+                        status: 'failed',
+                        duration: history.duration,
+                        error: history.error || 'Generation status failed',
+                    };
+                }
+
+                if (Date.now() - startTime >= timeout) {
+                    throw new Error(`Voicebox generation timed out after ${timeout}ms for id: ${id} at ${url}`);
+                }
+
+                await sleep(poll);
+            }
+        },
+
+        async downloadAudio(id: string): Promise<Uint8Array> {
+            let res: Response;
+            try {
+                res = await customFetch(`${url}/audio/${id}`);
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /audio/${id} request failed at ${url}: ${reason}`);
+            }
+
+            if (!res.ok) {
+                throw new Error(`Voicebox /audio/${id} request failed at ${url}: HTTP ${res.status} ${res.statusText}`);
+            }
+
+            try {
+                const arrayBuf = await res.arrayBuffer();
+                return new Uint8Array(arrayBuf);
+            } catch (err: unknown) {
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Voicebox /audio/${id} failed to read audio stream at ${url}: ${reason}`);
+            }
+        },
+    };
+}

package/plugins/generations/voice-gen/src/voicescript.ts

@@ -0,0 +1,365 @@
+import type { Doc } from '@gobing-ai/kk-core';
+
+export const VOICEBOX_TEXT_MAX = 50_000;
+export const VOICEBOX_INSTRUCT_MAX = 500;
+export const VOICEBOX_CHUNK_CHARS_MIN = 100;
+export const VOICEBOX_CHUNK_CHARS_MAX = 5_000;
+export const VOICEBOX_CHUNK_CHARS_DEFAULT = 800;
+export const VOICEBOX_CROSSFADE_MS_MIN = 0;
+export const VOICEBOX_CROSSFADE_MS_MAX = 500;
+export const VOICEBOX_CROSSFADE_MS_DEFAULT = 50;
+
+export const VOICEBOX_ENGINES = [
+    'qwen',
+    'qwen_custom_voice',
+    'luxtts',
+    'chatterbox',
+    'chatterbox_turbo',
+    'tada',
+    'kokoro',
+] as const;
+
+export const VOICEBOX_LANGUAGES = [
+    'zh',
+    'en',
+    'ja',
+    'ko',
+    'de',
+    'fr',
+    'ru',
+    'pt',
+    'es',
+    'it',
+    'he',
+    'ar',
+    'da',
+    'el',
+    'fi',
+    'hi',
+    'ms',
+    'nl',
+    'no',
+    'pl',
+    'sv',
+    'sw',
+    'tr',
+] as const;
+
+const ENGINE_SET = new Set<string>(VOICEBOX_ENGINES);
+const LANGUAGE_SET = new Set<string>(VOICEBOX_LANGUAGES);
+
+function assertEngine(value: string | undefined, label: string): void {
+    if (value !== undefined && !ENGINE_SET.has(value)) {
+        throw new Error(`${label} engine must be one of ${VOICEBOX_ENGINES.join('|')} (got "${value}")`);
+    }
+}
+
+function assertLanguage(value: string | undefined, label: string): void {
+    if (value !== undefined && !LANGUAGE_SET.has(value)) {
+        throw new Error(`${label} language must be a Voicebox language code (got "${value}")`);
+    }
+}
+
+export interface VoiceSpeaker {
+    profile: string;
+    engine?: string;
+    language?: string;
+    instruct?: string;
+}
+
+export interface VoiceSegment {
+    speaker?: string;
+    profile?: string;
+    text: string;
+    instruct?: string;
+    engine?: string;
+    language?: string;
+    gap_ms?: number;
+    max_chunk_chars?: number;
+    crossfade_ms?: number;
+}
+
+export interface VoiceScript {
+    title?: string;
+    language?: string;
+    default_engine?: string;
+    default_profile?: string;
+    max_chunk_chars?: number;
+    crossfade_ms?: number;
+    speakers?: Record<string, VoiceSpeaker>;
+    segments: VoiceSegment[];
+}
+
+const VOICESCRIPT_KEYS = new Set(['segments', 'speakers', 'default_profile', 'default_engine']);
+
+/**
+ * Parse a Doc into a VoiceScript structure.
+ * - JSON object starting with '{' -> VoiceScript path (even without segments -> validation fails loud).
+ * - Body starting with '[' -> Plain text path (e.g. Chatterbox [laugh] tag).
+ * - YAML mapping with any of segments/speakers/default_profile/default_engine -> VoiceScript path.
+ * - Otherwise -> Plain text single-segment script.
+ */
+export function parseDocToVoiceScript(doc: Doc, envDefaultProfile?: string): VoiceScript {
+    const trimmed = (doc.body || '').trim();
+
+    if (trimmed.startsWith('{')) {
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(trimmed);
+        } catch {
+            throw new Error('Invalid VoiceScript JSON structure: failed to parse JSON object');
+        }
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Invalid VoiceScript JSON structure: root must be a JSON object');
+        }
+        return parsed as VoiceScript;
+    }
+
+    if (trimmed.startsWith('[')) {
+        return {
+            segments: [{ text: trimmed }],
+            default_profile:
+                envDefaultProfile ??
+                (typeof doc.metadata?.voiceProfile === 'string' ? doc.metadata.voiceProfile : undefined),
+        };
+    }
+
+    try {
+        const parsed = Bun.YAML.parse(trimmed);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const hasKey = Object.keys(parsed).some((k) => VOICESCRIPT_KEYS.has(k));
+            if (hasKey) {
+                return parsed as VoiceScript;
+            }
+        }
+    } catch {
+        // Fall through to plain text
+    }
+
+    return {
+        segments: [{ text: trimmed }],
+        default_profile:
+            envDefaultProfile ??
+            (typeof doc.metadata?.voiceProfile === 'string' ? doc.metadata.voiceProfile : undefined),
+    };
+}
+
+/**
+ * Merge multiple Doc-level VoiceScripts into a single combined VoiceScript.
+ */
+export function mergeVoiceScripts(scripts: VoiceScript[], docs: Doc[], envDefaultProfile?: string): VoiceScript {
+    if (scripts.length === 0) {
+        return { segments: [] };
+    }
+    const firstScript = scripts[0];
+    if (scripts.length === 1 && firstScript) {
+        return firstScript;
+    }
+
+    const combinedSpeakers: Record<string, VoiceSpeaker> = {};
+    const combinedSegments: VoiceSegment[] = [];
+
+    let title: string | undefined;
+    let defaultProfile: string | undefined = envDefaultProfile;
+    let defaultEngine: string | undefined;
+    let language: string | undefined;
+    let maxChunkChars: number | undefined;
+    let crossfadeMs: number | undefined;
+
+    for (let i = 0; i < scripts.length; i++) {
+        const script = scripts[i];
+        if (!script) {
+            continue;
+        }
+        const doc = docs[i];
+
+        if (!title) {
+            title = script.title || doc?.title;
+        }
+        if (script.default_profile && defaultProfile === envDefaultProfile) {
+            defaultProfile = script.default_profile;
+        }
+        if (!defaultProfile && typeof doc?.metadata?.voiceProfile === 'string') {
+            defaultProfile = doc.metadata.voiceProfile;
+        }
+        if (!defaultEngine && script.default_engine) {
+            defaultEngine = script.default_engine;
+        }
+        if (!language && script.language) {
+            language = script.language;
+        }
+        if (maxChunkChars === undefined && script.max_chunk_chars !== undefined) {
+            maxChunkChars = script.max_chunk_chars;
+        }
+        if (crossfadeMs === undefined && script.crossfade_ms !== undefined) {
+            crossfadeMs = script.crossfade_ms;
+        }
+
+        if (script.speakers) {
+            for (const [key, speaker] of Object.entries(script.speakers)) {
+                if (key in combinedSpeakers) {
+                    throw new Error(`Duplicate speaker key across documents: "${key}"`);
+                }
+                combinedSpeakers[key] = speaker;
+            }
+        }
+
+        if (Array.isArray(script.segments)) {
+            combinedSegments.push(...script.segments);
+        }
+    }
+
+    const result: VoiceScript = {
+        title: title || docs[0]?.title || 'Generated voice',
+        segments: combinedSegments,
+    };
+
+    if (Object.keys(combinedSpeakers).length > 0) {
+        result.speakers = combinedSpeakers;
+    }
+    if (defaultProfile) {
+        result.default_profile = defaultProfile;
+    }
+    if (defaultEngine) {
+        result.default_engine = defaultEngine;
+    }
+    if (language) {
+        result.language = language;
+    }
+    if (maxChunkChars !== undefined) {
+        result.max_chunk_chars = maxChunkChars;
+    }
+    if (crossfadeMs !== undefined) {
+        result.crossfade_ms = crossfadeMs;
+    }
+
+    return result;
+}
+
+/**
+ * Validate that a VoiceScript satisfies all Voicebox and plugin constraints.
+ */
+export function validateVoiceScript(script: VoiceScript): void {
+    if (!script || typeof script !== 'object') {
+        throw new Error('VoiceScript must be an object');
+    }
+
+    if (!Array.isArray(script.segments) || script.segments.length === 0) {
+        throw new Error('VoiceScript must have a non-empty segments array');
+    }
+
+    if (script.max_chunk_chars !== undefined) {
+        if (
+            typeof script.max_chunk_chars !== 'number' ||
+            !Number.isInteger(script.max_chunk_chars) ||
+            script.max_chunk_chars < VOICEBOX_CHUNK_CHARS_MIN ||
+            script.max_chunk_chars > VOICEBOX_CHUNK_CHARS_MAX
+        ) {
+            throw new Error(
+                `max_chunk_chars must be between ${VOICEBOX_CHUNK_CHARS_MIN} and ${VOICEBOX_CHUNK_CHARS_MAX}`,
+            );
+        }
+    }
+
+    if (script.crossfade_ms !== undefined) {
+        if (
+            typeof script.crossfade_ms !== 'number' ||
+            !Number.isInteger(script.crossfade_ms) ||
+            script.crossfade_ms < VOICEBOX_CROSSFADE_MS_MIN ||
+            script.crossfade_ms > VOICEBOX_CROSSFADE_MS_MAX
+        ) {
+            throw new Error(
+                `crossfade_ms must be between ${VOICEBOX_CROSSFADE_MS_MIN} and ${VOICEBOX_CROSSFADE_MS_MAX}`,
+            );
+        }
+    }
+
+    assertEngine(script.default_engine, 'VoiceScript default_engine');
+    assertLanguage(script.language, 'VoiceScript');
+
+    if (script.speakers) {
+        for (const [name, speaker] of Object.entries(script.speakers)) {
+            if (!speaker || typeof speaker !== 'object') {
+                throw new Error(`Speaker "${name}" definition must be an object`);
+            }
+            if (!speaker.profile || typeof speaker.profile !== 'string') {
+                throw new Error(`Speaker "${name}" must have a profile specified`);
+            }
+            if (
+                speaker.instruct &&
+                typeof speaker.instruct === 'string' &&
+                speaker.instruct.length > VOICEBOX_INSTRUCT_MAX
+            ) {
+                throw new Error(`Speaker "${name}" instruct exceeds 500 characters (${speaker.instruct.length} chars)`);
+            }
+            assertEngine(speaker.engine, `Speaker "${name}"`);
+            assertLanguage(speaker.language, `Speaker "${name}"`);
+        }
+    }
+
+    for (let idx = 0; idx < script.segments.length; idx++) {
+        const segment = script.segments[idx];
+        if (!segment || typeof segment !== 'object') {
+            throw new Error(`Segment at index ${idx} must be an object`);
+        }
+
+        if (typeof segment.text !== 'string' || segment.text.length === 0) {
+            throw new Error(`Segment at index ${idx} text must not be empty`);
+        }
+
+        if (segment.text.length > VOICEBOX_TEXT_MAX) {
+            throw new Error(
+                `Segment text exceeds the 50,000-character Voicebox /generate cap (${segment.text.length} chars)`,
+            );
+        }
+
+        if (
+            segment.instruct &&
+            typeof segment.instruct === 'string' &&
+            segment.instruct.length > VOICEBOX_INSTRUCT_MAX
+        ) {
+            throw new Error(`Segment instruct exceeds 500 characters (${segment.instruct.length} chars)`);
+        }
+
+        if (segment.speaker) {
+            if (!script.speakers || !(segment.speaker in script.speakers)) {
+                throw new Error(`Unknown speaker: "${segment.speaker}"`);
+            }
+        }
+
+        if (segment.max_chunk_chars !== undefined) {
+            if (
+                typeof segment.max_chunk_chars !== 'number' ||
+                !Number.isInteger(segment.max_chunk_chars) ||
+                segment.max_chunk_chars < VOICEBOX_CHUNK_CHARS_MIN ||
+                segment.max_chunk_chars > VOICEBOX_CHUNK_CHARS_MAX
+            ) {
+                throw new Error(
+                    `max_chunk_chars must be between ${VOICEBOX_CHUNK_CHARS_MIN} and ${VOICEBOX_CHUNK_CHARS_MAX}`,
+                );
+            }
+        }
+
+        if (segment.crossfade_ms !== undefined) {
+            if (
+                typeof segment.crossfade_ms !== 'number' ||
+                !Number.isInteger(segment.crossfade_ms) ||
+                segment.crossfade_ms < VOICEBOX_CROSSFADE_MS_MIN ||
+                segment.crossfade_ms > VOICEBOX_CROSSFADE_MS_MAX
+            ) {
+                throw new Error(
+                    `crossfade_ms must be between ${VOICEBOX_CROSSFADE_MS_MIN} and ${VOICEBOX_CROSSFADE_MS_MAX}`,
+                );
+            }
+        }
+
+        if (segment.gap_ms !== undefined) {
+            if (typeof segment.gap_ms !== 'number' || segment.gap_ms < 0) {
+                throw new Error('gap_ms must be non-negative');
+            }
+        }
+
+        assertEngine(segment.engine, `Segment at index ${idx}`);
+        assertLanguage(segment.language, `Segment at index ${idx}`);
+    }
+}

package/plugins/generations/voice-gen/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../../tooling/typescript/base.json",
+    "compilerOptions": {
+        "rootDir": "./src",
+        "outDir": "./dist"
+    },
+    "include": ["src/**/*"]
+}

package/plugins/ingestions/karakeep-local/package.json

@@ -0,0 +1,17 @@
+{
+    "name": "@gobing-ai/karakeep-local",
+    "type": "module",
+    "private": true,
+    "scripts": {
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "@gobing-ai/kk-core": "workspace:*",
+        "@gobing-ai/ts-infra": "catalog:",
+        "@gobing-ai/ts-runtime": "catalog:",
+        "@gobing-ai/ts-utils": "catalog:"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    }
+}