@fonoster/community 0.0.0-stage → 0.27.0

package/dist/adapters.d.ts

@@ -0,0 +1,29 @@
+import { Think, ThinkProvider } from "./llm";
+import { SttAdapter, TtsAdapter } from "./speech";
+/** How a speech adapter is reached: key, endpoint override, provider model, timeout. */
+export type SpeechAdapterOptions = {
+    apiKey?: string;
+    url?: string;
+    model?: string;
+    timeoutMs?: number;
+};
+export type LlmAdapterFactory = {
+    /** The vendor's endpoint when the operator configures none. */
+    defaultEndpoint?: string;
+    create(provider: ThinkProvider, model: string, settings: {
+        temperature: number;
+        maxTokens: number;
+        jsonMode?: boolean;
+    }): Think;
+};
+export type AdapterFactories = {
+    /** Works without a credential (fake, local models). */
+    keyless?: boolean;
+    /** Undefined when the options are not enough to reach the vendor. */
+    tts?(options: SpeechAdapterOptions): TtsAdapter | undefined;
+    stt?(options: SpeechAdapterOptions): SttAdapter | undefined;
+    llm?: LlmAdapterFactory;
+};
+export declare const ADAPTERS: Readonly<Record<string, AdapterFactories>>;
+/** The factories for a catalog adapter id, or undefined when this version has none. */
+export declare function adapterFor(id: string): AdapterFactories | undefined;

package/dist/adapters.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADAPTERS = void 0;
+exports.adapterFor = adapterFor;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const deepgram_1 = require("./deepgram");
+const elevenlabs_1 = require("./elevenlabs");
+const fake_1 = require("./fake");
+const openai_1 = require("./openai");
+function openAiCompatible(adapter) {
+    return {
+        defaultEndpoint: openai_1.OPENAI_COMPATIBLE[adapter],
+        create: (provider, model, settings) => new openai_1.OpenAiCompatibleThink(provider, model, settings)
+    };
+}
+exports.ADAPTERS = {
+    deepgram: {
+        tts: (o) => {
+            var _a;
+            return new deepgram_1.DeepgramTtsAdapter({
+                apiKey: (_a = o.apiKey) !== null && _a !== void 0 ? _a : "",
+                baseUrl: o.url,
+                timeoutMs: o.timeoutMs
+            });
+        },
+        stt: (o) => {
+            var _a;
+            return new deepgram_1.DeepgramSttAdapter({
+                apiKey: (_a = o.apiKey) !== null && _a !== void 0 ? _a : "",
+                baseUrl: o.url,
+                sttModel: o.model
+            });
+        }
+    },
+    elevenlabs: {
+        tts: (o) => {
+            var _a;
+            return new elevenlabs_1.ElevenLabsTtsAdapter({
+                apiKey: (_a = o.apiKey) !== null && _a !== void 0 ? _a : "",
+                baseUrl: o.url,
+                model: o.model,
+                timeoutMs: o.timeoutMs
+            });
+        }
+    },
+    openai: { llm: openAiCompatible("openai") },
+    groq: { llm: openAiCompatible("groq") },
+    ollama: { keyless: true, llm: openAiCompatible("ollama") },
+    fake: {
+        keyless: true,
+        tts: (o) => {
+            var _a;
+            return o.url
+                ? new fake_1.FakeTtsAdapter({ url: o.url, timeoutMs: (_a = o.timeoutMs) !== null && _a !== void 0 ? _a : 3000 })
+                : undefined;
+        },
+        stt: (o) => (o.url ? new fake_1.FakeSttAdapter({ url: o.url }) : undefined),
+        llm: openAiCompatible("fake")
+    }
+};
+/** The factories for a catalog adapter id, or undefined when this version has none. */
+function adapterFor(id) {
+    return Object.prototype.hasOwnProperty.call(exports.ADAPTERS, id)
+        ? exports.ADAPTERS[id]
+        : undefined;
+}

