@gobing-ai/knowledge-kit 0.0.34 → 0.0.36

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

@@ -15,6 +15,6 @@
         "zod": "4.4.3"
     },
     "devDependencies": {
-        "@types/bun": "1.3.14"
+        "@types/bun": "1.4.3"
     }
 }

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

@@ -212,7 +212,13 @@ export async function processGeneratorIO(
             let loudnessDip = false;
             let lastError: unknown;
             let attemptBody = generateBody;
-            for (let verifyAttempt = 0; verifyAttempt <= 2 && wavBytes === undefined; verifyAttempt++) {
+            // Verify-retry budget. Hosted TTS is billed per request against a daily quota
+            // (Gemini Tier 1: 100/day), and each retry is a full re-synthesis — a 41-segment
+            // episode with the default 2 retries asks for up to 123 requests and dies partway
+            // through the render with no audio (daily-generate failures of 2026-10-06/07/09/10).
+            // Lower it for a quota-bound driver; 0 keeps the dip/fidelity result for QC instead.
+            const maxVerifyAttempts = Number.parseInt(process.env.VOICEBOX_MAX_VERIFY_ATTEMPTS ?? '2', 10) || 0;
+            for (let verifyAttempt = 0; verifyAttempt <= maxVerifyAttempts && wavBytes === undefined; verifyAttempt++) {
                 if (verifyAttempt > 0) {
                     verifyRetries = verifyAttempt;
                     const chunkChars = Math.max(VOICEBOX_CHUNK_CHARS_MIN, Math.floor(attemptBody.max_chunk_chars / 2));
@@ -262,7 +268,7 @@ export async function processGeneratorIO(
                     try {
                         const trans = await client.transcribe(attemptBytes, language);
                         const fidelity = transcriptionFidelity(segment.text, trans.text);
-                        if (fidelity < TRANSCRIPTION_FIDELITY_FLOOR && verifyAttempt < 2) {
+                        if (fidelity < TRANSCRIPTION_FIDELITY_FLOOR && verifyAttempt < maxVerifyAttempts) {
                             echoError(
                                 `voice-gen: transcription fidelity ${fidelity.toFixed(2)} below ${TRANSCRIPTION_FIDELITY_FLOOR} (looped/garbage audio): "${trans.text.slice(0, 80)}..."`,
                             );
@@ -278,7 +284,7 @@ export async function processGeneratorIO(
                 // (dogfood 2026-09-08 A/B: same text regenerated clean, so retry usually clears).
                 const dip = detectLoudnessDip(attemptBytes);
                 loudnessDip = dip.dip;
-                if (dip.dip && verifyAttempt < 2) {
+                if (dip.dip && verifyAttempt < maxVerifyAttempts) {
                     echoError(`voice-gen: loudness dip detected at ${dip.dipAtSec ?? '?'}s — regenerating segment`);
                     continue;
                 }

package/plugins/generations/voxcpm-tts/README.md

@@ -0,0 +1,72 @@
+# voxcpm-tts
+
+Standalone VoxCPM voice generator plugin for [knowledge-kit](../../../README.md). A TypeScript
+generator that reuses **voice-gen's** pipeline (VoiceScript parsing, gaps, speed, WAV
+concatenation, QC, optional MP3) behind the existing `VoiceboxClient` contract, backed by a
+private **uv-managed Python worker** that runs `voxcpm==2.0.3` (ADR-036). The default daily
+drivers are unchanged: opt in with `vdriver: voxcpm` (wired by task 0257).
+
+`vendors/VoxCPM` is reference-only. No import, subprocess, dependency, cache, profile or model
+path in this plugin may resolve into `vendors/` — every configured path is canonicalized and
+refused, including symlinks and the Hugging Face cache tiers.
+
+## Requirements
+
+- `uv` on `PATH` (the worker is spawned as `uv run --project <plugin-root> --locked --no-dev`).
+- Python 3.12 (the frozen interpreter; `uv` provisions it from the lock).
+- `ffmpeg`/`ffprobe` only when `VOICE_GEN_MP3` requests an MP3 sibling.
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `plugin.json` | `kk` manifest (`kind: generator`, entry `./src/index.ts` → bundled `./dist/index.js`) |
+| `src/index.ts` | `main(--in/--out)` entry; injects the adapter into `processGeneratorIO` and closes it in `finally` |
+| `src/voxcpm-client.ts` | registry/control/path validation + the bounded NDJSON worker adapter |
+| `python/worker.py` | private NDJSON worker: health/render, one model load per invocation |
+| `pyproject.toml` / `uv.lock` | independent uv project pinning `voxcpm==2.0.3` on Python 3.12 |
+| `profiles.json` | frozen profile registry (`profiles` array; `robin-news` instruct profile) |
+
+## Setup
+
+```bash
+uv lock --project plugins/generations/voxcpm-tts        # regenerate after editing pyproject.toml
+uv run --project plugins/generations/voxcpm-tts --locked --no-dev python plugins/generations/voxcpm-tts/python/worker.py
+```
+
+Step 0 (before live use) is the installed-import/API probe: confirm the locked `voxcpm==2.0.3`
+imports and exposes the expected signature. Source inspection does not prove hardware viability;
+that evidence belongs to task 0258.
+
+## Configuration (environment)
+
+| Var | Default | Notes |
+| --- | --- | --- |
+| `VOXCPM_MODEL` | `openbmb/VoxCPM2` | Hub id or a local snapshot directory. Hub models use the normal external cache; local paths pass canonical vendor exclusion |
+| `VOXCPM_DEVICE` | `auto` | `auto`/`cpu`/`cuda`/`mps`; an unavailable **requested** device fails |
+| `VOXCPM_PROFILES_PATH` | `<plugin-root>/profiles.json` | Profile registry |
+| `VOICEBOX_TIMEOUT_MS` | `600000` | Worker startup bound (shared with voice-gen) |
+| `VOICE_GEN_MAX_RUN_MS` | unset | Positive value bounds the whole invocation (startup + every render) |
+| `VOICE_GEN_MP3` | off | Request an MP3 sibling via ffmpeg |
+| `VOICE_GEN_FAIL_ON_QC` | off | Fail generation when the QC audit fails |
+
+## Profiles
+
+```json
+{ "profiles": [ { "id": "robin-news", "name": "robin-news", "mode": "instruct", "instruct": "清晰、自然、沉稳的中文新闻播报，语速适中。" } ] }
+```
+
+- `instruct`: needs a nonempty `instruct`; a per-request `instruct` overrides it.
+- `reference`: needs `reference_wav_path`.
+- `continuation`: needs `prompt_wav_path` + `prompt_text` together.
+- Relative assets resolve against the registry directory; serialized OmniVoice prompts, duplicate
+  ids/names, mixed mode fields and vendor paths are refused.
+
+## Control policy
+
+`normalize` maps directly; an explicit `seed` calls `torch.manual_seed` before synthesis (the
+2.0.3 API has no `seed`/`instruct` keyword); `language` is automatic multilingual inference with
+an advisory diagnostic; `max_chunk_chars`/`crossfade_ms` are advisory (one warning per invocation)
+— the shared VoiceScript segmentation remains the request boundary. A per-request `engine`,
+`personality=true` or an active `effects_chain` is rejected. Speed stays in shared postprocessing.
+Transcription is omitted, so ASR-dependent QC is reported unavailable (not passing evidence).