package/dist/deepgram/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { EventEmitter } from "events";
+import { SttAdapter, SttStream, Synthesis, TtsAdapter } from "../speech";
+export type DeepgramOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    sttModel?: string;
+    timeoutMs?: number;
+};
+export declare class DeepgramTtsAdapter implements TtsAdapter {
+    private readonly options;
+    constructor(options: DeepgramOptions);
+    synthesize(request: {
+        text: string;
+        voice: string;
+        language: string;
+    }, signal: AbortSignal): Promise<Synthesis>;
+}
+/** Deepgram's keyterm prompting works on Nova-3 and Flux; older models take `keywords`. */
+export declare function hintParam(model: string): "keyterm" | "keywords";
+export declare class DeepgramSttStream extends EventEmitter implements SttStream {
+    private readonly options;
+    private language;
+    private hints;
+    private readonly model;
+    private socket;
+    private queue;
+    private keepalive?;
+    private closed;
+    private finishing;
+    private failures;
+    private retry?;
+    constructor(options: DeepgramOptions, language: string, hints?: string[], model?: string);
+    private connect;
+    private onMessage;
+    write(frame: Buffer): void;
+    /**
+     * Deepgram cannot change language or keyterms mid-stream, so the stream reconnects. The old
+     * socket is finalized and drained, so words spoken just before the change are not lost.
+     */
+    update(options: {
+        language?: string;
+        hints?: string[];
+    }): void;
+    /**
+     * Ends the audio and waits (up to timeoutMs) for Deepgram to send its last results and close
+     * the socket, then closes the stream. Deepgram works through audio at about real-time pace even
+     * when it arrives faster, so a fixed wait followed by close() can drop every final (PR5, VO-B1).
+     */
+    finish(timeoutMs?: number): Promise<void>;
+    close(): void;
+    private retire;
+}
+export declare class DeepgramSttAdapter implements SttAdapter {
+    private readonly options;
+    constructor(options: DeepgramOptions);
+    open(options: {
+        language: string;
+        hints?: string[];
+        model?: string;
+    }): DeepgramSttStream;
+}

package/dist/deepgram/index.js

@@ -0,0 +1,268 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeepgramSttAdapter = exports.DeepgramSttStream = exports.DeepgramTtsAdapter = void 0;
+exports.hintParam = hintParam;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const events_1 = require("events");
+const url_1 = require("url");
+const ws_1 = __importDefault(require("ws"));
+const http_1 = require("../http");
+const speech_1 = require("../speech");
+const API = "https://api.deepgram.com";
+class DeepgramTtsAdapter {
+    constructor(options) {
+        this.options = options;
+    }
+    synthesize(request, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            // The voice is a Deepgram Aura model name (catalog id "deepgram/aura-2-thalia-en").
+            const query = new url_1.URLSearchParams({
+                model: request.voice,
+                encoding: "linear16",
+                sample_rate: "16000",
+                container: "none"
+            });
+            const audio = yield (0, http_1.streamingPost)(`${(_a = this.options.baseUrl) !== null && _a !== void 0 ? _a : API}/v1/speak?${query}`, {
+                headers: {
+                    authorization: `Token ${this.options.apiKey}`,
+                    "content-type": "application/json"
+                },
+                body: JSON.stringify({ text: request.text })
+            }, signal, (_b = this.options.timeoutMs) !== null && _b !== void 0 ? _b : 3000, "Deepgram TTS");
+            return { audio };
+        });
+    }
+}
+exports.DeepgramTtsAdapter = DeepgramTtsAdapter;
+/** Deepgram's keyterm prompting works on Nova-3 and Flux; older models take `keywords`. */
+function hintParam(model) {
+    return /^(nova-3|flux)/.test(model) ? "keyterm" : "keywords";
+}
+/** Frames kept while (re)connecting: 5 s of 20 ms frames. */
+const MAX_QUEUED_FRAMES = 250;
+/** How long a replaced socket may keep delivering its last transcripts (VO-B1). */
+const DRAIN_MS = 2000;
+class DeepgramSttStream extends events_1.EventEmitter {
+    constructor(options, language, hints, model) {
+        var _a;
+        if (hints === void 0) { hints = []; }
+        if (model === void 0) { model = (_a = options.sttModel) !== null && _a !== void 0 ? _a : "nova-3"; }
+        super();
+        this.options = options;
+        this.language = language;
+        this.hints = hints;
+        this.model = model;
+        this.queue = [];
+        this.closed = false;
+        this.finishing = false;
+        this.failures = 0;
+        this.connect();
+    }
+    connect() {
+        var _a;
+        const query = new url_1.URLSearchParams({
+            model: this.model,
+            encoding: "linear16",
+            sample_rate: "16000",
+            channels: "1",
+            interim_results: "true",
+            smart_format: "true",
+            language: this.language
+        });
+        const param = hintParam(this.model);
+        for (const h of this.hints)
+            query.append(param, h);
+        const base = ((_a = this.options.baseUrl) !== null && _a !== void 0 ? _a : API).replace(/^http/, "ws");
+        const socket = new ws_1.default(`${base}/v1/listen?${query}`, {
+            headers: { authorization: `Token ${this.options.apiKey}` }
+        });
+        this.socket = socket;
+        let rejected = false;
+        socket.on("open", () => {
+            for (const f of this.queue)
+                socket.send(f);
+            this.queue = [];
+            clearInterval(this.keepalive);
+            this.keepalive = setInterval(() => socket.readyState === ws_1.default.OPEN &&
+                socket.send(JSON.stringify({ type: "KeepAlive" })), 5000);
+        });
+        socket.on("message", (raw) => this.onMessage(raw.toString()));
+        // A rejected handshake (bad key, unknown model or language) is not retried.
+        socket.on("unexpected-response", (req, res) => {
+            rejected = true;
+            req.destroy();
+            if (this.closed || socket !== this.socket)
+                return;
+            this.emit("error", new speech_1.SpeechError(res.statusCode === 400 ? "bad_message" : "provider_unavailable", `Deepgram STT answered HTTP ${res.statusCode}`));
+        });
+        socket.on("error", () => undefined);
+        // Deepgram may close a live stream (NET-0001 after 10 s without audio, 1011 on its side). The
+        // old adapter went quietly deaf then; now it reconnects, keeping frames meanwhile (VO-B1).
+        socket.on("close", (code, reason) => {
+            if (socket !== this.socket || this.closed || this.finishing || rejected)
+                return;
+            clearInterval(this.keepalive);
+            if (code === 1008) {
+                this.emit("error", new speech_1.SpeechError("bad_message", `Deepgram STT rejected the stream: ${reason.toString() || code}`));
+                return;
+            }
+            if (++this.failures > 3) {
+                this.emit("error", new speech_1.SpeechError("provider_unavailable", `Deepgram STT closed the stream (${code} ${reason.toString()})`.trim()));
+                return;
+            }
+            this.retry = setTimeout(() => !this.closed && this.connect(), 250 * this.failures);
+        });
+    }
+    onMessage(text) {
+        var _a, _b, _c;
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch (_d) {
+            return;
+        }
+        if (this.closed || msg.type !== "Results")
+            return;
+        this.failures = 0;
+        const alt = (_b = (_a = msg.channel) === null || _a === void 0 ? void 0 : _a.alternatives) === null || _b === void 0 ? void 0 : _b[0];
+        if (!(alt === null || alt === void 0 ? void 0 : alt.transcript))
+            return;
+        const t = {
+            text: alt.transcript,
+            final: msg.is_final === true,
+            language: this.language,
+            confidence: (_c = alt.confidence) !== null && _c !== void 0 ? _c : 0
+        };
+        // Word timings (catalog feature `word-timings`), in ms from the start of this vendor stream.
+        const ms = (sec) => Math.round(Number(sec) * 1000);
+        if (typeof msg.start === "number" && typeof msg.duration === "number") {
+            t.startMs = ms(msg.start);
+            t.endMs = ms(msg.start + msg.duration);
+        }
+        if (Array.isArray(alt.words) && alt.words.length)
+            t.words = alt.words.map((w) => {
+                var _a;
+                return ({
+                    word: (_a = w.punctuated_word) !== null && _a !== void 0 ? _a : w.word,
+                    startMs: ms(w.start),
+                    endMs: ms(w.end)
+                });
+            });
+        this.emit("transcript", t);
+    }
+    write(frame) {
+        if (this.closed)
+            return;
+        if (this.socket.readyState === ws_1.default.OPEN)
+            this.socket.send(frame);
+        else {
+            this.queue.push(frame);
+            if (this.queue.length > MAX_QUEUED_FRAMES)
+                this.queue.shift();
+        }
+    }
+    /**
+     * Deepgram cannot change language or keyterms mid-stream, so the stream reconnects. The old
+     * socket is finalized and drained, so words spoken just before the change are not lost.
+     */
+    update(options) {
+        var _a, _b;
+        if (this.closed)
+            return;
+        this.language = (_a = options.language) !== null && _a !== void 0 ? _a : this.language;
+        this.hints = (_b = options.hints) !== null && _b !== void 0 ? _b : this.hints;
+        clearTimeout(this.retry);
+        this.retire(this.socket, DRAIN_MS);
+        this.connect();
+    }
+    /**
+     * Ends the audio and waits (up to timeoutMs) for Deepgram to send its last results and close
+     * the socket, then closes the stream. Deepgram works through audio at about real-time pace even
+     * when it arrives faster, so a fixed wait followed by close() can drop every final (PR5, VO-B1).
+     */
+    finish() {
+        return __awaiter(this, arguments, void 0, function* (timeoutMs = 10000) {
+            if (this.closed)
+                return;
+            this.finishing = true;
+            clearTimeout(this.retry);
+            clearInterval(this.keepalive);
+            const s = this.socket;
+            if (s.readyState === ws_1.default.OPEN) {
+                const done = new Promise((resolve) => {
+                    const timer = setTimeout(resolve, timeoutMs);
+                    s.once("close", () => {
+                        clearTimeout(timer);
+                        resolve();
+                    });
+                });
+                s.send(JSON.stringify({ type: "CloseStream" }));
+                yield done;
+            }
+            this.close();
+        });
+    }
+    close() {
+        this.closed = true;
+        clearTimeout(this.retry);
+        this.retire(this.socket, 0);
+        this.queue = [];
+        this.removeAllListeners();
+    }
+    retire(s, drainMs) {
+        clearInterval(this.keepalive);
+        if (s.readyState !== ws_1.default.OPEN) {
+            s.terminate();
+            return;
+        }
+        s.send(JSON.stringify({ type: "Finalize" }));
+        s.send(JSON.stringify({ type: "CloseStream" }));
+        if (!drainMs)
+            return s.close();
+        // Deepgram closes the socket itself once it has sent the last results.
+        const timer = setTimeout(() => s.terminate(), drainMs);
+        s.once("close", () => clearTimeout(timer));
+    }
+}
+exports.DeepgramSttStream = DeepgramSttStream;
+class DeepgramSttAdapter {
+    constructor(options) {
+        this.options = options;
+    }
+    open(options) {
+        var _a;
+        return new DeepgramSttStream(this.options, options.language, options.hints, (_a = options.model) !== null && _a !== void 0 ? _a : this.options.sttModel);
+    }
+}
+exports.DeepgramSttAdapter = DeepgramSttAdapter;

package/dist/elevenlabs/index.d.ts

@@ -0,0 +1,16 @@
+import { Synthesis, TtsAdapter } from "../speech";
+export type ElevenLabsOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    model?: string;
+    timeoutMs?: number;
+};
+export declare class ElevenLabsTtsAdapter implements TtsAdapter {
+    private readonly options;
+    constructor(options: ElevenLabsOptions);
+    synthesize(request: {
+        text: string;
+        voice: string;
+        language: string;
+    }, signal: AbortSignal): Promise<Synthesis>;
+}

package/dist/elevenlabs/index.js

@@ -0,0 +1,54 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElevenLabsTtsAdapter = void 0;
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+const http_1 = require("../http");
+class ElevenLabsTtsAdapter {
+    constructor(options) {
+        this.options = options;
+    }
+    synthesize(request, signal) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            // The voice is an ElevenLabs voice id (catalog id "elevenlabs/<voice id>").
+            const audio = yield (0, http_1.streamingPost)(`${(_a = this.options.baseUrl) !== null && _a !== void 0 ? _a : "https://api.elevenlabs.io"}/v1/text-to-speech/${encodeURIComponent(request.voice)}/stream?output_format=pcm_16000`, {
+                headers: {
+                    "xi-api-key": this.options.apiKey,
+                    "content-type": "application/json"
+                },
+                body: JSON.stringify({
+                    text: request.text,
+                    model_id: (_b = this.options.model) !== null && _b !== void 0 ? _b : "eleven_flash_v2_5"
+                })
+            }, signal, (_c = this.options.timeoutMs) !== null && _c !== void 0 ? _c : 3000, "ElevenLabs");
+            return { audio };
+        });
+    }
+}
+exports.ElevenLabsTtsAdapter = ElevenLabsTtsAdapter;

package/dist/fake/index.d.ts

@@ -0,0 +1,24 @@
+import { SttAdapter, SttStream, Synthesis, TtsAdapter } from "../speech";
+export declare class FakeTtsAdapter implements TtsAdapter {
+    private readonly options;
+    constructor(options: {
+        url: string;
+        timeoutMs: number;
+    });
+    synthesize(request: {
+        text: string;
+        voice: string;
+        language: string;
+    }, signal: AbortSignal): Promise<Synthesis>;
+}
+export declare class FakeSttAdapter implements SttAdapter {
+    private readonly options;
+    constructor(options: {
+        url: string;
+    });
+    open(options: {
+        language: string;
+        hints?: string[];
+        model?: string;
+    }): SttStream;
+}